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 --- drivers/media/dvb-core/demux.h | 71 ++--------------------------------- drivers/media/dvb-core/dvb_frontend.h | 27 ++----------- 2 files changed, 8 insertions(+), 90 deletions(-) (limited to 'drivers') 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 -- cgit v1.2.3-58-ga151 From d2f019851a404d71f6581b62b721f0b8222c3521 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 17 Jul 2016 11:25:37 -0300 Subject: [media] doc-rst: Fix conversion for dvb-core.rst The conversion from DocBook required some fixes: - 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/dtv-core.rst | 40 +++++++++++----- drivers/media/dvb-core/demux.h | 90 +++++++++++++++++------------------ 2 files changed, 72 insertions(+), 58 deletions(-) (limited to 'drivers') diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index fa462d5d0247..3291190c1865 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -11,6 +11,15 @@ Digital TV Common functions .. kernel-doc:: drivers/media/dvb-core/dvbdev.h + +.. kernel-doc:: drivers/media/dvb-core/dvb_math.h + :export: drivers/media/dvb-core/dvb_math.c + +.. kernel-doc:: drivers/media/dvb-core/dvbdev.h + :export: drivers/media/dvb-core/dvbdev.c + + + Digital TV Frontend kABI ------------------------ @@ -24,17 +33,20 @@ 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(), +the frontend demod, tuner and SEC devices and call +:cpp:func:`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. +detach/removal, the bridge driver should call +:cpp:func:`dvb_unregister_frontend()` to +remove the frontend from the core and then :cpp:func:`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(). +The drivers should also call :cpp:func:`dvb_frontend_suspend()` as part of +their handler for the :c:type:`device_driver`.\ ``suspend()``, and +:cpp:func:`dvb_frontend_resume()` as +part of their handler for :c:type:`device_driver`.\ ``resume()``. -few other optional functions are provided to handle some special cases. +A few other optional functions are provided to handle some special cases. .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h @@ -70,7 +82,7 @@ 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 +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 @@ -78,7 +90,7 @@ 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 +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 @@ -109,14 +121,16 @@ 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() +This mechanism is implemented by :cpp:func:`dmx_ts_cb()` and :cpp:func:`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 + + +.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h + :export: drivers/media/dvb-core/dvb_ca_en50221.c diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h index e8f04f8872f8..ad42252b1c66 100644 --- a/drivers/media/dvb-core/demux.h +++ b/drivers/media/dvb-core/demux.h @@ -379,10 +379,10 @@ enum dmx_demux_caps { * @open is called and decrement it when @close is called. * The @demux function parameter contains a pointer to the demux API and * instance data. - * It returns - * 0 on success; - * -EUSERS, if maximum usage count was reached; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -EUSERS, if maximum usage count was reached; + * -EINVAL, on bad parameter. * * @close: This function reserves the demux for use by the caller and, if * necessary, initializes the demux. When the demux is no longer needed, @@ -392,10 +392,10 @@ enum dmx_demux_caps { * @open is called and decrement it when @close is called. * The @demux function parameter contains a pointer to the demux API and * instance data. - * It returns - * 0 on success; - * -ENODEV, if demux was not in use (e. g. no users); - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -ENODEV, if demux was not in use (e. g. no users); + * -EINVAL, on bad parameter. * * @write: This function provides the demux driver with a memory buffer * containing TS packets. Instead of receiving TS packets from the DVB @@ -410,12 +410,12 @@ enum dmx_demux_caps { * The @buf function parameter contains a pointer to the TS data in * kernel-space memory. * The @count function parameter contains the length of the TS data. - * It returns - * 0 on success; - * -ERESTARTSYS, if mutex lock was interrupted; - * -EINTR, if a signal handling is pending; - * -ENODEV, if demux was removed; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -ERESTARTSYS, if mutex lock was interrupted; + * -EINTR, if a signal handling is pending; + * -ENODEV, if demux was removed; + * -EINVAL, on bad parameter. * * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS * packets carrying a certain PID. The TS feed normally corresponds to a @@ -426,11 +426,11 @@ enum dmx_demux_caps { * instance data. * The @callback function parameter contains a pointer to the callback * function for passing received TS packet. - * It returns - * 0 on success; - * -ERESTARTSYS, if mutex lock was interrupted; - * -EBUSY, if no more TS feeds is available; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -ERESTARTSYS, if mutex lock was interrupted; + * -EBUSY, if no more TS feeds is available; + * -EINVAL, on bad parameter. * * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed. * Any filtering in progress on the TS feed should be stopped before @@ -439,9 +439,9 @@ enum dmx_demux_caps { * instance data. * The @feed function parameter contains a pointer to the TS feed API and * instance data. - * It returns - * 0 on success; - * -EINVAL on bad parameter. + * It returns: + * 0 on success; + * -EINVAL on bad parameter. * * @allocate_section_feed: Allocates a new section feed, i.e. a demux resource * for filtering and receiving sections. On platforms with hardware @@ -457,10 +457,10 @@ enum dmx_demux_caps { * instance data. * The @callback function parameter contains a pointer to the callback * function for passing received TS packet. - * It returns - * 0 on success; - * -EBUSY, if no more TS feeds is available; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -EBUSY, if no more TS feeds is available; + * -EINVAL, on bad parameter. * * @release_section_feed: Releases the resources allocated with * @allocate_section_feed, including allocated filters. Any filtering in @@ -470,9 +470,9 @@ enum dmx_demux_caps { * instance data. * The @feed function parameter contains a pointer to the TS feed API and * instance data. - * It returns - * 0 on success; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -EINVAL, on bad parameter. * * @add_frontend: Registers a connectivity between a demux and a front-end, * i.e., indicates that the demux can be connected via a call to @@ -486,9 +486,9 @@ enum dmx_demux_caps { * instance data. * The @frontend function parameter contains a pointer to the front-end * instance data. - * It returns - * 0 on success; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -EINVAL, on bad parameter. * * @remove_frontend: Indicates that the given front-end, registered by a call * to @add_frontend, can no longer be connected as a TS source by this @@ -502,10 +502,10 @@ enum dmx_demux_caps { * instance data. * The @frontend function parameter contains a pointer to the front-end * instance data. - * It returns - * 0 on success; - * -ENODEV, if the front-end was not found, - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -ENODEV, if the front-end was not found, + * -EINVAL, on bad parameter. * * @get_frontends: Provides the APIs of the front-ends that have been * registered for this demux. Any of the front-ends obtained with this @@ -529,17 +529,17 @@ enum dmx_demux_caps { * instance data. * The @frontend function parameter contains a pointer to the front-end * instance data. - * It returns - * 0 on success; - * -EINVAL, on bad parameter. + * It returns: + * 0 on success; + * -EINVAL, on bad parameter. * * @disconnect_frontend: Disconnects the demux and a front-end previously * connected by a @connect_frontend call. * The @demux function parameter contains a pointer to the demux API and * instance data. - * It returns - * 0 on success; - * -EINVAL on bad parameter. + * It returns: + * 0 on success; + * -EINVAL on bad parameter. * * @get_pes_pids: Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0, * DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0. @@ -547,9 +547,9 @@ enum dmx_demux_caps { * instance data. * The @pids function parameter contains an array with five u16 elements * where the PIDs will be stored. - * It returns - * 0 on success; - * -EINVAL on bad parameter. + * It returns: + * 0 on success; + * -EINVAL on bad parameter. */ struct dmx_demux { -- cgit v1.2.3-58-ga151 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 'drivers') 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-58-ga151 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 'drivers') 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-58-ga151 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 'drivers') 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-58-ga151 From 7a23c2574d0c7cf3d2ddbf967e3fc32531037a16 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 13:58:09 -0300 Subject: [media] dvb_ringbuffer.h: some documentation improvements Better document a note on this header. While here, better format dvb_ringbuffer_pkt_read_user() to adjust it to CodingStyle. Signed-off-by: Mauro Carvalho Chehab --- drivers/media/dvb-core/dvb_ringbuffer.h | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'drivers') diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h index 3ebc2d34b4a2..8af642399f1e 100644 --- a/drivers/media/dvb-core/dvb_ringbuffer.h +++ b/drivers/media/dvb-core/dvb_ringbuffer.h @@ -150,9 +150,6 @@ extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, /** * dvb_ringbuffer_pkt_read_user - Read from a packet in the ringbuffer. - * Note: unlike dvb_ringbuffer_read(), this does NOT update the read pointer - * in the ringbuffer. You must use dvb_ringbuffer_pkt_dispose() to mark a - * packet as no longer required. * * @rbuf: Ringbuffer concerned. * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). @@ -161,9 +158,17 @@ extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, * @len: Size of destination buffer. * * returns Number of bytes read, or -EFAULT. + * + * .. note:: + * + * unlike dvb_ringbuffer_read(), this does **NOT** update the read pointer + * in the ringbuffer. You must use dvb_ringbuffer_pkt_dispose() to mark a + * packet as no longer required. */ -extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, size_t idx, - int offset, u8 __user *buf, size_t len); +extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, + size_t idx, + int offset, u8 __user *buf, + size_t len); /** * dvb_ringbuffer_pkt_read - Read from a packet in the ringbuffer. -- cgit v1.2.3-58-ga151 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 'drivers') 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-58-ga151