[media] media-entity.h: document all the structs

Only a few structs are documented on kernel-doc-nano format
(the ones added by the MC next gen patches).

Add a documentation for all structs, and ensure that they'll
be producing the documentation at the Kernel's device driver
DocBook.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index f165d303f03c896fb7244947708da920007366b2..fd19aecdcbb6428e891b75c4432132d4ee5e6e7a 100644 (file)
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -55,11 +55,13 @@ enum media_gobj_type {
 /**
  * struct media_gobj - Define a graph 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
  *             MEDIA_BITS_PER_LOCAL_ID to store a per-type ID
  *             (called as "local ID").
+ * @list:      List entry stored in one of the per-type mdev object lists
  *
  * All objects on the media graph should have this struct embedded
  */
@@ -73,6 +75,28 @@ struct media_gobj {
 struct media_pipeline {
 };
 
+/**
+ * struct media_link - A link object part of a media graph.
+ *
+ * @graph_obj: Embedded structure containing the media object common data
+ * @list:      Linked list associated with an entity or an interface that
+ *             owns the link.
+ * @gobj0:     Part of a union. Used to get the pointer for the first
+ *             graph_object of the link.
+ * @source:    Part of a union. Used only if the first object (gobj0) is
+ *             a pad. In that case, it represents the source pad.
+ * @intf:      Part of a union. Used only if the first object (gobj0) is
+ *             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
+ *             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.
+ * @reverse:   Pointer to the link for the reverse direction of a pad to pad
+ *             link.
+ * @flags:     Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)
+ */
 struct media_link {
        struct media_gobj graph_obj;
        struct list_head list;
@@ -86,15 +110,23 @@ struct media_link {
                struct media_pad *sink;
                struct media_entity *entity;
        };
-       struct media_link *reverse;     /* Link in the reverse direction */
-       unsigned long flags;            /* Link flags (MEDIA_LNK_FL_*) */
+       struct media_link *reverse;
+       unsigned long flags;
 };
 
+/**
+ * struct media_pad - A media pad graph object.
+ *
+ * @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_*)
+ */
 struct media_pad {
        struct media_gobj graph_obj;    /* must be first field in struct */
-       struct media_entity *entity;    /* Entity this pad belongs to */
-       u16 index;                      /* Pad index in the entity pads array */
-       unsigned long flags;            /* Pad flags (MEDIA_PAD_FL_*) */
+       struct media_entity *entity;
+       u16 index;
+       unsigned long flags;
 };
 
 /**
@@ -113,56 +145,78 @@ struct media_entity_operations {
        int (*link_validate)(struct media_link *link);
 };
 
+/**
+ * struct media_entity - A media entity graph object.
+ *
+ * @graph_obj: Embedded structure containing the media object common data.
+ * @name:      Entity name.
+ * @type:      Entity type, as defined in uapi/media.h (MEDIA_ENT_T_*)
+ * @revision:  Entity revision - OBSOLETE - should be removed soon.
+ * @flags:     Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*)
+ * @group_id:  Entity group ID - OBSOLETE - should be removed soon.
+ * @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
+ * @pads:      Pads array with the size defined by @num_pads.
+ * @links:     List of data links.
+ * @ops:       Entity operations.
+ * @stream_count: Stream count for the entity.
+ * @use_count: Use count for the entity.
+ * @pipe:      Pipeline this entity belongs to.
+ * @info:      Union with devnode information.  Kept just for backward
+ *             compatibility.
+ * @major:     Devnode major number (zero if not applicable). Kept just
+ *             for backward compatibility.
+ * @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.
+ */
 struct media_entity {
        struct media_gobj graph_obj;    /* must be first field in struct */
-       const char *name;               /* Entity name */
-       u32 type;                       /* Entity type (MEDIA_ENT_T_*) */
-       u32 revision;                   /* Entity revision, driver specific */
-       unsigned long flags;            /* Entity flags (MEDIA_ENT_FL_*) */
-       u32 group_id;                   /* Entity group ID */
+       const char *name;
+       u32 type;
+       u32 revision;
+       unsigned long flags;
+       u32 group_id;
 
-       u16 num_pads;                   /* Number of sink and source pads */
-       u16 num_links;                  /* Number of existing links, both
-                                        * enabled and disabled */
-       u16 num_backlinks;              /* Number of backlinks */
+       u16 num_pads;
+       u16 num_links;
+       u16 num_backlinks;
 
-       struct media_pad *pads;         /* Pads array (num_pads objects) */
-       struct list_head links;         /* Pad-to-pad links list */
+       struct media_pad *pads;
+       struct list_head links;
 
-       const struct media_entity_operations *ops;      /* Entity operations */
+       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;               /* Stream count for the entity. */
-       int use_count;                  /* Use count for the entity. */
+       int stream_count;
+       int use_count;
 
-       struct media_pipeline *pipe;    /* Pipeline this entity belongs to. */
+       struct media_pipeline *pipe;
 
        union {
-               /* Node specifications */
                struct {
                        u32 major;
                        u32 minor;
                } dev;
-
-               /* Sub-device specifications */
-               /* Nothing needed yet */
        } info;
 };
 
 /**
- * struct media_intf_devnode - Define a Kernel API interface
+ * struct media_interface - A media interface graph object.
  *
  * @graph_obj:         embedded graph object
- * @list:              Linked list used to find other interfaces that belong
- *                     to the same media controller
  * @links:             List of links pointing to graph entities
- * @type:              Type of the interface as defined at the
+ * @type:              Type of the interface as defined in the
  *                     uapi/media/media.h header, e. g.
  *                     MEDIA_INTF_T_*
- * @flags:             Interface flags as defined at uapi/media/media.h
+ * @flags:             Interface flags as defined in uapi/media/media.h
  */
 struct media_interface {
        struct media_gobj               graph_obj;
@@ -172,7 +226,7 @@ struct media_interface {
 };
 
 /**
- * struct media_intf_devnode - Define a Kernel API interface via a device node
+ * struct media_intf_devnode - A media interface via a device node.
  *
  * @intf:      embedded interface object
  * @major:     Major number of a device node