1 /* SPDX-License-Identifier: GPL-2.0-only */
26  * enum media_gobj_type - type of a graph object
30  * @MEDIA_GRAPH_LINK:		Identify a media link
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
86  * @stack.link:		pointer to &struct list_head.
93 		struct list_head *link;  member
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
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.
158  *		owns the link.
160  *		graph_object of the link.
166  *		graph_object of the link.
171  * @reverse:	Pointer to the link for the reverse direction of a pad to pad
172  *		link.
173  * @flags:	Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
174  * @is_backlink: Indicate if the link is a backlink.
195  * enum media_pad_signal_type - type of the signal inside a media pad
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.
250  * struct media_entity_operations - Media entity operations
254  * @link_setup:		Notify the entity of link changes. The operation can
255  *			return an error, in which case link setup will be
257  * @link_validate:	Return whether a link is valid from the entity point of
282 	int (*link_validate)(struct media_link *link);
288  * enum media_entity_type - Media entity type
298  * entity structure is inherited by (through embedding) other subsystem-specific
315  * struct media_entity - A media entity graph object.
330  *		re-used if entities are unregistered or registered again.
379  * media_entity_for_each_pad - Iterate on all pads in an entity
386 	for (iter = (entity)->pads;				\
387 	     iter < &(entity)->pads[(entity)->num_pads];	\
391  * struct media_interface - A media interface graph object.
414  * struct media_intf_devnode - A media interface via a device node.
429  * media_entity_id() - return the media entity graph object id
435 	return entity->graph_obj.id;  in media_entity_id()
439  * media_type() - return the media object type
445 	return gobj->id >> MEDIA_BITS_PER_ID;  in media_type()
449  * media_id() - return the media object ID
455 	return gobj->id & MEDIA_ID_MASK;  in media_id()
459  * media_gobj_gen_id() - encapsulates type and ID on at the object ID
475  * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
484 	return entity && entity->obj_type == MEDIA_ENTITY_TYPE_VIDEO_DEVICE;  in is_media_entity_v4l2_video_device()
488  * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
497 	return entity && entity->obj_type == MEDIA_ENTITY_TYPE_V4L2_SUBDEV;  in is_media_entity_v4l2_subdev()
501  * media_entity_enum_init - Initialise an entity enumeration
512  * media_entity_enum_cleanup - Release resources of an entity enumeration
519  * media_entity_enum_zero - Clear the entire enum
525 	bitmap_zero(ent_enum->bmap, ent_enum->idx_max);  in media_entity_enum_zero()
529  * media_entity_enum_set - Mark a single entity in the enum
537 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_set()
540 	__set_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_set()
544  * media_entity_enum_clear - Unmark a single entity in the enum
552 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_clear()
555 	__clear_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_clear()
559  * media_entity_enum_test - Test whether the entity is marked
569 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_test()
572 	return test_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_test()
576  * media_entity_enum_test_and_set - Test whether the entity is marked,
588 	if (WARN_ON(entity->internal_idx >= ent_enum->idx_max))  in media_entity_enum_test_and_set()
591 	return __test_and_set_bit(entity->internal_idx, ent_enum->bmap);  in media_entity_enum_test_and_set()
595  * media_entity_enum_empty - Test whether the entire enum is empty
603 	return bitmap_empty(ent_enum->bmap, ent_enum->idx_max);  in media_entity_enum_empty()
607  * media_entity_enum_intersects - Test whether two enums intersect
619 	WARN_ON(ent_enum1->idx_max != ent_enum2->idx_max);  in media_entity_enum_intersects()
621 	return bitmap_intersects(ent_enum1->bmap, ent_enum2->bmap,  in media_entity_enum_intersects()
622 				 min(ent_enum1->idx_max, ent_enum2->idx_max));  in media_entity_enum_intersects()
626  * gobj_to_entity - returns the struct &media_entity pointer from the
635  * gobj_to_pad - returns the struct &media_pad pointer from the
644  * gobj_to_link - returns the struct &media_link pointer from the
653  * gobj_to_intf - returns the struct &media_interface pointer from the
662  * intf_to_devnode - returns the struct media_intf_devnode pointer from the
671  *  media_gobj_create - Initialize a graph object
679  * function calls are used. However, if the object (entity, link, pad,
688  *  media_gobj_destroy - Stop using a graph object on a media device
698  * media_entity_pads_init() - Initialize the entity pads
709  * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
714  * pads array in a driver-specific structure, avoiding dynamic allocation.
723  * media_entity_cleanup() - free resources associated with an entity
732  * valid and is a no-op.
741  * media_get_pad_index() - retrieves a pad index from an entity
753  * entity is a NULL pointer, return -EINVAL.
759  * media_create_pad_link() - creates a link between two entities.
765  * @flags:	Link flags, as defined in
772  *   Indicates that the link is enabled and can be used to transfer media data.
777  *   Indicates that the link enabled state can't be modified at runtime. If
779  *   set, since an immutable link is always enabled.
791  * media_create_pad_links() - creates a link between two entities.
803  * @flags: Link flags, as defined in include/uapi/linux/media.h.
807  *	If %false, it will return 0 and won't create any link if both @source
812  * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
814  *	flag is passed as an argument, only the first created link will have
817  * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
819  *	%MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
824  * creates link by link, this function is meant to allow 1:n, n:1 and even
825  * cross-bar (n:n) links.
846  * media_entity_remove_links() - remove all links associated with an entity
858  * __media_entity_setup_link - Configure a media link without locking
859  * @link: The link being configured
860  * @flags: Link configuration flags
862  * The bulk of link setup is handled by the two entities connected through the
863  * link. This function notifies both entities of the link configuration change.
865  * If the link is immutable or if the current and new configuration are
868  * The user is expected to hold link->source->parent->mutex. If not,
871 int __media_entity_setup_link(struct media_link *link, u32 flags);
874  * media_entity_setup_link() - changes the link flags properties in runtime
876  * @link:	pointer to &media_link
877  * @flags:	the requested new link flags
879  * The only configurable property is the %MEDIA_LNK_FL_ENABLED link flag
880  * to enable/disable a link. Links marked with the
881  * %MEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled.
883  * When a link is enabled or disabled, the media framework calls the
885  * link, in that order. If the second link_setup call fails, another
886  * link_setup call is made on the first entity to restore the original link
889  * Media device drivers can be notified of link setup operations by setting the
895  * is non-immutable. The operation must either configure the hardware or store
898  * Link configuration must not have any side effect on other links. If an
899  * enabled link at a sink pad prevents another link at the same pad from
900  * being enabled, the link_setup operation must return %-EBUSY and can't
901  * implicitly disable the first enabled link.
905  *    The valid values of the flags for the link is the same as described
909 int media_entity_setup_link(struct media_link *link, u32 flags);
912  * media_entity_find_link - Find a link between two pads
916  * Return: returns a pointer to the link between the two entities. If no
917  * such link exists, return %NULL.
923  * media_pad_remote_pad_first - Find the first pad at the remote end of a link
924  * @pad: Pad at the local end of the link
927  * links originating or terminating at that pad until an enabled link is found.
930  * enabled link, or %NULL if no enabled link has been found.
935  * media_pad_remote_pad_unique - Find a remote pad connected to a pad
939  * link. If multiple (or no) remote pads are found, an error is returned.
942  * that support a single active source at a time on a given pad.
947  * * -ENOTUNIQ - Multiple links are enabled
948  * * -ENOLINK - No connected pad found
953  * media_entity_remote_pad_unique - Find a remote pad connected to an entity
958  * enabled link. If multiple (or no) remote pads match these criteria, an error
962  * that support a single active source or sink at a time.
967  * * -ENOTUNIQ - Multiple links are enabled
968  * * -ENOLINK - No connected pad found
975  * media_entity_remote_source_pad_unique - Find a remote source pad connected to
980  * enabled link. If multiple (or no) remote pads match these criteria, an error
984  * that support a single active source at a time.
989  * * -ENOTUNIQ - Multiple links are enabled
990  * * -ENOLINK - No connected pad found
999  * media_pad_is_streaming - Test if a pad is part of a streaming pipeline
1007 	return pad->pipe;  in media_pad_is_streaming()
1011  * media_entity_is_streaming - Test if an entity is part of a streaming pipeline
1030  * media_entity_pipeline - Get the media pipeline an entity is part of
1050  * media_pad_pipeline - Get the media pipeline a pad is part of
1063  * media_entity_get_fwnode_pad - Get pad number from fwnode
1086  * media_graph_walk_init - Allocate resources used by graph walk.
1102  * media_graph_walk_cleanup - Release resources used by graph walk.
1111  * media_graph_walk_start - Start walking the media graph at a
1131  * media_graph_walk_next - Get the next entity in the graph
1136  * Perform a depth-first traversal of the given media entities graph.
1147  * media_pipeline_start - Mark a pipeline as streaming
1163  * __media_pipeline_start - Mark a pipeline as streaming
1168  * ..note:: This is the non-locking version of media_pipeline_start()
1174  * media_pipeline_stop - Mark a pipeline as not streaming
1188  * __media_pipeline_stop - Mark a pipeline as not streaming
1192  * .. note:: This is the non-locking version of media_pipeline_stop()
1202  * media_pipeline_for_each_pad - Iterate on all pads in a media pipeline
1217  * media_pipeline_entity_iter_init - Initialize a pipeline entity iterator
1235  * media_pipeline_entity_iter_cleanup - Destroy a pipeline entity iterator
1249  * media_pipeline_for_each_entity - Iterate on all entities in a media pipeline
1267  * media_pipeline_alloc_start - Mark a pipeline as streaming
1280  * media_devnode_create() - creates and initializes a device node interface
1304  * media_devnode_remove() - removes a device node interface
1314  * media_create_intf_link() - creates a link between an entity and an interface
1318  * @flags:	Link flags, as defined in
1340  *    interface that will be part of the link.
1347  * __media_remove_intf_link() - remove a single interface link
1349  * @link:	pointer to &media_link.
1353 void __media_remove_intf_link(struct media_link *link);
1356  * media_remove_intf_link() - remove a single interface link
1358  * @link:	pointer to &media_link.
1362 void media_remove_intf_link(struct media_link *link);
1365  * __media_remove_intf_links() - remove all links associated with an interface
1374  * media_remove_intf_links() - remove all links associated with an interface
1388  * media_entity_call - Calls a struct media_entity_operations operation on
1400 	(((entity)->ops && (entity)->ops->operation) ?			\
1401 	 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
1404  * media_create_ancillary_link() - create an ancillary link between two
1410  * Create an ancillary link between two entities, indicating that they
1411  * represent two connected pieces of hardware that form a single logical unit.
1416  * the new link.
1423  * __media_entity_next_link() - Iterate through a &media_entity's links
1426  * @link:	pointer to a &media_link to hold the iterated values
1429  * Return the next link against an entity matching a specific link type. This
1434 					    struct media_link *link,
1438  * for_each_media_entity_data_link() - Iterate through an entity's data links
1441  * @link:	pointer to a &media_link to hold the iterated values
1445 #define for_each_media_entity_data_link(entity, link)			\  argument
1446 	for (link = __media_entity_next_link(entity, NULL,		\
1448 	     link;							\
1449 	     link = __media_entity_next_link(entity, link,		\