redonkable
/
remarkable-linux
1
0
Fork 0
Code Releases Activity

[media] docs-rst: improve the kAPI documentation for the mediactl 

There are several issues on the documentation:
  - the media.h header were not properly referenced;
  - verbatim expressions were not properly marked as such;
  - struct member references were wrong;
  - some notes were not using the right markup;
  - a comment that were moved to the kernel-doc markup were
    duplicated as a comment inside the struct media_entity;
  - some args were not pointing to the struct they're using;
  - macros weren't documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
steinar/wifi_calib_4_9_kernel
Mauro Carvalho Chehab 2016-08-29 16:09:11 -03:00
parent 36aefa35f4
commit 48a7c4bac9
3 changed files with 231 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
include/media/media-device.h
View File

@ -53,7 +53,7 @@ struct media_entity_notify {
* @dev: Parent device * @dev: Parent device
* @devnode: Media device node * @devnode: Media device node
* @driver_name: Optional device driver name. If not set, calls to * @driver_name: Optional device driver name. If not set, calls to
* %MEDIA_IOC_DEVICE_INFO will return dev->driver->name. * %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``.
* This is needed for USB drivers for example, as otherwise * This is needed for USB drivers for example, as otherwise
* they'll all appear as if the driver name was "usb". * they'll all appear as if the driver name was "usb".
* @model: Device model name * @model: Device model name
@ -102,16 +102,18 @@ struct media_entity_notify {
* sink entity and deactivate the link between them. Drivers * sink entity and deactivate the link between them. Drivers
* should call this handler to release the source. * should call this handler to release the source.
* *
* Note: Bridge driver is expected to implement and set the
* handler when media_device is registered or when
* bridge driver finds the media_device during probe.
* Bridge driver sets source_priv with information
* necessary to run enable/disable source handlers.
*
* Use-case: find tuner entity connected to the decoder * Use-case: find tuner entity connected to the decoder
* entity and check if it is available, and activate the * entity and check if it is available, and activate the
* the link between them from enable_source and deactivate * the link between them from @enable_source and deactivate
* from disable_source. * from @disable_source.
*
* .. note::
*
* Bridge driver is expected to implement and set the
* handler when &media_device is registered or when
* bridge driver finds the media_device during probe.
* Bridge driver sets source_priv with information
* necessary to run @enable_source and @disable_source handlers.
*/ */
struct media_device { struct media_device {
/* dev->driver_data points to this struct. */ /* dev->driver_data points to this struct. */
@ -168,7 +170,7 @@ struct usb_device;
* @ent_enum: Entity enumeration to be initialised * @ent_enum: Entity enumeration to be initialised
* @mdev: The related media device * @mdev: The related media device
* *
* Returns zero on success or a negative error code. * Return: zero on success or a negative error code.
*/ */
static inline __must_check int media_entity_enum_init( static inline __must_check int media_entity_enum_init(
struct media_entity_enum *ent_enum, struct media_device *mdev) struct media_entity_enum *ent_enum, struct media_device *mdev)
@ -211,36 +213,38 @@ void media_device_cleanup(struct media_device *mdev);
* *
* Users, should, instead, call the media_device_register() macro. * Users, should, instead, call the media_device_register() macro.
* *
* The caller is responsible for initializing the media_device structure before * The caller is responsible for initializing the &media_device structure
* registration. The following fields must be set: * before registration. The following fields of &media_device must be set:
* *
* - dev must point to the parent device (usually a &pci_dev, &usb_interface or * - &media_entity.dev must point to the parent device (usually a &pci_dev,
* &platform_device instance). * &usb_interface or &platform_device instance).
* *
* - model must be filled with the device model name as a NUL-terminated UTF-8 * - &media_entity.model must be filled with the device model name as a
* string. The device/model revision must not be stored in this field. * NUL-terminated UTF-8 string. The device/model revision must not be
* stored in this field.
* *
* The following fields are optional: * The following fields are optional:
* *
* - serial is a unique serial number stored as a NUL-terminated ASCII string. * - &media_entity.serial is a unique serial number stored as a
* The field is big enough to store a GUID in text form. If the hardware * NUL-terminated ASCII string. The field is big enough to store a GUID
* doesn't provide a unique serial number this field must be left empty. * in text form. If the hardware doesn't provide a unique serial number
* this field must be left empty.
* *
* - bus_info represents the location of the device in the system as a * - &media_entity.bus_info represents the location of the device in the
* NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to * system as a NUL-terminated ASCII string. For PCI/PCIe devices
* "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, * &media_entity.bus_info must be set to "PCI:" (or "PCIe:") followed by
* the usb_make_path() function must be used. This field is used by * the value of pci_name(). For USB devices,the usb_make_path() function
* applications to distinguish between otherwise identical devices that don't * must be used. This field is used by applications to distinguish between
* provide a serial number. * otherwise identical devices that don't provide a serial number.
* *
* - hw_revision is the hardware device revision in a driver-specific format. * - &media_entity.hw_revision is the hardware device revision in a
* When possible the revision should be formatted with the KERNEL_VERSION * driver-specific format. When possible the revision should be formatted
* macro. * with the KERNEL_VERSION() macro.
* *
* - driver_version is formatted with the KERNEL_VERSION macro. The version * - &media_entity.driver_version is formatted with the KERNEL_VERSION()
* minor must be incremented when new features are added to the userspace API * macro. The version minor must be incremented when new features are added
* without breaking binary compatibility. The version major must be * to the userspace API without breaking binary compatibility. The version
* incremented when binary compatibility is broken. * major must be incremented when binary compatibility is broken.
* *
* .. note:: * .. note::
* *
@ -252,6 +256,16 @@ void media_device_cleanup(struct media_device *mdev);
*/ */
int __must_check __media_device_register(struct media_device *mdev, int __must_check __media_device_register(struct media_device *mdev,
struct module *owner); struct module *owner);
/**
* media_device_register() - Registers a media device element
*
* @mdev: pointer to struct &media_device
*
* This macro calls __media_device_register() passing %THIS_MODULE as
* the __media_device_register() second argument (**owner**).
*/
#define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE)
/** /**
@ -259,7 +273,6 @@ int __must_check __media_device_register(struct media_device *mdev,
* *
* @mdev: pointer to struct &media_device * @mdev: pointer to struct &media_device
* *
*
* It is safe to call this function on an unregistered (but initialised) * It is safe to call this function on an unregistered (but initialised)
* media device. * media device.
*/ */
@ -285,14 +298,15 @@ void media_device_unregister(struct media_device *mdev);
* framework. * framework.
* *
* If the device has pads, media_entity_pads_init() should be called before * If the device has pads, media_entity_pads_init() should be called before
* this function. Otherwise, the &media_entity.@pad and &media_entity.@num_pads * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads
* should be zeroed before calling this function. * should be zeroed before calling this function.
* *
* Entities have flags that describe the entity capabilities and state: * Entities have flags that describe the entity capabilities and state:
* *
* %MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. * %MEDIA_ENT_FL_DEFAULT
* This can be used to report the default audio and video devices or the * indicates the default entity for a given type.
* default camera sensor. * This can be used to report the default audio and video devices or the
* default camera sensor.
* *
* .. note:: * .. note::
* *
@ -331,8 +345,10 @@ void media_device_unregister_entity(struct media_entity *entity);
* @mdev: The media device * @mdev: The media device
* @nptr: The media_entity_notify * @nptr: The media_entity_notify
* *
* Note: When a new entity is registered, all the registered * .. note::
* media_entity_notify callbacks are invoked. *
* When a new entity is registered, all the registered
* media_entity_notify callbacks are invoked.
*/ */
int __must_check media_device_register_entity_notify(struct media_device *mdev, int __must_check media_device_register_entity_notify(struct media_device *mdev,
@ -410,11 +426,13 @@ void media_device_pci_init(struct media_device *mdev,
* @board_name: media device name. If %NULL, the routine will use the usb * @board_name: media device name. If %NULL, the routine will use the usb
* product name, if available. * product name, if available.
* @driver_name: name of the driver. if %NULL, the routine will use the name * @driver_name: name of the driver. if %NULL, the routine will use the name
* given by udev->dev->driver->name, with is usually the wrong * given by ``udev->dev->driver->name``, with is usually the wrong
* thing to do. * thing to do.
* *
* NOTE: It is better to call media_device_usb_init() instead, as * .. note::
* such macro fills driver_name with %KBUILD_MODNAME. *
* It is better to call media_device_usb_init() instead, as
* such macro fills driver_name with %KBUILD_MODNAME.
*/ */
void __media_device_usb_init(struct media_device *mdev, void __media_device_usb_init(struct media_device *mdev,
struct usb_device *udev, struct usb_device *udev,
@ -472,6 +490,19 @@ static inline void __media_device_usb_init(struct media_device *mdev,
#endif /* CONFIG_MEDIA_CONTROLLER */ #endif /* CONFIG_MEDIA_CONTROLLER */
/**
* media_device_usb_init() - create and initialize a
* struct &media_device from a PCI device.
*
* @mdev: pointer to struct &media_device
* @udev: pointer to struct usb_device
* @name: media device name. If %NULL, the routine will use the usb
* product name, if available.
*
* This macro calls media_device_usb_init() passing the
* media_device_usb_init() **driver_name** parameter filled with
* %KBUILD_MODNAME.
*/
#define media_device_usb_init(mdev, udev, name) \ #define media_device_usb_init(mdev, udev, name) \
__media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME)

2
include/media/media-devnode.h
View File

@ -75,7 +75,7 @@ struct media_file_operations {
* @cdev: struct cdev pointer character device * @cdev: struct cdev pointer character device
* @parent: parent device * @parent: parent device
* @minor: device node minor number * @minor: device node minor number
* @flags: flags, combination of the MEDIA_FLAG_* constants * @flags: flags, combination of the ``MEDIA_FLAG_*`` constants
* @release: release callback called at the end of media_devnode_release() * @release: release callback called at the end of media_devnode_release()
* *
* This structure represents a media-related device node. * This structure represents a media-related device node.

237
include/media/media-entity.h
View File

@ -56,7 +56,7 @@ enum media_gobj_type {
/** /**
* struct media_gobj - Define a graph object. * 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 * @id: Non-zero object ID identifier. The ID should be unique
* inside a media_device, as it is composed by * inside a media_device, as it is composed by
* %MEDIA_BITS_PER_TYPE to store the type plus * %MEDIA_BITS_PER_TYPE to store the type plus
@ -162,7 +162,9 @@ struct media_link {
* @graph_obj: Embedded structure containing the media object common data * @graph_obj: Embedded structure containing the media object common data
* @entity: Entity this pad belongs to * @entity: Entity this pad belongs to
* @index: Pad index in the entity pads array, numbered from 0 to n * @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_pad {
struct media_gobj graph_obj; /* must be first field in struct */ struct media_gobj graph_obj; /* must be first field in struct */
@ -182,7 +184,7 @@ struct media_pad {
* *
* .. note:: * .. 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. * mutex held.
*/ */
struct media_entity_operations { struct media_entity_operations {
@ -210,7 +212,7 @@ struct media_entity_operations {
* This allows runtime type identification of media entities and safe casting to * This allows runtime type identification of media entities and safe casting to
* the correct object type. For instance, a media entity structure instance * the correct object type. For instance, a media entity structure instance
* embedded in a v4l2_subdev structure instance will have the type * 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. * structure using the container_of() macro.
*/ */
enum media_entity_type { enum media_entity_type {
@ -225,9 +227,12 @@ enum media_entity_type {
* @graph_obj: Embedded structure containing the media object common data. * @graph_obj: Embedded structure containing the media object common data.
* @name: Entity name. * @name: Entity name.
* @obj_type: Type of the object that implements the media_entity. * @obj_type: Type of the object that implements the media_entity.
* @function: Entity main function, as defined in uapi/media.h * @function: Entity main function, as defined in
* (MEDIA_ENT_F_*) * :ref:`include/uapi/linux/media.h <media_header>`
* @flags: Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*) * (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_pads: Number of sink and source pads.
* @num_links: Total number of links, forward and back, enabled and disabled. * @num_links: Total number of links, forward and back, enabled and disabled.
* @num_backlinks: Number of backlinks * @num_backlinks: Number of backlinks
@ -246,9 +251,12 @@ enum media_entity_type {
* @minor: Devnode minor number (zero if not applicable). Kept just * @minor: Devnode minor number (zero if not applicable). Kept just
* for backward compatibility. * for backward compatibility.
* *
* NOTE: @stream_count and @use_count reference counts must never be * .. note::
* 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. * @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_entity {
struct media_gobj graph_obj; /* must be first field in struct */ struct media_gobj graph_obj; /* must be first field in struct */
@ -267,10 +275,6 @@ struct media_entity {
const struct media_entity_operations *ops; 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 stream_count;
int use_count; int use_count;
@ -289,10 +293,16 @@ struct media_entity {
* *
* @graph_obj: embedded graph object * @graph_obj: embedded graph object
* @links: List of links pointing to graph entities * @links: List of links pointing to graph entities
* @type: Type of the interface as defined in the * @type: Type of the interface as defined in
* uapi/media/media.h header, e. g. * :ref:`include/uapi/linux/media.h <media_header>`
* MEDIA_INTF_T_* * (seek for ``MEDIA_INTF_T_*``)
* @flags: Interface flags as defined in uapi/media/media.h * @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_interface {
struct media_gobj graph_obj; struct media_gobj graph_obj;
@ -319,7 +329,7 @@ struct media_intf_devnode {
/** /**
* media_entity_id() - return the media entity graph object id * 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) 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 * 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) 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 * 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) 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 * media_gobj_gen_id() - encapsulates type and ID on at the object ID
* *
* @type: object type as define at enum &media_gobj_type. * @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) 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 * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
* @entity: pointer to entity * @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 * 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) 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 * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
* @entity: pointer to entity * @entity: pointer to entity
* *
* Return: true if the entity is an instance of a v4l2_subdev object and can * 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 * safely be cast to a struct &v4l2_subdev using the container_of() macro, or
* false otherwise. * %false otherwise.
*/ */
static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity) 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 * @ent_enum: Entity enumeration
* @entity: Entity to be tested * @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, static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
struct media_entity *entity) struct media_entity *entity)
@ -469,7 +479,7 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
* @ent_enum: Entity enumeration * @ent_enum: Entity enumeration
* @entity: Entity to be tested * @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 static inline bool
media_entity_enum_test_and_set(struct media_entity_enum *ent_enum, media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
@ -486,7 +496,7 @@ media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
* *
* @ent_enum: Entity enumeration * @ent_enum: Entity enumeration
* *
* Returns true if the entity was empty. * Return: %true if the entity was empty.
*/ */
static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum) static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
{ {
@ -499,7 +509,8 @@ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
* @ent_enum1: First entity enumeration * @ent_enum1: First entity enumeration
* @ent_enum2: Second 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( static inline bool media_entity_enum_intersects(
struct media_entity_enum *ent_enum1, struct media_entity_enum *ent_enum1,
@ -511,33 +522,63 @@ static inline bool media_entity_enum_intersects(
min(ent_enum1->idx_max, ent_enum2->idx_max)); 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) \ #define gobj_to_entity(gobj) \
container_of(gobj, struct media_entity, graph_obj) container_of(gobj, struct media_entity, graph_obj)
/**
* gobj_to_entity - 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) \ #define gobj_to_pad(gobj) \
container_of(gobj, struct media_pad, graph_obj) container_of(gobj, struct media_pad, graph_obj)
/**
* gobj_to_entity - 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) \ #define gobj_to_link(gobj) \
container_of(gobj, struct media_link, graph_obj) container_of(gobj, struct media_link, graph_obj)
/**
* gobj_to_entity - 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) \ #define gobj_to_intf(gobj) \
container_of(gobj, struct media_interface, graph_obj) container_of(gobj, struct media_interface, graph_obj)
/**
* gobj_to_entity - 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) \ #define intf_to_devnode(intf) \
container_of(intf, struct media_intf_devnode, intf) container_of(intf, struct media_intf_devnode, intf)
/** /**
* media_gobj_create - Initialize a graph object * 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 * @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 * This routine initializes the embedded struct &media_gobj inside a
* media graph object. It is called automatically if media_*_create\(\) * media graph object. It is called automatically if ``media_*_create``
* calls are used. However, if the object (entity, link, pad, interface) * function calls are used. However, if the object (entity, link, pad,
* is embedded on some other object, this function should be called before * interface) is embedded on some other object, this function should be
* registering the object at the media controller. * called before registering the object at the media controller.
*/ */
void media_gobj_create(struct media_device *mdev, void media_gobj_create(struct media_device *mdev,
enum media_gobj_type type, enum media_gobj_type type,
@ -546,7 +587,7 @@ void media_gobj_create(struct media_device *mdev,
/** /**
* media_gobj_destroy - Stop using a graph object on a media device * 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() * This should be called by all routines like media_device_unregister()
* that remove/destroy media graph objects. * that remove/destroy media graph objects.
@ -561,11 +602,11 @@ void media_gobj_destroy(struct media_gobj *gobj);
* @pads: Array of @num_pads pads. * @pads: Array of @num_pads pads.
* *
* The pads array is managed by the entity driver and passed to * 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 * media_entity_pads_init() where its pointer will be stored in the
* structure. * &media_entity structure.
* *
* If no pads are needed, drivers could either directly fill * 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. * this function that will do the same.
* *
* As the number of pads is known in advance, the pads array is not allocated * As the number of pads is known in advance, the pads array is not allocated
@ -595,18 +636,21 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
* @source_pad: number of the source pad in the pads array * @source_pad: number of the source pad in the pads array
* @sink: pointer to &media_entity of the sink pad. * @sink: pointer to &media_entity of the sink pad.
* @sink_pad: number of the sink pad in the pads array. * @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: * Valid values for flags:
* *
* - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can * %MEDIA_LNK_FL_ENABLED
* be used to transfer media data. When two or more links target a sink pad, * Indicates that the link is enabled and can be used to transfer media data.
* only one of them can be enabled at a time. * 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 * %MEDIA_LNK_FL_IMMUTABLE
* be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then * Indicates that the link enabled state can't be modified at runtime. If
* %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is * %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be
* always enabled. * set, since an immutable link is always enabled.
* *
* .. note:: * .. note::
* *
@ -624,17 +668,17 @@ __must_check int media_create_pad_link(struct media_entity *source,
* @source_function: Function of the source entities. Used only if @source is * @source_function: Function of the source entities. Used only if @source is
* NULL. * NULL.
* @source: pointer to &media_entity of the source pad. If NULL, it will use * @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 * @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_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 * @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. * @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 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 * In such case, it will create a crossbar between all entities that
* matches @source_function to all entities that matches @sink_function. * 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. * and @sink are NULL.
* *
* Valid values for flags: * Valid values for flags:
@ -654,9 +698,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 * creates link by link, this function is meant to allow 1:n, n:1 and even
* cross-bar (n:n) links. * cross-bar (n:n) links.
* *
* NOTE: Before calling this function, media_entity_pads_init() and * .. note::
* media_device_register_entity() should be called previously for the entities *
* to be linked. * 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, int media_create_pad_links(const struct media_device *mdev,
const u32 source_function, const u32 source_function,
@ -715,7 +761,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
* flags. * flags.
* *
* Media device drivers can be notified of link setup operations by setting the * 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 * notification callback will be called before enabling and after disabling
* links. * links.
* *
@ -725,7 +771,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 * 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 * 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. * implicitly disable the first enabled link.
* *
* .. note:: * .. note::
@ -741,8 +787,8 @@ int media_entity_setup_link(struct media_link *link, u32 flags);
* @source: Source pad * @source: Source pad
* @sink: Sink pad * @sink: Sink pad
* *
* Return a pointer to the link between the two entities. If no such link * Return: returns a pointer to the link between the two entities. If no
* exists, return NULL. * such link exists, return %NULL.
*/ */
struct media_link *media_entity_find_link(struct media_pad *source, struct media_link *media_entity_find_link(struct media_pad *source,
struct media_pad *sink); struct media_pad *sink);
@ -754,8 +800,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 * 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. * 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 * Return: returns a pointer to the pad at the remote end of the first found
* link, or NULL if no enabled link has been found. * enabled link, or %NULL if no enabled link has been found.
*/ */
struct media_pad *media_entity_remote_pad(struct media_pad *pad); struct media_pad *media_entity_remote_pad(struct media_pad *pad);
@ -766,12 +812,18 @@ struct media_pad *media_entity_remote_pad(struct media_pad *pad);
* *
* Get a reference to the parent media device module. * 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); 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( __must_check int media_entity_graph_walk_init(
struct media_entity_graph *graph, struct media_device *mdev); struct media_entity_graph *graph, struct media_device *mdev);
@ -789,12 +841,14 @@ void media_entity_graph_walk_cleanup(struct media_entity_graph *graph);
* *
* Release the reference count acquired by media_entity_get(). * 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); 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 * @graph: Media graph structure that will be used to walk the graph
* @entity: Starting entity * @entity: Starting entity
* *
@ -818,8 +872,8 @@ void media_entity_graph_walk_start(struct media_entity_graph *graph,
* The graph structure must have been previously initialized with a call to * The graph structure must have been previously initialized with a call to
* media_entity_graph_walk_start(). * media_entity_graph_walk_start().
* *
* Return the next entity in the graph or NULL if the whole graph have been * Return: returns the next entity in the graph or %NULL if the whole graph
* traversed. * have been traversed.
*/ */
struct media_entity * struct media_entity *
media_entity_graph_walk_next(struct media_entity_graph *graph); media_entity_graph_walk_next(struct media_entity_graph *graph);
@ -830,8 +884,8 @@ media_entity_graph_walk_next(struct media_entity_graph *graph);
* @pipe: Media pipeline to be assigned to all entities in the pipeline. * @pipe: Media pipeline to be assigned to all entities in the pipeline.
* *
* Mark all entities connected to a given entity through enabled links, either * Mark all entities connected to a given entity through enabled links, either
* directly or indirectly, as streaming. The given pipeline object is assigned to * directly or indirectly, as streaming. The given pipeline object is assigned
* every entity in the pipeline and stored in the media_entity pipe field. * 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 * 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 * media_entity_pipeline_stop() calls will be required to stop streaming. The
@ -857,7 +911,7 @@ __must_check int __media_entity_pipeline_start(struct media_entity *entity,
* *
* Mark all entities connected to a given entity through enabled links, either * Mark all entities connected to a given entity through enabled links, either
* directly or indirectly, as not streaming. The media_entity pipe field is * 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 * 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 * number of calls to this function are required to mark the pipeline as not
@ -878,14 +932,21 @@ void __media_entity_pipeline_stop(struct media_entity *entity);
* media_devnode_create() - creates and initializes a device node interface * media_devnode_create() - creates and initializes a device node interface
* *
* @mdev: pointer to struct &media_device * @mdev: pointer to struct &media_device
* @type: type of the interface, as given by MEDIA_INTF_T_* macros * @type: type of the interface, as given by
* as defined in the uapi/media/media.h header. * :ref:`include/uapi/linux/media.h <media_header>`
* @flags: Interface flags as defined in uapi/media/media.h. * ( 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. * @major: Device node major number.
* @minor: Device node minor number. * @minor: Device node minor number.
* *
* Return: if succeeded, returns a pointer to the newly allocated * Return: if succeeded, returns a pointer to the newly allocated
* &media_intf_devnode pointer. * &media_intf_devnode pointer.
*
* .. note::
*
* Currently, no flags for &media_interface is defined.
*/ */
struct media_intf_devnode * struct media_intf_devnode *
__must_check media_devnode_create(struct media_device *mdev, __must_check media_devnode_create(struct media_device *mdev,
@ -907,15 +968,19 @@ struct media_link *
* *
* @entity: pointer to %media_entity * @entity: pointer to %media_entity
* @intf: pointer to %media_interface * @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: * Valid values for flags:
* *
* - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to * %MEDIA_LNK_FL_ENABLED
* the entity hardware. That's the default value for interfaces. An * Indicates that the interface is connected to the entity hardware.
* interface may be disabled if the hardware is busy due to the usage * That's the default value for interfaces. An interface may be disabled if
* of some other interface that it is currently controlling the hardware. * 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 * 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, * 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 * the V4L2 interfaces won't be enabled, as such device is not able to
@ -971,6 +1036,18 @@ void __media_remove_intf_links(struct media_interface *intf);
*/ */
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...) \ #define media_entity_call(entity, operation, args...) \
(((entity)->ops && (entity)->ops->operation) ? \ (((entity)->ops && (entity)->ops->operation) ? \
(entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)