!Edrivers/base/platform.c
!Edrivers/base/bus.c
</sect1>
- <sect1><title>Device Drivers DMA Management</title>
+ <sect1>
+ <title>Buffer Sharing and Synchronization</title>
+ <para>
+ The dma-buf subsystem provides the framework for sharing buffers
+ for hardware (DMA) access across multiple device drivers and
+ subsystems, and for synchronizing asynchronous hardware access.
+ </para>
+ <para>
+ This is used, for example, by drm "prime" multi-GPU support, but
+ is of course not limited to GPU use cases.
+ </para>
+ <para>
+ The three main components of this are: (1) dma-buf, representing
+ a sg_table and exposed to userspace as a file descriptor to allow
+ passing between devices, (2) fence, which provides a mechanism
+ to signal when one device as finished access, and (3) reservation,
+ which manages the shared or exclusive fence(s) associated with
+ the buffer.
+ </para>
+ <sect2><title>dma-buf</title>
!Edrivers/dma-buf/dma-buf.c
+ !Iinclude/linux/dma-buf.h
+ </sect2>
+ <sect2><title>reservation</title>
+ !Pdrivers/dma-buf/reservation.c Reservation Object Overview
+ !Edrivers/dma-buf/reservation.c
+ !Iinclude/linux/reservation.h
+ </sect2>
+ <sect2><title>fence</title>
!Edrivers/dma-buf/fence.c
- !Edrivers/dma-buf/seqno-fence.c
!Iinclude/linux/fence.h
+ !Edrivers/dma-buf/seqno-fence.c
!Iinclude/linux/seqno-fence.h
- !Edrivers/dma-buf/reservation.c
- !Iinclude/linux/reservation.h
!Edrivers/dma-buf/sync_file.c
!Iinclude/linux/sync_file.h
+ </sect2>
+ </sect1>
+ <sect1><title>Device Drivers DMA Management</title>
!Edrivers/base/dma-coherent.c
!Edrivers/base/dma-mapping.c
</sect1>
-->
</chapter>
- <chapter id="mediadev">
- <title>Media Devices</title>
-
- <sect1><title>Video2Linux devices</title>
-!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
- </sect1>
- <sect1><title>Digital TV (DVB) devices</title>
- <sect1><title>Digital TV Common functions</title>
-!Idrivers/media/dvb-core/dvb_math.h
-!Idrivers/media/dvb-core/dvb_ringbuffer.h
-!Idrivers/media/dvb-core/dvbdev.h
- </sect1>
- <sect1><title>Digital TV Frontend kABI</title>
-!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
-!Idrivers/media/dvb-core/dvb_frontend.h
- </sect1>
- <sect1><title>Digital TV Demux kABI</title>
-!Pdrivers/media/dvb-core/demux.h Digital TV Demux
- <sect1><title>Demux Callback API</title>
-!Pdrivers/media/dvb-core/demux.h Demux Callback
- </sect1>
-!Idrivers/media/dvb-core/demux.h
- </sect1>
- <sect1><title>Digital TV Conditional Access kABI</title>
-!Idrivers/media/dvb-core/dvb_ca_en50221.h
- </sect1>
- </sect1>
- <sect1><title>Remote Controller devices</title>
-!Iinclude/media/rc-core.h
-!Iinclude/media/lirc_dev.h
- </sect1>
- <sect1><title>Media Controller devices</title>
-!Pinclude/media/media-device.h Media Controller
-!Iinclude/media/media-device.h
-!Iinclude/media/media-devnode.h
-!Iinclude/media/media-entity.h
- </sect1>
- <sect1><title>Consumer Electronics Control devices</title>
-!Iinclude/media/cec-edid.h
- </sect1>
-
- </chapter>
<chapter id="uart16x50">
<title>16x50 UART Driver</title>
<para>Some receiver have maximum resolution which is defined by internal
sample rate or data format limitations. E.g. it's common that signals can
only be reported in 50 microsecond steps. This integer value is used by
- lircd to automatically adjust the aeps tolerance value in the lircd
+ lircd to automatically adjust the steps tolerance value in the lircd
config file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIRC_SET_{SEND,REC}_CARRIER</term>
<listitem>
- <para>Set send/receive carrier (in Hz).</para>
+ <para>Set send/receive carrier (in Hz). Return 0 on success.</para>
</listitem>
</varlistentry>
<varlistentry>
+V4L2 Controls
+=============
+
Introduction
-============
+------------
The V4L2 control API seems simple enough, but quickly becomes very hard to
implement correctly in drivers. But much of the code needed to handle controls
Objects in the framework
-========================
+------------------------
There are two main objects:
Basic usage for V4L2 and sub-device drivers
-===========================================
+-------------------------------------------
1) Prepare the driver:
1.1) Add the handler to your driver's top-level struct:
+.. code-block:: none
+
struct foo_dev {
...
struct v4l2_ctrl_handler ctrl_handler;
1.2) Initialize the handler:
+.. code-block:: none
+
v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
- The second argument is a hint telling the function how many controls this
- handler is expected to handle. It will allocate a hashtable based on this
- information. It is a hint only.
+The second argument is a hint telling the function how many controls this
+handler is expected to handle. It will allocate a hashtable based on this
+information. It is a hint only.
1.3) Hook the control handler into the driver:
1.3.1) For V4L2 drivers do this:
+.. code-block:: none
+
struct foo_dev {
...
struct v4l2_device v4l2_dev;
foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
- Where foo->v4l2_dev is of type struct v4l2_device.
+Where foo->v4l2_dev is of type struct v4l2_device.
- Finally, remove all control functions from your v4l2_ioctl_ops (if any):
- vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
- vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
- Those are now no longer needed.
+Finally, remove all control functions from your v4l2_ioctl_ops (if any):
+vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
+vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
+Those are now no longer needed.
1.3.2) For sub-device drivers do this:
+.. code-block:: none
+
struct foo_dev {
...
struct v4l2_subdev sd;
foo->sd.ctrl_handler = &foo->ctrl_handler;
- Where foo->sd is of type struct v4l2_subdev.
+Where foo->sd is of type struct v4l2_subdev.
- And set all core control ops in your struct v4l2_subdev_core_ops to these
- helpers:
-
- .. code-block:: none
-
- .queryctrl = v4l2_subdev_queryctrl,
- .querymenu = v4l2_subdev_querymenu,
- .g_ctrl = v4l2_subdev_g_ctrl,
- .s_ctrl = v4l2_subdev_s_ctrl,
- .g_ext_ctrls = v4l2_subdev_g_ext_ctrls,
- .try_ext_ctrls = v4l2_subdev_try_ext_ctrls,
- .s_ext_ctrls = v4l2_subdev_s_ext_ctrls,
-
- Note: this is a temporary solution only. Once all V4L2 drivers that depend
- on subdev drivers are converted to the control framework these helpers will
- no longer be needed.
-
1.4) Clean up the handler at the end:
+.. code-block:: none
+
v4l2_ctrl_handler_free(&foo->ctrl_handler);
You add non-menu controls by calling v4l2_ctrl_new_std:
+.. code-block:: none
+
struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 min, s32 max, u32 step, s32 def);
Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:
+.. code-block:: none
+
struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 max, s32 skip_mask, s32 def);
Menu controls with a driver specific menu are added by calling
v4l2_ctrl_new_std_menu_items:
+.. code-block:: none
+
struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
Integer menu controls with a driver specific menu can be added by calling
v4l2_ctrl_new_int_menu:
+.. code-block:: none
+
struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 max, s32 def, const s64 *qmenu_int);
These functions are typically called right after the v4l2_ctrl_handler_init:
+.. code-block:: none
+
static const s64 exp_bias_qmenu[] = {
-2, -1, 0, 1, 2
};
3) Optionally force initial control setup:
+.. code-block:: none
+
v4l2_ctrl_handler_setup(&foo->ctrl_handler);
This will call s_ctrl for all controls unconditionally. Effectively this
4) Finally: implement the v4l2_ctrl_ops
+.. code-block:: none
+
static const struct v4l2_ctrl_ops foo_ctrl_ops = {
.s_ctrl = foo_s_ctrl,
};
Usually all you need is s_ctrl:
+.. code-block:: none
+
static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
{
struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
-==============================================================================
-
-The remainder of this document deals with more advanced topics and scenarios.
-In practice the basic usage as described above is sufficient for most drivers.
+.. note::
-===============================================================================
+ The remainder sections deal with more advanced controls topics and scenarios.
+ In practice the basic usage as described above is sufficient for most drivers.
Inheriting Controls
-===================
+-------------------
When a sub-device is registered with a V4L2 driver by calling
v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
Accessing Control Values
-========================
+------------------------
The following union is used inside the control framework to access control
values:
-union v4l2_ctrl_ptr {
- s32 *p_s32;
- s64 *p_s64;
- char *p_char;
- void *p;
-};
+.. code-block:: none
+
+ union v4l2_ctrl_ptr {
+ s32 *p_s32;
+ s64 *p_s64;
+ char *p_char;
+ void *p;
+ };
The v4l2_ctrl struct contains these fields that can be used to access both
current and new values:
+.. code-block:: none
+
s32 val;
struct {
s32 val;
If the control has a simple s32 type type, then:
+.. code-block:: none
+
&ctrl->val == ctrl->p_new.p_s32
&ctrl->cur.val == ctrl->p_cur.p_s32
strength read-out that changes continuously. In that case you will need to
implement g_volatile_ctrl like this:
+.. code-block:: none
+
static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
{
switch (ctrl->id) {
To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
+.. code-block:: none
+
ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
if (ctrl)
ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
Outside of the control ops you have to go through to helper functions to get
or set a single control value safely in your driver:
+.. code-block:: none
+
s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
You can also take the handler lock yourself:
+.. code-block:: none
+
mutex_lock(&state->ctrl_handler.lock);
pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
pr_info("Integer value is '%s'\n", ctrl2->cur.val);
Menu Controls
-=============
+-------------
The v4l2_ctrl struct contains this union:
+.. code-block:: none
+
union {
u32 step;
u32 menu_skip_mask;
Custom Controls
-===============
+---------------
Driver specific controls can be created using v4l2_ctrl_new_custom():
+.. code-block:: none
+
static const struct v4l2_ctrl_config ctrl_filter = {
.ops = &ctrl_custom_ops,
.id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
Active and Grabbed Controls
-===========================
+---------------------------
If you get more complex relationships between controls, then you may have to
activate and deactivate controls. For example, if the Chroma AGC control is
Control Clusters
-================
+----------------
By default all controls are independent from the others. But in more
complex scenarios you can get dependencies from one control to another.
In that case you need to 'cluster' them:
+.. code-block:: none
+
struct foo {
struct v4l2_ctrl_handler ctrl_handler;
-#define AUDIO_CL_VOLUME (0)
-#define AUDIO_CL_MUTE (1)
+ #define AUDIO_CL_VOLUME (0)
+ #define AUDIO_CL_MUTE (1)
struct v4l2_ctrl *audio_cluster[2];
...
};
So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
all two controls belonging to the audio_cluster:
+.. code-block:: none
+
static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
{
struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
In the example above the following are equivalent for the VOLUME case:
+.. code-block:: none
+
ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
In practice using cluster arrays like this becomes very tiresome. So instead
the following equivalent method is used:
+.. code-block:: none
+
struct {
/* audio cluster */
struct v4l2_ctrl *volume;
but it serves no other purpose. The effect is the same as creating an
array with two control pointers. So you can just do:
+.. code-block:: none
+
state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
v4l2_ctrl_cluster(2, &state->volume);
Handling autogain/gain-type Controls with Auto Clusters
-=======================================================
+-------------------------------------------------------
A common type of control cluster is one that handles 'auto-foo/foo'-type
controls. Typical examples are autogain/gain, autoexposure/exposure,
In order to simplify this a special variation of v4l2_ctrl_cluster was
introduced:
-void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
- u8 manual_val, bool set_volatile);
+.. code-block:: none
+
+ void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
+ u8 manual_val, bool set_volatile);
The first two arguments are identical to v4l2_ctrl_cluster. The third argument
tells the framework which value switches the cluster into manual mode. The
VIDIOC_LOG_STATUS Support
-=========================
+-------------------------
This ioctl allow you to dump the current status of a driver to the kernel log.
The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
Different Handlers for Different Video Nodes
-============================================
+--------------------------------------------
Usually the V4L2 driver has just one control handler that is global for
all video nodes. But you can also specify different control handlers for
the controls to the first handler, add the other controls to the second
handler and finally add the first handler to the second. For example:
+.. code-block:: none
+
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
Or you can add specific controls to a handler:
+.. code-block:: none
+
volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
What you should not do is make two identical controls for two handlers.
For example:
+.. code-block:: none
+
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
Finding Controls
-================
+----------------
Normally you have created the controls yourself and you can store the struct
v4l2_ctrl pointer into your own struct.
You can do that by calling v4l2_ctrl_find:
+.. code-block:: none
+
struct v4l2_ctrl *volume;
volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
Since v4l2_ctrl_find will lock the handler you have to be careful where you
use it. For example, this is not a good idea:
+.. code-block:: none
+
struct v4l2_ctrl_handler ctrl_handler;
v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
...and in video_ops.s_ctrl:
+.. code-block:: none
+
case V4L2_CID_BRIGHTNESS:
contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
...
Inheriting Controls
-===================
+-------------------
When one control handler is added to another using v4l2_ctrl_add_handler, then
by default all controls from one are merged to the other. But a subdev might
those low-level controls local to the subdev. You can do this by simply
setting the 'is_private' flag of the control to 1:
+.. code-block:: none
+
static const struct v4l2_ctrl_config ctrl_private = {
.ops = &ctrl_custom_ops,
.id = V4L2_CID_...,
V4L2_CTRL_TYPE_CTRL_CLASS Controls
-==================================
+----------------------------------
Controls of this type can be used by GUIs to get the name of the control class.
A fully featured GUI can make a dialog with multiple tabs with each tab
Adding Notify Callbacks
-=======================
+-----------------------
Sometimes the platform or bridge driver needs to be notified when a control
from a sub-device driver changes. You can set a notify callback by calling
this function:
-void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
- void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
+.. code-block:: none
+
+ void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
+ void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
Whenever the give control changes value the notify callback will be called
with a pointer to the control and the priv pointer that was passed with
VERSION = 4
PATCHLEVEL = 7
SUBLEVEL = 0
- EXTRAVERSION = -rc1
+ EXTRAVERSION = -rc6
NAME = Psychotic Stoned Sheep
# *DOCUMENTATION*
CHECKFLAGS := -D__linux__ -Dlinux -D__STDC__ -Dunix -D__unix__ \
-Wbitwise -Wno-return-void $(CF)
+ NOSTDINC_FLAGS =
CFLAGS_MODULE =
AFLAGS_MODULE =
LDFLAGS_MODULE =
CFLAGS_KERNEL =
AFLAGS_KERNEL =
+ LDFLAGS_vmlinux =
CFLAGS_GCOV = -fprofile-arcs -ftest-coverage -fno-tree-loop-im -Wno-maybe-uninitialized
CFLAGS_KCOV = -fsanitize-coverage=trace-pc
@$(MAKE) $(build)=$(package-dir) help
@echo ''
@echo 'Documentation targets:'
+ @$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
+ @echo ''
@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
@echo ''
@echo 'Architecture specific targets ($(SRCARCH)):'
# Documentation targets
# ---------------------------------------------------------------------------
-%docs: scripts_basic FORCE
+DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs cleanmediadocs
+PHONY += $(DOC_TARGETS)
+$(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
+ $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
else # KBUILD_EXTMOD
/*
* 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:
#include <linux/time.h>
#include <linux/dvb/dmx.h>
-/**
- * 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
*/
int type,
enum dmx_ts_pes pes_type,
size_t circular_buffer_size,
- struct timespec timeout);
+ ktime_t timeout);
int (*start_filtering)(struct dmx_ts_feed *feed);
int (*stop_filtering)(struct dmx_ts_feed *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
*
* @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,
* @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
* 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
* 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
* 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
* 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
* 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
* 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
* 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
* 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.
* 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 {
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,
};
/**
* @s_carrier_report: enable carrier reports
* @s_filter: set the scancode filter
* @s_wakeup_filter: set the wakeup scancode filter
+ * @s_timeout: set hardware timeout in ns
*/
struct rc_dev {
struct device dev;
struct rc_scancode_filter *filter);
int (*s_wakeup_filter)(struct rc_dev *dev,
struct rc_scancode_filter *filter);
+ int (*s_timeout)(struct rc_dev *dev,
+ unsigned int timeout);
};
#define to_rc_dev(d) container_of(d, struct rc_dev, dev)
* 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);
/* 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 */
#define RC_MAP_DM1105_NEC "rc-dm1105-nec"
#define RC_MAP_DNTV_LIVE_DVBT_PRO "rc-dntv-live-dvbt-pro"
#define RC_MAP_DNTV_LIVE_DVB_T "rc-dntv-live-dvb-t"
+ #define RC_MAP_DTT200U "rc-dtt200u"
#define RC_MAP_DVBSKY "rc-dvbsky"
#define RC_MAP_EMPTY "rc-empty"
#define RC_MAP_EM_TERRATEC "rc-em-terratec"
* @s_gpio: set GPIO pins. Very simple right now, might need to be extended with
* a direction argument if needed.
*
- * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code.
- *
- * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code.
- *
- * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code.
- *
- * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code.
- *
- * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code.
- *
- * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code.
- *
- * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code.
- *
* @ioctl: called at the end of ioctl() syscall handler at the V4L2 core.
* used to provide support for private ioctls used on the driver.
*
int (*load_fw)(struct v4l2_subdev *sd);
int (*reset)(struct v4l2_subdev *sd, u32 val);
int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
- int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
- int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
- int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
- int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
- int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
- int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
- int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
#ifdef CONFIG_COMPAT
long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd,
*
* @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.
*
*
* @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.
*
VB2_MEMORY_DMABUF = 4,
};
- struct vb2_alloc_ctx;
struct vb2_fileio_data;
struct vb2_threadio_data;
* @put_userptr: inform the allocator that a USERPTR buffer will no longer
* be used.
* @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
- * used for DMABUF memory types; alloc_ctx is the alloc context
+ * used for DMABUF memory types; dev is the alloc device
* dbuf is the shared dma_buf; returns NULL on failure;
* allocator private per-buffer structure on success;
* this needs to be used for further accesses to the buffer.
* @mmap: setup a userspace mapping for a given memory buffer under
* the provided virtual memory region.
*
- * Required ops for USERPTR types: get_userptr, put_userptr.
- * Required ops for MMAP types: alloc, put, num_users, mmap.
- * Required ops for read/write access types: alloc, put, num_users, vaddr.
- * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
- * unmap_dmabuf.
+ * Those operations are used by the videobuf2 core to implement the memory
+ * handling/memory allocators for each type of supported streaming I/O method.
+ *
+ * .. note::
+ * #) Required ops for USERPTR types: get_userptr, put_userptr.
+ *
+ * #) Required ops for MMAP types: alloc, put, num_users, mmap.
+ *
+ * #) Required ops for read/write access types: alloc, put, num_users, vaddr.
+ *
+ * #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
*/
struct vb2_mem_ops {
- void *(*alloc)(void *alloc_ctx, unsigned long size,
- enum dma_data_direction dma_dir,
+ void *(*alloc)(struct device *dev, const struct dma_attrs *attrs,
+ unsigned long size, enum dma_data_direction dma_dir,
gfp_t gfp_flags);
void (*put)(void *buf_priv);
struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags);
- void *(*get_userptr)(void *alloc_ctx, unsigned long vaddr,
+ void *(*get_userptr)(struct device *dev, unsigned long vaddr,
unsigned long size,
enum dma_data_direction dma_dir);
void (*put_userptr)(void *buf_priv);
void (*prepare)(void *buf_priv);
void (*finish)(void *buf_priv);
- void *(*attach_dmabuf)(void *alloc_ctx, struct dma_buf *dbuf,
+ void *(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf,
unsigned long size,
enum dma_data_direction dma_dir);
void (*detach_dmabuf)(void *buf_priv);
* 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
+ * allocator specific device in the alloc_devs[] array.
+ * When called from VIDIOC_REQBUFS, *num_planes == 0, the
* driver has to use the currently configured format to
- * determine the plane sizes and *num_buffers is the total
+ * determine the plane sizes and \*num_buffers is the total
* number of buffers that are being allocated. When called
- * from VIDIOC_CREATE_BUFS, *num_planes != 0 and it
+ * 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
struct vb2_ops {
int (*queue_setup)(struct vb2_queue *q,
unsigned int *num_buffers, unsigned int *num_planes,
- unsigned int sizes[], void *alloc_ctxs[]);
+ unsigned int sizes[], struct device *alloc_devs[]);
void (*wait_prepare)(struct vb2_queue *q);
void (*wait_finish)(struct vb2_queue *q);
* caller. For example, for V4L2, it should match
* the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h
* @io_modes: supported io methods (see vb2_io_modes enum)
+ * @dev: device to use for the default allocation context if the driver
+ * doesn't fill in the @alloc_devs array.
+ * @dma_attrs: DMA attributes to use for the DMA. May be NULL.
* @fileio_read_once: report EOF after reading the first buffer
* @fileio_write_immediately: queue buffer after each write() call
* @allow_zero_bytesused: allow bytesused == 0 to be passed to the driver
* @done_list: list of buffers ready to be dequeued to userspace
* @done_lock: lock to protect done_list list
* @done_wq: waitqueue for processes waiting for buffers ready to be dequeued
- * @alloc_ctx: memory type/allocator-specific contexts for each plane
+ * @alloc_devs: memory type/allocator-specific per-plane device
* @streaming: current streaming state
* @start_streaming_called: start_streaming() was called successfully and we
* started streaming.
struct vb2_queue {
unsigned int type;
unsigned int io_modes;
+ struct device *dev;
+ const struct dma_attrs *dma_attrs;
unsigned fileio_read_once:1;
unsigned fileio_write_immediately:1;
unsigned allow_zero_bytesused:1;
spinlock_t done_lock;
wait_queue_head_t done_wq;
- void *alloc_ctx[VB2_MAX_PLANES];
+ struct device *alloc_devs[VB2_MAX_PLANES];
unsigned int streaming:1;
unsigned int start_streaming_called:1;