diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-querycap.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-querycap.rst | 284 |
1 files changed, 0 insertions, 284 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst deleted file mode 100644 index 5f9930195d62..000000000000 --- a/Documentation/media/uapi/v4l/vidioc-querycap.rst +++ /dev/null @@ -1,284 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDIOC_QUERYCAP: - -********************* -ioctl VIDIOC_QUERYCAP -********************* - -Name -==== - -VIDIOC_QUERYCAP - Query device capabilities - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp ) - :name: VIDIOC_QUERYCAP - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() <func-open>`. - -``argp`` - Pointer to struct :c:type:`v4l2_capability`. - - -Description -=========== - -All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to -identify kernel devices compatible with this specification and to obtain -information about driver and hardware capabilities. The ioctl takes a -pointer to a struct :c:type:`v4l2_capability` which is -filled by the driver. When the driver is not compatible with this -specification the ioctl returns an ``EINVAL`` error code. - - -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| - -.. c:type:: v4l2_capability - -.. flat-table:: struct v4l2_capability - :header-rows: 0 - :stub-columns: 0 - :widths: 3 4 20 - - * - __u8 - - ``driver``\ [16] - - Name of the driver, a unique NUL-terminated ASCII string. For - example: "bttv". Driver specific applications can use this - information to verify the driver identity. It is also useful to - work around known bugs, or to identify drivers in error reports. - - Storing strings in fixed sized arrays is bad practice but - unavoidable here. Drivers and applications should take precautions - to never read or write beyond the end of the array and to make - sure the strings are properly NUL-terminated. - * - __u8 - - ``card``\ [32] - - Name of the device, a NUL-terminated UTF-8 string. For example: - "Yoyodyne TV/FM". One driver may support different brands or - models of video hardware. This information is intended for users, - for example in a menu of available devices. Since multiple TV - cards of the same brand may be installed which are supported by - the same driver, this name should be combined with the character - device file name (e. g. ``/dev/video2``) or the ``bus_info`` - string to avoid ambiguities. - * - __u8 - - ``bus_info``\ [32] - - Location of the device in the system, a NUL-terminated ASCII - string. For example: "PCI:0000:05:06.0". This information is - intended for users, to distinguish multiple identical devices. If - no such information is available the field must simply count the - devices controlled by the driver ("platform:vivi-000"). The - bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI - Express boards, "usb-" for USB devices, "I2C:" for i2c devices, - "ISA:" for ISA devices, "parport" for parallel port devices and - "platform:" for platform devices. - * - __u32 - - ``version`` - - Version number of the driver. - - Starting with kernel 3.1, the version reported is provided by the - V4L2 subsystem following the kernel numbering scheme. However, it - may not always return the same version as the kernel if, for - example, a stable or distribution-modified kernel uses the V4L2 - stack from a newer kernel. - - The version number is formatted using the ``KERNEL_VERSION()`` - macro. For example if the media stack corresponds to the V4L2 - version shipped with Kernel 4.14, it would be equivalent to: - * - :cspan:`2` - - ``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))`` - - ``__u32 version = KERNEL_VERSION(4, 14, 0);`` - - ``printf ("Version: %u.%u.%u\\n",`` - - ``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);`` - * - __u32 - - ``capabilities`` - - Available capabilities of the physical device as a whole, see - :ref:`device-capabilities`. The same physical device can export - multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and - /dev/radioZ). The ``capabilities`` field should contain a union of - all capabilities available around the several V4L2 devices - exported to userspace. For all those devices the ``capabilities`` - field returns the same set of capabilities. This allows - applications to open just one of the devices (typically the video - device) and discover whether video, vbi and/or radio are also - supported. - * - __u32 - - ``device_caps`` - - Device capabilities of the opened device, see - :ref:`device-capabilities`. Should contain the available - capabilities of that specific device node. So, for example, - ``device_caps`` of a radio device will only contain radio related - capabilities and no video or vbi capabilities. This field is only - set if the ``capabilities`` field contains the - ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities`` - field can have the ``V4L2_CAP_DEVICE_CAPS`` capability, - ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``. - * - __u32 - - ``reserved``\ [3] - - Reserved for future extensions. Drivers must set this array to - zero. - - - -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| - -.. _device-capabilities: - -.. cssclass:: longtable - -.. flat-table:: Device Capabilities Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_CAP_VIDEO_CAPTURE`` - - 0x00000001 - - The device supports the single-planar API through the - :ref:`Video Capture <capture>` interface. - * - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` - - 0x00001000 - - The device supports the :ref:`multi-planar API <planar-apis>` - through the :ref:`Video Capture <capture>` interface. - * - ``V4L2_CAP_VIDEO_OUTPUT`` - - 0x00000002 - - The device supports the single-planar API through the - :ref:`Video Output <output>` interface. - * - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` - - 0x00002000 - - The device supports the :ref:`multi-planar API <planar-apis>` - through the :ref:`Video Output <output>` interface. - * - ``V4L2_CAP_VIDEO_M2M`` - - 0x00004000 - - The device supports the single-planar API through the Video - Memory-To-Memory interface. - * - ``V4L2_CAP_VIDEO_M2M_MPLANE`` - - 0x00008000 - - The device supports the :ref:`multi-planar API <planar-apis>` - through the Video Memory-To-Memory interface. - * - ``V4L2_CAP_VIDEO_OVERLAY`` - - 0x00000004 - - The device supports the :ref:`Video Overlay <overlay>` - interface. A video overlay device typically stores captured images - directly in the video memory of a graphics card, with hardware - clipping and scaling. - * - ``V4L2_CAP_VBI_CAPTURE`` - - 0x00000010 - - The device supports the :ref:`Raw VBI Capture <raw-vbi>` - interface, providing Teletext and Closed Caption data. - * - ``V4L2_CAP_VBI_OUTPUT`` - - 0x00000020 - - The device supports the :ref:`Raw VBI Output <raw-vbi>` - interface. - * - ``V4L2_CAP_SLICED_VBI_CAPTURE`` - - 0x00000040 - - The device supports the :ref:`Sliced VBI Capture <sliced>` - interface. - * - ``V4L2_CAP_SLICED_VBI_OUTPUT`` - - 0x00000080 - - The device supports the :ref:`Sliced VBI Output <sliced>` - interface. - * - ``V4L2_CAP_RDS_CAPTURE`` - - 0x00000100 - - The device supports the :ref:`RDS <rds>` capture interface. - * - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` - - 0x00000200 - - The device supports the :ref:`Video Output Overlay <osd>` (OSD) - interface. Unlike the *Video Overlay* interface, this is a - secondary function of video output devices and overlays an image - onto an outgoing video signal. When the driver sets this flag, it - must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice - versa. [#f1]_ - * - ``V4L2_CAP_HW_FREQ_SEEK`` - - 0x00000400 - - The device supports the - :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl - for hardware frequency seeking. - * - ``V4L2_CAP_RDS_OUTPUT`` - - 0x00000800 - - The device supports the :ref:`RDS <rds>` output interface. - * - ``V4L2_CAP_TUNER`` - - 0x00010000 - - The device has some sort of tuner to receive RF-modulated video - signals. For more information about tuner programming see - :ref:`tuner`. - * - ``V4L2_CAP_AUDIO`` - - 0x00020000 - - The device has audio inputs or outputs. It may or may not support - audio recording or playback, in PCM or compressed formats. PCM - audio support must be implemented as ALSA or OSS interface. For - more information on audio inputs and outputs see :ref:`audio`. - * - ``V4L2_CAP_RADIO`` - - 0x00040000 - - This is a radio receiver. - * - ``V4L2_CAP_MODULATOR`` - - 0x00080000 - - The device has some sort of modulator to emit RF-modulated - video/audio signals. For more information about modulator - programming see :ref:`tuner`. - * - ``V4L2_CAP_SDR_CAPTURE`` - - 0x00100000 - - The device supports the :ref:`SDR Capture <sdr>` interface. - * - ``V4L2_CAP_EXT_PIX_FORMAT`` - - 0x00200000 - - The device supports the struct - :c:type:`v4l2_pix_format` extended fields. - * - ``V4L2_CAP_SDR_OUTPUT`` - - 0x00400000 - - The device supports the :ref:`SDR Output <sdr>` interface. - * - ``V4L2_CAP_META_CAPTURE`` - - 0x00800000 - - The device supports the :ref:`metadata` capture interface. - * - ``V4L2_CAP_READWRITE`` - - 0x01000000 - - The device supports the :ref:`read() <rw>` and/or - :ref:`write() <rw>` I/O methods. - * - ``V4L2_CAP_ASYNCIO`` - - 0x02000000 - - The device supports the :ref:`asynchronous <async>` I/O methods. - * - ``V4L2_CAP_STREAMING`` - - 0x04000000 - - The device supports the :ref:`streaming <mmap>` I/O method. - * - ``V4L2_CAP_META_OUTPUT`` - - 0x08000000 - - The device supports the :ref:`metadata` output interface. - * - ``V4L2_CAP_TOUCH`` - - 0x10000000 - - This is a touch device. - * - ``V4L2_CAP_DEVICE_CAPS`` - - 0x80000000 - - The driver fills the ``device_caps`` field. This capability can - only appear in the ``capabilities`` field and never in the - ``device_caps`` field. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes <gen-errors>` chapter. - -.. [#f1] - The struct :c:type:`v4l2_framebuffer` lacks an - enum :c:type:`v4l2_buf_type` field, therefore the - type of overlay is implied by the driver capabilities. |