Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c358e80d authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[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: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
parent d9c21e3e

include/media/media-entity.h

+84 −30
Original line number Diff line number Diff line
@@ -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