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)
50  * @type: VBI service type (V4L2_SLICED_*). 0 if no service found
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
72  * limited set (no more than approx. 8 categories).
81  * These ops are all used internally so it is no problem to change, remove
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.
160  *	There should be no reason normally to reset a device.
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);
318  * @vc: CSI-2 virtual channel
319  * @dt: CSI-2 data type ID
327  * enum v4l2_mbus_frame_desc_flags - media bus frame description flags
330  *	Indicates that &struct v4l2_mbus_frame_desc_entry->length field
342  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
349  * @bus:	Bus-specific frame descriptor parameters
350  * @bus.csi2:	CSI-2-specific bus configuration
368  * enum v4l2_mbus_frame_desc_type - media bus frame description type
376  *	CSI-2 media bus. Frame desc parameters must be set in
377  *	&struct v4l2_mbus_frame_desc_entry->csi2.
386  * struct v4l2_mbus_frame_desc - media bus data frame description
398  * enum v4l2_subdev_pre_streamon_flags - Flags for pre_streamon subdev core op
400  * @V4L2_SUBDEV_PRE_STREAMON_FL_MANUAL_LP: Set the transmitter to either LP-11
401  *	or LP-111 mode before call to s_stream().
408  * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
417  *	to 0. If the frequency is not supported, then -EINVAL is returned.
464  *	initialising the bus. Current usage is to set a CSI-2 transmitter to
465  *	LP-11 or LP-111 mode before streaming. See &enum
469  *	indicated by the flags argument. In particular, -EACCES indicates lack
477 	int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
478 	int (*s_crystal_freq)(struct v4l2_subdev *sd, u32 freq, u32 flags);
479 	int (*g_std)(struct v4l2_subdev *sd, v4l2_std_id *norm);
480 	int (*s_std)(struct v4l2_subdev *sd, v4l2_std_id norm);
481 	int (*s_std_output)(struct v4l2_subdev *sd, v4l2_std_id std);
482 	int (*g_std_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
483 	int (*querystd)(struct v4l2_subdev *sd, v4l2_std_id *std);
484 	int (*g_tvnorms)(struct v4l2_subdev *sd, v4l2_std_id *std);
485 	int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
486 	int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
487 	int (*s_stream)(struct v4l2_subdev *sd, int enable);
488 	int (*g_pixelaspect)(struct v4l2_subdev *sd, struct v4l2_fract *aspect);
489 	int (*g_frame_interval)(struct v4l2_subdev *sd,
491 	int (*s_frame_interval)(struct v4l2_subdev *sd,
493 	int (*s_dv_timings)(struct v4l2_subdev *sd,
495 	int (*g_dv_timings)(struct v4l2_subdev *sd,
497 	int (*query_dv_timings)(struct v4l2_subdev *sd,
499 	int (*s_rx_buffer)(struct v4l2_subdev *sd, void *buf,
501 	int (*pre_streamon)(struct v4l2_subdev *sd, u32 flags);
502 	int (*post_streamoff)(struct v4l2_subdev *sd);
506  * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
515  *	&struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the
521  *	VBI signal is disabled. If no valid VBI data was found, then the type
525  *	Not all video decoders support this. If no data is available because
526  *	the readback register contains invalid or erroneous data %-EIO is
541 	int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
542 	int (*s_vbi_data)(struct v4l2_subdev *sd, const struct v4l2_sliced_vbi_data *vbi_data);
543 	int (*g_vbi_data)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_data *vbi_data);
544 	int (*g_sliced_vbi_cap)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_cap *cap);
545 	int (*s_raw_fmt)(struct v4l2_subdev *sd, struct v4l2_vbi_format *fmt);
546 	int (*g_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
547 	int (*s_sliced_fmt)(struct v4l2_subdev *sd, struct v4l2_sliced_vbi_format *fmt);
551  * struct v4l2_subdev_sensor_ops - v4l2-subdev sensor operations
561 	int (*g_skip_top_lines)(struct v4l2_subdev *sd, u32 *lines);
562 	int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
566  * enum v4l2_subdev_ir_mode- describes the type of IR supported
575  * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
582  * @shutdown: if true: set hardware to low/no power, false: normal mode
624  * struct v4l2_subdev_ir_ops - operations for IR subdevices
627  *	The semantics are similar to a non-blocking read() call.
636  *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
643  *	The semantics are similar to a non-blocking write() call.
652  *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
660 	int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
663 	int (*rx_g_parameters)(struct v4l2_subdev *sd,
665 	int (*rx_s_parameters)(struct v4l2_subdev *sd,
669 	int (*tx_write)(struct v4l2_subdev *sd, u8 *buf, size_t count,
672 	int (*tx_g_parameters)(struct v4l2_subdev *sd,
674 	int (*tx_s_parameters)(struct v4l2_subdev *sd,
679  * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
699  * struct v4l2_subdev_state - Used for storing subdev state information.
717  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
754  * @get_mbus_config: get the media bus configuration of a remote sub-device.
756  *		     firmware interface at sub-device probe time, immediately
758  *		     driver. Remote sub-devices (usually video receivers) shall
761  *		     Callers should make sure they get the most up-to-date as
768 	int (*init_cfg)(struct v4l2_subdev *sd,
770 	int (*enum_mbus_code)(struct v4l2_subdev *sd,
773 	int (*enum_frame_size)(struct v4l2_subdev *sd,
776 	int (*enum_frame_interval)(struct v4l2_subdev *sd,
779 	int (*get_fmt)(struct v4l2_subdev *sd,
782 	int (*set_fmt)(struct v4l2_subdev *sd,
785 	int (*get_selection)(struct v4l2_subdev *sd,
788 	int (*set_selection)(struct v4l2_subdev *sd,
791 	int (*get_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
792 	int (*set_edid)(struct v4l2_subdev *sd, struct v4l2_edid *edid);
793 	int (*dv_timings_cap)(struct v4l2_subdev *sd,
795 	int (*enum_dv_timings)(struct v4l2_subdev *sd,
798 	int (*link_validate)(struct v4l2_subdev *sd, struct media_link *link,
802 	int (*get_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
804 	int (*set_frame_desc)(struct v4l2_subdev *sd, unsigned int pad,
806 	int (*get_mbus_config)(struct v4l2_subdev *sd, unsigned int pad,
811  * struct v4l2_subdev_ops - Subdev operations
834  * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
849  *	filehandle to the v4l-subdevX device node was closed. If no device
850  *	node was created for this sub-device, then the @release callback
854  *	sub-device that sets the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
861 	int (*registered)(struct v4l2_subdev *sd);
862 	void (*unregistered)(struct v4l2_subdev *sd);
863 	int (*open)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
864 	int (*close)(struct v4l2_subdev *sd, struct v4l2_subdev_fh *fh);
865 	void (*release)(struct v4l2_subdev *sd);
886  * struct v4l2_subdev_platform_data - regulators config struct
890  * @host_priv: Per-subdevice data, specific for a certain video host device
900  * struct v4l2_subdev - describes a V4L2 sub-device
903  * @list: List of sub-devices
905  * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
908  *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
909  *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
910  *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
912  *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
920  * @name: Name of the sub-device. Please notice that the name must be unique.
921  * @grp_id: can be used to group similar subdevs. Value is driver-specific
928  *	    either dev->of_node->fwnode or dev->fwnode (whichever is non-NULL).
929  * @async_list: Links this subdev to a global subdev_list or @notifier->done
933  * @subdev_notifier: A sub-device notifier implicitly registered for the sub-
944  * stand-alone or embedded in a larger struct.
991  * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from
1006  * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from
1015  * struct v4l2_subdev_fh - Used for storing subdev information per file handle
1030  * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from
1041  * v4l2_subdev_get_pad_format - ancillary routine to call
1042  *	&struct v4l2_subdev_pad_config->try_fmt
1044  * @sd: pointer to &struct v4l2_subdev
1046  * @pad: index of the pad in the &struct v4l2_subdev_state->pads array
1049 v4l2_subdev_get_pad_format(struct v4l2_subdev *sd,  in v4l2_subdev_get_pad_format()  argument
1055 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_pad_format()
1057 	return &state->pads[pad].try_fmt;  in v4l2_subdev_get_pad_format()
1061  * v4l2_subdev_get_pad_crop - ancillary routine to call
1062  *	&struct v4l2_subdev_pad_config->try_crop
1064  * @sd: pointer to &struct v4l2_subdev
1066  * @pad: index of the pad in the &struct v4l2_subdev_state->pads array.
1069 v4l2_subdev_get_pad_crop(struct v4l2_subdev *sd,  in v4l2_subdev_get_pad_crop()  argument
1075 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_pad_crop()
1077 	return &state->pads[pad].try_crop;  in v4l2_subdev_get_pad_crop()
1081  * v4l2_subdev_get_pad_compose - ancillary routine to call
1082  *	&struct v4l2_subdev_pad_config->try_compose
1084  * @sd: pointer to &struct v4l2_subdev
1086  * @pad: index of the pad in the &struct v4l2_subdev_state->pads array.
1089 v4l2_subdev_get_pad_compose(struct v4l2_subdev *sd,  in v4l2_subdev_get_pad_compose()  argument
1095 	if (WARN_ON(pad >= sd->entity.num_pads))  in v4l2_subdev_get_pad_compose()
1097 	return &state->pads[pad].try_compose;  in v4l2_subdev_get_pad_compose()
1104 #define v4l2_subdev_get_try_format(sd, state, pad) \  argument
1105 	v4l2_subdev_get_pad_format(sd, state, pad)
1107 #define v4l2_subdev_get_try_crop(sd, state, pad) \  argument
1108 	v4l2_subdev_get_pad_crop(sd, state, pad)
1110 #define v4l2_subdev_get_try_compose(sd, state, pad) \  argument
1111 	v4l2_subdev_get_pad_compose(sd, state, pad)
1118  * v4l2_set_subdevdata - Sets V4L2 dev private device data
1120  * @sd: pointer to &struct v4l2_subdev
1123 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)  in v4l2_set_subdevdata()  argument
1125 	sd->dev_priv = p;  in v4l2_set_subdevdata()
1129  * v4l2_get_subdevdata - Gets V4L2 dev private device data
1131  * @sd: pointer to &struct v4l2_subdev
1135 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)  in v4l2_get_subdevdata()  argument
1137 	return sd->dev_priv;  in v4l2_get_subdevdata()
1141  * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data
1143  * @sd: pointer to &struct v4l2_subdev
1146 static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)  in v4l2_set_subdev_hostdata()  argument
1148 	sd->host_priv = p;  in v4l2_set_subdev_hostdata()
1152  * v4l2_get_subdev_hostdata - Gets V4L2 dev private data
1154  * @sd: pointer to &struct v4l2_subdev
1158 static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)  in v4l2_get_subdev_hostdata()  argument
1160 	return sd->host_priv;  in v4l2_get_subdev_hostdata()
1166  * v4l2_subdev_get_fwnode_pad_1_to_1 - Get pad number from a subdev fwnode
1183  * v4l2_subdev_link_validate_default - validates a media link
1185  * @sd: pointer to &struct v4l2_subdev
1193 int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
1199  * v4l2_subdev_link_validate - validates a media link
1212  * __v4l2_subdev_state_alloc - allocate v4l2_subdev_state
1214  * @sd: pointer to &struct v4l2_subdev for which the state is being allocated.
1218  * Must call __v4l2_subdev_state_free() when state is no longer needed.
1222 struct v4l2_subdev_state *__v4l2_subdev_state_alloc(struct v4l2_subdev *sd,
1227  * __v4l2_subdev_state_free - free a v4l2_subdev_state
1236  * v4l2_subdev_init_finalize() - Finalizes the initialization of the subdevice
1237  * @sd: The subdev
1249 #define v4l2_subdev_init_finalize(sd)                                          \  argument
1253 			":" __stringify(__LINE__) ":sd->active_state->lock";   \
1254 		__v4l2_subdev_init_finalize(sd, name, &__key);                 \
1257 int __v4l2_subdev_init_finalize(struct v4l2_subdev *sd, const char *name,
1261  * v4l2_subdev_cleanup() - Releases the resources allocated by the subdevice
1262  * @sd: The subdevice
1267 void v4l2_subdev_cleanup(struct v4l2_subdev *sd);
1270  * v4l2_subdev_lock_state() - Locks the subdev state
1279 	mutex_lock(state->lock);  in v4l2_subdev_lock_state()
1283  * v4l2_subdev_unlock_state() - Unlocks the subdev state
1290 	mutex_unlock(state->lock);  in v4l2_subdev_unlock_state()
1294  * v4l2_subdev_get_unlocked_active_state() - Checks that the active subdev state
1296  * @sd: The subdevice
1306 v4l2_subdev_get_unlocked_active_state(struct v4l2_subdev *sd)  in v4l2_subdev_get_unlocked_active_state()  argument
1308 	if (sd->active_state)  in v4l2_subdev_get_unlocked_active_state()
1309 		lockdep_assert_not_held(sd->active_state->lock);  in v4l2_subdev_get_unlocked_active_state()
1310 	return sd->active_state;  in v4l2_subdev_get_unlocked_active_state()
1314  * v4l2_subdev_get_locked_active_state() - Checks that the active subdev state
1317  * @sd: The subdevice
1327 v4l2_subdev_get_locked_active_state(struct v4l2_subdev *sd)  in v4l2_subdev_get_locked_active_state()  argument
1329 	if (sd->active_state)  in v4l2_subdev_get_locked_active_state()
1330 		lockdep_assert_held(sd->active_state->lock);  in v4l2_subdev_get_locked_active_state()
1331 	return sd->active_state;  in v4l2_subdev_get_locked_active_state()
1335  * v4l2_subdev_lock_and_get_active_state() - Locks and returns the active subdev
1337  * @sd: The subdevice
1345 v4l2_subdev_lock_and_get_active_state(struct v4l2_subdev *sd)  in v4l2_subdev_lock_and_get_active_state()  argument
1347 	if (sd->active_state)  in v4l2_subdev_lock_and_get_active_state()
1348 		v4l2_subdev_lock_state(sd->active_state);  in v4l2_subdev_lock_and_get_active_state()
1349 	return sd->active_state;  in v4l2_subdev_lock_and_get_active_state()
1355  * v4l2_subdev_get_fmt() - Fill format based on state
1356  * @sd: subdevice
1360  * Fill @format->format field based on the information in the @format struct.
1368 int v4l2_subdev_get_fmt(struct v4l2_subdev *sd, struct v4l2_subdev_state *state,
1376  * v4l2_subdev_init - initializes the sub-device struct
1378  * @sd: pointer to the &struct v4l2_subdev to be initialized
1381 void v4l2_subdev_init(struct v4l2_subdev *sd,
1387  * v4l2_subdev_call - call an operation of a v4l2_subdev.
1389  * @sd: pointer to the &struct v4l2_subdev
1397  * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
1399 #define v4l2_subdev_call(sd, o, f, args...)				\  argument
1401 		struct v4l2_subdev *__sd = (sd);			\
1404 			__result = -ENODEV;				\
1405 		else if (!(__sd->ops->o && __sd->ops->o->f))		\
1406 			__result = -ENOIOCTLCMD;			\
1408 			 v4l2_subdev_call_wrappers.o->f)		\
1409 			__result = v4l2_subdev_call_wrappers.o->f(	\
1412 			__result = __sd->ops->o->f(__sd, ##args);	\
1417  * v4l2_subdev_call_state_active - call an operation of a v4l2_subdev which
1421  * @sd: pointer to the &struct v4l2_subdev
1433 #define v4l2_subdev_call_state_active(sd, o, f, args...)		\  argument
1437 		state = v4l2_subdev_get_unlocked_active_state(sd);	\
1440 		__result = v4l2_subdev_call(sd, o, f, state, ##args);	\
1447  * v4l2_subdev_call_state_try - call an operation of a v4l2_subdev which
1451  * @sd: pointer to the &struct v4l2_subdev
1463  * Note: only legacy non-MC drivers may need this macro.
1465 #define v4l2_subdev_call_state_try(sd, o, f, args...)                 \  argument
1470 			":" __stringify(__LINE__) ":state->lock";     \
1472 			__v4l2_subdev_state_alloc(sd, name, &__key);  \
1474 		__result = v4l2_subdev_call(sd, o, f, state, ##args); \
1481  * v4l2_subdev_has_op - Checks if a subdev defines a certain operation.
1483  * @sd: pointer to the &struct v4l2_subdev
1488 #define v4l2_subdev_has_op(sd, o, f) \  argument
1489 	((sd)->ops->o && (sd)->ops->o->f)
1492  * v4l2_subdev_notify_event() - Delivers event notification for subdevice
1493  * @sd: The subdev for which to deliver the event
1501 void v4l2_subdev_notify_event(struct v4l2_subdev *sd,