1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3  *  V4L2 sub-device support header.
12 #include <linux/v4l2-subdev.h>
13 #include <media/media-entity.h>
14 #include <media/v4l2-async.h>
15 #include <media/v4l2-common.h>
16 #include <media/v4l2-dev.h>
17 #include <media/v4l2-fh.h>
18 #include <media/v4l2-mediabus.h>
43  * struct v4l2_decode_vbi_line - used to decode_vbi_line
49  * @line: Line number of the sliced VBI data (1-23)
60  * Sub-devices are devices that are connected somehow to the main bridge
68  * generic manner. Most operations that these sub-devices support fall in
97  * The ioctl ops is meant for generic ioctl-like commands. Depending on
98  * the use-case it might be better to use subdev-specific ops (currently
99  * not yet implemented) since ops provide proper type-checking.
103  * enum v4l2_subdev_io_pin_bits - Subdevice external IO pin configuration
110  *				  &struct v4l2_subdev_io_pin_config->value.
123  * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
129  * @value: Initial value for pin - e.g. GPIO output value
141  * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
159  *	drivers without discussing this first on the linux-media mailinglist.
165  * @command: called by in-kernel drivers in order to call functions internal
192 	int (*log_status)(struct v4l2_subdev *sd);
193 	int (*s_io_pin_config)(struct v4l2_subdev *sd, size_t n,
195 	int (*init)(struct v4l2_subdev *sd, u32 val);
196 	int (*load_fw)(struct v4l2_subdev *sd);
197 	int (*reset)(struct v4l2_subdev *sd, u32 val);
198 	int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
199 	long (*command)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
200 	long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
202 	long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd,
206 	int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
207 	int (*s_register)(struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg);
209 	int (*s_power)(struct v4l2_subdev *sd, int on);
210 	int (*interrupt_service_routine)(struct v4l2_subdev *sd,
212 	int (*subscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
214 	int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
219  * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
233  *		 freq->type must be filled in. Normally done by video_ioctl2()
240  * @s_tuner: callback for VIDIOC_S_TUNER() ioctl handler code. @vt->type must be
269 	int (*standby)(struct v4l2_subdev *sd);
270 	int (*s_radio)(struct v4l2_subdev *sd);
271 	int (*s_frequency)(struct v4l2_subdev *sd, const struct v4l2_frequency *freq);
272 	int (*g_frequency)(struct v4l2_subdev *sd, struct v4l2_frequency *freq);
273 	int (*enum_freq_bands)(struct v4l2_subdev *sd, struct v4l2_frequency_band *band);
274 	int (*g_tuner)(struct v4l2_subdev *sd, struct v4l2_tuner *vt);
275 	int (*s_tuner)(struct v4l2_subdev *sd, const struct v4l2_tuner *vt);
276 	int (*g_modulator)(struct v4l2_subdev *sd, struct v4l2_modulator *vm);
277 	int (*s_modulator)(struct v4l2_subdev *sd, const struct v4l2_modulator *vm);
278 	int (*s_type_addr)(struct v4l2_subdev *sd, struct tuner_setup *type);
279 	int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
283  * struct v4l2_subdev_audio_ops - Callbacks used for audio-related settings
289  *	-EINVAL is returned.
294  *	If the frequency is not supported, then %-EINVAL is returned.
298  *	Never attempt to use user-level input IDs (e.g. Composite, S-Video,
302  *	The calling driver is responsible for mapping a user-level input to
309 	int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
310 	int (*s_i2s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
311 	int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
312 	int (*s_stream)(struct v4l2_subdev *sd, int enable);
316  * enum v4l2_mbus_frame_desc_entry - media bus frame description flags
319  *	Indicates that &struct v4l2_mbus_frame_desc_entry->length field
331  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
348  * struct v4l2_mbus_frame_desc - media bus data frame description
358  * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
367  *	to 0. If the frequency is not supported, then -EINVAL is returned.
382  *	CAPTURE device. This is ignored by video output devices.
385  *	OUTPUT device. This is ignored by video capture devices.
414 	int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
415 	int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags);
416 	int (*g_std)(struct v4l2_subdev *sd, v4l2_std_id *norm);
417 	int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm);
418 	int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std);
419 	int (*g_std_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
420 	int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std);
421 	int (*g_tvnorms)(struct v4l2_subdev *sd, v4l2_std_id *std);
422 	int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
423 	int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
424 	int (*s_stream)(struct v4l2_subdev *sd, int enable);
425 	int (*g_pixelaspect)(struct v4l2_subdev *sd, struct v4l2_fract *aspect);
426 	int (*g_frame_interval)(struct v4l2_subdev *sd,
428 	int (*s_frame_interval)(struct v4l2_subdev *sd,
430 	int (*s_dv_timings)(struct v4l2_subdev *sd,
432 	int (*g_dv_timings)(struct v4l2_subdev *sd,
434 	int (*query_dv_timings)(struct v4l2_subdev *sd,
436 	int (*s_rx_buffer)(struct v4l2_subdev *sd, void *buf,
441  * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
461  *	the readback register contains invalid or erroneous data %-EIO is
476 	int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
477 	int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
478 	int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
479 	int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
480 	int (*s_raw_fmt)(struct v4l2_subdev *sd, struct v4l2_vbi_format *fmt);
481 	int (*g_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
482 	int (*s_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
486  * struct v4l2_subdev_sensor_ops - v4l2-subdev sensor operations
487  * @g_skip_top_lines: number of lines at the top of the image to be skipped.
489  *		      several top lines of the output image, or which send their
496 	int (*g_skip_top_lines)(struct v4l2_subdev *sd, u32 *lines);
497 	int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
501  * enum v4l2_subdev_ir_mode- describes the type of IR supported
510  * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
559  * struct v4l2_subdev_ir_ops - operations for IR subdevices
562  *	The semantics are similar to a non-blocking read() call.
571  *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
578  *	The semantics are similar to a non-blocking write() call.
587  *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
595 	int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
598 	int (*rx_g_parameters)(struct v4l2_subdev *sd,
600 	int (*rx_s_parameters)(struct v4l2_subdev *sd,
604 	int (*tx_write)(struct v4l2_subdev *sd, u8 *buf, size_t count,
607 	int (*tx_g_parameters)(struct v4l2_subdev *sd,
609 	int (*tx_s_parameters)(struct v4l2_subdev *sd,
614  * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
631  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
668  * @get_mbus_config: get the media bus configuration of a remote sub-device.
670  *		     firmware interface at sub-device probe time, immediately
672  *		     driver. Remote sub-devices (usually video receivers) shall
675  *		     Callers should make sure they get the most up-to-date as
681  * @set_mbus_config: set the media bus configuration of a remote sub-device.
684  *		     configuration parameters between media sub-devices. The
693 	int (*init_cfg)(struct v4l2_subdev *sd,
695 	int (*enum_mbus_code)(struct v4l2_subdev *sd,
698 	int (*enum_frame_size)(struct v4l2_subdev *sd,
701 	int (*enum_frame_interval)(struct v4l2_subdev *sd,
704 	int (*get_fmt)(struct v4l2_subdev *sd,
707 	int (*set_fmt)(struct v4l2_subdev *sd,
710 	int (*get_selection)(struct v4l2_subdev *sd,
713 	int (*set_selection)(struct v4l2_subdev *sd,
716 	int (*get_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
717 	int (*set_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
718 	int (*dv_timings_cap)(struct v4l2_subdev *sd,
720 	int (*enum_dv_timings)(struct v4l2_subdev *sd,
723 	int (*link_validate)(struct v4l2_subdev *sd, struct media_link *link,
727 	int (*get_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
729 	int (*set_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
731 	int (*get_mbus_config)(struct v4l2_subdev *sd, unsigned int pad,
733 	int (*set_mbus_config)(struct v4l2_subdev *sd, unsigned int pad,
738  * struct v4l2_subdev_ops - Subdev operations
761  * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
776  *	filehandle to the v4l-subdevX device node was closed. If no device
777  *	node was created for this sub-device, then the @release callback
781  *	sub-device that sets the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
788 	int (*registered)(struct v4l2_subdev *sd);
789 	void (*unregistered)(struct v4l2_subdev *sd);
790 	int (*open)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
791 	int (*close)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
792 	void (*release)(struct v4l2_subdev *sd);
813  * struct v4l2_subdev_platform_data - regulators config struct
817  * @host_priv: Per-subdevice data, specific for a certain video host device
827  * struct v4l2_subdev - describes a V4L2 sub-device
830  * @list: List of sub-devices
832  * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
835  *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
836  *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
837  *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
839  *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
847  * @name: Name of the sub-device. Please notice that the name must be unique.
848  * @grp_id: can be used to group similar subdevs. Value is driver-specific
855  *	    either dev->of_node->fwnode or dev->fwnode (whichever is non-NULL).
856  * @async_list: Links this subdev to a global subdev_list or @notifier->done
860  * @subdev_notifier: A sub-device notifier implicitly registered for the sub-
865  * stand-alone or embedded in a larger struct.
898  * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from
913  * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from
922  * struct v4l2_subdev_fh - Used for storing subdev information per file handle
937  * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from
948  * v4l2_subdev_get_try_format - ancillary routine to call
949  *	&struct v4l2_subdev_pad_config->try_fmt
951  * @sd: pointer to &struct v4l2_subdev
956 v4l2_subdev_get_try_format(struct v4l2_subdev *sd,  in v4l2_subdev_get_try_format()  argument
960 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_try_format()
966  * v4l2_subdev_get_try_crop - ancillary routine to call
967  *	&struct v4l2_subdev_pad_config->try_crop
969  * @sd: pointer to &struct v4l2_subdev
974 v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,  in v4l2_subdev_get_try_crop()  argument
978 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_try_crop()
984  * v4l2_subdev_get_try_compose - ancillary routine to call
985  *	&struct v4l2_subdev_pad_config->try_compose
987  * @sd: pointer to &struct v4l2_subdev
992 v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,  in v4l2_subdev_get_try_compose()  argument
996 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_try_compose()
1006  * v4l2_set_subdevdata - Sets V4L2 dev private device data
1008  * @sd: pointer to &struct v4l2_subdev
1011 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)  in v4l2_set_subdevdata()  argument
1013 	sd->dev_priv = p;  in v4l2_set_subdevdata()
1017  * v4l2_get_subdevdata - Gets V4L2 dev private device data
1019  * @sd: pointer to &struct v4l2_subdev
1023 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)  in v4l2_get_subdevdata()  argument
1025 	return sd->dev_priv;  in v4l2_get_subdevdata()
1029  * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data
1031  * @sd: pointer to &struct v4l2_subdev
1034 static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)  in v4l2_set_subdev_hostdata()  argument
1036 	sd->host_priv = p;  in v4l2_set_subdev_hostdata()
1040  * v4l2_get_subdev_hostdata - Gets V4L2 dev private data
1042  * @sd: pointer to &struct v4l2_subdev
1046 static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)  in v4l2_get_subdev_hostdata()  argument
1048 	return sd->host_priv;  in v4l2_get_subdev_hostdata()
1054  * v4l2_subdev_get_fwnode_pad_1_to_1 - Get pad number from a subdev fwnode
1071  * v4l2_subdev_link_validate_default - validates a media link
1073  * @sd: pointer to &struct v4l2_subdev
1081 int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
1087  * v4l2_subdev_link_validate - validates a media link
1100  * v4l2_subdev_alloc_pad_config - Allocates memory for pad config
1102  * @sd: pointer to struct v4l2_subdev
1105 v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
1108  * v4l2_subdev_free_pad_config - Frees memory allocated by
1117  * v4l2_subdev_init - initializes the sub-device struct
1119  * @sd: pointer to the &struct v4l2_subdev to be initialized
1122 void v4l2_subdev_init(struct v4l2_subdev *sd,
1128  * v4l2_subdev_call - call an operation of a v4l2_subdev.
1130  * @sd: pointer to the &struct v4l2_subdev
1138  * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
1140 #define v4l2_subdev_call(sd, o, f, args...)				\  argument
1142 		struct v4l2_subdev *__sd = (sd);			\
1145 			__result = -ENODEV;				\
1146 		else if (!(__sd->ops->o && __sd->ops->o->f))		\
1147 			__result = -ENOIOCTLCMD;			\
1149 			 v4l2_subdev_call_wrappers.o->f)		\
1150 			__result = v4l2_subdev_call_wrappers.o->f(	\
1153 			__result = __sd->ops->o->f(__sd, ##args);	\
1158  * v4l2_subdev_has_op - Checks if a subdev defines a certain operation.
1160  * @sd: pointer to the &struct v4l2_subdev
1165 #define v4l2_subdev_has_op(sd, o, f) \  argument
1166 	((sd)->ops->o && (sd)->ops->o->f)
1169  * v4l2_subdev_notify_event() - Delivers event notification for subdevice
1170  * @sd: The subdev for which to deliver the event
1178 void v4l2_subdev_notify_event(struct v4l2_subdev *sd,