summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2016-07-28 00:58:31 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2016-07-28 00:58:31 +0300
commitff9a082fda424257976f08fce942609f358015e0 (patch)
tree478e6b449b19baaf842369a13923499ce83ef895 /include
parent6a492b0f23d28e1f946cdf08e54617484400dafb (diff)
parent85538b1ad145c67198cb55d02de14ba269cc323d (diff)
downloadlinux-ff9a082fda424257976f08fce942609f358015e0.tar.xz
Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media documentation updates from Mauro Carvalho Chehab: "This patch series does the conversion of all media documentation stuff to Restrutured Text markup format and add them to the Documentation/index.rst file. The media documentation was grouped into 4 books: - media uAPI - media kAPI - V4L driver-specific documentation - DVB driver-specific documentation It also contains several documentation improvements and one fixup patch for a core issue with cropcap. PS. After this patch series, the media DocBook is deprecated and should be removed. I'll add such patch on a future pull request" * tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits) [media] cx23885-cardlist.rst: add a new card [media] doc-rst: add some needed escape codes [media] doc-rst: kapi: use :c:func: instead of :cpp:func doc-rst: kernel-doc: fix a change introduced by mistake [media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops [media] dvb_ringbuffer.h: some documentation improvements [media] v4l2-ctrls.h: fully document the header file [media] doc-rst: Fix some typedef ugly warnings [media] doc-rst: reorganize the kAPI v4l2 chapters [media] rename v4l2-framework.rst to v4l2-intro.rst [media] move V4L2 clocks to a separate .rst file [media] v4l2-fh.rst: add cross references and markups [media] v4l2-fh.rst: add fh contents from v4l2-framework.rst [media] v4l2-fh.h: add documentation for it [media] v4l2-event.rst: add cross-references and markups [media] v4l2-event.h: document all functions [media] v4l2-event.rst: add text from v4l2-framework.rst [media] v4l2-framework.rst: remove videobuf quick chapter [media] v4l2-dev: add cross-references and improve markup [media] doc-rst: move v4l2-dev doc to a separate file ...
Diffstat (limited to 'include')
-rw-r--r--include/media/lirc_dev.h2
-rw-r--r--include/media/media-device.h255
-rw-r--r--include/media/media-entity.h89
-rw-r--r--include/media/rc-core.h45
-rw-r--r--include/media/rc-map.h17
-rw-r--r--include/media/tuner-types.h8
-rw-r--r--include/media/tveeprom.h18
-rw-r--r--include/media/v4l2-async.h39
-rw-r--r--include/media/v4l2-common.h92
-rw-r--r--include/media/v4l2-ctrls.h369
-rw-r--r--include/media/v4l2-dev.h364
-rw-r--r--include/media/v4l2-device.h198
-rw-r--r--include/media/v4l2-dv-timings.h2
-rw-r--r--include/media/v4l2-event.h125
-rw-r--r--include/media/v4l2-fh.h128
-rw-r--r--include/media/v4l2-ioctl.h266
-rw-r--r--include/media/v4l2-mc.h13
-rw-r--r--include/media/v4l2-subdev.h576
-rw-r--r--include/media/videobuf2-core.h74
-rw-r--r--include/uapi/linux/lirc.h39
20 files changed, 1913 insertions, 806 deletions
diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index 0ab59a571fee..cec7d35602d1 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -140,7 +140,7 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf,
* second.
*
* @features: lirc compatible hardware features, like LIRC_MODE_RAW,
- * LIRC_CAN_*, as defined at include/media/lirc.h.
+ * LIRC_CAN\_\*, as defined at include/media/lirc.h.
*
* @chunk_size: Size of each FIFO buffer.
*
diff --git a/include/media/media-device.h b/include/media/media-device.h
index f743ae2210ee..28195242386c 100644
--- a/include/media/media-device.h
+++ b/include/media/media-device.h
@@ -29,237 +29,6 @@
#include <media/media-devnode.h>
#include <media/media-entity.h>
-/**
- * DOC: Media Controller
- *
- * The media controller userspace API is documented in DocBook format in
- * Documentation/DocBook/media/v4l/media-controller.xml. This document focus
- * on the kernel-side implementation of the media framework.
- *
- * * Abstract media device model:
- *
- * Discovering a device internal topology, and configuring it at runtime, is one
- * of the goals of the media framework. To achieve this, hardware devices are
- * modelled as an oriented graph of building blocks called entities connected
- * through pads.
- *
- * An entity is a basic media hardware building block. It can correspond to
- * a large variety of logical blocks such as physical hardware devices
- * (CMOS sensor for instance), logical hardware devices (a building block
- * in a System-on-Chip image processing pipeline), DMA channels or physical
- * connectors.
- *
- * A pad is a connection endpoint through which an entity can interact with
- * other entities. Data (not restricted to video) produced by an entity
- * flows from the entity's output to one or more entity inputs. Pads should
- * not be confused with physical pins at chip boundaries.
- *
- * A link is a point-to-point oriented connection between two pads, either
- * on the same entity or on different entities. Data flows from a source
- * pad to a sink pad.
- *
- *
- * * Media device:
- *
- * A media device is represented by a struct &media_device instance, defined in
- * include/media/media-device.h. Allocation of the structure is handled by the
- * media device driver, usually by embedding the &media_device instance in a
- * larger driver-specific structure.
- *
- * Drivers register media device instances by calling
- * __media_device_register() via the macro media_device_register()
- * and unregistered by calling
- * media_device_unregister().
- *
- * * Entities, pads and links:
- *
- * - Entities
- *
- * Entities are represented by a struct &media_entity instance, defined in
- * include/media/media-entity.h. The structure is usually embedded into a
- * higher-level structure, such as a v4l2_subdev or video_device instance,
- * although drivers can allocate entities directly.
- *
- * Drivers initialize entity pads by calling
- * media_entity_pads_init().
- *
- * Drivers register entities with a media device by calling
- * media_device_register_entity()
- * and unregistred by calling
- * media_device_unregister_entity().
- *
- * - Interfaces
- *
- * Interfaces are represented by a struct &media_interface instance, defined in
- * include/media/media-entity.h. Currently, only one type of interface is
- * defined: a device node. Such interfaces are represented by a struct
- * &media_intf_devnode.
- *
- * Drivers initialize and create device node interfaces by calling
- * media_devnode_create()
- * and remove them by calling:
- * media_devnode_remove().
- *
- * - Pads
- *
- * Pads are represented by a struct &media_pad instance, defined in
- * include/media/media-entity.h. Each entity stores its pads in a pads array
- * managed by the entity driver. Drivers usually embed the array in a
- * driver-specific structure.
- *
- * Pads are identified by their entity and their 0-based index in the pads
- * array.
- * Both information are stored in the &media_pad structure, making the
- * &media_pad pointer the canonical way to store and pass link references.
- *
- * Pads have flags that describe the pad capabilities and state.
- *
- * %MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
- * %MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
- *
- * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
- * be set for each pad.
- *
- * - Links
- *
- * Links are represented by a struct &media_link instance, defined in
- * include/media/media-entity.h. There are two types of links:
- *
- * 1. pad to pad links:
- *
- * Associate two entities via their PADs. Each entity has a list that points
- * to all links originating at or targeting any of its pads.
- * A given link is thus stored twice, once in the source entity and once in
- * the target entity.
- *
- * Drivers create pad to pad links by calling:
- * media_create_pad_link() and remove with media_entity_remove_links().
- *
- * 2. interface to entity links:
- *
- * Associate one interface to a Link.
- *
- * Drivers create interface to entity links by calling:
- * media_create_intf_link() and remove with media_remove_intf_links().
- *
- * NOTE:
- *
- * Links can only be created after having both ends already created.
- *
- * Links have flags that describe the link capabilities and state. The
- * valid values are described at media_create_pad_link() and
- * media_create_intf_link().
- *
- * Graph traversal:
- *
- * The media framework provides APIs to iterate over entities in a graph.
- *
- * To iterate over all entities belonging to a media device, drivers can use
- * the media_device_for_each_entity macro, defined in
- * include/media/media-device.h.
- *
- * struct media_entity *entity;
- *
- * media_device_for_each_entity(entity, mdev) {
- * // entity will point to each entity in turn
- * ...
- * }
- *
- * Drivers might also need to iterate over all entities in a graph that can be
- * reached only through enabled links starting at a given entity. The media
- * framework provides a depth-first graph traversal API for that purpose.
- *
- * Note that graphs with cycles (whether directed or undirected) are *NOT*
- * supported by the graph traversal API. To prevent infinite loops, the graph
- * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
- * currently defined as 16.
- *
- * Drivers initiate a graph traversal by calling
- * media_entity_graph_walk_start()
- *
- * The graph structure, provided by the caller, is initialized to start graph
- * traversal at the given entity.
- *
- * Drivers can then retrieve the next entity by calling
- * media_entity_graph_walk_next()
- *
- * When the graph traversal is complete the function will return NULL.
- *
- * Graph traversal can be interrupted at any moment. No cleanup function call
- * is required and the graph structure can be freed normally.
- *
- * Helper functions can be used to find a link between two given pads, or a pad
- * connected to another pad through an enabled link
- * media_entity_find_link() and media_entity_remote_pad()
- *
- * Use count and power handling:
- *
- * Due to the wide differences between drivers regarding power management
- * needs, the media controller does not implement power management. However,
- * the &media_entity structure includes a use_count field that media drivers
- * can use to track the number of users of every entity for power management
- * needs.
- *
- * The &media_entity.@use_count field is owned by media drivers and must not be
- * touched by entity drivers. Access to the field must be protected by the
- * &media_device.@graph_mutex lock.
- *
- * Links setup:
- *
- * Link properties can be modified at runtime by calling
- * media_entity_setup_link()
- *
- * Pipelines and media streams:
- *
- * When starting streaming, drivers must notify all entities in the pipeline to
- * prevent link states from being modified during streaming by calling
- * media_entity_pipeline_start().
- *
- * The function will mark all entities connected to the given entity through
- * enabled links, either directly or indirectly, as streaming.
- *
- * The &media_pipeline instance pointed to by the pipe argument will be stored
- * in every entity in the pipeline. Drivers should embed the &media_pipeline
- * structure in higher-level pipeline structures and can then access the
- * pipeline through the &media_entity pipe field.
- *
- * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
- * must be identical for all nested calls to the function.
- *
- * media_entity_pipeline_start() may return an error. In that case, it will
- * clean up any of the changes it did by itself.
- *
- * When stopping the stream, drivers must notify the entities with
- * media_entity_pipeline_stop().
- *
- * If multiple calls to media_entity_pipeline_start() have been made the same
- * number of media_entity_pipeline_stop() calls are required to stop streaming.
- * The &media_entity pipe field is reset to NULL on the last nested stop call.
- *
- * Link configuration will fail with -%EBUSY by default if either end of the
- * link is a streaming entity. Links that can be modified while streaming must
- * be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
- *
- * If other operations need to be disallowed on streaming entities (such as
- * changing entities configuration parameters) drivers can explicitly check the
- * media_entity stream_count field to find out if an entity is streaming. This
- * operation must be done with the media_device graph_mutex held.
- *
- * Link validation:
- *
- * Link validation is performed by media_entity_pipeline_start() for any
- * entity which has sink pads in the pipeline. The
- * &media_entity.@link_validate() callback is used for that purpose. In
- * @link_validate() callback, entity driver should check that the properties of
- * the source pad of the connected entity and its own sink pad match. It is up
- * to the type of the entity (and in the end, the properties of the hardware)
- * what matching actually means.
- *
- * Subsystems should facilitate link validation by providing subsystem specific
- * helper functions to provide easy access for commonly needed information, and
- * in the end provide a way to use driver-specific callbacks.
- */
-
struct ida;
struct device;
@@ -473,13 +242,11 @@ void media_device_cleanup(struct media_device *mdev);
* without breaking binary compatibility. The version major must be
* incremented when binary compatibility is broken.
*
- * Notes:
+ * .. note::
*
- * 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.
+ * #) 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.
*
- * 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.
*/
@@ -527,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
* default camera sensor.
*
- * NOTE: Drivers should set the entity function before calling this function.
- * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
- * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
+ * .. note::
+ *
+ * Drivers should set the entity function before calling this function.
+ * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
+ * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
*/
int __must_check media_device_register_entity(struct media_device *mdev,
struct media_entity *entity);
-/*
+/**
* media_device_unregister_entity() - unregisters a media entity.
*
* @entity: pointer to struct &media_entity to be unregistered
@@ -548,8 +317,10 @@ int __must_check media_device_register_entity(struct media_device *mdev,
* When a media device is unregistered, all its entities are unregistered
* automatically. No manual entities unregistration is then required.
*
- * Note: the media_entity instance itself must be freed explicitly by
- * the driver if required.
+ * .. note::
+ *
+ * The media_entity instance itself must be freed explicitly by
+ * the driver if required.
*/
void media_device_unregister_entity(struct media_entity *entity);
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index cbb266f7f2b5..09b03c17784d 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -104,7 +104,7 @@ struct media_entity_graph {
int top;
};
-/*
+/**
* struct media_pipeline - Media pipeline related information
*
* @streaming_count: Streaming start count - streaming stop count
@@ -180,8 +180,10 @@ struct media_pad {
* view. The media_entity_pipeline_start() function
* validates all links by calling this operation. Optional.
*
- * Note: Those these callbacks are called with struct media_device.@graph_mutex
- * mutex held.
+ * .. note::
+ *
+ * Those these callbacks are called with struct media_device.@graph_mutex
+ * mutex held.
*/
struct media_entity_operations {
int (*link_setup)(struct media_entity *entity,
@@ -538,7 +540,7 @@ static inline bool media_entity_enum_intersects(
* @gobj: Pointer to the graph object
*
* 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)
* is embedded on some other object, this function should be called before
* registering the object at the media controller.
@@ -602,19 +604,20 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
* @flags: Link flags, as defined in include/uapi/linux/media.h.
*
* 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,
- * only one of them can be enabled at a time.
*
- * 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
- * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
- * always enabled.
+ * - 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.
+ *
+ * - 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
+ * %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
+ * always enabled.
*
- * NOTE:
+ * .. note::
*
- * Before calling this function, media_entity_pads_init() and
- * media_device_register_entity() should be called previously for both ends.
+ * Before calling this function, media_entity_pads_init() and
+ * media_device_register_entity() should be called previously for both ends.
*/
__must_check int media_create_pad_link(struct media_entity *source,
u16 source_pad, struct media_entity *sink,
@@ -641,6 +644,7 @@ __must_check int media_create_pad_link(struct media_entity *source,
* and @sink are NULL.
*
* Valid values for flags:
+ *
* 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
* flag is passed as an argument, only the first created link will have
@@ -677,8 +681,10 @@ void __media_entity_remove_links(struct media_entity *entity);
*
* @entity: pointer to &media_entity
*
- * Note: this is called automatically when an entity is unregistered via
- * media_device_register_entity().
+ * .. note::
+ *
+ * This is called automatically when an entity is unregistered via
+ * media_device_register_entity().
*/
void media_entity_remove_links(struct media_entity *entity);
@@ -728,9 +734,11 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
* being enabled, the link_setup operation must return -EBUSY and can't
* implicitly disable the first enabled link.
*
- * 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_intf_link(), for interface to entity links.
+ * .. 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_intf_link(), for interface to entity links.
*/
int media_entity_setup_link(struct media_link *link, u32 flags);
@@ -844,7 +852,7 @@ __must_check int media_entity_pipeline_start(struct media_entity *entity,
* @entity: Starting entity
* @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,
struct media_pipeline *pipe);
@@ -868,7 +876,7 @@ void media_entity_pipeline_stop(struct media_entity *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);
@@ -909,20 +917,21 @@ struct media_link *
*
*
* Valid values for flags:
- * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
- * the entity hardware. That's the default value for interfaces. An
- * interface may be disabled if 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
- * 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
- * also stream analog TV or radio.
*
- * Note:
+ * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
+ * the entity hardware. That's the default value for interfaces. An
+ * interface may be disabled if 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
+ * 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
+ * also stream analog TV or radio.
+ *
+ * .. note::
*
- * Before calling this function, media_devnode_create() should be called for
- * the interface and media_device_register_entity() should be called for the
- * interface that will be part of the link.
+ * Before calling this function, media_devnode_create() should be called for
+ * the interface and media_device_register_entity() should be called for the
+ * interface that will be part of the link.
*/
__must_check media_create_intf_link(struct media_entity *entity,
struct media_interface *intf,
@@ -932,7 +941,7 @@ __must_check media_create_intf_link(struct media_entity *entity,
*
* @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);
@@ -941,7 +950,7 @@ void __media_remove_intf_link(struct media_link *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);
@@ -950,7 +959,7 @@ void media_remove_intf_link(struct media_link *link);
*
* @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);
@@ -959,12 +968,12 @@ void __media_remove_intf_links(struct media_interface *intf);
*
* @intf: pointer to &media_interface
*
- * Notes:
+ * .. note::
*
- * this is called automatically when an entity is unregistered via
- * media_device_register_entity() and by media_devnode_remove().
+ * #) This is called automatically when an entity is unregistered via
+ * 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);
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index 324232cfc08d..10908e356b23 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -29,9 +29,16 @@ do { \
printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__); \
} while (0)
+/**
+ * enum rc_driver_type - type of the RC output
+ *
+ * @RC_DRIVER_SCANCODE: Driver or hardware generates a scancode
+ * @RC_DRIVER_IR_RAW: Driver or hardware generates pulse/space sequences.
+ * It needs a Infra-Red pulse/space decoder
+ */
enum rc_driver_type {
- RC_DRIVER_SCANCODE = 0, /* Driver or hardware generates a scancode */
- RC_DRIVER_IR_RAW, /* Needs a Infra-Red pulse/space decoder */
+ RC_DRIVER_SCANCODE = 0,
+ RC_DRIVER_IR_RAW,
};
/**
@@ -188,12 +195,46 @@ struct rc_dev {
* Remote Controller, at sys/class/rc.
*/
+/**
+ * rc_allocate_device - Allocates a RC device
+ *
+ * returns a pointer to struct rc_dev.
+ */
struct rc_dev *rc_allocate_device(void);
+
+/**
+ * rc_free_device - Frees a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
void rc_free_device(struct rc_dev *dev);
+
+/**
+ * rc_register_device - Registers a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
int rc_register_device(struct rc_dev *dev);
+
+/**
+ * rc_unregister_device - Unregisters a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
void rc_unregister_device(struct rc_dev *dev);
+/**
+ * rc_open - Opens a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
int rc_open(struct rc_dev *rdev);
+
+/**
+ * rc_open - Closes a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
void rc_close(struct rc_dev *rdev);
void rc_repeat(struct rc_dev *dev);
diff --git a/include/media/rc-map.h b/include/media/rc-map.h
index a459129dd554..daa75fcc1ff1 100644
--- a/include/media/rc-map.h
+++ b/include/media/rc-map.h
@@ -98,10 +98,25 @@ struct rc_map_list {
/* Routines from rc-map.c */
+/**
+ * rc_map_register() - Registers a Remote Controler scancode map
+ *
+ * @map: pointer to struct rc_map_list
+ */
int rc_map_register(struct rc_map_list *map);
+
+/**
+ * rc_map_unregister() - Unregisters a Remote Controler scancode map
+ *
+ * @map: pointer to struct rc_map_list
+ */
void rc_map_unregister(struct rc_map_list *map);
+
+/**
+ * rc_map_get - gets an RC map from its name
+ * @name: name of the RC scancode map
+ */
struct rc_map *rc_map_get(const char *name);
-void rc_map_init(void);
/* Names of the several keytables defined in-kernel */
diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index 094e112cc325..aed539068d2d 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -35,8 +35,12 @@ enum param_type {
* those ranges, as they're defined inside the driver. This is used by
* analog tuners that are compatible with the "Philips way" to setup the
* tuners. On those devices, the tuner set is done via 4 bytes:
- * divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
- * band switch byte (BB).
+ *
+ * #) divider byte1 (DB1)
+ * #) divider byte 2 (DB2)
+ * #) Control byte (CB)
+ * #) band switch byte (BB)
+ *
* Some tuners also have an additional optional Auxiliary byte (AB).
*/
struct tuner_range {
diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h
index 8be898739e0c..c56501ee0484 100644
--- a/include/media/tveeprom.h
+++ b/include/media/tveeprom.h
@@ -27,31 +27,43 @@ enum tveeprom_audio_processor {
* struct tveeprom - Contains the fields parsed from Hauppauge eeproms
*
* @has_radio: 1 if the device has radio; 0 otherwise.
+ *
* @has_ir: If has_ir == 0, then it is unknown what the IR
* capabilities are. Otherwise:
- * bit 0) 1 (= IR capabilities are known);
- * bit 1) IR receiver present;
- * bit 2) IR transmitter (blaster) present.
+ * bit 0) 1 (= IR capabilities are known);
+ * bit 1) IR receiver present;
+ * bit 2) IR transmitter (blaster) present.
+ *
* @has_MAC_address: 0: no MAC, 1: MAC present, 2: unknown.
* @tuner_type: type of the tuner (TUNER_*, as defined at
* include/media/tuner.h).
+ *
* @tuner_formats: Supported analog TV standards (V4L2_STD_*).
* @tuner_hauppauge_model: Hauppauge's code for the device model number.
* @tuner2_type: type of the second tuner (TUNER_*, as defined
* at include/media/tuner.h).
+ *
* @tuner2_formats: Tuner 2 supported analog TV standards
* (V4L2_STD_*).
+ *
* @tuner2_hauppauge_model: tuner 2 Hauppauge's code for the device model
* number.
+ *
* @audio_processor: analog audio decoder, as defined by enum
* tveeprom_audio_processor.
+ *
* @decoder_processor: Hauppauge's code for the decoder chipset.
* Unused by the drivers, as they probe the
* decoder based on the PCI or USB ID.
+ *
* @model: Hauppauge's model number
+ *
* @revision: Card revision number
+ *
* @serial_number: Card's serial number
+ *
* @rev_str: Card revision converted to number
+ *
* @MAC_address: MAC address for the network interface
*/
struct tveeprom {
diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h
index 1d6d7da4c45d..8e2a236a4d03 100644
--- a/include/media/v4l2-async.h
+++ b/include/media/v4l2-async.h
@@ -23,6 +23,19 @@ struct v4l2_async_notifier;
/* A random max subdevice number, used to allocate an array on stack */
#define V4L2_MAX_SUBDEVS 128U
+/**
+ * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
+ * in order to identify a match
+ *
+ * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
+ * v4l2_async_subdev.match ops
+ * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
+ * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
+ * @V4L2_ASYNC_MATCH_OF: Match will use OF node
+ *
+ * This enum is used by the asyncrhronous sub-device logic to define the
+ * algorithm that will be used to match an asynchronous device.
+ */
enum v4l2_async_match_type {
V4L2_ASYNC_MATCH_CUSTOM,
V4L2_ASYNC_MATCH_DEVNAME,
@@ -91,9 +104,35 @@ struct v4l2_async_notifier {
struct v4l2_async_subdev *asd);
};
+/**
+ * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
+ *
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_register_subdev - registers a sub-device to the asynchronous
+ * subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
int v4l2_async_register_subdev(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
+ * subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
#endif
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 1cc0c5ba16b3..350cbf9fb10e 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -78,11 +78,26 @@
v4l2_printk(KERN_DEBUG, dev, fmt , ## arg); \
} while (0)
-/* ------------------------------------------------------------------------- */
-
-/* Control helper function */
+/**
+ * v4l2_ctrl_query_fill- Fill in a struct v4l2_queryctrl
+ *
+ * @qctrl: pointer to the &struct v4l2_queryctrl to be filled
+ * @min: minimum value for the control
+ * @max: maximum value for the control
+ * @step: control step
+ * @def: default value for the control
+ *
+ * Fills the &struct v4l2_queryctrl fields for the query control.
+ *
+ * .. note::
+ *
+ * This function assumes that the @qctrl->id field is filled.
+ *
+ * Returns -EINVAL if the control is not known by the V4L2 core, 0 on success.
+ */
-int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def);
+int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl,
+ s32 min, s32 max, s32 step, s32 def);
/* ------------------------------------------------------------------------- */
@@ -96,23 +111,60 @@ struct v4l2_device;
struct v4l2_subdev;
struct v4l2_subdev_ops;
-
-/* Load an i2c module and return an initialized v4l2_subdev struct.
- The client_type argument is the name of the chip that's on the adapter. */
+/**
+ * v4l2_i2c_new_subdev - Load an i2c module and return an initialized
+ * &struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @client_type: name of the chip that's on the adapter.
+ * @addr: I2C address. If zero, it will use @probe_addrs
+ * @probe_addrs: array with a list of address. The last entry at such
+ * array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev,
struct i2c_adapter *adapter, const char *client_type,
u8 addr, const unsigned short *probe_addrs);
struct i2c_board_info;
+/**
+ * v4l2_i2c_new_subdev_board - Load an i2c module and return an initialized
+ * &struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @info: pointer to struct i2c_board_info used to replace the irq,
+ * platform_data and addr arguments.
+ * @probe_addrs: array with a list of address. The last entry at such
+ * array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev,
struct i2c_adapter *adapter, struct i2c_board_info *info,
const unsigned short *probe_addrs);
-/* Initialize a v4l2_subdev with data from an i2c_client struct */
+/**
+ * v4l2_i2c_subdev_init - Initializes a &struct v4l2_subdev with data from
+ * an i2c_client struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @client: pointer to struct i2c_client
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
const struct v4l2_subdev_ops *ops);
-/* Return i2c client address of v4l2_subdev. */
+
+/**
+ * v4l2_i2c_subdev_addr - returns i2c client address of &struct v4l2_subdev.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the address of an I2C sub-device
+ */
unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd);
enum v4l2_i2c_tuner_type {
@@ -137,12 +189,28 @@ const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type);
struct spi_device;
-/* Load an spi module and return an initialized v4l2_subdev struct.
- The client_type argument is the name of the chip that's on the adapter. */
+/**
+ * v4l2_spi_new_subdev - Load an spi module and return an initialized
+ * &struct v4l2_subdev.
+ *
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device.
+ * @master: pointer to struct spi_master.
+ * @info: pointer to struct spi_board_info.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev,
struct spi_master *master, struct spi_board_info *info);
-/* Initialize a v4l2_subdev with data from an spi_device struct */
+/**
+ * v4l2_spi_subdev_init - Initialize a v4l2_subdev with data from an
+ * spi_device struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @spi: pointer to struct spi_device.
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi,
const struct v4l2_subdev_ops *ops);
#endif
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 8b59336b2217..178a88d45aea 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -1,21 +1,17 @@
/*
- V4L2 controls support header.
-
- Copyright (C) 2010 Hans Verkuil <hverkuil@xs4all.nl>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ * V4L2 controls support header.
+ *
+ * Copyright (C) 2010 Hans Verkuil <hverkuil@xs4all.nl>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
*/
#ifndef _V4L2_CTRLS_H
@@ -58,6 +54,7 @@ union v4l2_ctrl_ptr {
/**
* struct v4l2_ctrl_ops - The control operations that the driver has to provide.
+ *
* @g_volatile_ctrl: Get a new value for this control. Generally only relevant
* for volatile (and usually read-only) controls such as a control
* that returns the current signal strength which changes
@@ -77,12 +74,13 @@ struct v4l2_ctrl_ops {
/**
* struct v4l2_ctrl_type_ops - The control type operations that the driver
- * has to provide.
+ * has to provide.
*
* @equal: return true if both values are equal.
* @init: initialize the value.
* @log: log the value.
- * @validate: validate the value. Return 0 on success and a negative value otherwise.
+ * @validate: validate the value. Return 0 on success and a negative value
+ * otherwise.
*/
struct v4l2_ctrl_type_ops {
bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
@@ -99,6 +97,7 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
/**
* struct v4l2_ctrl - The control structure.
+ *
* @node: The list node.
* @ev_subs: The list of control event subscriptions.
* @handler: The handler that owns the control.
@@ -106,7 +105,7 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
* @ncontrols: Number of controls in cluster array.
* @done: Internal flag: set for each processed control.
* @is_new: Set when the user specified a new value for this control. It
- * is also set when called from v4l2_ctrl_handler_setup. Drivers
+ * is also set when called from v4l2_ctrl_handler_setup(). Drivers
* should never set this flag.
* @has_changed: Set when the current value differs from the new value. Drivers
* should never use this flag.
@@ -119,9 +118,10 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
* set this flag directly.
* @is_int: If set, then this control has a simple integer value (i.e. it
* uses ctrl->val).
- * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING.
- * @is_ptr: If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES
- * and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct
+ * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
+ * @is_ptr: If set, then this control is an array and/or has type >=
+ * %V4L2_CTRL_COMPOUND_TYPES
+ * and/or has type %V4L2_CTRL_TYPE_STRING. In other words, &struct
* v4l2_ext_control uses field p to point to the data.
* @is_array: If set, then this control contains an N-dimensional array.
* @has_volatiles: If set, then one or more members of the cluster are volatile.
@@ -177,7 +177,8 @@ struct v4l2_ctrl {
struct list_head ev_subs;
struct v4l2_ctrl_handler *handler;
struct v4l2_ctrl **cluster;
- unsigned ncontrols;
+ unsigned int ncontrols;
+
unsigned int done:1;
unsigned int is_new:1;
@@ -223,10 +224,12 @@ struct v4l2_ctrl {
/**
* struct v4l2_ctrl_ref - The control reference.
+ *
* @node: List node for the sorted list.
* @next: Single-link list node for the hash.
* @ctrl: The actual control information.
- * @helper: Pointer to helper struct. Used internally in prepare_ext_ctrls().
+ * @helper: Pointer to helper struct. Used internally in
+ * prepare_ext_ctrls().
*
* Each control handler has a list of these refs. The list_head is used to
* keep a sorted-by-control-ID list of all controls, while the next pointer
@@ -241,8 +244,9 @@ struct v4l2_ctrl_ref {
/**
* struct v4l2_ctrl_handler - The control handler keeps track of all the
- * controls: both the controls owned by the handler and those inherited
- * from other handlers.
+ * controls: both the controls owned by the handler and those inherited
+ * from other handlers.
+ *
* @_lock: Default for "lock".
* @lock: Lock to control access to this handler and its controls.
* May be replaced by the user right after init.
@@ -252,7 +256,8 @@ struct v4l2_ctrl_ref {
* control is needed multiple times, so this is a simple
* optimization.
* @buckets: Buckets for the hashing. Allows for quick control lookup.
- * @notify: A notify callback that is called whenever the control changes value.
+ * @notify: A notify callback that is called whenever the control changes
+ * value.
* Note that the handler's lock is held when the notify function
* is called!
* @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
@@ -274,6 +279,7 @@ struct v4l2_ctrl_handler {
/**
* struct v4l2_ctrl_config - Control configuration structure.
+ *
* @ops: The control ops.
* @type_ops: The control type ops. Only needed for compound controls.
* @id: The control ID.
@@ -282,7 +288,7 @@ struct v4l2_ctrl_handler {
* @min: The control's minimum value.
* @max: The control's maximum value.
* @step: The control's step value for non-menu controls.
- * @def: The control's default value.
+ * @def: The control's default value.
* @dims: The size of each dimension.
* @elem_size: The size in bytes of the control.
* @flags: The control's flags.
@@ -297,7 +303,7 @@ struct v4l2_ctrl_handler {
* is in addition to the menu_skip_mask above). The last entry
* must be NULL.
* @qmenu_int: A const s64 integer array for all menu items of the type
- * V4L2_CTRL_TYPE_INTEGER_MENU.
+ * V4L2_CTRL_TYPE_INTEGER_MENU.
* @is_private: If set, then this control is private to its handler and it
* will not be added to any other handlers.
*/
@@ -320,20 +326,31 @@ struct v4l2_ctrl_config {
unsigned int is_private:1;
};
-/*
- * v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
+/**
+ * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
+ *
+ * @id: ID of the control
+ * @name: name of the control
+ * @type: type of the control
+ * @min: minimum value for the control
+ * @max: maximum value for the control
+ * @step: control step
+ * @def: default value for the control
+ * @flags: flags to be used on the control
*
* This works for all standard V4L2 controls.
* For non-standard controls it will only fill in the given arguments
- * and @name will be NULL.
+ * and @name will be %NULL.
*
* This function will overwrite the contents of @name, @type and @flags.
* The contents of @min, @max, @step and @def may be modified depending on
* the type.
*
- * Do not use in drivers! It is used internally for backwards compatibility
- * control handling only. Once all drivers are converted to use the new
- * control framework this function will no longer be exported.
+ * .. note::
+ *
+ * Do not use in drivers! It is used internally for backwards compatibility
+ * control handling only. Once all drivers are converted to use the new
+ * control framework this function will no longer be exported.
*/
void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
@@ -359,7 +376,7 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
* macro that hides the @key and @name arguments.
*/
int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
- unsigned nr_of_controls_hint,
+ unsigned int nr_of_controls_hint,
struct lock_class_key *key, const char *name);
#ifdef CONFIG_LOCKDEP
@@ -436,7 +453,8 @@ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
/**
* v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
- * control.
+ * control.
+ *
* @hdl: The control handler.
* @cfg: The control's configuration data.
* @priv: The control's driver-specific private data.
@@ -445,17 +463,20 @@ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
* and @hdl->error is set to the error code (if it wasn't set already).
*/
struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
- const struct v4l2_ctrl_config *cfg, void *priv);
+ const struct v4l2_ctrl_config *cfg,
+ void *priv);
/**
- * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
+ * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
+ * control.
+ *
* @hdl: The control handler.
* @ops: The control ops.
- * @id: The control ID.
+ * @id: The control ID.
* @min: The control's minimum value.
* @max: The control's maximum value.
* @step: The control's step value
- * @def: The control's default value.
+ * @def: The control's default value.
*
* If the &v4l2_ctrl struct could not be allocated, or the control
* ID is not known, then NULL is returned and @hdl->error is set to the
@@ -466,22 +487,25 @@ struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
* Use v4l2_ctrl_new_std_menu() when adding menu controls.
*/
struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
- const struct v4l2_ctrl_ops *ops,
- u32 id, s64 min, s64 max, u64 step, s64 def);
+ const struct v4l2_ctrl_ops *ops,
+ u32 id, s64 min, s64 max, u64 step,
+ s64 def);
/**
- * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
+ * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
+ * menu control.
+ *
* @hdl: The control handler.
* @ops: The control ops.
- * @id: The control ID.
+ * @id: The control ID.
* @max: The control's maximum value.
- * @mask: The control's skip mask for menu controls. This makes it
+ * @mask: The control's skip mask for menu controls. This makes it
* easy to skip menu items that are not valid. If bit X is set,
* then menu item X is skipped. Of course, this only works for
* menus with <= 64 menu items. There are no menus that come
* close to that number, so this is OK. Should we ever need more,
* then this will have to be extended to a bit array.
- * @def: The control's default value.
+ * @def: The control's default value.
*
* Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
* determines which menu items are to be skipped.
@@ -489,12 +513,13 @@ struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
* If @id refers to a non-menu control, then this function will return NULL.
*/
struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
- const struct v4l2_ctrl_ops *ops,
- u32 id, u8 max, u64 mask, u8 def);
+ const struct v4l2_ctrl_ops *ops,
+ u32 id, u8 max, u64 mask, u8 def);
/**
* v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
- * with driver specific menu.
+ * with driver specific menu.
+ *
* @hdl: The control handler.
* @ops: The control ops.
* @id: The control ID.
@@ -513,11 +538,14 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
*
*/
struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
- const struct v4l2_ctrl_ops *ops, u32 id, u8 max,
- u64 mask, u8 def, const char * const *qmenu);
+ const struct v4l2_ctrl_ops *ops,
+ u32 id, u8 max,
+ u64 mask, u8 def,
+ const char * const *qmenu);
/**
* v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
+ *
* @hdl: The control handler.
* @ops: The control ops.
* @id: The control ID.
@@ -528,15 +556,20 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
* Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
* takes as an argument an array of integers determining the menu items.
*
- * If @id refers to a non-integer-menu control, then this function will return NULL.
+ * If @id refers to a non-integer-menu control, then this function will
+ * return %NULL.
*/
struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
- const struct v4l2_ctrl_ops *ops,
- u32 id, u8 max, u8 def, const s64 *qmenu_int);
+ const struct v4l2_ctrl_ops *ops,
+ u32 id, u8 max, u8 def,
+ const s64 *qmenu_int);
+
+typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
/**
* v4l2_ctrl_add_handler() - Add all controls from handler @add to
- * handler @hdl.
+ * handler @hdl.
+ *
* @hdl: The control handler.
* @add: The control handler whose controls you want to add to
* the @hdl control handler.
@@ -550,10 +583,11 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
*/
int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
struct v4l2_ctrl_handler *add,
- bool (*filter)(const struct v4l2_ctrl *ctrl));
+ v4l2_ctrl_filter filter);
/**
* v4l2_ctrl_radio_filter() - Standard filter for radio controls.
+ *
* @ctrl: The control that is filtered.
*
* This will return true for any controls that are valid for radio device
@@ -565,16 +599,19 @@ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
/**
- * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
+ * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
+ * to that cluster.
+ *
* @ncontrols: The number of controls in this cluster.
- * @controls: The cluster control array of size @ncontrols.
+ * @controls: The cluster control array of size @ncontrols.
*/
-void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
+void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
/**
- * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
- * that cluster and set it up for autofoo/foo-type handling.
+ * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
+ * to that cluster and set it up for autofoo/foo-type handling.
+ *
* @ncontrols: The number of controls in this cluster.
* @controls: The cluster control array of size @ncontrols. The first control
* must be the 'auto' control (e.g. autogain, autoexposure, etc.)
@@ -602,12 +639,14 @@ void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
* on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
* if autofoo is in auto mode.
*/
-void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
- u8 manual_val, bool set_volatile);
+void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
+ struct v4l2_ctrl **controls,
+ u8 manual_val, bool set_volatile);
/**
* v4l2_ctrl_find() - Find a control with the given ID.
+ *
* @hdl: The control handler.
* @id: The control ID to find.
*
@@ -632,6 +671,7 @@ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
/**
* v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
+ *
* @ctrl: The control to (de)activate.
* @grabbed: True if the control should become grabbed.
*
@@ -671,6 +711,7 @@ int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
/**
* v4l2_ctrl_modify_range() - Update the range of a control.
+ *
* @ctrl: The control to update.
* @min: The control's minimum value.
* @max: The control's maximum value.
@@ -701,6 +742,7 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
/**
* v4l2_ctrl_notify() - Function to set a notify callback for a control.
+ *
* @ctrl: The control.
* @notify: The callback function.
* @priv: The callback private handle, passed as argument to the callback.
@@ -712,10 +754,12 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
* There can be only one notify. If another already exists, then a WARN_ON
* will be issued and the function will do nothing.
*/
-void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv);
+void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
+ void *priv);
/**
* v4l2_ctrl_get_name() - Get the name of the control
+ *
* @id: The control ID.
*
* This function returns the name of the given control ID or NULL if it isn't
@@ -725,6 +769,7 @@ const char *v4l2_ctrl_get_name(u32 id);
/**
* v4l2_ctrl_get_menu() - Get the menu string array of the control
+ *
* @id: The control ID.
*
* This function returns the NULL-terminated menu string array name of the
@@ -734,6 +779,7 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
/**
* v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
+ *
* @id: The control ID.
* @len: The size of the integer array.
*
@@ -743,7 +789,9 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
/**
- * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
+ * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
+ * within a driver.
+ *
* @ctrl: The control.
*
* This returns the control's value safely by going through the control
@@ -756,8 +804,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
/**
* __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
+ *
* @ctrl: The control.
- * @val: The new value.
+ * @val: TheControls name new value.
*
* This sets the control's new value safely by going through the control
* framework. This function assumes the control's handler is already locked,
@@ -767,7 +816,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
*/
int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
-/** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
+/**
+ * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
+ * within a driver.
* @ctrl: The control.
* @val: The new value.
*
@@ -791,6 +842,7 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
/**
* v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
* from within a driver.
+ *
* @ctrl: The control.
*
* This returns the control's value safely by going through the control
@@ -815,7 +867,8 @@ s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
*/
int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
-/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
+/**
+ * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
* from within a driver.
*
* @ctrl: The control.
@@ -838,7 +891,8 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
return rval;
}
-/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
+/**
+ * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
*
* @ctrl: The control.
* @s: The new string.
@@ -851,12 +905,13 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
*/
int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
-/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
+/**
+ * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
* from within a driver.
*
* @ctrl: The control.
* @s: The new string.
- *
+ *Controls name
* This sets the control's new string safely by going through the control
* framework. This function will lock the control's handler, so it cannot be
* used from within the &v4l2_ctrl_ops functions.
@@ -876,39 +931,179 @@ static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
/* Internal helper functions that deal with control events. */
extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
+
+/**
+ * v4l2_ctrl_replace - Function to be used as a callback to
+ * &struct v4l2_subscribed_event_ops replace\(\)
+ *
+ * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ * event;
+ * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the modified
+ * event;
+ */
void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
+
+/**
+ * v4l2_ctrl_merge - Function to be used as a callback to
+ * &struct v4l2_subscribed_event_ops merge(\)
+ *
+ * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ * event;
+ * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the merged
+ * event;
+ */
void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
-/* Can be used as a vidioc_log_status function that just dumps all controls
- associated with the filehandle. */
+/**
+ * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
+ *
+ * @file: pointer to struct file
+ * @fh: unused. Kept just to be compatible to the arguments expected by
+ * &struct v4l2_ioctl_ops.vidioc_log_status.
+ *
+ * Can be used as a vidioc_log_status function that just dumps all controls
+ * associated with the filehandle.
+ */
int v4l2_ctrl_log_status(struct file *file, void *fh);
-/* Can be used as a vidioc_subscribe_event function that just subscribes
- control events. */
+/**
+ * v4l2_ctrl_subscribe_event - Subscribes to an event
+ *
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ *
+ * Can be used as a vidioc_subscribe_event function that just subscribes
+ * control events.
+ */
int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
const struct v4l2_event_subscription *sub);
-/* Can be used as a poll function that just polls for control events. */
+/**
+ * v4l2_ctrl_poll - function to be used as a callback to the poll()
+ * That just polls for control events.
+ *
+ * @file: pointer to struct file
+ * @wait: pointer to struct poll_table_struct
+ */
unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
-/* Helpers for ioctl_ops. If hdl == NULL then they will all return -EINVAL. */
+/* Helpers for ioctl_ops */
+
+/**
+ * v4l2_queryctrl - Helper function to implement
+ * :ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qc: pointer to &struct v4l2_queryctrl
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
-int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_query_ext_ctrl *qc);
+
+/**
+ * v4l2_query_ext_ctrl - Helper function to implement
+ * :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qc: pointer to &struct v4l2_query_ext_ctrl
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
+ struct v4l2_query_ext_ctrl *qc);
+
+/**
+ * v4l2_querymenu - Helper function to implement
+ * :ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qm: pointer to &struct v4l2_querymenu
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
+
+/**
+ * v4l2_g_ctrl - Helper function to implement
+ * :ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @ctrl: pointer to &struct v4l2_control
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
+
+/**
+ * v4l2_s_ctrl - Helper function to implement
+ * :ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ *
+ * @ctrl: pointer to &struct v4l2_control
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
- struct v4l2_control *ctrl);
-int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
-int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
+ struct v4l2_control *ctrl);
+
+/**
+ * v4l2_g_ext_ctrls - Helper function to implement
+ * :ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl,
+ struct v4l2_ext_controls *c);
+
+/**
+ * v4l2_try_ext_ctrls - Helper function to implement
+ * :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
+ struct v4l2_ext_controls *c);
+
+/**
+ * v4l2_s_ext_ctrls - Helper function to implement
+ * :ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
- struct v4l2_ext_controls *c);
+ struct v4l2_ext_controls *c);
-/* Can be used as a subscribe_event function that just subscribes control
- events. */
+/**
+ * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
+ * as a &struct v4l2_subdev_core_ops subscribe_event function
+ * that just subscribes control events.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
struct v4l2_event_subscription *sub);
-/* Log all controls owned by subdev's control handler. */
+/**
+ * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
+ * handler.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
#endif
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 25a3190308fb..a122b1bd40f9 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -47,19 +47,105 @@ struct v4l2_ctrl_handler;
/* Priority helper functions */
+/**
+ * struct v4l2_prio_state - stores the priority states
+ *
+ * @prios: array with elements to store the array priorities
+ *
+ *
+ * .. note::
+ * The size of @prios array matches the number of priority types defined
+ * by :ref:`enum v4l2_priority <v4l2-priority>`.
+ */
struct v4l2_prio_state {
atomic_t prios[4];
};
+/**
+ * v4l2_prio_init - initializes a struct v4l2_prio_state
+ *
+ * @global: pointer to &struct v4l2_prio_state
+ */
void v4l2_prio_init(struct v4l2_prio_state *global);
+
+/**
+ * v4l2_prio_change - changes the v4l2 file handler priority
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ * @new: Priority type requested, as defined by :ref:`enum v4l2_priority <v4l2-priority>`.
+ *
+ * .. note::
+ * This function should be used only by the V4L2 core.
+ */
int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
enum v4l2_priority new);
+
+/**
+ * v4l2_prio_open - Implements the priority logic for a file handler open
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ * This function should be used only by the V4L2 core.
+ */
void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local);
+
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: priority to be released, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ * This function should be used only by the V4L2 core.
+ */
void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
+
+/**
+ * v4l2_prio_max - Return the maximum priority, as stored at the @global array.
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ *
+ * .. note::
+ * This function should be used only by the V4L2 core.
+ */
enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
-int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>` local
+ *
+ * .. note::
+ * This function should be used only by the V4L2 core.
+ */
+int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
+/**
+ * struct v4l2_file_operations - fs operations used by a V4L2 device
+ *
+ * @owner: pointer to struct module
+ * @read: operations needed to implement the read() syscall
+ * @write: operations needed to implement the write() syscall
+ * @poll: operations needed to implement the poll() syscall
+ * @unlocked_ioctl: operations needed to implement the ioctl() syscall
+ * @compat_ioctl32: operations needed to implement the ioctl() syscall for
+ * the special case where the Kernel uses 64 bits instructions, but
+ * the userspace uses 32 bits.
+ * @get_unmapped_area: called by the mmap() syscall, used when %!CONFIG_MMU
+ * @mmap: operations needed to implement the mmap() syscall
+ * @open: operations needed to implement the open() syscall
+ * @release: operations needed to implement the release() syscall
+ *
+ * .. note::
+ *
+ * Those operations are used to implemente the fs struct file_operations
+ * at the V4L2 drivers. The V4L2 core overrides the fs ops with some
+ * extra logic needed by the subsystem.
+ */
struct v4l2_file_operations {
struct module *owner;
ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
@@ -82,6 +168,47 @@ struct v4l2_file_operations {
* the common handler
*/
+/**
+ * struct video_device - Structure used to create and manage the V4L2 device
+ * nodes.
+ *
+ * @entity: &struct media_entity
+ * @intf_devnode: pointer to &struct media_intf_devnode
+ * @pipe: &struct media_pipeline
+ * @fops: pointer to &struct v4l2_file_operations for the video device
+ * @device_caps: device capabilities as used in v4l2_capabilities
+ * @dev: &struct device for the video device
+ * @cdev: character device
+ * @v4l2_dev: pointer to &struct v4l2_device parent
+ * @dev_parent: pointer to &struct device parent
+ * @ctrl_handler: Control handler associated with this device node.
+ * May be NULL.
+ * @queue: &struct vb2_queue associated with this device node. May be NULL.
+ * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
+ * If NULL, then v4l2_dev->prio will be used.
+ * @name: video device name
+ * @vfl_type: V4L device type
+ * @vfl_dir: V4L receiver, transmitter or m2m
+ * @minor: device node 'minor'. It is set to -1 if the registration failed
+ * @num: number of the video device node
+ * @flags: video device flags. Use bitops to set/clear/test flags
+ * @index: attribute to differentiate multiple indices on one physical device
+ * @fh_lock: Lock for all v4l2_fhs
+ * @fh_list: List of &struct v4l2_fh
+ * @dev_debug: Internal device debug flags, not for use by drivers
+ * @tvnorms: Supported tv norms
+ *
+ * @release: video device release() callback
+ * @ioctl_ops: pointer to &struct v4l2_ioctl_ops with ioctl callbacks
+ *
+ * @valid_ioctls: bitmap with the valid ioctls for this device
+ * @disable_locking: bitmap with the ioctls that don't require locking
+ * @lock: pointer to &struct mutex serialization lock
+ *
+ * .. note::
+ * Only set @dev_parent if that can't be deduced from @v4l2_dev.
+ */
+
struct video_device
{
#if defined(CONFIG_MEDIA_CONTROLLER)
@@ -89,59 +216,45 @@ struct video_device
struct media_intf_devnode *intf_devnode;
struct media_pipeline pipe;
#endif
- /* device ops */
const struct v4l2_file_operations *fops;
- /* device capabilities as used in v4l2_capabilities */
u32 device_caps;
/* sysfs */
- struct device dev; /* v4l device */
- struct cdev *cdev; /* character device */
+ struct device dev;
+ struct cdev *cdev;
- struct v4l2_device *v4l2_dev; /* v4l2_device parent */
- /* Only set parent if that can't be deduced from v4l2_dev */
- struct device *dev_parent; /* device parent */
+ struct v4l2_device *v4l2_dev;
+ struct device *dev_parent;
- /* Control handler associated with this device node. May be NULL. */
struct v4l2_ctrl_handler *ctrl_handler;
- /* vb2_queue associated with this device node. May be NULL. */
struct vb2_queue *queue;
- /* Priority state. If NULL, then v4l2_dev->prio will be used. */
struct v4l2_prio_state *prio;
/* device info */
char name[32];
- int vfl_type; /* device type */
- int vfl_dir; /* receiver, transmitter or m2m */
- /* 'minor' is set to -1 if the registration failed */
+ int vfl_type;
+ int vfl_dir;
int minor;
u16 num;
- /* use bitops to set/clear/test flags */
unsigned long flags;
- /* attribute to differentiate multiple indices on one physical device */
int index;
/* V4L2 file handles */
- spinlock_t fh_lock; /* Lock for all v4l2_fhs */
- struct list_head fh_list; /* List of struct v4l2_fh */
+ spinlock_t fh_lock;
+ struct list_head fh_list;
- /* Internal device debug flags, not for use by drivers */
int dev_debug;
- /* Video standard vars */
- v4l2_std_id tvnorms; /* Supported tv norms */
+ v4l2_std_id tvnorms;
/* callbacks */
void (*release)(struct video_device *vdev);
-
- /* ioctl callbacks */
const struct v4l2_ioctl_ops *ioctl_ops;
DECLARE_BITMAP(valid_ioctls, BASE_VIDIOC_PRIVATE);
- /* serialization lock */
DECLARE_BITMAP(disable_locking, BASE_VIDIOC_PRIVATE);
struct mutex *lock;
};
@@ -151,88 +264,241 @@ struct video_device
/* dev to video-device */
#define to_video_device(cd) container_of(cd, struct video_device, dev)
+/**
+ * __video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr: which device node number is desired:
+ * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ * @warn_if_nr_in_use: warn if the desired device node number
+ * was already in use and another number was chosen instead.
+ * @owner: module that owns the video device node
+ *
+ * The registration code assigns minor numbers and device node numbers
+ * based on the requested type and registers the new device node with
+ * the kernel.
+ *
+ * This function assumes that struct video_device was zeroed when it
+ * was allocated and does not contain any stale date.
+ *
+ * An error is returned if no free minor or device node number could be
+ * found, or if the registration of the device node failed.
+ *
+ * Returns 0 on success.
+ *
+ * Valid values for @type are:
+ *
+ * - %VFL_TYPE_GRABBER - A frame grabber
+ * - %VFL_TYPE_VBI - Vertical blank data (undecoded)
+ * - %VFL_TYPE_RADIO - A radio card
+ * - %VFL_TYPE_SUBDEV - A subdevice
+ * - %VFL_TYPE_SDR - Software Defined Radio
+ *
+ * .. note::
+ *
+ * This function is meant to be used only inside the V4L2 core.
+ * Drivers should use video_register_device() or
+ * video_register_device_no_warn().
+ */
int __must_check __video_register_device(struct video_device *vdev, int type,
int nr, int warn_if_nr_in_use, struct module *owner);
-/* Register video devices. Note that if video_register_device fails,
- the release() callback of the video_device structure is *not* called, so
- the caller is responsible for freeing any data. Usually that means that
- you call video_device_release() on failure. */
+/**
+ * video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr: which device node number is desired:
+ * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * if video_register_device fails, the release() callback of
+ * &struct video_device structure is *not* called, so the caller
+ * is responsible for freeing any data. Usually that means that
+ * you video_device_release() should be called on failure.
+ */
static inline int __must_check video_register_device(struct video_device *vdev,
int type, int nr)
{
return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
}
-/* Same as video_register_device, but no warning is issued if the desired
- device node number was already in use. */
+/**
+ * video_register_device_no_warn - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr: which device node number is desired:
+ * (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * This function is identical to video_register_device() except that no
+ * warning is issued if the desired device node number was already in use.
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * if video_register_device fails, the release() callback of
+ * &struct video_device structure is *not* called, so the caller
+ * is responsible for freeing any data. Usually that means that
+ * you video_device_release() should be called on failure.
+ */
static inline int __must_check video_register_device_no_warn(
struct video_device *vdev, int type, int nr)
{
return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
}
-/* Unregister video devices. Will do nothing if vdev == NULL or
- video_is_registered() returns false. */
+/**
+ * video_unregister_device - Unregister video devices.
+ *
+ * @vdev: &struct video_device to register
+ *
+ * Does nothing if vdev == NULL or if video_is_registered() returns false.
+ */
void video_unregister_device(struct video_device *vdev);
-/* helper functions to alloc/release struct video_device, the
- latter can also be used for video_device->release(). */
+/**
+ * video_device_alloc - helper function to alloc &struct video_device
+ *
+ * Returns NULL if %-ENOMEM or a &struct video_device on success.
+ */
struct video_device * __must_check video_device_alloc(void);
-/* this release function frees the vdev pointer */
+/**
+ * video_device_release - helper function to release &struct video_device
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Can also be used for video_device->release\(\).
+ */
void video_device_release(struct video_device *vdev);
-/* this release function does nothing, use when the video_device is a
- static global struct. Note that having a static video_device is
- a dubious construction at best. */
+/**
+ * video_device_release_empty - helper function to implement the
+ * video_device->release\(\) callback.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * This release function does nothing.
+ *
+ * It should be used when the video_device is a static global struct.
+ *
+ * .. note::
+ * Having a static video_device is a dubious construction at best.
+ */
void video_device_release_empty(struct video_device *vdev);
-/* returns true if cmd is a known V4L2 ioctl */
+/**
+ * v4l2_is_known_ioctl - Checks if a given cmd is a known V4L ioctl
+ *
+ * @cmd: ioctl command
+ *
+ * returns true if cmd is a known V4L2 ioctl
+ */
bool v4l2_is_known_ioctl(unsigned int cmd);
-/* mark that this command shouldn't use core locking */
-static inline void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd)
+/** v4l2_disable_ioctl_locking - mark that a given command
+ * shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ */
+static inline void v4l2_disable_ioctl_locking(struct video_device *vdev,
+ unsigned int cmd)
{
if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
set_bit(_IOC_NR(cmd), vdev->disable_locking);
}
-/* Mark that this command isn't implemented. This must be called before
- video_device_register. See also the comments in determine_valid_ioctls().
- This function allows drivers to provide just one v4l2_ioctl_ops struct, but
- disable ioctls based on the specific card that is actually found. */
-static inline void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd)
+/**
+ * v4l2_disable_ioctl- mark that a given command isn't implemented.
+ * shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ *
+ * This function allows drivers to provide just one v4l2_ioctl_ops struct, but
+ * disable ioctls based on the specific card that is actually found.
+ *
+ * .. note::
+ *
+ * This must be called before video_register_device.
+ * See also the comments for determine_valid_ioctls().
+ */
+static inline void v4l2_disable_ioctl(struct video_device *vdev,
+ unsigned int cmd)
{
if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
set_bit(_IOC_NR(cmd), vdev->valid_ioctls);
}
-/* helper functions to access driver private data. */
+/**
+ * video_get_drvdata - gets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * returns a pointer to the private data
+ */
static inline void *video_get_drvdata(struct video_device *vdev)
{
return dev_get_drvdata(&vdev->dev);
}
+/**
+ * video_set_drvdata - sets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @data: private data pointer
+ */
static inline void video_set_drvdata(struct video_device *vdev, void *data)
{
dev_set_drvdata(&vdev->dev, data);
}
+/**
+ * video_devdata - gets &struct video_device from struct file.
+ *
+ * @file: pointer to struct file
+ */
struct video_device *video_devdata(struct file *file);
-/* Combine video_get_drvdata and video_devdata as this is
- used very often. */
+/**
+ * video_drvdata - gets private data from &struct video_device using the
+ * struct file.
+ *
+ * @file: pointer to struct file
+ *
+ * This is function combines both video_get_drvdata() and video_devdata()
+ * as this is used very often.
+ */
static inline void *video_drvdata(struct file *file)
{
return video_get_drvdata(video_devdata(file));
}
+/**
+ * video_device_node_name - returns the video device name
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Returns the device name string
+ */
static inline const char *video_device_node_name(struct video_device *vdev)
{
return dev_name(&vdev->dev);
}
+/**
+ * video_is_registered - returns true if the &struct video_device is registered.
+ *
+ *
+ * @vdev: pointer to &struct video_device
+ */
static inline int video_is_registered(struct video_device *vdev)
{
return test_bit(V4L2_FL_REGISTERED, &vdev->flags);
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index d5d45a8d3998..a9d6aa41790e 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -25,100 +25,188 @@
#include <media/v4l2-subdev.h>
#include <media/v4l2-dev.h>
-/* Each instance of a V4L2 device should create the v4l2_device struct,
- either stand-alone or embedded in a larger struct.
-
- It allows easy access to sub-devices (see v4l2-subdev.h) and provides
- basic V4L2 device-level support.
- */
-
#define V4L2_DEVICE_NAME_SIZE (20 + 16)
struct v4l2_ctrl_handler;
+/**
+ * struct v4l2_device - main struct to for V4L2 device drivers
+ *
+ * @dev: pointer to struct device.
+ * @mdev: pointer to struct media_device
+ * @subdevs: used to keep track of the registered subdevs
+ * @lock: lock this struct; can be used by the driver as well
+ * if this struct is embedded into a larger struct.
+ * @name: unique device name, by default the driver name + bus ID
+ * @notify: notify callback called by some sub-devices.
+ * @ctrl_handler: The control handler. May be NULL.
+ * @prio: Device's priority state
+ * @ref: Keep track of the references to this struct.
+ * @release: Release function that is called when the ref count
+ * goes to 0.
+ *
+ * Each instance of a V4L2 device should create the v4l2_device struct,
+ * either stand-alone or embedded in a larger struct.
+ *
+ * It allows easy access to sub-devices (see v4l2-subdev.h) and provides
+ * basic V4L2 device-level support.
+ *
+ * .. note::
+ *
+ * #) dev->driver_data points to this struct.
+ * #) dev might be NULL if there is no parent device
+ */
+
struct v4l2_device {
- /* dev->driver_data points to this struct.
- Note: dev might be NULL if there is no parent device
- as is the case with e.g. ISA devices. */
struct device *dev;
#if defined(CONFIG_MEDIA_CONTROLLER)
struct media_device *mdev;
#endif
- /* used to keep track of the registered subdevs */
struct list_head subdevs;
- /* lock this struct; can be used by the driver as well if this
- struct is embedded into a larger struct. */
spinlock_t lock;
- /* unique device name, by default the driver name + bus ID */
char name[V4L2_DEVICE_NAME_SIZE];
- /* notify callback called by some sub-devices. */
void (*notify)(struct v4l2_subdev *sd,
unsigned int notification, void *arg);
- /* The control handler. May be NULL. */
struct v4l2_ctrl_handler *ctrl_handler;
- /* Device's priority state */
struct v4l2_prio_state prio;
- /* Keep track of the references to this struct. */
struct kref ref;
- /* Release function that is called when the ref count goes to 0. */
void (*release)(struct v4l2_device *v4l2_dev);
};
+/**
+ * v4l2_device_get - gets a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to increment the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
{
kref_get(&v4l2_dev->ref);
}
+/**
+ * v4l2_device_put - putss a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to decrement the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
int v4l2_device_put(struct v4l2_device *v4l2_dev);
-/* Initialize v4l2_dev and make dev->driver_data point to v4l2_dev.
- dev may be NULL in rare cases (ISA devices). In that case you
- must fill in the v4l2_dev->name field before calling this function. */
-int __must_check v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
-
-/* Optional function to initialize the name field of struct v4l2_device using
- the driver name and a driver-global atomic_t instance.
- This function will increment the instance counter and returns the instance
- value used in the name.
-
- Example:
-
- static atomic_t drv_instance = ATOMIC_INIT(0);
-
- ...
-
- instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
-
- The first time this is called the name field will be set to foo0 and
- this function returns 0. If the name ends with a digit (e.g. cx18),
- then the name will be set to cx18-0 since cx180 looks really odd. */
+/**
+ * v4l2_device_register -Initialize v4l2_dev and make dev->driver_data
+ * point to v4l2_dev.
+ *
+ * @dev: pointer to struct device
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * .. note::
+ * dev may be NULL in rare cases (ISA devices).
+ * In such case the caller must fill in the v4l2_dev->name field
+ * before calling this function.
+ */
+int __must_check v4l2_device_register(struct device *dev,
+ struct v4l2_device *v4l2_dev);
+
+/**
+ * v4l2_device_set_name - Optional function to initialize the
+ * name field of struct v4l2_device
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @basename: base name for the device name
+ * @instance: pointer to a static atomic_t var with the instance usage for
+ * the device driver.
+ *
+ * v4l2_device_set_name() initializes the name field of struct v4l2_device
+ * using the driver name and a driver-global atomic_t instance.
+ *
+ * This function will increment the instance counter and returns the
+ * instance value used in the name.
+ *
+ * Example:
+ *
+ * static atomic_t drv_instance = ATOMIC_INIT(0);
+ *
+ * ...
+ *
+ * instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
+ *
+ * The first time this is called the name field will be set to foo0 and
+ * this function returns 0. If the name ends with a digit (e.g. cx18),
+ * then the name will be set to cx18-0 since cx180 would look really odd.
+ */
int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
- atomic_t *instance);
-
-/* Set v4l2_dev->dev to NULL. Call when the USB parent disconnects.
- Since the parent disappears this ensures that v4l2_dev doesn't have an
- invalid parent pointer. */
+ atomic_t *instance);
+
+/**
+ * v4l2_device_disconnect - Change V4L2 device state to disconnected.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * Should be called when the USB parent disconnects.
+ * Since the parent disappears, this ensures that v4l2_dev doesn't have
+ * an invalid parent pointer.
+ *
+ * .. note:: This function sets v4l2_dev->dev to NULL.
+ */
void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
-/* Unregister all sub-devices and any other resources related to v4l2_dev. */
+/**
+ * v4l2_device_unregister - Unregister all sub-devices and any other
+ * resources related to v4l2_dev.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ */
void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
-/* Register a subdev with a v4l2 device. While registered the subdev module
- is marked as in-use. An error is returned if the module is no longer
- loaded when you attempt to register it. */
+/**
+ * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * While registered, the subdev module is marked as in-use.
+ *
+ * An error is returned if the module is no longer loaded on any attempts
+ * to register it.
+ */
int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
- struct v4l2_subdev *sd);
-/* Unregister a subdev with a v4l2 device. Can also be called if the subdev
- wasn't registered. In that case it will do nothing. */
+ struct v4l2_subdev *sd);
+
+/**
+ * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * .. note ::
+ *
+ * Can also be called if the subdev wasn't registered. In such
+ * case, it will do nothing.
+ */
void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
-/* Register device nodes for all subdev of the v4l2 device that are marked with
- * the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+/**
+ * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
+ * of the v4l2 device that are marked with
+ * the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
*/
int __must_check
v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
-/* Send a notification to v4l2_device. */
+/**
+ * v4l2_subdev_notify - Sends a notification to v4l2_device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ * @notification: type of notification. Please notice that the notification
+ * type is driver-specific.
+ * @arg: arguments for the notification. Those are specific to each
+ * notification type.
+ */
static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
unsigned int notification, void *arg)
{
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 1113c8874c26..65caadf13eec 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -28,7 +28,7 @@
*/
extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
-/**
+/*
* v4l2_check_dv_timings_fnc - timings check callback
*
* @t: the v4l2_dv_timings struct.
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 9792f906423b..ca854203b8b9 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -73,14 +73,15 @@ struct video_device;
* @list: List node for the v4l2_fh->available list.
* @sev: Pointer to parent v4l2_subscribed_event.
* @event: The event itself.
- */
+ */
struct v4l2_kevent {
struct list_head list;
struct v4l2_subscribed_event *sev;
struct v4l2_event event;
};
-/** struct v4l2_subscribed_event_ops - Subscribed event operations.
+/**
+ * struct v4l2_subscribed_event_ops - Subscribed event operations.
*
* @add: Optional callback, called when a new listener is added
* @del: Optional callback, called when a listener stops listening
@@ -88,20 +89,23 @@ struct v4l2_kevent {
* @merge: Optional callback that can merge event 'old' into event 'new'.
*/
struct v4l2_subscribed_event_ops {
- int (*add)(struct v4l2_subscribed_event *sev, unsigned elems);
+ int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
void (*del)(struct v4l2_subscribed_event *sev);
void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
};
/**
- * struct v4l2_subscribed_event - Internal struct representing a subscribed event.
+ * struct v4l2_subscribed_event - Internal struct representing a subscribed
+ * event.
+ *
* @list: List node for the v4l2_fh->subscribed list.
* @type: Event type.
* @id: Associated object ID (e.g. control ID). 0 if there isn't any.
* @flags: Copy of v4l2_event_subscription->flags.
* @fh: Filehandle that subscribed to this event.
- * @node: List node that hooks into the object's event list (if there is one).
+ * @node: List node that hooks into the object's event list
+ * (if there is one).
* @ops: v4l2_subscribed_event_ops
* @elems: The number of elements in the events array.
* @first: The index of the events containing the oldest available event.
@@ -116,27 +120,124 @@ struct v4l2_subscribed_event {
struct v4l2_fh *fh;
struct list_head node;
const struct v4l2_subscribed_event_ops *ops;
- unsigned elems;
- unsigned first;
- unsigned in_use;
+ unsigned int elems;
+ unsigned int first;
+ unsigned int in_use;
struct v4l2_kevent events[];
};
+/**
+ * v4l2_event_dequeue - Dequeue events from video device.
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @event: pointer to struct v4l2_event
+ * @nonblocking: if not zero, waits for an event to arrive
+ */
int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
int nonblocking);
+
+/**
+ * v4l2_event_queue - Queue events to video device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @ev: pointer to &struct v4l2_event
+ *
+ * The event will be queued for all &struct v4l2_fh file handlers.
+ *
+ * .. note::
+ * The driver's only responsibility is to fill in the type and the data
+ * fields.The other fields will be filled in by V4L2.
+ */
void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_queue_fh - Queue events to video device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @ev: pointer to &struct v4l2_event
+ *
+ *
+ * The event will be queued only for the specified &struct v4l2_fh file handler.
+ *
+ * .. note::
+ * The driver's only responsibility is to fill in the type and the data
+ * fields.The other fields will be filled in by V4L2.
+ */
void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_pending - Check if an event is available
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Returns the number of pending events.
+ */
int v4l2_event_pending(struct v4l2_fh *fh);
+
+/**
+ * v4l2_event_subscribe - Subscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ * @elems: size of the events queue
+ * @ops: pointer to &v4l2_subscribed_event_ops
+ *
+ * .. note::
+ *
+ * if @elems is zero, the framework will fill in a default value,
+ * with is currently 1 element.
+ */
int v4l2_event_subscribe(struct v4l2_fh *fh,
- const struct v4l2_event_subscription *sub, unsigned elems,
+ const struct v4l2_event_subscription *sub,
+ unsigned int elems,
const struct v4l2_subscribed_event_ops *ops);
+/**
+ * v4l2_event_unsubscribe - Unsubscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
int v4l2_event_unsubscribe(struct v4l2_fh *fh,
const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_event_unsubscribe_all - Unsubscribes to all events
+ *
+ * @fh: pointer to &struct v4l2_fh
+ */
void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
-int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh,
+
+/**
+ * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ *
+ * .. note::
+ *
+ * This function should be used for the &struct v4l2_subdev_core_ops
+ * %unsubscribe_event field.
+ */
+int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
+ struct v4l2_fh *fh,
struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subscribe -
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
- const struct v4l2_event_subscription *sub);
+ const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
+ * meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
- struct v4l2_fh *fh, struct v4l2_event_subscription *sub);
+ struct v4l2_fh *fh,
+ struct v4l2_event_subscription *sub);
#endif /* V4L2_EVENT_H */
diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h
index 803516775162..e19e6246e21c 100644
--- a/include/media/v4l2-fh.h
+++ b/include/media/v4l2-fh.h
@@ -33,6 +33,21 @@
struct video_device;
struct v4l2_ctrl_handler;
+/**
+ * struct v4l2_fh - Describes a V4L2 file handler
+ *
+ * @list: list of file handlers
+ * @vdev: pointer to &struct video_device
+ * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
+ * @prio: priority of the file handler, as defined by &enum v4l2_priority
+ *
+ * @wait: event' s wait queue
+ * @subscribed: list of subscribed events
+ * @available: list of events waiting to be dequeued
+ * @navailable: number of available events at @available list
+ * @sequence: event sequence number
+ * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
+ */
struct v4l2_fh {
struct list_head list;
struct video_device *vdev;
@@ -41,8 +56,8 @@ struct v4l2_fh {
/* Events */
wait_queue_head_t wait;
- struct list_head subscribed; /* Subscribed events */
- struct list_head available; /* Dequeueable event */
+ struct list_head subscribed;
+ struct list_head available;
unsigned int navailable;
u32 sequence;
@@ -51,53 +66,102 @@ struct v4l2_fh {
#endif
};
-/*
- * Initialise the file handle. Parts of the V4L2 framework using the
+/**
+ * v4l2_fh_init - Initialise the file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @vdev: pointer to &struct video_device
+ *
+ * Parts of the V4L2 framework using the
* file handles should be initialised in this function. Must be called
- * from driver's v4l2_file_operations->open() handler if the driver
- * uses v4l2_fh.
+ * from driver's v4l2_file_operations->open\(\) handler if the driver
+ * uses &struct v4l2_fh.
*/
void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
-/*
- * Add the fh to the list of file handles on a video_device. The file
- * handle must be initialised first.
+
+/**
+ * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * .. note::
+ * The @fh file handle must be initialised first.
*/
void v4l2_fh_add(struct v4l2_fh *fh);
-/*
- * Can be used as the open() op of v4l2_file_operations.
- * It allocates a v4l2_fh and inits and adds it to the video_device associated
- * with the file pointer.
+
+/**
+ * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
+ * of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
+ * It allocates a v4l2_fh and inits and adds it to the &struct video_device
+ * associated with the file pointer.
*/
int v4l2_fh_open(struct file *filp);
-/*
- * Remove file handle from the list of file handles. Must be called in
- * v4l2_file_operations->release() handler if the driver uses v4l2_fh.
- * On error filp->private_data will be NULL, otherwise it will point to
- * the v4l2_fh struct.
+
+/**
+ * v4l2_fh_del - Remove file handle from the list of file handles.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * On error filp->private_data will be %NULL, otherwise it will point to
+ * the &struct v4l2_fh.
+ *
+ * .. note::
+ * Must be called in v4l2_file_operations->release\(\) handler if the driver
+ * uses &struct v4l2_fh.
*/
void v4l2_fh_del(struct v4l2_fh *fh);
-/*
- * Release resources related to a file handle. Parts of the V4L2
- * framework using the v4l2_fh must release their resources here, too.
- * Must be called in v4l2_file_operations->release() handler if the
- * driver uses v4l2_fh.
+
+/**
+ * v4l2_fh_exit - Release resources related to a file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Parts of the V4L2 framework using the v4l2_fh must release their
+ * resources here, too.
+ *
+ * .. note::
+ * Must be called in v4l2_file_operations->release\(\) handler if the
+ * driver uses &struct v4l2_fh.
*/
void v4l2_fh_exit(struct v4l2_fh *fh);
-/*
- * Can be used as the release() op of v4l2_file_operations.
+
+/**
+ * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
+ * of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
* It deletes and exits the v4l2_fh associated with the file pointer and
* frees it. It will do nothing if filp->private_data (the pointer to the
- * v4l2_fh struct) is NULL. This function always returns 0.
+ * v4l2_fh struct) is %NULL.
+ *
+ * This function always returns 0.
*/
int v4l2_fh_release(struct file *filp);
-/*
- * Returns 1 if this filehandle is the only filehandle opened for the
- * associated video_device. If fh is NULL, then it returns 0.
+
+/**
+ * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
+ * opened for the associated video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * If @fh is NULL, then it returns 0.
*/
int v4l2_fh_is_singular(struct v4l2_fh *fh);
-/*
- * Helper function with struct file as argument. If filp->private_data is
- * NULL, then it will return 0.
+
+/**
+ * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
+ * filehandle opened for the associated video_device.
+ *
+ * @filp: pointer to struct file
+ *
+ * This is a helper function variant of v4l2_fh_is_singular() with uses
+ * struct file as argument.
+ *
+ * If filp->private_data is %NULL, then it will return 0.
*/
static inline int v4l2_fh_is_singular_file(struct file *filp)
{
diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h
index 017ffb2220c7..8b1d19bc9b0e 100644
--- a/include/media/v4l2-ioctl.h
+++ b/include/media/v4l2-ioctl.h
@@ -17,6 +17,272 @@
struct v4l2_fh;
+/**
+ * struct v4l2_ioctl_ops - describe operations for each V4L2 ioctl
+ *
+ * @vidioc_querycap: pointer to the function that implements
+ * :ref:`VIDIOC_QUERYCAP <vidioc_querycap>` ioctl
+ * @vidioc_enum_fmt_vid_cap: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for video capture in single plane mode
+ * @vidioc_enum_fmt_vid_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for video overlay
+ * @vidioc_enum_fmt_vid_out: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for video output in single plane mode
+ * @vidioc_enum_fmt_vid_cap_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for video capture in multiplane mode
+ * @vidioc_enum_fmt_vid_out_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for video output in multiplane mode
+ * @vidioc_enum_fmt_sdr_cap: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for Software Defined Radio capture
+ * @vidioc_enum_fmt_sdr_out: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ * for Software Defined Radio output
+ * @vidioc_g_fmt_vid_cap: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in single plane mode
+ * @vidioc_g_fmt_vid_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_g_fmt_vid_out: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in single plane mode
+ * @vidioc_g_fmt_vid_out_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay output
+ * @vidioc_g_fmt_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_g_fmt_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_g_fmt_sliced_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI capture
+ * @vidioc_g_fmt_sliced_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_g_fmt_vid_cap_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in multiple plane mode
+ * @vidioc_g_fmt_vid_out_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in multiplane plane mode
+ * @vidioc_g_fmt_sdr_cap: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio capture
+ * @vidioc_g_fmt_sdr_out: pointer to the function that implements
+ * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio output
+ * @vidioc_s_fmt_vid_cap: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in single plane mode
+ * @vidioc_s_fmt_vid_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_s_fmt_vid_out: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in single plane mode
+ * @vidioc_s_fmt_vid_out_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay output
+ * @vidioc_s_fmt_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_s_fmt_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_s_fmt_sliced_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI capture
+ * @vidioc_s_fmt_sliced_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_s_fmt_vid_cap_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in multiple plane mode
+ * @vidioc_s_fmt_vid_out_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in multiplane plane mode
+ * @vidioc_s_fmt_sdr_cap: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio capture
+ * @vidioc_s_fmt_sdr_out: pointer to the function that implements
+ * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio output
+ * @vidioc_try_fmt_vid_cap: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in single plane mode
+ * @vidioc_try_fmt_vid_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_try_fmt_vid_out: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in single plane mode
+ * @vidioc_try_fmt_vid_out_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * output
+ * @vidioc_try_fmt_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_try_fmt_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_try_fmt_sliced_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI
+ * capture
+ * @vidioc_try_fmt_sliced_vbi_out: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_try_fmt_vid_cap_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ * in multiple plane mode
+ * @vidioc_try_fmt_vid_out_mplane: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out
+ * in multiplane plane mode
+ * @vidioc_try_fmt_sdr_cap: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio capture
+ * @vidioc_try_fmt_sdr_out: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ * Radio output
+ * @vidioc_reqbufs: pointer to the function that implements
+ * :ref:`VIDIOC_REQBUFS <vidioc_reqbufs>` ioctl
+ * @vidioc_querybuf: pointer to the function that implements
+ * :ref:`VIDIOC_QUERYBUF <vidioc_querybuf>` ioctl
+ * @vidioc_qbuf: pointer to the function that implements
+ * :ref:`VIDIOC_QBUF <vidioc_qbuf>` ioctl
+ * @vidioc_expbuf: pointer to the function that implements
+ * :ref:`VIDIOC_EXPBUF <vidioc_expbuf>` ioctl
+ * @vidioc_dqbuf: pointer to the function that implements
+ * :ref:`VIDIOC_DQBUF <vidioc_qbuf>` ioctl
+ * @vidioc_create_bufs: pointer to the function that implements
+ * :ref:`VIDIOC_CREATE_BUFS <vidioc_create_bufs>` ioctl
+ * @vidioc_prepare_buf: pointer to the function that implements
+ * :ref:`VIDIOC_PREPARE_BUF <vidioc_prepare_buf>` ioctl
+ * @vidioc_overlay: pointer to the function that implements
+ * :ref:`VIDIOC_OVERLAY <vidioc_overlay>` ioctl
+ * @vidioc_g_fbuf: pointer to the function that implements
+ * :ref:`VIDIOC_G_FBUF <vidioc_g_fbuf>` ioctl
+ * @vidioc_s_fbuf: pointer to the function that implements
+ * :ref:`VIDIOC_S_FBUF <vidioc_g_fbuf>` ioctl
+ * @vidioc_streamon: pointer to the function that implements
+ * :ref:`VIDIOC_STREAMON <vidioc_streamon>` ioctl
+ * @vidioc_streamoff: pointer to the function that implements
+ * :ref:`VIDIOC_STREAMOFF <vidioc_streamon>` ioctl
+ * @vidioc_g_std: pointer to the function that implements
+ * :ref:`VIDIOC_G_STD <vidioc_g_std>` ioctl
+ * @vidioc_s_std: pointer to the function that implements
+ * :ref:`VIDIOC_S_STD <vidioc_g_std>` ioctl
+ * @vidioc_querystd: pointer to the function that implements
+ * :ref:`VIDIOC_QUERYSTD <vidioc_querystd>` ioctl
+ * @vidioc_enum_input: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_g_input: pointer to the function that implements
+ * :ref:`VIDIOC_G_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_s_input: pointer to the function that implements
+ * :ref:`VIDIOC_S_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_enum_output: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_g_output: pointer to the function that implements
+ * :ref:`VIDIOC_G_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_s_output: pointer to the function that implements
+ * :ref:`VIDIOC_S_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_queryctrl: pointer to the function that implements
+ * :ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
+ * @vidioc_query_ext_ctrl: pointer to the function that implements
+ * :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
+ * @vidioc_g_ctrl: pointer to the function that implements
+ * :ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
+ * @vidioc_s_ctrl: pointer to the function that implements
+ * :ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
+ * @vidioc_g_ext_ctrls: pointer to the function that implements
+ * :ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_s_ext_ctrls: pointer to the function that implements
+ * :ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_try_ext_ctrls: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_querymenu: pointer to the function that implements
+ * :ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
+ * @vidioc_enumaudio: pointer to the function that implements
+ * :ref:`VIDIOC_ENUMAUDIO <vidioc_enumaudio>` ioctl
+ * @vidioc_g_audio: pointer to the function that implements
+ * :ref:`VIDIOC_G_AUDIO <vidioc_g_audio>` ioctl
+ * @vidioc_s_audio: pointer to the function that implements
+ * :ref:`VIDIOC_S_AUDIO <vidioc_g_audio>` ioctl
+ * @vidioc_enumaudout: pointer to the function that implements
+ * :ref:`VIDIOC_ENUMAUDOUT <vidioc_enumaudout>` ioctl
+ * @vidioc_g_audout: pointer to the function that implements
+ * :ref:`VIDIOC_G_AUDOUT <vidioc_g_audout>` ioctl
+ * @vidioc_s_audout: pointer to the function that implements
+ * :ref:`VIDIOC_S_AUDOUT <vidioc_g_audout>` ioctl
+ * @vidioc_g_modulator: pointer to the function that implements
+ * :ref:`VIDIOC_G_MODULATOR <vidioc_g_modulator>` ioctl
+ * @vidioc_s_modulator: pointer to the function that implements
+ * :ref:`VIDIOC_S_MODULATOR <vidioc_g_modulator>` ioctl
+ * @vidioc_cropcap: pointer to the function that implements
+ * :ref:`VIDIOC_CROPCAP <vidioc_cropcap>` ioctl
+ * @vidioc_g_crop: pointer to the function that implements
+ * :ref:`VIDIOC_G_CROP <vidioc_g_crop>` ioctl
+ * @vidioc_s_crop: pointer to the function that implements
+ * :ref:`VIDIOC_S_CROP <vidioc_g_crop>` ioctl
+ * @vidioc_g_selection: pointer to the function that implements
+ * :ref:`VIDIOC_G_SELECTION <vidioc_g_selection>` ioctl
+ * @vidioc_s_selection: pointer to the function that implements
+ * :ref:`VIDIOC_S_SELECTION <vidioc_g_selection>` ioctl
+ * @vidioc_g_jpegcomp: pointer to the function that implements
+ * :ref:`VIDIOC_G_JPEGCOMP <vidioc_g_jpegcomp>` ioctl
+ * @vidioc_s_jpegcomp: pointer to the function that implements
+ * :ref:`VIDIOC_S_JPEGCOMP <vidioc_g_jpegcomp>` ioctl
+ * @vidioc_g_enc_index: pointer to the function that implements
+ * :ref:`VIDIOC_G_ENC_INDEX <vidioc_g_enc_index>` ioctl
+ * @vidioc_encoder_cmd: pointer to the function that implements
+ * :ref:`VIDIOC_ENCODER_CMD <vidioc_encoder_cmd>` ioctl
+ * @vidioc_try_encoder_cmd: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_ENCODER_CMD <vidioc_encoder_cmd>` ioctl
+ * @vidioc_decoder_cmd: pointer to the function that implements
+ * :ref:`VIDIOC_DECODER_CMD <vidioc_decoder_cmd>` ioctl
+ * @vidioc_try_decoder_cmd: pointer to the function that implements
+ * :ref:`VIDIOC_TRY_DECODER_CMD <vidioc_decoder_cmd>` ioctl
+ * @vidioc_g_parm: pointer to the function that implements
+ * :ref:`VIDIOC_G_PARM <vidioc_g_parm>` ioctl
+ * @vidioc_s_parm: pointer to the function that implements
+ * :ref:`VIDIOC_S_PARM <vidioc_g_parm>` ioctl
+ * @vidioc_g_tuner: pointer to the function that implements
+ * :ref:`VIDIOC_G_TUNER <vidioc_g_tuner>` ioctl
+ * @vidioc_s_tuner: pointer to the function that implements
+ * :ref:`VIDIOC_S_TUNER <vidioc_g_tuner>` ioctl
+ * @vidioc_g_frequency: pointer to the function that implements
+ * :ref:`VIDIOC_G_FREQUENCY <vidioc_g_frequency>` ioctl
+ * @vidioc_s_frequency: pointer to the function that implements
+ * :ref:`VIDIOC_S_FREQUENCY <vidioc_g_frequency>` ioctl
+ * @vidioc_enum_freq_bands: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc_enum_freq_bands>` ioctl
+ * @vidioc_g_sliced_vbi_cap: pointer to the function that implements
+ * :ref:`VIDIOC_G_SLICED_VBI_CAP <vidioc_g_sliced_vbi_cap>` ioctl
+ * @vidioc_log_status: pointer to the function that implements
+ * :ref:`VIDIOC_LOG_STATUS <vidioc_log_status>` ioctl
+ * @vidioc_s_hw_freq_seek: pointer to the function that implements
+ * :ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc_s_hw_freq_seek>` ioctl
+ * @vidioc_g_register: pointer to the function that implements
+ * :ref:`VIDIOC_DBG_G_REGISTER <vidioc_dbg_g_register>` ioctl
+ * @vidioc_s_register: pointer to the function that implements
+ * :ref:`VIDIOC_DBG_S_REGISTER <vidioc_dbg_g_register>` ioctl
+ * @vidioc_g_chip_info: pointer to the function that implements
+ * :ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc_dbg_g_chip_info>` ioctl
+ * @vidioc_enum_framesizes: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FRAMESIZES <vidioc_enum_framesizes>` ioctl
+ * @vidioc_enum_frameintervals: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_FRAMEINTERVALS <vidioc_enum_frameintervals>` ioctl
+ * @vidioc_s_dv_timings: pointer to the function that implements
+ * :ref:`VIDIOC_S_DV_TIMINGS <vidioc_g_dv_timings>` ioctl
+ * @vidioc_g_dv_timings: pointer to the function that implements
+ * :ref:`VIDIOC_G_DV_TIMINGS <vidioc_g_dv_timings>` ioctl
+ * @vidioc_query_dv_timings: pointer to the function that implements
+ * :ref:`VIDIOC_QUERY_DV_TIMINGS <vidioc_query_dv_timings>` ioctl
+ * @vidioc_enum_dv_timings: pointer to the function that implements
+ * :ref:`VIDIOC_ENUM_DV_TIMINGS <vidioc_enum_dv_timings>` ioctl
+ * @vidioc_dv_timings_cap: pointer to the function that implements
+ * :ref:`VIDIOC_DV_TIMINGS_CAP <vidioc_dv_timings_cap>` ioctl
+ * @vidioc_g_edid: pointer to the function that implements
+ * :ref:`VIDIOC_G_EDID <vidioc_g_edid>` ioctl
+ * @vidioc_s_edid: pointer to the function that implements
+ * :ref:`VIDIOC_S_EDID <vidioc_g_edid>` ioctl
+ * @vidioc_subscribe_event: pointer to the function that implements
+ * :ref:`VIDIOC_SUBSCRIBE_EVENT <vidioc_subscribe_event>` ioctl
+ * @vidioc_unsubscribe_event: pointer to the function that implements
+ * :ref:`VIDIOC_UNSUBSCRIBE_EVENT <vidioc_unsubscribe_event>` ioctl
+ * @vidioc_default: pointed used to allow other ioctls
+ */
struct v4l2_ioctl_ops {
/* ioctl callbacks */
diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h
index 7a8d6037a4bb..28c3f9d9c209 100644
--- a/include/media/v4l2-mc.h
+++ b/include/media/v4l2-mc.h
@@ -114,11 +114,14 @@ struct usb_device;
* Add links between the entities commonly found on PC customer's hardware at
* the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
* analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
- * NOTE: webcams are modelled on a very simple way: the sensor is
- * connected directly to the I/O entity. All dirty details, like
- * scaler and crop HW are hidden. While such mapping is enough for v4l2
- * interface centric PC-consumer's hardware, V4L2 subdev centric camera
- * hardware should not use this routine, as it will not build the right graph.
+ *
+ * .. note::
+ *
+ * Webcams are modelled on a very simple way: the sensor is
+ * connected directly to the I/O entity. All dirty details, like
+ * scaler and crop HW are hidden. While such mapping is enough for v4l2
+ * interface centric PC-consumer's hardware, V4L2 subdev centric camera
+ * hardware should not use this routine, as it will not build the right graph.
*/
int v4l2_mc_create_media_graph(struct media_device *mdev);
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index c672efc4f87b..2a2240c99b30 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -1,21 +1,17 @@
/*
- V4L2 sub-device support header.
-
- Copyright (C) 2008 Hans Verkuil <hverkuil@xs4all.nl>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ * V4L2 sub-device support header.
+ *
+ * Copyright (C) 2008 Hans Verkuil <hverkuil@xs4all.nl>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
*/
#ifndef _V4L2_SUBDEV_H
@@ -52,55 +48,64 @@ struct v4l2_subdev_fh;
struct tuner_setup;
struct v4l2_mbus_frame_desc;
-/* decode_vbi_line */
+/**
+ * struct v4l2_decode_vbi_line - used to decode_vbi_line
+ *
+ * @is_second_field: Set to 0 for the first (odd) field;
+ * set to 1 for the second (even) field.
+ * @p: Pointer to the sliced VBI data from the decoder. On exit, points to
+ * the start of the payload.
+ * @line: Line number of the sliced VBI data (1-23)
+ * @type: VBI service type (V4L2_SLICED_*). 0 if no service found
+ */
struct v4l2_decode_vbi_line {
- u32 is_second_field; /* Set to 0 for the first (odd) field,
- set to 1 for the second (even) field. */
- u8 *p; /* Pointer to the sliced VBI data from the decoder.
- On exit points to the start of the payload. */
- u32 line; /* Line number of the sliced VBI data (1-23) */
- u32 type; /* VBI service type (V4L2_SLICED_*). 0 if no service found */
+ u32 is_second_field;
+ u8 *p;
+ u32 line;
+ u32 type;
};
-/* Sub-devices are devices that are connected somehow to the main bridge
- device. These devices are usually audio/video muxers/encoders/decoders or
- sensors and webcam controllers.
-
- Usually these devices are controlled through an i2c bus, but other busses
- may also be used.
-
- The v4l2_subdev struct provides a way of accessing these devices in a
- generic manner. Most operations that these sub-devices support fall in
- a few categories: core ops, audio ops, video ops and tuner ops.
-
- More categories can be added if needed, although this should remain a
- limited set (no more than approx. 8 categories).
-
- Each category has its own set of ops that subdev drivers can implement.
-
- A subdev driver can leave the pointer to the category ops NULL if
- it does not implement them (e.g. an audio subdev will generally not
- implement the video category ops). The exception is the core category:
- this must always be present.
-
- These ops are all used internally so it is no problem to change, remove
- or add ops or move ops from one to another category. Currently these
- ops are based on the original ioctls, but since ops are not limited to
- one argument there is room for improvement here once all i2c subdev
- drivers are converted to use these ops.
+/*
+ * Sub-devices are devices that are connected somehow to the main bridge
+ * device. These devices are usually audio/video muxers/encoders/decoders or
+ * sensors and webcam controllers.
+ *
+ * Usually these devices are controlled through an i2c bus, but other busses
+ * may also be used.
+ *
+ * The v4l2_subdev struct provides a way of accessing these devices in a
+ * generic manner. Most operations that these sub-devices support fall in
+ * a few categories: core ops, audio ops, video ops and tuner ops.
+ *
+ * More categories can be added if needed, although this should remain a
+ * limited set (no more than approx. 8 categories).
+ *
+ * Each category has its own set of ops that subdev drivers can implement.
+ *
+ * A subdev driver can leave the pointer to the category ops NULL if
+ * it does not implement them (e.g. an audio subdev will generally not
+ * implement the video category ops). The exception is the core category:
+ * this must always be present.
+ *
+ * These ops are all used internally so it is no problem to change, remove
+ * or add ops or move ops from one to another category. Currently these
+ * ops are based on the original ioctls, but since ops are not limited to
+ * one argument there is room for improvement here once all i2c subdev
+ * drivers are converted to use these ops.
*/
-/* Core ops: it is highly recommended to implement at least these ops:
-
- log_status
- g_register
- s_register
-
- This provides basic debugging support.
-
- The ioctl ops is meant for generic ioctl-like commands. Depending on
- the use-case it might be better to use subdev-specific ops (currently
- not yet implemented) since ops provide proper type-checking.
+/*
+ * Core ops: it is highly recommended to implement at least these ops:
+ *
+ * log_status
+ * g_register
+ * s_register
+ *
+ * This provides basic debugging support.
+ *
+ * The ioctl ops is meant for generic ioctl-like commands. Depending on
+ * the use-case it might be better to use subdev-specific ops (currently
+ * not yet implemented) since ops provide proper type-checking.
*/
/* Subdevice external IO pin configuration */
@@ -110,18 +115,32 @@ struct v4l2_decode_vbi_line {
#define V4L2_SUBDEV_IO_PIN_SET_VALUE (1 << 3) /* Set output value */
#define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW (1 << 4) /* ACTIVE HIGH assumed */
+/**
+ * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
+ *
+ * @flags: bitmask with flags for this pin's config:
+ * %V4L2_SUBDEV_IO_PIN_DISABLE - disables a pin config,
+ * %V4L2_SUBDEV_IO_PIN_OUTPUT - if pin is an output,
+ * %V4L2_SUBDEV_IO_PIN_INPUT - if pin is an input,
+ * %V4L2_SUBDEV_IO_PIN_SET_VALUE - to set the output value via @value
+ * and %V4L2_SUBDEV_IO_PIN_ACTIVE_LOW - if active is 0.
+ * @pin: Chip external IO pin to configure
+ * @function: Internal signal pad/function to route to IO pin
+ * @value: Initial value for pin - e.g. GPIO output value
+ * @strength: Pin drive strength
+ */
struct v4l2_subdev_io_pin_config {
- u32 flags; /* V4L2_SUBDEV_IO_PIN_* flags for this pin's config */
- u8 pin; /* Chip external IO pin to configure */
- u8 function; /* Internal signal pad/function to route to IO pin */
- u8 value; /* Initial value for pin - e.g. GPIO output value */
- u8 strength; /* Pin drive strength */
+ u32 flags;
+ u8 pin;
+ u8 function;
+ u8 value;
+ u8 strength;
};
/**
* struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
*
- * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code.
+ * @log_status: callback for %VIDIOC_LOG_STATUS ioctl handler code.
*
* @s_io_pin_config: configure one or more chip I/O pins for chips that
* multiplex different internal signal pads out to IO pins. This function
@@ -149,9 +168,9 @@ struct v4l2_subdev_io_pin_config {
* @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
* in order to fix data passed from/to userspace.
*
- * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @g_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
*
- * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @s_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
*
* @s_power: puts subdevice in power saving mode (on == 0) or normal operation
* mode (on == 1).
@@ -159,7 +178,7 @@ struct v4l2_subdev_io_pin_config {
* @interrupt_service_routine: Called by the bridge chip's interrupt service
* handler, when an interrupt status has be raised due to this subdev,
* so that this subdev can handle the details. It may schedule work to be
- * performed later. It must not sleep. *Called from an IRQ context*.
+ * performed later. It must not sleep. **Called from an IRQ context**.
*
* @subscribe_event: used by the drivers to request the control framework that
* for it to be warned when the value of a control changes.
@@ -198,25 +217,25 @@ struct v4l2_subdev_core_ops {
/**
* struct s_radio - Callbacks used when v4l device was opened in radio mode.
*
- * @s_radio: callback for VIDIOC_S_RADIO ioctl handler code.
+ * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
*
- * @s_frequency: callback for VIDIOC_S_FREQUENCY ioctl handler code.
+ * @s_frequency: callback for %VIDIOC_S_FREQUENCY ioctl handler code.
*
- * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code.
- * freq->type must be filled in. Normally done by video_ioctl2
- * or the bridge driver.
+ * @g_frequency: callback for %VIDIOC_G_FREQUENCY ioctl handler code.
+ * freq->type must be filled in. Normally done by video_ioctl2()
+ * or the bridge driver.
*
- * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
+ * @enum_freq_bands: callback for %VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
*
- * @g_tuner: callback for VIDIOC_G_TUNER ioctl handler code.
+ * @g_tuner: callback for %VIDIOC_G_TUNER ioctl handler code.
*
- * @s_tuner: callback for VIDIOC_S_TUNER ioctl handler code. vt->type must be
+ * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. &vt->type must be
* filled in. Normally done by video_ioctl2 or the
- * bridge driver.
+ * bridge driver.
*
- * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code.
+ * @g_modulator: callback for %VIDIOC_G_MODULATOR ioctl handler code.
*
- * @s_modulator: callback for VIDIOC_S_MODULATOR ioctl handler code.
+ * @s_modulator: callback for %VIDIOC_S_MODULATOR ioctl handler code.
*
* @s_type_addr: sets tuner type and its I2C addr.
*
@@ -247,7 +266,7 @@ struct v4l2_subdev_tuner_ops {
* @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
* way to select I2S clock used by driving digital audio streams at some
* board designs. Usual values for the frequency are 1024000 and 2048000.
- * If the frequency is not supported, then -EINVAL is returned.
+ * If the frequency is not supported, then %-EINVAL is returned.
*
* @s_routing: used to define the input and/or output pins of an audio chip,
* and any additional configuration data.
@@ -279,7 +298,8 @@ struct v4l2_subdev_audio_ops {
/**
* struct v4l2_mbus_frame_desc_entry - media bus frame description structure
*
- * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags
+ * @flags: bitmask flags: %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX and
+ * %V4L2_MBUS_FRAME_DESC_FL_BLOB.
* @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
* @length: number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB
* is set
@@ -304,7 +324,7 @@ struct v4l2_mbus_frame_desc {
/**
* struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
- * in video mode.
+ * in video mode.
*
* @s_routing: see s_routing in audio_ops, except this version is for video
* devices.
@@ -314,9 +334,9 @@ struct v4l2_mbus_frame_desc {
* regarding clock frequency dividers, etc. If not used, then set flags
* to 0. If the frequency is not supported, then -EINVAL is returned.
*
- * @g_std: callback for VIDIOC_G_STD ioctl handler code.
+ * @g_std: callback for %VIDIOC_G_STD ioctl handler code.
*
- * @s_std: callback for VIDIOC_S_STD ioctl handler code.
+ * @s_std: callback for %VIDIOC_S_STD ioctl handler code.
*
* @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
* video input devices.
@@ -324,33 +344,33 @@ struct v4l2_mbus_frame_desc {
* @g_std_output: get current standard for video OUTPUT devices. This is ignored
* by video input devices.
*
- * @querystd: callback for VIDIOC_QUERYSTD ioctl handler code.
+ * @querystd: callback for %VIDIOC_QUERYSTD ioctl handler code.
*
- * @g_tvnorms: get v4l2_std_id with all standards supported by the video
+ * @g_tvnorms: get &v4l2_std_id with all standards supported by the video
* CAPTURE device. This is ignored by video output devices.
*
* @g_tvnorms_output: get v4l2_std_id with all standards supported by the video
* OUTPUT device. This is ignored by video capture devices.
*
- * @g_input_status: get input status. Same as the status field in the v4l2_input
- * struct.
+ * @g_input_status: get input status. Same as the status field in the
+ * &struct &v4l2_input
*
* @s_stream: used to notify the driver that a video stream will start or has
* stopped.
*
- * @cropcap: callback for VIDIOC_CROPCAP ioctl handler code.
+ * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code.
*
- * @g_crop: callback for VIDIOC_G_CROP ioctl handler code.
+ * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code.
*
- * @s_crop: callback for VIDIOC_S_CROP ioctl handler code.
+ * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code.
*
- * @g_parm: callback for VIDIOC_G_PARM ioctl handler code.
+ * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code.
*
- * @s_parm: callback for VIDIOC_S_PARM ioctl handler code.
+ * @s_parm: callback for %VIDIOC_S_PARM ioctl handler code.
*
- * @g_frame_interval: callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code.
+ * @g_frame_interval: callback for %VIDIOC_G_FRAMEINTERVAL ioctl handler code.
*
- * @s_frame_interval: callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code.
+ * @s_frame_interval: callback for %VIDIOC_S_FRAMEINTERVAL ioctl handler code.
*
* @s_dv_timings: Set custom dv timings in the sub device. This is used
* when sub device is capable of setting detailed timing information
@@ -358,7 +378,7 @@ struct v4l2_mbus_frame_desc {
*
* @g_dv_timings: Get custom dv timings in the sub device.
*
- * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
+ * @query_dv_timings: callback for %VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
*
* @g_mbus_config: get supported mediabus configurations
*
@@ -407,31 +427,31 @@ struct v4l2_subdev_video_ops {
/**
* struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
- * in video mode via the vbi device node.
+ * in video mode via the vbi device node.
*
* @decode_vbi_line: video decoders that support sliced VBI need to implement
- * this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
+ * this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the
* start of the VBI data that was generated by the decoder. The driver
* then parses the sliced VBI data and sets the other fields in the
* struct accordingly. The pointer p is updated to point to the start of
* the payload which can be copied verbatim into the data field of the
- * v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
+ * &struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the
* type field is set to 0 on return.
*
* @s_vbi_data: used to generate VBI signals on a video signal.
- * v4l2_sliced_vbi_data is filled with the data packets that should be
- * output. Note that if you set the line field to 0, then that VBI signal
- * is disabled. If no valid VBI data was found, then the type field is
- * set to 0 on return.
+ * &struct v4l2_sliced_vbi_data is filled with the data packets that
+ * should be output. Note that if you set the line field to 0, then that
+ * VBI signal is disabled. If no valid VBI data was found, then the type
+ * field is set to 0 on return.
*
* @g_vbi_data: used to obtain the sliced VBI packet from a readback register.
* Not all video decoders support this. If no data is available because
- * the readback register contains invalid or erroneous data -EIO is
+ * the readback register contains invalid or erroneous data %-EIO is
* returned. Note that you must fill in the 'id' member and the 'field'
* member (to determine whether CC data from the first or second field
* should be obtained).
*
- * @g_sliced_vbi_cap: callback for VIDIOC_SLICED_VBI_CAP ioctl handler code.
+ * @g_sliced_vbi_cap: callback for %VIDIOC_SLICED_VBI_CAP ioctl handler code.
*
* @s_raw_fmt: setup the video encoder/decoder for raw VBI.
*
@@ -464,58 +484,99 @@ struct v4l2_subdev_sensor_ops {
int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
};
-/*
- [rt]x_g_parameters: Get the current operating parameters and state of the
- the IR receiver or transmitter.
-
- [rt]x_s_parameters: Set the current operating parameters and state of the
- the IR receiver or transmitter. It is recommended to call
- [rt]x_g_parameters first to fill out the current state, and only change
- the fields that need to be changed. Upon return, the actual device
- operating parameters and state will be returned. Note that hardware
- limitations may prevent the actual settings from matching the requested
- settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
- was requested. An exception is when the shutdown parameter is true.
- The last used operational parameters will be returned, but the actual
- state of the hardware be different to minimize power consumption and
- processing when shutdown is true.
-
- rx_read: Reads received codes or pulse width data.
- The semantics are similar to a non-blocking read() call.
-
- tx_write: Writes codes or pulse width data for transmission.
- The semantics are similar to a non-blocking write() call.
+/**
+ * enum v4l2_subdev_ir_mode- describes the type of IR supported
+ *
+ * @V4L2_SUBDEV_IR_MODE_PULSE_WIDTH: IR uses struct ir_raw_event records
*/
-
enum v4l2_subdev_ir_mode {
- V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* uses struct ir_raw_event records */
+ V4L2_SUBDEV_IR_MODE_PULSE_WIDTH,
};
+/**
+ * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
+ *
+ * @bytes_per_data_element: bytes per data element of data in read or
+ * write call.
+ * @mode: IR mode as defined by &enum v4l2_subdev_ir_mode.
+ * @enable: device is active if true
+ * @interrupt_enable: IR interrupts are enabled if true
+ * @shutdown: if true: set hardware to low/no power, false: normal mode
+ *
+ * @modulation: if true, it uses carrier, if false: baseband
+ * @max_pulse_width: maximum pulse width in ns, valid only for baseband signal
+ * @carrier_freq: carrier frequency in Hz, valid only for modulated signal
+ * @duty_cycle: duty cycle percentage, valid only for modulated signal
+ * @invert_level: invert signal level
+ *
+ * @invert_carrier_sense: Send 0/space as a carrier burst. used only in TX.
+ *
+ * @noise_filter_min_width: min time of a valid pulse, in ns. Used only for RX.
+ * @carrier_range_lower: Lower carrier range, in Hz, valid only for modulated
+ * signal. Used only for RX.
+ * @carrier_range_upper: Upper carrier range, in Hz, valid only for modulated
+ * signal. Used only for RX.
+ * @resolution: The receive resolution, in ns . Used only for RX.
+ */
struct v4l2_subdev_ir_parameters {
- /* Either Rx or Tx */
- unsigned int bytes_per_data_element; /* of data in read or write call */
+ unsigned int bytes_per_data_element;
enum v4l2_subdev_ir_mode mode;
bool enable;
bool interrupt_enable;
- bool shutdown; /* true: set hardware to low/no power, false: normal */
+ bool shutdown;
- bool modulation; /* true: uses carrier, false: baseband */
- u32 max_pulse_width; /* ns, valid only for baseband signal */
- unsigned int carrier_freq; /* Hz, valid only for modulated signal*/
- unsigned int duty_cycle; /* percent, valid only for modulated signal*/
- bool invert_level; /* invert signal level */
+ bool modulation;
+ u32 max_pulse_width;
+ unsigned int carrier_freq;
+ unsigned int duty_cycle;
+ bool invert_level;
/* Tx only */
- bool invert_carrier_sense; /* Send 0/space as a carrier burst */
+ bool invert_carrier_sense;
/* Rx only */
- u32 noise_filter_min_width; /* ns, min time of a valid pulse */
- unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */
- unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */
- u32 resolution; /* ns */
+ u32 noise_filter_min_width;
+ unsigned int carrier_range_lower;
+ unsigned int carrier_range_upper;
+ u32 resolution;
};
+/**
+ * struct v4l2_subdev_ir_ops - operations for IR subdevices
+ *
+ * @rx_read: Reads received codes or pulse width data.
+ * The semantics are similar to a non-blocking read() call.
+ * @rx_g_parameters: Get the current operating parameters and state of the
+ * the IR receiver.
+ * @rx_s_parameters: Set the current operating parameters and state of the
+ * the IR receiver. It is recommended to call
+ * [rt]x_g_parameters first to fill out the current state, and only change
+ * the fields that need to be changed. Upon return, the actual device
+ * operating parameters and state will be returned. Note that hardware
+ * limitations may prevent the actual settings from matching the requested
+ * settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ * was requested. An exception is when the shutdown parameter is true.
+ * The last used operational parameters will be returned, but the actual
+ * state of the hardware be different to minimize power consumption and
+ * processing when shutdown is true.
+ *
+ * @tx_write: Writes codes or pulse width data for transmission.
+ * The semantics are similar to a non-blocking write() call.
+ * @tx_g_parameters: Get the current operating parameters and state of the
+ * the IR transmitter.
+ * @tx_s_parameters: Set the current operating parameters and state of the
+ * the IR transmitter. It is recommended to call
+ * [rt]x_g_parameters first to fill out the current state, and only change
+ * the fields that need to be changed. Upon return, the actual device
+ * operating parameters and state will be returned. Note that hardware
+ * limitations may prevent the actual settings from matching the requested
+ * settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ * was requested. An exception is when the shutdown parameter is true.
+ * The last used operational parameters will be returned, but the actual
+ * state of the hardware be different to minimize power consumption and
+ * processing when shutdown is true.
+ */
struct v4l2_subdev_ir_ops {
/* Receiver */
int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
@@ -536,11 +597,16 @@ struct v4l2_subdev_ir_ops {
struct v4l2_subdev_ir_parameters *params);
};
-/*
- * Used for storing subdev pad information. This structure only needs
- * to be passed to the pad op if the 'which' field of the main argument
- * is set to V4L2_SUBDEV_FORMAT_TRY. For V4L2_SUBDEV_FORMAT_ACTIVE it is
- * safe to pass NULL.
+/**
+ * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
+ *
+ * @try_fmt: pointer to &struct v4l2_mbus_framefmt
+ * @try_crop: pointer to &struct v4l2_rect to be used for crop
+ * @try_compose: pointer to &struct v4l2_rect to be used for compose
+ *
+ * This structure only needs to be passed to the pad op if the 'which' field
+ * of the main argument is set to %V4L2_SUBDEV_FORMAT_TRY. For
+ * %V4L2_SUBDEV_FORMAT_ACTIVE it is safe to pass %NULL.
*/
struct v4l2_subdev_pad_config {
struct v4l2_mbus_framefmt try_fmt;
@@ -552,30 +618,30 @@ struct v4l2_subdev_pad_config {
* struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
*
* @init_cfg: initialize the pad config to default values
- * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
+ * @enum_mbus_code: callback for %VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
* code.
- * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
+ * @enum_frame_size: callback for %VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
* code.
*
- * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
+ * @enum_frame_interval: callback for %VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
* handler code.
*
- * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT ioctl handler code.
+ * @get_fmt: callback for %VIDIOC_SUBDEV_G_FMT ioctl handler code.
*
- * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT ioctl handler code.
+ * @set_fmt: callback for %VIDIOC_SUBDEV_S_FMT ioctl handler code.
*
- * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
+ * @get_selection: callback for %VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
*
- * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
+ * @set_selection: callback for %VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
*
- * @get_edid: callback for VIDIOC_SUBDEV_G_EDID ioctl handler code.
+ * @get_edid: callback for %VIDIOC_SUBDEV_G_EDID ioctl handler code.
*
- * @set_edid: callback for VIDIOC_SUBDEV_S_EDID ioctl handler code.
+ * @set_edid: callback for %VIDIOC_SUBDEV_S_EDID ioctl handler code.
*
- * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
+ * @dv_timings_cap: callback for %VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
* code.
*
- * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
+ * @enum_dv_timings: callback for %VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
* code.
*
* @link_validate: used by the media controller code to check if the links
@@ -627,6 +693,18 @@ struct v4l2_subdev_pad_ops {
struct v4l2_mbus_frame_desc *fd);
};
+/**
+ * struct v4l2_subdev_ops - Subdev operations
+ *
+ * @core: pointer to &struct v4l2_subdev_core_ops. Can be %NULL
+ * @tuner: pointer to &struct v4l2_subdev_tuner_ops. Can be %NULL
+ * @audio: pointer to &struct v4l2_subdev_audio_ops. Can be %NULL
+ * @video: pointer to &struct v4l2_subdev_video_ops. Can be %NULL
+ * @vbi: pointer to &struct v4l2_subdev_vbi_ops. Can be %NULL
+ * @ir: pointer to &struct v4l2_subdev_ir_ops. Can be %NULL
+ * @sensor: pointer to &struct v4l2_subdev_sensor_ops. Can be %NULL
+ * @pad: pointer to &struct v4l2_subdev_pad_ops. Can be %NULL
+ */
struct v4l2_subdev_ops {
const struct v4l2_subdev_core_ops *core;
const struct v4l2_subdev_tuner_ops *tuner;
@@ -638,19 +716,22 @@ struct v4l2_subdev_ops {
const struct v4l2_subdev_pad_ops *pad;
};
-/*
- * Internal ops. Never call this from drivers, only the v4l2 framework can call
- * these ops.
+/**
+ * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
*
- * registered: called when this subdev is registered. When called the v4l2_dev
+ * @registered: called when this subdev is registered. When called the v4l2_dev
* field is set to the correct v4l2_device.
*
- * unregistered: called when this subdev is unregistered. When called the
+ * @unregistered: called when this subdev is unregistered. When called the
* v4l2_dev field is still set to the correct v4l2_device.
*
- * open: called when the subdev device node is opened by an application.
+ * @open: called when the subdev device node is opened by an application.
*
- * close: called when the subdev device node is closed.
+ * @close: called when the subdev device node is closed.
+ *
+ * .. note::
+ * Never call this from drivers, only the v4l2 framework can call
+ * these ops.
*/
struct v4l2_subdev_internal_ops {
int (*registered)(struct v4l2_subdev *sd);
@@ -672,17 +753,60 @@ struct v4l2_subdev_internal_ops {
struct regulator_bulk_data;
+/**
+ * struct v4l2_subdev_platform_data - regulators config struct
+ *
+ * @regulators: Optional regulators used to power on/off the subdevice
+ * @num_regulators: Number of regululators
+ * @host_priv: Per-subdevice data, specific for a certain video host device
+ */
struct v4l2_subdev_platform_data {
- /* Optional regulators uset to power on/off the subdevice */
struct regulator_bulk_data *regulators;
int num_regulators;
- /* Per-subdevice data, specific for a certain video host device */
void *host_priv;
};
-/* Each instance of a subdev driver should create this struct, either
- stand-alone or embedded in a larger struct.
+/**
+ * struct v4l2_subdev - describes a V4L2 sub-device
+ *
+ * @entity: pointer to &struct media_entity
+ * @list: List of sub-devices
+ * @owner: The owner is the same as the driver's &struct device owner.
+ * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev
+ * ownner. Initialized by v4l2_device_register_subdev().
+ * @flags: subdev flags. Can be:
+ * %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
+ * %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
+ * %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
+ * device node;
+ * %V4L2_SUBDEV_FL_HAS_EVENTS - Set this flag if this subdev generates
+ * events.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @ops: pointer to &struct v4l2_subdev_ops
+ * @internal_ops: pointer to &struct v4l2_subdev_internal_ops.
+ * Never call these internal ops from within a driver!
+ * @ctrl_handler: The control handler of this subdev. May be NULL.
+ * @name: Name of the sub-device. Please notice that the name must be unique.
+ * @grp_id: can be used to group similar subdevs. Value is driver-specific
+ * @dev_priv: pointer to private data
+ * @host_priv: pointer to private data used by the device where the subdev
+ * is attached.
+ * @devnode: subdev device node
+ * @dev: pointer to the physical device, if any
+ * @of_node: The device_node of the subdev, usually the same as dev->of_node.
+ * @async_list: Links this subdev to a global subdev_list or @notifier->done
+ * list.
+ * @asd: Pointer to respective &struct v4l2_async_subdev.
+ * @notifier: Pointer to the managing notifier.
+ * @pdata: common part of subdevice platform data
+ *
+ * Each instance of a subdev driver should create this struct, either
+ * stand-alone or embedded in a larger struct.
+ *
+ * This structure should be initialized by v4l2_subdev_init() or one of
+ * its variants: v4l2_spi_subdev_init(), v4l2_i2c_subdev_init().
*/
struct v4l2_subdev {
#if defined(CONFIG_MEDIA_CONTROLLER)
@@ -694,30 +818,18 @@ struct v4l2_subdev {
u32 flags;
struct v4l2_device *v4l2_dev;
const struct v4l2_subdev_ops *ops;
- /* Never call these internal ops from within a driver! */
const struct v4l2_subdev_internal_ops *internal_ops;
- /* The control handler of this subdev. May be NULL. */
struct v4l2_ctrl_handler *ctrl_handler;
- /* name must be unique */
char name[V4L2_SUBDEV_NAME_SIZE];
- /* can be used to group similar subdevs, value is driver-specific */
u32 grp_id;
- /* pointer to private data */
void *dev_priv;
void *host_priv;
- /* subdev device node */
struct video_device *devnode;
- /* pointer to the physical device, if any */
struct device *dev;
- /* The device_node of the subdev, usually the same as dev->of_node. */
struct device_node *of_node;
- /* Links this subdev to a global subdev_list or @notifier->done list. */
struct list_head async_list;
- /* Pointer to respective struct v4l2_async_subdev. */
struct v4l2_async_subdev *asd;
- /* Pointer to the managing notifier. */
struct v4l2_async_notifier *notifier;
- /* common part of subdevice platform data */
struct v4l2_subdev_platform_data *pdata;
};
@@ -726,8 +838,11 @@ struct v4l2_subdev {
#define vdev_to_v4l2_subdev(vdev) \
((struct v4l2_subdev *)video_get_drvdata(vdev))
-/*
- * Used for storing subdev information per file handle
+/**
+ * struct v4l2_subdev_fh - Used for storing subdev information per file handle
+ *
+ * @vfh: pointer to struct v4l2_fh
+ * @pad: pointer to v4l2_subdev_pad_config
*/
struct v4l2_subdev_fh {
struct v4l2_fh vfh;
@@ -757,53 +872,132 @@ __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
extern const struct v4l2_file_operations v4l2_subdev_fops;
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private device data to be stored.
+ */
static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
{
sd->dev_priv = p;
}
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private device data to be stored.
+ */
static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
{
return sd->dev_priv;
}
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private host data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private data to be stored.
+ */
static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
{
sd->host_priv = p;
}
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private host data to be stored.
+ */
static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)
{
return sd->host_priv;
}
#ifdef CONFIG_MEDIA_CONTROLLER
+
+/**
+ * v4l2_subdev_link_validate_default - validates a media link
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @link: pointer to &struct media_link
+ * @source_fmt: pointer to &struct v4l2_subdev_format
+ * @sink_fmt: pointer to &struct v4l2_subdev_format
+ *
+ * This function ensures that width, height and the media bus pixel
+ * code are equal on both source and sink of the link.
+ */
int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
struct media_link *link,
struct v4l2_subdev_format *source_fmt,
struct v4l2_subdev_format *sink_fmt);
+
+/**
+ * v4l2_subdev_link_validate - validates a media link
+ *
+ * @link: pointer to &struct media_link
+ *
+ * This function calls the subdev's link_validate ops to validate
+ * if a media link is valid for streaming. It also internally
+ * calls v4l2_subdev_link_validate_default() to ensure that
+ * width, height and the media bus pixel code are equal on both
+ * source and sink of the link.
+ */
int v4l2_subdev_link_validate(struct media_link *link);
-struct v4l2_subdev_pad_config *
-v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+/**
+ * v4l2_subdev_alloc_pad_config - Allocates memory for pad config
+ *
+ * @sd: pointer to struct v4l2_subdev
+ */
+struct
+v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_subdev_free_pad_config - Frees memory allocated by
+ * v4l2_subdev_alloc_pad_config().
+ *
+ * @cfg: pointer to &struct v4l2_subdev_pad_config
+ */
void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
#endif /* CONFIG_MEDIA_CONTROLLER */
+/**
+ * v4l2_subdev_init - initializes the sub-device struct
+ *
+ * @sd: pointer to the &struct v4l2_subdev to be initialized
+ * @ops: pointer to &struct v4l2_subdev_ops.
+ */
void v4l2_subdev_init(struct v4l2_subdev *sd,
const struct v4l2_subdev_ops *ops);
-/* Call an ops of a v4l2_subdev, doing the right checks against
- NULL pointers.
-
- Example: err = v4l2_subdev_call(sd, video, s_std, norm);
+/*
+ * Call an ops of a v4l2_subdev, doing the right checks against
+ * NULL pointers.
+ *
+ * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
*/
#define v4l2_subdev_call(sd, o, f, args...) \
(!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ? \
- (sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD))
+ (sd)->ops->o->f((sd), ##args) : -ENOIOCTLCMD))
#define v4l2_subdev_has_op(sd, o, f) \
((sd)->ops->o && (sd)->ops->o->f)
+/**
+ * v4l2_subdev_notify_event() - Delivers event notification for subdevice
+ * @sd: The subdev for which to deliver the event
+ * @ev: The event to deliver
+ *
+ * Will deliver the specified event to all userspace event listeners which are
+ * subscribed to the v42l subdev event queue as well as to the bridge driver
+ * using the notify callback. The notification type for the notify callback
+ * will be %V4L2_DEVICE_NOTIFY_EVENT.
+ */
void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
const struct v4l2_event *ev);
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index bea81c9e3758..946340ce7701 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -85,11 +85,17 @@ struct vb2_threadio_data;
* @mmap: setup a userspace mapping for a given memory buffer under
* the provided virtual memory region.
*
- * Required ops for USERPTR types: get_userptr, put_userptr.
- * Required ops for MMAP types: alloc, put, num_users, mmap.
- * Required ops for read/write access types: alloc, put, num_users, vaddr.
- * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
- * unmap_dmabuf.
+ * Those operations are used by the videobuf2 core to implement the memory
+ * handling/memory allocators for each type of supported streaming I/O method.
+ *
+ * .. note::
+ * #) Required ops for USERPTR types: get_userptr, put_userptr.
+ *
+ * #) Required ops for MMAP types: alloc, put, num_users, mmap.
+ *
+ * #) Required ops for read/write access types: alloc, put, num_users, vaddr.
+ *
+ * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
*/
struct vb2_mem_ops {
void *(*alloc)(struct device *dev, const struct dma_attrs *attrs,
@@ -271,26 +277,26 @@ struct vb2_buffer {
/**
* struct vb2_ops - driver-specific callbacks
*
- * @queue_setup: called from VIDIOC_REQBUFS and VIDIOC_CREATE_BUFS
+ * @queue_setup: called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS
* handlers before memory allocation. It can be called
* twice: if the original number of requested buffers
* could not be allocated, then it will be called a
* second time with the actually allocated number of
* buffers to verify if that is OK.
* The driver should return the required number of buffers
- * in *num_buffers, the required number of planes per
- * buffer in *num_planes, the size of each plane should be
- * set in the sizes[] array and optional per-plane
- * allocator specific device in the alloc_devs[] array.
- * When called from VIDIOC_REQBUFS, *num_planes == 0, the
+ * in \*num_buffers, the required number of planes per
+ * buffer in \*num_planes, the size of each plane should be
+ * set in the sizes\[\] array and optional per-plane
+ * allocator specific device in the alloc_devs\[\] array.
+ * When called from %VIDIOC_REQBUFS, \*num_planes == 0, the
* driver has to use the currently configured format to
- * determine the plane sizes and *num_buffers is the total
+ * determine the plane sizes and \*num_buffers is the total
* number of buffers that are being allocated. When called
- * from VIDIOC_CREATE_BUFS, *num_planes != 0 and it
- * describes the requested number of planes and sizes[]
+ * from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
+ * describes the requested number of planes and sizes\[\]
* contains the requested plane sizes. If either
- * *num_planes or the requested sizes are invalid callback
- * must return -EINVAL. In this case *num_buffers are
+ * \*num_planes or the requested sizes are invalid callback
+ * must return %-EINVAL. In this case \*num_buffers are
* being allocated additionally to q->num_buffers.
* @wait_prepare: release any locks taken while calling vb2 functions;
* it is called before an ioctl needs to wait for a new
@@ -305,11 +311,11 @@ struct vb2_buffer {
* initialization failure (return != 0) will prevent
* queue setup from completing successfully; optional.
* @buf_prepare: called every time the buffer is queued from userspace
- * and from the VIDIOC_PREPARE_BUF ioctl; drivers may
+ * and from the %VIDIOC_PREPARE_BUF ioctl; drivers may
* perform any initialization required before each
* hardware operation in this callback; drivers can
* access/modify the buffer here as it is still synced for
- * the CPU; drivers that support VIDIOC_CREATE_BUFS must
+ * the CPU; drivers that support %VIDIOC_CREATE_BUFS must
* also validate the buffer size; if an error is returned,
* the buffer will not be queued in driver; optional.
* @buf_finish: called before every dequeue of the buffer back to
@@ -317,23 +323,23 @@ struct vb2_buffer {
* can access/modify the buffer contents; drivers may
* perform any operations required before userspace
* accesses the buffer; optional. The buffer state can be
- * one of the following: DONE and ERROR occur while
- * streaming is in progress, and the PREPARED state occurs
+ * one of the following: %DONE and %ERROR occur while
+ * streaming is in progress, and the %PREPARED state occurs
* when the queue has been canceled and all pending
- * buffers are being returned to their default DEQUEUED
+ * buffers are being returned to their default %DEQUEUED
* state. Typically you only have to do something if the
- * state is VB2_BUF_STATE_DONE, since in all other cases
+ * state is %VB2_BUF_STATE_DONE, since in all other cases
* the buffer contents will be ignored anyway.
* @buf_cleanup: called once before the buffer is freed; drivers may
* perform any additional cleanup; optional.
* @start_streaming: called once to enter 'streaming' state; the driver may
- * receive buffers with @buf_queue callback before
- * @start_streaming is called; the driver gets the number
- * of already queued buffers in count parameter; driver
- * can return an error if hardware fails, in that case all
- * buffers that have been already given by the @buf_queue
- * callback are to be returned by the driver by calling
- * @vb2_buffer_done(VB2_BUF_STATE_QUEUED).
+ * receive buffers with @buf_queue callback
+ * before @start_streaming is called; the driver gets the
+ * number of already queued buffers in count parameter;
+ * driver can return an error if hardware fails, in that
+ * case all buffers that have been already given by
+ * the @buf_queue callback are to be returned by the driver
+ * by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\).
* If you need a minimum number of buffers before you can
* start streaming, then set @min_buffers_needed in the
* vb2_queue structure. If that is non-zero then
@@ -341,16 +347,16 @@ struct vb2_buffer {
* many buffers have been queued up by userspace.
* @stop_streaming: called when 'streaming' state must be disabled; driver
* should stop any DMA transactions or wait until they
- * finish and give back all buffers it got from buf_queue()
- * callback by calling @vb2_buffer_done() with either
- * VB2_BUF_STATE_DONE or VB2_BUF_STATE_ERROR; may use
+ * finish and give back all buffers it got from &buf_queue
+ * callback by calling @vb2_buffer_done\(\) with either
+ * %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
* vb2_wait_for_all_buffers() function
* @buf_queue: passes buffer vb to the driver; driver may start
* hardware operation on this buffer; driver should give
* the buffer back by calling vb2_buffer_done() function;
- * it is allways called after calling STREAMON ioctl;
+ * it is allways called after calling %VIDIOC_STREAMON ioctl;
* might be called before start_streaming callback if user
- * pre-queued buffers before calling STREAMON.
+ * pre-queued buffers before calling %VIDIOC_STREAMON.
*/
struct vb2_ops {
int (*queue_setup)(struct vb2_queue *q,
diff --git a/include/uapi/linux/lirc.h b/include/uapi/linux/lirc.h
index 4b3ab2966b5a..991ab4570b8e 100644
--- a/include/uapi/linux/lirc.h
+++ b/include/uapi/linux/lirc.h
@@ -90,20 +90,11 @@
#define LIRC_GET_SEND_MODE _IOR('i', 0x00000001, __u32)
#define LIRC_GET_REC_MODE _IOR('i', 0x00000002, __u32)
-#define LIRC_GET_SEND_CARRIER _IOR('i', 0x00000003, __u32)
-#define LIRC_GET_REC_CARRIER _IOR('i', 0x00000004, __u32)
-#define LIRC_GET_SEND_DUTY_CYCLE _IOR('i', 0x00000005, __u32)
-#define LIRC_GET_REC_DUTY_CYCLE _IOR('i', 0x00000006, __u32)
#define LIRC_GET_REC_RESOLUTION _IOR('i', 0x00000007, __u32)
#define LIRC_GET_MIN_TIMEOUT _IOR('i', 0x00000008, __u32)
#define LIRC_GET_MAX_TIMEOUT _IOR('i', 0x00000009, __u32)
-#define LIRC_GET_MIN_FILTER_PULSE _IOR('i', 0x0000000a, __u32)
-#define LIRC_GET_MAX_FILTER_PULSE _IOR('i', 0x0000000b, __u32)
-#define LIRC_GET_MIN_FILTER_SPACE _IOR('i', 0x0000000c, __u32)
-#define LIRC_GET_MAX_FILTER_SPACE _IOR('i', 0x0000000d, __u32)
-
/* code length in bits, currently only for LIRC_MODE_LIRCCODE */
#define LIRC_GET_LENGTH _IOR('i', 0x0000000f, __u32)
@@ -113,7 +104,6 @@
#define LIRC_SET_SEND_CARRIER _IOW('i', 0x00000013, __u32)
#define LIRC_SET_REC_CARRIER _IOW('i', 0x00000014, __u32)
#define LIRC_SET_SEND_DUTY_CYCLE _IOW('i', 0x00000015, __u32)
-#define LIRC_SET_REC_DUTY_CYCLE _IOW('i', 0x00000016, __u32)
#define LIRC_SET_TRANSMITTER_MASK _IOW('i', 0x00000017, __u32)
/*
@@ -127,42 +117,17 @@
#define LIRC_SET_REC_TIMEOUT_REPORTS _IOW('i', 0x00000019, __u32)
/*
- * pulses shorter than this are filtered out by hardware (software
- * emulation in lirc_dev?)
- */
-#define LIRC_SET_REC_FILTER_PULSE _IOW('i', 0x0000001a, __u32)
-/*
- * spaces shorter than this are filtered out by hardware (software
- * emulation in lirc_dev?)
- */
-#define LIRC_SET_REC_FILTER_SPACE _IOW('i', 0x0000001b, __u32)
-/*
- * if filter cannot be set independently for pulse/space, this should
- * be used
- */
-#define LIRC_SET_REC_FILTER _IOW('i', 0x0000001c, __u32)
-
-/*
* if enabled from the next key press on the driver will send
* LIRC_MODE2_FREQUENCY packets
*/
#define LIRC_SET_MEASURE_CARRIER_MODE _IOW('i', 0x0000001d, __u32)
/*
- * to set a range use
- * LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE with the
- * lower bound first and later
- * LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper bound
+ * to set a range use LIRC_SET_REC_CARRIER_RANGE with the
+ * lower bound first and later LIRC_SET_REC_CARRIER with the upper bound
*/
-
-#define LIRC_SET_REC_DUTY_CYCLE_RANGE _IOW('i', 0x0000001e, __u32)
#define LIRC_SET_REC_CARRIER_RANGE _IOW('i', 0x0000001f, __u32)
-#define LIRC_NOTIFY_DECODE _IO('i', 0x00000020)
-
-#define LIRC_SETUP_START _IO('i', 0x00000021)
-#define LIRC_SETUP_END _IO('i', 0x00000022)
-
#define LIRC_SET_WIDEBAND_RECEIVER _IOW('i', 0x00000023, __u32)
#endif