1 /* SPDX-License-Identifier: GPL-2.0-only */
26  * enum media_gobj_type - type of a graph object
29  * @MEDIA_GRAPH_PAD:		Identify a media pad
42 #define MEDIA_BITS_PER_ID		(32 - MEDIA_BITS_PER_TYPE)
43 #define MEDIA_ID_MASK			 GENMASK_ULL(MEDIA_BITS_PER_ID - 1, 0)
48  * struct media_gobj - Define a graph object.
51  * @id:		Non-zero object ID identifier. The ID should be unique
55  * @list:	List entry stored in one of the per-type mdev object lists
68  * struct media_entity_enum - An enumeration of media entities.
71  *		media_entity->internal_idx.
80  * struct media_graph - Media graph traversal state
101  * struct media_pipeline - Media pipeline related information
106  * @start_count:	Media pipeline start - stop count
116  * struct media_pipeline_pad - A pad part of a media pipeline
119  * @pipe:		The media_pipeline that the pad is part of
120  * @pad:		The media pad
122  * This structure associate a pad with a media pipeline. Instances of
130 	struct media_pad *pad;  member
134  * struct media_pipeline_pad_iter - Iterator for media_pipeline_for_each_pad
143  * struct media_pipeline_entity_iter - Iterator for media_pipeline_for_each_entity
154  * struct media_link - A link object part of a media graph.
162  *		a pad. In that case, it represents the source pad.
168  *		a pad. In that case, it represents the sink pad.
171  * @reverse:	Pointer to the link for the reverse direction of a pad to pad
195  * enum media_pad_signal_type - type of the signal inside a media pad
199  *	uniquely identified by the pad number.
201  *	The pad contains an analog signal. It can be Radio Frequency,
202  *	Intermediate Frequency, a baseband signal or sub-carriers.
203  *	Tuner inputs, IF-PLL demodulators, composite and s-video signals
211  *	sub-carrier or an audio bitstream. IF signals are provided by tuners
223  * struct media_pad - A media pad graph object.
226  * @entity:	Entity this pad belongs to
227  * @index:	Pad index in the entity pads array, numbered from 0 to n
228  * @num_links:	Number of links connected to this pad
229  * @sig_type:	Type of the signal inside a media pad
230  * @flags:	Pad flags, as defined in
231  *		:ref:`include/uapi/linux/media.h <media_header>`
233  * @pipe:	Pipeline this pad belongs to. Use media_entity_pipeline() to
252  * struct media_entity_operations - Media entity operations
253  * @get_fwnode_pad:	Return the pad number based on a fwnode endpoint or
255  *			to map a fwnode to a media pad number. Optional.
265  *			means that the other pad will become "locked" and
290  * enum media_entity_type - Media entity type
300  * entity structure is inherited by (through embedding) other subsystem-specific
317  * struct media_entity - A media entity graph object.
323  *		:ref:`include/uapi/linux/media.h <media_header>`
326  *		:ref:`include/uapi/linux/media.h <media_header>`
332  *		re-used if entities are unregistered or registered again.
381  * media_entity_for_each_pad - Iterate on all pads in an entity
383  * @iter: The iterator pad
388 	for (iter = (entity)->pads;				\
389 	     iter < &(entity)->pads[(entity)->num_pads];	\
393  * struct media_interface - A media interface graph object.
398  *			:ref:`include/uapi/linux/media.h <media_header>`
401  *			:ref:`include/uapi/linux/media.h <media_header>`
416  * struct media_intf_devnode - A media interface via a device node.
431  * media_entity_id() - return the media entity graph object id
437 	return entity->graph_obj.id;  in media_entity_id()
441  * media_type() - return the media object type
447 	return gobj->id >> MEDIA_BITS_PER_ID;  in media_type()
451  * media_id() - return the media object ID
457 	return gobj->id & MEDIA_ID_MASK;  in media_id()
461  * media_gobj_gen_id() - encapsulates type and ID on at the object ID
477  * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
486 	return entity && entity->obj_type == MEDIA_ENTITY_TYPE_VIDEO_DEVICE;  in is_media_entity_v4l2_video_device()
490  * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
499 	return entity && entity->obj_type == MEDIA_ENTITY_TYPE_V4L2_SUBDEV;  in is_media_entity_v4l2_subdev()
503  * media_entity_enum_init - Initialise an entity enumeration
514  * media_entity_enum_cleanup - Release resources of an entity enumeration
521  * media_entity_enum_zero - Clear the entire enum
527 	bitmap_zero(ent_enum->bmap, ent_enum->idx_max);  in media_entity_enum_zero()
531  * media_entity_enum_set - Mark a single entity in the enum
539 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_set()
542 	__set_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_set()
546  * media_entity_enum_clear - Unmark a single entity in the enum
554 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_clear()
557 	__clear_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_clear()
561  * media_entity_enum_test - Test whether the entity is marked
571 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_test()
574 	return test_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_test()
578  * media_entity_enum_test_and_set - Test whether the entity is marked,
590 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_test_and_set()
593 	return __test_and_set_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_test_and_set()
597  * media_entity_enum_empty - Test whether the entire enum is empty
605 	return bitmap_empty(ent_enum->bmap, ent_enum->idx_max);  in media_entity_enum_empty()
609  * media_entity_enum_intersects - Test whether two enums intersect
621 	WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max);  in media_entity_enum_intersects()
623 	return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap,  in media_entity_enum_intersects()
624 				 min(ent_enum1->idx_max, ent_enum2->idx_max));  in media_entity_enum_intersects()
628  * gobj_to_entity - returns the struct &media_entity pointer from the
637  * gobj_to_pad - returns the struct &media_pad pointer from the
646  * gobj_to_link - returns the struct &media_link pointer from the
655  * gobj_to_intf - returns the struct &media_interface pointer from the
664  * intf_to_devnode - returns the struct media_intf_devnode pointer from the
673  *  media_gobj_create - Initialize a graph object
681  * function calls are used. However, if the object (entity, link, pad,
690  *  media_gobj_destroy - Stop using a graph object on a media device
700  * media_entity_pads_init() - Initialize the entity pads
711  * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
716  * pads array in a driver-specific structure, avoiding dynamic allocation.
718  * Drivers must set the direction of every pad in the pads array before calling
725  * media_entity_cleanup() - free resources associated with an entity
734  * valid and is a no-op.
743  * media_get_pad_index() - retrieves a pad index from an entity
746  * @pad_type:	the type of the pad, one of MEDIA_PAD_FL_* pad types
747  * @sig_type:	type of signal of the pad to be search
749  * This helper function finds the first pad index inside an entity that
754  * On success, return the pad number. If the pad was not found or the media
755  * entity is a NULL pointer, return -EINVAL.
761  * media_create_pad_link() - creates a link between two entities.
763  * @source:	pointer to &media_entity of the source pad.
764  * @source_pad:	number of the source pad in the pads array
765  * @sink:	pointer to &media_entity of the sink pad.
766  * @sink_pad:	number of the sink pad in the pads array.
768  *		:ref:`include/uapi/linux/media.h <media_header>`
775  *   When two or more links target a sink pad, only one of them can be
793  * media_create_pad_links() - creates a link between two entities.
798  * @source: pointer to &media_entity of the source pad. If NULL, it will use
800  * @source_pad: number of the source pad in the pads array
802  * @sink: pointer to &media_entity of the sink pad. If NULL, it will use
804  * @sink_pad: number of the sink pad in the pads array.
827  * cross-bar (n:n) links.
848  * media_entity_remove_links() - remove all links associated with an entity
860  * __media_entity_setup_link - Configure a media link without locking
870  * The user is expected to hold link->source->parent->mutex. If not,
876  * media_entity_setup_link() - changes the link flags properties in runtime
897  * is non-immutable. The operation must either configure the hardware or store
901  * enabled link at a sink pad prevents another link at the same pad from
902  * being enabled, the link_setup operation must return %-EBUSY and can't
908  *    on media_create_pad_link(), for pad to pad links or the same as described
914  * media_entity_find_link - Find a link between two pads
915  * @source: Source pad
916  * @sink: Sink pad
925  * media_pad_remote_pad_first - Find the first pad at the remote end of a link
926  * @pad: Pad at the local end of the link
928  * Search for a remote pad connected to the given pad by iterating over all
929  * links originating or terminating at that pad until an enabled link is found.
931  * Return: returns a pointer to the pad at the remote end of the first found
934 struct media_pad *media_pad_remote_pad_first(const struct media_pad *pad);
937  * media_pad_remote_pad_unique - Find a remote pad connected to a pad
938  * @pad: The pad
940  * Search for and return a remote pad connected to @pad through an enabled
944  * that support a single active source at a time on a given pad.
946  * Return: A pointer to the remote pad, or one of the following error pointers
949  * * -ENOTUNIQ - Multiple links are enabled
950  * * -ENOLINK - No connected pad found
952 struct media_pad *media_pad_remote_pad_unique(const struct media_pad *pad);
955  * media_entity_remote_pad_unique - Find a remote pad connected to an entity
957  * @type: The type of pad to find (MEDIA_PAD_FL_SINK or MEDIA_PAD_FL_SOURCE)
959  * Search for and return a remote pad of @type connected to @entity through an
966  * Return: A pointer to the remote pad, or one of the following error pointers
969  * * -ENOTUNIQ - Multiple links are enabled
970  * * -ENOLINK - No connected pad found
977  * media_entity_remote_source_pad_unique - Find a remote source pad connected to
981  * Search for and return a remote source pad connected to @entity through an
988  * Return: A pointer to the remote pad, or one of the following error pointers
991  * * -ENOTUNIQ - Multiple links are enabled
992  * * -ENOLINK - No connected pad found
1001  * media_pad_is_streaming - Test if a pad is part of a streaming pipeline
1002  * @pad: The pad
1004  * Return: True if the pad is part of a pipeline started with the
1007 static inline bool media_pad_is_streaming(const struct media_pad *pad)  in media_pad_is_streaming()  argument
1009 	return pad->pipe;  in media_pad_is_streaming()
1013  * media_entity_is_streaming - Test if an entity is part of a streaming pipeline
1021 	struct media_pad *pad;  in media_entity_is_streaming()  local
1023 	media_entity_for_each_pad(entity, pad) {  in media_entity_is_streaming()
1024 		if (media_pad_is_streaming(pad))  in media_entity_is_streaming()
1032  * media_entity_pipeline - Get the media pipeline an entity is part of
1042  * multiple streams (either on different pads, or on the same pad using
1052  * media_pad_pipeline - Get the media pipeline a pad is part of
1053  * @pad: The pad
1055  * This function returns the media pipeline that a pad has been associated
1059  * Return: The media_pipeline the pad is part of, or NULL if the pad is
1062 struct media_pipeline *media_pad_pipeline(struct media_pad *pad);
1065  * media_entity_get_fwnode_pad - Get pad number from fwnode
1068  * @fwnode: Pointer to the fwnode_handle which should be used to find the pad
1069  * @direction_flags: Expected direction of the pad, as defined in
1070  *		     :ref:`include/uapi/linux/media.h <media_header>`
1073  * This function can be used to resolve the media pad number from
1078  * then this function searches the entity for the first pad that
1081  * Return: returns the pad number on success or a negative error code.
1088  * media_graph_walk_init - Allocate resources used by graph walk.
1104  * media_graph_walk_cleanup - Release resources used by graph walk.
1113  * media_graph_walk_start - Start walking the media graph at a
1133  * media_graph_walk_next - Get the next entity in the graph
1138  * Perform a depth-first traversal of the given media entities graph.
1149  * media_pipeline_start - Mark a pipeline as streaming
1150  * @pad: Starting pad
1153  * Mark all pads connected to a given pad through enabled links, either
1155  * to every pad in the pipeline and stored in the media_pad pipe field.
1162 __must_check int media_pipeline_start(struct media_pad *pad,
1165  * __media_pipeline_start - Mark a pipeline as streaming
1167  * @pad: Starting pad
1170  * ..note:: This is the non-locking version of media_pipeline_start()
1172 __must_check int __media_pipeline_start(struct media_pad *pad,
1176  * media_pipeline_stop - Mark a pipeline as not streaming
1177  * @pad: Starting pad
1179  * Mark all pads connected to a given pad through enabled links, either
1187 void media_pipeline_stop(struct media_pad *pad);
1190  * __media_pipeline_stop - Mark a pipeline as not streaming
1192  * @pad: Starting pad
1194  * .. note:: This is the non-locking version of media_pipeline_stop()
1196 void __media_pipeline_stop(struct media_pad *pad);
1201 			       struct media_pad *pad);
1204  * media_pipeline_for_each_pad - Iterate on all pads in a media pipeline
1207  * @pad: The iterator pad
1213 #define media_pipeline_for_each_pad(pipe, iter, pad)			\  argument
1214 	for (pad = __media_pipeline_pad_iter_next((pipe), iter, NULL);	\
1215 	     pad != NULL;						\
1216 	     pad = __media_pipeline_pad_iter_next((pipe), iter, pad))
1219  * media_pipeline_entity_iter_init - Initialize a pipeline entity iterator
1237  * media_pipeline_entity_iter_cleanup - Destroy a pipeline entity iterator
1251  * media_pipeline_for_each_entity - Iterate on all entities in a media pipeline
1269  * media_pipeline_alloc_start - Mark a pipeline as streaming
1270  * @pad: Starting pad
1274  * the pad is already part of a pipeline, or allocate a new pipeline.
1279 __must_check int media_pipeline_alloc_start(struct media_pad *pad);
1282  * media_devnode_create() - creates and initializes a device node interface
1286  *		:ref:`include/uapi/linux/media.h <media_header>`
1289  *		:ref:`include/uapi/linux/media.h <media_header>`
1306  * media_devnode_remove() - removes a device node interface
1316  * media_create_intf_link() - creates a link between an entity and an interface
1321  *		:ref:`include/uapi/linux/media.h <media_header>`
1349  * __media_remove_intf_link() - remove a single interface link
1358  * media_remove_intf_link() - remove a single interface link
1367  * __media_remove_intf_links() - remove all links associated with an interface
1376  * media_remove_intf_links() - remove all links associated with an interface
1390  * media_entity_call - Calls a struct media_entity_operations operation on
1402 	(((entity)->ops && (entity)->ops->operation) ?			\
1403 	 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
1406  * media_create_ancillary_link() - create an ancillary link between two
1425  * __media_entity_next_link() - Iterate through a &media_entity's links
1440  * for_each_media_entity_data_link() - Iterate through an entity's data links