diff options
Diffstat (limited to 'include/media/media-entity.h')
| -rw-r--r-- | include/media/media-entity.h | 248 |
1 files changed, 160 insertions, 88 deletions
diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 09b03c17784d..b2203ee7a4c1 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -56,7 +56,7 @@ enum media_gobj_type { /** * struct media_gobj - Define a graph object. * - * @mdev: Pointer to the struct media_device that owns the object + * @mdev: Pointer to the struct &media_device that owns the object * @id: Non-zero object ID identifier. The ID should be unique * inside a media_device, as it is composed by * %MEDIA_BITS_PER_TYPE to store the type plus @@ -129,7 +129,7 @@ struct media_pipeline { * an interface. * @gobj1: Part of a union. Used to get the pointer for the second * graph_object of the link. - * @source: Part of a union. Used only if the second object (gobj1) is + * @sink: Part of a union. Used only if the second object (gobj1) is * a pad. In that case, it represents the sink pad. * @entity: Part of a union. Used only if the second object (gobj1) is * an entity. @@ -162,7 +162,9 @@ struct media_link { * @graph_obj: Embedded structure containing the media object common data * @entity: Entity this pad belongs to * @index: Pad index in the entity pads array, numbered from 0 to n - * @flags: Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*) + * @flags: Pad flags, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * (seek for ``MEDIA_PAD_FL_*``) */ struct media_pad { struct media_gobj graph_obj; /* must be first field in struct */ @@ -182,7 +184,7 @@ struct media_pad { * * .. note:: * - * Those these callbacks are called with struct media_device.@graph_mutex + * Those these callbacks are called with struct &media_device.graph_mutex * mutex held. */ struct media_entity_operations { @@ -210,7 +212,7 @@ struct media_entity_operations { * This allows runtime type identification of media entities and safe casting to * the correct object type. For instance, a media entity structure instance * embedded in a v4l2_subdev structure instance will have the type - * MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a v4l2_subdev + * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev * structure using the container_of() macro. */ enum media_entity_type { @@ -225,9 +227,12 @@ enum media_entity_type { * @graph_obj: Embedded structure containing the media object common data. * @name: Entity name. * @obj_type: Type of the object that implements the media_entity. - * @function: Entity main function, as defined in uapi/media.h - * (MEDIA_ENT_F_*) - * @flags: Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*) + * @function: Entity main function, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * (seek for ``MEDIA_ENT_F_*``) + * @flags: Entity flags, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * (seek for ``MEDIA_ENT_FL_*``) * @num_pads: Number of sink and source pads. * @num_links: Total number of links, forward and back, enabled and disabled. * @num_backlinks: Number of backlinks @@ -246,9 +251,12 @@ enum media_entity_type { * @minor: Devnode minor number (zero if not applicable). Kept just * for backward compatibility. * - * NOTE: @stream_count and @use_count reference counts must never be - * negative, but are signed integers on purpose: a simple WARN_ON(<0) check - * can be used to detect reference count bugs that would make them negative. + * .. note:: + * + * @stream_count and @use_count reference counts must never be + * negative, but are signed integers on purpose: a simple ``WARN_ON(<0)`` + * check can be used to detect reference count bugs that would make them + * negative. */ struct media_entity { struct media_gobj graph_obj; /* must be first field in struct */ @@ -267,10 +275,6 @@ struct media_entity { const struct media_entity_operations *ops; - /* Reference counts must never be negative, but are signed integers on - * purpose: a simple WARN_ON(<0) check can be used to detect reference - * count bugs that would make them negative. - */ int stream_count; int use_count; @@ -289,10 +293,16 @@ struct media_entity { * * @graph_obj: embedded graph object * @links: List of links pointing to graph entities - * @type: Type of the interface as defined in the - * uapi/media/media.h header, e. g. - * MEDIA_INTF_T_* - * @flags: Interface flags as defined in uapi/media/media.h + * @type: Type of the interface as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * (seek for ``MEDIA_INTF_T_*``) + * @flags: Interface flags as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * (seek for ``MEDIA_INTF_FL_*``) + * + * .. note:: + * + * Currently, no flags for &media_interface is defined. */ struct media_interface { struct media_gobj graph_obj; @@ -319,7 +329,7 @@ struct media_intf_devnode { /** * media_entity_id() - return the media entity graph object id * - * @entity: pointer to entity + * @entity: pointer to &media_entity */ static inline u32 media_entity_id(struct media_entity *entity) { @@ -329,7 +339,7 @@ static inline u32 media_entity_id(struct media_entity *entity) /** * media_type() - return the media object type * - * @gobj: pointer to the media graph object + * @gobj: Pointer to the struct &media_gobj graph object */ static inline enum media_gobj_type media_type(struct media_gobj *gobj) { @@ -339,7 +349,7 @@ static inline enum media_gobj_type media_type(struct media_gobj *gobj) /** * media_id() - return the media object ID * - * @gobj: pointer to the media graph object + * @gobj: Pointer to the struct &media_gobj graph object */ static inline u32 media_id(struct media_gobj *gobj) { @@ -350,7 +360,7 @@ static inline u32 media_id(struct media_gobj *gobj) * media_gobj_gen_id() - encapsulates type and ID on at the object ID * * @type: object type as define at enum &media_gobj_type. - * @local_id: next ID, from struct &media_device.@id. + * @local_id: next ID, from struct &media_device.id. */ static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) { @@ -366,9 +376,9 @@ static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id) * is_media_entity_v4l2_video_device() - Check if the entity is a video_device * @entity: pointer to entity * - * Return: true if the entity is an instance of a video_device object and can + * Return: %true if the entity is an instance of a video_device object and can * safely be cast to a struct video_device using the container_of() macro, or - * false otherwise. + * %false otherwise. */ static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity) { @@ -379,9 +389,9 @@ static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev * @entity: pointer to entity * - * Return: true if the entity is an instance of a v4l2_subdev object and can - * safely be cast to a struct v4l2_subdev using the container_of() macro, or - * false otherwise. + * Return: %true if the entity is an instance of a &v4l2_subdev object and can + * safely be cast to a struct &v4l2_subdev using the container_of() macro, or + * %false otherwise. */ static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity) { @@ -452,7 +462,7 @@ static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum, * @ent_enum: Entity enumeration * @entity: Entity to be tested * - * Returns true if the entity was marked. + * Returns %true if the entity was marked. */ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, struct media_entity *entity) @@ -464,12 +474,13 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum, } /** - * media_entity_enum_test - Test whether the entity is marked, and mark it + * media_entity_enum_test_and_set - Test whether the entity is marked, + * and mark it * * @ent_enum: Entity enumeration * @entity: Entity to be tested * - * Returns true if the entity was marked, and mark it before doing so. + * Returns %true if the entity was marked, and mark it before doing so. */ static inline bool media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, @@ -486,7 +497,7 @@ media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, * * @ent_enum: Entity enumeration * - * Returns true if the entity was marked. + * Return: %true if the entity was empty. */ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) { @@ -499,7 +510,8 @@ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) * @ent_enum1: First entity enumeration * @ent_enum2: Second entity enumeration * - * Returns true if entity enumerations e and f intersect, otherwise false. + * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect, + * otherwise %false. */ static inline bool media_entity_enum_intersects( struct media_entity_enum *ent_enum1, @@ -511,39 +523,63 @@ static inline bool media_entity_enum_intersects( min(ent_enum1->idx_max, ent_enum2->idx_max)); } +/** + * gobj_to_entity - returns the struct &media_entity pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_entity(gobj) \ container_of(gobj, struct media_entity, graph_obj) +/** + * gobj_to_pad - returns the struct &media_pad pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_pad(gobj) \ container_of(gobj, struct media_pad, graph_obj) +/** + * gobj_to_link - returns the struct &media_link pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_link(gobj) \ container_of(gobj, struct media_link, graph_obj) -#define gobj_to_link(gobj) \ - container_of(gobj, struct media_link, graph_obj) - -#define gobj_to_pad(gobj) \ - container_of(gobj, struct media_pad, graph_obj) - +/** + * gobj_to_intf - returns the struct &media_interface pointer from the + * @gobj contained on it. + * + * @gobj: Pointer to the struct &media_gobj graph object + */ #define gobj_to_intf(gobj) \ container_of(gobj, struct media_interface, graph_obj) +/** + * intf_to_devnode - returns the struct media_intf_devnode pointer from the + * @intf contained on it. + * + * @intf: Pointer to struct &media_intf_devnode + */ #define intf_to_devnode(intf) \ container_of(intf, struct media_intf_devnode, intf) /** * media_gobj_create - Initialize a graph object * - * @mdev: Pointer to the media_device that contains the object + * @mdev: Pointer to the &media_device that contains the object * @type: Type of the object - * @gobj: Pointer to the graph object + * @gobj: Pointer to the struct &media_gobj graph object * - * This routine initializes the embedded struct media_gobj inside a - * media graph object. It is called automatically if media_*_create\(\) - * calls are used. However, if the object (entity, link, pad, interface) - * is embedded on some other object, this function should be called before - * registering the object at the media controller. + * This routine initializes the embedded struct &media_gobj inside a + * media graph object. It is called automatically if ``media_*_create`` + * function calls are used. However, if the object (entity, link, pad, + * interface) is embedded on some other object, this function should be + * called before registering the object at the media controller. */ void media_gobj_create(struct media_device *mdev, enum media_gobj_type type, @@ -552,7 +588,7 @@ void media_gobj_create(struct media_device *mdev, /** * media_gobj_destroy - Stop using a graph object on a media device * - * @gobj: Pointer to the graph object + * @gobj: Pointer to the struct &media_gobj graph object * * This should be called by all routines like media_device_unregister() * that remove/destroy media graph objects. @@ -567,11 +603,11 @@ void media_gobj_destroy(struct media_gobj *gobj); * @pads: Array of @num_pads pads. * * The pads array is managed by the entity driver and passed to - * media_entity_pads_init() where its pointer will be stored in the entity - * structure. + * media_entity_pads_init() where its pointer will be stored in the + * &media_entity structure. * * If no pads are needed, drivers could either directly fill - * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call + * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call * this function that will do the same. * * As the number of pads is known in advance, the pads array is not allocated @@ -601,18 +637,21 @@ static inline void media_entity_cleanup(struct media_entity *entity) {}; * @source_pad: number of the source pad in the pads array * @sink: pointer to &media_entity of the sink pad. * @sink_pad: number of the sink pad in the pads array. - * @flags: Link flags, as defined in include/uapi/linux/media.h. + * @flags: Link flags, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * ( seek for ``MEDIA_LNK_FL_*``) * * Valid values for flags: * - * - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can - * be used to transfer media data. When two or more links target a sink pad, - * only one of them can be enabled at a time. + * %MEDIA_LNK_FL_ENABLED + * Indicates that the link is enabled and can be used to transfer media data. + * When two or more links target a sink pad, only one of them can be + * enabled at a time. * - * - A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't - * be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then - * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is - * always enabled. + * %MEDIA_LNK_FL_IMMUTABLE + * Indicates that the link enabled state can't be modified at runtime. If + * %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be + * set, since an immutable link is always enabled. * * .. note:: * @@ -630,17 +669,17 @@ __must_check int media_create_pad_link(struct media_entity *source, * @source_function: Function of the source entities. Used only if @source is * NULL. * @source: pointer to &media_entity of the source pad. If NULL, it will use - * all entities that matches the @sink_function. + * all entities that matches the @sink_function. * @source_pad: number of the source pad in the pads array * @sink_function: Function of the sink entities. Used only if @sink is NULL. * @sink: pointer to &media_entity of the sink pad. If NULL, it will use - * all entities that matches the @sink_function. + * all entities that matches the @sink_function. * @sink_pad: number of the sink pad in the pads array. * @flags: Link flags, as defined in include/uapi/linux/media.h. - * @allow_both_undefined: if true, then both @source and @sink can be NULL. + * @allow_both_undefined: if %true, then both @source and @sink can be NULL. * In such case, it will create a crossbar between all entities that * matches @source_function to all entities that matches @sink_function. - * If false, it will return 0 and won't create any link if both @source + * If %false, it will return 0 and won't create any link if both @source * and @sink are NULL. * * Valid values for flags: @@ -660,9 +699,11 @@ __must_check int media_create_pad_link(struct media_entity *source, * creates link by link, this function is meant to allow 1:n, n:1 and even * cross-bar (n:n) links. * - * NOTE: Before calling this function, media_entity_pads_init() and - * media_device_register_entity() should be called previously for the entities - * to be linked. + * .. note:: + * + * Before calling this function, media_entity_pads_init() and + * media_device_register_entity() should be called previously for the + * entities to be linked. */ int media_create_pad_links(const struct media_device *mdev, const u32 source_function, @@ -721,7 +762,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags); * flags. * * Media device drivers can be notified of link setup operations by setting the - * media_device::link_notify pointer to a callback function. If provided, the + * &media_device.link_notify pointer to a callback function. If provided, the * notification callback will be called before enabling and after disabling * links. * @@ -731,7 +772,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags); * * Link configuration must not have any side effect on other links. If an * enabled link at a sink pad prevents another link at the same pad from - * being enabled, the link_setup operation must return -EBUSY and can't + * being enabled, the link_setup operation must return %-EBUSY and can't * implicitly disable the first enabled link. * * .. note:: @@ -747,8 +788,8 @@ int media_entity_setup_link(struct media_link *link, u32 flags); * @source: Source pad * @sink: Sink pad * - * Return a pointer to the link between the two entities. If no such link - * exists, return NULL. + * Return: returns a pointer to the link between the two entities. If no + * such link exists, return %NULL. */ struct media_link *media_entity_find_link(struct media_pad *source, struct media_pad *sink); @@ -760,8 +801,8 @@ struct media_link *media_entity_find_link(struct media_pad *source, * Search for a remote pad connected to the given pad by iterating over all * links originating or terminating at that pad until an enabled link is found. * - * Return a pointer to the pad at the remote end of the first found enabled - * link, or NULL if no enabled link has been found. + * Return: returns a pointer to the pad at the remote end of the first found + * enabled link, or %NULL if no enabled link has been found. */ struct media_pad *media_entity_remote_pad(struct media_pad *pad); @@ -772,12 +813,18 @@ struct media_pad *media_entity_remote_pad(struct media_pad *pad); * * Get a reference to the parent media device module. * - * The function will return immediately if @entity is NULL. + * The function will return immediately if @entity is %NULL. * - * Return a pointer to the entity on success or NULL on failure. + * Return: returns a pointer to the entity on success or %NULL on failure. */ struct media_entity *media_entity_get(struct media_entity *entity); +/** + * media_entity_graph_walk_init - Allocate resources used by graph walk. + * + * @graph: Media graph structure that will be used to walk the graph + * @mdev: Pointer to the &media_device that contains the object + */ __must_check int media_entity_graph_walk_init( struct media_entity_graph *graph, struct media_device *mdev); @@ -795,12 +842,14 @@ void media_entity_graph_walk_cleanup(struct media_entity_graph *graph); * * Release the reference count acquired by media_entity_get(). * - * The function will return immediately if @entity is NULL. + * The function will return immediately if @entity is %NULL. */ void media_entity_put(struct media_entity *entity); /** - * media_entity_graph_walk_start - Start walking the media graph at a given entity + * media_entity_graph_walk_start - Start walking the media graph at a + * given entity + * * @graph: Media graph structure that will be used to walk the graph * @entity: Starting entity * @@ -824,8 +873,8 @@ void media_entity_graph_walk_start(struct media_entity_graph *graph, * The graph structure must have been previously initialized with a call to * media_entity_graph_walk_start(). * - * Return the next entity in the graph or NULL if the whole graph have been - * traversed. + * Return: returns the next entity in the graph or %NULL if the whole graph + * have been traversed. */ struct media_entity * media_entity_graph_walk_next(struct media_entity_graph *graph); @@ -836,8 +885,8 @@ media_entity_graph_walk_next(struct media_entity_graph *graph); * @pipe: Media pipeline to be assigned to all entities in the pipeline. * * Mark all entities connected to a given entity through enabled links, either - * directly or indirectly, as streaming. The given pipeline object is assigned to - * every entity in the pipeline and stored in the media_entity pipe field. + * directly or indirectly, as streaming. The given pipeline object is assigned + * to every entity in the pipeline and stored in the media_entity pipe field. * * Calls to this function can be nested, in which case the same number of * media_entity_pipeline_stop() calls will be required to stop streaming. The @@ -863,7 +912,7 @@ __must_check int __media_entity_pipeline_start(struct media_entity *entity, * * Mark all entities connected to a given entity through enabled links, either * directly or indirectly, as not streaming. The media_entity pipe field is - * reset to NULL. + * reset to %NULL. * * If multiple calls to media_entity_pipeline_start() have been made, the same * number of calls to this function are required to mark the pipeline as not @@ -884,14 +933,21 @@ void __media_entity_pipeline_stop(struct media_entity *entity); * media_devnode_create() - creates and initializes a device node interface * * @mdev: pointer to struct &media_device - * @type: type of the interface, as given by MEDIA_INTF_T_* macros - * as defined in the uapi/media/media.h header. - * @flags: Interface flags as defined in uapi/media/media.h. + * @type: type of the interface, as given by + * :ref:`include/uapi/linux/media.h <media_header>` + * ( seek for ``MEDIA_INTF_T_*``) macros. + * @flags: Interface flags, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * ( seek for ``MEDIA_INTF_FL_*``) * @major: Device node major number. * @minor: Device node minor number. * * Return: if succeeded, returns a pointer to the newly allocated * &media_intf_devnode pointer. + * + * .. note:: + * + * Currently, no flags for &media_interface is defined. */ struct media_intf_devnode * __must_check media_devnode_create(struct media_device *mdev, @@ -913,15 +969,19 @@ struct media_link * * * @entity: pointer to %media_entity * @intf: pointer to %media_interface - * @flags: Link flags, as defined in include/uapi/linux/media.h. + * @flags: Link flags, as defined in + * :ref:`include/uapi/linux/media.h <media_header>` + * ( seek for ``MEDIA_LNK_FL_*``) * * * Valid values for flags: * - * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to - * the entity hardware. That's the default value for interfaces. An - * interface may be disabled if the hardware is busy due to the usage - * of some other interface that it is currently controlling the hardware. + * %MEDIA_LNK_FL_ENABLED + * Indicates that the interface is connected to the entity hardware. + * That's the default value for interfaces. An interface may be disabled if + * the hardware is busy due to the usage of some other interface that it is + * currently controlling the hardware. + * * A typical example is an hybrid TV device that handle only one type of * stream on a given time. So, when the digital TV is streaming, * the V4L2 interfaces won't be enabled, as such device is not able to @@ -977,6 +1037,18 @@ void __media_remove_intf_links(struct media_interface *intf); */ void media_remove_intf_links(struct media_interface *intf); +/** + * media_entity_call - Calls a struct media_entity_operations operation on + * an entity + * + * @entity: entity where the @operation will be called + * @operation: type of the operation. Should be the name of a member of + * struct &media_entity_operations. + * + * This helper function will check if @operation is not %NULL. On such case, + * it will issue a call to @operation\(@entity, @args\). + */ + #define media_entity_call(entity, operation, args...) \ (((entity)->ops && (entity)->ops->operation) ? \ (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) |