From d55f09abe24b4dfadab246b6f217da547361cdb6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 11 Jul 2016 09:45:32 -0300 Subject: [media] lirc.h: remove several unused ioctls While reviewing the documentation gaps on LIRC, it was noticed that several ioctls aren't used by any LIRC drivers (nor at staging or mainstream). It doesn't make sense to document them, as they're not used anywhere. So, let's remove those from the lirc header. Signed-off-by: Mauro Carvalho Chehab --- include/uapi/linux/lirc.h | 39 ++------------------------------------- 1 file changed, 2 insertions(+), 37 deletions(-) (limited to 'include') diff --git a/include/uapi/linux/lirc.h b/include/uapi/linux/lirc.h index 4b3ab2966b5a..991ab4570b8e 100644 --- a/include/uapi/linux/lirc.h +++ b/include/uapi/linux/lirc.h @@ -90,20 +90,11 @@ #define LIRC_GET_SEND_MODE _IOR('i', 0x00000001, __u32) #define LIRC_GET_REC_MODE _IOR('i', 0x00000002, __u32) -#define LIRC_GET_SEND_CARRIER _IOR('i', 0x00000003, __u32) -#define LIRC_GET_REC_CARRIER _IOR('i', 0x00000004, __u32) -#define LIRC_GET_SEND_DUTY_CYCLE _IOR('i', 0x00000005, __u32) -#define LIRC_GET_REC_DUTY_CYCLE _IOR('i', 0x00000006, __u32) #define LIRC_GET_REC_RESOLUTION _IOR('i', 0x00000007, __u32) #define LIRC_GET_MIN_TIMEOUT _IOR('i', 0x00000008, __u32) #define LIRC_GET_MAX_TIMEOUT _IOR('i', 0x00000009, __u32) -#define LIRC_GET_MIN_FILTER_PULSE _IOR('i', 0x0000000a, __u32) -#define LIRC_GET_MAX_FILTER_PULSE _IOR('i', 0x0000000b, __u32) -#define LIRC_GET_MIN_FILTER_SPACE _IOR('i', 0x0000000c, __u32) -#define LIRC_GET_MAX_FILTER_SPACE _IOR('i', 0x0000000d, __u32) - /* code length in bits, currently only for LIRC_MODE_LIRCCODE */ #define LIRC_GET_LENGTH _IOR('i', 0x0000000f, __u32) @@ -113,7 +104,6 @@ #define LIRC_SET_SEND_CARRIER _IOW('i', 0x00000013, __u32) #define LIRC_SET_REC_CARRIER _IOW('i', 0x00000014, __u32) #define LIRC_SET_SEND_DUTY_CYCLE _IOW('i', 0x00000015, __u32) -#define LIRC_SET_REC_DUTY_CYCLE _IOW('i', 0x00000016, __u32) #define LIRC_SET_TRANSMITTER_MASK _IOW('i', 0x00000017, __u32) /* @@ -126,22 +116,6 @@ /* 1 enables, 0 disables timeout reports in MODE2 */ #define LIRC_SET_REC_TIMEOUT_REPORTS _IOW('i', 0x00000019, __u32) -/* - * pulses shorter than this are filtered out by hardware (software - * emulation in lirc_dev?) - */ -#define LIRC_SET_REC_FILTER_PULSE _IOW('i', 0x0000001a, __u32) -/* - * spaces shorter than this are filtered out by hardware (software - * emulation in lirc_dev?) - */ -#define LIRC_SET_REC_FILTER_SPACE _IOW('i', 0x0000001b, __u32) -/* - * if filter cannot be set independently for pulse/space, this should - * be used - */ -#define LIRC_SET_REC_FILTER _IOW('i', 0x0000001c, __u32) - /* * if enabled from the next key press on the driver will send * LIRC_MODE2_FREQUENCY packets @@ -149,20 +123,11 @@ #define LIRC_SET_MEASURE_CARRIER_MODE _IOW('i', 0x0000001d, __u32) /* - * to set a range use - * LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE with the - * lower bound first and later - * LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper bound + * to set a range use LIRC_SET_REC_CARRIER_RANGE with the + * lower bound first and later LIRC_SET_REC_CARRIER with the upper bound */ - -#define LIRC_SET_REC_DUTY_CYCLE_RANGE _IOW('i', 0x0000001e, __u32) #define LIRC_SET_REC_CARRIER_RANGE _IOW('i', 0x0000001f, __u32) -#define LIRC_NOTIFY_DECODE _IO('i', 0x00000020) - -#define LIRC_SETUP_START _IO('i', 0x00000021) -#define LIRC_SETUP_END _IO('i', 0x00000022) - #define LIRC_SET_WIDEBAND_RECEIVER _IOW('i', 0x00000023, __u32) #endif -- cgit v1.2.3 From d26a5d4350fd234c1f35d8b262527c8cb97c630d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 17 Jul 2016 07:20:06 -0300 Subject: [media] doc-rst: Convert media API to rst Move the contents of the media section at DocBooks/DocBook/device-drivers.tmpl to a new ReST book. For now, the contents is kept as-is. Next patches will fix the warnings and add cross-references that were removed due to the conversion. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/device-drivers.tmpl | 58 ----- Documentation/index.rst | 1 + Documentation/media/media_drivers.rst | 414 ++++++++++++++++++++++++++++++ drivers/media/dvb-core/demux.h | 71 +---- drivers/media/dvb-core/dvb_frontend.h | 27 +- include/media/media-device.h | 231 ----------------- 6 files changed, 423 insertions(+), 379 deletions(-) create mode 100644 Documentation/media/media_drivers.rst (limited to 'include') diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index a20a45b45c30..e9f77f2fe27b 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -219,64 +219,6 @@ X!Isound/sound_firmware.c --> - - Media Devices - - Video2Linux devices -!Iinclude/media/tuner.h -!Iinclude/media/tuner-types.h -!Iinclude/media/tveeprom.h -!Iinclude/media/v4l2-async.h -!Iinclude/media/v4l2-ctrls.h -!Iinclude/media/v4l2-dv-timings.h -!Iinclude/media/v4l2-event.h -!Iinclude/media/v4l2-flash-led-class.h -!Iinclude/media/v4l2-mc.h -!Iinclude/media/v4l2-mediabus.h -!Iinclude/media/v4l2-mem2mem.h -!Iinclude/media/v4l2-of.h -!Iinclude/media/v4l2-rect.h -!Iinclude/media/v4l2-subdev.h -!Iinclude/media/videobuf2-core.h -!Iinclude/media/videobuf2-v4l2.h -!Iinclude/media/videobuf2-memops.h - - Digital TV (DVB) devices - Digital TV Common functions -!Idrivers/media/dvb-core/dvb_math.h -!Idrivers/media/dvb-core/dvb_ringbuffer.h -!Idrivers/media/dvb-core/dvbdev.h - - Digital TV Frontend kABI -!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend -!Idrivers/media/dvb-core/dvb_frontend.h - - Digital TV Demux kABI -!Pdrivers/media/dvb-core/demux.h Digital TV Demux - Demux Callback API -!Pdrivers/media/dvb-core/demux.h Demux Callback - -!Idrivers/media/dvb-core/demux.h - - Digital TV Conditional Access kABI -!Idrivers/media/dvb-core/dvb_ca_en50221.h - - - Remote Controller devices -!Iinclude/media/rc-core.h -!Iinclude/media/lirc_dev.h - - Media Controller devices -!Pinclude/media/media-device.h Media Controller -!Iinclude/media/media-device.h -!Iinclude/media/media-devnode.h -!Iinclude/media/media-entity.h - - Consumer Electronics Control devices -!Iinclude/media/cec-edid.h - - - 16x50 UART Driver diff --git a/Documentation/index.rst b/Documentation/index.rst index ad07716c73f4..a5a100d43f4f 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -15,6 +15,7 @@ Contents: kernel-documentation media/media_uapi + media/media_drivers Indices and tables ================== diff --git a/Documentation/media/media_drivers.rst b/Documentation/media/media_drivers.rst new file mode 100644 index 000000000000..722170cb7f40 --- /dev/null +++ b/Documentation/media/media_drivers.rst @@ -0,0 +1,414 @@ +========== +Media core +========== + +Video2Linux devices +------------------- + +.. kernel-doc:: include/media/tuner.h + +.. kernel-doc:: include/media/tuner-types.h + +.. kernel-doc:: include/media/tveeprom.h + +.. kernel-doc:: include/media/v4l2-async.h + +.. kernel-doc:: include/media/v4l2-ctrls.h + +.. kernel-doc:: include/media/v4l2-dv-timings.h + +.. kernel-doc:: include/media/v4l2-event.h + +.. kernel-doc:: include/media/v4l2-flash-led-class.h + +.. kernel-doc:: include/media/v4l2-mc.h + +.. kernel-doc:: include/media/v4l2-mediabus.h + +.. kernel-doc:: include/media/v4l2-mem2mem.h + +.. kernel-doc:: include/media/v4l2-of.h + +.. kernel-doc:: include/media/v4l2-rect.h + +.. kernel-doc:: include/media/v4l2-subdev.h + +.. kernel-doc:: include/media/videobuf2-core.h + +.. kernel-doc:: include/media/videobuf2-v4l2.h + +.. kernel-doc:: include/media/videobuf2-memops.h + + +Digital TV (DVB) devices +------------------------ + +Digital TV Common functions +--------------------------- + +.. kernel-doc:: drivers/media/dvb-core/dvb_math.h + +.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h + +.. kernel-doc:: drivers/media/dvb-core/dvbdev.h + + +Digital TV Frontend kABI +------------------------ + +Digital TV Frontend +~~~~~~~~~~~~~~~~~~~ + +The Digital TV Frontend kABI defines a driver-internal interface for +registering low-level, hardware specific driver to a hardware independent +frontend layer. It is only of interest for Digital TV device driver writers. +The header file for this API is named dvb_frontend.h and located in +drivers/media/dvb-core. + +Before using the Digital TV frontend core, the bridge driver should attach +the frontend demod, tuner and SEC devices and call dvb_register_frontend(), +in order to register the new frontend at the subsystem. At device +detach/removal, the bridge driver should call dvb_unregister_frontend() to +remove the frontend from the core and then dvb_frontend_detach() to free the +memory allocated by the frontend drivers. + +The drivers should also call dvb_frontend_suspend() as part of their +handler for the &device_driver.suspend(), and dvb_frontend_resume() as +part of their handler for &device_driver.resume(). + +few other optional functions are provided to handle some special cases. + +.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h + + +Digital TV Demux kABI +--------------------- + +Digital TV Demux +~~~~~~~~~~~~~~~~ + +The Kernel Digital TV Demux kABI defines a driver-internal interface for +registering low-level, hardware specific driver to a hardware independent +demux layer. It is only of interest for Digital TV device driver writers. +The header file for this kABI is named demux.h and located in +drivers/media/dvb-core. + +The demux kABI should be implemented for each demux in the system. It is +used to select the TS source of a demux and to manage the demux resources. +When the demux client allocates a resource via the demux kABI, it receives +a pointer to the kABI of that resource. + +Each demux receives its TS input from a DVB front-end or from memory, as +set via this demux kABI. In a system with more than one front-end, the kABI +can be used to select one of the DVB front-ends as a TS source for a demux, +unless this is fixed in the HW platform. + +The demux kABI only controls front-ends regarding to their connections with +demuxes; the kABI used to set the other front-end parameters, such as +tuning, are devined via the Digital TV Frontend kABI. + +The functions that implement the abstract interface demux should be defined +static or module private and registered to the Demux core for external +access. It is not necessary to implement every function in the struct +&dmx_demux. For example, a demux interface might support Section filtering, +but not PES filtering. The kABI client is expected to check the value of any +function pointer before calling the function: the value of NULL means +that the function is not available. + +Whenever the functions of the demux API modify shared data, the +possibilities of lost update and race condition problems should be +addressed, e.g. by protecting parts of code with mutexes. + +Note that functions called from a bottom half context must not sleep. +Even a simple memory allocation without using %GFP_ATOMIC can result in a +kernel thread being put to sleep if swapping is needed. For example, the +Linux Kernel calls the functions of a network device interface from a +bottom half context. Thus, if a demux kABI function is called from network +device code, the function must not sleep. + + + +Demux Callback API +------------------ + +Demux Callback +~~~~~~~~~~~~~~ + +This kernel-space API comprises the callback functions that deliver filtered +data to the demux client. Unlike the other DVB kABIs, these functions are +provided by the client and called from the demux code. + +The function pointers of this abstract interface are not packed into a +structure as in the other demux APIs, because the callback functions are +registered and used independent of each other. As an example, it is possible +for the API client to provide several callback functions for receiving TS +packets and no callbacks for PES packets or sections. + +The functions that implement the callback API need not be re-entrant: when +a demux driver calls one of these functions, the driver is not allowed to +call the function again before the original call returns. If a callback is +triggered by a hardware interrupt, it is recommended to use the Linux +bottom half mechanism or start a tasklet instead of making the callback +function call directly from a hardware interrupt. + +This mechanism is implemented by dmx_ts_cb() and dmx_section_cb() +callbacks. + + +.. kernel-doc:: drivers/media/dvb-core/demux.h + + +Digital TV Conditional Access kABI +---------------------------------- + +.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h + + +Remote Controller devices +------------------------- + +.. kernel-doc:: include/media/rc-core.h + +.. kernel-doc:: include/media/lirc_dev.h + + +Media Controller devices +------------------------ + +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. + +.. kernel-doc:: include/media/media-device.h + +.. kernel-doc:: include/media/media-devnode.h + +.. kernel-doc:: include/media/media-entity.h + diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h index 6d3b95b8939d..e8f04f8872f8 100644 --- a/drivers/media/dvb-core/demux.h +++ b/drivers/media/dvb-core/demux.h @@ -1,6 +1,10 @@ /* * demux.h * + * The Kernel Digital TV Demux kABI defines a driver-internal interface for + * registering low-level, hardware specific driver to a hardware independent + * demux layer. + * * Copyright (c) 2002 Convergence GmbH * * based on code: @@ -32,49 +36,6 @@ #include #include -/** - * DOC: Digital TV Demux - * - * The Kernel Digital TV Demux kABI defines a driver-internal interface for - * registering low-level, hardware specific driver to a hardware independent - * demux layer. It is only of interest for Digital TV device driver writers. - * The header file for this kABI is named demux.h and located in - * drivers/media/dvb-core. - * - * The demux kABI should be implemented for each demux in the system. It is - * used to select the TS source of a demux and to manage the demux resources. - * When the demux client allocates a resource via the demux kABI, it receives - * a pointer to the kABI of that resource. - * - * Each demux receives its TS input from a DVB front-end or from memory, as - * set via this demux kABI. In a system with more than one front-end, the kABI - * can be used to select one of the DVB front-ends as a TS source for a demux, - * unless this is fixed in the HW platform. - * - * The demux kABI only controls front-ends regarding to their connections with - * demuxes; the kABI used to set the other front-end parameters, such as - * tuning, are devined via the Digital TV Frontend kABI. - * - * The functions that implement the abstract interface demux should be defined - * static or module private and registered to the Demux core for external - * access. It is not necessary to implement every function in the struct - * &dmx_demux. For example, a demux interface might support Section filtering, - * but not PES filtering. The kABI client is expected to check the value of any - * function pointer before calling the function: the value of NULL means - * that the function is not available. - * - * Whenever the functions of the demux API modify shared data, the - * possibilities of lost update and race condition problems should be - * addressed, e.g. by protecting parts of code with mutexes. - * - * Note that functions called from a bottom half context must not sleep. - * Even a simple memory allocation without using %GFP_ATOMIC can result in a - * kernel thread being put to sleep if swapping is needed. For example, the - * Linux Kernel calls the functions of a network device interface from a - * bottom half context. Thus, if a demux kABI function is called from network - * device code, the function must not sleep. - */ - /* * Common definitions */ @@ -230,30 +191,6 @@ struct dmx_section_feed { int (*stop_filtering)(struct dmx_section_feed *feed); }; -/** - * DOC: Demux Callback - * - * This kernel-space API comprises the callback functions that deliver filtered - * data to the demux client. Unlike the other DVB kABIs, these functions are - * provided by the client and called from the demux code. - * - * The function pointers of this abstract interface are not packed into a - * structure as in the other demux APIs, because the callback functions are - * registered and used independent of each other. As an example, it is possible - * for the API client to provide several callback functions for receiving TS - * packets and no callbacks for PES packets or sections. - * - * The functions that implement the callback API need not be re-entrant: when - * a demux driver calls one of these functions, the driver is not allowed to - * call the function again before the original call returns. If a callback is - * triggered by a hardware interrupt, it is recommended to use the Linux - * bottom half mechanism or start a tasklet instead of making the callback - * function call directly from a hardware interrupt. - * - * This mechanism is implemented by dmx_ts_cb() and dmx_section_cb() - * callbacks. - */ - /** * typedef dmx_ts_cb - DVB demux TS filter callback function prototype * diff --git a/drivers/media/dvb-core/dvb_frontend.h b/drivers/media/dvb-core/dvb_frontend.h index 9592573a0b41..8c551174537a 100644 --- a/drivers/media/dvb-core/dvb_frontend.h +++ b/drivers/media/dvb-core/dvb_frontend.h @@ -1,6 +1,10 @@ /* * dvb_frontend.h * + * The Digital TV Frontend kABI defines a driver-internal interface for + * registering low-level, hardware specific driver to a hardware independent + * frontend layer. + * * Copyright (C) 2001 convergence integrated media GmbH * Copyright (C) 2004 convergence GmbH * @@ -42,29 +46,6 @@ #include "dvbdev.h" -/** - * DOC: Digital TV Frontend - * - * The Digital TV Frontend kABI defines a driver-internal interface for - * registering low-level, hardware specific driver to a hardware independent - * frontend layer. It is only of interest for Digital TV device driver writers. - * The header file for this API is named dvb_frontend.h and located in - * drivers/media/dvb-core. - * - * Before using the Digital TV frontend core, the bridge driver should attach - * the frontend demod, tuner and SEC devices and call dvb_register_frontend(), - * in order to register the new frontend at the subsystem. At device - * detach/removal, the bridge driver should call dvb_unregister_frontend() to - * remove the frontend from the core and then dvb_frontend_detach() to free the - * memory allocated by the frontend drivers. - * - * The drivers should also call dvb_frontend_suspend() as part of their - * handler for the &device_driver.suspend(), and dvb_frontend_resume() as - * part of their handler for &device_driver.resume(). - * - * A few other optional functions are provided to handle some special cases. - */ - /* * Maximum number of Delivery systems per frontend. It * should be smaller or equal to 32 diff --git a/include/media/media-device.h b/include/media/media-device.h index f743ae2210ee..4605fee0c228 100644 --- a/include/media/media-device.h +++ b/include/media/media-device.h @@ -29,237 +29,6 @@ #include #include -/** - * 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; -- cgit v1.2.3 From 5b6137dc84f627e8497e554890ae02378c54f9f0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 17 Jul 2016 09:16:57 -0300 Subject: [media] doc-rst: Fix issues with RC documentation The kernel-doc script is now broken if it doesn't find all exported symbols documented. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/rc-core.rst | 9 ++++++++ include/media/lirc_dev.h | 2 +- include/media/rc-core.h | 45 ++++++++++++++++++++++++++++++++++-- include/media/rc-map.h | 17 +++++++++++++- 4 files changed, 69 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst index 8c8e3bbac0d7..9c244ac9ce92 100644 --- a/Documentation/media/kapi/rc-core.rst +++ b/Documentation/media/kapi/rc-core.rst @@ -1,6 +1,15 @@ Remote Controller devices ------------------------- +Remote Controller core +~~~~~~~~~~~~~~~~~~~~~~ + .. kernel-doc:: include/media/rc-core.h +.. kernel-doc:: include/media/rc-core.h include/media/rc-map.h + :export: drivers/media/rc/rc-main.c drivers/media/rc/rc-raw.c + +LIRC +~~~~ + .. kernel-doc:: include/media/lirc_dev.h diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h index 0ab59a571fee..cec7d35602d1 100644 --- a/include/media/lirc_dev.h +++ b/include/media/lirc_dev.h @@ -140,7 +140,7 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf, * second. * * @features: lirc compatible hardware features, like LIRC_MODE_RAW, - * LIRC_CAN_*, as defined at include/media/lirc.h. + * LIRC_CAN\_\*, as defined at include/media/lirc.h. * * @chunk_size: Size of each FIFO buffer. * diff --git a/include/media/rc-core.h b/include/media/rc-core.h index b6586a91129c..ff54a71f5cd2 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, }; /** @@ -185,12 +192,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 6e6557dbeb9f..726bd9374fd2 100644 --- a/include/media/rc-map.h +++ b/include/media/rc-map.h @@ -98,10 +98,25 @@ struct rc_map_list { /* Routines from rc-map.c */ +/** + * rc_map_register() - Registers a Remote Controler scancode map + * + * @map: pointer to struct rc_map_list + */ int rc_map_register(struct rc_map_list *map); + +/** + * rc_map_unregister() - Unregisters a Remote Controler scancode map + * + * @map: pointer to struct rc_map_list + */ void rc_map_unregister(struct rc_map_list *map); + +/** + * rc_map_get - gets an RC map from its name + * @name: name of the RC scancode map + */ struct rc_map *rc_map_get(const char *name); -void rc_map_init(void); /* Names of the several keytables defined in-kernel */ -- cgit v1.2.3 From 89cb3ddbe7cc5ce49ffa814f30fb019fc531865d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 17 Jul 2016 08:44:08 -0300 Subject: [media] doc-rst: Fix conversion for v4l2 core functions The conversion from DocBook lead into some conversion issues, basically due to the lack of proper support at kernel-doc. So, address them: - Now, the C files with the exported symbols also need to be added. So, all headers need to be included twice: one to get the structs/enums/.. and another one for the functions; - Notes should use the ReST tag, as kernel-doc doesn't recognizes it anymore; - Identation needs to be fixed, as ReST uses it to identify when a format "tag" ends. - kernel-doc doesn't escape things like *pointer, so we need to manually add a escape char before it. - On some cases, kernel-doc conversion requires violating the 80-cols, as otherwise it won't properly parse the source code. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-core.rst | 21 +++++++++++++++++++++ include/media/tuner-types.h | 8 ++++++-- include/media/tveeprom.h | 18 +++++++++++++++--- include/media/v4l2-mc.h | 13 ++++++++----- include/media/v4l2-subdev.h | 4 ++-- include/media/videobuf2-core.h | 30 ++++++++++++++++++------------ 6 files changed, 70 insertions(+), 24 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index a1b73e8d6795..4e2aa721d9c8 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -34,3 +34,24 @@ Video2Linux devices .. kernel-doc:: include/media/videobuf2-v4l2.h .. kernel-doc:: include/media/videobuf2-memops.h + + + + +.. kernel-doc:: include/media/tveeprom.h + :export: drivers/media/common/tveeprom.c + +.. kernel-doc:: include/media/v4l2-ctrls.h + :export: drivers/media/v4l2-core/v4l2-ctrls.c + +.. kernel-doc:: include/media/v4l2-dv-timings.h + :export: drivers/media/v4l2-core/v4l2-dv-timings.c + +.. kernel-doc:: include/media/v4l2-flash-led-class.h + :export: drivers/media/v4l2-core/v4l2-flash-led-class.c + +.. kernel-doc:: include/media/v4l2-mc.h + :export: drivers/media/v4l2-core/v4l2-mc.c + +.. kernel-doc:: include/media/videobuf2-core.h + :export: drivers/media/v4l2-core/videobuf2-core.c diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h index 094e112cc325..aed539068d2d 100644 --- a/include/media/tuner-types.h +++ b/include/media/tuner-types.h @@ -35,8 +35,12 @@ enum param_type { * those ranges, as they're defined inside the driver. This is used by * analog tuners that are compatible with the "Philips way" to setup the * tuners. On those devices, the tuner set is done via 4 bytes: - * divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and - * band switch byte (BB). + * + * #) divider byte1 (DB1) + * #) divider byte 2 (DB2) + * #) Control byte (CB) + * #) band switch byte (BB) + * * Some tuners also have an additional optional Auxiliary byte (AB). */ struct tuner_range { diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h index 8be898739e0c..c56501ee0484 100644 --- a/include/media/tveeprom.h +++ b/include/media/tveeprom.h @@ -27,31 +27,43 @@ enum tveeprom_audio_processor { * struct tveeprom - Contains the fields parsed from Hauppauge eeproms * * @has_radio: 1 if the device has radio; 0 otherwise. + * * @has_ir: If has_ir == 0, then it is unknown what the IR * capabilities are. Otherwise: - * bit 0) 1 (= IR capabilities are known); - * bit 1) IR receiver present; - * bit 2) IR transmitter (blaster) present. + * bit 0) 1 (= IR capabilities are known); + * bit 1) IR receiver present; + * bit 2) IR transmitter (blaster) present. + * * @has_MAC_address: 0: no MAC, 1: MAC present, 2: unknown. * @tuner_type: type of the tuner (TUNER_*, as defined at * include/media/tuner.h). + * * @tuner_formats: Supported analog TV standards (V4L2_STD_*). * @tuner_hauppauge_model: Hauppauge's code for the device model number. * @tuner2_type: type of the second tuner (TUNER_*, as defined * at include/media/tuner.h). + * * @tuner2_formats: Tuner 2 supported analog TV standards * (V4L2_STD_*). + * * @tuner2_hauppauge_model: tuner 2 Hauppauge's code for the device model * number. + * * @audio_processor: analog audio decoder, as defined by enum * tveeprom_audio_processor. + * * @decoder_processor: Hauppauge's code for the decoder chipset. * Unused by the drivers, as they probe the * decoder based on the PCI or USB ID. + * * @model: Hauppauge's model number + * * @revision: Card revision number + * * @serial_number: Card's serial number + * * @rev_str: Card revision converted to number + * * @MAC_address: MAC address for the network interface */ struct tveeprom { diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h index 7a8d6037a4bb..28c3f9d9c209 100644 --- a/include/media/v4l2-mc.h +++ b/include/media/v4l2-mc.h @@ -114,11 +114,14 @@ struct usb_device; * Add links between the entities commonly found on PC customer's hardware at * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners, * analog TV decoder and I/O entities (video, VBI and Software Defined Radio). - * NOTE: webcams are modelled on a very simple way: the sensor is - * connected directly to the I/O entity. All dirty details, like - * scaler and crop HW are hidden. While such mapping is enough for v4l2 - * interface centric PC-consumer's hardware, V4L2 subdev centric camera - * hardware should not use this routine, as it will not build the right graph. + * + * .. note:: + * + * Webcams are modelled on a very simple way: the sensor is + * connected directly to the I/O entity. All dirty details, like + * scaler and crop HW are hidden. While such mapping is enough for v4l2 + * interface centric PC-consumer's hardware, V4L2 subdev centric camera + * hardware should not use this routine, as it will not build the right graph. */ int v4l2_mc_create_media_graph(struct media_device *mdev); diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 32fc7a4beb5e..4c880e86a1aa 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -225,7 +225,7 @@ struct v4l2_subdev_core_ops { * * @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. + * or the bridge driver. * * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code. * @@ -233,7 +233,7 @@ struct v4l2_subdev_core_ops { * * @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. * diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index 88e3ab496e8f..01cdd5bf90c8 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -86,11 +86,17 @@ struct vb2_threadio_data; * @mmap: setup a userspace mapping for a given memory buffer under * the provided virtual memory region. * - * Required ops for USERPTR types: get_userptr, put_userptr. - * Required ops for MMAP types: alloc, put, num_users, mmap. - * Required ops for read/write access types: alloc, put, num_users, vaddr. - * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, - * unmap_dmabuf. + * Those operations are used by the videobuf2 core to implement the memory + * handling/memory allocators for each type of supported streaming I/O method. + * + * .. note:: + * #) Required ops for USERPTR types: get_userptr, put_userptr. + * + * #) Required ops for MMAP types: alloc, put, num_users, mmap. + * + * #) Required ops for read/write access types: alloc, put, num_users, vaddr. + * + * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf. */ struct vb2_mem_ops { void *(*alloc)(void *alloc_ctx, unsigned long size, @@ -279,19 +285,19 @@ struct vb2_buffer { * 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 + * 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 + * 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 + * 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 -- cgit v1.2.3 From 74604b7390af3afb1bcb055b87787b5cfabd03a0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 17 Jul 2016 09:18:03 -0300 Subject: [media] doc-rst: Fix conversion for MC core functions There were lots of issues at the media controller side, after the conversion: - Some documentation at the header files weren't using the kernel-doc start block; - Now, the C files with the exported symbols also need to be added. So, all headers need to be included twice: one to get the structs/enums/.. and another one for the functions; - Notes should use the ReST tag, as kernel-doc doesn't recognizes it anymore; - Identation needs to be fixed, as ReST uses it to identify when a format "tag" ends. - Fix the cross-references at the media controller description. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/mc-core.rst | 186 ++++++++++++++++++++--------------- include/media/media-device.h | 24 ++--- include/media/media-entity.h | 83 +++++++++------- 3 files changed, 163 insertions(+), 130 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst index 2ec242b6e4c3..2ab541ba6e88 100644 --- a/Documentation/media/kapi/mc-core.rst +++ b/Documentation/media/kapi/mc-core.rst @@ -4,9 +4,8 @@ Media Controller devices Media Controller ~~~~~~~~~~~~~~~~ - -The media controller userspace API is documented in DocBook format in -Documentation/DocBook/media/v4l/media-controller.xml. This document focus +The media controller userspace API is documented in +:ref:`the Media Controller uAPI book `. This document focus on the kernel-side implementation of the media framework. Abstract media device model @@ -35,72 +34,77 @@ 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. +A media device is represented by a :c:type:`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 :c:type:`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(). +:cpp:func:`__media_device_register()` via the macro ``media_device_register()`` +and unregistered by calling :cpp:func:`media_device_unregister()`. 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. +Entities are represented by a :c:type:`struct media_entity ` +instance, defined in ``include/media/media-entity.h``. The structure is usually +embedded into a higher-level structure, such as +:ref:`v4l2_subdev` or :ref:`video_device` +instances, although drivers can allocate entities directly. Drivers initialize entity pads by calling -media_entity_pads_init(). +:cpp:func:`media_entity_pads_init()`. Drivers register entities with a media device by calling -media_device_register_entity() +:cpp:func:`media_device_register_entity()` and unregistred by calling -media_device_unregister_entity(). +:cpp:func:`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. +Interfaces are represented by a +:c:type:`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 +:c:type:`struct media_intf_devnode `. Drivers initialize and create device node interfaces by calling -media_devnode_create() +:cpp:func:`media_devnode_create()` and remove them by calling: -media_devnode_remove(). +:cpp:func:`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 represented by a :c:type:`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. + +Both information are stored in the :c:type:`struct media_pad`, making the +:c:type:`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. +``MEDIA_PAD_FL_SINK`` indicates that the pad supports sinking data. +``MEDIA_PAD_FL_SOURCE`` indicates that the pad supports sourcing data. + +.. note:: -NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must -be set for each pad. + One and only one of ``MEDIA_PAD_FL_SINK`` or ``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: +Links are represented by a :c:type:`struct media_link ` instance, +defined in ``include/media/media-entity.h``. There are two types of links: -1. pad to pad 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. @@ -108,22 +112,24 @@ 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(). +:cpp:func:`media_create_pad_link()` and remove with +:cpp:func:`media_entity_remove_links()`. -2. interface to entity 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(). +:cpp:func:`media_create_intf_link()` and remove with +:cpp:func:`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(). +valid values are described at :cpp:func:`media_create_pad_link()` and +:cpp:func:`media_create_intf_link()`. Graph traversal ^^^^^^^^^^^^^^^ @@ -132,92 +138,103 @@ 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. +``include/media/media-device.h``. + +.. code-block:: c -struct media_entity *entity; + struct media_entity *entity; -media_device_for_each_entity(entity, mdev) { -// entity will point to each entity in turn -... -} + 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. +.. note:: + + 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() +:cpp:func:`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() +:cpp:func:`media_entity_graph_walk_next()` -When the graph traversal is complete the function will return NULL. +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() +:cpp:func:`media_entity_find_link()` and +:cpp:func:`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 +the :c:type:`struct media_entity ` 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 +The :c:type:`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. +:c:type:`media_device`.\ ``graph_mutex`` lock. Links setup ^^^^^^^^^^^ Link properties can be modified at runtime by calling -media_entity_setup_link() +:cpp:func:`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(). +:cpp:func:`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. +The :c:type:`struct media_pipeline ` instance pointed to by +the pipe argument will be stored in every entity in the pipeline. +Drivers should embed the :c:type:`struct media_pipeline ` +in higher-level pipeline structures and can then access the +pipeline through the :c:type:`struct 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. +Calls to :cpp:func:`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. +:cpp:func:`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(). +:cpp:func:`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. +If multiple calls to :cpp:func:`media_entity_pipeline_start()` have been +made the same number of :cpp:func:`media_entity_pipeline_stop()` calls +are required to stop streaming. +The :c:type:`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 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. +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 @@ -227,13 +244,13 @@ 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. +Link validation is performed by :cpp:func:`media_entity_pipeline_start()` +for any entity which has sink pads in the pipeline. The +:c:type:`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 @@ -245,3 +262,10 @@ in the end provide a way to use driver-specific callbacks. .. kernel-doc:: include/media/media-entity.h + + +.. kernel-doc:: include/media/media-device.h + :export: drivers/media/media-device.c + +.. kernel-doc:: include/media/media-entity.h + :export: drivers/media/media-entity.c diff --git a/include/media/media-device.h b/include/media/media-device.h index 4605fee0c228..28195242386c 100644 --- a/include/media/media-device.h +++ b/include/media/media-device.h @@ -242,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. */ @@ -296,14 +294,16 @@ void media_device_unregister(struct media_device *mdev); * This can be used to report the default audio and video devices or the * 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 @@ -317,8 +317,10 @@ int __must_check media_device_register_entity(struct media_device *mdev, * When a media device is unregistered, all its entities are unregistered * automatically. No manual entities unregistration is then required. * - * Note: the media_entity instance itself must be freed explicitly by - * the driver if required. + * .. note:: + * + * The media_entity instance itself must be freed explicitly by + * the driver if required. */ void media_device_unregister_entity(struct media_entity *entity); diff --git a/include/media/media-entity.h b/include/media/media-entity.h index cbb266f7f2b5..83877719bef4 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,7 +180,7 @@ 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 + * .. note:: Those these callbacks are called with struct media_device.@graph_mutex * mutex held. */ struct media_entity_operations { @@ -602,19 +602,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 +642,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 +679,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 +732,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 +850,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 +874,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 +915,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 +939,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 +948,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 +957,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 +966,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); -- cgit v1.2.3 From 5b8700e9f909d8fb2802d7ea2626460d3a233256 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 20 Jul 2016 09:22:38 -0300 Subject: [media] doc-rst: Fix some Sphinx warnings Fix all remaining media warnings with ReST that are fixable without changing at the Sphinx code. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/cx88.rst | 1 + Documentation/media/v4l-drivers/tm6000-cardlist.rst | 2 +- drivers/media/dvb-core/dvb_math.h | 7 +++++++ include/media/media-entity.h | 6 ++++-- 4 files changed, 13 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/Documentation/media/v4l-drivers/cx88.rst b/Documentation/media/v4l-drivers/cx88.rst index 97865007f51f..d8f3a014726a 100644 --- a/Documentation/media/v4l-drivers/cx88.rst +++ b/Documentation/media/v4l-drivers/cx88.rst @@ -119,6 +119,7 @@ GPIO 16(I believe) is tied to the IR port (if present). From the data sheet: - Register 24'h20004 PCI Interrupt Status + - bit [18] IR_SMP_INT Set when 32 input samples have been collected over - gpio[16] pin into GP_SAMPLE register. diff --git a/Documentation/media/v4l-drivers/tm6000-cardlist.rst b/Documentation/media/v4l-drivers/tm6000-cardlist.rst index ca08d4214b38..2fbd3886b5f0 100644 --- a/Documentation/media/v4l-drivers/tm6000-cardlist.rst +++ b/Documentation/media/v4l-drivers/tm6000-cardlist.rst @@ -1,5 +1,5 @@ TM6000 cards list -=============== +================= .. code-block:: none diff --git a/drivers/media/dvb-core/dvb_math.h b/drivers/media/dvb-core/dvb_math.h index 34dc1df03cab..2f0326674ca6 100644 --- a/drivers/media/dvb-core/dvb_math.h +++ b/drivers/media/dvb-core/dvb_math.h @@ -30,11 +30,15 @@ * @value: The value (must be != 0) * * to use rational values you can use the following method: + * * intlog2(value) = intlog2(value * 2^x) - x * 2^24 * * Some usecase examples: + * * intlog2(8) will give 3 << 24 = 3 * 2^24 + * * intlog2(9) will give 3 << 24 + ... = 3.16... * 2^24 + * * intlog2(1.5) = intlog2(3) - 2^24 = 0.584... * 2^24 * * @@ -48,10 +52,13 @@ extern unsigned int intlog2(u32 value); * @value: The value (must be != 0) * * to use rational values you can use the following method: + * * intlog10(value) = intlog10(value * 10^x) - x * 2^24 * * An usecase example: + * * intlog10(1000) will give 3 << 24 = 3 * 2^24 + * * due to the implementation intlog10(1000) might be not exactly 3 * 2^24 * * look at intlog2 for similar examples diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 83877719bef4..3d885d97d149 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -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, -- cgit v1.2.3 From f58cad224796600f91a1faebec9f868985869851 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 20 Jul 2016 11:15:31 -0300 Subject: [media] media-entry.h: Fix a note markup The Sphinx note markup for media_remove_intf_links() is wrong: there's a missing space. While here, let's auto-numerate the two notes. Signed-off-by: Mauro Carvalho Chehab --- include/media/media-entity.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 3d885d97d149..17390cc7b538 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -968,12 +968,12 @@ void __media_remove_intf_links(struct media_interface *intf); * * @intf: pointer to &media_interface * - * ..note:: + * .. 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); -- cgit v1.2.3 From 575f93084db35ced739a3df9ad398e46704c32c9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 20 Jul 2016 13:05:05 -0300 Subject: [media] v4l2-device.h: document functions The functions at v4l2-device.h are not using the proper markups. Add it, and include at the v4l2-core.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-core.rst | 2 + include/media/v4l2-device.h | 198 ++++++++++++++++++++++++--------- 2 files changed, 145 insertions(+), 55 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index a1b73e8d6795..db571a4f498a 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -11,6 +11,8 @@ Video2Linux devices .. kernel-doc:: include/media/v4l2-ctrls.h +.. kernel-doc:: include/media/v4l2-device.h + .. kernel-doc:: include/media/v4l2-dv-timings.h .. kernel-doc:: include/media/v4l2-event.h diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h index d5d45a8d3998..a9d6aa41790e 100644 --- a/include/media/v4l2-device.h +++ b/include/media/v4l2-device.h @@ -25,100 +25,188 @@ #include #include -/* 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) { -- cgit v1.2.3 From 21c29de1d090488f595c56be77c088c2ceed394b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 20 Jul 2016 14:20:26 -0300 Subject: [media] v4l2-subdev.h: Improve documentation This header were poorly documented, and weren't using the kernel-doc format. Document everything but the macros using the right format. While here, also fix the other comments to match the Linux CodingStyle. Signed-off-by: Mauro Carvalho Chehab --- drivers/media/v4l2-core/v4l2-subdev.c | 10 - include/media/v4l2-subdev.h | 572 +++++++++++++++++++++++----------- 2 files changed, 383 insertions(+), 199 deletions(-) (limited to 'include') diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c index 953eab08e420..34a1e7c8b306 100644 --- a/drivers/media/v4l2-core/v4l2-subdev.c +++ b/drivers/media/v4l2-core/v4l2-subdev.c @@ -621,16 +621,6 @@ void v4l2_subdev_init(struct v4l2_subdev *sd, const struct v4l2_subdev_ops *ops) } EXPORT_SYMBOL(v4l2_subdev_init); -/** - * 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/v4l2-subdev.h b/include/media/v4l2-subdev.h index 1f672c0ac7d1..2a2240c99b30 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -1,21 +1,17 @@ /* - V4L2 sub-device support header. - - Copyright (C) 2008 Hans Verkuil - - 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 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. */ #ifndef _V4L2_SUBDEV_H @@ -52,55 +48,64 @@ struct v4l2_subdev_fh; struct tuner_setup; struct v4l2_mbus_frame_desc; -/* decode_vbi_line */ +/** + * struct v4l2_decode_vbi_line - used to decode_vbi_line + * + * @is_second_field: Set to 0 for the first (odd) field; + * set to 1 for the second (even) field. + * @p: Pointer to the sliced VBI data from the decoder. On exit, points to + * the start of the payload. + * @line: Line number of the sliced VBI data (1-23) + * @type: VBI service type (V4L2_SLICED_*). 0 if no service found + */ struct v4l2_decode_vbi_line { - u32 is_second_field; /* Set to 0 for the first (odd) field, - set to 1 for the second (even) field. */ - u8 *p; /* Pointer to the sliced VBI data from the decoder. - On exit points to the start of the payload. */ - u32 line; /* Line number of the sliced VBI data (1-23) */ - u32 type; /* VBI service type (V4L2_SLICED_*). 0 if no service found */ + u32 is_second_field; + u8 *p; + u32 line; + u32 type; }; -/* Sub-devices are devices that are connected somehow to the main bridge - device. These devices are usually audio/video muxers/encoders/decoders or - sensors and webcam controllers. - - Usually these devices are controlled through an i2c bus, but other busses - may also be used. - - The v4l2_subdev struct provides a way of accessing these devices in a - generic manner. Most operations that these sub-devices support fall in - a few categories: core ops, audio ops, video ops and tuner ops. - - More categories can be added if needed, although this should remain a - limited set (no more than approx. 8 categories). - - Each category has its own set of ops that subdev drivers can implement. - - A subdev driver can leave the pointer to the category ops NULL if - it does not implement them (e.g. an audio subdev will generally not - implement the video category ops). The exception is the core category: - this must always be present. - - These ops are all used internally so it is no problem to change, remove - or add ops or move ops from one to another category. Currently these - ops are based on the original ioctls, but since ops are not limited to - one argument there is room for improvement here once all i2c subdev - drivers are converted to use these ops. +/* + * Sub-devices are devices that are connected somehow to the main bridge + * device. These devices are usually audio/video muxers/encoders/decoders or + * sensors and webcam controllers. + * + * Usually these devices are controlled through an i2c bus, but other busses + * may also be used. + * + * The v4l2_subdev struct provides a way of accessing these devices in a + * generic manner. Most operations that these sub-devices support fall in + * a few categories: core ops, audio ops, video ops and tuner ops. + * + * More categories can be added if needed, although this should remain a + * limited set (no more than approx. 8 categories). + * + * Each category has its own set of ops that subdev drivers can implement. + * + * A subdev driver can leave the pointer to the category ops NULL if + * it does not implement them (e.g. an audio subdev will generally not + * implement the video category ops). The exception is the core category: + * this must always be present. + * + * These ops are all used internally so it is no problem to change, remove + * or add ops or move ops from one to another category. Currently these + * ops are based on the original ioctls, but since ops are not limited to + * one argument there is room for improvement here once all i2c subdev + * drivers are converted to use these ops. */ -/* Core ops: it is highly recommended to implement at least these ops: - - log_status - g_register - s_register - - This provides basic debugging support. - - The ioctl ops is meant for generic ioctl-like commands. Depending on - the use-case it might be better to use subdev-specific ops (currently - not yet implemented) since ops provide proper type-checking. +/* + * Core ops: it is highly recommended to implement at least these ops: + * + * log_status + * g_register + * s_register + * + * This provides basic debugging support. + * + * The ioctl ops is meant for generic ioctl-like commands. Depending on + * the use-case it might be better to use subdev-specific ops (currently + * not yet implemented) since ops provide proper type-checking. */ /* Subdevice external IO pin configuration */ @@ -110,18 +115,32 @@ struct v4l2_decode_vbi_line { #define V4L2_SUBDEV_IO_PIN_SET_VALUE (1 << 3) /* Set output value */ #define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW (1 << 4) /* ACTIVE HIGH assumed */ +/** + * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration + * + * @flags: bitmask with flags for this pin's config: + * %V4L2_SUBDEV_IO_PIN_DISABLE - disables a pin config, + * %V4L2_SUBDEV_IO_PIN_OUTPUT - if pin is an output, + * %V4L2_SUBDEV_IO_PIN_INPUT - if pin is an input, + * %V4L2_SUBDEV_IO_PIN_SET_VALUE - to set the output value via @value + * and %V4L2_SUBDEV_IO_PIN_ACTIVE_LOW - if active is 0. + * @pin: Chip external IO pin to configure + * @function: Internal signal pad/function to route to IO pin + * @value: Initial value for pin - e.g. GPIO output value + * @strength: Pin drive strength + */ struct v4l2_subdev_io_pin_config { - u32 flags; /* V4L2_SUBDEV_IO_PIN_* flags for this pin's config */ - u8 pin; /* Chip external IO pin to configure */ - u8 function; /* Internal signal pad/function to route to IO pin */ - u8 value; /* Initial value for pin - e.g. GPIO output value */ - u8 strength; /* Pin drive strength */ + u32 flags; + u8 pin; + u8 function; + u8 value; + u8 strength; }; /** * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs * - * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code. + * @log_status: callback for %VIDIOC_LOG_STATUS ioctl handler code. * * @s_io_pin_config: configure one or more chip I/O pins for chips that * multiplex different internal signal pads out to IO pins. This function @@ -149,9 +168,9 @@ struct v4l2_subdev_io_pin_config { * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel, * in order to fix data passed from/to userspace. * - * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code. + * @g_register: callback for %VIDIOC_G_REGISTER ioctl handler code. * - * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code. + * @s_register: callback for %VIDIOC_G_REGISTER ioctl handler code. * * @s_power: puts subdevice in power saving mode (on == 0) or normal operation * mode (on == 1). @@ -159,7 +178,7 @@ struct v4l2_subdev_io_pin_config { * @interrupt_service_routine: Called by the bridge chip's interrupt service * handler, when an interrupt status has be raised due to this subdev, * so that this subdev can handle the details. It may schedule work to be - * performed later. It must not sleep. *Called from an IRQ context*. + * performed later. It must not sleep. **Called from an IRQ context**. * * @subscribe_event: used by the drivers to request the control framework that * for it to be warned when the value of a control changes. @@ -198,25 +217,25 @@ struct v4l2_subdev_core_ops { /** * struct s_radio - Callbacks used when v4l device was opened in radio mode. * - * @s_radio: callback for VIDIOC_S_RADIO ioctl handler code. + * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code. * - * @s_frequency: callback for VIDIOC_S_FREQUENCY ioctl handler code. + * @s_frequency: callback for %VIDIOC_S_FREQUENCY ioctl handler code. * - * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code. - * freq->type must be filled in. Normally done by video_ioctl2 + * @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. * - * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code. + * @g_modulator: callback for %VIDIOC_G_MODULATOR ioctl handler code. * - * @s_modulator: callback for VIDIOC_S_MODULATOR ioctl handler code. + * @s_modulator: callback for %VIDIOC_S_MODULATOR ioctl handler code. * * @s_type_addr: sets tuner type and its I2C addr. * @@ -247,7 +266,7 @@ struct v4l2_subdev_tuner_ops { * @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard * way to select I2S clock used by driving digital audio streams at some * board designs. Usual values for the frequency are 1024000 and 2048000. - * If the frequency is not supported, then -EINVAL is returned. + * If the frequency is not supported, then %-EINVAL is returned. * * @s_routing: used to define the input and/or output pins of an audio chip, * and any additional configuration data. @@ -279,7 +298,8 @@ struct v4l2_subdev_audio_ops { /** * struct v4l2_mbus_frame_desc_entry - media bus frame description structure * - * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags + * @flags: bitmask flags: %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX and + * %V4L2_MBUS_FRAME_DESC_FL_BLOB. * @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set * @length: number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB * is set @@ -304,7 +324,7 @@ struct v4l2_mbus_frame_desc { /** * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened - * in video mode. + * in video mode. * * @s_routing: see s_routing in audio_ops, except this version is for video * devices. @@ -314,9 +334,9 @@ struct v4l2_mbus_frame_desc { * regarding clock frequency dividers, etc. If not used, then set flags * to 0. If the frequency is not supported, then -EINVAL is returned. * - * @g_std: callback for VIDIOC_G_STD ioctl handler code. + * @g_std: callback for %VIDIOC_G_STD ioctl handler code. * - * @s_std: callback for VIDIOC_S_STD ioctl handler code. + * @s_std: callback for %VIDIOC_S_STD ioctl handler code. * * @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by * video input devices. @@ -324,33 +344,33 @@ struct v4l2_mbus_frame_desc { * @g_std_output: get current standard for video OUTPUT devices. This is ignored * by video input devices. * - * @querystd: callback for VIDIOC_QUERYSTD ioctl handler code. + * @querystd: callback for %VIDIOC_QUERYSTD ioctl handler code. * - * @g_tvnorms: get v4l2_std_id with all standards supported by the video + * @g_tvnorms: get &v4l2_std_id with all standards supported by the video * CAPTURE device. This is ignored by video output devices. * * @g_tvnorms_output: get v4l2_std_id with all standards supported by the video * OUTPUT device. This is ignored by video capture devices. * - * @g_input_status: get input status. Same as the status field in the v4l2_input - * struct. + * @g_input_status: get input status. Same as the status field in the + * &struct &v4l2_input * * @s_stream: used to notify the driver that a video stream will start or has * stopped. * - * @cropcap: callback for VIDIOC_CROPCAP ioctl handler code. + * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code. * - * @g_crop: callback for VIDIOC_G_CROP ioctl handler code. + * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code. * - * @s_crop: callback for VIDIOC_S_CROP ioctl handler code. + * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code. * - * @g_parm: callback for VIDIOC_G_PARM ioctl handler code. + * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code. * - * @s_parm: callback for VIDIOC_S_PARM ioctl handler code. + * @s_parm: callback for %VIDIOC_S_PARM ioctl handler code. * - * @g_frame_interval: callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code. + * @g_frame_interval: callback for %VIDIOC_G_FRAMEINTERVAL ioctl handler code. * - * @s_frame_interval: callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code. + * @s_frame_interval: callback for %VIDIOC_S_FRAMEINTERVAL ioctl handler code. * * @s_dv_timings: Set custom dv timings in the sub device. This is used * when sub device is capable of setting detailed timing information @@ -358,7 +378,7 @@ struct v4l2_mbus_frame_desc { * * @g_dv_timings: Get custom dv timings in the sub device. * - * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code. + * @query_dv_timings: callback for %VIDIOC_QUERY_DV_TIMINGS ioctl handler code. * * @g_mbus_config: get supported mediabus configurations * @@ -407,31 +427,31 @@ struct v4l2_subdev_video_ops { /** * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened - * in video mode via the vbi device node. + * in video mode via the vbi device node. * * @decode_vbi_line: video decoders that support sliced VBI need to implement - * this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the + * this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the * start of the VBI data that was generated by the decoder. The driver * then parses the sliced VBI data and sets the other fields in the * struct accordingly. The pointer p is updated to point to the start of * the payload which can be copied verbatim into the data field of the - * v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the + * &struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the * type field is set to 0 on return. * * @s_vbi_data: used to generate VBI signals on a video signal. - * v4l2_sliced_vbi_data is filled with the data packets that should be - * output. Note that if you set the line field to 0, then that VBI signal - * is disabled. If no valid VBI data was found, then the type field is - * set to 0 on return. + * &struct v4l2_sliced_vbi_data is filled with the data packets that + * should be output. Note that if you set the line field to 0, then that + * VBI signal is disabled. If no valid VBI data was found, then the type + * field is set to 0 on return. * * @g_vbi_data: used to obtain the sliced VBI packet from a readback register. * Not all video decoders support this. If no data is available because - * the readback register contains invalid or erroneous data -EIO is + * the readback register contains invalid or erroneous data %-EIO is * returned. Note that you must fill in the 'id' member and the 'field' * member (to determine whether CC data from the first or second field * should be obtained). * - * @g_sliced_vbi_cap: callback for VIDIOC_SLICED_VBI_CAP ioctl handler code. + * @g_sliced_vbi_cap: callback for %VIDIOC_SLICED_VBI_CAP ioctl handler code. * * @s_raw_fmt: setup the video encoder/decoder for raw VBI. * @@ -464,58 +484,99 @@ struct v4l2_subdev_sensor_ops { int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames); }; -/* - [rt]x_g_parameters: Get the current operating parameters and state of the - the IR receiver or transmitter. - - [rt]x_s_parameters: Set the current operating parameters and state of the - the IR receiver or transmitter. It is recommended to call - [rt]x_g_parameters first to fill out the current state, and only change - the fields that need to be changed. Upon return, the actual device - operating parameters and state will be returned. Note that hardware - limitations may prevent the actual settings from matching the requested - settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz - was requested. An exception is when the shutdown parameter is true. - The last used operational parameters will be returned, but the actual - state of the hardware be different to minimize power consumption and - processing when shutdown is true. - - rx_read: Reads received codes or pulse width data. - The semantics are similar to a non-blocking read() call. - - tx_write: Writes codes or pulse width data for transmission. - The semantics are similar to a non-blocking write() call. +/** + * enum v4l2_subdev_ir_mode- describes the type of IR supported + * + * @V4L2_SUBDEV_IR_MODE_PULSE_WIDTH: IR uses struct ir_raw_event records */ - enum v4l2_subdev_ir_mode { - V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* uses struct ir_raw_event records */ + V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, }; +/** + * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX + * + * @bytes_per_data_element: bytes per data element of data in read or + * write call. + * @mode: IR mode as defined by &enum v4l2_subdev_ir_mode. + * @enable: device is active if true + * @interrupt_enable: IR interrupts are enabled if true + * @shutdown: if true: set hardware to low/no power, false: normal mode + * + * @modulation: if true, it uses carrier, if false: baseband + * @max_pulse_width: maximum pulse width in ns, valid only for baseband signal + * @carrier_freq: carrier frequency in Hz, valid only for modulated signal + * @duty_cycle: duty cycle percentage, valid only for modulated signal + * @invert_level: invert signal level + * + * @invert_carrier_sense: Send 0/space as a carrier burst. used only in TX. + * + * @noise_filter_min_width: min time of a valid pulse, in ns. Used only for RX. + * @carrier_range_lower: Lower carrier range, in Hz, valid only for modulated + * signal. Used only for RX. + * @carrier_range_upper: Upper carrier range, in Hz, valid only for modulated + * signal. Used only for RX. + * @resolution: The receive resolution, in ns . Used only for RX. + */ struct v4l2_subdev_ir_parameters { - /* Either Rx or Tx */ - unsigned int bytes_per_data_element; /* of data in read or write call */ + unsigned int bytes_per_data_element; enum v4l2_subdev_ir_mode mode; bool enable; bool interrupt_enable; - bool shutdown; /* true: set hardware to low/no power, false: normal */ + bool shutdown; - bool modulation; /* true: uses carrier, false: baseband */ - u32 max_pulse_width; /* ns, valid only for baseband signal */ - unsigned int carrier_freq; /* Hz, valid only for modulated signal*/ - unsigned int duty_cycle; /* percent, valid only for modulated signal*/ - bool invert_level; /* invert signal level */ + bool modulation; + u32 max_pulse_width; + unsigned int carrier_freq; + unsigned int duty_cycle; + bool invert_level; /* Tx only */ - bool invert_carrier_sense; /* Send 0/space as a carrier burst */ + bool invert_carrier_sense; /* Rx only */ - u32 noise_filter_min_width; /* ns, min time of a valid pulse */ - unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */ - unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */ - u32 resolution; /* ns */ + u32 noise_filter_min_width; + unsigned int carrier_range_lower; + unsigned int carrier_range_upper; + u32 resolution; }; +/** + * struct v4l2_subdev_ir_ops - operations for IR subdevices + * + * @rx_read: Reads received codes or pulse width data. + * The semantics are similar to a non-blocking read() call. + * @rx_g_parameters: Get the current operating parameters and state of the + * the IR receiver. + * @rx_s_parameters: Set the current operating parameters and state of the + * the IR receiver. It is recommended to call + * [rt]x_g_parameters first to fill out the current state, and only change + * the fields that need to be changed. Upon return, the actual device + * operating parameters and state will be returned. Note that hardware + * limitations may prevent the actual settings from matching the requested + * settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz + * was requested. An exception is when the shutdown parameter is true. + * The last used operational parameters will be returned, but the actual + * state of the hardware be different to minimize power consumption and + * processing when shutdown is true. + * + * @tx_write: Writes codes or pulse width data for transmission. + * The semantics are similar to a non-blocking write() call. + * @tx_g_parameters: Get the current operating parameters and state of the + * the IR transmitter. + * @tx_s_parameters: Set the current operating parameters and state of the + * the IR transmitter. It is recommended to call + * [rt]x_g_parameters first to fill out the current state, and only change + * the fields that need to be changed. Upon return, the actual device + * operating parameters and state will be returned. Note that hardware + * limitations may prevent the actual settings from matching the requested + * settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz + * was requested. An exception is when the shutdown parameter is true. + * The last used operational parameters will be returned, but the actual + * state of the hardware be different to minimize power consumption and + * processing when shutdown is true. + */ struct v4l2_subdev_ir_ops { /* Receiver */ int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count, @@ -536,11 +597,16 @@ struct v4l2_subdev_ir_ops { struct v4l2_subdev_ir_parameters *params); }; -/* - * Used for storing subdev pad information. This structure only needs - * to be passed to the pad op if the 'which' field of the main argument - * is set to V4L2_SUBDEV_FORMAT_TRY. For V4L2_SUBDEV_FORMAT_ACTIVE it is - * safe to pass NULL. +/** + * struct v4l2_subdev_pad_config - Used for storing subdev pad information. + * + * @try_fmt: pointer to &struct v4l2_mbus_framefmt + * @try_crop: pointer to &struct v4l2_rect to be used for crop + * @try_compose: pointer to &struct v4l2_rect to be used for compose + * + * This structure only needs to be passed to the pad op if the 'which' field + * of the main argument is set to %V4L2_SUBDEV_FORMAT_TRY. For + * %V4L2_SUBDEV_FORMAT_ACTIVE it is safe to pass %NULL. */ struct v4l2_subdev_pad_config { struct v4l2_mbus_framefmt try_fmt; @@ -552,30 +618,30 @@ struct v4l2_subdev_pad_config { * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations * * @init_cfg: initialize the pad config to default values - * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler + * @enum_mbus_code: callback for %VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler * code. - * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler + * @enum_frame_size: callback for %VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler * code. * - * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl + * @enum_frame_interval: callback for %VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl * handler code. * - * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT ioctl handler code. + * @get_fmt: callback for %VIDIOC_SUBDEV_G_FMT ioctl handler code. * - * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT ioctl handler code. + * @set_fmt: callback for %VIDIOC_SUBDEV_S_FMT ioctl handler code. * - * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code. + * @get_selection: callback for %VIDIOC_SUBDEV_G_SELECTION ioctl handler code. * - * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code. + * @set_selection: callback for %VIDIOC_SUBDEV_S_SELECTION ioctl handler code. * - * @get_edid: callback for VIDIOC_SUBDEV_G_EDID ioctl handler code. + * @get_edid: callback for %VIDIOC_SUBDEV_G_EDID ioctl handler code. * - * @set_edid: callback for VIDIOC_SUBDEV_S_EDID ioctl handler code. + * @set_edid: callback for %VIDIOC_SUBDEV_S_EDID ioctl handler code. * - * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler + * @dv_timings_cap: callback for %VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler * code. * - * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler + * @enum_dv_timings: callback for %VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler * code. * * @link_validate: used by the media controller code to check if the links @@ -627,6 +693,18 @@ struct v4l2_subdev_pad_ops { struct v4l2_mbus_frame_desc *fd); }; +/** + * struct v4l2_subdev_ops - Subdev operations + * + * @core: pointer to &struct v4l2_subdev_core_ops. Can be %NULL + * @tuner: pointer to &struct v4l2_subdev_tuner_ops. Can be %NULL + * @audio: pointer to &struct v4l2_subdev_audio_ops. Can be %NULL + * @video: pointer to &struct v4l2_subdev_video_ops. Can be %NULL + * @vbi: pointer to &struct v4l2_subdev_vbi_ops. Can be %NULL + * @ir: pointer to &struct v4l2_subdev_ir_ops. Can be %NULL + * @sensor: pointer to &struct v4l2_subdev_sensor_ops. Can be %NULL + * @pad: pointer to &struct v4l2_subdev_pad_ops. Can be %NULL + */ struct v4l2_subdev_ops { const struct v4l2_subdev_core_ops *core; const struct v4l2_subdev_tuner_ops *tuner; @@ -638,19 +716,22 @@ struct v4l2_subdev_ops { const struct v4l2_subdev_pad_ops *pad; }; -/* - * Internal ops. Never call this from drivers, only the v4l2 framework can call - * these ops. +/** + * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops * - * registered: called when this subdev is registered. When called the v4l2_dev + * @registered: called when this subdev is registered. When called the v4l2_dev * field is set to the correct v4l2_device. * - * unregistered: called when this subdev is unregistered. When called the + * @unregistered: called when this subdev is unregistered. When called the * v4l2_dev field is still set to the correct v4l2_device. * - * open: called when the subdev device node is opened by an application. + * @open: called when the subdev device node is opened by an application. * - * close: called when the subdev device node is closed. + * @close: called when the subdev device node is closed. + * + * .. note:: + * Never call this from drivers, only the v4l2 framework can call + * these ops. */ struct v4l2_subdev_internal_ops { int (*registered)(struct v4l2_subdev *sd); @@ -672,17 +753,60 @@ struct v4l2_subdev_internal_ops { struct regulator_bulk_data; +/** + * struct v4l2_subdev_platform_data - regulators config struct + * + * @regulators: Optional regulators used to power on/off the subdevice + * @num_regulators: Number of regululators + * @host_priv: Per-subdevice data, specific for a certain video host device + */ struct v4l2_subdev_platform_data { - /* Optional regulators uset to power on/off the subdevice */ struct regulator_bulk_data *regulators; int num_regulators; - /* Per-subdevice data, specific for a certain video host device */ void *host_priv; }; -/* Each instance of a subdev driver should create this struct, either - stand-alone or embedded in a larger struct. +/** + * struct v4l2_subdev - describes a V4L2 sub-device + * + * @entity: pointer to &struct media_entity + * @list: List of sub-devices + * @owner: The owner is the same as the driver's &struct device owner. + * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev + * ownner. Initialized by v4l2_device_register_subdev(). + * @flags: subdev flags. Can be: + * %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device; + * %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device; + * %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a + * device node; + * %V4L2_SUBDEV_FL_HAS_EVENTS - Set this flag if this subdev generates + * events. + * + * @v4l2_dev: pointer to &struct v4l2_device + * @ops: pointer to &struct v4l2_subdev_ops + * @internal_ops: pointer to &struct v4l2_subdev_internal_ops. + * Never call these internal ops from within a driver! + * @ctrl_handler: The control handler of this subdev. May be NULL. + * @name: Name of the sub-device. Please notice that the name must be unique. + * @grp_id: can be used to group similar subdevs. Value is driver-specific + * @dev_priv: pointer to private data + * @host_priv: pointer to private data used by the device where the subdev + * is attached. + * @devnode: subdev device node + * @dev: pointer to the physical device, if any + * @of_node: The device_node of the subdev, usually the same as dev->of_node. + * @async_list: Links this subdev to a global subdev_list or @notifier->done + * list. + * @asd: Pointer to respective &struct v4l2_async_subdev. + * @notifier: Pointer to the managing notifier. + * @pdata: common part of subdevice platform data + * + * Each instance of a subdev driver should create this struct, either + * stand-alone or embedded in a larger struct. + * + * This structure should be initialized by v4l2_subdev_init() or one of + * its variants: v4l2_spi_subdev_init(), v4l2_i2c_subdev_init(). */ struct v4l2_subdev { #if defined(CONFIG_MEDIA_CONTROLLER) @@ -694,30 +818,18 @@ struct v4l2_subdev { u32 flags; struct v4l2_device *v4l2_dev; const struct v4l2_subdev_ops *ops; - /* Never call these internal ops from within a driver! */ const struct v4l2_subdev_internal_ops *internal_ops; - /* The control handler of this subdev. May be NULL. */ struct v4l2_ctrl_handler *ctrl_handler; - /* name must be unique */ char name[V4L2_SUBDEV_NAME_SIZE]; - /* can be used to group similar subdevs, value is driver-specific */ u32 grp_id; - /* pointer to private data */ void *dev_priv; void *host_priv; - /* subdev device node */ struct video_device *devnode; - /* pointer to the physical device, if any */ struct device *dev; - /* The device_node of the subdev, usually the same as dev->of_node. */ struct device_node *of_node; - /* Links this subdev to a global subdev_list or @notifier->done list. */ struct list_head async_list; - /* Pointer to respective struct v4l2_async_subdev. */ struct v4l2_async_subdev *asd; - /* Pointer to the managing notifier. */ struct v4l2_async_notifier *notifier; - /* common part of subdevice platform data */ struct v4l2_subdev_platform_data *pdata; }; @@ -726,8 +838,11 @@ struct v4l2_subdev { #define vdev_to_v4l2_subdev(vdev) \ ((struct v4l2_subdev *)video_get_drvdata(vdev)) -/* - * Used for storing subdev information per file handle +/** + * struct v4l2_subdev_fh - Used for storing subdev information per file handle + * + * @vfh: pointer to struct v4l2_fh + * @pad: pointer to v4l2_subdev_pad_config */ struct v4l2_subdev_fh { struct v4l2_fh vfh; @@ -757,53 +872,132 @@ __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose) extern const struct v4l2_file_operations v4l2_subdev_fops; +/** + * v4l2_set_subdevdata - Sets V4L2 dev private device data + * + * @sd: pointer to &struct v4l2_subdev + * @p: pointer to the private device data to be stored. + */ static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p) { sd->dev_priv = p; } +/** + * v4l2_get_subdevdata - Gets V4L2 dev private device data + * + * @sd: pointer to &struct v4l2_subdev + * + * Returns the pointer to the private device data to be stored. + */ static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd) { return sd->dev_priv; } +/** + * v4l2_set_subdevdata - Sets V4L2 dev private host data + * + * @sd: pointer to &struct v4l2_subdev + * @p: pointer to the private data to be stored. + */ static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p) { sd->host_priv = p; } +/** + * v4l2_get_subdevdata - Gets V4L2 dev private data + * + * @sd: pointer to &struct v4l2_subdev + * + * Returns the pointer to the private host data to be stored. + */ static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd) { return sd->host_priv; } #ifdef CONFIG_MEDIA_CONTROLLER + +/** + * v4l2_subdev_link_validate_default - validates a media link + * + * @sd: pointer to &struct v4l2_subdev + * @link: pointer to &struct media_link + * @source_fmt: pointer to &struct v4l2_subdev_format + * @sink_fmt: pointer to &struct v4l2_subdev_format + * + * This function ensures that width, height and the media bus pixel + * code are equal on both source and sink of the link. + */ int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd, struct media_link *link, struct v4l2_subdev_format *source_fmt, struct v4l2_subdev_format *sink_fmt); + +/** + * v4l2_subdev_link_validate - validates a media link + * + * @link: pointer to &struct media_link + * + * This function calls the subdev's link_validate ops to validate + * if a media link is valid for streaming. It also internally + * calls v4l2_subdev_link_validate_default() to ensure that + * width, height and the media bus pixel code are equal on both + * source and sink of the link. + */ int v4l2_subdev_link_validate(struct media_link *link); -struct v4l2_subdev_pad_config * -v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd); +/** + * v4l2_subdev_alloc_pad_config - Allocates memory for pad config + * + * @sd: pointer to struct v4l2_subdev + */ +struct +v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd); + +/** + * v4l2_subdev_free_pad_config - Frees memory allocated by + * v4l2_subdev_alloc_pad_config(). + * + * @cfg: pointer to &struct v4l2_subdev_pad_config + */ void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg); #endif /* CONFIG_MEDIA_CONTROLLER */ +/** + * v4l2_subdev_init - initializes the sub-device struct + * + * @sd: pointer to the &struct v4l2_subdev to be initialized + * @ops: pointer to &struct v4l2_subdev_ops. + */ void v4l2_subdev_init(struct v4l2_subdev *sd, const struct v4l2_subdev_ops *ops); -/* Call an ops of a v4l2_subdev, doing the right checks against - NULL pointers. - - Example: err = v4l2_subdev_call(sd, video, s_std, norm); +/* + * Call an ops of a v4l2_subdev, doing the right checks against + * NULL pointers. + * + * Example: err = v4l2_subdev_call(sd, video, s_std, norm); */ #define v4l2_subdev_call(sd, o, f, args...) \ (!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ? \ - (sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD)) + (sd)->ops->o->f((sd), ##args) : -ENOIOCTLCMD)) #define v4l2_subdev_has_op(sd, o, f) \ ((sd)->ops->o && (sd)->ops->o->f) +/** + * v4l2_subdev_notify_event() - Delivers event notification for subdevice + * @sd: The subdev for which to deliver the event + * @ev: The event to deliver + * + * Will deliver the specified event to all userspace event listeners which are + * subscribed to the v42l subdev event queue as well as to the bridge driver + * using the notify callback. The notification type for the notify callback + * will be %V4L2_DEVICE_NOTIFY_EVENT. + */ void v4l2_subdev_notify_event(struct v4l2_subdev *sd, const struct v4l2_event *ev); -- cgit v1.2.3 From ab4f5a4afc2d7a32285baba8ffab865beba60e13 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 09:24:55 -0300 Subject: [media] v4l2-async: document the remaining stuff There are one enum and 4 functions undocumented there. Document them. That will fix the broken links at the v4l2-subdev.rst file. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-async.h | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'include') diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h index 1d6d7da4c45d..8e2a236a4d03 100644 --- a/include/media/v4l2-async.h +++ b/include/media/v4l2-async.h @@ -23,6 +23,19 @@ struct v4l2_async_notifier; /* A random max subdevice number, used to allocate an array on stack */ #define V4L2_MAX_SUBDEVS 128U +/** + * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used + * in order to identify a match + * + * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct + * v4l2_async_subdev.match ops + * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name + * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address + * @V4L2_ASYNC_MATCH_OF: Match will use OF node + * + * This enum is used by the asyncrhronous sub-device logic to define the + * algorithm that will be used to match an asynchronous device. + */ enum v4l2_async_match_type { V4L2_ASYNC_MATCH_CUSTOM, V4L2_ASYNC_MATCH_DEVNAME, @@ -91,9 +104,35 @@ struct v4l2_async_notifier { struct v4l2_async_subdev *asd); }; +/** + * v4l2_async_notifier_register - registers a subdevice asynchronous notifier + * + * @v4l2_dev: pointer to &struct v4l2_device + * @notifier: pointer to &struct v4l2_async_notifier + */ int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev, struct v4l2_async_notifier *notifier); + +/** + * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier + * + * @notifier: pointer to &struct v4l2_async_notifier + */ void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier); + +/** + * v4l2_async_register_subdev - registers a sub-device to the asynchronous + * subdevice framework + * + * @sd: pointer to &struct v4l2_subdev + */ int v4l2_async_register_subdev(struct v4l2_subdev *sd); + +/** + * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous + * subdevice framework + * + * @sd: pointer to &struct v4l2_subdev + */ void v4l2_async_unregister_subdev(struct v4l2_subdev *sd); #endif -- cgit v1.2.3 From a39c57f8cd0526d8227468f8e0f88c4be4f97139 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 10:08:31 -0300 Subject: [media] v4l2-common.h: document the subdev functions There are some subdev-specific functions at v4l2-common.h that are mentioned at v4l2-subdev.rst. Document them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-subdev.rst | 6 ++++ include/media/v4l2-common.h | 49 +++++++++++++++++++++++++++----- 2 files changed, 48 insertions(+), 7 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst index 80982a9d002f..456fdec69042 100644 --- a/Documentation/media/kapi/v4l2-subdev.rst +++ b/Documentation/media/kapi/v4l2-subdev.rst @@ -449,3 +449,9 @@ V4L2 sub-device asynchronous kAPI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. kernel-doc:: include/media/v4l2-async.h + + +V4L2 common kAPI +^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-common.h diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h index 1cc0c5ba16b3..9b1dfcd9e229 100644 --- a/include/media/v4l2-common.h +++ b/include/media/v4l2-common.h @@ -80,8 +80,6 @@ /* ------------------------------------------------------------------------- */ -/* Control helper function */ - int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def); /* ------------------------------------------------------------------------- */ @@ -96,23 +94,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 { -- cgit v1.2.3 From b871915893c32473ef5ce0d075c1952ed8232ce1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 12:26:04 -0300 Subject: [media] v4l2-common.h: Add documentation for other functions Not all functions at v4l2-common.h are documented. Add documentation for some other ones. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-common.h | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h index 9b1dfcd9e229..350cbf9fb10e 100644 --- a/include/media/v4l2-common.h +++ b/include/media/v4l2-common.h @@ -78,9 +78,26 @@ v4l2_printk(KERN_DEBUG, dev, fmt , ## arg); \ } while (0) -/* ------------------------------------------------------------------------- */ +/** + * 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); /* ------------------------------------------------------------------------- */ @@ -172,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 -- cgit v1.2.3 From d9d3d1761abecf72a8044762724fb04b5974a513 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 15:30:20 -0300 Subject: [media] doc-rst: document v4l2-dev.h Add documentation for v4l2-dev.h, and put it at v4l2-framework.rst, where struct video_device is currently documented. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-framework.rst | 5 + drivers/media/v4l2-core/v4l2-dev.c | 34 --- include/media/v4l2-dev.h | 364 ++++++++++++++++++++++++---- 3 files changed, 320 insertions(+), 83 deletions(-) (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst index de341fc5b235..315388ef6593 100644 --- a/Documentation/media/kapi/v4l2-framework.rst +++ b/Documentation/media/kapi/v4l2-framework.rst @@ -699,3 +699,8 @@ methods. It is expected that once the CCF becomes available on all relevant architectures this API will be removed. + +video_device kAPI +^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-dev.h diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c index 70b559d7ca80..e6da353b39bc 100644 --- a/drivers/media/v4l2-core/v4l2-dev.c +++ b/drivers/media/v4l2-core/v4l2-dev.c @@ -812,40 +812,6 @@ static int video_register_media_controller(struct video_device *vdev, int type) return 0; } -/** - * __video_register_device - register video4linux devices - * @vdev: video device structure we want to register - * @type: type of device to register - * @nr: which device node number (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. - * - * Zero is returned on success. - * - * Valid types 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 - */ int __video_register_device(struct video_device *vdev, int type, int nr, int warn_if_nr_in_use, struct module *owner) { diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h index 25a3190308fb..5921c24565cf 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 `. + */ 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 ` + * @new: Priority type requested, as defined by :ref:`enum 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 ` + * + * .. 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 ` + * + * .. 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 ` 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); -- cgit v1.2.3 From 9d4ee1ad925ffc77fe3b8d6f6a188c54d65af5dc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 07:27:06 -0300 Subject: [media] v4l2-event.h: document all functions Several functions weren't documented. Document them all. While here, makes checkpatch.pl happy. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-event.h | 125 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 12 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h index 9792f906423b..ca854203b8b9 100644 --- a/include/media/v4l2-event.h +++ b/include/media/v4l2-event.h @@ -73,14 +73,15 @@ struct video_device; * @list: List node for the v4l2_fh->available list. * @sev: Pointer to parent v4l2_subscribed_event. * @event: The event itself. - */ + */ struct v4l2_kevent { struct list_head list; struct v4l2_subscribed_event *sev; struct v4l2_event event; }; -/** struct v4l2_subscribed_event_ops - Subscribed event operations. +/** + * struct v4l2_subscribed_event_ops - Subscribed event operations. * * @add: Optional callback, called when a new listener is added * @del: Optional callback, called when a listener stops listening @@ -88,20 +89,23 @@ struct v4l2_kevent { * @merge: Optional callback that can merge event 'old' into event 'new'. */ struct v4l2_subscribed_event_ops { - int (*add)(struct v4l2_subscribed_event *sev, unsigned elems); + int (*add)(struct v4l2_subscribed_event *sev, unsigned int elems); void (*del)(struct v4l2_subscribed_event *sev); void (*replace)(struct v4l2_event *old, const struct v4l2_event *new); void (*merge)(const struct v4l2_event *old, struct v4l2_event *new); }; /** - * struct v4l2_subscribed_event - Internal struct representing a subscribed event. + * struct v4l2_subscribed_event - Internal struct representing a subscribed + * event. + * * @list: List node for the v4l2_fh->subscribed list. * @type: Event type. * @id: Associated object ID (e.g. control ID). 0 if there isn't any. * @flags: Copy of v4l2_event_subscription->flags. * @fh: Filehandle that subscribed to this event. - * @node: List node that hooks into the object's event list (if there is one). + * @node: List node that hooks into the object's event list + * (if there is one). * @ops: v4l2_subscribed_event_ops * @elems: The number of elements in the events array. * @first: The index of the events containing the oldest available event. @@ -116,27 +120,124 @@ struct v4l2_subscribed_event { struct v4l2_fh *fh; struct list_head node; const struct v4l2_subscribed_event_ops *ops; - unsigned elems; - unsigned first; - unsigned in_use; + unsigned int elems; + unsigned int first; + unsigned int in_use; struct v4l2_kevent events[]; }; +/** + * v4l2_event_dequeue - Dequeue events from video device. + * + * @fh: pointer to struct v4l2_fh + * @event: pointer to struct v4l2_event + * @nonblocking: if not zero, waits for an event to arrive + */ int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event, int nonblocking); + +/** + * v4l2_event_queue - Queue events to video device. + * + * @vdev: pointer to &struct video_device + * @ev: pointer to &struct v4l2_event + * + * The event will be queued for all &struct v4l2_fh file handlers. + * + * .. note:: + * The driver's only responsibility is to fill in the type and the data + * fields.The other fields will be filled in by V4L2. + */ void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev); + +/** + * v4l2_event_queue_fh - Queue events to video device. + * + * @fh: pointer to &struct v4l2_fh + * @ev: pointer to &struct v4l2_event + * + * + * The event will be queued only for the specified &struct v4l2_fh file handler. + * + * .. note:: + * The driver's only responsibility is to fill in the type and the data + * fields.The other fields will be filled in by V4L2. + */ void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev); + +/** + * v4l2_event_pending - Check if an event is available + * + * @fh: pointer to &struct v4l2_fh + * + * Returns the number of pending events. + */ int v4l2_event_pending(struct v4l2_fh *fh); + +/** + * v4l2_event_subscribe - Subscribes to an event + * + * @fh: pointer to &struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + * @elems: size of the events queue + * @ops: pointer to &v4l2_subscribed_event_ops + * + * .. note:: + * + * if @elems is zero, the framework will fill in a default value, + * with is currently 1 element. + */ int v4l2_event_subscribe(struct v4l2_fh *fh, - const struct v4l2_event_subscription *sub, unsigned elems, + const struct v4l2_event_subscription *sub, + unsigned int elems, const struct v4l2_subscribed_event_ops *ops); +/** + * v4l2_event_unsubscribe - Unsubscribes to an event + * + * @fh: pointer to &struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + */ int v4l2_event_unsubscribe(struct v4l2_fh *fh, const struct v4l2_event_subscription *sub); +/** + * v4l2_event_unsubscribe_all - Unsubscribes to all events + * + * @fh: pointer to &struct v4l2_fh + */ void v4l2_event_unsubscribe_all(struct v4l2_fh *fh); -int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh, + +/** + * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe() + * + * @sd: pointer to &struct v4l2_subdev + * @fh: pointer to &struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + * + * .. note:: + * + * This function should be used for the &struct v4l2_subdev_core_ops + * %unsubscribe_event field. + */ +int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, + struct v4l2_fh *fh, struct v4l2_event_subscription *sub); +/** + * v4l2_src_change_event_subscribe - + * + * @fh: pointer to struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + */ int v4l2_src_change_event_subscribe(struct v4l2_fh *fh, - const struct v4l2_event_subscription *sub); + const struct v4l2_event_subscription *sub); +/** + * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(), + * meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE. + * + * @sd: pointer to &struct v4l2_subdev + * @fh: pointer to &struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + */ int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd, - struct v4l2_fh *fh, struct v4l2_event_subscription *sub); + struct v4l2_fh *fh, + struct v4l2_event_subscription *sub); #endif /* V4L2_EVENT_H */ -- cgit v1.2.3 From 4ada120eaa2d57378b9c270273e8c0b7e542f019 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 09:06:45 -0300 Subject: [media] v4l2-fh.h: add documentation for it This header file was undocumented. Add documentation for it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-core.rst | 1 + Documentation/media/kapi/v4l2-fh.rst | 3 + include/media/v4l2-fh.h | 128 ++++++++++++++++++++++++--------- 3 files changed, 100 insertions(+), 32 deletions(-) create mode 100644 Documentation/media/kapi/v4l2-fh.rst (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index 6fa30f8908dd..67eaf0c0b6b6 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -8,6 +8,7 @@ Video2Linux devices v4l2-dev v4l2-controls v4l2-device + v4l2-fh v4l2-dv-timings v4l2-event v4l2-flash-led-class diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst new file mode 100644 index 000000000000..9309c18e967a --- /dev/null +++ b/Documentation/media/kapi/v4l2-fh.rst @@ -0,0 +1,3 @@ +V4L2 File Handler kAPI +^^^^^^^^^^^^^^^^^^^^^^ +.. kernel-doc:: include/media/v4l2-fh.h diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h index 803516775162..e19e6246e21c 100644 --- a/include/media/v4l2-fh.h +++ b/include/media/v4l2-fh.h @@ -33,6 +33,21 @@ struct video_device; struct v4l2_ctrl_handler; +/** + * struct v4l2_fh - Describes a V4L2 file handler + * + * @list: list of file handlers + * @vdev: pointer to &struct video_device + * @ctrl_handler: pointer to &struct v4l2_ctrl_handler + * @prio: priority of the file handler, as defined by &enum v4l2_priority + * + * @wait: event' s wait queue + * @subscribed: list of subscribed events + * @available: list of events waiting to be dequeued + * @navailable: number of available events at @available list + * @sequence: event sequence number + * @m2m_ctx: pointer to &struct v4l2_m2m_ctx + */ struct v4l2_fh { struct list_head list; struct video_device *vdev; @@ -41,8 +56,8 @@ struct v4l2_fh { /* Events */ wait_queue_head_t wait; - struct list_head subscribed; /* Subscribed events */ - struct list_head available; /* Dequeueable event */ + struct list_head subscribed; + struct list_head available; unsigned int navailable; u32 sequence; @@ -51,53 +66,102 @@ struct v4l2_fh { #endif }; -/* - * Initialise the file handle. Parts of the V4L2 framework using the +/** + * v4l2_fh_init - Initialise the file handle. + * + * @fh: pointer to &struct v4l2_fh + * @vdev: pointer to &struct video_device + * + * Parts of the V4L2 framework using the * file handles should be initialised in this function. Must be called - * from driver's v4l2_file_operations->open() handler if the driver - * uses v4l2_fh. + * from driver's v4l2_file_operations->open\(\) handler if the driver + * uses &struct v4l2_fh. */ void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev); -/* - * Add the fh to the list of file handles on a video_device. The file - * handle must be initialised first. + +/** + * v4l2_fh_add - Add the fh to the list of file handles on a video_device. + * + * @fh: pointer to &struct v4l2_fh + * + * .. note:: + * The @fh file handle must be initialised first. */ void v4l2_fh_add(struct v4l2_fh *fh); -/* - * Can be used as the open() op of v4l2_file_operations. - * It allocates a v4l2_fh and inits and adds it to the video_device associated - * with the file pointer. + +/** + * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op + * of v4l2_file_operations. + * + * @filp: pointer to struct file + * + * It allocates a v4l2_fh and inits and adds it to the &struct video_device + * associated with the file pointer. */ int v4l2_fh_open(struct file *filp); -/* - * Remove file handle from the list of file handles. Must be called in - * v4l2_file_operations->release() handler if the driver uses v4l2_fh. - * On error filp->private_data will be NULL, otherwise it will point to - * the v4l2_fh struct. + +/** + * v4l2_fh_del - Remove file handle from the list of file handles. + * + * @fh: pointer to &struct v4l2_fh + * + * On error filp->private_data will be %NULL, otherwise it will point to + * the &struct v4l2_fh. + * + * .. note:: + * Must be called in v4l2_file_operations->release\(\) handler if the driver + * uses &struct v4l2_fh. */ void v4l2_fh_del(struct v4l2_fh *fh); -/* - * Release resources related to a file handle. Parts of the V4L2 - * framework using the v4l2_fh must release their resources here, too. - * Must be called in v4l2_file_operations->release() handler if the - * driver uses v4l2_fh. + +/** + * v4l2_fh_exit - Release resources related to a file handle. + * + * @fh: pointer to &struct v4l2_fh + * + * Parts of the V4L2 framework using the v4l2_fh must release their + * resources here, too. + * + * .. note:: + * Must be called in v4l2_file_operations->release\(\) handler if the + * driver uses &struct v4l2_fh. */ void v4l2_fh_exit(struct v4l2_fh *fh); -/* - * Can be used as the release() op of v4l2_file_operations. + +/** + * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op + * of v4l2_file_operations. + * + * @filp: pointer to struct file + * * It deletes and exits the v4l2_fh associated with the file pointer and * frees it. It will do nothing if filp->private_data (the pointer to the - * v4l2_fh struct) is NULL. This function always returns 0. + * v4l2_fh struct) is %NULL. + * + * This function always returns 0. */ int v4l2_fh_release(struct file *filp); -/* - * Returns 1 if this filehandle is the only filehandle opened for the - * associated video_device. If fh is NULL, then it returns 0. + +/** + * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle + * opened for the associated video_device. + * + * @fh: pointer to &struct v4l2_fh + * + * If @fh is NULL, then it returns 0. */ int v4l2_fh_is_singular(struct v4l2_fh *fh); -/* - * Helper function with struct file as argument. If filp->private_data is - * NULL, then it will return 0. + +/** + * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only + * filehandle opened for the associated video_device. + * + * @filp: pointer to struct file + * + * This is a helper function variant of v4l2_fh_is_singular() with uses + * struct file as argument. + * + * If filp->private_data is %NULL, then it will return 0. */ static inline int v4l2_fh_is_singular_file(struct file *filp) { -- cgit v1.2.3 From 6d85d7d7eb86f0f16f9da94d5999ed4d55396d2e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 10:58:03 -0300 Subject: [media] doc-rst: Fix some typedef ugly warnings Sphinx can't handle well typedefs. Change two typedef occurrences, in order to cleanup some of such warnings. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ctrls.h | 4 +++- include/media/v4l2-dv-timings.h | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index 8b59336b2217..d6f63406b885 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -534,6 +534,8 @@ 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); +typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl); + /** * v4l2_ctrl_add_handler() - Add all controls from handler @add to * handler @hdl. @@ -550,7 +552,7 @@ 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. diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h index 1113c8874c26..65caadf13eec 100644 --- a/include/media/v4l2-dv-timings.h +++ b/include/media/v4l2-dv-timings.h @@ -28,7 +28,7 @@ */ extern const struct v4l2_dv_timings v4l2_dv_timings_presets[]; -/** +/* * v4l2_check_dv_timings_fnc - timings check callback * * @t: the v4l2_dv_timings struct. -- cgit v1.2.3 From 8ec4bee7c10e55ca9df398a28cbd53beb26b343c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 13:57:29 -0300 Subject: [media] v4l2-ctrls.h: fully document the header file There are lots of undocumented stuff on this header. Document them. Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-ctrls.h | 365 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 279 insertions(+), 86 deletions(-) (limited to 'include') diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h index d6f63406b885..178a88d45aea 100644 --- a/include/media/v4l2-ctrls.h +++ b/include/media/v4l2-ctrls.h @@ -1,21 +1,17 @@ /* - V4L2 controls support header. - - Copyright (C) 2010 Hans Verkuil - - 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 + * + * 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,17 +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. @@ -556,6 +587,7 @@ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl, /** * 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 @@ -567,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.) @@ -604,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. * @@ -634,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. * @@ -673,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. @@ -703,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. @@ -714,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 @@ -727,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 @@ -736,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. * @@ -745,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 @@ -758,8 +804,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); /** * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl(). + * * @ctrl: The control. - * @val: The new value. + * @val: TheControls name new value. * * This sets the control's new value safely by going through the control * framework. This function assumes the control's handler is already locked, @@ -769,7 +816,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); */ int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); -/** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver. +/** + * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from + * within a driver. * @ctrl: The control. * @val: The new value. * @@ -793,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 @@ -817,7 +867,8 @@ s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl); */ int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val); -/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value +/** + * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value * from within a driver. * * @ctrl: The control. @@ -840,7 +891,8 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val) return rval; } -/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). +/** + * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). * * @ctrl: The control. * @s: The new string. @@ -853,12 +905,13 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val) */ int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s); -/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value +/** + * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value * from within a driver. * * @ctrl: The control. * @s: The new string. - * + *Controls name * This sets the control's new string safely by going through the control * framework. This function will lock the control's handler, so it cannot be * used from within the &v4l2_ctrl_ops functions. @@ -878,39 +931,179 @@ static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s) /* Internal helper functions that deal with control events. */ extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops; + +/** + * v4l2_ctrl_replace - Function to be used as a callback to + * &struct v4l2_subscribed_event_ops replace\(\) + * + * @old: pointer to :ref:`struct v4l2_event ` with the reported + * event; + * @new: pointer to :ref:`struct 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 ` with the reported + * event; + * @new: pointer to :ref:`struct 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` ioctl + * + * @fh: pointer to &struct v4l2_fh + * @hdl: pointer to &struct v4l2_ctrl_handler + * @c: pointer to &struct v4l2_ext_controls + * + * If hdl == NULL then they will all return -EINVAL. + */ int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl, - struct v4l2_ext_controls *c); + struct v4l2_ext_controls *c); -/* Can be used as a subscribe_event function that just subscribes control - events. */ +/** + * v4l2_ctrl_subdev_subscribe_event - Helper function to implement + * as a &struct v4l2_subdev_core_ops subscribe_event function + * that just subscribes control events. + * + * @sd: pointer to &struct v4l2_subdev + * @fh: pointer to &struct v4l2_fh + * @sub: pointer to &struct v4l2_event_subscription + */ int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh, struct v4l2_event_subscription *sub); -/* Log all controls owned by subdev's control handler. */ +/** + * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control + * handler. + * + * @sd: pointer to &struct v4l2_subdev + */ int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd); #endif -- cgit v1.2.3 From c91661f1e69bec066c970f3a911de5713ec4a91e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 16:22:41 -0300 Subject: [media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops This struct is mentioned at the kAPI docbook. So, let's document it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-common.rst | 2 + include/media/v4l2-ioctl.h | 266 +++++++++++++++++++++++++++++++ 2 files changed, 268 insertions(+) (limited to 'include') diff --git a/Documentation/media/kapi/v4l2-common.rst b/Documentation/media/kapi/v4l2-common.rst index d1ea1c9e35a0..525d804871ff 100644 --- a/Documentation/media/kapi/v4l2-common.rst +++ b/Documentation/media/kapi/v4l2-common.rst @@ -2,3 +2,5 @@ V4L2 common functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. kernel-doc:: include/media/v4l2-common.h + +.. kernel-doc:: include/media/v4l2-ioctl.h diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h index 017ffb2220c7..8b1d19bc9b0e 100644 --- a/include/media/v4l2-ioctl.h +++ b/include/media/v4l2-ioctl.h @@ -17,6 +17,272 @@ struct v4l2_fh; +/** + * struct v4l2_ioctl_ops - describe operations for each V4L2 ioctl + * + * @vidioc_querycap: pointer to the function that implements + * :ref:`VIDIOC_QUERYCAP ` ioctl + * @vidioc_enum_fmt_vid_cap: pointer to the function that implements + * :ref:`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 ` ioctl logic + * for video overlay + * @vidioc_enum_fmt_vid_out: pointer to the function that implements + * :ref:`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 ` ioctl logic + * for video capture in multiplane mode + * @vidioc_enum_fmt_vid_out_mplane: pointer to the function that implements + * :ref:`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 ` ioctl logic + * for Software Defined Radio capture + * @vidioc_enum_fmt_sdr_out: pointer to the function that implements + * :ref:`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 ` ioctl logic for video capture + * in single plane mode + * @vidioc_g_fmt_vid_overlay: pointer to the function that implements + * :ref:`VIDIOC_G_FMT ` ioctl logic for video overlay + * @vidioc_g_fmt_vid_out: pointer to the function that implements + * :ref:`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 ` ioctl logic for video overlay output + * @vidioc_g_fmt_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_G_FMT ` ioctl logic for raw VBI capture + * @vidioc_g_fmt_vbi_out: pointer to the function that implements + * :ref:`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 ` ioctl logic for sliced VBI capture + * @vidioc_g_fmt_sliced_vbi_out: pointer to the function that implements + * :ref:`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 ` 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 ` ioctl logic for video out + * in multiplane plane mode + * @vidioc_g_fmt_sdr_cap: pointer to the function that implements + * :ref:`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 ` ioctl logic for Software Defined + * Radio output + * @vidioc_s_fmt_vid_cap: pointer to the function that implements + * :ref:`VIDIOC_S_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 ` ioctl logic for video overlay + * @vidioc_s_fmt_vid_out: pointer to the function that implements + * :ref:`VIDIOC_S_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 ` ioctl logic for video overlay output + * @vidioc_s_fmt_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for raw VBI capture + * @vidioc_s_fmt_vbi_out: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for raw VBI output + * @vidioc_s_fmt_sliced_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for sliced VBI capture + * @vidioc_s_fmt_sliced_vbi_out: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for sliced VBI output + * @vidioc_s_fmt_vid_cap_mplane: pointer to the function that implements + * :ref:`VIDIOC_S_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 ` ioctl logic for video out + * in multiplane plane mode + * @vidioc_s_fmt_sdr_cap: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for Software Defined + * Radio capture + * @vidioc_s_fmt_sdr_out: pointer to the function that implements + * :ref:`VIDIOC_S_FMT ` ioctl logic for Software Defined + * Radio output + * @vidioc_try_fmt_vid_cap: pointer to the function that implements + * :ref:`VIDIOC_TRY_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 ` ioctl logic for video overlay + * @vidioc_try_fmt_vid_out: pointer to the function that implements + * :ref:`VIDIOC_TRY_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 ` ioctl logic for video overlay + * output + * @vidioc_try_fmt_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for raw VBI capture + * @vidioc_try_fmt_vbi_out: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for raw VBI output + * @vidioc_try_fmt_sliced_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for sliced VBI + * capture + * @vidioc_try_fmt_sliced_vbi_out: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for sliced VBI output + * @vidioc_try_fmt_vid_cap_mplane: pointer to the function that implements + * :ref:`VIDIOC_TRY_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 ` ioctl logic for video out + * in multiplane plane mode + * @vidioc_try_fmt_sdr_cap: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for Software Defined + * Radio capture + * @vidioc_try_fmt_sdr_out: pointer to the function that implements + * :ref:`VIDIOC_TRY_FMT ` ioctl logic for Software Defined + * Radio output + * @vidioc_reqbufs: pointer to the function that implements + * :ref:`VIDIOC_REQBUFS ` ioctl + * @vidioc_querybuf: pointer to the function that implements + * :ref:`VIDIOC_QUERYBUF ` ioctl + * @vidioc_qbuf: pointer to the function that implements + * :ref:`VIDIOC_QBUF ` ioctl + * @vidioc_expbuf: pointer to the function that implements + * :ref:`VIDIOC_EXPBUF ` ioctl + * @vidioc_dqbuf: pointer to the function that implements + * :ref:`VIDIOC_DQBUF ` ioctl + * @vidioc_create_bufs: pointer to the function that implements + * :ref:`VIDIOC_CREATE_BUFS ` ioctl + * @vidioc_prepare_buf: pointer to the function that implements + * :ref:`VIDIOC_PREPARE_BUF ` ioctl + * @vidioc_overlay: pointer to the function that implements + * :ref:`VIDIOC_OVERLAY ` ioctl + * @vidioc_g_fbuf: pointer to the function that implements + * :ref:`VIDIOC_G_FBUF ` ioctl + * @vidioc_s_fbuf: pointer to the function that implements + * :ref:`VIDIOC_S_FBUF ` ioctl + * @vidioc_streamon: pointer to the function that implements + * :ref:`VIDIOC_STREAMON ` ioctl + * @vidioc_streamoff: pointer to the function that implements + * :ref:`VIDIOC_STREAMOFF ` ioctl + * @vidioc_g_std: pointer to the function that implements + * :ref:`VIDIOC_G_STD ` ioctl + * @vidioc_s_std: pointer to the function that implements + * :ref:`VIDIOC_S_STD ` ioctl + * @vidioc_querystd: pointer to the function that implements + * :ref:`VIDIOC_QUERYSTD ` ioctl + * @vidioc_enum_input: pointer to the function that implements + * :ref:`VIDIOC_ENUM_INPUT ` ioctl + * @vidioc_g_input: pointer to the function that implements + * :ref:`VIDIOC_G_INPUT ` ioctl + * @vidioc_s_input: pointer to the function that implements + * :ref:`VIDIOC_S_INPUT ` ioctl + * @vidioc_enum_output: pointer to the function that implements + * :ref:`VIDIOC_ENUM_OUTPUT ` ioctl + * @vidioc_g_output: pointer to the function that implements + * :ref:`VIDIOC_G_OUTPUT ` ioctl + * @vidioc_s_output: pointer to the function that implements + * :ref:`VIDIOC_S_OUTPUT ` ioctl + * @vidioc_queryctrl: pointer to the function that implements + * :ref:`VIDIOC_QUERYCTRL ` ioctl + * @vidioc_query_ext_ctrl: pointer to the function that implements + * :ref:`VIDIOC_QUERY_EXT_CTRL ` ioctl + * @vidioc_g_ctrl: pointer to the function that implements + * :ref:`VIDIOC_G_CTRL ` ioctl + * @vidioc_s_ctrl: pointer to the function that implements + * :ref:`VIDIOC_S_CTRL ` ioctl + * @vidioc_g_ext_ctrls: pointer to the function that implements + * :ref:`VIDIOC_G_EXT_CTRLS ` ioctl + * @vidioc_s_ext_ctrls: pointer to the function that implements + * :ref:`VIDIOC_S_EXT_CTRLS ` ioctl + * @vidioc_try_ext_ctrls: pointer to the function that implements + * :ref:`VIDIOC_TRY_EXT_CTRLS ` ioctl + * @vidioc_querymenu: pointer to the function that implements + * :ref:`VIDIOC_QUERYMENU ` ioctl + * @vidioc_enumaudio: pointer to the function that implements + * :ref:`VIDIOC_ENUMAUDIO ` ioctl + * @vidioc_g_audio: pointer to the function that implements + * :ref:`VIDIOC_G_AUDIO ` ioctl + * @vidioc_s_audio: pointer to the function that implements + * :ref:`VIDIOC_S_AUDIO ` ioctl + * @vidioc_enumaudout: pointer to the function that implements + * :ref:`VIDIOC_ENUMAUDOUT ` ioctl + * @vidioc_g_audout: pointer to the function that implements + * :ref:`VIDIOC_G_AUDOUT ` ioctl + * @vidioc_s_audout: pointer to the function that implements + * :ref:`VIDIOC_S_AUDOUT ` ioctl + * @vidioc_g_modulator: pointer to the function that implements + * :ref:`VIDIOC_G_MODULATOR ` ioctl + * @vidioc_s_modulator: pointer to the function that implements + * :ref:`VIDIOC_S_MODULATOR ` ioctl + * @vidioc_cropcap: pointer to the function that implements + * :ref:`VIDIOC_CROPCAP ` ioctl + * @vidioc_g_crop: pointer to the function that implements + * :ref:`VIDIOC_G_CROP ` ioctl + * @vidioc_s_crop: pointer to the function that implements + * :ref:`VIDIOC_S_CROP ` ioctl + * @vidioc_g_selection: pointer to the function that implements + * :ref:`VIDIOC_G_SELECTION ` ioctl + * @vidioc_s_selection: pointer to the function that implements + * :ref:`VIDIOC_S_SELECTION ` ioctl + * @vidioc_g_jpegcomp: pointer to the function that implements + * :ref:`VIDIOC_G_JPEGCOMP ` ioctl + * @vidioc_s_jpegcomp: pointer to the function that implements + * :ref:`VIDIOC_S_JPEGCOMP ` ioctl + * @vidioc_g_enc_index: pointer to the function that implements + * :ref:`VIDIOC_G_ENC_INDEX ` ioctl + * @vidioc_encoder_cmd: pointer to the function that implements + * :ref:`VIDIOC_ENCODER_CMD ` ioctl + * @vidioc_try_encoder_cmd: pointer to the function that implements + * :ref:`VIDIOC_TRY_ENCODER_CMD ` ioctl + * @vidioc_decoder_cmd: pointer to the function that implements + * :ref:`VIDIOC_DECODER_CMD ` ioctl + * @vidioc_try_decoder_cmd: pointer to the function that implements + * :ref:`VIDIOC_TRY_DECODER_CMD ` ioctl + * @vidioc_g_parm: pointer to the function that implements + * :ref:`VIDIOC_G_PARM ` ioctl + * @vidioc_s_parm: pointer to the function that implements + * :ref:`VIDIOC_S_PARM ` ioctl + * @vidioc_g_tuner: pointer to the function that implements + * :ref:`VIDIOC_G_TUNER ` ioctl + * @vidioc_s_tuner: pointer to the function that implements + * :ref:`VIDIOC_S_TUNER ` ioctl + * @vidioc_g_frequency: pointer to the function that implements + * :ref:`VIDIOC_G_FREQUENCY ` ioctl + * @vidioc_s_frequency: pointer to the function that implements + * :ref:`VIDIOC_S_FREQUENCY ` ioctl + * @vidioc_enum_freq_bands: pointer to the function that implements + * :ref:`VIDIOC_ENUM_FREQ_BANDS ` ioctl + * @vidioc_g_sliced_vbi_cap: pointer to the function that implements + * :ref:`VIDIOC_G_SLICED_VBI_CAP ` ioctl + * @vidioc_log_status: pointer to the function that implements + * :ref:`VIDIOC_LOG_STATUS ` ioctl + * @vidioc_s_hw_freq_seek: pointer to the function that implements + * :ref:`VIDIOC_S_HW_FREQ_SEEK ` ioctl + * @vidioc_g_register: pointer to the function that implements + * :ref:`VIDIOC_DBG_G_REGISTER ` ioctl + * @vidioc_s_register: pointer to the function that implements + * :ref:`VIDIOC_DBG_S_REGISTER ` ioctl + * @vidioc_g_chip_info: pointer to the function that implements + * :ref:`VIDIOC_DBG_G_CHIP_INFO ` ioctl + * @vidioc_enum_framesizes: pointer to the function that implements + * :ref:`VIDIOC_ENUM_FRAMESIZES ` ioctl + * @vidioc_enum_frameintervals: pointer to the function that implements + * :ref:`VIDIOC_ENUM_FRAMEINTERVALS ` ioctl + * @vidioc_s_dv_timings: pointer to the function that implements + * :ref:`VIDIOC_S_DV_TIMINGS ` ioctl + * @vidioc_g_dv_timings: pointer to the function that implements + * :ref:`VIDIOC_G_DV_TIMINGS ` ioctl + * @vidioc_query_dv_timings: pointer to the function that implements + * :ref:`VIDIOC_QUERY_DV_TIMINGS ` ioctl + * @vidioc_enum_dv_timings: pointer to the function that implements + * :ref:`VIDIOC_ENUM_DV_TIMINGS ` ioctl + * @vidioc_dv_timings_cap: pointer to the function that implements + * :ref:`VIDIOC_DV_TIMINGS_CAP ` ioctl + * @vidioc_g_edid: pointer to the function that implements + * :ref:`VIDIOC_G_EDID ` ioctl + * @vidioc_s_edid: pointer to the function that implements + * :ref:`VIDIOC_S_EDID ` ioctl + * @vidioc_subscribe_event: pointer to the function that implements + * :ref:`VIDIOC_SUBSCRIBE_EVENT ` ioctl + * @vidioc_unsubscribe_event: pointer to the function that implements + * :ref:`VIDIOC_UNSUBSCRIBE_EVENT ` ioctl + * @vidioc_default: pointed used to allow other ioctls + */ struct v4l2_ioctl_ops { /* ioctl callbacks */ -- cgit v1.2.3 From 564aaf69208d6f9e37cd82c06b889e5d9c59bfb6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 23 Jul 2016 07:12:03 -0300 Subject: [media] doc-rst: add some needed escape codes Some extra escape codes are needed to avoid Sphinx to not identify the tags. Signed-off-by: Mauro Carvalho Chehab --- drivers/media/dvb-core/demux.h | 4 +-- drivers/media/dvb-core/dvb_frontend.h | 26 +++++++++--------- include/media/media-entity.h | 2 +- include/media/v4l2-dev.h | 4 +-- include/media/videobuf2-core.h | 50 +++++++++++++++++------------------ 5 files changed, 43 insertions(+), 43 deletions(-) (limited to 'include') diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h index 99379c09aa7f..4b4c1da20f4b 100644 --- a/drivers/media/dvb-core/demux.h +++ b/drivers/media/dvb-core/demux.h @@ -65,7 +65,7 @@ */ /** - * enum ts_filter_type - filter type bitmap for dmx_ts_feed.set() + * enum ts_filter_type - filter type bitmap for dmx_ts_feed.set\(\) * * @TS_PACKET: Send TS packets (188 bytes) to callback (default). * @TS_PAYLOAD_ONLY: In case TS_PACKET is set, only send the TS payload @@ -339,7 +339,7 @@ struct dmx_frontend { * @DMX_SECTION_FILTERING: set if section filtering is supported; * @DMX_MEMORY_BASED_FILTERING: set if write() available. * - * Those flags are OR'ed in the &dmx_demux.&capabilities field + * Those flags are OR'ed in the &dmx_demux.capabilities field */ enum dmx_demux_caps { DMX_TS_FILTERING = 1, diff --git a/drivers/media/dvb-core/dvb_frontend.h b/drivers/media/dvb-core/dvb_frontend.h index 8c551174537a..fb6e84811504 100644 --- a/drivers/media/dvb-core/dvb_frontend.h +++ b/drivers/media/dvb-core/dvb_frontend.h @@ -387,7 +387,7 @@ struct dtv_frontend_properties; * FE_DISHNETWORK_SEND_LEGACY_CMD ioctl (only Satellite). * Drivers should not use this, except when the DVB * core emulation fails to provide proper support (e.g. - * if set_voltage() takes more than 8ms to work), and + * if @set_voltage takes more than 8ms to work), and * when backward compatibility with this legacy API is * required. * @i2c_gate_ctrl: controls the I2C gate. Newer drivers should use I2C @@ -722,13 +722,13 @@ void dvb_frontend_detach(struct dvb_frontend *fe); * This function prepares a Digital TV frontend to suspend. * * In order to prepare the tuner to suspend, if - * &dvb_frontend_ops.tuner_ops.suspend() is available, it calls it. Otherwise, - * it will call &dvb_frontend_ops.tuner_ops.sleep(), if available. + * &dvb_frontend_ops.tuner_ops.suspend\(\) is available, it calls it. Otherwise, + * it will call &dvb_frontend_ops.tuner_ops.sleep\(\), if available. * - * It will also call &dvb_frontend_ops.sleep() to put the demod to suspend. + * It will also call &dvb_frontend_ops.sleep\(\) to put the demod to suspend. * - * The drivers should also call dvb_frontend_suspend() as part of their - * handler for the &device_driver.suspend(). + * The drivers should also call dvb_frontend_suspend\(\) as part of their + * handler for the &device_driver.suspend\(\). */ int dvb_frontend_suspend(struct dvb_frontend *fe); @@ -739,17 +739,17 @@ int dvb_frontend_suspend(struct dvb_frontend *fe); * * This function resumes the usual operation of the tuner after resume. * - * In order to resume the frontend, it calls the demod &dvb_frontend_ops.init(). + * In order to resume the frontend, it calls the demod &dvb_frontend_ops.init\(\). * - * If &dvb_frontend_ops.tuner_ops.resume() is available, It, it calls it. - * Otherwise,t will call &dvb_frontend_ops.tuner_ops.init(), if available. + * If &dvb_frontend_ops.tuner_ops.resume\(\) is available, It, it calls it. + * Otherwise,t will call &dvb_frontend_ops.tuner_ops.init\(\), if available. * * Once tuner and demods are resumed, it will enforce that the SEC voltage and * tone are restored to their previous values and wake up the frontend's * kthread in order to retune the frontend. * * The drivers should also call dvb_frontend_resume() as part of their - * handler for the &device_driver.resume(). + * handler for the &device_driver.resume\(\). */ int dvb_frontend_resume(struct dvb_frontend *fe); @@ -758,7 +758,7 @@ int dvb_frontend_resume(struct dvb_frontend *fe); * * @fe: pointer to the frontend struct * - * Calls &dvb_frontend_ops.init() and &dvb_frontend_ops.tuner_ops.init(), + * Calls &dvb_frontend_ops.init\(\) and &dvb_frontend_ops.tuner_ops.init\(\), * and resets SEC tone and voltage (for Satellite systems). * * NOTE: Currently, this function is used only by one driver (budget-av). @@ -780,14 +780,14 @@ void dvb_frontend_reinitialise(struct dvb_frontend *fe); * satellite subsystem. * * Its used internally by the DVB frontend core, in order to emulate - * %FE_DISHNETWORK_SEND_LEGACY_CMD using the &dvb_frontend_ops.set_voltage() + * %FE_DISHNETWORK_SEND_LEGACY_CMD using the &dvb_frontend_ops.set_voltage\(\) * callback. * * NOTE: it should not be used at the drivers, as the emulation for the * legacy callback is provided by the Kernel. The only situation where this * should be at the drivers is when there are some bugs at the hardware that * would prevent the core emulation to work. On such cases, the driver would - * be writing a &dvb_frontend_ops.dishnetwork_send_legacy_command() and + * be writing a &dvb_frontend_ops.dishnetwork_send_legacy_command\(\) and * calling this function directly. */ void dvb_frontend_sleep_until(ktime_t *waketime, u32 add_usec); diff --git a/include/media/media-entity.h b/include/media/media-entity.h index 17390cc7b538..09b03c17784d 100644 --- a/include/media/media-entity.h +++ b/include/media/media-entity.h @@ -540,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. diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h index 5921c24565cf..a122b1bd40f9 100644 --- a/include/media/v4l2-dev.h +++ b/include/media/v4l2-dev.h @@ -374,13 +374,13 @@ struct video_device * __must_check video_device_alloc(void); * * @vdev: pointer to &struct video_device * - * Can also be used for video_device->release(). + * Can also be used for video_device->release\(\). */ void video_device_release(struct video_device *vdev); /** * video_device_release_empty - helper function to implement the - * video_device->release() callback. + * video_device->release\(\) callback. * * @vdev: pointer to &struct video_device * diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h index c346beaaeae6..946340ce7701 100644 --- a/include/media/videobuf2-core.h +++ b/include/media/videobuf2-core.h @@ -277,7 +277,7 @@ 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 @@ -286,17 +286,17 @@ struct vb2_buffer { * The driver should return the required number of buffers * in \*num_buffers, the required number of planes per * buffer in \*num_planes, the size of each plane should be - * set in the sizes[] array and optional per-plane - * allocator specific device in the alloc_devs[] array. - * When called from VIDIOC_REQBUFS, *num_planes == 0, the + * 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 * 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 + * 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 @@ -311,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 @@ -323,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 @@ -347,16 +347,16 @@ struct vb2_buffer { * many buffers have been queued up by userspace. * @stop_streaming: called when 'streaming' state must be disabled; driver * should stop any DMA transactions or wait until they - * finish and give back all buffers it got from buf_queue() - * callback by calling @vb2_buffer_done() with either - * VB2_BUF_STATE_DONE or VB2_BUF_STATE_ERROR; may use + * finish and give back all buffers it got from &buf_queue + * callback by calling @vb2_buffer_done\(\) with either + * %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use * vb2_wait_for_all_buffers() function * @buf_queue: passes buffer vb to the driver; driver may start * hardware operation on this buffer; driver should give * the buffer back by calling vb2_buffer_done() function; - * it is allways called after calling STREAMON ioctl; + * it is allways called after calling %VIDIOC_STREAMON ioctl; * might be called before start_streaming callback if user - * pre-queued buffers before calling STREAMON. + * pre-queued buffers before calling %VIDIOC_STREAMON. */ struct vb2_ops { int (*queue_setup)(struct vb2_queue *q, -- cgit v1.2.3