/**
* 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
* 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.
* @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 */
*
* .. 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 {
* 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 {
* @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
* @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 */
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;
*
* @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;
/**
* 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)
{
/**
* 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)
{
/**
* 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)
{
* 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)
{
* 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)
{
* 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)
{
* @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)
}
/**
- * 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,
*
* @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)
{
* @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,
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,
/**
* 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.
* @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
* @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::
*
* @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:
* 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,
* 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.
*
*
* 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::
* @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);
* 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);
*
* 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);
*
* 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
*
* 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);
* @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
*
* 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
* 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,
*
* @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
*/
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)
projects / cascardo / linux.git / blobdiff