Re: [PATCH v8 55/55] [media] media-entity.h: document all the structs
Em Mon, 23 Nov 2015 22:19:19 +0200
Laurent Pinchart escreveu:
> Hi Mauro,
>
> Thank you for the patch.
>
> On Sunday 06 September 2015 09:03:14 Mauro Carvalho Chehab wrote:
> > 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.
>
> Very good idea ! Please see below for some spelling mistakes or other
> corrections in addition to the ones pointed out by Hans.
>
> > Signed-off-by: Mauro Carvalho Chehab
> >
> > diff --git a/include/media/media-entity.h b/include/media/media-entity.h
> > index fb5f0e21f137..e1a89899deef 100644
> > --- 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: Linked list associated to one of the per-type mdev object lists
>
> I'd say "List entry stored in one of the ..." (or "List head" if you prefer).
>
> > *
> > * All objects on the media graph should have this struct embedded
> > */
> > @@ -73,6 +75,28 @@ struct media_gobj {
> > struct media_pipeline {
> > };
> >
> > +/**
> > + * struct media_link - Define a media link graph object.
>
> I think you can drop the "Define" and just say "A media link graph object".
> Or, rather, "A media graph link object" to mean "a link object part of a
> media
> graph".
>
> Same comment for the other structures.
>
> > + *
> > + * @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 an union. Used to get the pointer for the first
> > + * graph_object of the link.
> > + * @source:Part of an union. Used only if the first object (gobj0)
> > is
> > + * a pad. On such case, it represents the source pad.
> > + * @intf: Part of an union. Used only if the first object (gobj0) is
> > + * an interface.
> > + * @gobj1: Part of an union. Used to get the pointer for the second
> > + * graph_object of the link.
> > + * @source:Part of an union. Used only if the second object
> > (gobj0) is
>
> s/gobj0/gobj1/
>
> > + * a pad. On such case, it represents the sink pad.
> > + * @entity:Part of an union. Used only if the second object
> > (gobj0) is
>
> Ditto.
>
> > + * an entity.
> > + * @reverse: Pointer to the link for the reverse direction of a pad
> > to
> pad
> > + * link.
> > + * @flags: Link flags, as defined at 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 - Define a media pad graph object.
> > + *
> > + * @graph_obj: Embedded structure containing the media object common
> > data
> > + * @entity:Entity where this object belongs
>
> "Entity this pad belongs to"
>
> > + * @index: Pad index in the entity pads array, numbered from 0 to n
> > + * @flags: Pad flags, as defined at 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,51 +145,73 @@ struct media_entity_operations {
> > int (*link_validate)(struct media_link *link);
> > };
> >
> > +/**
> > + * struct media_entity - Define a media entity graph object.
> > + *
> > + * @graph_obj: Embedded structure containing the media object common
> > data.
> > + * @name: Entity name.
> > + * @type: Entity type, as defined at uapi/media.h (MEDIA_ENT_T_*)
> > + * @revision: Entity revision - OBSOLETE - should be removed soon.
> > + * @flags: Entity flags, as defined at uapi/media.h (MEDIA_ENT_FL_*)
Re: [PATCH v8 55/55] [media] media-entity.h: document all the structs
Hi Mauro,
Thank you for the patch.
On Sunday 06 September 2015 09:03:14 Mauro Carvalho Chehab wrote:
> 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.
Very good idea ! Please see below for some spelling mistakes or other
corrections in addition to the ones pointed out by Hans.
> Signed-off-by: Mauro Carvalho Chehab
>
> diff --git a/include/media/media-entity.h b/include/media/media-entity.h
> index fb5f0e21f137..e1a89899deef 100644
> --- 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:Linked list associated to one of the per-type mdev object lists
I'd say "List entry stored in one of the ..." (or "List head" if you prefer).
> *
> * All objects on the media graph should have this struct embedded
> */
> @@ -73,6 +75,28 @@ struct media_gobj {
> struct media_pipeline {
> };
>
> +/**
> + * struct media_link - Define a media link graph object.
I think you can drop the "Define" and just say "A media link graph object".
Or, rather, "A media graph link object" to mean "a link object part of a media
graph".
Same comment for the other structures.
> + *
> + * @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 an union. Used to get the pointer for the first
> + * graph_object of the link.
> + * @source: Part of an union. Used only if the first object (gobj0) is
> + * a pad. On such case, it represents the source pad.
> + * @intf:Part of an union. Used only if the first object (gobj0) is
> + * an interface.
> + * @gobj1: Part of an union. Used to get the pointer for the second
> + * graph_object of the link.
> + * @source: Part of an union. Used only if the second object (gobj0) is
s/gobj0/gobj1/
> + * a pad. On such case, it represents the sink pad.
> + * @entity: Part of an union. Used only if the second object (gobj0) is
Ditto.
> + * an entity.
> + * @reverse: Pointer to the link for the reverse direction of a pad to
pad
> + * link.
> + * @flags: Link flags, as defined at 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 - Define a media pad graph object.
> + *
> + * @graph_obj: Embedded structure containing the media object common
> data
> + * @entity: Entity where this object belongs
"Entity this pad belongs to"
> + * @index: Pad index in the entity pads array, numbered from 0 to n
> + * @flags: Pad flags, as defined at 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,51 +145,73 @@ struct media_entity_operations {
> int (*link_validate)(struct media_link *link);
> };
>
> +/**
> + * struct media_entity - Define a media entity graph object.
> + *
> + * @graph_obj: Embedded structure containing the media object common
> data.
> + * @name:Entity name.
> + * @type:Entity type, as defined at uapi/media.h (MEDIA_ENT_T_*)
> + * @revision:Entity revision - OBSOLETE - should be removed soon.
> + * @flags: Entity flags, as defined at 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: Number of existing links, both enabled and disabled.
I'd mention there that it includes the backlinks too as it's always c
Re: [PATCH v8 55/55] [media] media-entity.h: document all the structs
On 09/06/2015 02:03 PM, Mauro Carvalho Chehab wrote:
> 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.
>
> Signed-off-by: Mauro Carvalho Chehab
After correcting some typos (see below):
Acked-by: Hans Verkuil
>
> diff --git a/include/media/media-entity.h b/include/media/media-entity.h
> index fb5f0e21f137..e1a89899deef 100644
> --- 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:Linked list associated to 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 - Define a media link graph object.
> + *
> + * @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 an union. Used to get the pointer for the first
s/an union/a union/ (in multiple places)
See: https://answers.yahoo.com/question/index?qid=20081006092816AAvPO9n
> + * graph_object of the link.
> + * @source: Part of an union. Used only if the first object (gobj0) is
> + * a pad. On such case, it represents the source pad.
s/On such case/In that case/ (in multiple places)
> + * @intf:Part of an union. Used only if the first object (gobj0) is
> + * an interface.
> + * @gobj1: Part of an union. Used to get the pointer for the second
> + * graph_object of the link.
> + * @source: Part of an union. Used only if the second object (gobj0) is
> + * a pad. On such case, it represents the sink pad.
> + * @entity: Part of an union. Used only if the second object (gobj0) is
> + * an entity.
> + * @reverse: Pointer to the link for the reverse direction of a pad to pad
> + * link.
> + * @flags: Link flags, as defined at uapi/media.h (MEDIA_LNK_FL_*)
s/as defined at/as defined in/ (in multiple places)
> + */
> 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 - Define a media pad graph object.
> + *
> + * @graph_obj: Embedded structure containing the media object common
> data
> + * @entity: Entity where this object belongs
> + * @index: Pad index in the entity pads array, numbered from 0 to n
> + * @flags: Pad flags, as defined at 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,51 +145,73 @@ struct media_entity_operations {
> int (*link_validate)(struct media_link *link);
> };
>
> +/**
> + * struct media_entity - Define a media entity graph object.
> + *
> + * @graph_obj: Embedded structure containing the media object common
> data.
> + * @name:Entity name.
> + * @type:Entity type, as defined at uapi/media.h (MEDIA_ENT_T_*)
> + * @revision:Entity revision - OBSOLETE - should be removed soon.
> + * @flags: Entity flags, as defined at 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: Number of existing links, both enabled and disabled.
> + * @num_backlinks: Number of backlinks
> + * @pads:Pads array with the size defined by @num_pads.
> + * @links: Linked list for the data links.
> + * @ops: Entity operations.
> + * @stream_count: Stream count for the entity.
> + * @use_count: Use count for the entity.
> + * @
Re: [PATCH v8 55/55] [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.
Signed-off-by: Mauro Carvalho Chehab
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index fb5f0e21f137..e1a89899deef 100644
--- 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: Linked list associated to 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 - Define a media link graph object.
+ *
+ * @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 an union. Used to get the pointer for the first
+ * graph_object of the link.
+ * @source:Part of an union. Used only if the first object (gobj0) is
+ * a pad. On such case, it represents the source pad.
+ * @intf: Part of an union. Used only if the first object (gobj0) is
+ * an interface.
+ * @gobj1: Part of an union. Used to get the pointer for the second
+ * graph_object of the link.
+ * @source:Part of an union. Used only if the second object (gobj0) is
+ * a pad. On such case, it represents the sink pad.
+ * @entity:Part of an union. Used only if the second object (gobj0) is
+ * an entity.
+ * @reverse: Pointer to the link for the reverse direction of a pad to pad
+ * link.
+ * @flags: Link flags, as defined at 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 - Define a media pad graph object.
+ *
+ * @graph_obj: Embedded structure containing the media object common data
+ * @entity:Entity where this object belongs
+ * @index: Pad index in the entity pads array, numbered from 0 to n
+ * @flags: Pad flags, as defined at 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,51 +145,73 @@ struct media_entity_operations {
int (*link_validate)(struct media_link *link);
};
+/**
+ * struct media_entity - Define a media entity graph object.
+ *
+ * @graph_obj: Embedded structure containing the media object common data.
+ * @name: Entity name.
+ * @type: Entity type, as defined at uapi/media.h (MEDIA_ENT_T_*)
+ * @revision: Entity revision - OBSOLETE - should be removed soon.
+ * @flags: Entity flags, as defined at 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: Number of existing links, both enabled and disabled.
+ * @num_backlinks: Number of backlinks
+ * @pads: Pads array with the size defined by @num_pads.
+ * @links: Linked list for the 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 WAR
[PATCH v8 55/55] [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.
Signed-off-by: Mauro Carvalho Chehab
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index 7fd6265f0bcb..c42d191fa5a8 100644
--- 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: Linked list associated to 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 - Define a media link graph object.
+ *
+ * @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 an union. Used to get the pointer for the first
+ * graph_object of the link.
+ * @source:Part of an union. Used only if the first object (gobj0) is
+ * a pad. On such case, it represents the source pad.
+ * @intf: Part of an union. Used only if the first object (gobj0) is
+ * an interface.
+ * @gobj1: Part of an union. Used to get the pointer for the second
+ * graph_object of the link.
+ * @source:Part of an union. Used only if the second object (gobj0) is
+ * a pad. On such case, it represents the sink pad.
+ * @entity:Part of an union. Used only if the second object (gobj0) is
+ * an entity.
+ * @reverse: Pointer to the link for the reverse direction of a pad to pad
+ * link.
+ * @flags: Link flags, as defined at 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 - Define a media pad graph object.
+ *
+ * @graph_obj: Embedded structure containing the media object common data
+ * @entity:Entity where this object belongs
+ * @index: Pad index in the entity pads array, numbered from 0 to n
+ * @flags: Pad flags, as defined at 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,51 +145,73 @@ struct media_entity_operations {
int (*link_validate)(struct media_link *link);
};
+/**
+ * struct media_entity - Define a media entity graph object.
+ *
+ * @graph_obj: Embedded structure containing the media object common data.
+ * @name: Entity name.
+ * @type: Entity type, as defined at uapi/media.h (MEDIA_ENT_T_*)
+ * @revision: Entity revision - OBSOLETE - should be removed soon.
+ * @flags: Entity flags, as defined at 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: Number of existing links, both enabled and disabled.
+ * @num_backlinks: Number of backlinks
+ * @pads: Pads array with the size defined by @num_pads.
+ * @links: Linked list for the 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 WAR
