diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-27 13:45:04 (GMT) |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-07-27 13:45:04 (GMT) |
commit | 85538b1ad145c67198cb55d02de14ba269cc323d (patch) | |
tree | 409fca93b357839b8c89b7099f2888c087694b64 /include/media | |
parent | 9c1958fc326a0a0a533ec8e86ea6fa30977207de (diff) | |
parent | d271d3d9b333c94cd54a12fa506e17772a04617c (diff) | |
download | linux-85538b1ad145c67198cb55d02de14ba269cc323d.tar.xz |
Merge branch 'topic/docs-next' into v4l_for_linus
* topic/docs-next: (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/media')
-rw-r--r-- | include/media/lirc_dev.h | 2 | ||||
-rw-r--r-- | include/media/media-device.h | 255 | ||||
-rw-r--r-- | include/media/media-entity.h | 89 | ||||
-rw-r--r-- | include/media/rc-core.h | 45 | ||||
-rw-r--r-- | include/media/rc-map.h | 17 | ||||
-rw-r--r-- | include/media/tuner-types.h | 8 | ||||
-rw-r--r-- | include/media/tveeprom.h | 18 | ||||
-rw-r--r-- | include/media/v4l2-async.h | 39 | ||||
-rw-r--r-- | include/media/v4l2-common.h | 92 | ||||
-rw-r--r-- | include/media/v4l2-ctrls.h | 369 | ||||
-rw-r--r-- | include/media/v4l2-dev.h | 364 | ||||
-rw-r--r-- | include/media/v4l2-device.h | 198 | ||||
-rw-r--r-- | include/media/v4l2-dv-timings.h | 2 | ||||
-rw-r--r-- | include/media/v4l2-event.h | 125 | ||||
-rw-r--r-- | include/media/v4l2-fh.h | 128 | ||||
-rw-r--r-- | include/media/v4l2-ioctl.h | 266 | ||||
-rw-r--r-- | include/media/v4l2-mc.h | 13 | ||||
-rw-r--r-- | include/media/v4l2-subdev.h | 576 | ||||
-rw-r--r-- | include/media/videobuf2-core.h | 74 |
19 files changed, 1911 insertions, 769 deletions
diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h index 0ab59a5..cec7d35 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 f743ae2..2819524 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 cbb266f..09b03c1 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 324232c..10908e3 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 a459129..daa75fc 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 094e112..aed5390 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 8be8987..c56501ee 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 1d6d7da..8e2a236 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 1cc0c5b..350cbf9 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 8b59336..178a88d 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 25a3190..a122b1b 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 d5d45a8..a9d6aa4 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 1113c88..65caadf 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 9792f90..ca85420 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 8035167..e19e624 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 017ffb2..8b1d19b 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 7a8d603..28c3f9d 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 c672efc..2a2240c 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 bea81c9e..946340c 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, |