From 55093284fb6f9009a339e522773417bdd54ec144 Mon Sep 17 00:00:00 2001 From: Guennadi Liakhovetski Date: Wed, 28 Sep 2011 08:10:58 -0300 Subject: [media] V4L: document the new VIDIOC_CREATE_BUFS and VIDIOC_PREPARE_BUF ioctl()s [mchehab@redhat.com: remove emacs format crap at the end of the new files] Signed-off-by: Guennadi Liakhovetski Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 3 + Documentation/DocBook/media/v4l/io.xml | 27 ++++ Documentation/DocBook/media/v4l/v4l2.xml | 2 + .../DocBook/media/v4l/vidioc-create-bufs.xml | 139 +++++++++++++++++++++ .../DocBook/media/v4l/vidioc-prepare-buf.xml | 88 +++++++++++++ 5 files changed, 259 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-create-bufs.xml create mode 100644 Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 91410b6e7e08..b68698f96e7f 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2486,6 +2486,9 @@ ioctls. Flash API. + + &VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls. + diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index c57d1ec6291c..3f47df1aa54a 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -927,6 +927,33 @@ ioctl is called. Applications set or clear this flag before calling the VIDIOC_QBUF ioctl. + + V4L2_BUF_FLAG_PREPARED + 0x0400 + The buffer has been prepared for I/O and can be queued by the +application. Drivers set or clear this flag when the +VIDIOC_QUERYBUF, VIDIOC_PREPARE_BUF, VIDIOC_QBUF or VIDIOC_DQBUF ioctl is called. + + + V4L2_BUF_FLAG_NO_CACHE_INVALIDATE + 0x0400 + Caches do not have to be invalidated for this buffer. +Typically applications shall use this flag if the data captured in the buffer +is not going to be touched by the CPU, instead the buffer will, probably, be +passed on to a DMA-capable hardware unit for further processing or output. + + + + V4L2_BUF_FLAG_NO_CACHE_CLEAN + 0x0800 + Caches do not have to be cleaned for this buffer. +Typically applications shall use this flag for output buffers if the data +in this buffer has not been created by the CPU but by some DMA-capable unit, +in which case caches have not been used. + diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 40132c277647..2ab365c10fb9 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -469,6 +469,7 @@ and discussions on the V4L mailing list. &sub-close; &sub-ioctl; + &sub-create-bufs; &sub-cropcap; &sub-dbg-g-chip-ident; &sub-dbg-g-register; @@ -511,6 +512,7 @@ and discussions on the V4L mailing list. &sub-queryctrl; &sub-query-dv-preset; &sub-querystd; + &sub-prepare-buf; &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml new file mode 100644 index 000000000000..73ae8a6cd004 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -0,0 +1,139 @@ + + + ioctl VIDIOC_CREATE_BUFS + &manvol; + + + + VIDIOC_CREATE_BUFS + Create buffers for Memory Mapped or User Pointer I/O + + + + + + int ioctl + int fd + int request + struct v4l2_create_buffers *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_CREATE_BUFS + + + + argp + + + + + + + + + Description + + This ioctl is used to create buffers for memory +mapped or user pointer +I/O. It can be used as an alternative or in addition to the +VIDIOC_REQBUFS ioctl, when a tighter control over buffers +is required. This ioctl can be called multiple times to create buffers of +different sizes. + + To allocate device buffers applications initialize relevant fields of +the v4l2_create_buffers structure. They set the +type field in the +v4l2_format structure, embedded in this +structure, to the respective stream or buffer type. +count must be set to the number of required buffers. +memory specifies the required I/O method. The +format field shall typically be filled in using +either the VIDIOC_TRY_FMT or +VIDIOC_G_FMT ioctl(). Additionally, applications can adjust +sizeimage fields to fit their specific needs. The +reserved array must be zeroed. + + When the ioctl is called with a pointer to this structure the driver +will attempt to allocate up to the requested number of buffers and store the +actual number allocated and the starting index in the +count and the index fields +respectively. On return count can be smaller than +the number requested. The driver may also increase buffer sizes if required, +however, it will not update sizeimage field values. +The user has to use VIDIOC_QUERYBUF to retrieve that +information. + + + struct <structname>v4l2_create_buffers</structname> + + &cs-str; + + + __u32 + index + The starting buffer index, returned by the driver. + + + __u32 + count + The number of buffers requested or granted. + + + &v4l2-memory; + memory + Applications set this field to +V4L2_MEMORY_MMAP or +V4L2_MEMORY_USERPTR. + + + &v4l2-format; + format + Filled in by the application, preserved by the driver. + + + __u32 + reserved[8] + A place holder for future extensions. + + + +
+ + + + &return-value; + + + + ENOMEM + + No memory to allocate buffers for memory +mapped I/O. + + + + EINVAL + + The buffer type (type field) or the +requested I/O method (memory) is not +supported. + + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml new file mode 100644 index 000000000000..7bde698760e4 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -0,0 +1,88 @@ + + + ioctl VIDIOC_PREPARE_BUF + &manvol; + + + + VIDIOC_PREPARE_BUF + Prepare a buffer for I/O + + + + + + int ioctl + int fd + int request + struct v4l2_buffer *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_PREPARE_BUF + + + + argp + + + + + + + + + Description + + Applications can optionally call the +VIDIOC_PREPARE_BUF ioctl to pass ownership of the buffer +to the driver before actually enqueuing it, using the +VIDIOC_QBUF ioctl, and to prepare it for future I/O. +Such preparations may include cache invalidation or cleaning. Performing them +in advance saves time during the actual I/O. In case such cache operations are +not required, the application can use one of +V4L2_BUF_FLAG_NO_CACHE_INVALIDATE and +V4L2_BUF_FLAG_NO_CACHE_CLEAN flags to skip the respective +step. + + The v4l2_buffer structure is +specified in . + + + + &return-value; + + + + EBUSY + + File I/O is in progress. + + + + EINVAL + + The buffer type is not +supported, or the index is out of bounds, +or no buffers have been allocated yet, or the +userptr or +length are invalid. + + + + + -- cgit v1.2.3-55-g7522 From d26a6635b24210791cf4b71fd861738270c8cc3c Mon Sep 17 00:00:00 2001 From: Sylwester Nawrocki Date: Sun, 4 Sep 2011 19:08:54 -0300 Subject: [media] v4l: Add AUTO option for the V4L2_CID_POWER_LINE_FREQUENCY control V4L2_CID_POWER_LINE_FREQUENCY control allows applications to instruct a driver what is the power line frequency so an appropriate filter can be used by the device to cancel flicker by compensating the light intensity ripple. Currently in the menu we have entries for 50 Hz and 60 Hz and for entirely disabling the anti-flicker filter. However some devices are capable of automatically detecting the frequency, so add V4L2_CID_POWER_LINE_FREQUENCY_AUTO entry for them. Signed-off-by: Sylwester Nawrocki Signed-off-by: Kyungmin Park Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 5 +++-- drivers/media/video/v4l2-ctrls.c | 1 + include/linux/videodev2.h | 1 + 3 files changed, 5 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 23fdf79f8cf3..3bc5ee8b2c74 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -232,8 +232,9 @@ control is deprecated. New drivers and applications should use the Enables a power line frequency filter to avoid flicker. Possible values for enum v4l2_power_line_frequency are: V4L2_CID_POWER_LINE_FREQUENCY_DISABLED (0), -V4L2_CID_POWER_LINE_FREQUENCY_50HZ (1) and -V4L2_CID_POWER_LINE_FREQUENCY_60HZ (2). +V4L2_CID_POWER_LINE_FREQUENCY_50HZ (1), +V4L2_CID_POWER_LINE_FREQUENCY_60HZ (2) and +V4L2_CID_POWER_LINE_FREQUENCY_AUTO (3). V4L2_CID_HUE_AUTO diff --git a/drivers/media/video/v4l2-ctrls.c b/drivers/media/video/v4l2-ctrls.c index fc8666ae408f..5552f8137571 100644 --- a/drivers/media/video/v4l2-ctrls.c +++ b/drivers/media/video/v4l2-ctrls.c @@ -210,6 +210,7 @@ const char * const *v4l2_ctrl_get_menu(u32 id) "Disabled", "50 Hz", "60 Hz", + "Auto", NULL }; static const char * const camera_exposure_auto[] = { diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h index 66945a6f628d..4b752d5ee80e 100644 --- a/include/linux/videodev2.h +++ b/include/linux/videodev2.h @@ -1169,6 +1169,7 @@ enum v4l2_power_line_frequency { V4L2_CID_POWER_LINE_FREQUENCY_DISABLED = 0, V4L2_CID_POWER_LINE_FREQUENCY_50HZ = 1, V4L2_CID_POWER_LINE_FREQUENCY_60HZ = 2, + V4L2_CID_POWER_LINE_FREQUENCY_AUTO = 3, }; #define V4L2_CID_HUE_AUTO (V4L2_CID_BASE+25) #define V4L2_CID_WHITE_BALANCE_TEMPERATURE (V4L2_CID_BASE+26) -- cgit v1.2.3-55-g7522