Commit 74604b73 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

[media] doc-rst: Fix conversion for MC core functions

There were lots of issues at the media controller side,
after the conversion:

- Some documentation at the header files weren't using the
  kernel-doc start block;

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- Fix the cross-references at the media controller description.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 89cb3ddb
This diff is collapsed.
...@@ -242,13 +242,11 @@ void media_device_cleanup(struct media_device *mdev); ...@@ -242,13 +242,11 @@ void media_device_cleanup(struct media_device *mdev);
* without breaking binary compatibility. The version major must be * without breaking binary compatibility. The version major must be
* incremented when binary compatibility is broken. * incremented when binary compatibility is broken.
* *
* Notes: * .. note::
* *
* Upon successful registration a character device named media[0-9]+ is created. * #) Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute.
* The device major and minor numbers are dynamic. The model name is exported as
* a sysfs attribute.
* *
* Unregistering a media device that hasn't been registered is *NOT* safe. * #) Unregistering a media device that hasn't been registered is **NOT** safe.
* *
* Return: returns zero on success or a negative error code. * Return: returns zero on success or a negative error code.
*/ */
...@@ -296,14 +294,16 @@ void media_device_unregister(struct media_device *mdev); ...@@ -296,14 +294,16 @@ void media_device_unregister(struct media_device *mdev);
* This can be used to report the default audio and video devices or the * This can be used to report the default audio and video devices or the
* default camera sensor. * default camera sensor.
* *
* NOTE: Drivers should set the entity function before calling this function. * .. note::
*
* Drivers should set the entity function before calling this function.
* Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
* %MEDIA_ENT_F_UNKNOWN should not be used by the drivers. * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
*/ */
int __must_check media_device_register_entity(struct media_device *mdev, int __must_check media_device_register_entity(struct media_device *mdev,
struct media_entity *entity); struct media_entity *entity);
/* /**
* media_device_unregister_entity() - unregisters a media entity. * media_device_unregister_entity() - unregisters a media entity.
* *
* @entity: pointer to struct &media_entity to be unregistered * @entity: pointer to struct &media_entity to be unregistered
...@@ -317,7 +317,9 @@ int __must_check media_device_register_entity(struct media_device *mdev, ...@@ -317,7 +317,9 @@ int __must_check media_device_register_entity(struct media_device *mdev,
* When a media device is unregistered, all its entities are unregistered * When a media device is unregistered, all its entities are unregistered
* automatically. No manual entities unregistration is then required. * automatically. No manual entities unregistration is then required.
* *
* Note: the media_entity instance itself must be freed explicitly by * .. note::
*
* The media_entity instance itself must be freed explicitly by
* the driver if required. * the driver if required.
*/ */
void media_device_unregister_entity(struct media_entity *entity); void media_device_unregister_entity(struct media_entity *entity);
......
...@@ -104,7 +104,7 @@ struct media_entity_graph { ...@@ -104,7 +104,7 @@ struct media_entity_graph {
int top; int top;
}; };
/* /**
* struct media_pipeline - Media pipeline related information * struct media_pipeline - Media pipeline related information
* *
* @streaming_count: Streaming start count - streaming stop count * @streaming_count: Streaming start count - streaming stop count
...@@ -180,7 +180,7 @@ struct media_pad { ...@@ -180,7 +180,7 @@ struct media_pad {
* view. The media_entity_pipeline_start() function * view. The media_entity_pipeline_start() function
* validates all links by calling this operation. Optional. * validates all links by calling this operation. Optional.
* *
* Note: Those these callbacks are called with struct media_device.@graph_mutex * .. note:: Those these callbacks are called with struct media_device.@graph_mutex
* mutex held. * mutex held.
*/ */
struct media_entity_operations { struct media_entity_operations {
...@@ -602,16 +602,17 @@ static inline void media_entity_cleanup(struct media_entity *entity) {}; ...@@ -602,16 +602,17 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
* @flags: Link flags, as defined in include/uapi/linux/media.h. * @flags: Link flags, as defined in include/uapi/linux/media.h.
* *
* Valid values for flags: * 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, * - 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. * only one of them can be enabled at a time.
* *
* A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't * - 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 * 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 * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
* always enabled. * always enabled.
* *
* NOTE: * .. note::
* *
* Before calling this function, media_entity_pads_init() and * Before calling this function, media_entity_pads_init() and
* media_device_register_entity() should be called previously for both ends. * media_device_register_entity() should be called previously for both ends.
...@@ -641,6 +642,7 @@ __must_check int media_create_pad_link(struct media_entity *source, ...@@ -641,6 +642,7 @@ __must_check int media_create_pad_link(struct media_entity *source,
* and @sink are NULL. * and @sink are NULL.
* *
* Valid values for flags: * Valid values for flags:
*
* A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
* used to transfer media data. If multiple links are created and this * used to transfer media data. If multiple links are created and this
* flag is passed as an argument, only the first created link will have * flag is passed as an argument, only the first created link will have
...@@ -677,7 +679,9 @@ void __media_entity_remove_links(struct media_entity *entity); ...@@ -677,7 +679,9 @@ void __media_entity_remove_links(struct media_entity *entity);
* *
* @entity: pointer to &media_entity * @entity: pointer to &media_entity
* *
* Note: this is called automatically when an entity is unregistered via * .. note::
*
* This is called automatically when an entity is unregistered via
* media_device_register_entity(). * media_device_register_entity().
*/ */
void media_entity_remove_links(struct media_entity *entity); void media_entity_remove_links(struct media_entity *entity);
...@@ -728,7 +732,9 @@ int __media_entity_setup_link(struct media_link *link, u32 flags); ...@@ -728,7 +732,9 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
* 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: the valid values of the flags for the link is the same as described * .. note::
*
* The valid values of the flags for the link is the same as described
* on media_create_pad_link(), for pad to pad links or the same as described * on media_create_pad_link(), for pad to pad links or the same as described
* on media_create_intf_link(), for interface to entity links. * on media_create_intf_link(), for interface to entity links.
*/ */
...@@ -844,7 +850,7 @@ __must_check int media_entity_pipeline_start(struct media_entity *entity, ...@@ -844,7 +850,7 @@ __must_check int media_entity_pipeline_start(struct media_entity *entity,
* @entity: Starting entity * @entity: Starting entity
* @pipe: Media pipeline to be assigned to all entities in the pipeline. * @pipe: Media pipeline to be assigned to all entities in the pipeline.
* *
* Note: This is the non-locking version of media_entity_pipeline_start() * ..note:: This is the non-locking version of media_entity_pipeline_start()
*/ */
__must_check int __media_entity_pipeline_start(struct media_entity *entity, __must_check int __media_entity_pipeline_start(struct media_entity *entity,
struct media_pipeline *pipe); struct media_pipeline *pipe);
...@@ -868,7 +874,7 @@ void media_entity_pipeline_stop(struct media_entity *entity); ...@@ -868,7 +874,7 @@ void media_entity_pipeline_stop(struct media_entity *entity);
* *
* @entity: Starting entity * @entity: Starting entity
* *
* Note: This is the non-locking version of media_entity_pipeline_stop() * .. note:: This is the non-locking version of media_entity_pipeline_stop()
*/ */
void __media_entity_pipeline_stop(struct media_entity *entity); void __media_entity_pipeline_stop(struct media_entity *entity);
...@@ -909,7 +915,8 @@ struct media_link * ...@@ -909,7 +915,8 @@ struct media_link *
* *
* *
* Valid values for flags: * Valid values for flags:
* The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to *
* - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
* the entity hardware. That's the default value for interfaces. An * the entity hardware. That's the default value for interfaces. An
* interface may be disabled if the hardware is busy due to the usage * interface may be disabled if the hardware is busy due to the usage
* of some other interface that it is currently controlling the hardware. * of some other interface that it is currently controlling the hardware.
...@@ -918,7 +925,7 @@ struct media_link * ...@@ -918,7 +925,7 @@ struct media_link *
* 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
* also stream analog TV or radio. * also stream analog TV or radio.
* *
* Note: * .. note::
* *
* Before calling this function, media_devnode_create() should be called for * Before calling this function, media_devnode_create() should be called for
* the interface and media_device_register_entity() should be called for the * the interface and media_device_register_entity() should be called for the
...@@ -932,7 +939,7 @@ __must_check media_create_intf_link(struct media_entity *entity, ...@@ -932,7 +939,7 @@ __must_check media_create_intf_link(struct media_entity *entity,
* *
* @link: pointer to &media_link. * @link: pointer to &media_link.
* *
* Note: this is an unlocked version of media_remove_intf_link() * .. note:: This is an unlocked version of media_remove_intf_link()
*/ */
void __media_remove_intf_link(struct media_link *link); void __media_remove_intf_link(struct media_link *link);
...@@ -941,7 +948,7 @@ void __media_remove_intf_link(struct media_link *link); ...@@ -941,7 +948,7 @@ void __media_remove_intf_link(struct media_link *link);
* *
* @link: pointer to &media_link. * @link: pointer to &media_link.
* *
* Note: prefer to use this one, instead of __media_remove_intf_link() * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
*/ */
void media_remove_intf_link(struct media_link *link); void media_remove_intf_link(struct media_link *link);
...@@ -950,7 +957,7 @@ void media_remove_intf_link(struct media_link *link); ...@@ -950,7 +957,7 @@ void media_remove_intf_link(struct media_link *link);
* *
* @intf: pointer to &media_interface * @intf: pointer to &media_interface
* *
* Note: this is an unlocked version of media_remove_intf_links(). * .. note:: This is an unlocked version of media_remove_intf_links().
*/ */
void __media_remove_intf_links(struct media_interface *intf); void __media_remove_intf_links(struct media_interface *intf);
...@@ -959,12 +966,12 @@ void __media_remove_intf_links(struct media_interface *intf); ...@@ -959,12 +966,12 @@ void __media_remove_intf_links(struct media_interface *intf);
* *
* @intf: pointer to &media_interface * @intf: pointer to &media_interface
* *
* Notes: * ..note::
* *
* this is called automatically when an entity is unregistered via * - This is called automatically when an entity is unregistered via
* media_device_register_entity() and by media_devnode_remove(). * media_device_register_entity() and by media_devnode_remove().
* *
* Prefer to use this one, instead of __media_remove_intf_links(). * - Prefer to use this one, instead of __media_remove_intf_links().
*/ */
void media_remove_intf_links(struct media_interface *intf); void media_remove_intf_links(struct media_interface *intf);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment