diff options
Diffstat (limited to 'include/media')
30 files changed, 2379 insertions, 879 deletions
diff --git a/include/media/cec-edid.h b/include/media/cec-edid.h new file mode 100644 index 000000000..bdf731ecb --- /dev/null +++ b/include/media/cec-edid.h @@ -0,0 +1,104 @@ +/* + * cec-edid - HDMI Consumer Electronics Control & EDID helpers + * + * Copyright 2016 Cisco Systems, Inc. and/or its affiliates. All rights reserved. + * + * This program is free software; you may redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef _MEDIA_CEC_EDID_H +#define _MEDIA_CEC_EDID_H + +#include <linux/types.h> + +#define CEC_PHYS_ADDR_INVALID 0xffff +#define cec_phys_addr_exp(pa) \ + ((pa) >> 12), ((pa) >> 8) & 0xf, ((pa) >> 4) & 0xf, (pa) & 0xf + +/** + * cec_get_edid_phys_addr() - find and return the physical address + * + * @edid: pointer to the EDID data + * @size: size in bytes of the EDID data + * @offset: If not %NULL then the location of the physical address + * bytes in the EDID will be returned here. This is set to 0 + * if there is no physical address found. + * + * Return: the physical address or CEC_PHYS_ADDR_INVALID if there is none. + */ +u16 cec_get_edid_phys_addr(const u8 *edid, unsigned int size, + unsigned int *offset); + +/** + * cec_set_edid_phys_addr() - find and set the physical address + * + * @edid: pointer to the EDID data + * @size: size in bytes of the EDID data + * @phys_addr: the new physical address + * + * This function finds the location of the physical address in the EDID + * and fills in the given physical address and updates the checksum + * at the end of the EDID block. It does nothing if the EDID doesn't + * contain a physical address. + */ +void cec_set_edid_phys_addr(u8 *edid, unsigned int size, u16 phys_addr); + +/** + * cec_phys_addr_for_input() - calculate the PA for an input + * + * @phys_addr: the physical address of the parent + * @input: the number of the input port, must be between 1 and 15 + * + * This function calculates a new physical address based on the input + * port number. For example: + * + * PA = 0.0.0.0 and input = 2 becomes 2.0.0.0 + * + * PA = 3.0.0.0 and input = 1 becomes 3.1.0.0 + * + * PA = 3.2.1.0 and input = 5 becomes 3.2.1.5 + * + * PA = 3.2.1.3 and input = 5 becomes f.f.f.f since it maxed out the depth. + * + * Return: the new physical address or CEC_PHYS_ADDR_INVALID. + */ +u16 cec_phys_addr_for_input(u16 phys_addr, u8 input); + +/** + * cec_phys_addr_validate() - validate a physical address from an EDID + * + * @phys_addr: the physical address to validate + * @parent: if not %NULL, then this is filled with the parents PA. + * @port: if not %NULL, then this is filled with the input port. + * + * This validates a physical address as read from an EDID. If the + * PA is invalid (such as 1.0.1.0 since '0' is only allowed at the end), + * then it will return -EINVAL. + * + * The parent PA is passed into %parent and the input port is passed into + * %port. For example: + * + * PA = 0.0.0.0: has parent 0.0.0.0 and input port 0. + * + * PA = 1.0.0.0: has parent 0.0.0.0 and input port 1. + * + * PA = 3.2.0.0: has parent 3.0.0.0 and input port 2. + * + * PA = f.f.f.f: has parent f.f.f.f and input port 0. + * + * Return: 0 if the PA is valid, -EINVAL if not. + */ +int cec_phys_addr_validate(u16 phys_addr, u16 *parent, u16 *port); + +#endif /* _MEDIA_CEC_EDID_H */ diff --git a/include/media/cec.h b/include/media/cec.h new file mode 100644 index 000000000..fdb5d600e --- /dev/null +++ b/include/media/cec.h @@ -0,0 +1,241 @@ +/* + * cec - HDMI Consumer Electronics Control support header + * + * Copyright 2016 Cisco Systems, Inc. and/or its affiliates. All rights reserved. + * + * This program is free software; you may redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef _MEDIA_CEC_H +#define _MEDIA_CEC_H + +#include <linux/poll.h> +#include <linux/fs.h> +#include <linux/debugfs.h> +#include <linux/device.h> +#include <linux/cdev.h> +#include <linux/kthread.h> +#include <linux/timer.h> +#include <linux/cec-funcs.h> +#include <media/rc-core.h> +#include <media/cec-edid.h> + +/** + * struct cec_devnode - cec device node + * @dev: cec device + * @cdev: cec character device + * @parent: parent device + * @minor: device node minor number + * @registered: the device was correctly registered + * @unregistered: the device was unregistered + * @fhs_lock: lock to control access to the filehandle list + * @fhs: the list of open filehandles (cec_fh) + * + * This structure represents a cec-related device node. + * + * The @parent is a physical device. It must be set by core or device drivers + * before registering the node. + */ +struct cec_devnode { + /* sysfs */ + struct device dev; + struct cdev cdev; + struct device *parent; + + /* device info */ + int minor; + bool registered; + bool unregistered; + struct list_head fhs; + struct mutex lock; +}; + +struct cec_adapter; +struct cec_data; + +struct cec_data { + struct list_head list; + struct list_head xfer_list; + struct cec_adapter *adap; + struct cec_msg msg; + struct cec_fh *fh; + struct delayed_work work; + struct completion c; + u8 attempts; + bool new_initiator; + bool blocking; + bool completed; +}; + +struct cec_msg_entry { + struct list_head list; + struct cec_msg msg; +}; + +#define CEC_NUM_EVENTS CEC_EVENT_LOST_MSGS + +struct cec_fh { + struct list_head list; + struct list_head xfer_list; + struct cec_adapter *adap; + u8 mode_initiator; + u8 mode_follower; + + /* Events */ + wait_queue_head_t wait; + unsigned int pending_events; + struct cec_event events[CEC_NUM_EVENTS]; + struct mutex lock; + struct list_head msgs; /* queued messages */ + unsigned int queued_msgs; +}; + +#define CEC_SIGNAL_FREE_TIME_RETRY 3 +#define CEC_SIGNAL_FREE_TIME_NEW_INITIATOR 5 +#define CEC_SIGNAL_FREE_TIME_NEXT_XFER 7 + +/* The nominal data bit period is 2.4 ms */ +#define CEC_FREE_TIME_TO_USEC(ft) ((ft) * 2400) + +struct cec_adap_ops { + /* Low-level callbacks */ + int (*adap_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); + + /* High-level CEC message callback */ + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); +}; + +/* + * The minimum message length you can receive (excepting poll messages) is 2. + * With a transfer rate of at most 36 bytes per second this makes 18 messages + * per second worst case. + * + * We queue at most 3 seconds worth of received messages. The CEC specification + * requires that messages are replied to within a second, so 3 seconds should + * give more than enough margin. Since most messages are actually more than 2 + * bytes, this is in practice a lot more than 3 seconds. + */ +#define CEC_MAX_MSG_RX_QUEUE_SZ (18 * 3) + +/* + * The transmit queue is limited to 1 second worth of messages (worst case). + * Messages can be transmitted by userspace and kernel space. But for both it + * makes no sense to have a lot of messages queued up. One second seems + * reasonable. + */ +#define CEC_MAX_MSG_TX_QUEUE_SZ (18 * 1) + +struct cec_adapter { + struct module *owner; + char name[32]; + struct cec_devnode devnode; + struct mutex lock; + struct rc_dev *rc; + + struct list_head transmit_queue; + unsigned int transmit_queue_sz; + struct list_head wait_queue; + struct cec_data *transmitting; + + struct task_struct *kthread_config; + struct completion config_completion; + + struct task_struct *kthread; + wait_queue_head_t kthread_waitq; + wait_queue_head_t waitq; + + const struct cec_adap_ops *ops; + void *priv; + u32 capabilities; + u8 available_log_addrs; + + u16 phys_addr; + bool is_configuring; + bool is_configured; + u32 monitor_all_cnt; + u32 follower_cnt; + struct cec_fh *cec_follower; + struct cec_fh *cec_initiator; + bool passthrough; + struct cec_log_addrs log_addrs; + + struct dentry *cec_dir; + struct dentry *status_file; + + u16 phys_addrs[15]; + u32 sequence; + + char input_name[32]; + char input_phys[32]; + char input_drv[32]; +}; + +static inline bool cec_has_log_addr(const struct cec_adapter *adap, u8 log_addr) +{ + return adap->log_addrs.log_addr_mask & (1 << log_addr); +} + +static inline bool cec_is_sink(const struct cec_adapter *adap) +{ + return adap->phys_addr == 0; +} + +#if IS_ENABLED(CONFIG_MEDIA_CEC) +struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, + void *priv, const char *name, u32 caps, u8 available_las, + struct device *parent); +int cec_register_adapter(struct cec_adapter *adap); +void cec_unregister_adapter(struct cec_adapter *adap); +void cec_delete_adapter(struct cec_adapter *adap); + +int cec_s_log_addrs(struct cec_adapter *adap, struct cec_log_addrs *log_addrs, + bool block); +void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, + bool block); +int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, + bool block); + +/* Called by the adapter */ +void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, + u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); +void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); + +#else + +static inline int cec_register_adapter(struct cec_adapter *adap) +{ + return 0; +} + +static inline void cec_unregister_adapter(struct cec_adapter *adap) +{ +} + +static inline void cec_delete_adapter(struct cec_adapter *adap) +{ +} + +static inline void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, + bool block) +{ +} + +#endif + +#endif /* _MEDIA_CEC_H */ diff --git a/include/media/davinci/vpbe_display.h b/include/media/davinci/vpbe_display.h index e14a9370b..12783fd82 100644 --- a/include/media/davinci/vpbe_display.h +++ b/include/media/davinci/vpbe_display.h @@ -81,8 +81,6 @@ struct vpbe_layer { * Buffer queue used in video-buf */ struct vb2_queue buffer_queue; - /* allocator-specific contexts for each plane */ - struct vb2_alloc_ctx *alloc_ctx; /* Queue of filled frames */ struct list_head dma_queue; /* Used in video-buf */ diff --git a/include/media/i2c/adv7511.h b/include/media/i2c/adv7511.h index d83b91d80..61c3d711c 100644 --- a/include/media/i2c/adv7511.h +++ b/include/media/i2c/adv7511.h @@ -32,11 +32,7 @@ struct adv7511_monitor_detect { struct adv7511_edid_detect { int present; int segment; -}; - -struct adv7511_cec_arg { - void *arg; - u32 f_flags; + uint16_t phys_addr; }; struct adv7511_platform_data { diff --git a/include/media/i2c/adv7604.h b/include/media/i2c/adv7604.h index a913859bf..2e6857dee 100644 --- a/include/media/i2c/adv7604.h +++ b/include/media/i2c/adv7604.h @@ -121,8 +121,6 @@ struct adv76xx_platform_data { /* IO register 0x02 */ unsigned alt_gamma:1; - unsigned op_656_range:1; - unsigned alt_data_sat:1; /* IO register 0x05 */ unsigned blank_data:1; diff --git a/include/media/i2c/adv7842.h b/include/media/i2c/adv7842.h index bc249709b..7f53ada9b 100644 --- a/include/media/i2c/adv7842.h +++ b/include/media/i2c/adv7842.h @@ -165,8 +165,6 @@ struct adv7842_platform_data { /* IO register 0x02 */ unsigned alt_gamma:1; - unsigned op_656_range:1; - unsigned alt_data_sat:1; /* IO register 0x05 */ unsigned blank_data:1; diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h index 0ab59a571..cec7d3560 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 a9b33c473..281952423 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; @@ -347,7 +116,7 @@ struct media_entity_notify { struct media_device { /* dev->driver_data points to this struct. */ struct device *dev; - struct media_devnode devnode; + struct media_devnode *devnode; char model[32]; char driver_name[32]; @@ -393,9 +162,6 @@ struct usb_device; #define MEDIA_DEV_NOTIFY_PRE_LINK_CH 0 #define MEDIA_DEV_NOTIFY_POST_LINK_CH 1 -/* media_devnode to media_device */ -#define to_media_device(node) container_of(node, struct media_device, devnode) - /** * media_entity_enum_init - Initialise an entity enumeration * @@ -476,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. */ @@ -530,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 @@ -551,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-devnode.h b/include/media/media-devnode.h index fe42f08e7..37d494805 100644 --- a/include/media/media-devnode.h +++ b/include/media/media-devnode.h @@ -33,6 +33,8 @@ #include <linux/device.h> #include <linux/cdev.h> +struct media_device; + /* * Flag to mark the media_devnode struct as registered. Drivers must not touch * this flag directly, it will be set and cleared by media_devnode_register and @@ -67,8 +69,9 @@ struct media_file_operations { /** * struct media_devnode - Media device node + * @media_dev: pointer to struct &media_device * @fops: pointer to struct &media_file_operations with media device ops - * @dev: struct device pointer for the media controller device + * @dev: pointer to struct &device containing the media controller device * @cdev: struct cdev pointer character device * @parent: parent device * @minor: device node minor number @@ -81,6 +84,8 @@ struct media_file_operations { * before registering the node. */ struct media_devnode { + struct media_device *media_dev; + /* device ops */ const struct media_file_operations *fops; @@ -94,7 +99,7 @@ struct media_devnode { unsigned long flags; /* Use bitops to access flags */ /* callbacks */ - void (*release)(struct media_devnode *mdev); + void (*release)(struct media_devnode *devnode); }; /* dev to media_devnode */ @@ -103,7 +108,8 @@ struct media_devnode { /** * media_devnode_register - register a media device node * - * @mdev: media device node structure we want to register + * @mdev: struct media_device we want to register a device node + * @devnode: media device node structure we want to register * @owner: should be filled with %THIS_MODULE * * The registration code assigns minor numbers and registers the new device node @@ -116,20 +122,33 @@ struct media_devnode { * the media_devnode structure is *not* called, so the caller is responsible for * freeing any data. */ -int __must_check media_devnode_register(struct media_devnode *mdev, +int __must_check media_devnode_register(struct media_device *mdev, + struct media_devnode *devnode, struct module *owner); /** + * media_devnode_unregister_prepare - clear the media device node register bit + * @devnode: the device node to prepare for unregister + * + * This clears the passed device register bit. Future open calls will be met + * with errors. Should be called before media_devnode_unregister() to avoid + * races with unregister and device file open calls. + * + * This function can safely be called if the device node has never been + * registered or has already been unregistered. + */ +void media_devnode_unregister_prepare(struct media_devnode *devnode); + +/** * media_devnode_unregister - unregister a media device node - * @mdev: the device node to unregister + * @devnode: the device node to unregister * * This unregisters the passed device. Future open calls will be met with * errors. * - * This function can safely be called if the device node has never been - * registered or has already been unregistered. + * Should be called after media_devnode_unregister_prepare() */ -void media_devnode_unregister(struct media_devnode *mdev); +void media_devnode_unregister(struct media_devnode *devnode); /** * media_devnode_data - returns a pointer to the &media_devnode @@ -145,11 +164,16 @@ static inline struct media_devnode *media_devnode_data(struct file *filp) * media_devnode_is_registered - returns true if &media_devnode is registered; * false otherwise. * - * @mdev: pointer to struct &media_devnode. + * @devnode: pointer to struct &media_devnode. + * + * Note: If mdev is NULL, it also returns false. */ -static inline int media_devnode_is_registered(struct media_devnode *mdev) +static inline int media_devnode_is_registered(struct media_devnode *devnode) { - return test_bit(MEDIA_FLAG_REGISTERED, &mdev->flags); + if (!devnode) + return false; + + return test_bit(MEDIA_FLAG_REGISTERED, &devnode->flags); } #endif /* _MEDIA_DEVNODE_H */ diff --git a/include/media/media-entity.h b/include/media/media-entity.h index cbb266f7f..09b03c177 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 b6586a911..10908e356 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, }; /** @@ -119,6 +126,7 @@ enum rc_filter_type { * @s_carrier_report: enable carrier reports * @s_filter: set the scancode filter * @s_wakeup_filter: set the wakeup scancode filter + * @s_timeout: set hardware timeout in ns */ struct rc_dev { struct device dev; @@ -174,6 +182,8 @@ struct rc_dev { struct rc_scancode_filter *filter); int (*s_wakeup_filter)(struct rc_dev *dev, struct rc_scancode_filter *filter); + int (*s_timeout)(struct rc_dev *dev, + unsigned int timeout); }; #define to_rc_dev(d) container_of(d, struct rc_dev, dev) @@ -185,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 7844e9879..daa75fcc1 100644 --- a/include/media/rc-map.h +++ b/include/media/rc-map.h @@ -31,6 +31,7 @@ enum rc_type { RC_TYPE_RC6_MCE = 16, /* MCE (Philips RC6-6A-32 subtype) protocol */ RC_TYPE_SHARP = 17, /* Sharp protocol */ RC_TYPE_XMP = 18, /* XMP protocol */ + RC_TYPE_CEC = 19, /* CEC protocol */ }; #define RC_BIT_NONE 0ULL @@ -53,6 +54,7 @@ enum rc_type { #define RC_BIT_RC6_MCE (1ULL << RC_TYPE_RC6_MCE) #define RC_BIT_SHARP (1ULL << RC_TYPE_SHARP) #define RC_BIT_XMP (1ULL << RC_TYPE_XMP) +#define RC_BIT_CEC (1ULL << RC_TYPE_CEC) #define RC_BIT_ALL (RC_BIT_UNKNOWN | RC_BIT_OTHER | \ RC_BIT_RC5 | RC_BIT_RC5X | RC_BIT_RC5_SZ | \ @@ -61,7 +63,7 @@ enum rc_type { RC_BIT_NEC | RC_BIT_SANYO | RC_BIT_MCE_KBD | \ RC_BIT_RC6_0 | RC_BIT_RC6_6A_20 | RC_BIT_RC6_6A_24 | \ RC_BIT_RC6_6A_32 | RC_BIT_RC6_MCE | RC_BIT_SHARP | \ - RC_BIT_XMP) + RC_BIT_XMP | RC_BIT_CEC) #define RC_SCANCODE_UNKNOWN(x) (x) @@ -96,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 */ @@ -123,6 +140,7 @@ void rc_map_init(void); #define RC_MAP_BEHOLD_COLUMBUS "rc-behold-columbus" #define RC_MAP_BEHOLD "rc-behold" #define RC_MAP_BUDGET_CI_OLD "rc-budget-ci-old" +#define RC_MAP_CEC "rc-cec" #define RC_MAP_CINERGY_1400 "rc-cinergy-1400" #define RC_MAP_CINERGY "rc-cinergy" #define RC_MAP_DELOCK_61959 "rc-delock-61959" @@ -133,6 +151,7 @@ void rc_map_init(void); #define RC_MAP_DM1105_NEC "rc-dm1105-nec" #define RC_MAP_DNTV_LIVE_DVBT_PRO "rc-dntv-live-dvbt-pro" #define RC_MAP_DNTV_LIVE_DVB_T "rc-dntv-live-dvb-t" +#define RC_MAP_DTT200U "rc-dtt200u" #define RC_MAP_DVBSKY "rc-dvbsky" #define RC_MAP_EMPTY "rc-empty" #define RC_MAP_EM_TERRATEC "rc-em-terratec" diff --git a/include/media/rcar-fcp.h b/include/media/rcar-fcp.h new file mode 100644 index 000000000..4c7fc77ea --- /dev/null +++ b/include/media/rcar-fcp.h @@ -0,0 +1,37 @@ +/* + * rcar-fcp.h -- R-Car Frame Compression Processor Driver + * + * Copyright (C) 2016 Renesas Electronics Corporation + * + * Contact: Laurent Pinchart (laurent.pinchart@ideasonboard.com) + * + * 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. + */ +#ifndef __MEDIA_RCAR_FCP_H__ +#define __MEDIA_RCAR_FCP_H__ + +struct device_node; +struct rcar_fcp_device; + +#if IS_ENABLED(CONFIG_VIDEO_RENESAS_FCP) +struct rcar_fcp_device *rcar_fcp_get(const struct device_node *np); +void rcar_fcp_put(struct rcar_fcp_device *fcp); +int rcar_fcp_enable(struct rcar_fcp_device *fcp); +void rcar_fcp_disable(struct rcar_fcp_device *fcp); +#else +static inline struct rcar_fcp_device *rcar_fcp_get(const struct device_node *np) +{ + return ERR_PTR(-ENOENT); +} +static inline void rcar_fcp_put(struct rcar_fcp_device *fcp) { } +static inline int rcar_fcp_enable(struct rcar_fcp_device *fcp) +{ + return -ENOSYS; +} +static inline void rcar_fcp_disable(struct rcar_fcp_device *fcp) { } +#endif + +#endif /* __MEDIA_RCAR_FCP_H__ */ diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h index 094e112cc..aed539068 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 8be898739..c56501ee0 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 1d6d7da4c..8e2a236a4 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 1cc0c5ba1..350cbf9fb 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 0bc9b35b8..178a88d45 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,22 +804,25 @@ 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 set the control's new value 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. + * This sets the control's new value safely by going through the control + * framework. This function assumes the control's handler is already locked, + * allowing it to be used from within the &v4l2_ctrl_ops functions. * * This function is for integer type controls only. */ 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. * - * This set the control's new value safely by going through the control + * This sets the control's new value 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. * @@ -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 @@ -807,21 +859,22 @@ s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl); * @ctrl: The control. * @val: The new value. * - * This set the control's new value 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. + * This sets the control's new value safely by going through the control + * framework. This function assumes the control's handler is already locked, + * allowing it to be used from within the &v4l2_ctrl_ops functions. * * This function is for 64-bit integer type controls only. */ 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. * @val: The new value. * - * This set the control's new value safely by going through the control + * This sets the control's new value 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. * @@ -838,26 +891,28 @@ 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. * - * This set 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. + * This sets the control's new string safely by going through the control + * framework. This function assumes the control's handler is already locked, + * allowing it to be used from within the &v4l2_ctrl_ops functions. * * This function is for string type controls only. */ 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. - * - * This set the control's new string safely by going through the control + *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,49 +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); - -/* Helpers for subdevices. If the associated ctrl_handler == NULL then they - will all return -EINVAL. */ -int v4l2_subdev_queryctrl(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc); -int v4l2_subdev_querymenu(struct v4l2_subdev *sd, struct v4l2_querymenu *qm); -int v4l2_subdev_g_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs); -int v4l2_subdev_try_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs); -int v4l2_subdev_s_ext_ctrls(struct v4l2_subdev *sd, struct v4l2_ext_controls *cs); -int v4l2_subdev_g_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl); -int v4l2_subdev_s_ctrl(struct v4l2_subdev *sd, struct v4l2_control *ctrl); - -/* Can be used as a subscribe_event function that just subscribes control - events. */ + struct v4l2_ext_controls *c); + +/** + * 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 25a319030..a122b1bd4 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 d5d45a8d3..a9d6aa417 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 1113c8874..65caadf13 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 9792f9064..ca854203b 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 803516775..e19e6246e 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 017ffb222..8b1d19bc9 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 7a8d6037a..28c3f9d9c 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 32fc7a4be..2a2240c99 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 @@ -143,29 +162,15 @@ struct v4l2_subdev_io_pin_config { * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with * a direction argument if needed. * - * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code. - * - * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code. - * - * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code. - * - * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code. - * - * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code. - * - * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code. - * - * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code. - * * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core. * used to provide support for private ioctls used on the driver. * * @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). @@ -173,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. @@ -190,13 +195,6 @@ struct v4l2_subdev_core_ops { int (*load_fw)(struct v4l2_subdev *sd); int (*reset)(struct v4l2_subdev *sd, u32 val); int (*s_gpio)(struct v4l2_subdev *sd, u32 val); - int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc); - int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); - int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); - int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); - int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); - int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); - int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm); long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg); #ifdef CONFIG_COMPAT long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd, @@ -219,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. * @@ -268,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. @@ -300,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 @@ -325,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. @@ -335,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. @@ -345,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 @@ -379,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 * @@ -428,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. * @@ -485,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, @@ -557,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; @@ -573,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 @@ -648,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; @@ -659,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); @@ -693,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) @@ -715,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; }; @@ -747,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; @@ -778,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 88e3ab496..a4a9a55a0 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -27,7 +27,6 @@ enum vb2_memory { VB2_MEMORY_DMABUF = 4, }; -struct vb2_alloc_ctx; struct vb2_fileio_data; struct vb2_threadio_data; @@ -57,7 +56,7 @@ struct vb2_threadio_data; * @put_userptr: inform the allocator that a USERPTR buffer will no longer * be used. * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation; - * used for DMABUF memory types; alloc_ctx is the alloc context + * used for DMABUF memory types; dev is the alloc device * dbuf is the shared dma_buf; returns NULL on failure; * allocator private per-buffer structure on success; * this needs to be used for further accesses to the buffer. @@ -86,20 +85,26 @@ 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)(void *alloc_ctx, unsigned long size, - enum dma_data_direction dma_dir, + void *(*alloc)(struct device *dev, unsigned long attrs, + unsigned long size, enum dma_data_direction dma_dir, gfp_t gfp_flags); void (*put)(void *buf_priv); struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags); - void *(*get_userptr)(void *alloc_ctx, unsigned long vaddr, + void *(*get_userptr)(struct device *dev, unsigned long vaddr, unsigned long size, enum dma_data_direction dma_dir); void (*put_userptr)(void *buf_priv); @@ -107,7 +112,7 @@ struct vb2_mem_ops { void (*prepare)(void *buf_priv); void (*finish)(void *buf_priv); - void *(*attach_dmabuf)(void *alloc_ctx, struct dma_buf *dbuf, + void *(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf, unsigned long size, enum dma_data_direction dma_dir); void (*detach_dmabuf)(void *buf_priv); @@ -272,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 context in the alloc_ctxs[] 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 @@ -306,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 @@ -318,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 @@ -342,21 +347,21 @@ 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, unsigned int *num_buffers, unsigned int *num_planes, - unsigned int sizes[], void *alloc_ctxs[]); + unsigned int sizes[], struct device *alloc_devs[]); void (*wait_prepare)(struct vb2_queue *q); void (*wait_finish)(struct vb2_queue *q); @@ -401,6 +406,9 @@ struct vb2_buf_ops { * caller. For example, for V4L2, it should match * the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h * @io_modes: supported io methods (see vb2_io_modes enum) + * @dev: device to use for the default allocation context if the driver + * doesn't fill in the @alloc_devs array. + * @dma_attrs: DMA attributes to use for the DMA. * @fileio_read_once: report EOF after reading the first buffer * @fileio_write_immediately: queue buffer after each write() call * @allow_zero_bytesused: allow bytesused == 0 to be passed to the driver @@ -447,7 +455,7 @@ struct vb2_buf_ops { * @done_list: list of buffers ready to be dequeued to userspace * @done_lock: lock to protect done_list list * @done_wq: waitqueue for processes waiting for buffers ready to be dequeued - * @alloc_ctx: memory type/allocator-specific contexts for each plane + * @alloc_devs: memory type/allocator-specific per-plane device * @streaming: current streaming state * @start_streaming_called: start_streaming() was called successfully and we * started streaming. @@ -467,6 +475,8 @@ struct vb2_buf_ops { struct vb2_queue { unsigned int type; unsigned int io_modes; + struct device *dev; + unsigned long dma_attrs; unsigned fileio_read_once:1; unsigned fileio_write_immediately:1; unsigned allow_zero_bytesused:1; @@ -499,7 +509,7 @@ struct vb2_queue { spinlock_t done_lock; wait_queue_head_t done_wq; - void *alloc_ctx[VB2_MAX_PLANES]; + struct device *alloc_devs[VB2_MAX_PLANES]; unsigned int streaming:1; unsigned int start_streaming_called:1; diff --git a/include/media/videobuf2-dma-contig.h b/include/media/videobuf2-dma-contig.h index 2087c9a68..5604818d1 100644 --- a/include/media/videobuf2-dma-contig.h +++ b/include/media/videobuf2-dma-contig.h @@ -16,8 +16,6 @@ #include <media/videobuf2-v4l2.h> #include <linux/dma-mapping.h> -struct dma_attrs; - static inline dma_addr_t vb2_dma_contig_plane_dma_addr(struct vb2_buffer *vb, unsigned int plane_no) { @@ -26,15 +24,8 @@ vb2_dma_contig_plane_dma_addr(struct vb2_buffer *vb, unsigned int plane_no) return *addr; } -void *vb2_dma_contig_init_ctx_attrs(struct device *dev, - struct dma_attrs *attrs); - -static inline void *vb2_dma_contig_init_ctx(struct device *dev) -{ - return vb2_dma_contig_init_ctx_attrs(dev, NULL); -} - -void vb2_dma_contig_cleanup_ctx(void *alloc_ctx); +int vb2_dma_contig_set_max_seg_size(struct device *dev, unsigned int size); +void vb2_dma_contig_clear_max_seg_size(struct device *dev); extern const struct vb2_mem_ops vb2_dma_contig_memops; diff --git a/include/media/videobuf2-dma-sg.h b/include/media/videobuf2-dma-sg.h index 8d1083f83..52afa0e2b 100644 --- a/include/media/videobuf2-dma-sg.h +++ b/include/media/videobuf2-dma-sg.h @@ -21,9 +21,6 @@ static inline struct sg_table *vb2_dma_sg_plane_desc( return (struct sg_table *)vb2_plane_cookie(vb, plane_no); } -void *vb2_dma_sg_init_ctx(struct device *dev); -void vb2_dma_sg_cleanup_ctx(void *alloc_ctx); - extern const struct vb2_mem_ops vb2_dma_sg_memops; #endif diff --git a/include/media/vsp1.h b/include/media/vsp1.h index 3e654a045..9322d9775 100644 --- a/include/media/vsp1.h +++ b/include/media/vsp1.h @@ -14,31 +14,28 @@ #define __MEDIA_VSP1_H__ #include <linux/types.h> +#include <linux/videodev2.h> struct device; -struct v4l2_rect; int vsp1_du_init(struct device *dev); int vsp1_du_setup_lif(struct device *dev, unsigned int width, unsigned int height); +struct vsp1_du_atomic_config { + u32 pixelformat; + unsigned int pitch; + dma_addr_t mem[2]; + struct v4l2_rect src; + struct v4l2_rect dst; + unsigned int alpha; + unsigned int zpos; +}; + void vsp1_du_atomic_begin(struct device *dev); -int vsp1_du_atomic_update_ext(struct device *dev, unsigned int rpf, - u32 pixelformat, unsigned int pitch, - dma_addr_t mem[2], const struct v4l2_rect *src, - const struct v4l2_rect *dst, unsigned int alpha, - unsigned int zpos); +int vsp1_du_atomic_update(struct device *dev, unsigned int rpf, + const struct vsp1_du_atomic_config *cfg); void vsp1_du_atomic_flush(struct device *dev); -static inline int vsp1_du_atomic_update(struct device *dev, - unsigned int rpf_index, u32 pixelformat, - unsigned int pitch, dma_addr_t mem[2], - const struct v4l2_rect *src, - const struct v4l2_rect *dst) -{ - return vsp1_du_atomic_update_ext(dev, rpf_index, pixelformat, pitch, - mem, src, dst, 255, 0); -} - #endif /* __MEDIA_VSP1_H__ */ |