diff options
Diffstat (limited to 'Documentation/userspace-api')
16 files changed, 509 insertions, 72 deletions
diff --git a/Documentation/userspace-api/ELF.rst b/Documentation/userspace-api/ELF.rst new file mode 100644 index 000000000000..ac8aeacd458d --- /dev/null +++ b/Documentation/userspace-api/ELF.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +Linux-specific ELF idiosyncrasies +================================= + +Definitions +=========== + +"First" program header is the one with the smallest offset in the file: +e_phoff. + +"Last" program header is the one with the biggest offset in the file: +e_phoff + (e_phnum - 1) * sizeof(Elf_Phdr). + +PT_INTERP +========= + +First PT_INTERP program header is used to locate the filename of ELF +interpreter. Other PT_INTERP headers are ignored (since Linux 2.4.11). + +PT_GNU_STACK +============ + +Last PT_GNU_STACK program header defines userspace stack executability +(since Linux 2.6.6). Other PT_GNU_STACK headers are ignored. + +PT_GNU_PROPERTY +=============== + +ELF interpreter's last PT_GNU_PROPERTY program header is used (since +Linux 5.8). If interpreter doesn't have one, then the last PT_GNU_PROPERTY +program header of an executable is used. Other PT_GNU_PROPERTY headers +are ignored. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index f16337bdb852..72a65db0c498 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -23,6 +23,7 @@ place where this information is gathered. spec_ctrl accelerators/ocxl ebpf/index + ELF ioctl/index iommu iommufd diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index 4f4b23b95b9b..d52977120b41 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -67,6 +67,7 @@ ioctls must be supported by all video overlay devices. Setup ===== +*Note: support for this has been removed.* Before overlay can commence applications must program the driver with frame buffer parameters, namely the address and size of the frame buffer and the image format, for example RGB 5:6:5. The @@ -92,11 +93,13 @@ A driver may support any (or none) of five clipping/blending methods: 1. Chroma-keying displays the overlaid image only where pixels in the primary graphics surface assume a certain color. -2. A bitmap can be specified where each bit corresponds to a pixel in +2. *Note: support for this has been removed.* + A bitmap can be specified where each bit corresponds to a pixel in the overlaid image. When the bit is set, the corresponding video pixel is displayed, otherwise a pixel of the graphics surface. -3. A list of clipping rectangles can be specified. In these regions *no* +3. *Note: support for this has been removed.* + A list of clipping rectangles can be specified. In these regions *no* video is displayed, so the graphics surface can be seen here. 4. The framebuffer has an alpha channel that can be used to clip or @@ -185,6 +188,7 @@ struct v4l2_window be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host. ``struct v4l2_clip * clips`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to an array of clipping @@ -201,6 +205,7 @@ struct v4l2_window are undefined. ``__u32 clipcount`` + *Note: support for this has been removed.* When the application set the ``clips`` field, this field must contain the number of clipping rectangles in the list. When clip lists are not supported the driver ignores this field, its contents @@ -208,6 +213,7 @@ struct v4l2_window supported but no clipping is desired this field must be set to zero. ``void * bitmap`` + *Note: support for this has been removed.* When chroma-keying has *not* been negotiated and :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability, applications can set this field to point to a clipping bit mask. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 506dd3c98884..06b78e5589d2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -88,6 +88,11 @@ Compressed Formats - ``V4L2_PIX_FMT_H263`` - 'H263' - H263 video elementary stream. + * .. _V4L2-PIX-FMT-SPK: + + - ``V4L2_PIX_FMT_SPK`` + - 'SPK0' + - Sorenson Spark is an implementation of H.263 for use in Flash Video and Adobe Flash files * .. _V4L2-PIX-FMT-MPEG1: - ``V4L2_PIX_FMT_MPEG1`` @@ -232,6 +237,26 @@ Compressed Formats Metadata associated with the frame to decode is required to be passed through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. + * .. _V4L2-PIX-FMT-RV30: + + - ``V4L2_PIX_FMT_RV30`` + - 'RV30' + - RealVideo, or also spelled as Real Video, is a suite of + proprietary video compression formats developed by + RealNetworks - the specific format changes with the version. + RealVideo codecs are identified by four-character codes. + RV30 corresponds to RealVideo 8, suspected to be based + largely on an early draft of H.264 + * .. _V4L2-PIX-FMT-RV40: + + - ``V4L2_PIX_FMT_RV40`` + - 'RV40' + - RV40 represents RealVideo 9 and RealVideo 10. + RealVideo 9, suspected to be based on H.264. + RealVideo 10, aka RV9 EHQ, This refers to an improved encoder + for the RV9 format that is fully backwards compatible with + RV9 players - the format and decoder did not change, only + the encoder did. As a result, it uses the same FourCC. .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index 24a771542059..9f111ed594d2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -257,6 +257,34 @@ the second byte and Y'\ :sub:`7-0` in the third byte. - The padding bits contain undefined values that must be ignored by all applications and drivers. +The next table lists the packed YUV 4:4:4 formats with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order, storing 1 pixel in 6 bytes. + +.. flat-table:: Packed YUV 4:4:4 Image Formats (12bpc) + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + - Byte 9-8 + - Byte 11-10 + + * .. _V4L2-PIX-FMT-YUV48-12: + + - ``V4L2_PIX_FMT_YUV48_12`` + - 'Y312' + + - Y'\ :sub:`0` + - Cb\ :sub:`0` + - Cr\ :sub:`0` + - Y'\ :sub:`1` + - Cb\ :sub:`1` + - Cr\ :sub:`1` 4:2:2 Subsampling ================= diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index d330aeb4d3eb..b71b80d634d6 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -778,7 +778,7 @@ number of bits for each component. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{3.2cm}|p{0.8cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. flat-table:: RGB Formats 10 Bits Per Color Component @@ -868,7 +868,6 @@ number of bits for each component. - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - * .. _V4L2-PIX-FMT-RGBA1010102: - ``V4L2_PIX_FMT_RGBA1010102`` @@ -909,7 +908,6 @@ number of bits for each component. - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - * .. _V4L2-PIX-FMT-ARGB2101010: - ``V4L2_PIX_FMT_ARGB2101010`` @@ -950,12 +948,53 @@ number of bits for each component. - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - - .. raw:: latex \endgroup +12 Bits Per Component +============================== + +These formats store an RGB triplet in six or eight bytes, with 12 bits per component. +Expand the bits per component to 16 bits, data in the high bits, zeros in the low bits, +arranged in little endian order. + +.. raw:: latex + + \small + +.. flat-table:: RGB Formats With 12 Bits Per Component + :header-rows: 1 + + * - Identifier + - Code + - Byte 1-0 + - Byte 3-2 + - Byte 5-4 + - Byte 7-6 + * .. _V4L2-PIX-FMT-BGR48-12: + + - ``V4L2_PIX_FMT_BGR48_12`` + - 'B312' + + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - + * .. _V4L2-PIX-FMT-ABGR64-12: + + - ``V4L2_PIX_FMT_ABGR64_12`` + - 'B412' + + - B\ :sub:`15-4` + - G\ :sub:`15-4` + - R\ :sub:`15-4` + - A\ :sub:`15-4` + +.. raw:: latex + + \normalsize Deprecated RGB Formats ====================== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 62078a01de76..cf8e4dfbfbd4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -103,6 +103,17 @@ are often referred to as greyscale formats. - ... - ... + * .. _V4L2-PIX-FMT-Y012: + + - ``V4L2_PIX_FMT_Y012`` + - 'Y012' + + - Y'\ :sub:`0`\ [3:0] `0000` + - Y'\ :sub:`0`\ [11:4] + - ... + - ... + - ... + * .. _V4L2-PIX-FMT-Y14: - ``V4L2_PIX_FMT_Y14`` @@ -146,3 +157,7 @@ are often referred to as greyscale formats. than 16 bits. For example, 10 bits per pixel uses values in the range 0 to 1023. For the IPU3_Y10 format 25 pixels are packed into 32 bytes, which leaves the 6 most significant bits of the last byte padded with 0. + + For Y012 and Y12 formats, Y012 places its data in the 12 high bits, with + padding zeros in the 4 low bits, in contrast to the Y12 format, which has + its padding located in the most significant bits of the 16 bit word. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index f1d5bb7b806d..72324274f20c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -123,6 +123,20 @@ All components are stored with the same number of bits per component. - Cb, Cr - Yes - 4x4 tiles + * - V4L2_PIX_FMT_P012 + - 'P012' + - 12 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P012M + - 'PM12' + - 12 + - 4:2:0 + - Cb, Cr + - No + - Linear * - V4L2_PIX_FMT_NV16 - 'NV16' - 8 @@ -586,6 +600,86 @@ Data in the 10 high bits, zeros in the 6 low bits, arranged in little endian ord - Cb\ :sub:`11` - Cr\ :sub:`11` +.. _V4L2-PIX-FMT-P012: +.. _V4L2-PIX-FMT-P012M: + +P012 and P012M +-------------- + +P012 is like NV12 with 12 bits per component, expanded to 16 bits. +Data in the 12 high bits, zeros in the 4 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P012 Image + :header-rows: 0 + :stub-columns: 0 + + * - start + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - start + 32: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start + 40: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + +.. flat-table:: Sample 4x4 P012M Image + :header-rows: 0 + :stub-columns: 0 + + * - start0 + 0: + - Y'\ :sub:`00` + - Y'\ :sub:`01` + - Y'\ :sub:`02` + - Y'\ :sub:`03` + * - start0 + 8: + - Y'\ :sub:`10` + - Y'\ :sub:`11` + - Y'\ :sub:`12` + - Y'\ :sub:`13` + * - start0 + 16: + - Y'\ :sub:`20` + - Y'\ :sub:`21` + - Y'\ :sub:`22` + - Y'\ :sub:`23` + * - start0 + 24: + - Y'\ :sub:`30` + - Y'\ :sub:`31` + - Y'\ :sub:`32` + - Y'\ :sub:`33` + * - + * - start1 + 0: + - Cb\ :sub:`00` + - Cr\ :sub:`00` + - Cb\ :sub:`01` + - Cr\ :sub:`01` + * - start1 + 8: + - Cb\ :sub:`10` + - Cr\ :sub:`10` + - Cb\ :sub:`11` + - Cr\ :sub:`11` + Fully Planar YUV Formats ======================== diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst index 228c1521f190..15ff0bf7bbe6 100644 --- a/Documentation/userspace-api/media/v4l/user-func.rst +++ b/Documentation/userspace-api/media/v4l/user-func.rst @@ -72,6 +72,7 @@ Function Reference vidioc-subdev-g-frame-interval vidioc-subdev-g-routing vidioc-subdev-g-selection + vidioc-subdev-g-client-cap vidioc-subdev-querycap vidioc-subscribe-event func-mmap diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index 892cfeb8b988..5292d5e1a91f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -185,6 +185,16 @@ still cause this situation. - ``p_u32`` - A pointer to a matrix control of unsigned 32-bit values. Valid if this control is of type ``V4L2_CTRL_TYPE_U32``. + * - __u32 * + - ``p_s32`` + - A pointer to a matrix control of signed 32-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. + * - __u32 * + - ``p_s64`` + - A pointer to a matrix control of signed 64-bit values. Valid if + this control is of type ``V4L2_CTRL_TYPE_INTEGER64`` and + ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set. * - struct :c:type:`v4l2_area` * - ``p_area`` - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index b6cc1a823207..b651e53643dd 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -49,6 +49,9 @@ of a graphics card. A non-destructive overlay blends video images into a VGA signal or graphics into a video signal. *Video Output Overlays* are always non-destructive. +Destructive overlay support has been removed: with modern GPUs and CPUs +this is no longer needed, and it was always a very dangerous feature. + To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl with a pointer to a struct :c:type:`v4l2_framebuffer` structure. The driver fills all fields of the structure or returns an @@ -63,18 +66,12 @@ this structure, the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -To set the parameters for a *non-destructive Video Overlay*, +To set the parameters for a *Video Capture Overlay* applications must initialize the ``flags`` field, the ``fmt`` substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error code. -For a *destructive Video Overlay* applications must additionally provide -a ``base`` address. Setting up a DMA to a random memory location can -jeopardize the system security, its stability or even damage the -hardware, therefore only the superuser can set the parameters for a -destructive video overlay. - .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_framebuffer @@ -100,17 +97,14 @@ destructive video overlay. - ``base`` - - Physical base address of the framebuffer, that is the address of - the pixel in the top left corner of the framebuffer. [#f1]_ - * - - - - - - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must provide a base - address. The driver may accept only base addresses which are a - multiple of two, four or eight bytes. For *Video Output Overlays* - the driver must return a valid base address, so applications can + the pixel in the top left corner of the framebuffer. + For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported + and the kernel will always set this to NULL. + For *Video Output Overlays* + the driver will return a valid base address, so applications can find the corresponding Linux framebuffer device (see - :ref:`osd`). + :ref:`osd`). For *Video Capture Overlays* this field will always be + NULL. * - struct - ``fmt`` - @@ -136,8 +130,7 @@ destructive video overlay. * - - - - - For *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - For *Video Output Overlays* the driver must return a valid format. * - - @@ -165,13 +158,6 @@ destructive video overlay. This field is irrelevant to *non-destructive Video Overlays*. - For *destructive Video Overlays* both applications and drivers can - set this field to request padding bytes at the end of each line. - Drivers however may ignore the requested value, returning - ``width`` times bytes-per-pixel or a larger value required by the - hardware. That implies applications can just set this field to - zero to get a reasonable default. - For *Video Output Overlays* the driver must return a valid value. Video hardware may access padding bytes, therefore they must @@ -190,9 +176,8 @@ destructive video overlay. * - - __u32 - ``sizeimage`` - - This field is irrelevant to *non-destructive Video Overlays*. For - *destructive Video Overlays* applications must initialize this - field. For *Video Output Overlays* the driver must return a valid + - This field is irrelevant to *non-destructive Video Overlays*. + For *Video Output Overlays* the driver must return a valid format. Together with ``base`` it defines the framebuffer memory @@ -232,9 +217,11 @@ destructive video overlay. * - ``V4L2_FBUF_CAP_LIST_CLIPPING`` - 0x0004 - The device supports clipping using a list of clip rectangles. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` - 0x0008 - The device supports clipping using a bit mask. + Note that this is no longer supported. * - ``V4L2_FBUF_CAP_LOCAL_ALPHA`` - 0x0010 - The device supports clipping/blending using the alpha channel of @@ -342,10 +329,3 @@ EPERM EINVAL The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable. - -.. [#f1] - A physical base address may not suit all platforms. GK notes in - theory we should pass something like PCI device + memory region + - offset instead. If you encounter problems please discuss on the - linux-media mailing list: - `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index 3ef361c0dca7..e3ae84df5486 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -31,18 +31,30 @@ Arguments Description =========== -This ioctl allows applications to enumerate all frame sizes supported by -a sub-device on the given pad for the given media bus format. Supported -formats can be retrieved with the +This ioctl allows applications to access the enumeration of frame sizes +supported by a sub-device on the specified pad +for the specified media bus format. +Supported formats can be retrieved with the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl. -To enumerate frame sizes applications initialize the ``pad``, ``which`` -, ``code`` and ``index`` fields of the struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the -structure. Drivers fill the minimum and maximum frame sizes or return an -EINVAL error code if one of the input parameters is invalid. +The enumerations are defined by the driver, and indexed using the ``index`` field +of the struct :c:type:`v4l2_subdev_frame_size_enum`. +Each pair of ``pad`` and ``code`` correspond to a separate enumeration. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of the enumeration. + +Therefore, to enumerate frame sizes allowed on the specified pad +and using the specified mbus format, initialize the +``pad``, ``which``, and ``code`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the +structure. + +A successful call will return with minimum and maximum frame sizes filled in. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either no more entries are available in the enumeration, +or that an input parameter was invalid. Sub-devices that only support discrete frame sizes (such as most sensors) will return one or more frame sizes with identical minimum and @@ -72,26 +84,28 @@ information about try formats. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the frame size in the enumeration belonging to the given pad + and format. Filled in by the application. * - __u32 - ``pad`` - Pad number as reported by the media controller API. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the application. * - __u32 - ``min_width`` - - Minimum frame width, in pixels. + - Minimum frame width, in pixels. Filled in by the driver. * - __u32 - ``max_width`` - - Maximum frame width, in pixels. + - Maximum frame width, in pixels. Filled in by the driver. * - __u32 - ``min_height`` - - Minimum frame height, in pixels. + - Minimum frame height, in pixels. Filled in by the driver. * - __u32 - ``max_height`` - - Maximum frame height, in pixels. + - Maximum frame height, in pixels. Filled in by the driver. * - __u32 - ``which`` - Frame sizes to be enumerated, from enum diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 248f6f9ee7c5..4ad7dec27e25 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -31,15 +31,28 @@ Arguments Description =========== -To enumerate media bus formats available at a given sub-device pad -applications initialize the ``pad``, ``which`` and ``index`` fields of -struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an ``EINVAL`` -error code if either the ``pad`` or ``index`` are invalid. All media bus -formats are enumerable by beginning at index zero and incrementing by -one until ``EINVAL`` is returned. +This call is used by the application to access the enumeration +of media bus formats for the selected pad. + +The enumerations are defined by the driver, and indexed using the ``index`` field +of struct :c:type:`v4l2_subdev_mbus_code_enum`. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of enumeration. + +Therefore, to enumerate media bus formats available at a given sub-device pad, +initialize the ``pad``, and ``which`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl +with a pointer to this structure. + +A successful call will return with the ``code`` field filled in +with a mbus code value. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either ``pad`` is invalid, +or that there are no more codes available at this pad. + +The driver must not return the same value of ``code`` for different indices +at the same pad. Available media bus formats may depend on the current 'try' formats at other pads of the sub-device, as well as on the current active links. @@ -57,14 +70,16 @@ information about the try formats. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the + application. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the mbus code in the enumeration belonging to the given pad. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the driver. * - __u32 - ``which`` - Media bus format codes to be enumerated, from enum diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst new file mode 100644 index 000000000000..20f12a1cc0f7 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_CLIENT_CAP: + +************************************************************ +ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP +************************************************************ + +Name +==== + +VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client +capabilities. + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP + +``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_client_capability`. + +Description +=========== + +These ioctls are used to get and set the client (the application using the +subdevice ioctls) capabilities. The client capabilities are stored in the file +handle of the opened subdev device node, and the client must set the +capabilities for each opened subdev separately. + +By default no client capabilities are set when a subdev device node is opened. + +The purpose of the client capabilities are to inform the kernel of the behavior +of the client, mainly related to maintaining compatibility with different +kernel and userspace versions. + +The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities +associated with the file handle ``fd``. + +The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file +handle ``fd``. The new capabilities fully replace the current capabilities, the +ioctl can therefore also be used to remove capabilities that have previously +been set. + +``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct +:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have +been accepted. A common case for the kernel not accepting a capability is that +the kernel is older than the headers the userspace uses, and thus the capability +is unknown to the kernel. + +.. flat-table:: Client Capabilities + :header-rows: 1 + + * - Capability + - Description + * - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS`` + - The client is aware of streams. Setting this flag enables the use + of 'stream' fields (referring to the stream number) with various + ioctls. If this is not set (which is the default), the 'stream' fields + will be forced to 0 by the kernel. + +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. + +ENOIOCTLCMD + The kernel does not support this ioctl. diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index 3bf0bcdf21d8..802875a37a27 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -162,9 +162,91 @@ Other quirks (todo) Structures ---------- -Legacy families can define C structures both to be used as the contents -of an attribute and as a fixed message header. The plan is to define -the structs in ``definitions`` and link the appropriate attrs. +Legacy families can define C structures both to be used as the contents of +an attribute and as a fixed message header. Structures are defined in +``definitions`` and referenced in operations or attributes. Note that +structures defined in YAML are implicitly packed according to C +conventions. For example, the following struct is 4 bytes, not 6 bytes: + +.. code-block:: c + + struct { + u8 a; + u16 b; + u8 c; + } + +Any padding must be explicitly added and C-like languages should infer the +need for explicit padding from whether the members are naturally aligned. + +Here is the struct definition from above, declared in YAML: + +.. code-block:: yaml + + definitions: + - + name: message-header + type: struct + members: + - + name: a + type: u8 + - + name: b + type: u16 + - + name: c + type: u8 + +Fixed Headers +~~~~~~~~~~~~~ + +Fixed message headers can be added to operations using ``fixed-header``. +The default ``fixed-header`` can be set in ``operations`` and it can be set +or overridden for each operation. + +.. code-block:: yaml + + operations: + fixed-header: message-header + list: + - + name: get + fixed-header: custom-header + attribute-set: message-attrs + +Attributes +~~~~~~~~~~ + +A ``binary`` attribute can be interpreted as a C structure using a +``struct`` property with the name of the structure definition. The +``struct`` property implies ``sub-type: struct`` so it is not necessary to +specify a sub-type. + +.. code-block:: yaml + + attribute-sets: + - + name: stats-attrs + attributes: + - + name: stats + type: binary + struct: vport-stats + +C Arrays +-------- + +Legacy families also use ``binary`` attributes to encapsulate C arrays. The +``sub-type`` is used to identify the type of scalar to extract. + +.. code-block:: yaml + + attributes: + - + name: ports + type: binary + sub-type: u32 Multi-message DO ---------------- diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index a22442ba1d30..2e4acde890b7 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -254,6 +254,16 @@ rather than depend on what is specified in the spec file. The validation policy in the kernel is formed by combining the type definition (``type`` and ``nested-attributes``) and the ``checks``. +sub-type +~~~~~~~~ + +Legacy families have special ways of expressing arrays. ``sub-type`` can be +used to define the type of array members in case array members are not +fully defined as attributes (in a bona fide attribute space). For instance +a C array of u32 values can be specified with ``type: binary`` and +``sub-type: u32``. Binary types and legacy array formats are described in +more detail in :doc:`genetlink-legacy`. + operations ---------- |