diff options
Diffstat (limited to 'Documentation/userspace-api')
132 files changed, 15136 insertions, 1177 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/dcdbas.rst b/Documentation/userspace-api/dcdbas.rst new file mode 100644 index 000000000000..309cc57a7c1c --- /dev/null +++ b/Documentation/userspace-api/dcdbas.rst @@ -0,0 +1,99 @@ +=================================== +Dell Systems Management Base Driver +=================================== + +Overview +======== + +The Dell Systems Management Base Driver provides a sysfs interface for +systems management software such as Dell OpenManage to perform system +management interrupts and host control actions (system power cycle or +power off after OS shutdown) on certain Dell systems. + +Dell OpenManage requires this driver on the following Dell PowerEdge systems: +300, 1300, 1400, 400SC, 500SC, 1500SC, 1550, 600SC, 1600SC, 650, 1655MC, +700, and 750. Other Dell software such as the open source libsmbios project +is expected to make use of this driver, and it may include the use of this +driver on other Dell systems. + +The Dell libsmbios project aims towards providing access to as much BIOS +information as possible. See http://linux.dell.com/libsmbios/main/ for +more information about the libsmbios project. + + +System Management Interrupt +=========================== + +On some Dell systems, systems management software must access certain +management information via a system management interrupt (SMI). The SMI data +buffer must reside in 32-bit address space, and the physical address of the +buffer is required for the SMI. The driver maintains the memory required for +the SMI and provides a way for the application to generate the SMI. +The driver creates the following sysfs entries for systems management +software to perform these system management interrupts:: + + /sys/devices/platform/dcdbas/smi_data + /sys/devices/platform/dcdbas/smi_data_buf_phys_addr + /sys/devices/platform/dcdbas/smi_data_buf_size + /sys/devices/platform/dcdbas/smi_request + +Systems management software must perform the following steps to execute +a SMI using this driver: + +1) Lock smi_data. +2) Write system management command to smi_data. +3) Write "1" to smi_request to generate a calling interface SMI or + "2" to generate a raw SMI. +4) Read system management command response from smi_data. +5) Unlock smi_data. + + +Host Control Action +=================== + +Dell OpenManage supports a host control feature that allows the administrator +to perform a power cycle or power off of the system after the OS has finished +shutting down. On some Dell systems, this host control feature requires that +a driver perform a SMI after the OS has finished shutting down. + +The driver creates the following sysfs entries for systems management software +to schedule the driver to perform a power cycle or power off host control +action after the system has finished shutting down: + +/sys/devices/platform/dcdbas/host_control_action +/sys/devices/platform/dcdbas/host_control_smi_type +/sys/devices/platform/dcdbas/host_control_on_shutdown + +Dell OpenManage performs the following steps to execute a power cycle or +power off host control action using this driver: + +1) Write host control action to be performed to host_control_action. +2) Write type of SMI that driver needs to perform to host_control_smi_type. +3) Write "1" to host_control_on_shutdown to enable host control action. +4) Initiate OS shutdown. + (Driver will perform host control SMI when it is notified that the OS + has finished shutting down.) + + +Host Control SMI Type +===================== + +The following table shows the value to write to host_control_smi_type to +perform a power cycle or power off host control action: + +=================== ===================== +PowerEdge System Host Control SMI Type +=================== ===================== + 300 HC_SMITYPE_TYPE1 + 1300 HC_SMITYPE_TYPE1 + 1400 HC_SMITYPE_TYPE2 + 500SC HC_SMITYPE_TYPE2 + 1500SC HC_SMITYPE_TYPE2 + 1550 HC_SMITYPE_TYPE2 + 600SC HC_SMITYPE_TYPE2 + 1600SC HC_SMITYPE_TYPE2 + 650 HC_SMITYPE_TYPE2 + 1655MC HC_SMITYPE_TYPE2 + 700 HC_SMITYPE_TYPE3 + 750 HC_SMITYPE_TYPE3 +=================== ===================== diff --git a/Documentation/userspace-api/dma-buf-alloc-exchange.rst b/Documentation/userspace-api/dma-buf-alloc-exchange.rst new file mode 100644 index 000000000000..fdff19fce13e --- /dev/null +++ b/Documentation/userspace-api/dma-buf-alloc-exchange.rst @@ -0,0 +1,389 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright 2021-2023 Collabora Ltd. + +======================== +Exchanging pixel buffers +======================== + +As originally designed, the Linux graphics subsystem had extremely limited +support for sharing pixel-buffer allocations between processes, devices, and +subsystems. Modern systems require extensive integration between all three +classes; this document details how applications and kernel subsystems should +approach this sharing for two-dimensional image data. + +It is written with reference to the DRM subsystem for GPU and display devices, +V4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace +support, however any other subsystems should also follow this design and advice. + + +Glossary of terms +================= + +.. glossary:: + + image: + Conceptually a two-dimensional array of pixels. The pixels may be stored + in one or more memory buffers. Has width and height in pixels, pixel + format and modifier (implicit or explicit). + + row: + A span along a single y-axis value, e.g. from co-ordinates (0,100) to + (200,100). + + scanline: + Synonym for row. + + column: + A span along a single x-axis value, e.g. from co-ordinates (100,0) to + (100,100). + + memory buffer: + A piece of memory for storing (parts of) pixel data. Has stride and size + in bytes and at least one handle in some API. May contain one or more + planes. + + plane: + A two-dimensional array of some or all of an image's color and alpha + channel values. + + pixel: + A picture element. Has a single color value which is defined by one or + more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also + have an alpha value as an additional channel. + + pixel data: + Bytes or bits that represent some or all of the color/alpha channel values + of a pixel or an image. The data for one pixel may be spread over several + planes or memory buffers depending on format and modifier. + + color value: + A tuple of numbers, representing a color. Each element in the tuple is a + color channel value. + + color channel: + One of the dimensions in a color model. For example, RGB model has + channels R, G, and B. Alpha channel is sometimes counted as a color + channel as well. + + pixel format: + A description of how pixel data represents the pixel's color and alpha + values. + + modifier: + A description of how pixel data is laid out in memory buffers. + + alpha: + A value that denotes the color coverage in a pixel. Sometimes used for + translucency instead. + + stride: + A value that denotes the relationship between pixel-location co-ordinates + and byte-offset values. Typically used as the byte offset between two + pixels at the start of vertically-consecutive tiling blocks. For linear + layouts, the byte offset between two vertically-adjacent pixels. For + non-linear formats the stride must be computed in a consistent way, which + usually is done as-if the layout was linear. + + pitch: + Synonym for stride. + + +Formats and modifiers +===================== + +Each buffer must have an underlying format. This format describes the color +values provided for each pixel. Although each subsystem has its own format +descriptions (e.g. V4L2 and fbdev), the ``DRM_FORMAT_*`` tokens should be reused +wherever possible, as they are the standard descriptions used for interchange. +These tokens are described in the ``drm_fourcc.h`` file, which is a part of +DRM's uAPI. + +Each ``DRM_FORMAT_*`` token describes the translation between a pixel +co-ordinate in an image, and the color values for that pixel contained within +its memory buffers. The number and type of color channels are described: +whether they are RGB or YUV, integer or floating-point, the size of each channel +and their locations within the pixel memory, and the relationship between color +planes. + +For example, ``DRM_FORMAT_ARGB8888`` describes a format in which each pixel has +a single 32-bit value in memory. Alpha, red, green, and blue, color channels are +available at 8-bit precision per channel, ordered respectively from most to +least significant bits in little-endian storage. ``DRM_FORMAT_*`` is not +affected by either CPU or device endianness; the byte pattern in memory is +always as described in the format definition, which is usually little-endian. + +As a more complex example, ``DRM_FORMAT_NV12`` describes a format in which luma +and chroma YUV samples are stored in separate planes, where the chroma plane is +stored at half the resolution in both dimensions (i.e. one U/V chroma +sample is stored for each 2x2 pixel grouping). + +Format modifiers describe a translation mechanism between these per-pixel memory +samples, and the actual memory storage for the buffer. The most straightforward +modifier is ``DRM_FORMAT_MOD_LINEAR``, describing a scheme in which each plane +is laid out row-sequentially, from the top-left to the bottom-right corner. +This is considered the baseline interchange format, and most convenient for CPU +access. + +Modern hardware employs much more sophisticated access mechanisms, typically +making use of tiled access and possibly also compression. For example, the +``DRM_FORMAT_MOD_VIVANTE_TILED`` modifier describes memory storage where pixels +are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in +a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane +stores pixels (4,0) to (7,3) inclusive. + +Some modifiers may modify the number of planes required for an image; for +example, the ``I915_FORMAT_MOD_Y_TILED_CCS`` modifier adds a second plane to RGB +formats in which it stores data about the status of every tile, notably +including whether the tile is fully populated with pixel data, or can be +expanded from a single solid color. + +These extended layouts are highly vendor-specific, and even specific to +particular generations or configurations of devices per-vendor. For this reason, +support of modifiers must be explicitly enumerated and negotiated by all users +in order to ensure a compatible and optimal pipeline, as discussed below. + + +Dimensions and size +=================== + +Each pixel buffer must be accompanied by logical pixel dimensions. This refers +to the number of unique samples which can be extracted from, or stored to, the +underlying memory storage. For example, even though a 1920x1080 +``DRM_FORMAT_NV12`` buffer has a luma plane containing 1920x1080 samples for the Y +component, and 960x540 samples for the U and V components, the overall buffer is +still described as having dimensions of 1920x1080. + +The in-memory storage of a buffer is not guaranteed to begin immediately at the +base address of the underlying memory, nor is it guaranteed that the memory +storage is tightly clipped to either dimension. + +Each plane must therefore be described with an ``offset`` in bytes, which will be +added to the base address of the memory storage before performing any per-pixel +calculations. This may be used to combine multiple planes into a single memory +buffer; for example, ``DRM_FORMAT_NV12`` may be stored in a single memory buffer +where the luma plane's storage begins immediately at the start of the buffer +with an offset of 0, and the chroma plane's storage follows within the same buffer +beginning from the byte offset for that plane. + +Each plane must also have a ``stride`` in bytes, expressing the offset in memory +between two contiguous row. For example, a ``DRM_FORMAT_MOD_LINEAR`` buffer +with dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in +order to allow for aligned access patterns. In this case, the buffer will still +be described with a width of 1000, however the stride will be ``1024 * bpp``, +indicating that there are 24 pixels at the positive extreme of the x axis whose +values are not significant. + +Buffers may also be padded further in the y dimension, simply by allocating a +larger area than would ordinarily be required. For example, many media decoders +are not able to natively output buffers of height 1080, but instead require an +effective height of 1088 pixels. In this case, the buffer continues to be +described as having a height of 1080, with the memory allocation for each buffer +being increased to account for the extra padding. + + +Enumeration +=========== + +Every user of pixel buffers must be able to enumerate a set of supported formats +and modifiers, described together. Within KMS, this is achieved with the +``IN_FORMATS`` property on each DRM plane, listing the supported DRM formats, and +the modifiers supported for each format. In userspace, this is supported through +the `EGL_EXT_image_dma_buf_import_modifiers`_ extension entrypoints for EGL, the +`VK_EXT_image_drm_format_modifier`_ extension for Vulkan, and the +`zwp_linux_dmabuf_v1`_ extension for Wayland. + +Each of these interfaces allows users to query a set of supported +format+modifier combinations. + + +Negotiation +=========== + +It is the responsibility of userspace to negotiate an acceptable format+modifier +combination for its usage. This is performed through a simple intersection of +lists. For example, if a user wants to use Vulkan to render an image to be +displayed on a KMS plane, it must: + + - query KMS for the ``IN_FORMATS`` property for the given plane + - query Vulkan for the supported formats for its physical device, making sure + to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` + corresponding to the intended rendering use + - intersect these formats to determine the most appropriate one + - for this format, intersect the lists of supported modifiers for both KMS and + Vulkan, to obtain a final list of acceptable modifiers for that format + +This intersection must be performed for all usages. For example, if the user +also wishes to encode the image to a video stream, it must query the media API +it intends to use for encoding for the set of modifiers it supports, and +additionally intersect against this list. + +If the intersection of all lists is an empty list, it is not possible to share +buffers in this way, and an alternate strategy must be considered (e.g. using +CPU access routines to copy data between the different uses, with the +corresponding performance cost). + +The resulting modifier list is unsorted; the order is not significant. + + +Allocation +========== + +Once userspace has determined an appropriate format, and corresponding list of +acceptable modifiers, it must allocate the buffer. As there is no universal +buffer-allocation interface available at either kernel or userspace level, the +client makes an arbitrary choice of allocation interface such as Vulkan, GBM, or +a media API. + +Each allocation request must take, at a minimum: the pixel format, a list of +acceptable modifiers, and the buffer's width and height. Each API may extend +this set of properties in different ways, such as allowing allocation in more +than two dimensions, intended usage patterns, etc. + +The component which allocates the buffer will make an arbitrary choice of what +it considers the 'best' modifier within the acceptable list for the requested +allocation, any padding required, and further properties of the underlying +memory buffers such as whether they are stored in system or device-specific +memory, whether or not they are physically contiguous, and their cache mode. +These properties of the memory buffer are not visible to userspace, however the +``dma-heaps`` API is an effort to address this. + +After allocation, the client must query the allocator to determine the actual +modifier selected for the buffer, as well as the per-plane offset and stride. +Allocators are not permitted to vary the format in use, to select a modifier not +provided within the acceptable list, nor to vary the pixel dimensions other than +the padding expressed through offset, stride, and size. + +Communicating additional constraints, such as alignment of stride or offset, +placement within a particular memory area, etc, is out of scope of dma-buf, +and is not solved by format and modifier tokens. + + +Import +====== + +To use a buffer within a different context, device, or subsystem, the user +passes these parameters (format, modifier, width, height, and per-plane offset +and stride) to an importing API. + +Each memory buffer is referred to by a buffer handle, which may be unique or +duplicated within an image. For example, a ``DRM_FORMAT_NV12`` buffer may have +the luma and chroma buffers combined into a single memory buffer by use of the +per-plane offset parameters, or they may be completely separate allocations in +memory. For this reason, each import and allocation API must provide a separate +handle for each plane. + +Each kernel subsystem has its own types and interfaces for buffer management. +DRM uses GEM buffer objects (BOs), V4L2 has its own references, etc. These types +are not portable between contexts, processes, devices, or subsystems. + +To address this, ``dma-buf`` handles are used as the universal interchange for +buffers. Subsystem-specific operations are used to export native buffer handles +to a ``dma-buf`` file descriptor, and to import those file descriptors into a +native buffer handle. dma-buf file descriptors can be transferred between +contexts, processes, devices, and subsystems. + +For example, a Wayland media player may use V4L2 to decode a video frame into a +``DRM_FORMAT_NV12`` buffer. This will result in two memory planes (luma and +chroma) being dequeued by the user from V4L2. These planes are then exported to +one dma-buf file descriptor per plane, these descriptors are then sent along +with the metadata (format, modifier, width, height, per-plane offset and stride) +to the Wayland server. The Wayland server will then import these file +descriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use +through Vulkan, or a KMS framebuffer object; each of these import operations +will take the same metadata and convert the dma-buf file descriptors into their +native buffer handles. + +Having a non-empty intersection of supported modifiers does not guarantee that +import will succeed into all consumers; they may have constraints beyond those +implied by modifiers which must be satisfied. + + +Implicit modifiers +================== + +The concept of modifiers post-dates all of the subsystems mentioned above. As +such, it has been retrofitted into all of these APIs, and in order to ensure +backwards compatibility, support is needed for drivers and userspace which do +not (yet) support modifiers. + +As an example, GBM is used to allocate buffers to be shared between EGL for +rendering and KMS for display. It has two entrypoints for allocating buffers: +``gbm_bo_create`` which only takes the format, width, height, and a usage token, +and ``gbm_bo_create_with_modifiers`` which extends this with a list of modifiers. + +In the latter case, the allocation is as discussed above, being provided with a +list of acceptable modifiers that the implementation can choose from (or fail if +it is not possible to allocate within those constraints). In the former case +where modifiers are not provided, the GBM implementation must make its own +choice as to what is likely to be the 'best' layout. Such a choice is entirely +implementation-specific: some will internally use tiled layouts which are not +CPU-accessible if the implementation decides that is a good idea through +whatever heuristic. It is the implementation's responsibility to ensure that +this choice is appropriate. + +To support this case where the layout is not known because there is no awareness +of modifiers, a special ``DRM_FORMAT_MOD_INVALID`` token has been defined. This +pseudo-modifier declares that the layout is not known, and that the driver +should use its own logic to determine what the underlying layout may be. + +.. note:: + + ``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is + ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image + has the linear layout. Care and attention should be taken to ensure that + zero as a default value is not mixed up with either no modifier or the linear + modifier. Also note that in some APIs the invalid modifier value is specified + with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``. + +There are four cases where this token may be used: + - during enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either + as the sole member of a modifier list to declare that explicit modifiers are + not supported, or as part of a larger list to declare that implicit modifiers + may be used + - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the + sole member of a modifier list (equivalent to not supplying a modifier list + at all) to declare that explicit modifiers are not supported and must not be + used, or as part of a larger list to declare that an allocation using implicit + modifiers is acceptable + - in a post-allocation query, an implementation may return + ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare + that the underlying layout is implementation-defined and that an explicit + modifier description is not available; per the above rules, this may only be + returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the + list of acceptable modifiers, or not provided a list + - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the + buffer modifier (or not supply a modifier) to indicate that the modifier is + unknown for whatever reason; this is only acceptable when the buffer has + not been allocated with an explicit modifier + +It follows from this that for any single buffer, the complete chain of operations +formed by the producer and all the consumers must be either fully implicit or fully +explicit. For example, if a user wishes to allocate a buffer for use between +GPU, display, and media, but the media API does not support modifiers, then the +user **must not** allocate the buffer with explicit modifiers and attempt to +import the buffer into the media API with no modifier, but either perform the +allocation using implicit modifiers, or allocate the buffer for media use +separately and copy between the two buffers. + +As one exception to the above, allocations may be 'upgraded' from implicit +to explicit modifiers. For example, if the buffer is allocated with +``gbm_bo_create`` (taking no modifiers), the user may then query the modifier with +``gbm_bo_get_modifier`` and then use this modifier as an explicit modifier token +if a valid modifier is returned. + +When allocating buffers for exchange between different users and modifiers are +not available, implementations are strongly encouraged to use +``DRM_FORMAT_MOD_LINEAR`` for their allocation, as this is the universal baseline +for exchange. However, it is not guaranteed that this will result in the correct +interpretation of buffer content, as implicit modifier operation may still be +subject to driver-specific heuristics. + +Any new users - userspace programs and protocols, kernel subsystems, etc - +wishing to exchange buffers must offer interoperability through dma-buf file +descriptors for memory planes, DRM format tokens to describe the format, DRM +format modifiers to describe the layout in memory, at least width and height for +dimensions, and at least offset and stride for each memory plane. + +.. _zwp_linux_dmabuf_v1: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml +.. _VK_EXT_image_drm_format_modifier: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_drm_format_modifier.html +.. _EGL_EXT_image_dma_buf_import_modifiers: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/userspace-api/gpio/chardev.rst new file mode 100644 index 000000000000..c58dd9771ac9 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +GPIO Character Device Userspace API +=================================== + +This is latest version (v2) of the character device API, as defined in +``include/uapi/linux/gpio.h.`` + +First added in 5.10. + +.. note:: + Do NOT abuse userspace APIs to control hardware that has proper kernel + drivers. There may already be a driver for your use case, and an existing + kernel driver is sure to provide a superior solution to bitbashing + from userspace. + + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing + kernel wheels in userspace. + + Similarly, for multi-function lines there may be other subsystems, such as + Documentation/spi/index.rst, Documentation/i2c/index.rst, + Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that + provide suitable drivers and APIs for your hardware. + +Basic examples using the character device API can be found in ``tools/gpio/*``. + +The API is based around two major objects, the :ref:`gpio-v2-chip` and the +:ref:`gpio-v2-line-request`. + +.. _gpio-v2-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using gpio-v2-get-line-ioctl.rst +and the resulting line request is used to access the GPIO chip's lines or +monitor the lines for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line <gpio-v2-get-line-ioctl> + Get Chip Info <gpio-get-chipinfo-ioctl> + Get Line Info <gpio-v2-get-lineinfo-ioctl> + Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl> + Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl> + Read Line Info Changed Events <gpio-v2-lineinfo-changed-read> + +.. _gpio-v2-line-request: + +Line Request +============ + +Line requests are created by gpio-v2-get-line-ioctl.rst and provide +access to a set of requested lines. The line request is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. + +Within this documentation, the line request file descriptor is referred to +as ``req_fd``. + +Operations +---------- + +The following operations may be performed on the line request: + +.. toctree:: + :titlesonly: + + Get Line Values <gpio-v2-line-get-values-ioctl> + Set Line Values <gpio-v2-line-set-values-ioctl> + Read Line Edge Events <gpio-v2-line-event-read> + Reconfigure Lines <gpio-v2-line-set-config-ioctl> + +Types +===== + +This section contains the structs and enums that are referenced by the API v2, +as defined in ``include/uapi/linux/gpio.h``. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpio_v2_line_attr_id + gpio_v2_line_attribute + gpio_v2_line_changed_type + gpio_v2_line_config + gpio_v2_line_config_attribute + gpio_v2_line_event + gpio_v2_line_event_id + gpio_v2_line_flag + gpio_v2_line_info + gpio_v2_line_info_changed + gpio_v2_line_request + gpio_v2_line_values + gpiochip_info + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/chardev_v1.rst b/Documentation/userspace-api/gpio/chardev_v1.rst new file mode 100644 index 000000000000..67124b1d0487 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev_v1.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +GPIO Character Device Userspace API (v1) +======================================== + +.. warning:: + This API is obsoleted by chardev.rst (v2). + + New developments should use the v2 API, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. The v2 API is a functional superset of the v1 API so any + v1 call can be directly translated to a v2 equivalent. + + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. + +First added in 4.8. + +The API is based around three major objects, the :ref:`gpio-v1-chip`, the +:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`. + +Where "line event" is used in this document it refers to the request that can +monitor a line for edge events, not the edge events themselves. + +.. _gpio-v1-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst +and the resulting line handle is used to access the GPIO chip's lines, or +gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor +a GPIO line for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line Handle <gpio-get-linehandle-ioctl> + Get Line Event <gpio-get-lineevent-ioctl> + Get Chip Info <gpio-get-chipinfo-ioctl> + Get Line Info <gpio-get-lineinfo-ioctl> + Watch Line Info <gpio-get-lineinfo-watch-ioctl> + Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl> + Read Line Info Changed Events <gpio-lineinfo-changed-read> + +.. _gpio-v1-line-handle: + +Line Handle +=========== + +Line handles are created by gpio-get-linehandle-ioctl.rst and provide +access to a set of requested lines. The line handle is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst. + +Within this documentation, the line handle file descriptor is referred to +as ``handle_fd``. + +Operations +---------- + +The following operations may be performed on the line handle: + +.. toctree:: + :titlesonly: + + Get Line Values <gpio-handle-get-line-values-ioctl> + Set Line Values <gpio-handle-set-line-values-ioctl> + Reconfigure Lines <gpio-handle-set-config-ioctl> + +.. _gpio-v1-line-event: + +Line Event +========== + +Line events are created by gpio-get-lineevent-ioctl.rst and provide +access to a requested line. The line event is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst. + +Within this documentation, the line event file descriptor is referred to +as ``event_fd``. + +Operations +---------- + +The following operations may be performed on the line event: + +.. toctree:: + :titlesonly: + + Get Line Value <gpio-handle-get-line-values-ioctl> + Read Line Edge Events <gpio-lineevent-data-read> + +Types +===== + +This section contains the structs that are referenced by the ABI v1. + +The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpioevent_data + gpioevent_request + gpiohandle_config + gpiohandle_data + gpiohandle_request + gpioline_info + gpioline_info_changed + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst new file mode 100644 index 000000000000..6bf2948990cd --- /dev/null +++ b/Documentation/userspace-api/gpio/error-codes.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _gpio_errors: + +******************* +GPIO Error Codes +******************* + +.. _gpio-errors: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: Common GPIO error codes + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EAGAIN`` (aka ``EWOULDBLOCK``) + + - The device was opened in non-blocking mode and a read can't + be performed as there is no data available. + + - - ``EBADF`` + + - The file descriptor is not valid. + + - - ``EBUSY`` + + - The ioctl can't be handled because the device is busy. Typically + returned when an ioctl attempts something that would require the + usage of a resource that was already allocated. The ioctl must not + be retried without performing another action to fix the problem + first. + + - - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probably + caused by an invalid pointer reference. + + - - ``EINVAL`` + + - One or more of the ioctl parameters are invalid or out of the + allowed range. This is a widely used error code. + + - - ``ENODEV`` + + - Device not found or was removed. + + - - ``ENOMEM`` + + - There's not enough memory to handle the desired operation. + + - - ``EPERM`` + + - Permission denied. Typically returned in response to an attempt + to perform an action incompatible with the current line + configuration. + + - - ``EIO`` + + - I/O error. Typically returned when there are problems communicating + with a hardware device or requesting features that hardware does not + support. This could indicate broken or flaky hardware. + It's a 'Something is wrong, I give up!' type of error. + + - - ``ENXIO`` + + - Typically returned when a feature requiring interrupt support was + requested, but the line does not support interrupts. + +.. note:: + + #. This list is not exhaustive; ioctls may return other error codes. + Since errors may have side effects such as a driver reset, + applications should abort on unexpected errors, or otherwise + assume that the device is in a bad state. + + #. Request-specific error codes are listed in the individual + requests descriptions. diff --git a/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst new file mode 100644 index 000000000000..05f07fdefe2f --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_CHIPINFO_IOCTL: + +*********************** +GPIO_GET_CHIPINFO_IOCTL +*********************** + +Name +==== + +GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip. + +Synopsis +======== + +.. c:macro:: GPIO_GET_CHIPINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`chip_info<gpiochip_info>` to be populated. + +Description +=========== + +Gets the publicly available information for a particular GPIO chip. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst new file mode 100644 index 000000000000..09a9254f38cf --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEEVENT_IOCTL: + +************************ +GPIO_GET_LINEEVENT_IOCTL +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEEVENT_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`event_request<gpioevent_request>` specifying the line + to request and its configuration. + +Description +=========== + +Request a line with edge detection from the kernel. + +On success, the requesting process is granted exclusive access to the line +value and may receive events when edges are detected on the line, as +described in gpio-lineevent-data-read.rst. + +The state of a line is guaranteed to remain as requested until the returned +file descriptor is closed. Once the file descriptor is closed, the state of +the line becomes uncontrolled from the userspace perspective, and may revert +to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Requesting edge detection on a line that does not support interrupts is an +error (**ENXIO**). + +As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the +bias configuration is best effort. + +Closing the ``chip_fd`` has no effect on existing line events. + +Configuration Rules +------------------- + +The following configuration rules apply: + +The line event is requested as an input, so no flags specific to output lines, +``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or +``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and +``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising +and falling edges. + +Requesting an invalid configuration is an error (**EINVAL**). + +Return Value +============ + +On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file +descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst new file mode 100644 index 000000000000..9112a9d31174 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEHANDLE_IOCTL: + +************************* +GPIO_GET_LINEHANDLE_IOCTL +************************* + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`handle_request<gpiohandle_request>` specifying the lines to + request and their configuration. + +Description +=========== + +Request a line or lines from the kernel. + +While multiple lines may be requested, the same configuration applies to all +lines in the request. + +On success, the requesting process is granted exclusive access to the line +value and write access to the line configuration. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line handles. + +.. _gpio-get-linehandle-config-rules: + +Configuration Rules +------------------- + +The following configuration rules apply: + +The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and +``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the +only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the +line is requested "as-is" to allow reading of the line value without altering +the electrical configuration. + +The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the +``GPIOHANDLE_REQUEST_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and +it requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +Requesting an invalid configuration is an error (**EINVAL**). + + +.. _gpio-get-linehandle-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Direction reject +Drive emulate +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Drive is emulated by switching the line to an input when the line should not +be driven. + +In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + +Return Value +============ + +On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst new file mode 100644 index 000000000000..c895b8910b25 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_IOCTL: + +*********************** +GPIO_GET_LINEINFO_IOCTL +*********************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info<gpioline_info>` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst new file mode 100644 index 000000000000..a82d0161daf8 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL: + +******************************* +GPIO_GET_LINEINFO_UNWATCH_IOCTL +******************************* + +Name +==== + +GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its +requested state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``offset`` + The offset of the line to no longer watch. + +Description +=========== + +Remove the line from the list of lines being watched on this ``chip_fd``. + +This is the reverse of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and +gpio-get-lineinfo-watch-ioctl.rst (v1). + +Unwatching a line that is not watched is an error (**EBUSY**). + +First added in 5.7. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst new file mode 100644 index 000000000000..f5c92b69a496 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_WATCH_IOCTL: + +***************************** +GPIO_GET_LINEINFO_WATCH_IOCTL +***************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-watch-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_WATCH_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info<gpioline_info>` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value, and the line event can + monitor a line for events using gpio-lineevent-data-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +First added in 5.7. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst new file mode 100644 index 000000000000..25263b8f0588 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_GET_LINE_VALUES_IOCTL: + +******************************** +GPIOHANDLE_GET_LINE_VALUES_IOCTL +******************************** +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-get-values-ioctl.rst. + +Name +==== + +GPIOHANDLE_GET_LINE_VALUES_IOCTL - Get the values of all requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_GET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values<gpiohandle_data>` to be populated. + +Description +=========== + +Get the values of all requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +This ioctl can also be used to read the line value for line events, +substituting the ``event_fd`` for the ``handle_fd``. As there is only +one line requested in that case, only the one value is returned in ``values``. + +Return Value +============ + +On success 0 and ``values`` populated with the values read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst new file mode 100644 index 000000000000..d002a84681ac --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_SET_CONFIG_IOCTL: + +*************************** +GPIOHANDLE_SET_CONFIG_IOCTL +*************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-config-ioctl.rst. + +Name +==== + +GPIOHANDLE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_SET_CONFIG_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_SET_CONFIG_IOCTL, struct gpiohandle_config *config)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst. + +``config`` + The new :c:type:`configuration<gpiohandle_config>` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The configuration applies to all requested lines. + +The same :ref:`gpio-get-linehandle-config-rules` and +:ref:`gpio-get-linehandle-config-support` that apply when requesting the +lines also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may be used more +generally to move lines seamlessly from one configuration state to another. + +To only change the value of output lines, use +gpio-handle-set-line-values-ioctl.rst. + +First added in 5.5. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst new file mode 100644 index 000000000000..0aa05e623a6c --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_HANDLE_SET_LINE_VALUES_IOCTL: + +********************************* +GPIO_HANDLE_SET_LINE_VALUES_IOCTL +********************************* +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-values-ioctl.rst. + +Name +==== + +GPIO_HANDLE_SET_LINE_VALUES_IOCTL - Set the values of all requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_HANDLE_SET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIO_HANDLE_SET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values<gpiohandle_data>` to set. + +Description +=========== + +Set the values of all requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of input lines is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst new file mode 100644 index 000000000000..68b8d4f9f604 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEEVENT_DATA_READ: + +************************ +GPIO_LINEEVENT_DATA_READ +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-event-read.rst. + +Name +==== + +GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. + +Synopsis +======== + +``int read(int event_fd, void *buf, size_t count)`` + +Arguments +========= + +``event_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events<gpioevent_data>`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpioevent_data`. + +Description +=========== + +Read edge detection events for a line from a line event. + +Edge detection must be enabled for the input line using either +``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or +both. Edge events are then generated whenever edge interrupts are detected on +the input line. + +The kernel captures and timestamps edge events as close as possible to their +occurrence and stores them in a buffer from where they can be read by +userspace at its convenience using `read()`. + +The source of the clock for :c:type:`event.timestamp<gpioevent_data>` is +``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was +``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data` +as to which clock source is used, it must be determined from either the kernel +version or sanity checks on the timestamp itself. + +Events read from the buffer are always in the same order that they were +detected by the kernel. + +The size of the kernel event buffer is fixed at 16 events. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +The `read()` will block if no event is available and the ``event_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``event_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpio_lineevent_data` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst new file mode 100644 index 000000000000..c4f5e1787a9d --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEINFO_CHANGED_READ: + +************************** +GPIO_LINEINFO_CHANGED_READ +************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-lineinfo-changed-read.rst. + +Name +==== + +GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines +from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events<gpioline_info_changed>`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpioline_info_changed` event. + +Description +=========== + +Read line info change events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-lineevent-data-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +First added in 5.7. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpioline_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst new file mode 100644 index 000000000000..56b975801b6a --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst @@ -0,0 +1,152 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINE_IOCTL: + +********************** +GPIO_V2_GET_LINE_IOCTL +********************** + +Name +==== + +GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINE_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`line_request<gpio_v2_line_request>` specifying the lines + to request and their configuration. + +Description +=========== + +On success, the requesting process is granted exclusive access to the line +value, write access to the line configuration, and may receive events when +edges are detected on the line, all of which are described in more detail in +:ref:`gpio-v2-line-request`. + +A number of lines may be requested in the one line request, and request +operations are performed on the requested lines by the kernel as atomically +as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the +requested lines at once. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line requests. + +.. _gpio-v2-get-line-config-rules: + +Configuration Rules +------------------- + +For any given requested line, the following configuration rules apply: + +The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and +``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then +the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` +and the line is requested "as-is" to allow reading of the line value +without altering the electrical configuration. + +The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the +``GPIO_V2_LINE_FLAG_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it +requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require +``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising +and falling edges. Requesting edge detection from a line that does not support +it is an error (**ENXIO**). + +Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set. +If none are set then the event clock defaults to ``CLOCK_MONOTONIC``. +The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware +and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that +doesn't support it is an error (**EOPNOTSUP**). + +The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only +be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce +applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and +the edges returned by gpio-v2-line-event-read.rst. If not +supported directly by hardware, debouncing is emulated in software by the +kernel. Requesting debounce on a line that supports neither debounce in +hardware nor interrupts, as required for software emulation, is an error +(**ENXIO**). + +Requesting an invalid configuration is an error (**EINVAL**). + +.. _gpio-v2-get-line-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Debounce emulate +Direction reject +Drive emulate +Edge Detection reject +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Debounce is emulated by applying a filter to hardware interrupts on the line. +An edge event is generated after an edge is detected and the line remains +stable for the debounce period. +The event timestamp corresponds to the end of the debounce period. + +Drive is emulated by switching the line to an input when the line should not +be actively driven. + +Edge detection requires interrupt support, and is rejected if that is not +supported. Emulation by polling can still be performed from userspace. + +In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + +Return Value +============ + +On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst new file mode 100644 index 000000000000..bc4d8df887d4 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_IOCTL: + +************************** +GPIO_V2_GET_LINEINFO_IOCTL +************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info<gpio_v2_line_info>` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-v2-get-line-ioctl.rst to access its + value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst new file mode 100644 index 000000000000..938ff85a9322 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_WATCH_IOCTL: + +******************************** +GPIO_V2_GET_LINEINFO_WATCH_IOCTL +******************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_WATCH_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info<gpio_v2_line_info>` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + The line must be requested using gpio-v2-get-line-ioctl.rst to access + its value, and the line request can monitor a line for events using + gpio-v2-line-event-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-v2-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst new file mode 100644 index 000000000000..6513c23fb7ca --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_EVENT_READ: + +*********************** +GPIO_V2_LINE_EVENT_READ +*********************** + +Name +==== + +GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request. + +Synopsis +======== + +``int read(int req_fd, void *buf, size_t count)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events<gpio_v2_line_event>`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpio_v2_line_event`. + +Description +=========== + +Read edge detection events for lines from a request. + +Edge detection must be enabled for the input line using either +``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or +both. Edge events are then generated whenever edge interrupts are detected on +the input line. + +The kernel captures and timestamps edge events as close as possible to their +occurrence and stores them in a buffer from where they can be read by +userspace at its convenience using `read()`. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one request. + +The size of the kernel event buffer is fixed at the time of line request +creation, and can be influenced by the +:c:type:`request.event_buffer_size<gpio_v2_line_request>`. +The default size is 16 times the number of lines requested. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the oldest buffered event is +discarded. Overflow can be detected from userspace by monitoring the event +sequence numbers. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst +does not remove or modify the events already contained in the kernel event +buffer. + +The `read()` will block if no event is available and the ``req_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``req_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of a +:c:type:`gpio_v2_line_event` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst new file mode 100644 index 000000000000..e4e74a1926d8 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_GET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_GET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_GET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_GET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values<gpio_v2_line_values>` to get with the ``mask`` set + to indicate the subset of requested lines to get. + +Description +=========== + +Get the values of requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +Return Value +============ + +On success 0 and the corresponding :c:type:`values.bits<gpio_v2_line_values>` +contain the value read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst new file mode 100644 index 000000000000..9b942a8a53ca --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_CONFIG_IOCTL: + +***************************** +GPIO_V2_LINE_SET_CONFIG_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_CONFIG_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_CONFIG_IOCTL, struct gpio_v2_line_config *config)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. + +``config`` + The new :c:type:`configuration<gpio_v2_line_config>` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The new configuration must specify the configuration of all requested lines. + +The same :ref:`gpio-v2-get-line-config-rules` and +:ref:`gpio-v2-get-line-config-support` that apply when requesting the lines +also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may also be used to +dynamically control edge detection, or more generally move lines seamlessly +from one configuration state to another. + +To only change the value of output lines, use +gpio-v2-line-set-values-ioctl.rst. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst new file mode 100644 index 000000000000..6d2d1886950b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_SET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values<gpio_v2_line_values>` to set with the ``mask`` set + to indicate the subset of requested lines to set and ``bits`` set to + indicate the new value. + +Description +=========== + +Set the values of requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of an input line is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst new file mode 100644 index 000000000000..24ad325e7253 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINEINFO_CHANGED_READ: + +***************************** +GPIO_V2_LINEINFO_CHANGED_READ +***************************** + +Name +==== + +GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched +lines from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events<gpio_v2_line_info_changed>`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpio_v2_line_info_changed` event. + +Description +=========== + +Read line info changed events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-v2-line-event-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size +of a :c:type:`gpio_v2_line_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst new file mode 100644 index 000000000000..f258de4ef370 --- /dev/null +++ b/Documentation/userspace-api/gpio/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +GPIO +==== + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API <chardev> + Obsolete Userspace APIs <obsolete> + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/userspace-api/gpio/obsolete.rst b/Documentation/userspace-api/gpio/obsolete.rst new file mode 100644 index 000000000000..c42538b44ec8 --- /dev/null +++ b/Documentation/userspace-api/gpio/obsolete.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Obsolete GPIO Userspace APIs +============================ + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API (v1) <chardev_v1> + Sysfs Interface <sysfs> diff --git a/Documentation/userspace-api/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst new file mode 100644 index 000000000000..116921048b18 --- /dev/null +++ b/Documentation/userspace-api/gpio/sysfs.rst @@ -0,0 +1,170 @@ +GPIO Sysfs Interface for Userspace +================================== + +.. warning:: + This API is obsoleted by the chardev.rst and the ABI documentation has + been moved to Documentation/ABI/obsolete/sysfs-gpio. + + New developments should use the chardev.rst, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. + + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. + +The obsolete sysfs ABI +---------------------- +Platforms which use the "gpiolib" implementors framework may choose to +configure a sysfs user interface to GPIOs. This is different from the +debugfs interface, since it provides control over GPIO direction and +value instead of just showing a gpio state summary. Plus, it could be +present on production systems without debugging support. + +Given appropriate hardware documentation for the system, userspace could +know for example that GPIO #23 controls the write protect line used to +protect boot loader segments in flash memory. System upgrade procedures +may need to temporarily remove that protection, first importing a GPIO, +then changing its output state, then updating the code before re-enabling +the write protection. In normal use, GPIO #23 would never be touched, +and the kernel would have no need to know about it. + +Again depending on appropriate hardware documentation, on some systems +userspace GPIO can be used to determine system configuration data that +standard kernels won't know about. And for some tasks, simple userspace +GPIO drivers could be all that the system really needs. + +.. note:: + Do NOT abuse sysfs to control hardware that has proper kernel drivers. + Please read Documentation/driver-api/gpio/drivers-on-gpio.rst + to avoid reinventing kernel wheels in userspace. + + I MEAN IT. REALLY. + +Paths in Sysfs +-------------- +There are three kinds of entries in /sys/class/gpio: + + - Control interfaces used to get userspace control over GPIOs; + + - GPIOs themselves; and + + - GPIO controllers ("gpio_chip" instances). + +That's in addition to standard files including the "device" symlink. + +The control interfaces are write-only: + + /sys/class/gpio/ + + "export" ... + Userspace may ask the kernel to export control of + a GPIO to userspace by writing its number to this file. + + Example: "echo 19 > export" will create a "gpio19" node + for GPIO #19, if that's not requested by kernel code. + + "unexport" ... + Reverses the effect of exporting to userspace. + + Example: "echo 19 > unexport" will remove a "gpio19" + node exported using the "export" file. + +GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) +and have the following read/write attributes: + + /sys/class/gpio/gpioN/ + + "direction" ... + reads as either "in" or "out". This value may + normally be written. Writing as "out" defaults to + initializing the value as low. To ensure glitch free + operation, values "low" and "high" may be written to + configure the GPIO as an output with that initial value. + + Note that this attribute *will not exist* if the kernel + doesn't support changing the direction of a GPIO, or + it was exported by kernel code that didn't explicitly + allow userspace to reconfigure this GPIO's direction. + + "value" ... + reads as either 0 (inactive) or 1 (active). If the GPIO + is configured as an output, this value may be written; + any nonzero value is treated as active. + + If the pin can be configured as interrupt-generating interrupt + and if it has been configured to generate interrupts (see the + description of "edge"), you can poll(2) on that file and + poll(2) will return whenever the interrupt was triggered. If + you use poll(2), set the events POLLPRI and POLLERR. If you + use select(2), set the file descriptor in exceptfds. After + poll(2) returns, either lseek(2) to the beginning of the sysfs + file and read the new value or close the file and re-open it + to read the value. + + "edge" ... + reads as either "none", "rising", "falling", or + "both". Write these strings to select the signal edge(s) + that will make poll(2) on the "value" file return. + + This file exists only if the pin can be configured as an + interrupt generating input pin. + + "active_low" ... + reads as either 0 (false) or 1 (true). Write + any nonzero value to invert the value attribute both + for reading and writing. Existing and subsequent + poll(2) support configuration via the edge attribute + for "rising" and "falling" edges will follow this + setting. + +GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the +controller implementing GPIOs starting at #42) and have the following +read-only attributes: + + /sys/class/gpio/gpiochipN/ + + "base" ... + same as N, the first GPIO managed by this chip + + "label" ... + provided for diagnostics (not always unique) + + "ngpio" ... + how many GPIOs this manages (N to N + ngpio - 1) + +Board documentation should in most cases cover what GPIOs are used for +what purposes. However, those numbers are not always stable; GPIOs on +a daughtercard might be different depending on the base board being used, +or other cards in the stack. In such cases, you may need to use the +gpiochip nodes (possibly in conjunction with schematics) to determine +the correct GPIO number to use for a given signal. + + +Exporting from Kernel code +-------------------------- +Kernel code can explicitly manage exports of GPIOs which have already been +requested using gpio_request():: + + /* export the GPIO to userspace */ + int gpiod_export(struct gpio_desc *desc, bool direction_may_change); + + /* reverse gpiod_export() */ + void gpiod_unexport(struct gpio_desc *desc); + + /* create a sysfs link to an exported GPIO node */ + int gpiod_export_link(struct device *dev, const char *name, + struct gpio_desc *desc); + +After a kernel driver requests a GPIO, it may only be made available in +the sysfs interface by gpiod_export(). The driver can control whether the +signal direction may change. This helps drivers prevent userspace code +from accidentally clobbering important system state. + +This explicit exporting can help with debugging (by making some kinds +of experiments easier), or can provide an always-there interface that's +suitable for documenting as part of a board support package. + +After the GPIO has been exported, gpiod_export_link() allows creating +symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can +use this to provide the interface under their own device in sysfs with +a descriptive name. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index a61eac0c73f8..afecfe3cc4a8 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -9,26 +9,59 @@ While much of the kernel's user-space API is documented elsewhere also be found in the kernel tree itself. This manual is intended to be the place where this information is gathered. -.. class:: toc-title - Table of contents +System calls +============ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + unshare + futex2 + ebpf/index + ioctl/index + +Security-related interfaces +=========================== + +.. toctree:: + :maxdepth: 1 no_new_privs seccomp_filter landlock - unshare + lsm spec_ctrl + tee + +Devices and I/O +=============== + +.. toctree:: + :maxdepth: 1 + accelerators/ocxl - ebpf/index - ioctl/index + dma-buf-alloc-exchange + gpio/index iommu + iommufd media/index + dcdbas + vduse + isapnp + +Everything else +=============== + +.. toctree:: + :maxdepth: 1 + + ELF + netlink/index sysfs-platform_profile vduse futex2 + perf_ring_buffer .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index fcab013e47c9..c472423412bf 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -82,8 +82,9 @@ Code Seq# Include File Comments 0x10 00-0F drivers/char/s390/vmcp.h 0x10 10-1F arch/s390/include/uapi/sclp_ctl.h 0x10 20-2F arch/s390/include/uapi/asm/hypfs.h -0x12 all linux/fs.h +0x12 all linux/fs.h BLK* ioctls linux/blkpg.h +0x15 all linux/fs.h FS_IOC_* ioctls 0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/> 0x20 all drivers/cdrom/cm206.h @@ -105,6 +106,7 @@ Code Seq# Include File Comments '8' all SNP8023 advanced NIC card <mailto:mcr@solidum.com> ';' 64-7F linux/vfio.h +';' 80-FF linux/iommufd.h '=' 00-3f uapi/linux/ptp_clock.h <mailto:richardcochran@gmail.com> '@' 00-0F linux/radeonfb.h conflict! '@' 00-0F drivers/video/aty/aty128fb.c conflict! @@ -120,14 +122,13 @@ Code Seq# Include File Comments 'C' 01-2F linux/capi.h conflict! 'C' F0-FF drivers/net/wan/cosa.h conflict! 'D' all arch/s390/include/asm/dasd.h -'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h +'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h Dead since 2022 'D' 05 drivers/scsi/pmcraid.h 'E' all linux/input.h conflict! 'E' 00-0F xen/evtchn.h conflict! 'F' all linux/fb.h conflict! 'F' 01-02 drivers/scsi/pmcraid.h conflict! 'F' 20 drivers/video/fsl-diu-fb.h conflict! -'F' 20 drivers/video/intelfb/intelfb.h conflict! 'F' 20 linux/ivtvfb.h conflict! 'F' 20 linux/matroxfb.h conflict! 'F' 20 drivers/video/aty/atyfb_base.c conflict! @@ -179,6 +180,7 @@ Code Seq# Include File Comments 'P' 00-0F drivers/usb/class/usblp.c conflict! 'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! 'P' 00-0F xen/privcmd.h conflict! +'P' 00-05 linux/tps6594_pfsm.h conflict! 'Q' all linux/soundcard.h 'R' 00-1F linux/random.h conflict! 'R' 01 linux/rfkill.h conflict! @@ -200,7 +202,6 @@ Code Seq# Include File Comments 'V' all linux/videodev2.h conflict! 'V' C0 linux/ivtvfb.h conflict! 'V' C0 linux/ivtv.h conflict! -'V' C0 media/davinci/vpfe_capture.h conflict! 'V' C0 media/si4713.h conflict! 'W' 00-1F linux/watchdog.h conflict! 'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) @@ -221,7 +222,7 @@ Code Seq# Include File Comments 'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver 'b' 00-FF conflict! bit3 vme host bridge <mailto:natalia@nikhefk.nikhef.nl> -'c' all linux/cm4000_cs.h conflict! +'b' 00-0F linux/dma-buf.h conflict! 'c' 00-7F linux/comstats.h conflict! 'c' 00-7F linux/coda.h conflict! 'c' 00-1F linux/chio.h conflict! @@ -308,8 +309,8 @@ Code Seq# Include File Comments 0x89 00-06 arch/x86/include/asm/sockios.h 0x89 0B-DF linux/sockios.h 0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range -0x89 E0-EF linux/dn.h PROTOPRIVATE range 0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range +0x8A 00-1F linux/eventpoll.h 0x8B all linux/wireless.h 0x8C 00-3F WiNRADiO driver <http://www.winradio.com.au/> @@ -349,6 +350,10 @@ Code Seq# Include File Comments <mailto:vgo@ratio.de> 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> +0xB2 00 arch/powerpc/include/uapi/asm/papr-vpd.h powerpc/pseries VPD API + <mailto:linuxppc-dev> +0xB2 01-02 arch/powerpc/include/uapi/asm/papr-sysparm.h powerpc/pseries system parameter API + <mailto:linuxppc-dev> 0xB3 00 linux/mmc/ioctl.h 0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org> 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> @@ -364,7 +369,7 @@ Code Seq# Include File Comments 0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver 0xCD 01 linux/reiserfs_fs.h 0xCE 01-02 uapi/linux/cxl_mem.h Compute Express Link Memory Devices -0xCF 02 fs/cifs/ioctl.c +0xCF 02 fs/smb/client/cifs_ioctl.h 0xDB 00-0F drivers/char/mwave/mwavepub.h 0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ <mailto:aherrman@de.ibm.com> diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst new file mode 100644 index 000000000000..aa004faed5fd --- /dev/null +++ b/Documentation/userspace-api/iommufd.rst @@ -0,0 +1,223 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======= +IOMMUFD +======= + +:Author: Jason Gunthorpe +:Author: Kevin Tian + +Overview +======== + +IOMMUFD is the user API to control the IOMMU subsystem as it relates to managing +IO page tables from userspace using file descriptors. It intends to be general +and consumable by any driver that wants to expose DMA to userspace. These +drivers are eventually expected to deprecate any internal IOMMU logic +they may already/historically implement (e.g. vfio_iommu_type1.c). + +At minimum iommufd provides universal support of managing I/O address spaces and +I/O page tables for all IOMMUs, with room in the design to add non-generic +features to cater to specific hardware functionality. + +In this context the capital letter (IOMMUFD) refers to the subsystem while the +small letter (iommufd) refers to the file descriptors created via /dev/iommu for +use by userspace. + +Key Concepts +============ + +User Visible Objects +-------------------- + +Following IOMMUFD objects are exposed to userspace: + +- IOMMUFD_OBJ_IOAS, representing an I/O address space (IOAS), allowing map/unmap + of user space memory into ranges of I/O Virtual Address (IOVA). + + The IOAS is a functional replacement for the VFIO container, and like the VFIO + container it copies an IOVA map to a list of iommu_domains held within it. + +- IOMMUFD_OBJ_DEVICE, representing a device that is bound to iommufd by an + external driver. + +- IOMMUFD_OBJ_HW_PAGETABLE, representing an actual hardware I/O page table + (i.e. a single struct iommu_domain) managed by the iommu driver. + + The IOAS has a list of HW_PAGETABLES that share the same IOVA mapping and + it will synchronize its mapping with each member HW_PAGETABLE. + +All user-visible objects are destroyed via the IOMMU_DESTROY uAPI. + +The diagram below shows relationship between user-visible objects and kernel +datastructures (external to iommufd), with numbers referred to operations +creating the objects and links:: + + _________________________________________________________ + | iommufd | + | [1] | + | _________________ | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | [3] [2] | + | | | ____________ __________ | + | | IOAS |<--| |<------| | | + | | | |HW_PAGETABLE| | DEVICE | | + | | | |____________| |__________| | + | | | | | | + | | | | | | + | | | | | | + | | | | | | + | | | | | | + | |_________________| | | | + | | | | | + |_________|___________________|___________________|_______| + | | | + | _____v______ _______v_____ + | PFN storage | | | | + |------------>|iommu_domain| |struct device| + |____________| |_____________| + +1. IOMMUFD_OBJ_IOAS is created via the IOMMU_IOAS_ALLOC uAPI. An iommufd can + hold multiple IOAS objects. IOAS is the most generic object and does not + expose interfaces that are specific to single IOMMU drivers. All operations + on the IOAS must operate equally on each of the iommu_domains inside of it. + +2. IOMMUFD_OBJ_DEVICE is created when an external driver calls the IOMMUFD kAPI + to bind a device to an iommufd. The driver is expected to implement a set of + ioctls to allow userspace to initiate the binding operation. Successful + completion of this operation establishes the desired DMA ownership over the + device. The driver must also set the driver_managed_dma flag and must not + touch the device until this operation succeeds. + +3. IOMMUFD_OBJ_HW_PAGETABLE is created when an external driver calls the IOMMUFD + kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI + allows userspace to initiate the attaching operation. If a compatible + pagetable already exists then it is reused for the attachment. Otherwise a + new pagetable object and iommu_domain is created. Successful completion of + this operation sets up the linkages among IOAS, device and iommu_domain. Once + this completes the device could do DMA. + + Every iommu_domain inside the IOAS is also represented to userspace as a + HW_PAGETABLE object. + + .. note:: + + Future IOMMUFD updates will provide an API to create and manipulate the + HW_PAGETABLE directly. + +A device can only bind to an iommufd due to DMA ownership claim and attach to at +most one IOAS object (no support of PASID yet). + +Kernel Datastructure +-------------------- + +User visible objects are backed by following datastructures: + +- iommufd_ioas for IOMMUFD_OBJ_IOAS. +- iommufd_device for IOMMUFD_OBJ_DEVICE. +- iommufd_hw_pagetable for IOMMUFD_OBJ_HW_PAGETABLE. + +Several terminologies when looking at these datastructures: + +- Automatic domain - refers to an iommu domain created automatically when + attaching a device to an IOAS object. This is compatible to the semantics of + VFIO type1. + +- Manual domain - refers to an iommu domain designated by the user as the + target pagetable to be attached to by a device. Though currently there are + no uAPIs to directly create such domain, the datastructure and algorithms + are ready for handling that use case. + +- In-kernel user - refers to something like a VFIO mdev that is using the + IOMMUFD access interface to access the IOAS. This starts by creating an + iommufd_access object that is similar to the domain binding a physical device + would do. The access object will then allow converting IOVA ranges into struct + page * lists, or doing direct read/write to an IOVA. + +iommufd_ioas serves as the metadata datastructure to manage how IOVA ranges are +mapped to memory pages, composed of: + +- struct io_pagetable holding the IOVA map +- struct iopt_area's representing populated portions of IOVA +- struct iopt_pages representing the storage of PFNs +- struct iommu_domain representing the IO page table in the IOMMU +- struct iopt_pages_access representing in-kernel users of PFNs +- struct xarray pinned_pfns holding a list of pages pinned by in-kernel users + +Each iopt_pages represents a logical linear array of full PFNs. The PFNs are +ultimately derived from userspace VAs via an mm_struct. Once they have been +pinned the PFNs are stored in IOPTEs of an iommu_domain or inside the pinned_pfns +xarray if they have been pinned through an iommufd_access. + +PFN have to be copied between all combinations of storage locations, depending +on what domains are present and what kinds of in-kernel "software access" users +exist. The mechanism ensures that a page is pinned only once. + +An io_pagetable is composed of iopt_areas pointing at iopt_pages, along with a +list of iommu_domains that mirror the IOVA to PFN map. + +Multiple io_pagetable-s, through their iopt_area-s, can share a single +iopt_pages which avoids multi-pinning and double accounting of page +consumption. + +iommufd_ioas is shareable between subsystems, e.g. VFIO and VDPA, as long as +devices managed by different subsystems are bound to a same iommufd. + +IOMMUFD User API +================ + +.. kernel-doc:: include/uapi/linux/iommufd.h + +IOMMUFD Kernel API +================== + +The IOMMUFD kAPI is device-centric with group-related tricks managed behind the +scene. This allows the external drivers calling such kAPI to implement a simple +device-centric uAPI for connecting its device to an iommufd, instead of +explicitly imposing the group semantics in its uAPI as VFIO does. + +.. kernel-doc:: drivers/iommu/iommufd/device.c + :export: + +.. kernel-doc:: drivers/iommu/iommufd/main.c + :export: + +VFIO and IOMMUFD +---------------- + +Connecting a VFIO device to iommufd can be done in two ways. + +First is a VFIO compatible way by directly implementing the /dev/vfio/vfio +container IOCTLs by mapping them into io_pagetable operations. Doing so allows +the use of iommufd in legacy VFIO applications by symlinking /dev/vfio/vfio to +/dev/iommufd or extending VFIO to SET_CONTAINER using an iommufd instead of a +container fd. + +The second approach directly extends VFIO to support a new set of device-centric +user API based on aforementioned IOMMUFD kernel API. It requires userspace +change but better matches the IOMMUFD API semantics and easier to support new +iommufd features when comparing it to the first approach. + +Currently both approaches are still work-in-progress. + +There are still a few gaps to be resolved to catch up with VFIO type1, as +documented in iommufd_vfio_check_extension(). + +Future TODOs +============ + +Currently IOMMUFD supports only kernel-managed I/O page table, similar to VFIO +type1. New features on the radar include: + + - Binding iommu_domain's to PASID/SSID + - Userspace page tables, for ARM, x86 and S390 + - Kernel bypass'd invalidation of user page tables + - Re-use of the KVM page table in the IOMMU + - Dirty page tracking in the IOMMU + - Runtime Increase/Decrease of IOPTE size + - PRI support with faults resolved in userspace diff --git a/Documentation/userspace-api/isapnp.rst b/Documentation/userspace-api/isapnp.rst new file mode 100644 index 000000000000..d6fceb19b8ae --- /dev/null +++ b/Documentation/userspace-api/isapnp.rst @@ -0,0 +1,15 @@ +======================= +ISA Plug & Play support +======================= + +Interface /proc/isapnp +====================== + +The interface was removed in kernel 2.5.53. See pnp.rst for more details. + +Interface /proc/bus/isapnp +========================== + +This directory allows access to ISA PnP cards and logical devices. +The regular files contain the contents of ISA PnP registers for +a logical device. diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index b8ea59493964..9dd636aaa829 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,40 +8,55 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: May 2022 +:Date: October 2023 The goal of Landlock is to enable to restrict ambient rights (e.g. global -filesystem access) for a set of processes. Because Landlock is a stackable -LSM, it makes possible to create safe security sandboxes as new security layers -in addition to the existing system-wide access-controls. This kind of sandbox -is expected to help mitigate the security impact of bugs or +filesystem or network access) for a set of processes. Because Landlock +is a stackable LSM, it makes possible to create safe security sandboxes as new +security layers in addition to the existing system-wide access-controls. This +kind of sandbox is expected to help mitigate the security impact of bugs or unexpected/malicious behaviors in user space applications. Landlock empowers any process, including unprivileged ones, to securely restrict themselves. We can quickly make sure that Landlock is enabled in the running system by -looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep -landlock || journalctl -kg landlock`` . Developers can also easily check for -Landlock support with a :ref:`related system call <landlock_abi_versions>`. If -Landlock is not currently supported, we need to :ref:`configure the kernel -appropriately <kernel_support>`. +looking for "landlock: Up and running" in kernel logs (as root): +``dmesg | grep landlock || journalctl -kb -g landlock`` . +Developers can also easily check for Landlock support with a +:ref:`related system call <landlock_abi_versions>`. +If Landlock is not currently supported, we need to +:ref:`configure the kernel appropriately <kernel_support>`. Landlock rules ============== -A Landlock rule describes an action on an object. An object is currently a -file hierarchy, and the related filesystem actions are defined with `access -rights`_. A set of rules is aggregated in a ruleset, which can then restrict +A Landlock rule describes an action on an object which the process intends to +perform. A set of rules is aggregated in a ruleset, which can then restrict the thread enforcing it, and its future children. +The two existing types of rules are: + +Filesystem rules + For these rules, the object is a file hierarchy, + and the related filesystem actions are defined with + `filesystem access rights`. + +Network rules (since ABI v4) + For these rules, the object is a TCP port, + and the related actions are defined with `network access rights`. + Defining and enforcing a security policy ---------------------------------------- -We first need to define the ruleset that will contain our rules. For this -example, the ruleset will contain rules that only allow read actions, but write -actions will be denied. The ruleset then needs to handle both of these kind of -actions. This is required for backward and forward compatibility (i.e. the -kernel and user space may not know each other's supported restrictions), hence -the need to be explicit about the denied-by-default access rights. +We first need to define the ruleset that will contain our rules. + +For this example, the ruleset will contain rules that only allow filesystem +read actions and establish a specific TCP connection. Filesystem write +actions and other TCP actions will be denied. + +The ruleset then needs to handle both these kinds of actions. This is +required for backward and forward compatibility (i.e. the kernel and user +space may not know each other's supported restrictions), hence the need +to be explicit about the denied-by-default access rights. .. code-block:: c @@ -60,7 +75,11 @@ the need to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | - LANDLOCK_ACCESS_FS_REFER, + LANDLOCK_ACCESS_FS_REFER | + LANDLOCK_ACCESS_FS_TRUNCATE, + .handled_access_net = + LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP, }; Because we may not know on which kernel version an application will be @@ -69,16 +88,32 @@ should try to protect users as much as possible whatever the kernel they are using. To avoid binary enforcement (i.e. either all security features or none), we can leverage a dedicated Landlock command to get the current version of the Landlock ABI and adapt the handled accesses. Let's check if we should -remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported -starting with the second version of the ABI. +remove access rights which are only supported in higher versions of the ABI. .. code-block:: c int abi; abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); - if (abi < 2) { + if (abi < 0) { + /* Degrades gracefully if Landlock is not handled. */ + perror("The running kernel does not enable to use Landlock"); + return 0; + } + switch (abi) { + case 1: + /* Removes LANDLOCK_ACCESS_FS_REFER for ABI < 2 */ ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; + __attribute__((fallthrough)); + case 2: + /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */ + ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE; + __attribute__((fallthrough)); + case 3: + /* Removes network support for ABI < 4 */ + ruleset_attr.handled_access_net &= + ~(LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP); } This enables to create an inclusive ruleset that will contain our rules. @@ -127,13 +162,26 @@ descriptor. It may also be required to create rules following the same logic as explained for the ruleset creation, by filtering access rights according to the Landlock -ABI version. In this example, this is not required because -`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule. +ABI version. In this example, this is not required because all of the requested +``allowed_access`` rights are already available in ABI 1. + +For network access-control, we can add a set of rules that allow to use a port +number for a specific action: HTTPS connections. + +.. code-block:: c + + struct landlock_net_port_attr net_port = { + .allowed_access = LANDLOCK_ACCESS_NET_CONNECT_TCP, + .port = 443, + }; -We now have a ruleset with one rule allowing read access to ``/usr`` while -denying all other handled accesses for the filesystem. The next step is to -restrict the current thread from gaining more privileges (e.g. thanks to a SUID -binary). + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT, + &net_port, 0); + +The next step is to restrict the current thread from gaining more privileges +(e.g. through a SUID binary). We now have a ruleset with the first rule +allowing read access to ``/usr`` while denying all other handled accesses for +the filesystem, and a second rule allowing HTTPS connections. .. code-block:: c @@ -154,8 +202,8 @@ The current thread is now ready to sandbox itself with the ruleset. } close(ruleset_fd); -If the `landlock_restrict_self` system call succeeds, the current thread is now -restricted and this policy will be enforced on all its subsequently created +If the ``landlock_restrict_self`` system call succeeds, the current thread is +now restricted and this policy will be enforced on all its subsequently created children as well. Once a thread is landlocked, there is no way to remove its security policy; only adding more restrictions is allowed. These threads are now in a new Landlock domain, merge of their parent one (if any) with the new @@ -170,12 +218,13 @@ It is recommended setting access rights to file hierarchy leaves as much as possible. For instance, it is better to be able to have ``~/doc/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. -Following this good practice leads to self-sufficient hierarchies that don't +Following this good practice leads to self-sufficient hierarchies that do not depend on their location (i.e. parent directories). This is particularly relevant when we want to allow linking or renaming. Indeed, having consistent access rights per directory enables to change the location of such directory without relying on the destination directory access rights (except those that -are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation). +are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` +documentation). Having self-sufficient hierarchies also helps to tighten the required access rights to the minimal set of data. This also helps avoid sinkhole directories, i.e. directories where data can be linked to but not linked from. However, @@ -251,6 +300,37 @@ To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target process, a sandboxed process should have a subset of the target process rules, which means the tracee must be in a sub-domain of the tracer. +Truncating files +---------------- + +The operations covered by ``LANDLOCK_ACCESS_FS_WRITE_FILE`` and +``LANDLOCK_ACCESS_FS_TRUNCATE`` both change the contents of a file and sometimes +overlap in non-intuitive ways. It is recommended to always specify both of +these together. + +A particularly surprising example is :manpage:`creat(2)`. The name suggests +that this system call requires the rights to create and write files. However, +it also requires the truncate right if an existing file under the same name is +already present. + +It should also be noted that truncating files does not require the +``LANDLOCK_ACCESS_FS_WRITE_FILE`` right. Apart from the :manpage:`truncate(2)` +system call, this can also be done through :manpage:`open(2)` with the flags +``O_RDONLY | O_TRUNC``. + +When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` +right is associated with the newly created file descriptor and will be used for +subsequent truncation attempts using :manpage:`ftruncate(2)`. The behavior is +similar to opening a file for reading or writing, where permissions are checked +during :manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and +:manpage:`write(2)` calls. + +As a consequence, it is possible to have multiple open file descriptors for the +same file, where one grants the right to truncate the file and the other does +not. It is also possible to pass such file descriptors between processes, +keeping their Landlock properties, even when these processes do not have an +enforced Landlock ruleset. + Compatibility ============= @@ -259,7 +339,7 @@ Backward and forward compatibility Landlock is designed to be compatible with past and future versions of the kernel. This is achieved thanks to the system call attributes and the -associated bitflags, particularly the ruleset's `handled_access_fs`. Making +associated bitflags, particularly the ruleset's ``handled_access_fs``. Making handled access right explicit enables the kernel and user space to have a clear contract with each other. This is required to make sure sandboxing will not get stricter with a system update, which could break applications. @@ -310,7 +390,7 @@ Access rights ------------- .. kernel-doc:: include/uapi/linux/landlock.h - :identifiers: fs_access + :identifiers: fs_access net_access Creating a new ruleset ---------------------- @@ -329,6 +409,7 @@ Extending a ruleset .. kernel-doc:: include/uapi/linux/landlock.h :identifiers: landlock_rule_type landlock_path_beneath_attr + landlock_net_port_attr Enforcing a ruleset ------------------- @@ -342,9 +423,9 @@ Current limitations Filesystem topology modification -------------------------------- -As for file renaming and linking, a sandboxed thread cannot modify its -filesystem topology, whether via :manpage:`mount(2)` or -:manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. +Threads sandboxed with filesystem restrictions cannot modify filesystem +topology, whether via :manpage:`mount(2)` or :manpage:`pivot_root(2)`. +However, :manpage:`chroot(2)` calls are not denied. Special filesystems ------------------- @@ -380,8 +461,8 @@ by the Documentation/admin-guide/cgroup-v1/memory.rst. Previous limitations ==================== -File renaming and linking (ABI 1) ---------------------------------- +File renaming and linking (ABI < 2) +----------------------------------- Because Landlock targets unprivileged access controls, it needs to properly handle composition of rules. Such property also implies rules nesting. @@ -394,27 +475,94 @@ according to the potentially lost constraints. To protect against privilege escalations through renaming or linking, and for the sake of simplicity, Landlock previously limited linking and renaming to the same directory. Starting with the Landlock ABI version 2, it is now possible to securely -control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER` +control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` access right. +File truncation (ABI < 3) +------------------------- + +File truncation could not be denied before the third Landlock ABI, so it is +always allowed when using a kernel that only supports the first or second ABI. + +Starting with the Landlock ABI version 3, it is now possible to securely control +truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right. + +Network support (ABI < 4) +------------------------- + +Starting with the Landlock ABI version 4, it is now possible to restrict TCP +bind and connect actions to only a set of allowed ports thanks to the new +``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` +access rights. + .. _kernel_support: Kernel support ============== +Build time configuration +------------------------ + Landlock was first introduced in Linux 5.13 but it must be configured at build -time with `CONFIG_SECURITY_LANDLOCK=y`. Landlock must also be enabled at boot +time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot time as the other security modules. The list of security modules enabled by -default is set with `CONFIG_LSM`. The kernel configuration should then -contains `CONFIG_LSM=landlock,[...]` with `[...]` as the list of other +default is set with ``CONFIG_LSM``. The kernel configuration should then +contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other potentially useful security modules for the running system (see the -`CONFIG_LSM` help). +``CONFIG_LSM`` help). + +Boot time configuration +----------------------- -If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can -still enable it by adding ``lsm=landlock,[...]`` to -Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader +If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can +enable Landlock by adding ``lsm=landlock,[...]`` to +Documentation/admin-guide/kernel-parameters.rst in the boot loader configuration. +For example, if the current built-in configuration is: + +.. code-block:: console + + $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(uname -r)" /proc/config.gz 2>/dev/null + CONFIG_LSM="lockdown,yama,integrity,apparmor" + +...and if the cmdline doesn't contain ``landlock`` either: + +.. code-block:: console + + $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc/cmdline + lsm=lockdown,yama,integrity,apparmor + +...we should configure the boot loader to set a cmdline extending the ``lsm`` +list with the ``landlock,`` prefix:: + + lsm=landlock,lockdown,yama,integrity,apparmor + +After a reboot, we can check that Landlock is up and running by looking at +kernel logs: + +.. code-block:: console + + # dmesg | grep landlock || journalctl -kb -g landlock + [ 0.000000] Command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor + [ 0.000000] Kernel command line: [...] lsm=landlock,lockdown,yama,integrity,apparmor + [ 0.000000] LSM: initializing lsm=lockdown,capability,landlock,yama,integrity,apparmor + [ 0.000000] landlock: Up and running. + +The kernel may be configured at build time to always load the ``lockdown`` and +``capability`` LSMs. In that case, these LSMs will appear at the beginning of +the ``LSM: initializing`` log line as well, even if they are not configured in +the boot loader. + +Network support +--------------- + +To be able to explicitly allow TCP operations (e.g., adding a network rule with +``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP +(``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an +``EAFNOSUPPORT`` error, which can safely be ignored because this kind of TCP +operation is already not possible. + Questions and answers ===================== diff --git a/Documentation/userspace-api/lsm.rst b/Documentation/userspace-api/lsm.rst new file mode 100644 index 000000000000..a76da373841b --- /dev/null +++ b/Documentation/userspace-api/lsm.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2022 Casey Schaufler <casey@schaufler-ca.com> +.. Copyright (C) 2022 Intel Corporation + +===================================== +Linux Security Modules +===================================== + +:Author: Casey Schaufler +:Date: July 2023 + +Linux security modules (LSM) provide a mechanism to implement +additional access controls to the Linux security policies. + +The various security modules may support any of these attributes: + +``LSM_ATTR_CURRENT`` is the current, active security context of the +process. +The proc filesystem provides this value in ``/proc/self/attr/current``. +This is supported by the SELinux, Smack and AppArmor security modules. +Smack also provides this value in ``/proc/self/attr/smack/current``. +AppArmor also provides this value in ``/proc/self/attr/apparmor/current``. + +``LSM_ATTR_EXEC`` is the security context of the process at the time the +current image was executed. +The proc filesystem provides this value in ``/proc/self/attr/exec``. +This is supported by the SELinux and AppArmor security modules. +AppArmor also provides this value in ``/proc/self/attr/apparmor/exec``. + +``LSM_ATTR_FSCREATE`` is the security context of the process used when +creating file system objects. +The proc filesystem provides this value in ``/proc/self/attr/fscreate``. +This is supported by the SELinux security module. + +``LSM_ATTR_KEYCREATE`` is the security context of the process used when +creating key objects. +The proc filesystem provides this value in ``/proc/self/attr/keycreate``. +This is supported by the SELinux security module. + +``LSM_ATTR_PREV`` is the security context of the process at the time the +current security context was set. +The proc filesystem provides this value in ``/proc/self/attr/prev``. +This is supported by the SELinux and AppArmor security modules. +AppArmor also provides this value in ``/proc/self/attr/apparmor/prev``. + +``LSM_ATTR_SOCKCREATE`` is the security context of the process used when +creating socket objects. +The proc filesystem provides this value in ``/proc/self/attr/sockcreate``. +This is supported by the SELinux security module. + +Kernel interface +================ + +Set a security attribute of the current process +----------------------------------------------- + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_set_self_attr + +Get the specified security attributes of the current process +------------------------------------------------------------ + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_get_self_attr + +.. kernel-doc:: security/lsm_syscalls.c + :identifiers: sys_lsm_list_modules + +Additional documentation +======================== + +* Documentation/security/lsm.rst +* Documentation/security/lsm-development.rst diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 00922aa7efde..3d8aaf5c253b 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -47,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception # Media build rules -.PHONY: all html epub xml latex +.PHONY: all html texinfo epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} html: all +texinfo: all epub: all xml: all latex: $(IMGPDF) all diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec.h.rst.exceptions index 13de01d9555e..15fa1752d4ef 100644 --- a/Documentation/userspace-api/media/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec.h.rst.exceptions @@ -239,6 +239,7 @@ ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX +ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_VOLUME_LEVEL ignore define CEC_MSG_GIVE_FEATURES @@ -487,6 +488,7 @@ ignore define CEC_OP_SYS_AUD_STATUS_ON ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS +ignore define CEC_MSG_SET_AUDIO_VOLUME_LEVEL ignore define CEC_OP_AUD_FMT_ID_CEA861 ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT diff --git a/Documentation/userspace-api/media/cec/cec-api.rst b/Documentation/userspace-api/media/cec/cec-api.rst index 4d229ed8a1d9..578303d484f3 100644 --- a/Documentation/userspace-api/media/cec/cec-api.rst +++ b/Documentation/userspace-api/media/cec/cec-api.rst @@ -10,13 +10,8 @@ Part V - Consumer Electronics Control API This part describes the CEC: Consumer Electronics Control -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index b0efce40471f..411d42a742f3 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. _cec_pin_error_inj: + CEC Pin Framework Error Injection ================================= diff --git a/Documentation/userspace-api/media/drivers/aspeed-video.rst b/Documentation/userspace-api/media/drivers/aspeed-video.rst new file mode 100644 index 000000000000..567387aca6b0 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/aspeed-video.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +ASPEED video driver +=================== + +ASPEED Video Engine found on AST2400/2500/2600 SoC supports high performance +video compressions with a wide range of video quality and compression ratio +options. The adopted compressing algorithm is a modified JPEG algorithm. + +There are 2 types of compressions in this IP. + +* JPEG JFIF standard mode: for single frame and management compression +* ASPEED proprietary mode: for multi-frame and differential compression. + Support 2-pass (high quality) video compression scheme (Patent pending by + ASPEED). Provide visually lossless video compression quality or to reduce + the network average loading under intranet KVM applications. + +VIDIOC_S_FMT can be used to choose which format you want. V4L2_PIX_FMT_JPEG +stands for JPEG JFIF standard mode; V4L2_PIX_FMT_AJPG stands for ASPEED +proprietary mode. + +More details on the ASPEED video hardware operations can be found in +*chapter 6.2.16 KVM Video Driver* of SDK_User_Guide which available on +`github <https://github.com/AspeedTech-BMC/openbmc/releases/>`__. + +The ASPEED video driver implements the following driver-specific control: + +``V4L2_CID_ASPEED_HQ_MODE`` +--------------------------- + Enable/Disable ASPEED's High quality mode. This is a private control + that can be used to enable high quality for aspeed proprietary mode. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - ASPEED HQ mode is disabled. + * - ``(1)`` + - ASPEED HQ mode is enabled. + +``V4L2_CID_ASPEED_HQ_JPEG_QUALITY`` +----------------------------------- + Define the quality of ASPEED's High quality mode. This is a private control + that can be used to decide compression quality if High quality mode enabled + . Higher the value, better the quality and bigger the size. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(1)`` + - minimum + * - ``(12)`` + - maximum + * - ``(1)`` + - step + * - ``(1)`` + - default + +**Copyright** |copy| 2022 ASPEED Technology Inc. diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst new file mode 100644 index 000000000000..919a50e8b9d9 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _media_using_camera_sensor_drivers: + +Using camera sensor drivers +=========================== + +This section describes common practices for how the V4L2 sub-device interface is +used to control the camera sensor drivers. + +You may also find :ref:`media_writing_camera_sensor_drivers` useful. + +Frame size +---------- + +There are two distinct ways to configure the frame size produced by camera +sensors. + +Freely configurable camera sensor drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Freely configurable camera sensor drivers expose the device's internal +processing pipeline as one or more sub-devices with different cropping and +scaling configurations. The output size of the device is the result of a series +of cropping and scaling operations from the device's pixel array's size. + +An example of such a driver is the CCS driver. + +Register list based drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register list based drivers generally, instead of able to configure the device +they control based on user requests, are limited to a number of preset +configurations that combine a number of different parameters that on hardware +level are independent. How a driver picks such configuration is based on the +format set on a source pad at the end of the device's internal pipeline. + +Most sensor drivers are implemented this way. + +Frame interval configuration +---------------------------- + +There are two different methods for obtaining possibilities for different frame +intervals as well as configuring the frame interval. Which one to implement +depends on the type of the device. + +Raw camera sensors +~~~~~~~~~~~~~~~~~~ + +Instead of a high level parameter such as frame interval, the frame interval is +a result of the configuration of a number of camera sensor implementation +specific parameters. Luckily, these parameters tend to be the same for more or +less all modern raw camera sensors. + +The frame interval is calculated using the following equation:: + + frame interval = (analogue crop width + horizontal blanking) * + (analogue crop height + vertical blanking) / pixel rate + +The formula is bus independent and is applicable for raw timing parameters on +large variety of devices beyond camera sensors. Devices that have no analogue +crop, use the full source image size, i.e. pixel array size. + +Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and +``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control +is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in +the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same +sub-device. The unit of that control is pixels per second. + +Register list based drivers need to implement read-only sub-device nodes for the +purpose. Devices that are not register list based need these to configure the +device's internal processing pipeline. + +The first entity in the linear pipeline is the pixel array. The pixel array may +be followed by other entities that are there to allow configuring binning, +skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION +<VIDIOC_SUBDEV_G_SELECTION>`. + +USB cameras etc. devices +~~~~~~~~~~~~~~~~~~~~~~~~ + +USB video class hardware, as well as many cameras offering a similar higher +level interface natively, generally use the concept of frame interval (or frame +rate) on device level in firmware or hardware. This means lower level controls +implemented by raw cameras may not be used on uAPI (or even kAPI) to control the +frame interval on these devices. + +Rotation, orientation and flipping +---------------------------------- + +Some systems have the camera sensor mounted upside down compared to its natural +mounting rotation. In such cases, drivers shall expose the information to +userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION +<v4l2-camera-sensor-rotation>` control. + +Sensor drivers shall also report the sensor's mounting orientation with the +:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. + +Sensor drivers that have any vertical or horizontal flips embedded in the +register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP +<v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the +values programmed by the register sequences. The default values of these +controls shall be 0 (disabled). Especially these controls shall not be inverted, +independently of the sensor's mounting rotation. diff --git a/Documentation/userspace-api/media/drivers/ccs.rst b/Documentation/userspace-api/media/drivers/ccs.rst index 161cb65f4d98..03015b33d5ab 100644 --- a/Documentation/userspace-api/media/drivers/ccs.rst +++ b/Documentation/userspace-api/media/drivers/ccs.rst @@ -2,6 +2,8 @@ .. include:: <isonum.txt> +.. _media-ccs-uapi: + MIPI CCS camera sensor driver ============================= @@ -13,6 +15,8 @@ the binner and the scaler. As the capabilities of individual devices vary, the driver exposes interfaces based on the capabilities that exist in hardware. +Also see :ref:`the CCS driver kernel documentation <media-ccs-driver>`. + Pixel Array sub-device ---------------------- @@ -30,7 +34,7 @@ that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the sink pad (0). Additionally, if a device has no scaler or digital crop functionality, the -source pad (1) expses another digital crop selection rectangle that can only +source pad (1) exposes another digital crop selection rectangle that can only crop at the end of the lines and frames. Scaler diff --git a/Documentation/userspace-api/media/drivers/dw100.rst b/Documentation/userspace-api/media/drivers/dw100.rst new file mode 100644 index 000000000000..fceea6ece622 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/dw100.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +DW100 dewarp driver +=================== + +The Vivante DW100 Dewarp Processor IP core found on i.MX8MP SoC applies a +programmable geometrical transformation on the input image to correct distortion +introduced by lenses. + +The transformation function is exposed by the hardware as a grid map with 16x16 +pixel macroblocks indexed using X, Y vertex coordinates. +:: + + Image width + <---------------------------------------> + + ^ .-------.-------.-------.-------.-------. + | | 16x16 | | | | | + I | | pixel | | | | | + m | | block | | | | | + a | .-------.-------.-------.-------.-------. + g | | | | | | | + e | | | | | | | + | | | | | | | + h | .-------.-------.-------.-------.-------. + e | | | | | | | + i | | | | | | | + g | | | | | | | + h | .-------.-------.-------.-------.-------. + t | | | | | | | + | | | | | | | + | | | | | | | + v '-------'-------'-------'-------'-------' + + Grid of Image Blocks for Dewarping Map + + +Each x, y coordinate register uses 16 bits to record the coordinate address in +an unsigned 12.4 fixed point format (UQ12.4). +:: + + .----------------------.--------..----------------------.--------. + | 31~20 | 19~16 || 15~4 | 3~0 | + | (integer) | (frac) || (integer) | (frac) | + '----------------------'--------''----------------------'--------' + <-------------------------------><-------------------------------> + Y coordinate X coordinate + + Remap Register Layout + +The dewarping map is set from applications using the +V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP control. The control contains +an array of u32 values storing (x, y) destination coordinates for each +vertex of the grid. The x coordinate is stored in the 16 LSBs and the y +coordinate in the 16 MSBs. + +The number of elements in the array must match the image size: + +.. code-block:: C + + elems = (DIV_ROUND_UP(width, 16) + 1) * (DIV_ROUND_UP(height, 16) + 1); + +If the control has not been set by the application, the driver uses an identity +map. + +More details on the DW100 hardware operations can be found in +*chapter 13.15 DeWarp* of IMX8MP_ reference manual. + +The Vivante DW100 m2m driver implements the following driver-specific control: + +``V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP (__u32 array)`` + Specifies to DW100 driver its dewarping map (aka LUT) blob as described in + *chapter 13.15.2.3 Dewarping Remap* of IMX8MP_ reference manual as an U32 + dynamic array. The image is divided into many small 16x16 blocks. If the + width/height of the image is not divisible by 16, the size of the + rightmost/bottommost block is the remainder. The dewarping map only saves + the vertex coordinates of the block. The dewarping grid map is comprised of + vertex coordinates for x and y. Each x, y coordinate register uses 16 bits + (UQ12.4) to record the coordinate address, with the Y coordinate in the + upper bits and X in the lower bits. The driver modifies the dimensions of + this control when the sink format is changed, to reflect the new input + resolution. + +.. _IMX8MP: https://www.nxp.com/webapp/Download?colCode=IMX8MPRM diff --git a/Documentation/userspace-api/media/drivers/hantro.rst b/Documentation/userspace-api/media/drivers/hantro.rst deleted file mode 100644 index cd9754b4e005..000000000000 --- a/Documentation/userspace-api/media/drivers/hantro.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Hantro video decoder driver -=========================== - -The Hantro video decoder driver implements the following driver-specific controls: - -``V4L2_CID_HANTRO_HEVC_SLICE_HEADER_SKIP (integer)`` - Specifies to Hantro HEVC video decoder driver the number of data (in bits) to - skip in the slice segment header. - If non-IDR, the bits to be skipped go from syntax element "pic_output_flag" - to before syntax element "slice_temporal_mvp_enabled_flag". - If IDR, the skipped bits are just "pic_output_flag" - (separate_colour_plane_flag is not supported). - -.. note:: - - This control is not yet part of the public kernel API and - it is expected to change. diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 12e3c512d718..2252063593bf 100644 --- a/Documentation/userspace-api/media/drivers/index.rst +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -21,21 +21,20 @@ more details. For more details see the file COPYING in the source distribution of Linux. -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: + aspeed-video + camera-sensor ccs cx2341x-uapi - hantro + dw100 imx-uapi max2175 - meye-uapi + npcm-video omap3isp-uapi + st-vgxy61 + thp7312 uvcvideo diff --git a/Documentation/userspace-api/media/drivers/meye-uapi.rst b/Documentation/userspace-api/media/drivers/meye-uapi.rst deleted file mode 100644 index 66b1c142f920..000000000000 --- a/Documentation/userspace-api/media/drivers/meye-uapi.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: <isonum.txt> - -Vaio Picturebook Motion Eye Camera Driver -========================================= - -Copyright |copy| 2001-2004 Stelian Pop <stelian@popies.net> - -Copyright |copy| 2001-2002 Alcôve <www.alcove.com> - -Copyright |copy| 2000 Andrew Tridgell <tridge@samba.org> - -Private API ------------ - -The driver supports frame grabbing with the video4linux API, -so all video4linux tools (like xawtv) should work with this driver. - -Besides the video4linux interface, the driver has a private interface -for accessing the Motion Eye extended parameters (camera sharpness, -agc, video framerate), the snapshot and the MJPEG capture facilities. - -This interface consists of several ioctls (prototypes and structures -can be found in include/linux/meye.h): - -MEYEIOC_G_PARAMS and MEYEIOC_S_PARAMS - Get and set the extended parameters of the motion eye camera. - The user should always query the current parameters with - MEYEIOC_G_PARAMS, change what he likes and then issue the - MEYEIOC_S_PARAMS call (checking for -EINVAL). The extended - parameters are described by the meye_params structure. - - -MEYEIOC_QBUF_CAPT - Queue a buffer for capture (the buffers must have been - obtained with a VIDIOCGMBUF call and mmap'ed by the - application). The argument to MEYEIOC_QBUF_CAPT is the - buffer number to queue (or -1 to end capture). The first - call to MEYEIOC_QBUF_CAPT starts the streaming capture. - -MEYEIOC_SYNC - Takes as an argument the buffer number you want to sync. - This ioctl blocks until the buffer is filled and ready - for the application to use. It returns the buffer size. - -MEYEIOC_STILLCAPT and MEYEIOC_STILLJCAPT - Takes a snapshot in an uncompressed or compressed jpeg format. - This ioctl blocks until the snapshot is done and returns (for - jpeg snapshot) the size of the image. The image data is - available from the first mmap'ed buffer. - -Look at the 'motioneye' application code for an actual example. diff --git a/Documentation/userspace-api/media/drivers/npcm-video.rst b/Documentation/userspace-api/media/drivers/npcm-video.rst new file mode 100644 index 000000000000..b47771dd8b27 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/npcm-video.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +NPCM video driver +================= + +This driver is used to control the Video Capture/Differentiation (VCD) engine +and Encoding Compression Engine (ECE) present on Nuvoton NPCM SoCs. The VCD can +capture a frame from digital video input and compare two frames in memory, and +the ECE can compress the frame data into HEXTILE format. + +Driver-specific Controls +------------------------ + +V4L2_CID_NPCM_CAPTURE_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The VCD engine supports two modes: + +- COMPLETE mode: + + Capture the next complete frame into memory. + +- DIFF mode: + + Compare the incoming frame with the frame stored in memory, and updates the + differentiated frame in memory. + +Application can use ``V4L2_CID_NPCM_CAPTURE_MODE`` control to set the VCD mode +with different control values (enum v4l2_npcm_capture_mode): + +- ``V4L2_NPCM_CAPTURE_MODE_COMPLETE``: will set VCD to COMPLETE mode. +- ``V4L2_NPCM_CAPTURE_MODE_DIFF``: will set VCD to DIFF mode. + +V4L2_CID_NPCM_RECT_COUNT +~~~~~~~~~~~~~~~~~~~~~~~~ + +If using V4L2_PIX_FMT_HEXTILE format, VCD will capture frame data and then ECE +will compress the data into HEXTILE rectangles and store them in V4L2 video +buffer with the layout defined in Remote Framebuffer Protocol: +:: + + (RFC 6143, https://www.rfc-editor.org/rfc/rfc6143.html#section-7.6.1) + + +--------------+--------------+-------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------------+ + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + | 4 | S32 | encoding-type (5) | + +--------------+--------------+-------------------+ + | HEXTILE rectangle data | + +-------------------------------------------------+ + +Application can get the video buffer through VIDIOC_DQBUF, and followed by +calling ``V4L2_CID_NPCM_RECT_COUNT`` control to get the number of HEXTILE +rectangles in this buffer. + +References +---------- +include/uapi/linux/npcm-video.h + +**Copyright** |copy| 2022 Nuvoton Technologies diff --git a/Documentation/userspace-api/media/drivers/st-vgxy61.rst b/Documentation/userspace-api/media/drivers/st-vgxy61.rst new file mode 100644 index 000000000000..17ac15afa77c --- /dev/null +++ b/Documentation/userspace-api/media/drivers/st-vgxy61.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +ST VGXY61 camera sensor driver +============================== + +The ST VGXY61 driver implements the following controls: + +``V4L2_CID_HDR_SENSOR_MODE`` +------------------------------- + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - HDR linearize + - The merger outputs a long exposure capture as long as it is not + saturated. + * - HDR subtraction + - This involves subtracting the short exposure frame from the long + exposure frame. + * - No HDR + - This mode is used for standard dynamic range (SDR) exposures. diff --git a/Documentation/userspace-api/media/drivers/thp7312.rst b/Documentation/userspace-api/media/drivers/thp7312.rst new file mode 100644 index 000000000000..7c777e6fb7d2 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/thp7312.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +THine THP7312 ISP driver +======================== + +The THP7312 driver implements the following driver-specific controls: + +``V4L2_CID_THP7312_LOW_LIGHT_COMPENSATION`` + Enable/Disable auto-adjustment, based on lighting conditions, of the frame + rate when auto-exposure is enabled. + +``V4L2_CID_THP7312_AUTO_FOCUS_METHOD`` + Set method of auto-focus. Only takes effect when auto-focus is enabled. + + .. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``0`` + - Contrast-based auto-focus + * - ``1`` + - PDAF + * - ``2`` + - Hybrid of contrast-based and PDAF + + Supported values for the control depend on the camera sensor module + connected to the THP7312. If the module doesn't have a focus lens actuator, + this control will not be exposed by the THP7312 driver. If the module has a + controllable focus lens but the sensor doesn't support PDAF, only the + contrast-based auto-focus value will be valid. Otherwise all values for the + controls will be supported. + +``V4L2_CID_THP7312_NOISE_REDUCTION_AUTO`` + Enable/Disable auto noise reduction. + +``V4L2_CID_THP7312_NOISE_REDUCTION_ABSOLUTE`` + Set the noise reduction strength, where 0 is the weakest and 10 is the + strongest. diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst index 1dda69343f34..4ac0c1bc54ca 100644 --- a/Documentation/userspace-api/media/dvb/dvbapi.rst +++ b/Documentation/userspace-api/media/dvb/dvbapi.rst @@ -27,13 +27,8 @@ Part II - Digital TV API **Version 5.10** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst index ecd84a8790a2..1717a0565fe8 100644 --- a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst +++ b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst @@ -89,16 +89,21 @@ ATSC (version 1) 8-VSB and 16-VSB. DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. DVB-C Annex B 64-QAM. +DVB-C2 QPSK, 16-QAM, 64-QAM, 256-QAM, 1024-QAM and 4096-QAM. DVB-T QPSK, 16-QAM and 64-QAM. DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. DVB-S No need to set. It supports only QPSK. DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. +DVB-S2X 8-APSK-L, 16-APSK-L, 32-APSK-L, 64-APSK and 64-APSK-L. ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. ISDB-S 8-PSK, QPSK and BPSK. ======================= ======================================================= .. note:: + As DVB-S2X specifies extensions to the DVB-S2 standard, the same + delivery system enum value is used (SYS_DVBS2). + Please notice that some of the above modulation types may not be defined currently at the Kernel. The reason is simple: no driver needed such definition yet. @@ -854,9 +859,10 @@ The acceptable values are defined by :c:type:`fe_guard_interval`. #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the hardware will try to find the correct guard interval (if capable) and will use TMCC to fill in the missing parameters. - #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` - and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at - present. + #. Interval ``GUARD_INTERVAL_1_64`` is used only for DVB-C2. + #. Interval ``GUARD_INTERVAL_1_128`` is used for both DVB-C2 and DVB_T2. + #. Intervals ``GUARD_INTERVAL_19_128`` and ``GUARD_INTERVAL_19_256`` are + used only for DVB-T2. #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` @@ -916,14 +922,15 @@ The acceptable values are defined by :c:type:`fe_hierarchy`. DTV_STREAM_ID ============= -Used on DVB-S2, DVB-T2 and ISDB-S. +Used on DVB-C2, DVB-S2, DVB-T2 and ISDB-S. -DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on -a single transport stream. This property enables the digital TV driver to -handle substream filtering, when supported by the hardware. By default, -substream filtering is disabled. +DVB-C2, DVB-S2, DVB-T2 and ISDB-S support the transmission of several +streams on a single transport stream. This property enables the digital +TV driver to handle substream filtering, when supported by the hardware. +By default, substream filtering is disabled. -For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. +For DVB-C2, DVB-S2 and DVB-T2, the valid substream id range is from 0 to +255. For ISDB, the valid substream id range is from 1 to 65535. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst index b97d56ee543c..ffe8325749e5 100644 --- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst @@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc. :maxdepth: 1 frontend_legacy_dvbv3_api + legacy_dvb_decoder_api diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst new file mode 100644 index 000000000000..b46fe2becd02 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst @@ -0,0 +1,1642 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.audio + +.. _dvb_audio: + +================ +DVB Audio Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB audio device controls the MPEG2 audio decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/audio.h`` in your application. + +Please note that most DVB cards don’t have their own MPEG decoder, which +results in the omission of the audio and video device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers! + + +Audio Data Types +================ + +This section describes the structures, data types and defines used when +talking to the audio device. + + +----- + + +audio_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_stream_source_t + +.. code-block:: c + + typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY + } audio_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_SOURCE_DEMUX`` + + - :cspan:`1` Selects the demultiplexer (fed either by the frontend + or the DVR device) as the source of the video stream. + + - .. + + - ``AUDIO_SOURCE_MEMORY`` + + - Selects the stream from the application that comes through + the `write()`_ system call. + +Description +~~~~~~~~~~~ + +The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demux) or external (user write) source. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +----- + + +audio_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_play_state_t + +.. code-block:: c + + typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED + } audio_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STOPPED`` + + - Audio is stopped. + + - .. + + - ``AUDIO_PLAYING`` + + - Audio is currently playing. + + - .. + + - ``AUDIO_PAUSE`` + + - Audio is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `AUDIO_GET_STATUS`_ call +representing the state of audio playback. + + +----- + + +audio_channel_select_t +---------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_channel_select_t + +.. code-block:: c + + typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, + AUDIO_MONO, + AUDIO_STEREO_SWAPPED + } audio_channel_select_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STEREO`` + + - Stereo. + + - .. + + - ``AUDIO_MONO_LEFT`` + + - Mono, select left stereo channel as source. + + - .. + + - ``AUDIO_MONO_RIGHT`` + + - Mono, select right stereo channel as source. + + - .. + + - ``AUDIO_MONO`` + + - Mono source only. + + - .. + + - ``AUDIO_STEREO_SWAPPED`` + + - Stereo, swap L & R. + +Description +~~~~~~~~~~~ + +The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by +this values. + + +----- + + +audio_mixer_t +------------- + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_mixer + +.. code-block:: c + + typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; + } audio_mixer_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``unsigned int volume_left`` + + - Volume left channel. + Valid range: 0 ... 255 + + - .. + + - ``unsigned int volume_right`` + + - Volume right channel. + Valid range: 0 ... 255 + +Description +~~~~~~~~~~~ + +This structure is used by the `AUDIO_SET_MIXER`_ call to set the +audio volume. + + +----- + + +audio_status +------------ + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_status + +.. code-block:: c + + typedef struct audio_status { + int AV_sync_state; + int mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + int bypass_mode; + audio_mixer_t mixer_state; + } audio_status_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int AV_sync_state`` + + - :cspan:`1` Shows if A/V synchronization is ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + + - .. + + - :rspan:`2` ``int mute_state`` + + - :cspan:`1` Indicates if audio is muted or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + + - .. + + - `audio_play_state_t`_ ``play_state`` + + - Current playback state. + + - .. + + - `audio_stream_source_t`_ ``stream_source`` + + - Current source of the data. + + - .. + + - :rspan:`2` ``int bypass_mode`` + + - :cspan:`1` Is the decoding of the current Audio stream in + the DVB subsystem enabled or disabled. + + - .. + + - TRUE ( != 0 ) + + - Bypass disabled. + + - .. + + - FALSE ( == 0 ) + + - Bypass enabled. + + - .. + + - `audio_mixer_t`_ ``mixer_state`` + + - Current volume settings. + +Description +~~~~~~~~~~~ + +The `AUDIO_GET_STATUS`_ call returns this structure as information +about various states of the playback operation. + + +----- + + +audio encodings +--------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define AUDIO_CAP_DTS 1 + #define AUDIO_CAP_LPCM 2 + #define AUDIO_CAP_MP1 4 + #define AUDIO_CAP_MP2 8 + #define AUDIO_CAP_MP3 16 + #define AUDIO_CAP_AAC 32 + #define AUDIO_CAP_OGG 64 + #define AUDIO_CAP_SDDS 128 + #define AUDIO_CAP_AC3 256 + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_CAP_DTS`` + + - :cspan:`1` The hardware accepts DTS audio tracks. + + - .. + + - ``AUDIO_CAP_LPCM`` + + - The hardware accepts uncompressed audio with + Linear Pulse-Code Modulation (LPCM) + + - .. + + - ``AUDIO_CAP_MP1`` + + - The hardware accepts MPEG-1 Audio Layer 1. + + - .. + + - ``AUDIO_CAP_MP2`` + + - The hardware accepts MPEG-1 Audio Layer 2. + Also known as MUSICAM. + + - .. + + - ``AUDIO_CAP_MP3`` + + - The hardware accepts MPEG-1 Audio Layer III. + Commomly known as .mp3. + + - .. + + - ``AUDIO_CAP_AAC`` + + - The hardware accepts AAC (Advanced Audio Coding). + + - .. + + - ``AUDIO_CAP_OGG`` + + - The hardware accepts Vorbis audio tracks. + + - .. + + - ``AUDIO_CAP_SDDS`` + + - The hardware accepts Sony Dynamic Digital Sound (SDDS). + + - .. + + - ``AUDIO_CAP_AC3`` + + - The hardware accepts Dolby Digital ATSC A/52 audio. + Also known as AC-3. + +Description +~~~~~~~~~~~ + +A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardwares capabilities. + + +----- + + +Audio Function Calls +==================== + + +AUDIO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_STOP + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_STOP) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_STOP`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to stop playing the current +stream. + +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. + + +----- + + +AUDIO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PLAY + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to start playing an audio stream +from the selected source. + +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. + + +----- + + +AUDIO_PAUSE +----------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PAUSE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PAUSE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_PAUSE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call suspends the audio stream being played. Decoding and +playing are paused. It is then possible to restart again decoding and +playing process of the audio stream using `AUDIO_CONTINUE`_ command. + +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. + + +----- + + +AUDIO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CONTINUE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl restarts the decoding and playing process previously paused +with `AUDIO_PAUSE`_ command. + +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. + + +----- + + +AUDIO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, + audio_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SELECT_SOURCE`` for this command. + + - .. + + - `audio_stream_source_t`_ ``source`` + + - Indicates the source that shall be used for the Audio stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call informs the audio device which source shall be used for +the input data. The possible sources are demux or memory. If +``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device +through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data +is directly transferred from the onboard demux-device to the decoder. +Note: This only supports DVB-devices with one demux and one decoder so far. + +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. + + +----- + + +AUDIO_SET_MUTE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MUTE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MUTE, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Indicates if audio device shall mute or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 :ref:`VIDIOC_DECODER_CMD` with the +``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. + +This ioctl call asks the audio device to mute the stream that is +currently being played. + +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. + + +----- + + +AUDIO_SET_AV_SYNC +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_AV_SYNC + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Tells the DVB subsystem if A/V synchronization + shall be ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to turn ON or OFF A/V +synchronization. + +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. + + +----- + + +AUDIO_SET_BYPASS_MODE +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_BYPASS_MODE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Enables or disables the decoding of the current + Audio stream in the DVB subsystem. + - .. + + - TRUE ( != 0 ) + + - Disable bypass + + - .. + + - FALSE ( == 0 ) + + - Enable bypass + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to bypass the Audio decoder and +forward the stream without decoding. This mode shall be used if streams +that can’t be handled by the DVB system shall be decoded. Dolby +DigitalTM streams are automatically forwarded by the DVB subsystem if +the hardware can handle it. + +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. + + +----- + + +AUDIO_CHANNEL_SELECT +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CHANNEL_SELECT`` for this command. + + - .. + + - `audio_channel_select_t`_ ``ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. + +This ioctl call asks the Audio Device to select the requested channel if +possible. + +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. + + +----- + + +AUDIO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_STATUS + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_STATUS, + struct audio_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals AUDIO_GET_STATUS for this command. + + - .. + + - ``struct`` `audio_status`_ ``*status`` + + - Returns the current state of Audio Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to return the current state of the +Audio Device. + +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. + + +----- + + +AUDIO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, + unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Returns a bit array of supported sound formats. + Bits are defined in `audio encodings`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to tell us about the decoding +capabilities of the audio hardware. + +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. + + +----- + + +AUDIO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to clear all software and hardware +buffers of the audio decoder device. + +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. + + +----- + + +AUDIO_SET_ID +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_ID + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_ID, int id) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_ID`` for this command. + + - .. + + - ``int id`` + + - Audio sub-stream id. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl selects which sub-stream is to be decoded if a program or +system stream is sent to the video device. + +If no audio stream type is set the id has to be in range [0xC0,0xDF] +for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM. +See ITU-T H.222.0 | ISO/IEC 13818-1 for further description. + +If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the +id just the sub-stream id of the audio stream and only the first 5 bits +(& 0x1F) are recognized. + +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. + + +----- + + +AUDIO_SET_MIXER +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MIXER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_MIXER`` for this command. + + - .. + + - ``audio_mixer_t *mix`` + + - Mixer settings. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl lets you adjust the mixer settings of the audio decoder. + +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. + + +----- + + +AUDIO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of audio stream to expect. This +is useful if the stream offers several audio sub-streams like LPCM and +AC3. + +Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used. + + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EINVAL`` + + - Type is not a valid or supported stream type. + + +----- + + +AUDIO_BILINGUAL_CHANNEL_SELECT +------------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command. + + - .. + + - ``audio_channel_select_t ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl has been replaced by the V4L2 +``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control +for MPEG decoders controlled through V4L2. + +This ioctl call asks the Audio Device to select the requested channel +for bilingual streams if possible. + +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. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific audio device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named audio device (e.g. +``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has +succeeded, the device will be ready for use. The significance of +blocking or non-blocking mode is described in the documentation for +functions where there is a difference. It does not affect the semantics +of the open() call itself. A device opened in blocking mode can later be +put into non-blocking mode (and vice versa) using the F_SETFL command +of the fcntl system call. This is a standard system call, documented in +the Linux manual page for fcntl. Only one user can open the Audio Device +in O_RDWR mode. All other attempts to open the device in this mode will +fail, and an error code will be returned. If the Audio Device is opened +in O_RDONLY mode, the only ioctl call that can be used is +`AUDIO_GET_STATUS`_. All other call will return with an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened audio device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected +in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in +PES format. If ``O_NONBLOCK`` is not specified the function will block +until buffer space is available. The amount of data to be transferred is +implied by count. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst new file mode 100644 index 000000000000..f58985a6e63c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. _legacy_dvb_decoder_api: + +============================ +Legacy DVB MPEG Decoder APIs +============================ + +.. _legacy_dvb_decoder_notes: + +General Notes +============= + +This API has originally been designed for DVB only and is therefore limited to +the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems. + +To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has +been designed. Which replaces this part of the DVB API. + +Nevertheless there have been projects build around this API. +To ensure compatibility this API is kept as it is. + +.. attention:: Do **not** use this API in new drivers! + + For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs. + + Pipelines should be set up using the :ref:`Media Controller API<media_controller>`. + +Practically the decoders seem to be treated differently. The application typically +knows which decoder is in use or it is specially written for one decoder type. +Querying capabilities are rarely used because they are already known. + + +.. _legacy_dvb_decoder_formats: + +Data Formats +============ + +The API has been designed for DVB and compatible broadcastsystems. +Because of that fact the only supported data formats are ISO/IEC 13818-1 +compatible MPEG streams. The supported payloads may vary depending on the +used decoder. + +Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 / +ISO/IEC 13818-1, if not otherwise noted. + +For storing recordings typically TS streams are used, in lesser extent PES. +Both variants are commonly accepted for playback, but it may be driver dependent. + + + + +Table of Contents +================= + +.. toctree:: + :maxdepth: 2 + + legacy_dvb_video + legacy_dvb_audio + legacy_dvb_osd diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst new file mode 100644 index 000000000000..179b66a8016a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst @@ -0,0 +1,883 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.osd + +.. _dvb_osd: + +============== +DVB OSD Device +============== + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB OSD device controls the OnScreen-Display of the AV7110 based +DVB-cards with hardware MPEG2 decoder. It can be accessed through +``/dev/dvb/adapter?/osd0``. +Data types and ioctl definitions can be accessed by including +``linux/dvb/osd.h`` in your application. + +The OSD is not a frame-buffer like on many other cards. +It is a kind of canvas one can draw on. +The color-depth is limited depending on the memory size installed. +An appropriate palette of colors has to be set up. +The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ +ioctl. + +OSD Data Types +============== + +OSD_Command +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + /* All functions return -2 on "not open" */ + OSD_Close = 1, + OSD_Open, + OSD_Show, + OSD_Hide, + OSD_Clear, + OSD_Fill, + OSD_SetColor, + OSD_SetPalette, + OSD_SetTrans, + OSD_SetPixel, + OSD_GetPixel, + OSD_SetRow, + OSD_SetBlock, + OSD_FillRow, + OSD_FillBlock, + OSD_Line, + OSD_Query, + OSD_Test, + OSD_Text, + OSD_SetWindow, + OSD_MoveWindow, + OSD_OpenRaw, + } OSD_Command; + +Commands +~~~~~~~~ + +.. note:: All functions return -2 on "not open" + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Command + + - | Used variables of ``struct`` `osd_cmd_t`_. + | Usage{variable} if alternative use. + + - :cspan:`2` Description + + + + - .. + + - ``OSD_Close`` + + - - + + - | Disables OSD and releases the buffers. + | Returns 0 on success. + + - .. + + - ``OSD_Open`` + + - | x0,y0,x1,y1, + | BitPerPixel[2/4/8]{color&0x0F}, + | mix[0..15]{color&0xF0} + + - | Opens OSD with this size and bit depth + | Returns 0 on success, + | -1 on DRAM allocation error, + | -2 on "already open". + + - .. + + - ``OSD_Show`` + + - - + + - | Enables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Hide`` + + - - + + - | Disables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Clear`` + + - - + + - | Sets all pixel to color 0. + | Returns 0 on success. + + - .. + + - ``OSD_Fill`` + + - color + + - | Sets all pixel to color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_SetColor`` + + - | color, + | R{x0},G{y0},B{x1}, + | opacity{y1} + + - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply + | R,G,B: 0..255 + | R=Red, G=Green, B=Blue + | opacity=0: pixel opacity 0% (only video pixel shows) + | opacity=1..254: pixel opacity as specified in header + | opacity=255: pixel opacity 100% (only OSD pixel shows) + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_SetPalette`` + + - | firstcolor{color}, + | lastcolor{x0},data + + - | Set a number of entries in the palette. + | Sets the entries "firstcolor" through "lastcolor" from the + array "data". + | Data has 4 byte for each color: + | R,G,B, and a opacity value: 0->transparent, 1..254->mix, + 255->pixel + + - .. + + - ``OSD_SetTrans`` + + - transparency{color} + + - | Sets transparency of mixed pixel (0..15). + | Returns 0 on success. + + - .. + + - ``OSD_SetPixel`` + + - x0,y0,color + + - | Sets pixel <x>,<y> to color number <color>. + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_GetPixel`` + + - x0,y0 + + - | Returns color number of pixel <x>,<y>, or -1. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_SetRow`` + + - x0,y0,x1,data + + - | Fills pixels x0,y through x1,y with the content of data[]. + | Returns 0 on success, -1 on clipping all pixel (no pixel + drawn). + + - .. + + - ``OSD_SetBlock`` + + - | x0,y0,x1,y1, + | increment{color}, + | data + + - | Fills pixels x0,y0 through x1,y1 with the content of data[]. + | Inc contains the width of one line in the data block, + | inc<=0 uses block width as line width. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillRow`` + + - x0,y0,x1,color + + - | Fills pixels x0,y through x1,y with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillBlock`` + + - x0,y0,x1,y1,color + + - | Fills pixels x0,y0 through x1,y1 with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_Line`` + + - x0,y0,x1,y1,color + + - | Draw a line from x0,y0 to x1,y1 with the color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_Query`` + + - | x0,y0,x1,y1, + | xasp{color}; yasp=11 + + - | Fills parameters with the picture dimensions and the pixel + aspect ratio. + | Returns 0 on success. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_Test`` + + - - + + - | Draws a test picture. + | For debugging purposes only. + | Returns 0 on success. + - .. + + - ``OSD_Text`` + + - x0,y0,size,color,text + + - Draws a text at position x0,y0 with the color <color>. + + - .. + + - ``OSD_SetWindow`` + + - x0 + + - Set window with number 0<x0<8 as current. + + - .. + + - ``OSD_MoveWindow`` + + - x0,y0 + + - Move current window to (x0, y0). + + - .. + + - ``OSD_OpenRaw`` + + - | x0,y0,x1,y1, + | `osd_raw_window_t`_ {color} + + - Open other types of OSD windows. + +Description +~~~~~~~~~~~ + +The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to +tell the driver which OSD_Command to execute. + + +----- + +osd_cmd_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cmd_s { + OSD_Command cmd; + int x0; + int y0; + int x1; + int y1; + int color; + void __user *data; + } osd_cmd_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_Command cmd`` + + - `OSD_Command`_ to be executed. + + - .. + + - ``int x0`` + + - First horizontal position. + + - .. + + - ``int y0`` + + - First vertical position. + + - .. + + - ``int x1`` + + - Second horizontal position. + + - .. + + - ``int y1`` + + - Second vertical position. + + - .. + + - ``int color`` + + - Number of the color in the palette. + + - .. + + - ``void __user *data`` + + - Command specific Data. + +Description +~~~~~~~~~~~ + +The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl. +It contains the data for the OSD_Command and the `OSD_Command`_ itself. +The structure has to be passed to the driver and the components may be +modified by it. + + +----- + + +osd_raw_window_t +---------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + OSD_BITMAP1, + OSD_BITMAP2, + OSD_BITMAP4, + OSD_BITMAP8, + OSD_BITMAP1HR, + OSD_BITMAP2HR, + OSD_BITMAP4HR, + OSD_BITMAP8HR, + OSD_YCRCB422, + OSD_YCRCB444, + OSD_YCRCB444HR, + OSD_VIDEOTSIZE, + OSD_VIDEOHSIZE, + OSD_VIDEOQSIZE, + OSD_VIDEODSIZE, + OSD_VIDEOTHSIZE, + OSD_VIDEOTQSIZE, + OSD_VIDEOTDSIZE, + OSD_VIDEONSIZE, + OSD_CURSOR + } osd_raw_window_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_BITMAP1`` + + - :cspan:`1` 1 bit bitmap + + - .. + + - ``OSD_BITMAP2`` + + - 2 bit bitmap + + - .. + + - ``OSD_BITMAP4`` + + - 4 bit bitmap + + - .. + + - ``OSD_BITMAP8`` + + - 8 bit bitmap + + - .. + + - ``OSD_BITMAP1HR`` + + - 1 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP2HR`` + + - 2 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP4HR`` + + - 4 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP8HR`` + + - 8 Bit bitmap half resolution + + - .. + + - ``OSD_YCRCB422`` + + - 4:2:2 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444`` + + - 4:4:4 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444HR`` + + - 4:4:4 YCRCB graphic half resolution + + - .. + + - ``OSD_VIDEOTSIZE`` + + - True Size Normal MPEG Video Display + + - .. + + - ``OSD_VIDEOHSIZE`` + + - MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOQSIZE`` + + - MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEODSIZE`` + + - MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEOTHSIZE`` + + - True Size MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOTQSIZE`` + + - True Size MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEOTDSIZE`` + + - True Size MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEONSIZE`` + + - Full Size MPEG Video Display + + - .. + + - ``OSD_CURSOR`` + + - Cursor + +Description +~~~~~~~~~~~ + +The ``osd_raw_window_t`` data type is used with the `OSD_Command`_ +OSD_OpenRaw to tell the driver which type of OSD to open. + + +----- + + +osd_cap_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cap_s { + int cmd; + #define OSD_CAP_MEMSIZE 1 + long val; + } osd_cap_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int cmd`` + + - Capability to query. + + - .. + + - ``long val`` + + - Used to store the Data. + +Supported capabilities +~~~~~~~~~~~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_CAP_MEMSIZE`` + + - Memory size installed on the card. + +Description +~~~~~~~~~~~ + +This structure of data used with the `OSD_GET_CAPABILITY`_ call. + + +----- + + +OSD Function Calls +================== + +OSD_SEND_CMD +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_SEND_CMD + +.. code-block:: c + + int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd) + + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Pointer to the location of the structure `osd_cmd_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sends the `OSD_Command`_ to the card. + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EINVAL`` + + - Command is out of range. + + +----- + + +OSD_GET_CAPABILITY +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_GET_CAPABILITY + +.. code-block:: c + + int ioctl(int fd, int request = OSD_GET_CAPABILITY, + struct osd_cap_t *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``OSD_GET_CAPABILITY`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to the location of the structure `osd_cap_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is used to get the capabilities of the OSD of the AV7110 based +DVB-decoder-card in use. + +.. note:: + The structure osd_cap_t has to be setup by the user and passed to the + driver. + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. + + - ``EINVAL`` + + - Unsupported capability. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific OSD device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named OSD device (e.g. +``/dev/dvb/adapter?/osd0``) for subsequent use. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_ . + +Description +~~~~~~~~~~~ + +This system call closes a previously opened OSD device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst new file mode 100644 index 000000000000..b9fd5cadae24 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst @@ -0,0 +1,2430 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.video + +.. _dvb_video: + +================ +DVB Video Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB video device controls the MPEG2 video decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/video.h`` in your application. + +Note that the DVB video device only controls decoding of the MPEG video +stream, not its presentation on the TV or computer screen. On PCs this +is typically handled by an associated video4linux device, e.g. +``/dev/video``, which allows scaling and defining output windows. + +Most DVB cards don’t have their own MPEG decoder, which results in the +omission of the audio and video device as well as the video4linux +device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<video>` for new drivers! + + +Video Data Types +================ + + + +video_format_t +-------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9, + VIDEO_FORMAT_221_1 + } video_format_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_FORMAT_4_3`` + + - Select 4:3 format. + + - .. + + - ``VIDEO_FORMAT_16_9`` + + - Select 16:9 format. + + - .. + + - ``VIDEO_FORMAT_221_1`` + + - Select 2.21:1 format. + +Description +~~~~~~~~~~~ + +The ``video_format_t`` data type +is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which +aspect ratio the output hardware (e.g. TV) has. It is also used in the +data structures `video_status`_ returned by `VIDEO_GET_STATUS`_ +and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report +about the display format of the current video stream. + + +----- + + +video_displayformat_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT + } video_displayformat_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_PAN_SCAN`` + + - Use pan and scan format. + + - .. + + - ``VIDEO_LETTER_BOX`` + + - Use letterbox format. + + - .. + + - ``VIDEO_CENTER_CUT_OUT`` + + - Use center cut out format. + +Description +~~~~~~~~~~~ + +In case the display format of the video stream and of the display +hardware differ the application has to specify how to handle the +cropping of the picture. This can be done using the +`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts this enum as argument. + + +----- + + +video_size_t +------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct { + int w; + int h; + video_format_t aspect_ratio; + } video_size_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int w`` + + - Video width in pixels. + + - .. + + - ``int h`` + + - Video height in pixels. + + - .. + + - `video_format_t`_ ``aspect_ratio`` + + - Aspect ratio. + +Description +~~~~~~~~~~~ + +Used in the struct `video_event`_. It stores the resolution and +aspect ratio of the video. + + +----- + + +video_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY + } video_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_SOURCE_DEMUX`` + + - :cspan:`1` Select the demux as the main source. + + - .. + + - ``VIDEO_SOURCE_MEMORY`` + + - If this source is selected, the stream + comes from the user through the write + system call. + +Description +~~~~~~~~~~~ + +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demuxer) or external (user write) source. +VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the +frontend or the DVR device) as the source of the video stream. If +VIDEO_SOURCE_MEMORY is selected the stream comes from the application +through the `write()`_ system call. + + +----- + + +video_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED + } video_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_STOPPED`` + + - Video is stopped. + + - .. + + - ``VIDEO_PLAYING`` + + - Video is currently playing. + + - .. + + - ``VIDEO_FREEZED`` + + - Video is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `VIDEO_GET_STATUS`_ call +representing the state of video playback. + + +----- + + +struct video_command +-------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_command { + __u32 cmd; + __u32 flags; + union { + struct { + __u64 pts; + } stop; + + struct { + __s32 speed; + __u32 format; + } play; + + struct { + __u32 data[16]; + } raw; + }; + }; + + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``__u32 cmd`` + + - `Decoder command`_ + + - .. + + - ``__u32 flags`` + + - Flags for the `Decoder command`_. + + - .. + + - ``struct stop`` + + - ``__u64 pts`` + + - MPEG PTS + + - .. + + - :rspan:`5` ``stuct play`` + + - :rspan:`4` ``__s32 speed`` + + - 0 or 1000 specifies normal speed, + + - .. + + - 1: specifies forward single stepping, + + - .. + + - -1: specifies backward single stepping, + + - .. + + - >1: playback at speed / 1000 of the normal speed + + - .. + + - <-1: reverse playback at ( -speed / 1000 ) of the normal speed. + + - .. + + - ``__u32 format`` + + - `Play input formats`_ + + - .. + + - ``__u32 data[16]`` + + - Reserved + +Description +~~~~~~~~~~~ + +The structure must be zeroed before use by the application. This ensures +it can be extended safely in the future. + + +----- + + +Predefined decoder commands and flags +------------------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CMD_PLAY (0) + #define VIDEO_CMD_STOP (1) + #define VIDEO_CMD_FREEZE (2) + #define VIDEO_CMD_CONTINUE (3) + + #define VIDEO_CMD_FREEZE_TO_BLACK (1 << 0) + + #define VIDEO_CMD_STOP_TO_BLACK (1 << 0) + #define VIDEO_CMD_STOP_IMMEDIATELY (1 << 1) + + #define VIDEO_PLAY_FMT_NONE (0) + #define VIDEO_PLAY_FMT_GOP (1) + + #define VIDEO_VSYNC_FIELD_UNKNOWN (0) + #define VIDEO_VSYNC_FIELD_ODD (1) + #define VIDEO_VSYNC_FIELD_EVEN (2) + #define VIDEO_VSYNC_FIELD_PROGRESSIVE (3) + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`3` _`Decoder command` + + - ``VIDEO_CMD_PLAY`` + + - Start playback. + + - .. + + - ``VIDEO_CMD_STOP`` + + - Stop playback. + + - .. + + - ``VIDEO_CMD_FREEZE`` + + - Freeze playback. + + - .. + + - ``VIDEO_CMD_CONTINUE`` + + - Continue playback after freeze. + + - .. + + - Flags for ``VIDEO_CMD_FREEZE`` + + - ``VIDEO_CMD_FREEZE_TO_BLACK`` + + - Show black picture on freeze. + + - .. + + - :rspan:`1` Flags for ``VIDEO_CMD_STOP`` + + - ``VIDEO_CMD_STOP_TO_BLACK`` + + - Show black picture on stop. + + - .. + + - ``VIDEO_CMD_STOP_IMMEDIATELY`` + + - Stop immediately, without emptying buffers. + + - .. + + - :rspan:`1` _`Play input formats` + + - ``VIDEO_PLAY_FMT_NONE`` + + - The decoder has no special format requirements + + - .. + + - ``VIDEO_PLAY_FMT_GOP`` + + - The decoder requires full GOPs + + - .. + + - :rspan:`3` Field order + + - ``VIDEO_VSYNC_FIELD_UNKNOWN`` + + - FIELD_UNKNOWN can be used if the hardware does not know + whether the Vsync is for an odd, even or progressive + (i.e. non-interlaced) field. + + - .. + + - ``VIDEO_VSYNC_FIELD_ODD`` + + - Vsync is for an odd field. + + - .. + + - ``VIDEO_VSYNC_FIELD_EVEN`` + + - Vsync is for an even field. + + - .. + + - ``VIDEO_VSYNC_FIELD_PROGRESSIVE`` + + - progressive (i.e. non-interlaced) + + +----- + + +video_event +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_event { + __s32 type; + #define VIDEO_EVENT_SIZE_CHANGED 1 + #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 + #define VIDEO_EVENT_DECODER_STOPPED 3 + #define VIDEO_EVENT_VSYNC 4 + long timestamp; + union { + video_size_t size; + unsigned int frame_rate; + unsigned char vsync_field; + } u; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`4` ``__s32 type`` + + - :cspan:`1` Event type. + + - .. + + - ``VIDEO_EVENT_SIZE_CHANGED`` + + - Size changed. + + - .. + + - ``VIDEO_EVENT_FRAME_RATE_CHANGED`` + + - Framerate changed. + + - .. + + - ``VIDEO_EVENT_DECODER_STOPPED`` + + - Decoder stopped. + + - .. + + - ``VIDEO_EVENT_VSYNC`` + + - Vsync occurred. + + - .. + + - ``long timestamp`` + + - :cspan:`1` MPEG PTS at occurrence. + + - .. + + - :rspan:`2` ``union u`` + + - `video_size_t`_ size + + - Resolution and aspect ratio of the video. + + - .. + + - ``unsigned int frame_rate`` + + - in frames per 1000sec + + - .. + + - ``unsigned char vsync_field`` + + - | unknown / odd / even / progressive + | See: `Predefined decoder commands and flags`_ + +Description +~~~~~~~~~~~ + +This is the structure of a video event as it is returned by the +`VIDEO_GET_EVENT`_ call. See there for more details. + + +----- + + +video_status +------------ + +Synopsis +~~~~~~~~ + +The `VIDEO_GET_STATUS`_ call returns the following structure informing +about various states of the playback operation. + +.. code-block:: c + + struct video_status { + int video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int video_blank`` + + - :cspan:`1` Show blank video on freeze? + + - .. + + - TRUE ( != 0 ) + + - Blank screen when freeze. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + + - .. + + - `video_play_state_t`_ ``play_state`` + + - Current state of playback. + + - .. + + - `video_stream_source_t`_ ``stream_source`` + + - Current source (demux/memory). + + - .. + + - `video_format_t`_ ``video_format`` + + - Current aspect ratio of stream. + + - .. + + - `video_displayformat_t`_ ``display_format`` + + - Applied cropping mode. + +Description +~~~~~~~~~~~ + +If ``video_blank`` is set ``TRUE`` video will be blanked out if the +channel is changed or if playback is stopped. Otherwise, the last picture +will be displayed. ``play_state`` indicates if the video is currently +frozen, stopped, or being played back. The ``stream_source`` corresponds +to the selected source for the video stream. It can come either from the +demultiplexer or from memory. The ``video_format`` indicates the aspect +ratio (one of 4:3 or 16:9) of the currently played video stream. +Finally, ``display_format`` corresponds to the applied cropping mode in +case the source video format is not the same as the format of the output +device. + + +----- + + +video_still_picture +------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_still_picture { + char *iFrame; + int32_t size; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``char *iFrame`` + + - Pointer to a single iframe in memory. + + - .. + + - ``int32_t size`` + + - Size of the iframe. + + +Description +~~~~~~~~~~~ + +An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on +within this structure. + + +----- + + +video capabilities +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CAP_MPEG1 1 + #define VIDEO_CAP_MPEG2 2 + #define VIDEO_CAP_SYS 4 + #define VIDEO_CAP_PROG 8 + +Constants +~~~~~~~~~ +Bit definitions for capabilities: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_CAP_MPEG1`` + + - :cspan:`1` The hardware can decode MPEG1. + + - .. + + - ``VIDEO_CAP_MPEG2`` + + - The hardware can decode MPEG2. + + - .. + + - ``VIDEO_CAP_SYS`` + + - The video device accepts system stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + + - .. + + - ``VIDEO_CAP_PROG`` + + - The video device accepts program stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + +Description +~~~~~~~~~~~ + +A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardware's capabilities. + + +----- + + +Video Function Calls +==================== + + +VIDEO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STOP + +.. code-block:: c + + int ioctl(fd, VIDEO_STOP, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_STOP`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates how the screen shall be handled. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to stop playing the current +stream. Depending on the input parameter, the screen can be blanked out +or displaying the last decoded frame. + +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. + + +----- + + +VIDEO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_PLAY + +.. code-block:: c + + int ioctl(fd, VIDEO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to start playing a video stream +from the selected source. + +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. + + +----- + + +VIDEO_FREEZE +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FREEZE + +.. code-block:: c + + int ioctl(fd, VIDEO_FREEZE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FREEZE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call suspends the live video stream being played, if +VIDEO_SOURCE_DEMUX is selected. Decoding and playing are frozen. +It is then possible to restart the decoding and playing process of the +video stream using the `VIDEO_CONTINUE`_ command. +If VIDEO_SOURCE_MEMORY is selected in the ioctl call +`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more +data until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed. + +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. + + +----- + + +VIDEO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CONTINUE + +.. code-block:: c + + int ioctl(fd, VIDEO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call restarts decoding and playing processes of the video +stream which was played before a call to `VIDEO_FREEZE`_ was made. + +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. + + +----- + + +VIDEO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SELECT_SOURCE`` for this command. + + - .. + + - `video_stream_source_t`_ ``source`` + + - Indicates which source shall be used for the Video stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. This ioctl was also supported +by the V4L2 ivtv driver, but that has been replaced by the ivtv-specific +``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. + +This ioctl call informs the video device which source shall be used for +the input data. The possible sources are demux or memory. If memory is +selected, the data is fed to the video device through the write command +using the struct `video_stream_source_t`_. If demux is selected, the data +is directly transferred from the onboard demux-device to the decoder. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +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. + + +----- + + +VIDEO_SET_BLANK +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_BLANK + +.. code-block:: c + + int ioctl(fd, VIDEO_SET_BLANK, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_SET_BLANK`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates if the screen shall be blanked. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to blank out the picture. + +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. + + +----- + + +VIDEO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_STATUS + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_STATUS, + struct video_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_STATUS`` for this command. + + - .. + + - ``struct`` `video_status`_ ``*status`` + + - Returns the current status of the Video Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to return the current status of +the device. + +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. + + +----- + + +VIDEO_GET_EVENT +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_EVENT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_EVENT, + struct video_event *ev) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_EVENT`` for this command. + + - .. + + - ``struct`` `video_event`_ ``*ev`` + + - Points to the location where the event, if any, is to be stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To get events from a V4L2 decoder +use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. + +This ioctl call returns an event of type `video_event`_ if available. A +certain number of the latest events will be cued and returned in order of +occurrence. Older events may be discarded if not fetched in time. If +an event is not available, the behavior depends on whether the device is +in blocking or non-blocking mode. In the latter case, the call fails +immediately with errno set to ``EWOULDBLOCK``. In the former case, the +call blocks until an event becomes available. The standard Linux poll() +and/or select() system calls can be used with the device file descriptor +to watch for new events. For select(), the file descriptor should be +included in the exceptfds argument, and for poll(), POLLPRI should be +specified as the wake-up condition. Read-only permissions are sufficient +for this ioctl call. + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EWOULDBLOCK`` + + - :cspan:`1` There is no event pending, and the device is in + non-blocking mode. + + - .. + + - ``EOVERFLOW`` + + - Overflow in event queue - one or more events were lost. + + +----- + + +VIDEO_SET_DISPLAY_FORMAT +------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_DISPLAY_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, + video_display_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_DISPLAY_FORMAT`` for this command. + + - .. + + - `video_displayformat_t`_ ``format`` + + - Selects the video format to be used. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to select the video format to be +applied by the MPEG chip on the video. + +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. + + +----- + + +VIDEO_STILLPICTURE +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STILLPICTURE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_STILLPICTURE, + struct video_still_picture *sp) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_STILLPICTURE`` for this command. + + - .. + + - ``struct`` `video_still_picture`_ ``*sp`` + + - Pointer to the location where the struct with the I-frame + and size is stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to display a still picture +(I-frame). The input data shall be the section of an elementary video +stream containing an I-frame. Typically this section is extracted from a +TS or PES recording. Resolution and codec (see `video capabilities`_) must +be supported by the device. If the pointer is NULL, then the current +displayed still picture is blanked. + +e.g. The AV7110 supports MPEG1 and MPEG2 with the common PAL-SD +resolutions. + +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. + + +----- + + +VIDEO_FAST_FORWARD +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FAST_FORWARD + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FAST_FORWARD`` for this command. + + - .. + + - ``int nFrames`` + + - The number of frames to skip. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to skip decoding of N number of +I-frames. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_SLOWMOTION +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SLOWMOTION + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SLOWMOTION`` for this command. + + - .. + + - ``int nFrames`` + + - The number of times to repeat each frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device to repeat decoding frames N number +of times. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +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. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to a location where to store the capability information. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device about its decoding capabilities. +On success it returns an integer which has bits set according to the +defines in `video capabilities`_. + +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. + + +----- + + +VIDEO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call clears all video buffers in the driver and in the +decoder hardware. + +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. + + +----- + + +VIDEO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of stream to expect being written +to it. +Intelligent decoder might also not support or ignore (like the AV7110) +this call and determine the stream type themselves. + +Currently used stream types: + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Codec + + - Stream type + + - .. + + - MPEG2 + + - 0 + + - .. + + - MPEG4 h.264 + + - 1 + + - .. + + - VC1 + + - 3 + + - .. + + - MPEG4 Part2 + + - 4 + + - .. + + - VC1 SM + + - 5 + + - .. + + - MPEG1 + + - 6 + + - .. + + - HEVC h.265 + + - | 7 + | DREAMBOX: 22 + + - .. + + - AVS + + - 16 + + - .. + + - AVS2 + + - 40 + +Not every decoder supports all stream types. + +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. + + +----- + + +VIDEO_SET_FORMAT +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_FORMAT`` for this command. + + - .. + + - `video_format_t`_ ``format`` + + - Video format of TV as defined in section `video_format_t`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sets the screen format (aspect ratio) of the connected output +device (TV) so that the output of the decoder can be adjusted +accordingly. + +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. + + +----- + + +VIDEO_GET_SIZE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_SIZE + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call, + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_SIZE`` for this command. + + - .. + + - `video_size_t`_ ``*size`` + + - Returns the size and aspect ratio. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl returns the size and aspect ratio. + +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. + + +----- + + +VIDEO_GET_PTS +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_PTS + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_PTS`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / + ISO/IEC 13818-1. + + The PTS should belong to the currently played frame if possible, + but may also be a value close to it like the PTS of the last + decoded frame or the last PTS extracted by the PES parser. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control. + +This ioctl call asks the Video Device to return the current PTS +timestamp. + +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. + + +----- + + +VIDEO_GET_FRAME_COUNT +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_FRAME_COUNT + +.. code-block:: c + + int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_FRAME_COUNT`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the number of frames displayed since the decoder was + started. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` control. + +This ioctl call asks the Video Device to return the number of displayed +frames since the decoder was started. + +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. + + +----- + + +VIDEO_COMMAND +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Commands the decoder. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_DECODER_CMD` ioctl. + +This ioctl commands the decoder. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_DECODER_CMD` documentation for +more information. + +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. + + +----- + + +VIDEO_TRY_COMMAND +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_TRY_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_TRY_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_TRY_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Try a decoder command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl. + +This ioctl tries a decoder command. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation +for more information. + +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. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific video device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named video device (e.g. +/dev/dvb/adapter?/video?) for subsequent use. + +When an open() call has succeeded, the device will be ready for use. The +significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the open() call itself. A device opened in +blocking mode can later be put into non-blocking mode (and vice versa) +using the F_SETFL command of the fcntl system call. This is a standard +system call, documented in the Linux manual page for fcntl. Only one +user can open the Video Device in O_RDWR mode. All other attempts to +open the device in this mode will fail, and an error-code will be +returned. If the Video Device is opened in O_RDONLY mode, the only +ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will +return an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - :cspan:`1` Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened video device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. + + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if VIDEO_SOURCE_MEMORY is selected +in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in +PES format, unless the capability allows other formats. TS is the +most common format for storing DVB-data, it is usually supported too. +If O_NONBLOCK is not specified the function will block until buffer space +is available. The amount of data to be transferred is implied by count. + +.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>` + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/frontend.h.rst.exceptions index 6283702c08c8..dcaf5740de7e 100644 --- a/Documentation/userspace-api/media/frontend.h.rst.exceptions +++ b/Documentation/userspace-api/media/frontend.h.rst.exceptions @@ -86,6 +86,13 @@ ignore symbol APSK_16 ignore symbol APSK_32 ignore symbol DQPSK ignore symbol QAM_4_NR +ignore symbol QAM_1024 +ignore symbol QAM_4096 +ignore symbol APSK_8_L +ignore symbol APSK_16_L +ignore symbol APSK_32_L +ignore symbol APSK_64 +ignore symbol APSK_64_L ignore symbol SEC_VOLTAGE_13 ignore symbol SEC_VOLTAGE_18 @@ -119,6 +126,26 @@ ignore symbol FEC_AUTO ignore symbol FEC_3_5 ignore symbol FEC_9_10 ignore symbol FEC_2_5 +ignore symbol FEC_1_3 +ignore symbol FEC_1_4 +ignore symbol FEC_5_9 +ignore symbol FEC_7_9 +ignore symbol FEC_8_15 +ignore symbol FEC_11_15 +ignore symbol FEC_13_18 +ignore symbol FEC_9_20 +ignore symbol FEC_11_20 +ignore symbol FEC_23_36 +ignore symbol FEC_25_36 +ignore symbol FEC_13_45 +ignore symbol FEC_26_45 +ignore symbol FEC_28_45 +ignore symbol FEC_32_45 +ignore symbol FEC_77_90 +ignore symbol FEC_11_45 +ignore symbol FEC_4_15 +ignore symbol FEC_14_45 +ignore symbol FEC_7_15 ignore symbol TRANSMISSION_MODE_AUTO ignore symbol TRANSMISSION_MODE_1K @@ -143,6 +170,7 @@ ignore symbol GUARD_INTERVAL_19_256 ignore symbol GUARD_INTERVAL_PN420 ignore symbol GUARD_INTERVAL_PN595 ignore symbol GUARD_INTERVAL_PN945 +ignore symbol GUARD_INTERVAL_1_64 ignore symbol HIERARCHY_NONE ignore symbol HIERARCHY_AUTO @@ -163,6 +191,9 @@ ignore symbol ROLLOFF_35 ignore symbol ROLLOFF_20 ignore symbol ROLLOFF_25 ignore symbol ROLLOFF_AUTO +ignore symbol ROLLOFF_15 +ignore symbol ROLLOFF_10 +ignore symbol ROLLOFF_5 ignore symbol INVERSION_ON ignore symbol INVERSION_OFF @@ -187,6 +218,7 @@ ignore symbol SYS_DAB ignore symbol SYS_DSS ignore symbol SYS_CMMB ignore symbol SYS_DVBH +ignore symbol SYS_DVBC2 ignore symbol ATSCMH_SCCC_BLK_SEP ignore symbol ATSCMH_SCCC_BLK_COMB diff --git a/Documentation/userspace-api/media/gen-errors.rst b/Documentation/userspace-api/media/gen-errors.rst index e595d0bea109..4e8defd3612b 100644 --- a/Documentation/userspace-api/media/gen-errors.rst +++ b/Documentation/userspace-api/media/gen-errors.rst @@ -59,9 +59,7 @@ Generic Error Codes - - ``ENOTTY`` - - The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device. + - The ioctl is not supported by the file descriptor. - - ``ENOSPC`` diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst index d839904be085..337ef6c7c47f 100644 --- a/Documentation/userspace-api/media/index.rst +++ b/Documentation/userspace-api/media/index.rst @@ -21,13 +21,8 @@ Documentation/driver-api/media/index.rst media devices; -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 1 intro diff --git a/Documentation/userspace-api/media/mediactl/media-controller.rst b/Documentation/userspace-api/media/mediactl/media-controller.rst index 508dd693bf6c..73a87f82f92d 100644 --- a/Documentation/userspace-api/media/mediactl/media-controller.rst +++ b/Documentation/userspace-api/media/mediactl/media-controller.rst @@ -7,13 +7,8 @@ Part IV - Media Controller API ############################## -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst index 0ffeece1e0c8..6332e8395263 100644 --- a/Documentation/userspace-api/media/mediactl/media-types.rst +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -375,12 +375,11 @@ Types and flags used to represent the media graph elements are origins of links. * - ``MEDIA_PAD_FL_MUST_CONNECT`` - - If this flag is set and the pad is linked to any other pad, then - at least one of those links must be enabled for the entity to be - able to stream. There could be temporary reasons (e.g. device - configuration dependent) for the pad to need enabled links even - when this flag isn't set; the absence of the flag doesn't imply - there is none. + - If this flag is set, then for this pad to be able to stream, it must + be connected by at least one enabled link. There could be temporary + reasons (e.g. device configuration dependent) for the pad to need + enabled links even when this flag isn't set; the absence of the flag + doesn't imply there is none. One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index c9d578e291b8..5ae8fac8ed4f 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -43,7 +43,7 @@ reduced range of reception. .. note:: - Wide band receiver might be implictly enabled if you enable + Wide band receiver might be implicitly enabled if you enable carrier reports. In that case it will be disabled as soon as you disable carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing. diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index a2eab3b45647..2a888ff5829f 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -75,7 +75,7 @@ protocol, or the manchester BPF decoder. - Command There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. +where there the second stop bit is the 6th command bit, but inverted. This is done so it the scancodes and encoding is compatible with existing schemes. This bit is stored in bit 6 of the scancode, inverted. This is done to keep it compatible with plain rc-5 where there are two start bits. diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 28ed94088015..aab99260fef5 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -628,7 +628,7 @@ the remote via /dev/input/event devices. - Put device into zoom/full screen mode - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH + - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANEL / SWITCH - .. row 80 diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst index f89291838637..483f9ae92a90 100644 --- a/Documentation/userspace-api/media/rc/remote_controllers.rst +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -7,13 +7,8 @@ Part III - Remote Controller API ################################ -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/userspace-api/media/v4l/async.rst b/Documentation/userspace-api/media/v4l/async.rst deleted file mode 100644 index d6960ff5c382..000000000000 --- a/Documentation/userspace-api/media/v4l/async.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later - -.. _async: - -**************** -Asynchronous I/O -**************** - -This method is not defined yet. diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 9cd18c153d19..72aef1759b60 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -427,3 +427,12 @@ VP9 :title: VP9 Bitstream & Decoding Process Specification :author: Adrian Grange (Google), Peter de Rivaz (Argon Design), Jonathan Hunt (Argon Design) + +.. _av1: + +AV1 +=== + +:title: AV1 Bitstream & Decoding Process Specification + +:author: Peter de Rivaz, Argon Design Ltd, Jack Haughton, Argon Design Ltd diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 4638ec64db00..52bbee81c080 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -187,10 +187,8 @@ struct v4l2_buffer on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the + when it refers to an output stream. For multiplanar formats this field + is ignored and the ``planes`` pointer is used instead. * - __u32 - ``flags`` @@ -327,10 +325,7 @@ struct v4l2_plane - ``bytesused`` - The number of bytes occupied by data in the plane (its payload). Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. + stream, applications when it refers to an output stream. .. note:: @@ -554,9 +549,9 @@ Buffer Flags - 0x00000400 - The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, - :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 3eec65174260..57893814a1e5 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -143,9 +143,13 @@ Control IDs recognise the difference between digital and analogue gain use controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. +.. _v4l2-cid-hflip: + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. +.. _v4l2-cid-vflip: + ``V4L2_CID_VFLIP`` ``(boolean)`` Mirror the picture vertically. @@ -461,10 +465,10 @@ Example: Changing controls perror("VIDIOC_QUERYCTRL"); exit(EXIT_FAILURE); } else { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } else { memset(&control, 0, sizeof (control)); control.id = V4L2_CID_BRIGHTNESS; diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index 675bc2c3c6b8..ef8e8cf31f90 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -277,7 +277,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``OUTPUT`` buffers. @@ -311,7 +311,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` the actual number of buffers allocated. @@ -339,7 +339,7 @@ Initialization ``format`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. @@ -410,7 +410,7 @@ Capture Setup ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` frame buffer resolution for the decoded frames. @@ -443,7 +443,7 @@ Capture Setup ``target`` set to ``V4L2_SEL_TGT_COMPOSE``. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -552,7 +552,7 @@ Capture Setup frame is written; defaults to ``V4L2_SEL_TGT_COMPOSE_DEFAULT``; read-only on hardware without additional compose/scaling capabilities. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` the visible rectangle; it must fit within the frame buffer resolution @@ -629,7 +629,7 @@ Capture Setup ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -668,7 +668,7 @@ Capture Setup a format representing the maximum framebuffer resolution to be accommodated by newly allocated buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst index aa338b9624b0..6c523c69bdce 100644 --- a/Documentation/userspace-api/media/v4l/dev-encoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -115,8 +115,8 @@ Querying Capabilities 4. The client may use :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` to detect supported frame intervals for a given format and resolution, passing the desired pixel - format in :c:type:`v4l2_frmsizeenum` ``pixel_format`` and the resolution - in :c:type:`v4l2_frmsizeenum` ``width`` and :c:type:`v4l2_frmsizeenum` + format in :c:type:`v4l2_frmivalenum` ``pixel_format`` and the resolution + in :c:type:`v4l2_frmivalenum` ``width`` and :c:type:`v4l2_frmivalenum` ``height``. * Values returned by :c:func:`VIDIOC_ENUM_FRAMEINTERVALS` for a coded pixel @@ -163,7 +163,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``sizeimage`` adjusted size of ``CAPTURE`` buffers. @@ -189,7 +189,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``pixelformat`` raw format supported for the coded format currently selected on @@ -215,7 +215,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``width``, ``height`` may be adjusted to match encoder minimums, maximums and alignment @@ -233,7 +233,7 @@ Initialization :c:func:`VIDIOC_S_PARM`. This also sets the coded frame interval on the ``CAPTURE`` queue to the same value. - * ** Required fields:** + * **Required fields:** ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``OUTPUT``. @@ -245,7 +245,7 @@ Initialization the desired frame interval; the encoder may adjust it to match hardware requirements. - * **Return fields:** + * **Returned fields:** ``parm.output.timeperframe`` the adjusted frame interval. @@ -284,7 +284,7 @@ Initialization the case for off-line encoding. Support for this feature is signalled by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL <fmtdesc-flags>` format flag. - * ** Required fields:** + * **Required fields:** ``type`` a ``V4L2_BUF_TYPE_*`` enum appropriate for ``CAPTURE``. @@ -296,7 +296,7 @@ Initialization the desired coded frame interval; the encoder may adjust it to match hardware requirements. - * **Return fields:** + * **Returned fields:** ``parm.capture.timeperframe`` the adjusted frame interval. @@ -339,7 +339,7 @@ Initialization rectangle and may be subject to adjustment to match codec and hardware constraints. - * **Return fields:** + * **Returned fields:** ``r.left``, ``r.top``, ``r.width``, ``r.height`` visible rectangle adjusted by the encoder. @@ -387,7 +387,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -420,7 +420,7 @@ Initialization other fields follow standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to the number of allocated buffers. 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/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index 58f97c3a7792..2bec20d87928 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -41,7 +41,7 @@ Devices supporting the raw VBI capturing or output API set the in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous I/O methods must be supported. VBI +read/write or streaming I/O methods must be supported. VBI devices may or may not have a tuner or modulator. Supplemental Functions diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index 928884dfe09d..dfdeddbca41f 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -34,7 +34,7 @@ Devices supporting the SDR transmitter interface set the device has an Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. -At least one of the read/write, streaming or asynchronous I/O methods +At least one of the read/write or streaming I/O methods must be supported. diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 97ec2b115c71..42cdb0a9f786 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -36,7 +36,7 @@ Devices supporting the sliced VBI capturing or output API set the respectively, in the ``capabilities`` field of struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the -read/write, streaming or asynchronous :ref:`I/O methods <io>` must be +read/write or streaming :ref:`I/O methods <io>` must be supported. Sliced VBI devices may have a tuner or modulator. Supplemental Functions @@ -490,7 +490,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv - An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are - implcitly set. + implicitly set. * - } - diff --git a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst index 4a26646eeec5..35ed05f2695e 100644 --- a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst @@ -180,7 +180,7 @@ Initialization ``memory`` follows standard semantics. - * **Return fields:** + * **Returned fields:** ``count`` actual number of buffers allocated. @@ -208,7 +208,7 @@ Initialization follows standard semantics. ``V4L2_MEMORY_USERPTR`` is not supported for ``CAPTURE`` buffers. - * **Return fields:** + * **Returned fields:** ``count`` adjusted to allocated number of buffers, in case the codec requires diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index fd1de0a73a9f..43988516acdd 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -29,6 +29,8 @@ will feature a character device node on which ioctls can be called to - negotiate image formats on individual pads +- inspect and modify internal data routing between pads of the same entity + Sub-device character device nodes, conventionally named ``/dev/v4l-subdev*``, use major number 81. @@ -404,6 +406,8 @@ pixel array is not rectangular but cross-shaped or round. The maximum size may also be smaller than the BOUNDS rectangle. +.. _format-propagation: + Order of configuration and format propagation --------------------------------------------- @@ -501,3 +505,164 @@ source pads. :maxdepth: 1 subdev-formats + +Streams, multiplexed media pads and internal routing +---------------------------------------------------- + +Simple V4L2 sub-devices do not support multiple, unrelated video streams, +and only a single stream can pass through a media link and a media pad. +Thus each pad contains a format and selection configuration for that +single stream. A subdev can do stream processing and split a stream into +two or compose two streams into one, but the inputs and outputs for the +subdev are still a single stream per pad. + +Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple +data streams are transmitted on the same bus, which is represented by a media +link connecting a transmitter source pad with a sink pad on the receiver. For +example, a camera sensor can produce two distinct streams, a pixel stream and a +metadata stream, which are transmitted on the multiplexed data bus, represented +by a media link which connects the single sensor's source pad with the receiver +sink pad. The stream-aware receiver will de-multiplex the streams received on +the its sink pad and allows to route them individually to one of its source +pads. + +Subdevice drivers that support multiplexed streams are compatible with +non-multiplexed subdev drivers, but, of course, require a routing configuration +where the link between those two types of drivers contains only a single +stream. + +Understanding streams +^^^^^^^^^^^^^^^^^^^^^ + +A stream is a stream of content (e.g. pixel data or metadata) flowing through +the media pipeline from a source (e.g. a sensor) towards the final sink (e.g. a +receiver and demultiplexer in a SoC). Each media link carries all the enabled +streams from one end of the link to the other, and sub-devices have routing +tables which describe how the incoming streams from sink pads are routed to the +source pads. + +A stream ID is a media pad-local identifier for a stream. Streams IDs of +the same stream must be equal on both ends of a link. In other words, +a particular stream ID must exist on both sides of a media +link, but another stream ID can be used for the same stream at the other side +of the sub-device. + +A stream at a specific point in the media pipeline is identified by the +sub-device and a (pad, stream) pair. For sub-devices that do not support +multiplexed streams the 'stream' field is always 0. + +Interaction between routes, streams, formats and selections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The addition of streams to the V4L2 sub-device interface moves the sub-device +formats and selections from pads to (pad, stream) pairs. Besides the +usual pad, also the stream ID needs to be provided for setting formats and +selections. The order of configuring formats and selections along a stream is +the same as without streams (see :ref:`format-propagation`). + +Instead of the sub-device wide merging of streams from all sink pads +towards all source pads, data flows for each route are separate from each +other. Any number of routes from streams on sink pads towards streams on +source pads is allowed, to the extent supported by drivers. For every +stream on a source pad, however, only a single route is allowed. + +Any configurations of a stream within a pad, such as format or selections, +are independent of similar configurations on other streams. This is +subject to change in the future. + +Configuring streams +^^^^^^^^^^^^^^^^^^^ + +The configuration of the streams is done individually for each sub-device and +the validity of the streams between sub-devices is validated when the pipeline +is started. + +There are three steps in configuring the streams: + +1. Set up links. Connect the pads between sub-devices using the + :ref:`Media Controller API <media_controller>` + +2. Streams. Streams are declared and their routing is configured by setting the + routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING + <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that setting the routing table will + reset formats and selections in the sub-device to default values. + +3. Configure formats and selections. Formats and selections of each stream are + configured separately as documented for plain sub-devices in + :ref:`format-propagation`. The stream ID is set to the same stream ID + associated with either sink or source pads of routes configured using the + :ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. + +Multiplexed streams setup example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A simple example of a multiplexed stream setup might be as follows: + +- Two identical sensors (Sensor A and Sensor B). Each sensor has a single source + pad (pad 0) which carries a pixel data stream. + +- Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the + sensors (pads 0, 1), and one source pad (pad 2), which outputs two streams. + +- Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0), + connected to the bridge, and two source pads (pads 1-2), going to the DMA + engine. The receiver demultiplexes the incoming streams to the source pads. + +- DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is + connected to a single source pad in the receiver. + +The sensors, the bridge and the receiver are modeled as V4L2 sub-devices, +exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are +modeled as V4L2 devices, exposed to userspace via /dev/videoX nodes. + +To configure this pipeline, the userspace must take the following steps: + +1. Set up media links between entities: connect the sensors to the bridge, + bridge to the receiver, and the receiver to the DMA engines. This step does + not differ from normal non-multiplexed media controller setup. + +2. Configure routing + +.. flat-table:: Bridge routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 1/0 + - 2/1 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +.. flat-table:: Receiver routing table + :header-rows: 1 + + * - Sink Pad/Stream + - Source Pad/Stream + - Routing Flags + - Comments + * - 0/0 + - 1/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor A + * - 0/1 + - 2/0 + - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - Pixel data stream from Sensor B + +3. Configure formats and selections + + After configuring routing, the next step is configuring the formats and + selections for the streams. This is similar to performing this step without + streams, with just one exception: the ``stream`` field needs to be assigned + to the value of the stream ID. + + A common way to accomplish this is to start from the sensors and propagate + the configurations along the stream towards the receiver, using + :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each + stream endpoint in each sub-device. diff --git a/Documentation/userspace-api/media/v4l/dv-timings.rst b/Documentation/userspace-api/media/v4l/dv-timings.rst index e17f056b129f..4b19bcb4bd80 100644 --- a/Documentation/userspace-api/media/v4l/dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/dv-timings.rst @@ -33,6 +33,27 @@ current DV timings they use the the DV timings as seen by the video receiver applications use the :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. +When the hardware detects a video source change (e.g. the video +signal appears or disappears, or the video resolution changes), then +it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the +:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the +:ref:`VIDIOC_DQEVENT` to check if this event was reported. + +If the video signal changed, then the application has to stop +streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS` +to obtain the new video timings, and if they are valid, it can set +those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`. +This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>` +to obtain the new format. Now the application can allocate new buffers +and start streaming again. + +The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the +hardware detects, it will never change the configuration. If the +currently set timings and the actually detected timings differ, then +typically this will mean that you will not be able to capture any +video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE` +event so you know when something changed. + Applications can make use of the :ref:`input-capabilities` and :ref:`output-capabilities` flags to determine whether the digital video ioctls can be used with the given input or output. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index 4c5061aa9cd4..cdc515c60468 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -506,6 +506,8 @@ enum v4l2_scene_mode - value down. A value of zero stops the motion if one is in progress and has no effect otherwise. +.. _v4l2-camera-sensor-orientation: + ``V4L2_CID_CAMERA_ORIENTATION (menu)`` This read-only control describes the camera orientation by reporting its mounting position on the device where the camera is installed. The control @@ -536,6 +538,7 @@ enum v4l2_scene_mode - - The camera is not directly attached to the device and is freely movable. +.. _v4l2-camera-sensor-rotation: ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)`` This read-only control describes the rotation correction in degrees in the @@ -661,3 +664,11 @@ enum v4l2_scene_mode - .. [#f1] This control may be changed to a menu control in the future, if more options are required. + +``V4L2_CID_HDR_SENSOR_MODE (menu)`` + Change the sensor HDR mode. A HDR picture is obtained by merging two + captures of the same scene using two different exposure periods. HDR mode + describes the way these two captures are merged in the sensor. + + As modes differ for each sensor, menu items are not standardized by this + control and are left to the programmer. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index bee73065e993..786127b1e206 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -1213,7 +1213,7 @@ FWHT Flags - Luma AC coefficient table index. * - __s8 - ``y_dc_delta`` - - Luma DC delta vaue. + - Luma DC delta value. * - __s8 - ``y2_dc_delta`` - Y2 block DC delta value. @@ -1890,11 +1890,11 @@ params syntax' of the :ref:`vp9` specification for more details. * - __u8 - ``tree_probs[7]`` - Specifies the probability values to be used when decoding a Segment-ID. - See '5.15. Segmentation map' section of :ref:`vp9` for more details. + See '5.15 Segmentation map' section of :ref:`vp9` for more details. * - __u8 - ``pred_probs[3]`` - Specifies the probability values to be used when decoding a - Predicted-Segment-ID. See '6.4.14. Get segment id syntax' + Predicted-Segment-ID. See '6.4.14 Get segment id syntax' section of :ref:`vp9` for more details. * - __u8 - ``flags`` @@ -2048,3 +2048,2117 @@ This structure contains all loop filter related parameters. See sections - 0x2 - When set, the bitstream contains additional syntax elements that specify which mode and reference frame deltas are to be updated. + +.. _v4l2-codec-stateless-hevc: + +``V4L2_CID_STATELESS_HEVC_SPS (struct)`` + Specifies the Sequence Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.2 "Sequence parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_sps + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``video_parameter_set_id`` + - Specifies the value of the vps_video_parameter_set_id of the active VPS + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u8 + - ``seq_parameter_set_id`` + - Provides an identifier for the SPS for reference by other syntax elements + as described in section "7.4.3.2.1 General sequence parameter set RBSP semantics" + of H.265 specifications. + * - __u16 + - ``pic_width_in_luma_samples`` + - Specifies the width of each decoded picture in units of luma samples. + * - __u16 + - ``pic_height_in_luma_samples`` + - Specifies the height of each decoded picture in units of luma samples. + * - __u8 + - ``bit_depth_luma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the luma array. + * - __u8 + - ``bit_depth_chroma_minus8`` + - This value plus 8 specifies the bit depth of the samples of the chroma arrays. + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - Specifies the value of the variable MaxPicOrderCntLsb. + * - __u8 + - ``sps_max_dec_pic_buffering_minus1`` + - This value plus 1 specifies the maximum required size of the decoded picture buffer for + the coded video sequence (CVS). + * - __u8 + - ``sps_max_num_reorder_pics`` + - Indicates the maximum allowed number of pictures. + * - __u8 + - ``sps_max_latency_increase_plus1`` + - Used to signal MaxLatencyPictures, which indicates the maximum number of + pictures that can precede any picture in output order and follow that + picture in decoding order. + * - __u8 + - ``log2_min_luma_coding_block_size_minus3`` + - This value plus 3 specifies the minimum luma coding block size. + * - __u8 + - ``log2_diff_max_min_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum luma coding block size. + * - __u8 + - ``log2_min_luma_transform_block_size_minus2`` + - This value plus 2 specifies the minimum luma transform block size. + * - __u8 + - ``log2_diff_max_min_luma_transform_block_size`` + - Specifies the difference between the maximum and minimum luma transform block size. + * - __u8 + - ``max_transform_hierarchy_depth_inter`` + - Specifies the maximum hierarchy depth for transform units of coding units coded + in inter prediction mode. + * - __u8 + - ``max_transform_hierarchy_depth_intra`` + - Specifies the maximum hierarchy depth for transform units of coding units coded in + intra prediction mode. + * - __u8 + - ``pcm_sample_bit_depth_luma_minus1`` + - This value plus 1 specifies the number of bits used to represent each of PCM sample values of the + luma component. + * - __u8 + - ``pcm_sample_bit_depth_chroma_minus1`` + - Specifies the number of bits used to represent each of PCM sample values of + the chroma components. + * - __u8 + - ``log2_min_pcm_luma_coding_block_size_minus3`` + - Plus 3 specifies the minimum size of coding blocks. + * - __u8 + - ``log2_diff_max_min_pcm_luma_coding_block_size`` + - Specifies the difference between the maximum and minimum size of coding blocks. + * - __u8 + - ``num_short_term_ref_pic_sets`` + - Specifies the number of st_ref_pic_set() syntax structures included in the SPS. + * - __u8 + - ``num_long_term_ref_pics_sps`` + - Specifies the number of candidate long-term reference pictures that are + specified in the SPS. + * - __u8 + - ``chroma_format_idc`` + - Specifies the chroma sampling. + * - __u8 + - ``sps_max_sub_layers_minus1`` + - This value plus 1 specifies the maximum number of temporal sub-layers. + * - __u64 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_sps_flags: + +``Sequence Parameter Set Flags`` + +.. raw:: latex + + \small + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` + - 0x00000002 + - + * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` + - 0x00000008 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` + - 0x00000010 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` + - 0x00000040 + - + * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` + - 0x00000100 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_PPS (struct)`` + Specifies the Picture Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.3 "Picture parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_pps + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - Identifies the PPS for reference by other syntax elements. + * - __u8 + - ``num_extra_slice_header_bits`` + - Specifies the number of extra slice header bits that are present + in the slice header RBSP for coded pictures referring to the PPS. + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l0_active_minus1. + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - This value plus 1 specifies the inferred value of num_ref_idx_l1_active_minus1. + * - __s8 + - ``init_qp_minus26`` + - This value plus 26 specifies the initial value of SliceQp Y for each slice + referring to the PPS. + * - __u8 + - ``diff_cu_qp_delta_depth`` + - Specifies the difference between the luma coding tree block size + and the minimum luma coding block size of coding units that + convey cu_qp_delta_abs and cu_qp_delta_sign_flag. + * - __s8 + - ``pps_cb_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cb. + * - __s8 + - ``pps_cr_qp_offset`` + - Specifies the offsets to the luma quantization parameter Cr. + * - __u8 + - ``num_tile_columns_minus1`` + - This value plus 1 specifies the number of tile columns partitioning the picture. + * - __u8 + - ``num_tile_rows_minus1`` + - This value plus 1 specifies the number of tile rows partitioning the picture. + * - __u8 + - ``column_width_minus1[20]`` + - This value plus 1 specifies the width of the i-th tile column in units of + coding tree blocks. + * - __u8 + - ``row_height_minus1[22]`` + - This value plus 1 specifies the height of the i-th tile row in units of coding + tree blocks. + * - __s8 + - ``pps_beta_offset_div2`` + - Specifies the default deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``pps_tc_offset_div2`` + - Specifies the default deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``log2_parallel_merge_level_minus2`` + - This value plus 2 specifies the value of the variable Log2ParMrgLevel. + * - __u8 + - ``padding[4]`` + - Applications and drivers must set this to zero. + * - __u64 + - ``flags`` + - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` + +.. _hevc_pps_flags: + +``Picture Parameter Set Flags`` + +.. raw:: latex + + \small + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT_ENABLED`` + - 0x00000001 + - + * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` + - 0x00000002 + - + * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` + - 0x00000008 + - + * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` + - 0x00000040 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` + - 0x00000080 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000100 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` + - 0x00000200 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` + - 0x00000400 + - + * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` + - 0x00000800 + - + * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` + - 0x00001000 + - + * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` + - 0x00002000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00004000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` + - 0x00008000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` + - 0x00010000 + - + * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` + - 0x00020000 + - + * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` + - 0x00040000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00080000 + - Specifies the presence of deblocking filter control syntax elements in + the PPS + * - ``V4L2_HEVC_PPS_FLAG_UNIFORM_SPACING`` + - 0x00100000 + - Specifies that tile column boundaries and likewise tile row boundaries + are distributed uniformly across the picture + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_SLICE_PARAMS (struct)`` + Specifies various slice-specific parameters, especially from the NAL unit + header, general slice segment header and weighted prediction parameter + parts of the bitstream. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.7 "General slice segment header + semantics" of the specification. + This control is a dynamically sized 1-dimensional array, + V4L2_CTRL_FLAG_DYNAMIC_ARRAY flag must be set when using it. + +.. c:type:: v4l2_ctrl_hevc_slice_params + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bit_size`` + - Size (in bits) of the current slice data. + * - __u32 + - ``data_byte_offset`` + - Offset (in byte) to the video data in the current slice data. + * - __u32 + - ``num_entry_point_offsets`` + - Specifies the number of entry point offset syntax elements in the slice header. + When the driver supports it, the ``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS`` + must be set. + * - __u8 + - ``nal_unit_type`` + - Specifies the coding type of the slice (B, P or I). + * - __u8 + - ``nuh_temporal_id_plus1`` + - Minus 1 specifies a temporal identifier for the NAL unit. + * - __u8 + - ``slice_type`` + - + (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or + V4L2_HEVC_SLICE_TYPE_B). + * - __u8 + - ``colour_plane_id`` + - Specifies the colour plane associated with the current slice. + * - __s32 + - ``slice_pic_order_cnt`` + - Specifies the picture order count. + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 0 + that may be used to decode the slice. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - This value plus 1 specifies the maximum reference index for reference picture list 1 + that may be used to decode the slice. + * - __u8 + - ``collocated_ref_idx`` + - Specifies the reference index of the collocated picture used for + temporal motion vector prediction. + * - __u8 + - ``five_minus_max_num_merge_cand`` + - Specifies the maximum number of merging motion vector prediction + candidates supported in the slice subtracted from 5. + * - __s8 + - ``slice_qp_delta`` + - Specifies the initial value of QpY to be used for the coding blocks in the slice. + * - __s8 + - ``slice_cb_qp_offset`` + - Specifies a difference to be added to the value of pps_cb_qp_offset. + * - __s8 + - ``slice_cr_qp_offset`` + - Specifies a difference to be added to the value of pps_cr_qp_offset. + * - __s8 + - ``slice_act_y_qp_offset`` + - Specifies the offset to the luma of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cb_qp_offset`` + - Specifies the offset to the cb of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_act_cr_qp_offset`` + - Specifies the offset to the cr of quantization parameter qP derived in section 8.6.2 + * - __s8 + - ``slice_beta_offset_div2`` + - Specifies the deblocking parameter offsets for beta divided by 2. + * - __s8 + - ``slice_tc_offset_div2`` + - Specifies the deblocking parameter offsets for tC divided by 2. + * - __u8 + - ``pic_struct`` + - Indicates whether a picture should be displayed as a frame or as one or more fields. + * - __u32 + - ``slice_segment_addr`` + - Specifies the address of the first coding tree block in the slice segment. + * - __u8 + - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L0 reference elements as indices in the DPB. + * - __u8 + - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L1 reference elements as indices in the DPB. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, described as st_ref_pic_set() + in the specification, included in the slice header or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set include in the slice header + or SPS. It is the number of bits in the conditional block if(long_term_ref_pics_present_flag) + in section 7.3.6.1 of the specification. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_hevc_pred_weight_table` + - ``pred_weight_table`` + - The prediction weight coefficients for inter-picture prediction. + * - __u64 + - ``flags`` + - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` + +.. raw:: latex + + \normalsize + +.. _hevc_slice_params_flags: + +``Slice Parameters Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` + - 0x00000001 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` + - 0x00000002 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` + - 0x00000008 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` + - 0x00000010 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` + - 0x00000020 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` + - 0x00000040 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00000100 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_DEPENDENT_SLICE_SEGMENT`` + - 0x00000200 + - + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_ENTRY_POINT_OFFSETS (integer)`` + Specifies entry point offsets in bytes. + This control is a dynamically sized array. The number of entry point + offsets is reported by the ``elems`` field. + This bitstream parameter is defined according to :ref:`hevc`. + They are described in section 7.4.7.1 "General slice segment header + semantics" of the specification. + When multiple slices are submitted in a request, the length of + this array must be the sum of num_entry_point_offsets of all the + slices in the request. + +``V4L2_CID_STATELESS_HEVC_SCALING_MATRIX (struct)`` + Specifies the HEVC scaling matrix parameters used for the scaling process + for transform coefficients. + These matrix and parameters are defined according to :ref:`hevc`. + They are described in section 7.4.5 "Scaling list data semantics" of + the specification. + +.. c:type:: v4l2_ctrl_hevc_scaling_matrix + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_8x8[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_16x16[6][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_32x32[2][64]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_16x16[6]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + * - __u8 + - ``scaling_list_dc_coef_32x32[2]`` + - Scaling list is used for the scaling process for transform + coefficients. The values on each scaling list are expected + in raster scan order. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_hevc_dpb_entry + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_hevc_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the V4L2 capture buffer to use as reference, used + with B-coded and P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u8 + - ``flags`` + - Long term flag for the reference frame + (V4L2_HEVC_DPB_ENTRY_LONG_TERM_REFERENCE). The flag is set as + described in the ITU HEVC specification chapter "8.3.2 Decoding + process for reference picture set". + * - __u8 + - ``field_pic`` + - Whether the reference is a field picture or a frame. + See :ref:`HEVC dpb field pic Flags <hevc_dpb_field_pic_flags>` + * - __s32 + - ``pic_order_cnt_val`` + - The picture order count of the current picture. + * - __u8 + - ``padding[2]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +.. _hevc_dpb_field_pic_flags: + +``HEVC dpb field pic Flags`` + +.. raw:: latex + + \scriptsize + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME`` + - 0 + - (progressive) Frame + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_FIELD`` + - 1 + - Top field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_FIELD`` + - 2 + - Bottom field + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM`` + - 3 + - Top field, bottom field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP`` + - 4 + - Bottom field, top field, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_BOTTOM_TOP`` + - 5 + - Top field, bottom field, top field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_TOP_BOTTOM`` + - 6 + - Bottom field, top field, bottom field repeated, in that order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_DOUBLING`` + - 7 + - Frame doubling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_FRAME_TRIPLING`` + - 8 + - Frame tripling + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_PREVIOUS_BOTTOM`` + - 9 + - Top field paired with previous bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_PREVIOUS_TOP`` + - 10 + - Bottom field paired with previous top field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_TOP_PAIRED_NEXT_BOTTOM`` + - 11 + - Top field paired with next bottom field in output order + * - ``V4L2_HEVC_SEI_PIC_STRUCT_BOTTOM_PAIRED_NEXT_TOP`` + - 12 + - Bottom field paired with next top field in output order + +.. c:type:: v4l2_hevc_pred_weight_table + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| + +.. flat-table:: struct v4l2_hevc_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 0. + * - __s8 + - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 0. + * - __s8 + - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 0. + * - __s8 + - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 0. + * - __s8 + - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The difference of the weighting factor applied to the luma + prediction value for list 1. + * - __s8 + - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The additive offset applied to the luma prediction value for list 1. + * - __s8 + - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the weighting factor applied to the chroma + prediction value for list 1. + * - __s8 + - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - The difference of the additive offset applied to the chroma + prediction values for list 1. + * - __u8 + - ``luma_log2_weight_denom`` + - The base 2 logarithm of the denominator for all luma weighting + factors. + * - __s8 + - ``delta_chroma_log2_weight_denom`` + - The difference of the base 2 logarithm of the denominator for + all chroma weighting factors. + * - __u8 + - ``padding[6]`` + - Applications and drivers must set this to zero. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_decode_mode + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_STATELESS_HEVC_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + The OUTPUT buffer must contain all slices needed to decode the + frame. + +.. raw:: latex + + \normalsize + +``V4L2_CID_STATELESS_HEVC_START_CODE (enum)`` + Specifies the HEVC slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + +.. c:type:: v4l2_stateless_hevc_start_code + +.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_HEVC_START_CODE_NONE`` + - 0 + - Selecting this value specifies that HEVC slices are passed + to the driver without any start code. The bitstream data should be + according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence + contains emulation prevention bytes when required. + * - ``V4L2_STATELESS_HEVC_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that HEVC slices are expected + to be prefixed by Annex B start codes. According to :ref:`hevc` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. + +.. raw:: latex + + \normalsize + +``V4L2_CID_MPEG_VIDEO_BASELAYER_PRIORITY_ID (integer)`` + Specifies a priority identifier for the NAL unit, which will be applied to + the base layer. By default this value is set to 0 for the base layer, + and the next layer will have the priority ID assigned as 1, 2, 3 and so on. + The video encoder can't decide the priority id to be applied to a layer, + so this has to come from client. + This is applicable to H264 and valid Range is from 0 to 63. + Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. + +``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` + Specifies the maximum number of Long Term Reference (LTR) frames at any + given time that the encoder can keep. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` + After setting this control the frame that will be queued next + will be marked as a Long Term Reference (LTR) frame + and given this LTR index which ranges from 0 to LTR_COUNT-1. + This is applicable to the H264 and HEVC encoders. + Source Rec. ITU-T H.264 (06/2019); Table 7.9 + +``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` + Specifies the Long Term Reference (LTR) frame(s) to be used for + encoding the next frame queued after setting this control. + This provides a bitmask which consists of bits [0, LTR_COUNT-1]. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_STATELESS_HEVC_DECODE_PARAMS (struct)`` + Specifies various decode parameters, especially the references picture order + count (POC) for all the lists (short, long, before, current, after) and the + number of entries for each of them. + These parameters are defined according to :ref:`hevc`. + They are described in section 8.3 "Slice decoding process" of the + specification. + +.. c:type:: v4l2_ctrl_hevc_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s32 + - ``pic_order_cnt_val`` + - PicOrderCntVal as described in section 8.3.1 "Decoding process + for picture order count" of the specification. + * - __u16 + - ``short_term_ref_pic_set_size`` + - Specifies the size, in bits, of the short-term reference picture set, of the first slice + described as st_ref_pic_set() in the specification, included in the slice header + or SPS (section 7.3.6.1). + * - __u16 + - ``long_term_ref_pic_set_size`` + - Specifies the size, in bits, of the long-term reference picture set, of the first slice + included in the slice header or SPS. It is the number of bits in the conditional block + if(long_term_ref_pics_present_flag) in section 7.3.6.1 of the specification. + * - __u8 + - ``num_active_dpb_entries`` + - The number of entries in ``dpb``. + * - __u8 + - ``num_poc_st_curr_before`` + - The number of reference pictures in the short-term set that come before + the current frame. + * - __u8 + - ``num_poc_st_curr_after`` + - The number of reference pictures in the short-term set that come after + the current frame. + * - __u8 + - ``num_poc_lt_curr`` + - The number of reference pictures in the long-term set. + * - __u8 + - ``poc_st_curr_before[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrBefore as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term before references in DPB array. + * - __u8 + - ``poc_st_curr_after[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocStCurrAfter as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the short term after references in DPB array. + * - __u8 + - ``poc_lt_curr[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - PocLtCurr as described in section 8.3.2 "Decoding process for reference + picture set": provides the index of the long term references in DPB array. + * - __u8 + - ``num_delta_pocs_of_ref_rps_idx`` + - When the short_term_ref_pic_set_sps_flag in the slice header is equal to 0, + it is the same as the derived value NumDeltaPocs[RefRpsIdx]. It can be used to parse + the RPS data in slice headers instead of skipping it with @short_term_ref_pic_set_size. + When the value of short_term_ref_pic_set_sps_flag in the slice header is + equal to 1, num_delta_pocs_of_ref_rps_idx shall be set to 0. + * - struct :c:type:`v4l2_hevc_dpb_entry` + - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The decoded picture buffer, for meta-data about reference frames. + * - __u64 + - ``flags`` + - See :ref:`Decode Parameters Flags <hevc_decode_params_flags>` + +.. _hevc_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IRAP_PIC`` + - 0x00000001 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000002 + - + * - ``V4L2_HEVC_DECODE_PARAM_FLAG_NO_OUTPUT_OF_PRIOR`` + - 0x00000004 + - + +.. _v4l2-codec-stateless-av1: + +``V4L2_CID_STATELESS_AV1_SEQUENCE (struct)`` + Represents an AV1 Sequence OBU (Open Bitstream Unit). See section 5.5 + "Sequence header OBU syntax" in :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_sequence + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``flags`` + - See :ref:`AV1 Sequence Flags <av1_sequence_flags>`. + * - __u8 + - ``seq_profile`` + - Specifies the features that can be used in the coded video sequence. + * - __u8 + - ``order_hint_bits`` + - Specifies the number of bits used for the order_hint field at each frame. + * - __u8 + - ``bit_depth`` + - the bit depth to use for the sequence as described in section 5.5.2 + "Color config syntax" in :ref:`av1` for more details. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - __u16 + - ``max_frame_width_minus_1`` + - specifies the maximum frame width minus 1 for the frames represented by + this sequence header. + +.. _av1_sequence_flags: + +``AV1 Sequence Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEQUENCE_FLAG_STILL_PICTURE`` + - 0x00000001 + - If set, specifies that the coded video sequence contains only one coded + frame. If not set, specifies that the coded video sequence contains one + or more coded frames. + * - ``V4L2_AV1_SEQUENCE_FLAG_USE_128X128_SUPERBLOCK`` + - 0x00000002 + - If set, indicates that superblocks contain 128x128 luma samples. + When equal to 0, it indicates that superblocks contain 64x64 luma + samples. The number of contained chroma samples depends on + subsampling_x and subsampling_y. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_FILTER_INTRA`` + - 0x00000004 + - If set, specifies that the use_filter_intra syntax element may be + present. If not set, specifies that the use_filter_intra syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTRA_EDGE_FILTER`` + - 0x00000008 + - Specifies whether the intra edge filtering process should be enabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_INTERINTRA_COMPOUND`` + - 0x00000010 + - If set, specifies that the mode info for inter blocks may contain the + syntax element interintra. If not set, specifies that the syntax element + interintra will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_MASKED_COMPOUND`` + - 0x00000020 + - If set, specifies that the mode info for inter blocks may contain the + syntax element compound_type. If not set, specifies that the syntax + element compound_type will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_WARPED_MOTION`` + - 0x00000040 + - If set, indicates that the allow_warped_motion syntax element may be + present. If not set, indicates that the allow_warped_motion syntax + element will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_DUAL_FILTER`` + - 0x00000080 + - If set, indicates that the inter prediction filter type may be specified + independently in the horizontal and vertical directions. If the flag is + equal to 0, only one filter type may be specified, which is then used in + both directions. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_ORDER_HINT`` + - 0x00000100 + - If set, indicates that tools based on the values of order hints may be + used. If not set, indicates that tools based on order hints are + disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_JNT_COMP`` + - 0x00000200 + - If set, indicates that the distance weights process may be used for + inter prediction. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_REF_FRAME_MVS`` + - 0x00000400 + - If set, indicates that the use_ref_frame_mvs syntax element may be + present. If not set, indicates that the use_ref_frame_mvs syntax element + will not be present. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_SUPERRES`` + - 0x00000800 + - If set, specifies that the use_superres syntax element will be present + in the uncompressed header. If not set, specifies that the use_superres + syntax element will not be present (instead use_superres will be set to + 0 in the uncompressed header without being read). + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_CDEF`` + - 0x00001000 + - If set, specifies that cdef filtering may be enabled. If not set, + specifies that cdef filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_ENABLE_RESTORATION`` + - 0x00002000 + - If set, specifies that loop restoration filtering may be enabled. If not + set, specifies that loop restoration filtering is disabled. + * - ``V4L2_AV1_SEQUENCE_FLAG_MONO_CHROME`` + - 0x00004000 + - If set, indicates that the video does not contain U and V color planes. + If not set, indicates that the video contains Y, U, and V color planes. + * - ``V4L2_AV1_SEQUENCE_FLAG_COLOR_RANGE`` + - 0x00008000 + - If set, signals full swing representation, i.e. "Full Range + Quantization". If not set, signals studio swing representation, i.e. + "Limited Range Quantization". + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_X`` + - 0x00010000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_SUBSAMPLING_Y`` + - 0x00020000 + - Specify the chroma subsampling format. + * - ``V4L2_AV1_SEQUENCE_FLAG_FILM_GRAIN_PARAMS_PRESENT`` + - 0x00040000 + - Specifies whether film grain parameters are present in the coded video + sequence. + * - ``V4L2_AV1_SEQUENCE_FLAG_SEPARATE_UV_DELTA_Q`` + - 0x00080000 + - If set, indicates that the U and V planes may have separate delta + quantizer values. If not set, indicates that the U and V planes will share + the same delta quantizer value. + +``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY (struct)`` + Represents a single AV1 tile inside an AV1 Tile Group. Note that MiRowStart, + MiRowEnd, MiColStart and MiColEnd can be retrieved from struct + v4l2_av1_tile_info in struct v4l2_ctrl_av1_frame using tile_row and + tile_col. See section 6.10.1 "General tile group OBU semantics" in + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_tile_group_entry + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_tile_group_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``tile_offset`` + - Offset from the OBU data, i.e. where the coded tile data actually starts. + * - __u32 + - ``tile_size`` + - Specifies the size in bytes of the coded tile. Equivalent to "TileSize" + in :ref:`av1`. + * - __u32 + - ``tile_row`` + - Specifies the row of the current tile. Equivalent to "TileRow" in + :ref:`av1`. + * - __u32 + - ``tile_col`` + - Specifies the column of the current tile. Equivalent to "TileColumn" in + :ref:`av1`. + +.. c:type:: v4l2_av1_warp_model + + AV1 Warp Model as described in section 3 "Symbols and abbreviated terms" of + :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_WARP_MODEL_IDENTITY`` + - 0 + - Warp model is just an identity transform. + * - ``V4L2_AV1_WARP_MODEL_TRANSLATION`` + - 1 + - Warp model is a pure translation. + * - ``V4L2_AV1_WARP_MODEL_ROTZOOM`` + - 2 + - Warp model is a rotation + symmetric zoom + translation. + * - ``V4L2_AV1_WARP_MODEL_AFFINE`` + - 3 + - Warp model is a general affine transform. + +.. c:type:: v4l2_av1_reference_frame + +AV1 Reference Frames as described in section 6.10.24 "Ref frames semantics" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_REF_INTRA_FRAME`` + - 0 + - Intra Frame Reference. + * - ``V4L2_AV1_REF_LAST_FRAME`` + - 1 + - Last Frame Reference. + * - ``V4L2_AV1_REF_LAST2_FRAME`` + - 2 + - Last2 Frame Reference. + * - ``V4L2_AV1_REF_LAST3_FRAME`` + - 3 + - Last3 Frame Reference. + * - ``V4L2_AV1_REF_GOLDEN_FRAME`` + - 4 + - Golden Frame Reference. + * - ``V4L2_AV1_REF_BWDREF_FRAME`` + - 5 + - BWD Frame Reference. + * - ``V4L2_AV1_REF_ALTREF2_FRAME`` + - 6 + - ALTREF2 Frame Reference. + * - ``V4L2_AV1_REF_ALTREF_FRAME`` + - 7 + - ALTREF Frame Reference. + +.. c:type:: v4l2_av1_global_motion + +AV1 Global Motion parameters as described in section 6.8.17 +"Global motion params semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_global_motion + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - A bitfield containing the flags per reference frame. See + :ref:`AV1 Global Motion Flags <av1_global_motion_flags>` for more + details. + * - enum :c:type:`v4l2_av1_warp_model` + - ``type[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The type of global motion transform used. + * - __s32 + - ``params[V4L2_AV1_TOTAL_REFS_PER_FRAME][6]`` + - This field has the same meaning as "gm_params" in :ref:`av1`. + * - __u8 + - ``invalid`` + - Bitfield indicating whether the global motion params are invalid for a + given reference frame. See section 7.11.3.6 Setup shear process and the + variable "warpValid". Use V4L2_AV1_GLOBAL_MOTION_IS_INVALID(ref) to + create a suitable mask. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_global_motion_flags: + +``AV1 Global Motion Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_GLOBAL`` + - 0x00000001 + - Specifies whether global motion parameters are present for a particular + reference frame. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_ROT_ZOOM`` + - 0x00000002 + - Specifies whether a particular reference frame uses rotation and zoom + global motion. + * - ``V4L2_AV1_GLOBAL_MOTION_FLAG_IS_TRANSLATION`` + - 0x00000004 + - Specifies whether a particular reference frame uses translation global + motion + +.. c:type:: v4l2_av1_frame_restoration_type + +AV1 Frame Restoration Type. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_RESTORE_NONE`` + - 0 + - No filtering is applied. + * - ``V4L2_AV1_FRAME_RESTORE_WIENER`` + - 1 + - Wiener filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SGRPROJ`` + - 2 + - Self guided filter process is invoked. + * - ``V4L2_AV1_FRAME_RESTORE_SWITCHABLE`` + - 3 + - Restoration filter is swichtable. + +.. c:type:: v4l2_av1_loop_restoration + +AV1 Loop Restoration as described in section 6.10.15 "Loop restoration params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_loop_restoration + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Loop Restoration Flags <av1_loop_restoration_flags>`. + * - __u8 + - ``lr_unit_shift`` + - Specifies if the luma restoration size should be halved. + * - __u8 + - ``lr_uv_shift`` + - Specifies if the chroma size should be half the luma size. + * - __u8 + - ``reserved`` + - Applications and drivers must set this to zero. + * - :c:type:`v4l2_av1_frame_restoration_type` + - ``frame_restoration_type[V4L2_AV1_NUM_PLANES_MAX]`` + - Specifies the type of restoration used for each plane. + * - __u8 + - ``loop_restoration_size[V4L2_AV1_MAX_NUM_PLANES]`` + - Specifies the size of loop restoration units in units of samples in the + current plane. + +.. _av1_loop_restoration_flags: + +``AV1 Loop Restoration Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_LR`` + - 0x00000001 + - Retains the same meaning as UsesLr in :ref:`av1`. + * - ``V4L2_AV1_LOOP_RESTORATION_FLAG_USES_CHROMA_LR`` + - 0x00000002 + - Retains the same meaning as UsesChromaLr in :ref:`av1`. + +.. c:type:: v4l2_av1_cdef + +AV1 CDEF params semantics as described in section 6.10.14 "CDEF params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_cdef + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``damping_minus_3`` + - Controls the amount of damping in the deringing filter. + * - __u8 + - ``bits`` + - Specifies the number of bits needed to specify which CDEF filter to + apply. + * - __u8 + - ``y_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``y_sec_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + * - __u8 + - ``uv_pri_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the primary filter. + * - __u8 + - ``uv_secondary_strength[V4L2_AV1_CDEF_MAX]`` + - Specifies the strength of the secondary filter. + +.. c:type:: v4l2_av1_segment_feature + +AV1 segment features as described in section 3 "Symbols and abbreviated terms" +of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEG_LVL_ALT_Q`` + - 0 + - Index for quantizer segment feature. + * - ``V4L2_AV1_SEG_LVL_ALT_LF_Y_V`` + - 1 + - Index for vertical luma loop filter segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_FRAME`` + - 5 + - Index for reference frame segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_SKIP`` + - 6 + - Index for skip segment feature. + * - ``V4L2_AV1_SEG_LVL_REF_GLOBALMV`` + - 7 + - Index for global mv feature. + * - ``V4L2_AV1_SEG_LVL_MAX`` + - 8 + - Number of segment features. + +.. c:type:: v4l2_av1_segmentation + +AV1 Segmentation params as defined in section 6.8.13 "Segmentation params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_segmentation + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Segmentation Flags <av1_segmentation_flags>` + * - __u8 + - ``last_active_seg_id`` + - Indicates the highest numbered segment id that has some + enabled feature. This is used when decoding the segment id to only decode + choices corresponding to used segments. + * - __u8 + - ``feature_enabled[V4L2_AV1_MAX_SEGMENTS]`` + - Bitmask defining which features are enabled in each segment. Use + V4L2_AV1_SEGMENT_FEATURE_ENABLED to build a suitable mask. + * - __u16 + - `feature_data[V4L2_AV1_MAX_SEGMENTS][V4L2_AV1_SEG_LVL_MAX]`` + - Data attached to each feature. Data entry is only valid if the feature + is enabled. + +.. _av1_segmentation_flags: + +``AV1 Segmentation Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_SEGMENTATION_FLAG_ENABLED`` + - 0x00000001 + - If set, indicates that this frame makes use of the segmentation tool. If + not set, indicates that the frame does not use segmentation. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_MAP`` + - 0x00000002 + - If set, indicates that the segmentation map are updated during the + decoding of this frame. If not set, indicates that the segmentation map + from the previous frame is used. + * - ``V4L2_AV1_SEGMENTATION_FLAG_TEMPORAL_UPDATE`` + - 0x00000004 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_UPDATE_DATA`` + - 0x00000008 + - If set, indicates that the updates to the segmentation map are coded + relative to the existing segmentation map. If not set, indicates that + the new segmentation map is coded without reference to the existing + segmentation map. + * - ``V4L2_AV1_SEGMENTATION_FLAG_SEG_ID_PRE_SKIP`` + - 0x00000010 + - If set, indicates that the segment id will be read before the skip + syntax element. If not set, indicates that the skip syntax element will + be read first. + +.. c:type:: v4l2_av1_loop_filter + +AV1 Loop filter params as defined in section 6.8.10 "Loop filter semantics" of +:ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_global_motion + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_loop_filter_flags>` for more details. + * - __u8 + - ``level[4]`` + - An array containing loop filter strength values. Different loop + filter strength values from the array are used depending on the image + plane being filtered, and the edge direction (vertical or horizontal) + being filtered. + * - __u8 + - ``sharpness`` + - indicates the sharpness level. The loop_filter_level and + loop_filter_sharpness together determine when a block edge is filtered, + and by how much the filtering can change the sample values. The loop + filter process is described in section 7.14 of :ref:`av1`. + * - __u8 + - ``ref_deltas[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - contains the adjustment needed for the filter level based on the + chosen reference frame. If this syntax element is not present, it + maintains its previous value. + * - __u8 + - ``mode_deltas[2]`` + - contains the adjustment needed for the filter level based on + the chosen mode. If this syntax element is not present, it maintains its + previous value. + * - __u8 + - ``delta_lf_res`` + - specifies the left shift which should be applied to decoded loop filter + delta values. + +.. _av1_loop_filter_flags: + +``AV1 Loop Filter Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_ENABLED`` + - 0x00000001 + - If set, means that the filter level depends on the mode and reference + frame used to predict a block. If not set, means that the filter level + does not depend on the mode and reference frame. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_UPDATE`` + - 0x00000002 + - If set, means that additional syntax elements are present that specify + which mode and reference frame deltas are to be updated. If not set, + means that these syntax elements are not present. + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_PRESENT`` + - 0x00000004 + - Specifies whether loop filter delta values are present + * - ``V4L2_AV1_LOOP_FILTER_FLAG_DELTA_LF_MULTI`` + - 0x00000008 + - A value equal to 1 specifies that separate loop filter + deltas are sent for horizontal luma edges, vertical luma edges, + the U edges, and the V edges. A value of delta_lf_multi equal to 0 + specifies that the same loop filter delta is used for all edges. + +.. c:type:: v4l2_av1_quantization + +AV1 Quantization params as defined in section 6.8.11 "Quantization params +semantics" of :ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Loop Filter flags <av1_quantization_flags>` for more details. + * - __u8 + - ``base_q_idx`` + - Indicates the base frame qindex. This is used for Y AC coefficients and + as the base value for the other quantizers. + * - __u8 + - ``delta_q_y_dc`` + - Indicates the Y DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_dc`` + - Indicates the U DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_u_ac`` + - Indicates the U AC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_dc`` + - Indicates the V DC quantizer relative to base_q_idx. + * - __u8 + - ``delta_q_v_ac`` + - Indicates the V AC quantizer relative to base_q_idx. + * - __u8 + - ``qm_y`` + - Specifies the level in the quantizer matrix that should be used for + luma plane decoding. + * - __u8 + - ``qm_u`` + - Specifies the level in the quantizer matrix that should be used for + chroma U plane decoding. + * - __u8 + - ``qm_v`` + - Specifies the level in the quantizer matrix that should be used for + chroma V plane decoding. + * - __u8 + - ``delta_q_res`` + - Specifies the left shift which should be applied to decoded quantizer + index delta values. + +.. _av1_quantization_flags: + +``AV1 Quantization Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_QUANTIZATION_FLAG_DIFF_UV_DELTA`` + - 0x00000001 + - If set, indicates that the U and V delta quantizer values are coded + separately. If not set, indicates that the U and V delta quantizer + values share a common value. + * - ``V4L2_AV1_QUANTIZATION_FLAG_USING_QMATRIX`` + - 0x00000002 + - If set, specifies that the quantizer matrix will be used to compute + quantizers. + * - ``V4L2_AV1_QUANTIZATION_FLAG_DELTA_Q_PRESENT`` + - 0x00000004 + - Specifies whether quantizer index delta values are present. + +.. c:type:: v4l2_av1_tile_info + +AV1 Tile info as defined in section 6.8.14 "Tile info semantics" of ref:`av1`. + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_av1_tile_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See + :ref:`AV1 Tile Info flags <av1_tile_info_flags>` for more details. + * - __u8 + - ``context_update_tile_id`` + - Specifies which tile to use for the CDF update. + * - __u8 + - ``tile_cols`` + - Specifies the number of tiles across the frame. + * - __u8 + - ``tile_rows`` + - Specifies the number of tiles down the frame. + * - __u32 + - ``mi_col_starts[V4L2_AV1_MAX_TILE_COLS + 1]`` + - An array specifying the start column (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``mi_row_starts[V4L2_AV1_MAX_TILE_ROWS + 1]`` + - An array specifying the start row (in units of 4x4 luma + samples) for each tile across the image. + * - __u32 + - ``width_in_sbs_minus_1[V4L2_AV1_MAX_TILE_COLS]`` + - Specifies the width of a tile minus 1 in units of superblocks. + * - __u32 + - ``height_in_sbs_minus_1[V4L2_AV1_MAX_TILE_ROWS]`` + - Specifies the height of a tile minus 1 in units of superblocks. + * - __u8 + - ``tile_size_bytes`` + - Specifies the number of bytes needed to code each tile size. + * - __u8 + - ``reserved[3]`` + - Applications and drivers must set this to zero. + +.. _av1_tile_info_flags: + +``AV1 Tile Info Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TILE_INFO_FLAG_UNIFORM_TILE_SPACING`` + - 0x00000001 + - If set, means that the tiles are uniformly spaced across the frame. (In + other words, all tiles are the same size except for the ones at the + right and bottom edge which can be smaller). If not set means that the + tile sizes are coded. + +.. c:type:: v4l2_av1_frame_type + +AV1 Frame Type + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_KEY_FRAME`` + - 0 + - Key frame. + * - ``V4L2_AV1_INTER_FRAME`` + - 1 + - Inter frame. + * - ``V4L2_AV1_INTRA_ONLY_FRAME`` + - 2 + - Intra-only frame. + * - ``V4L2_AV1_SWITCH_FRAME`` + - 3 + - Switch frame. + +.. c:type:: v4l2_av1_interpolation_filter + +AV1 Interpolation Filter + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP`` + - 0 + - Eight tap filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SMOOTH`` + - 1 + - Eight tap smooth filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_EIGHTTAP_SHARP`` + - 2 + - Eight tap sharp filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_BILINEAR`` + - 3 + - Bilinear filter. + * - ``V4L2_AV1_INTERPOLATION_FILTER_SWITCHABLE`` + - 4 + - Filter selection is signaled at the block level. + +.. c:type:: v4l2_av1_tx_mode + +AV1 Tx mode as described in section 6.8.21 "TX mode semantics" of :ref:`av1`. + +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_TX_MODE_ONLY_4X4`` + - 0 + - The inverse transform will use only 4x4 transforms. + * - ``V4L2_AV1_TX_MODE_LARGEST`` + - 1 + - The inverse transform will use the largest transform size that fits + inside the block. + * - ``V4L2_AV1_TX_MODE_SELECT`` + - 2 + - The choice of transform size is specified explicitly for each block. + +``V4L2_CID_STATELESS_AV1_FRAME (struct)`` + Represents a Frame Header OBU. See 6.8 "Frame Header OBU semantics" of + :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_frame + +.. cssclass:: longtable + +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + +.. flat-table:: struct v4l2_ctrl_av1_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_av1_tile_info` + - ``tile_info`` + - Tile info + * - struct :c:type:`v4l2_av1_quantization` + - ``quantization`` + - Quantization parameters. + * - struct :c:type:`v4l2_av1_segmentation` + - ``segmentation`` + - Segmentation parameters. + * - __u8 + - ``superres_denom`` + - The denominator for the upscaling ratio. + * - struct :c:type:`v4l2_av1_loop_filter` + - ``loop_filter`` + - Loop filter params + * - struct :c:type:`v4l2_av1_cdef` + - ``cdef`` + - CDEF params + * - __u8 + - ``skip_mode_frame[2]`` + - Specifies the frames to use for compound prediction when skip_mode is + equal to 1. + * - __u8 + - ``primary_ref_frame`` + - Specifies which reference frame contains the CDF values and other state + that should be loaded at the start of the frame. + * - struct :c:type:`v4l2_av1_loop_restoration` + - ``loop_restoration`` + - Loop restoration parameters. + * - struct :c:type:`v4l2_av1_loop_global_motion` + - ``global_motion`` + - Global motion parameters. + * - __u32 + - ``flags`` + - See + :ref:`AV1 Frame flags <av1_frame_flags>` for more details. + * - enum :c:type:`v4l2_av1_frame_type` + - ``frame_type`` + - Specifies the AV1 frame type + * - __u32 + - ``order_hint`` + - Specifies OrderHintBits least significant bits of the expected output + order for this frame. + * - __u32 + - ``upscaled_width`` + - The upscaled width. + * - enum :c:type:`v4l2_av1_interpolation_filter` + - ``interpolation_filter`` + - Specifies the filter selection used for performing inter prediction. + * - enum :c:type:`v4l2_av1_tx_mode` + - ``tx_mode`` + - Specifies how the transform size is determined. + * - __u32 + - ``frame_width_minus_1`` + - Add 1 to get the frame's width. + * - __u32 + - ``frame_height_minus_1`` + - Add 1 to get the frame's height. + * - __u16 + - ``render_width_minus_1`` + - Add 1 to get the render width of the frame in luma samples. + * - __u16 + - ``render_height_minus_1`` + - Add 1 to get the render height of the frame in luma samples. + * - __u32 + - ``current_frame_id`` + - Specifies the frame id number for the current frame. Frame + id numbers are additional information that do not affect the decoding + process, but provide decoders with a way of detecting missing reference + frames so that appropriate action can be taken. + * - __u8 + - ``buffer_removal_time[V4L2_AV1_MAX_OPERATING_POINTS]`` + - Specifies the frame removal time in units of DecCT clock ticks counted + from the removal time of the last random access point for operating point + opNum. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + * - __u32 + - ``order_hints[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - Specifies the expected output order hint for each reference frame. + This field corresponds to the OrderHints variable from the specification + (section 5.9.2 "Uncompressed header syntax"). As such, this is only + used for non-intra frames and ignored otherwise. order_hints[0] is + always ignored. + * - __u64 + - ``reference_frame_ts[V4L2_AV1_TOTAL_REFS_PER_FRAME]`` + - The V4L2 timestamp for each of the reference frames enumerated in + enum :c:type:`v4l2_av1_reference_frame` starting at + ``V4L2_AV1_REF_LAST_FRAME``. This represents the state of reference + slot as described in the spec and updated by userland through the + "Reference frame update process" in section 7.20 The timestamp refers + to the ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __s8 + - ``ref_frame_idx[V4L2_AV1_REFS_PER_FRAME]`` + - An index into ``reference_frame_ts`` representing the ordered list of + references used by inter-frame. Matches the bitstream syntax + element of the same name. + * - __u8 + - ``refresh_frame_flags`` + - Contains a bitmask that specifies which reference frame slots will be + updated with the current frame after it is decoded. + +.. _av1_frame_flags: + +``AV1 Frame Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FRAME_FLAG_SHOW_FRAME`` + - 0x00000001 + - If set, specifies that this frame should be immediately output once + decoded. If not set, specifies that this frame should not be immediately + output; it may be output later if a later uncompressed header uses + show_existing_frame equal to 1. + * - ``V4L2_AV1_FRAME_FLAG_SHOWABLE_FRAME`` + - 0x00000002 + - If set, specifies that the frame may be output using the + show_existing_frame mechanism. If not set, specifies that this frame + will not be output using the show_existing_frame mechanism. + * - ``V4L2_AV1_FRAME_FLAG_ERROR_RESILIENT_MODE`` + - 0x00000004 + - Specifies whether error resilient mode is enabled. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_CDF_UPDATE`` + - 0x00000008 + - Specifies whether the CDF update in the symbol decoding process should + be disabled. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_SCREEN_CONTENT_TOOLS`` + - 0x00000010 + - If set, indicates that intra blocks may use palette encoding. If not + set, indicates that palette encoding is never used. + * - ``V4L2_AV1_FRAME_FLAG_FORCE_INTEGER_MV`` + - 0x00000020 + - If set, specifies that motion vectors will always be integers. If not + set, specifies that motion vectors can contain fractional bits. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_INTRABC`` + - 0x00000040 + - If set, indicates that intra block copy may be used in this frame. If + not set, indicates that intra block copy is not allowed in this frame. + * - ``V4L2_AV1_FRAME_FLAG_USE_SUPERRES`` + - 0x00000080 + - If set, indicates that upscaling is needed. + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_HIGH_PRECISION_MV`` + - 0x00000100 + - If set, specifies that motion vectors are specified to eighth pel + precision. If not set, specifies that motion vectors are specified to + quarter pel precision; + * - ``V4L2_AV1_FRAME_FLAG_IS_MOTION_MODE_SWITCHABLE`` + - 0x00000200 + - If not set, specifies that only the SIMPLE motion mode will be used. + * - ``V4L2_AV1_FRAME_FLAG_USE_REF_FRAME_MVS`` + - 0x00000400 + - If set specifies that motion vector information from a previous frame + can be used when decoding the current frame. If not set, specifies that + this information will not be used. + * - ``V4L2_AV1_FRAME_FLAG_DISABLE_FRAME_END_UPDATE_CDF`` + - 0x00000800 + - If set indicates that the end of frame CDF update is disabled. If not + set, indicates that the end of frame CDF update is enabled + * - ``V4L2_AV1_FRAME_FLAG_ALLOW_WARPED_MOTION`` + - 0x00001000 + - If set, indicates that the syntax element motion_mode may be present, if + not set, indicates that the syntax element motion_mode will not be + present. + * - ``V4L2_AV1_FRAME_FLAG_REFERENCE_SELECT`` + - 0x00002000 + - If set, specifies that the mode info for inter blocks contains the + syntax element comp_mode that indicates whether to use single or + compound reference prediction. If not set, specifies that all inter + blocks will use single prediction. + * - ``V4L2_AV1_FRAME_FLAG_REDUCED_TX_SET`` + - 0x00004000 + - If set, specifies that the frame is restricted to a reduced subset of + the full set of transform types. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_ALLOWED`` + - 0x00008000 + - This flag retains the same meaning as SkipModeAllowed in :ref:`av1`. + * - ``V4L2_AV1_FRAME_FLAG_SKIP_MODE_PRESENT`` + - 0x00010000 + - If set, specifies that the syntax element skip_mode will be present, if + not set, specifies that skip_mode will not be used for this frame. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_SIZE_OVERRIDE`` + - 0x00020000 + - If set, specifies that the frame size will either be specified as the + size of one of the reference frames, or computed from the + frame_width_minus_1 and frame_height_minus_1 syntax elements. If not + set, specifies that the frame size is equal to the size in the sequence + header. + * - ``V4L2_AV1_FRAME_FLAG_BUFFER_REMOVAL_TIME_PRESENT`` + - 0x00040000 + - If set, specifies that buffer_removal_time is present. If not set, + specifies that buffer_removal_time is not present. + * - ``V4L2_AV1_FRAME_FLAG_FRAME_REFS_SHORT_SIGNALING`` + - 0x00080000 + - If set, indicates that only two reference frames are explicitly + signaled. If not set, indicates that all reference frames are explicitly + signaled. + +``V4L2_CID_STATELESS_AV1_FILM_GRAIN (struct)`` + Represents the optional film grain parameters. See section + 6.8.20 "Film grain params semantics" of :ref:`av1` for more details. + +.. c:type:: v4l2_ctrl_av1_film_grain + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_ctrl_av1_film_grain + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``flags`` + - See :ref:`AV1 Film Grain Flags <av1_film_grain_flags>`. + * - __u8 + - ``cr_mult`` + - Represents a multiplier for the cr component used in derivation of the + input index to the cr component scaling function. + * - __u16 + - ``grain_seed`` + - Specifies the starting value for the pseudo-random numbers used during + film grain synthesis. + * - __u8 + - ``film_grain_params_ref_idx`` + - Indicates which reference frame contains the film grain parameters to be + used for this frame. + * - __u8 + - ``num_y_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the luma component. + * - __u8 + - ``point_y_value[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the x (luma value) coordinate for the i-th point + of the piecewise linear scaling function for luma component. The values + are signaled on the scale of 0..255. In case of 10 bit video, these + values correspond to luma values divided by 4. In case of 12 bit video, + these values correspond to luma values divided by 16. + * - __u8 + - ``point_y_scaling[V4L2_AV1_MAX_NUM_Y_POINTS]`` + - Represents the scaling (output) value for the i-th point + of the piecewise linear scaling function for luma component. + * - __u8 + - ``num_cb_points`` + - Specifies the number of points for the piece-wise linear scaling + function of the cb component. + * - __u8 + - ``point_cb_value[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cb component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cb_scaling[V4L2_AV1_MAX_NUM_CB_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cb component. + * - __u8 + - ``num_cr_points`` + - Represents the number of points for the piece-wise + linear scaling function of the cr component. + * - __u8 + - ``point_cr_value[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the x coordinate for the i-th point of the + piece-wise linear scaling function for cr component. The values are + signaled on the scale of 0..255. + * - __u8 + - ``point_cr_scaling[V4L2_AV1_MAX_NUM_CR_POINTS]`` + - Represents the scaling (output) value for the i-th point of the + piecewise linear scaling function for cr component. + * - __u8 + - ``grain_scaling_minus_8`` + - Represents the shift - 8 applied to the values of the chroma component. + The grain_scaling_minus_8 can take values of 0..3 and determines the + range and quantization step of the standard deviation of film grain. + * - __u8 + - ``ar_coeff_lag`` + - Specifies the number of auto-regressive coefficients for luma and + chroma. + * - __u8 + - ``ar_coeffs_y_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the Y plane. + * - __u8 + - ``ar_coeffs_cb_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the U plane. + * - __u8 + - ``ar_coeffs_cr_plus_128[V4L2_AV1_AR_COEFFS_SIZE]`` + - Specifies auto-regressive coefficients used for the V plane. + * - __u8 + - ``ar_coeff_shift_minus_6`` + - Specifies the range of the auto-regressive coefficients. Values of 0, + 1, 2, and 3 correspond to the ranges for auto-regressive coefficients of + [-2, 2), [-1, 1), [-0.5, 0.5) and [-0.25, 0.25) respectively. + * - __u8 + - ``grain_scale_shift`` + - Specifies how much the Gaussian random numbers should be scaled down + during the grain synthesis process. + * - __u8 + - ``cb_mult`` + - Represents a multiplier for the cb component used in derivation of the + input index to the cb component scaling function. + * - __u8 + - ``cb_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cb component scaling function.. + * - __u8 + - ``cr_luma_mult`` + - Represents a multiplier for the average luma component used in + derivation of the input index to the cr component scaling function. + * - __u16 + - ``cb_offset`` + - Represents an offset used in derivation of the input index to the + cb component scaling function. + * - __u16 + - ``cr_offset`` + - Represents an offset used in derivation of the input index to the + cr component scaling function. + * - __u8 + - ``reserved[4]`` + - Applications and drivers must set this to zero. + +.. _av1_film_grain_flags: + +``AV1 Film Grain Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_AV1_FILM_GRAIN_FLAG_APPLY_GRAIN`` + - 0x00000001 + - If set, specifies that film grain should be added to this frame. If not + set, specifies that film grain should not be added. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_UPDATE_GRAIN`` + - 0x00000002 + - If set, means that a new set of parameters should be sent. If not set, + specifies that the previous set of parameters should be used. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CHROMA_SCALING_FROM_LUMA`` + - 0x00000004 + - If set, specifies that the chroma scaling is inferred from the luma + scaling. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_OVERLAP`` + - 0x00000008 + - If set, indicates that the overlap between film grain blocks shall be + applied. If not set, indicates that the overlap between film grain blocks + shall not be applied. + * - ``V4L2_AV1_FILM_GRAIN_FLAG_CLIP_TO_RESTRICTED_RANGE`` + - 0x00000010 + - If set, indicates that clipping to the restricted (studio, i.e. limited) + range shall be applied to the sample values after adding the film grain + (see the semantics for color_range for an explanation of studio swing). + If not set, indicates that clipping to the full range shall be applied + to the sample values after adding the film grain. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 6183f43f4d73..2a165ae063fb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -2658,783 +2658,3 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 disables generating SPS and PPS at every IDR. Setting it to one enables generating SPS and PPS at every IDR. - -.. _v4l2-mpeg-hevc: - -``V4L2_CID_MPEG_VIDEO_HEVC_SPS (struct)`` - Specifies the Sequence Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.2 "Sequence parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_sps - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_sps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u16 - - ``pic_width_in_luma_samples`` - - - * - __u16 - - ``pic_height_in_luma_samples`` - - - * - __u8 - - ``bit_depth_luma_minus8`` - - - * - __u8 - - ``bit_depth_chroma_minus8`` - - - * - __u8 - - ``log2_max_pic_order_cnt_lsb_minus4`` - - - * - __u8 - - ``sps_max_dec_pic_buffering_minus1`` - - - * - __u8 - - ``sps_max_num_reorder_pics`` - - - * - __u8 - - ``sps_max_latency_increase_plus1`` - - - * - __u8 - - ``log2_min_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_luma_coding_block_size`` - - - * - __u8 - - ``log2_min_luma_transform_block_size_minus2`` - - - * - __u8 - - ``log2_diff_max_min_luma_transform_block_size`` - - - * - __u8 - - ``max_transform_hierarchy_depth_inter`` - - - * - __u8 - - ``max_transform_hierarchy_depth_intra`` - - - * - __u8 - - ``pcm_sample_bit_depth_luma_minus1`` - - - * - __u8 - - ``pcm_sample_bit_depth_chroma_minus1`` - - - * - __u8 - - ``log2_min_pcm_luma_coding_block_size_minus3`` - - - * - __u8 - - ``log2_diff_max_min_pcm_luma_coding_block_size`` - - - * - __u8 - - ``num_short_term_ref_pic_sets`` - - - * - __u8 - - ``num_long_term_ref_pics_sps`` - - - * - __u8 - - ``chroma_format_idc`` - - - * - __u8 - - ``sps_max_sub_layers_minus1`` - - - * - __u64 - - ``flags`` - - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` - -.. raw:: latex - - \normalsize - -.. _hevc_sps_flags: - -``Sequence Parameter Set Flags`` - -.. raw:: latex - - \small - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` - - 0x00000001 - - - * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` - - 0x00000002 - - - * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` - - 0x00000008 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` - - 0x00000010 - - - * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` - - 0x00000040 - - - * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` - - 0x00000100 - - - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` - Specifies the Picture Parameter Set fields (as extracted from the - bitstream) for the associated HEVC slice data. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.3.3 "Picture parameter set RBSP - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_pps - -.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_pps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``num_extra_slice_header_bits`` - - - * - __u8 - - ``num_ref_idx_l0_default_active_minus1`` - - Specifies the inferred value of num_ref_idx_l0_active_minus1 - * - __u8 - - ``num_ref_idx_l1_default_active_minus1`` - - Specifies the inferred value of num_ref_idx_l1_active_minus1 - * - __s8 - - ``init_qp_minus26`` - - - * - __u8 - - ``diff_cu_qp_delta_depth`` - - - * - __s8 - - ``pps_cb_qp_offset`` - - - * - __s8 - - ``pps_cr_qp_offset`` - - - * - __u8 - - ``num_tile_columns_minus1`` - - - * - __u8 - - ``num_tile_rows_minus1`` - - - * - __u8 - - ``column_width_minus1[20]`` - - - * - __u8 - - ``row_height_minus1[22]`` - - - * - __s8 - - ``pps_beta_offset_div2`` - - - * - __s8 - - ``pps_tc_offset_div2`` - - - * - __u8 - - ``log2_parallel_merge_level_minus2`` - - - * - __u8 - - ``padding[4]`` - - Applications and drivers must set this to zero. - * - __u64 - - ``flags`` - - See :ref:`Picture Parameter Set Flags <hevc_pps_flags>` - -.. _hevc_pps_flags: - -``Picture Parameter Set Flags`` - -.. raw:: latex - - \small - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT_ENABLED`` - - 0x00000001 - - - * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` - - 0x00000002 - - - * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` - - 0x00000008 - - - * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` - - 0x00000020 - - - * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` - - 0x00000040 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` - - 0x00000080 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000100 - - - * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` - - 0x00000200 - - - * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` - - 0x00000400 - - - * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` - - 0x00000800 - - - * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` - - 0x00001000 - - - * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` - - 0x00002000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00004000 - - - * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` - - 0x00008000 - - - * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` - - 0x00010000 - - - * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` - - 0x00020000 - - - * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` - - 0x00040000 - - - * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00080000 - - Specifies the presence of deblocking filter control syntax elements in - the PPS - * - ``V4L2_HEVC_PPS_FLAG_UNIFORM_SPACING`` - - 0x00100000 - - Specifies that tile column boundaries and likewise tile row boundaries - are distributed uniformly across the picture - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` - Specifies various slice-specific parameters, especially from the NAL unit - header, general slice segment header and weighted prediction parameter - parts of the bitstream. - These bitstream parameters are defined according to :ref:`hevc`. - They are described in section 7.4.7 "General slice segment header - semantics" of the specification. - -.. c:type:: v4l2_ctrl_hevc_slice_params - -.. raw:: latex - - \scriptsize - -.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_slice_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bit_size`` - - Size (in bits) of the current slice data. - * - __u32 - - ``data_bit_offset`` - - Offset (in bits) to the video data in the current slice data. - * - __u8 - - ``nal_unit_type`` - - - * - __u8 - - ``nuh_temporal_id_plus1`` - - - * - __u8 - - ``slice_type`` - - - (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or - V4L2_HEVC_SLICE_TYPE_B). - * - __u8 - - ``colour_plane_id`` - - - * - __u16 - - ``slice_pic_order_cnt`` - - - * - __u8 - - ``num_ref_idx_l0_active_minus1`` - - - * - __u8 - - ``num_ref_idx_l1_active_minus1`` - - - * - __u8 - - ``collocated_ref_idx`` - - - * - __u8 - - ``five_minus_max_num_merge_cand`` - - - * - __s8 - - ``slice_qp_delta`` - - - * - __s8 - - ``slice_cb_qp_offset`` - - - * - __s8 - - ``slice_cr_qp_offset`` - - - * - __s8 - - ``slice_act_y_qp_offset`` - - - * - __s8 - - ``slice_act_cb_qp_offset`` - - - * - __s8 - - ``slice_act_cr_qp_offset`` - - - * - __s8 - - ``slice_beta_offset_div2`` - - - * - __s8 - - ``slice_tc_offset_div2`` - - - * - __u8 - - ``pic_struct`` - - - * - __u32 - - ``slice_segment_addr`` - - - * - __u8 - - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L0 reference elements as indices in the DPB. - * - __u8 - - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The list of L1 reference elements as indices in the DPB. - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - * - struct :c:type:`v4l2_hevc_pred_weight_table` - - ``pred_weight_table`` - - The prediction weight coefficients for inter-picture prediction. - * - __u64 - - ``flags`` - - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` - -.. raw:: latex - - \normalsize - -.. _hevc_slice_params_flags: - -``Slice Parameters Flags`` - -.. raw:: latex - - \scriptsize - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` - - 0x00000001 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` - - 0x00000002 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` - - 0x00000004 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` - - 0x00000008 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` - - 0x00000010 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` - - 0x00000020 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` - - 0x00000040 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` - - 0x00000080 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` - - 0x00000100 - - - * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_DEPENDENT_SLICE_SEGMENT`` - - 0x00000200 - - - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_SCALING_MATRIX (struct)`` - Specifies the HEVC scaling matrix parameters used for the scaling process - for transform coefficients. - These matrix and parameters are defined according to :ref:`hevc`. - They are described in section 7.4.5 "Scaling list data semantics" of - the specification. - -.. c:type:: v4l2_ctrl_hevc_scaling_matrix - -.. raw:: latex - - \scriptsize - -.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_scaling_matrix - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``scaling_list_4x4[6][16]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - * - __u8 - - ``scaling_list_8x8[6][64]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - * - __u8 - - ``scaling_list_16x16[6][64]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - * - __u8 - - ``scaling_list_32x32[2][64]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - * - __u8 - - ``scaling_list_dc_coef_16x16[6]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - * - __u8 - - ``scaling_list_dc_coef_32x32[2]`` - - Scaling list is used for the scaling process for transform - coefficients. The values on each scaling list are expected - in raster scan order. - -.. raw:: latex - - \normalsize - -.. c:type:: v4l2_hevc_dpb_entry - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| - -.. flat-table:: struct v4l2_hevc_dpb_entry - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u64 - - ``timestamp`` - - Timestamp of the V4L2 capture buffer to use as reference, used - with B-coded and P-coded frames. The timestamp refers to the - ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the - :c:func:`v4l2_timeval_to_ns()` function to convert the struct - :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. - * - __u8 - - ``flags`` - - Long term flag for the reference frame - (V4L2_HEVC_DPB_ENTRY_LONG_TERM_REFERENCE). The flag is set as - described in the ITU HEVC specification chapter "8.3.2 Decoding - process for reference picture set". - * - __u8 - - ``field_pic`` - - Whether the reference is a field picture or a frame. - * - __u16 - - ``pic_order_cnt[2]`` - - The picture order count of the reference. Only the first element of the - array is used for frame pictures, while the first element identifies the - top field and the second the bottom field in field-coded pictures. - * - __u8 - - ``padding[2]`` - - Applications and drivers must set this to zero. - -.. raw:: latex - - \normalsize - -.. c:type:: v4l2_hevc_pred_weight_table - -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| - -.. flat-table:: struct v4l2_hevc_pred_weight_table - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``luma_log2_weight_denom`` - - - * - __s8 - - ``delta_chroma_log2_weight_denom`` - - - * - __s8 - - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - - * - __s8 - - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __s8 - - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` - - - * - __u8 - - ``padding[6]`` - - Applications and drivers must set this to zero. - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` - Specifies the decoding mode to use. Currently exposes slice-based and - frame-based decoding but new modes might be added later on. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the decoding mode - that is expected for the buffer. - Drivers may expose a single or multiple decoding modes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_decode_mode - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_SLICE_BASED`` - - 0 - - Decoding is done at the slice granularity. - The OUTPUT buffer must contain a single slice. - * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_FRAME_BASED`` - - 1 - - Decoding is done at the frame granularity. - The OUTPUT buffer must contain all slices needed to decode the - frame. The OUTPUT buffer must also contain both fields. - -.. raw:: latex - - \normalsize - -``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` - Specifies the HEVC slice start code expected for each slice. - This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE - pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE - are required to set this control in order to specify the start code - that is expected for the buffer. - Drivers may expose a single or multiple start codes, depending - on what they can support. - - .. note:: - - This menu control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_mpeg_video_hevc_start_code - -.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` - - 0 - - Selecting this value specifies that HEVC slices are passed - to the driver without any start code. The bitstream data should be - according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence - contains emulation prevention bytes when required. - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` - - 1 - - Selecting this value specifies that HEVC slices are expected - to be prefixed by Annex B start codes. According to :ref:`hevc` - valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. - -``V4L2_CID_MPEG_VIDEO_BASELAYER_PRIORITY_ID (integer)`` - Specifies a priority identifier for the NAL unit, which will be applied to - the base layer. By default this value is set to 0 for the base layer, - and the next layer will have the priority ID assigned as 1, 2, 3 and so on. - The video encoder can't decide the priority id to be applied to a layer, - so this has to come from client. - This is applicable to H264 and valid Range is from 0 to 63. - Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. - -``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` - Specifies the maximum number of Long Term Reference (LTR) frames at any - given time that the encoder can keep. - This is applicable to the H264 and HEVC encoders. - -``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` - After setting this control the frame that will be queued next - will be marked as a Long Term Reference (LTR) frame - and given this LTR index which ranges from 0 to LTR_COUNT-1. - This is applicable to the H264 and HEVC encoders. - Source Rec. ITU-T H.264 (06/2019); Table 7.9 - -``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` - Specifies the Long Term Reference (LTR) frame(s) to be used for - encoding the next frame queued after setting this control. - This provides a bitmask which consists of bits [0, LTR_COUNT-1]. - This is applicable to the H264 and HEVC encoders. - -``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_PARAMS (struct)`` - Specifies various decode parameters, especially the references picture order - count (POC) for all the lists (short, long, before, current, after) and the - number of entries for each of them. - These parameters are defined according to :ref:`hevc`. - They are described in section 8.3 "Slice decoding process" of the - specification. - -.. c:type:: v4l2_ctrl_hevc_decode_params - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_ctrl_hevc_decode_params - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s32 - - ``pic_order_cnt_val`` - - PicOrderCntVal as described in section 8.3.1 "Decoding process - for picture order count" of the specification. - * - __u8 - - ``num_active_dpb_entries`` - - The number of entries in ``dpb``. - * - struct :c:type:`v4l2_hevc_dpb_entry` - - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - The decoded picture buffer, for meta-data about reference frames. - * - __u8 - - ``num_poc_st_curr_before`` - - The number of reference pictures in the short-term set that come before - the current frame. - * - __u8 - - ``num_poc_st_curr_after`` - - The number of reference pictures in the short-term set that come after - the current frame. - * - __u8 - - ``num_poc_lt_curr`` - - The number of reference pictures in the long-term set. - * - __u8 - - ``poc_st_curr_before[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - PocStCurrBefore as described in section 8.3.2 "Decoding process for reference - picture set": provides the index of the short term before references in DPB array. - * - __u8 - - ``poc_st_curr_after[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - PocStCurrAfter as described in section 8.3.2 "Decoding process for reference - picture set": provides the index of the short term after references in DPB array. - * - __u8 - - ``poc_lt_curr[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` - - PocLtCurr as described in section 8.3.2 "Decoding process for reference - picture set": provides the index of the long term references in DPB array. - * - __u64 - - ``flags`` - - See :ref:`Decode Parameters Flags <hevc_decode_params_flags>` - -.. _hevc_decode_params_flags: - -``Decode Parameters Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IRAP_PIC`` - - 0x00000001 - - - * - ``V4L2_HEVC_DECODE_PARAM_FLAG_IDR_PIC`` - - 0x00000002 - - - * - ``V4L2_HEVC_DECODE_PARAM_FLAG_NO_OUTPUT_OF_PRIOR`` - - 0x00000004 - - diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 60f9a09422d6..522095c08469 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -8,7 +8,7 @@ JPEG Control Reference The JPEG class includes controls for common features of JPEG encoders and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy +progressive baseline DCT compression process with Huffman entropy coding. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index 28a2750d5c8c..cdc11e9a0f32 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -47,7 +47,7 @@ Codec API was released. 1998-11-08: Many minor changes. Most symbols have been renamed. Some material changes to struct v4l2_capability. -1998-11-12: The read/write directon of some ioctls was misdefined. +1998-11-12: The read/write direction of some ioctls was misdefined. 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio @@ -145,7 +145,7 @@ common Linux driver API conventions. ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format struct v4l2_format was renamed to struct v4l2_pix_format, while - struct v4l2_format is now the envelopping structure + struct v4l2_format is now the enveloping structure for all format negotiations. 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and @@ -316,7 +316,7 @@ This unnamed version was finally merged into Linux 2.5.46. There are new fields to identify the driver, a new RDS device function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag indicates if the device has any audio connectors, another I/O - capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these + capability V4L2_CAP_ASYNCIO can be flagged. In response to these changes the ``type`` field became a bit set and was merged into the ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced diff --git a/Documentation/userspace-api/media/v4l/io.rst b/Documentation/userspace-api/media/v4l/io.rst index ce0cece6f35f..4b1964df9d73 100644 --- a/Documentation/userspace-api/media/v4l/io.rst +++ b/Documentation/userspace-api/media/v4l/io.rst @@ -17,8 +17,7 @@ read or write will fail at any time. Other methods must be negotiated. To select the streaming I/O method with memory mapped or user buffers applications call the -:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O -method is not defined yet. +:ref:`VIDIOC_REQBUFS` ioctl. Video overlay can be considered another I/O method, although the application does not directly receive the image data. It is selected by @@ -46,6 +45,5 @@ The following sections describe the various I/O methods in more detail. mmap userp dmabuf - async buffer field-order diff --git a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst index 90215313b965..7c8bf160e1c6 100644 --- a/Documentation/userspace-api/media/v4l/libv4l-introduction.rst +++ b/Documentation/userspace-api/media/v4l/libv4l-introduction.rst @@ -136,9 +136,9 @@ V4L2 functions operates like the :c:func:`read()` function. -.. c:function:: void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); +.. c:function:: void *v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - operates like the :c:func:`munmap()` function. + operates like the :c:func:`mmap()` function. .. c:function:: int v4l2_munmap(void *_start, size_t length); diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index fff25357fe86..0bb61fc5bc00 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -12,10 +12,10 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 - pixfmt-meta-d4xx - pixfmt-meta-intel-ipu3 - pixfmt-meta-rkisp1 - pixfmt-meta-uvc - pixfmt-meta-vsp1-hgo - pixfmt-meta-vsp1-hgt - pixfmt-meta-vivid + metafmt-d4xx + metafmt-intel-ipu3 + metafmt-rkisp1 + metafmt-uvc + metafmt-vsp1-hgo + metafmt-vsp1-hgt + metafmt-vivid diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst index 4e437ba97a0e..0686413b16b2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst @@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata Description =========== -Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC +Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC payload headers, following the Microsoft(R) UVC extension proposal [1_]. That means, that the private D4XX metadata, following the standard UVC header, is organised in blocks. D4XX cameras implement several standard block types, @@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary payload header data. D4xx cameras use bulk transfers and only send one payload per frame, therefore their headers cannot be larger than 255 bytes. +This document implements Intel Configuration version 3 [9_]. + Below are proprietary Microsoft style metadata types, used by D4xx cameras, where all fields are in little endian order: @@ -43,10 +45,10 @@ where all fields are in little endian order: * - __u32 ID - 0x80000000 * - __u32 Size - - Size in bytes (currently 56) + - Size in bytes, include ID (all protocol versions: 60) * - __u32 Version - - Version of this structure. The documentation herein corresponds to - version xxx. The version number will be incremented when new fields are + - Version of this structure. The documentation herein covers versions 1, + 2 and 3. The version number will be incremented when new fields are added. * - __u32 Flags - A bitmask of flags: see [2_] below @@ -72,13 +74,17 @@ where all fields are in little endian order: - Bottom border of the AE Region of Interest * - __u32 Preset - Preset selector value, default: 0, unless changed by the user - * - __u32 Laser mode - - 0: off, 1: on + * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_] + - 0: off, 1: on, same as __u32 Laser mode for v1 + * - __u8 RFU byte (v3 only) + - Spare byte for future use + * - __u16 LED Power (v3 only) + - Led power value 0-360 (F416 SKU) * - :cspan:`1` *Capture Timing* * - __u32 ID - 0x80000001 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (all protocol versions: 40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -101,7 +107,7 @@ where all fields are in little endian order: * - __u32 ID - 0x80000002 * - __u32 Size - - Size in bytes (currently 40) + - Size in bytes, include ID (v1:36, v3:40) * - __u32 Version - Version of this structure. The documentation herein corresponds to version xxx. The version number will be incremented when new fields are @@ -124,6 +130,14 @@ where all fields are in little endian order: - Requested frame rate per second * - __u16 Trigger - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger + * - __u16 Calibration count (v3 only) + - Calibration counter, see [4_] below + * - __u8 GPIO input data (v3 only) + - GPIO readout, see [4_] below (Supported from FW 5.12.7.0) + * - __u32 Sub-preset info (v3 only) + - Sub-preset choice information, see [4_] below + * - __u8 reserved (v3 only) + - RFU byte. .. _1: @@ -140,6 +154,8 @@ where all fields are in little endian order: 0x00000010 Exposure priority 0x00000020 AE ROI 0x00000040 Preset + 0x00000080 Emitter mode + 0x00000100 LED Power .. _3: @@ -165,6 +181,8 @@ where all fields are in little endian order: 0x00000040 Framerate 0x00000080 Trigger 0x00000100 Cal count + 0x00000200 GPIO Input Data + 0x00000400 Sub-preset Info .. _5: @@ -211,3 +229,24 @@ Left sensor: :: Fish Eye sensor: :: 1 RAW8 + +.. _8: + +[8] The "Laser mode" has been replaced in version 3 by three different fields. +"Laser" has been renamed to "Emitter" as there are multiple technologies for +camera projectors. As we have another field for "Laser Power" we introduced +"LED Power" for extra emitter. + +The "Laser mode" __u32 fields has been split into: :: + 1 __u8 Emitter mode + 2 __u8 RFU byte + 3 __u16 LED Power + +This is a change between versions 1 and 3. All versions 1, 2 and 3 are backward +compatible with the same data format and they are supported. See [2_] for which +attributes are valid. + +.. _9: + +[9] LibRealSense SDK metadata source: +https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst index 84d81dd7a7b5..84d81dd7a7b5 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst index fa04f00bcd2e..fa04f00bcd2e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst index 784346d14bbd..784346d14bbd 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst index 7173e2c3e245..7173e2c3e245 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst index 8d886feb180c..8d886feb180c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst diff --git a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst index d8830ff605de..d8830ff605de 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst diff --git a/Documentation/userspace-api/media/v4l/mmap.rst b/Documentation/userspace-api/media/v4l/mmap.rst index 16b1e13b029f..a5672573dd6f 100644 --- a/Documentation/userspace-api/media/v4l/mmap.rst +++ b/Documentation/userspace-api/media/v4l/mmap.rst @@ -232,7 +232,7 @@ In the write loop, when the application runs out of free buffers, it must wait until an empty buffer can be dequeued and reused. To enqueue and dequeue a buffer applications use the -:ref:`VIVIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer being mapped, enqueued, full or empty can be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend execution of the application until one or more diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 967fc803ef94..806ed73ac474 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`` @@ -212,14 +217,9 @@ Compressed Formats ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``, ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``, and ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-hevc>`. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. - - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` @@ -237,6 +237,42 @@ 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. + + * .. _V4L2-PIX-FMT-AV1-FRAME: + + - ``V4L2_PIX_FMT_AV1_FRAME`` + - 'AV1F' + - AV1 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement a AV1 + pipeline with the :ref:`stateless_decoder`. Metadata associated with the + frame to decode is required to be passed through the + ``V4L2_CID_STATELESS_AV1_SEQUENCE``, ``V4L2_CID_STATELESS_AV1_FRAME``, + and ``V4L2_CID_STATELESS_AV1_TILE_GROUP_ENTRY`` controls. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-av1>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. .. 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 65520c3af7cf..9f111ed594d2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -220,6 +220,26 @@ the second byte and Y'\ :sub:`7-0` in the third byte. - Y'\ :sub:`7-0` - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-YUVA32: + + - ``V4L2_PIX_FMT_YUVA32`` + - 'YUVA' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - A\ :sub:`7-0` + + * .. _V4L2-PIX-FMT-YUVX32: + + - ``V4L2_PIX_FMT_YUVX32`` + - 'YUVX' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-YUV24: - ``V4L2_PIX_FMT_YUV24`` @@ -237,12 +257,45 @@ 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 ================= These formats, commonly referred to as YUYV or YUY2, subsample the chroma -components horizontally by 2, storing 2 pixels in 4 bytes. +components horizontally by 2, storing 2 pixels in a container. The container +is 32-bits for 8-bit formats, and 64-bits for 10+-bit formats. + +The packed YUYV formats with more than 8 bits per component are stored as four +16-bit little-endian words. Each word's most significant bits contain one +component, and the least significant bits are zero padding. .. raw:: latex @@ -250,7 +303,7 @@ components horizontally by 2, storing 2 pixels in 4 bytes. .. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| -.. flat-table:: Packed YUV 4:2:2 Formats +.. flat-table:: Packed YUV 4:2:2 Formats in 32-bit container :header-rows: 1 :stub-columns: 0 @@ -317,6 +370,46 @@ components horizontally by 2, storing 2 pixels in 4 bytes. - Y'\ :sub:`3` - Cb\ :sub:`2` +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + +.. flat-table:: Packed YUV 4:2:2 Formats in 64-bit container + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Code + - Word 0 + - Word 1 + - Word 2 + - Word 3 + * .. _V4L2-PIX-FMT-Y210: + + - ``V4L2_PIX_FMT_Y210`` + - 'Y210' + + - Y'\ :sub:`0` (bits 15-6) + - Cb\ :sub:`0` (bits 15-6) + - Y'\ :sub:`1` (bits 15-6) + - Cr\ :sub:`0` (bits 15-6) + * .. _V4L2-PIX-FMT-Y212: + + - ``V4L2_PIX_FMT_Y212`` + - 'Y212' + + - Y'\ :sub:`0` (bits 15-4) + - Cb\ :sub:`0` (bits 15-4) + - Y'\ :sub:`1` (bits 15-4) + - Cr\ :sub:`0` (bits 15-4) + * .. _V4L2-PIX-FMT-Y216: + + - ``V4L2_PIX_FMT_Y216`` + - 'Y216' + + - Y'\ :sub:`0` (bits 15-0) + - Cb\ :sub:`0` (bits 15-0) + - Y'\ :sub:`1` (bits 15-0) + - Cr\ :sub:`0` (bits 15-0) + .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 0ff68cd8cf62..886ba7b08d6b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -258,6 +258,43 @@ please make a proposal on the linux-media mailing list. and it is used by various multimedia hardware blocks like GPU, display controllers, ISP and video accelerators. It contains four planes for progressive video. + * .. _V4L2-PIX-FMT-AJPG: + + - ``V4L2_PIX_FMT_AJPG`` + - 'AJPG' + - ASPEED JPEG format used by the aspeed-video driver on Aspeed platforms, + which is generally adapted for remote KVM. + On each frame compression, I will compare the new frame with previous + one to decide which macroblock's data is changed, and only the changed + macroblocks will be compressed. + + The implementation is based on AST2600 A3 datasheet, revision 0.9, which + is not publicly available. Or you can reference Video stream data format + – ASPEED mode compression of SDK_User_Guide which available on + `github <https://github.com/AspeedTech-BMC/openbmc/releases/>`__. + + Decoder's implementation can be found here, + `aspeed_codec <https://github.com/AspeedTech-BMC/aspeed_codec/>`__ + * .. _V4L2-PIX-FMT-MT2110T: + + - ``V4L2_PIX_FMT_MT2110T`` + - 'MT2110T' + - This format is two-planar 10-Bit tile mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for VP9, AV1 + and HEVC. + * .. _V4L2-PIX-FMT-MT2110R: + + - ``V4L2_PIX_FMT_MT2110R`` + - 'MT2110R' + - This format is two-planar 10-Bit raster mode and having similitude with + ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for AVC. + * .. _V4L2-PIX-FMT-HEXTILE: + + - ``V4L2_PIX_FMT_HEXTILE`` + - 'HXTL' + - Compressed format used by Nuvoton NPCM video driver. This format is + defined in Remote Framebuffer Protocol (RFC 6143, chapter 7.7.4 Hextile + Encoding). .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 30f51cd33f99..b71b80d634d6 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -763,6 +763,239 @@ nomenclature that instead use the order of components as seen in a 24- or \normalsize +10 Bits Per Component +===================== + +These formats store a 30-bit RGB triplet with an optional 2 bit alpha in four +bytes. They are named based on the order of the RGB components as seen in a +32-bit word, which is then stored in memory in little endian byte order +(unless otherwise noted by the presence of bit 31 in the 4CC value), and on the +number of bits for each component. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. 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 + :header-rows: 2 + :stub-columns: 0 + + * - Identifier + - Code + - :cspan:`7` Byte 0 in memory + - :cspan:`7` Byte 1 + - :cspan:`7` Byte 2 + - :cspan:`7` Byte 3 + * - + - + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _V4L2-PIX-FMT-RGBX1010102: + + - ``V4L2_PIX_FMT_RGBX1010102`` + - 'RX30' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - x + - x + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + * .. _V4L2-PIX-FMT-RGBA1010102: + + - ``V4L2_PIX_FMT_RGBA1010102`` + - 'RA30' + + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`1` + - a\ :sub:`0` + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + * .. _V4L2-PIX-FMT-ARGB2101010: + + - ``V4L2_PIX_FMT_ARGB2101010`` + - 'AR30' + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + + - a\ :sub:`1` + - a\ :sub:`0` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - 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-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index b6e79e2f8ce4..7c3810ff783c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -60,7 +60,7 @@ Each cell is one byte. G\ :sub:`10low`\ (bits 3--0) - G\ :sub:`12high` - R\ :sub:`13high` - - R\ :sub:`13low`\ (bits 3--2) + - R\ :sub:`13low`\ (bits 7--4) G\ :sub:`12low`\ (bits 3--0) - - start + 12: @@ -82,6 +82,6 @@ Each cell is one byte. G\ :sub:`30low`\ (bits 3--0) - G\ :sub:`32high` - R\ :sub:`33high` - - R\ :sub:`33low`\ (bits 3--2) + - R\ :sub:`33low`\ (bits 7--4) G\ :sub:`32low`\ (bits 3--0) diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 6a387f9df3ba..cf8e4dfbfbd4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -14,7 +14,7 @@ are often referred to as greyscale formats. - In all the tables that follow, bit 7 is the most significant bit in a byte. - Formats are described with the minimum number of pixels needed to create a byte-aligned repeating pattern. `...` indicates repetition of the pattern. - - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at column `x`. - `0` denotes padding bits set to 0. @@ -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 8dff5906639b..1840224faa41 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -109,6 +109,41 @@ All components are stored with the same number of bits per component. - Cb, Cr - No - 16x16 tiles + * - V4L2_PIX_FMT_P010 + - 'P010' + - 10 + - 4:2:0 + - Cb, Cr + - Yes + - Linear + * - V4L2_PIX_FMT_P010_4L4 + - 'T010' + - 10 + - 4:2:0 + - 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_NV15_4L4 + - 'VT15' + - 15 + - 4:2:0 + - Cb, Cr + - Yes + - 4x4 tiles * - V4L2_PIX_FMT_NV16 - 'NV16' - 8 @@ -171,6 +206,7 @@ horizontally. .. _V4L2-PIX-FMT-NV21: .. _V4L2-PIX-FMT-NV12M: .. _V4L2-PIX-FMT-NV21M: +.. _V4L2-PIX-FMT-P010: NV12, NV21, NV12M and NV21M --------------------------- @@ -258,7 +294,9 @@ of the luma plane. .. _V4L2-PIX-FMT-NV12-16L16: .. _V4L2-PIX-FMT-NV12-32L32: .. _V4L2-PIX-FMT-NV12M-8L128: +.. _V4L2-PIX-FMT-NV12-8L128: .. _V4L2-PIX-FMT-NV12M-10BE-8L128: +.. _V4L2-PIX-FMT-NV12-10BE-8L128: .. _V4L2-PIX-FMT-MM21: Tiled NV12 @@ -304,6 +342,9 @@ pixels in 2D 8x128 tiles, and stores tiles linearly in memory. The image height must be aligned to a multiple of 128. The layouts of the luma and chroma planes are identical. +``V4L2_PIX_FMT_NV12_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_8L128`` but stores +two planes in one memory. + ``V4L2_PIX_FMT_NV12M_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores 10 bits pixels in 2D 8x128 tiles, and stores tiles linearly in memory. the data is arranged in big endian order. @@ -319,6 +360,9 @@ byte 2: Y1(bits 3-0) Y2(bits 9-6) byte 3: Y2(bits 5-0) Y3(bits 9-8) byte 4: Y3(bits 7-0) +``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores +two planes in one memory. + ``V4L2_PIX_FMT_MM21`` store luma pixel in 16x32 tiles, and chroma pixels in 16x16 tiles. The line stride must be aligned to a multiple of 16 and the image height must be aligned to a multiple of 32. The number of luma and chroma @@ -341,6 +385,15 @@ two non-contiguous planes. Example V4L2_PIX_FMT_NV12MT memory layout of tiles +.. _V4L2-PIX-FMT-NV15-4L4: + +Tiled NV15 +---------- + +Semi-planar 10-bit YUV 4:2:0 formats, using 4x4 tiling. +All components are packed without any padding between each other. +As a side-effect, each group of 4 components are stored over 5 bytes +(YYYY or UVUV = 4 * 10 bits = 40 bits = 5 bytes). .. _V4L2-PIX-FMT-NV16: .. _V4L2-PIX-FMT-NV61: @@ -519,6 +572,130 @@ number of lines as the luma plane. - Cb\ :sub:`33` - Cr\ :sub:`33` +.. _V4L2_PIX_FMT_P010: +.. _V4L2-PIX-FMT-P010-4L4: + +P010 and tiled P010 +------------------- + +P010 is like NV12 with 10 bits per component, expanded to 16 bits. +Data in the 10 high bits, zeros in the 6 low bits, arranged in little endian order. + +.. flat-table:: Sample 4x4 P010 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` + +.. _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 ======================== @@ -538,6 +715,10 @@ relationship between the luma and chroma line padding and stride. All components are stored with the same number of bits per component. +``V4L2_PIX_FMT_P010_4L4`` stores pixels in 4x4 tiles, and stores tiles linearly +in memory. The line stride must be aligned to multiple of 8 and image height to +a multiple of 4. The layouts of the luma and chroma planes are identical. + .. raw:: latex \small diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 0cbc045d5df6..eb3cd20b0cf2 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -949,6 +949,115 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-2X9-BE: + + - MEDIA_BUS_FMT_RGB666_2X9_BE + - 0x1025 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X18: + + - MEDIA_BUS_FMT_BGR666_1X18 + - 0x1023 + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-RBG888-1X24: - MEDIA_BUS_FMT_RBG888_1X24 @@ -1023,6 +1132,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR666-1X24_CPADHI: + + - MEDIA_BUS_FMT_BGR666_1X24_CPADHI + - 0x1024 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB565-1X24_CPADHI: + + - MEDIA_BUS_FMT_RGB565_1X24_CPADHI + - 0x1022 + - + - + - + - + - + - + - + - + - + - 0 + - 0 + - 0 + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` * .. _MEDIA-BUS-FMT-BGR888-1X24: - MEDIA_BUS_FMT_BGR888_1X24 @@ -1492,6 +1675,80 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB666-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X30-CPADLO + - 0x101e + - + - + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X30-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X30-CPADLO + - 0x101f + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 * .. _MEDIA-BUS-FMT-ARGB888-1X32: - MEDIA_BUS_FMT_ARGB888_1X32 @@ -1669,6 +1926,88 @@ The following table list existing packed 36bit wide RGB formats. - 2 - 1 - 0 + * .. _MEDIA-BUS-FMT-RGB666-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB666_1X36_CPADLO + - 0x1020 + - + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + * .. _MEDIA-BUS-FMT-RGB888-1X36-CPADLO: + + - MEDIA_BUS_FMT_RGB888_1X36_CPADLO + - 0x1021 + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - 0 + - 0 + - 0 + - 0 + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - 0 + - 0 + - 0 + - 0 * .. _MEDIA-BUS-FMT-RGB121212-1X36: - MEDIA_BUS_FMT_RGB121212_1X36 @@ -5901,6 +6240,43 @@ the following codes. - y\ :sub:`2` - y\ :sub:`1` - y\ :sub:`0` + * .. _MEDIA-BUS-FMT-Y16-1X16: + + - MEDIA_BUS_FMT_Y16_1X16 + - 0x202e + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-UYVY8-1X16: - MEDIA_BUS_FMT_UYVY8_1X16 diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst index 53e604bd7d60..15ff0bf7bbe6 100644 --- a/Documentation/userspace-api/media/v4l/user-func.rst +++ b/Documentation/userspace-api/media/v4l/user-func.rst @@ -70,7 +70,9 @@ Function Reference vidioc-subdev-g-crop vidioc-subdev-g-fmt 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/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index ad7a2bf0cf26..cf8ae56a008c 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -11,13 +11,8 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. **Revision 4.5** -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :numbered: :maxdepth: 5 diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index a048a9f6b7b6..49232c9006c2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -116,9 +116,13 @@ than the number requested. - ``flags`` - Specifies additional buffer management attributes. See :ref:`memory-flags`. - * - __u32 - - ``reserved``\ [6] + - ``max_num_buffers`` + - If the V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS capability flag is set + this field indicates the maximum possible number of buffers + for this queue. + * - __u32 + - ``reserved``\ [5] - A place holder for future extensions. Drivers and applications must set the array to zero. diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 551ac9d3c6ef..7f10f0bbcfd3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -71,7 +71,7 @@ overlay devices. - Default cropping rectangle, it shall cover the "whole picture". Assuming pixel aspect 1/1 this could be for example a 640 × 480 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM - centered over the active picture area. The same co-ordinate system + centered over the active picture area. The same coordinate system as for ``bounds`` is used. * - struct :c:type:`v4l2_fract` - ``pixelaspect`` diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index 6eb40073c906..8db103760930 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -332,6 +332,11 @@ call. - 0x0004 - This control event was triggered because the minimum, maximum, step or the default value of the control changed. + * - ``V4L2_EVENT_CTRL_CH_DIMENSIONS`` + - 0x0008 + - This control event was triggered because the dimensions of the + control changed. Note that the number of dimensions remains the + same. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| 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 29971a45a2d4..4d56c0528ad7 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``. + * - __s32 * + - ``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. + * - __s64 * + - ``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 @@ -249,6 +259,50 @@ still cause this situation. - ``p_hdr10_mastering`` - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. + * - struct :c:type:`v4l2_ctrl_hevc_sps` * + - ``p_hevc_sps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_sps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SPS``. + * - struct :c:type:`v4l2_ctrl_hevc_pps` * + - ``p_hevc_pps`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_pps`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_PPS``. + * - struct :c:type:`v4l2_ctrl_hevc_slice_params` * + - ``p_hevc_slice_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_slice_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_hevc_scaling_matrix` * + - ``p_hevc_scaling_matrix`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``. + * - struct :c:type:`v4l2_ctrl_hevc_decode_params` * + - ``p_hevc_decode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_av1_sequence` * + - ``p_av1_sequence`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_sequence`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_SEQUENCE``. + * - struct :c:type:`v4l2_ctrl_av1_tile_group_entry` * + - ``p_av1_tile_group_entry`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_tile_group_entry`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY``. + * - struct :c:type:`v4l2_ctrl_av1_frame` * + - ``p_av1_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FRAME``. + * - struct :c:type:`v4l2_ctrl_av1_film_grain` * + - ``p_av1_film_grain`` + - A pointer to a struct :c:type:`v4l2_ctrl_av1_film_grain`. Valid if this control is + of type ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll_info`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering_display`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array 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-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index 63e23f6f95ee..6c57b8428356 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -244,9 +244,6 @@ specification the ioctl returns an ``EINVAL`` error code. - 0x01000000 - The device supports the :c:func:`read()` and/or :c:func:`write()` 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. diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 88f630252d98..4d38acafe8e1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -525,6 +525,30 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9 frame decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_sequence`, containing AV1 Sequence OBU + decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_tile_group_entry`, containing AV1 Tile Group + OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_frame`, containing AV1 Frame/Frame + Header OBU decoding parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_av1_film_grain`, containing AV1 Film Grain + parameters for stateless video decoders. .. raw:: latex @@ -625,6 +649,14 @@ See also the examples in :ref:`control`. ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or streaming is in progress since most drivers do not support changing the format in that case. + * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY`` + - 0x0800 + - This control is a dynamically sized 1-dimensional array. It + behaves the same as a regular array, except that the number + of elements as reported by the ``elems`` field is between 1 and + ``dims[0]``. So setting the control with a differently sized + array will change the ``elems`` field when the control is + queried afterwards. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index 099fa6695167..0b3a41a45d05 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -120,6 +120,7 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: +.. _V4L2-BUF-CAP-SUPPORTS-MAX-NUM-BUFFERS: .. raw:: latex diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 3703943b412f..c935bacc3bc2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -92,7 +92,10 @@ multiple pads of the same sub-device is not defined. - Frame intervals to be enumerated, from enum :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -104,8 +107,7 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval_enum` - ``pad`` references a non-existing pad, one of the ``code``, - ``width`` or ``height`` fields are invalid for the given pad or the - ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_interval_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, one of the + ``code``, ``width`` or ``height`` fields are invalid for the given pad, or + the ``index`` field is out of bounds. 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 c25a9896df0e..65f0cfeca973 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,32 +84,37 @@ 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 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -109,7 +126,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_frame_size_enum` - ``pad`` references a non-existing pad, the ``code`` is invalid for - the given pad or the ``index`` field is out of bounds. + The struct :c:type:`v4l2_subdev_frame_size_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, the ``code`` + is invalid for the given pad, or the ``index`` field is out of bounds. 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 417f1a19bcc4..3050966b199f 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 @@ -73,7 +88,10 @@ information about the try formats. - ``flags`` - See :ref:`v4l2-subdev-mbus-code-flags` * - __u32 - - ``reserved``\ [7] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [6] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -140,7 +158,6 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct - :c:type:`v4l2_subdev_mbus_code_enum` - ``pad`` references a non-existing pad, or the ``index`` field is out - of bounds. + The struct :c:type:`v4l2_subdev_mbus_code_enum` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + ``index`` field is out of bounds. 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..da4a358ce762 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-client-cap.rst @@ -0,0 +1,103 @@ +.. 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. + +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| + +.. c:type:: v4l2_subdev_client_capability + +.. flat-table:: struct v4l2_subdev_client_capability + :header-rows: 0 + :stub-columns: 0 + :widths: 3 4 20 + + * - __u64 + - ``capabilities`` + - Sub-device client capabilities of the opened device. + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| + +.. 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. + * - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH`` + - The client is aware of the :c:type:`v4l2_subdev_frame_interval` + ``which`` field. If this is not set (which is the default), the + ``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` 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/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index bd15c0a5a66b..92d933631fda 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -96,7 +96,10 @@ modified format should be as close as possible to the original request. - ``rect`` - Crop rectangle boundaries, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -115,10 +118,9 @@ EBUSY ``VIDIOC_SUBDEV_S_CROP`` EINVAL - The struct :c:type:`v4l2_subdev_crop` ``pad`` - references a non-existing pad, the ``which`` field references a - non-existing format, or cropping is not supported on the given - subdev pad. + The struct :c:type:`v4l2_subdev_crop` ``pad`` references a non-existing pad, + the ``which`` field has an unsupported value, or cropping is not supported + on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_CROP`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 7acdbb939d89..4a2b4e4f0152 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -102,7 +102,10 @@ should be as close as possible to the original request. - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for details. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -137,9 +140,8 @@ EBUSY fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT`` EINVAL - The struct :c:type:`v4l2_subdev_format` - ``pad`` references a non-existing pad, or the ``which`` field - references a non-existing format. + The struct :c:type:`v4l2_subdev_format` ``pad`` references a non-existing + pad, or the ``which`` field has an unsupported value. EPERM The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index d7fe7543c506..c8022809ac35 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -58,8 +58,9 @@ struct contains the current frame interval as would be returned by a ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call. -Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been -registered in read-only mode is not allowed. An error is returned and the errno +If the subdev device node has been registered in read-only mode, calls to +``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` are only valid if the ``which`` field is set +to ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno variable is set to ``-EPERM``. Drivers must not return an error solely because the requested interval @@ -90,7 +91,14 @@ the same sub-device is not defined. - ``interval`` - Period, in seconds, between consecutive video frames. * - __u32 - - ``reserved``\ [9] + - ``stream`` + - Stream identifier. + * - __u32 + - ``which`` + - Active or try frame interval, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -109,11 +117,10 @@ EBUSY ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` EINVAL - The struct - :c:type:`v4l2_subdev_frame_interval` - ``pad`` references a non-existing pad, or the pad doesn't support - frame intervals. + The struct :c:type:`v4l2_subdev_frame_interval` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the pad + doesn't support frame intervals. EPERM The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only - subdevice. + subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst new file mode 100644 index 000000000000..26b5004bfe6d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst @@ -0,0 +1,149 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_SUBDEV_G_ROUTING: + +****************************************************** +ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING +****************************************************** + +Name +==== + +VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity. + + +Synopsis +======== + +.. c:macro:: VIDIOC_SUBDEV_G_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)`` + +.. c:macro:: VIDIOC_SUBDEV_S_ROUTING + +``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + Pointer to struct :c:type:`v4l2_subdev_routing`. + + +Description +=========== + +These ioctls are used to get and set the routing in a media entity. +The routing configuration determines the flows of data inside an entity. + +Drivers report their current routing tables using the +``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes +with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and +setting or clearing flags of the ``flags`` field of a +struct :c:type:`v4l2_subdev_route`. + +All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. This +means that the userspace must reconfigure all streams after calling the ioctl +with e.g. ``VIDIOC_SUBDEV_S_FMT``. + +Only subdevices which have both sink and source pads can support routing. + +When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application +provided ``num_routes`` is not big enough to contain all the available routes +the subdevice exposes, drivers return the ENOSPC error code and adjust the +value of the ``num_routes`` field. Application should then reserve enough memory +for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again. + +On a successful ``VIDIOC_SUBDEV_G_ROUTING`` call the driver updates the +``num_routes`` field to reflect the actual number of routes returned. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_routing + +.. flat-table:: struct v4l2_subdev_routing + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``which`` + - Routing table to be accessed, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + * - struct :c:type:`v4l2_subdev_route` + - ``routes[]`` + - Array of struct :c:type:`v4l2_subdev_route` entries + * - __u32 + - ``num_routes`` + - Number of entries of the routes array + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_subdev_route + +.. flat-table:: struct v4l2_subdev_route + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``sink_pad`` + - Sink pad number. + * - __u32 + - ``sink_stream`` + - Sink pad stream number. + * - __u32 + - ``source_pad`` + - Source pad number. + * - __u32 + - ``source_stream`` + - Source pad stream number. + * - __u32 + - ``flags`` + - Route enable/disable flags + :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`. + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Applications and drivers must set + the array to zero. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _v4l2-subdev-routing-flags: + +.. flat-table:: enum v4l2_subdev_routing_flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - V4L2_SUBDEV_ROUTE_FL_ACTIVE + - 0x0001 + - The route is enabled. Set by applications. + +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. + +ENOSPC + The application provided ``num_routes`` is not big enough to contain + all the available routes the subdevice exposes. + +EINVAL + The sink or source pad identifiers reference a non-existing pad or reference + pads of different types (ie. the sink_pad identifiers refers to a source + pad), or the ``which`` field has an unsupported value. + +E2BIG + The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is + larger than the number of routes the driver can handle. diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index f9172a42f036..19e6c3e9c06d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -94,7 +94,10 @@ Selection targets and flags are documented in - ``r`` - Selection rectangle, in pixels. * - __u32 - - ``reserved``\ [8] + - ``stream`` + - Stream identifier. + * - __u32 + - ``reserved``\ [7] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -113,10 +116,9 @@ EBUSY ``VIDIOC_SUBDEV_S_SELECTION`` EINVAL - The struct :c:type:`v4l2_subdev_selection` - ``pad`` references a non-existing pad, the ``which`` field - references a non-existing format, or the selection target is not - supported on the given subdev pad. + The struct :c:type:`v4l2_subdev_selection` ``pad`` references a + non-existing pad, the ``which`` field has an unsupported value, or the + selection target is not supported on the given subdev pad. EPERM The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index 9cbb7a0c354a..3e58aac4ef0b 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -70,6 +70,7 @@ replace symbol V4L2_COLORSPACE_REC709 :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SMPTE170M :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SMPTE240M :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_SRGB :c:type:`v4l2_colorspace` +replace symbol V4L2_COLORSPACE_LAST :c:type:`v4l2_colorspace` # Documented enum v4l2_xfer_func replace symbol V4L2_XFER_FUNC_709 :c:type:`v4l2_xfer_func` @@ -81,6 +82,7 @@ replace symbol V4L2_XFER_FUNC_NONE :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SMPTE2084 :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SMPTE240M :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_SRGB :c:type:`v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_LAST :c:type:`v4l2_xfer_func` # Documented enum v4l2_ycbcr_encoding replace symbol V4L2_YCBCR_ENC_601 :c:type:`v4l2_ycbcr_encoding` @@ -92,6 +94,7 @@ replace symbol V4L2_YCBCR_ENC_SYCC :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_XV601 :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_XV709 :c:type:`v4l2_ycbcr_encoding` replace symbol V4L2_YCBCR_ENC_SMPTE240M :c:type:`v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_LAST :c:type:`v4l2_ycbcr_encoding` # Documented enum v4l2_hsv_encoding replace symbol V4L2_HSV_ENC_180 :c:type:`v4l2_hsv_encoding` @@ -153,6 +156,15 @@ replace symbol V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_VP9_FRAME :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_SEQUENCE :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FILM_GRAIN :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities @@ -379,6 +391,7 @@ replace define V4L2_CTRL_FLAG_VOLATILE control-flags replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags +replace define V4L2_CTRL_FLAG_DYNAMIC_ARRAY control-flags replace define V4L2_CTRL_FLAG_NEXT_CTRL control replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control @@ -505,6 +518,7 @@ replace define V4L2_EVENT_PRIVATE_START event-type replace define V4L2_EVENT_CTRL_CH_VALUE ctrl-changes-flags replace define V4L2_EVENT_CTRL_CH_FLAGS ctrl-changes-flags replace define V4L2_EVENT_CTRL_CH_RANGE ctrl-changes-flags +replace define V4L2_EVENT_CTRL_CH_DIMENSIONS ctrl-changes-flags replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags diff --git a/Documentation/userspace-api/netlink/c-code-gen.rst b/Documentation/userspace-api/netlink/c-code-gen.rst new file mode 100644 index 000000000000..89de42c13350 --- /dev/null +++ b/Documentation/userspace-api/netlink/c-code-gen.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +============================== +Netlink spec C code generation +============================== + +This document describes how Netlink specifications are used to render +C code (uAPI, policies etc.). It also defines the additional properties +allowed in older families by the ``genetlink-c`` protocol level, +to control the naming. + +For brevity this document refers to ``name`` properties of various +objects by the object type. For example ``$attr`` is the value +of ``name`` in an attribute, and ``$family`` is the name of the +family (the global ``name`` property). + +The upper case is used to denote literal values, e.g. ``$family-CMD`` +means the concatenation of ``$family``, a dash character, and the literal +``CMD``. + +The names of ``#defines`` and enum values are always converted to upper case, +and with dashes (``-``) replaced by underscores (``_``). + +If the constructed name is a C keyword, an extra underscore is +appended (``do`` -> ``do_``). + +Globals +======= + +``c-family-name`` controls the name of the ``#define`` for the family +name, default is ``$family-FAMILY-NAME``. + +``c-version-name`` controls the name of the ``#define`` for the version +of the family, default is ``$family-FAMILY-VERSION``. + +``max-by-define`` selects if max values for enums are defined as a +``#define`` rather than inside the enum. + +Definitions +=========== + +Constants +--------- + +Every constant is rendered as a ``#define``. +The name of the constant is ``$family-$constant`` and the value +is rendered as a string or integer according to its type in the spec. + +Enums and flags +--------------- + +Enums are named ``$family-$enum``. The full name can be set directly +or suppressed by specifying the ``enum-name`` property. +Default entry name is ``$family-$enum-$entry``. +If ``name-prefix`` is specified it replaces the ``$family-$enum`` +portion of the entry name. + +Boolean ``render-max`` controls creation of the max values +(which are enabled by default for attribute enums). + +Attributes +========== + +Each attribute set (excluding fractional sets) is rendered as an enum. + +Attribute enums are traditionally unnamed in netlink headers. +If naming is desired ``enum-name`` can be used to specify the name. + +The default attribute name prefix is ``$family-A`` if the name of the set +is the same as the name of the family and ``$family-A-$set`` if the names +differ. The prefix can be overridden by the ``name-prefix`` property of a set. +The rest of the section will refer to the prefix as ``$pfx``. + +Attributes are named ``$pfx-$attribute``. + +Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX`` +which are used for sizing attribute tables. +These two names can be specified directly with the ``attr-cnt-name`` +and ``attr-max-name`` properties respectively. + +If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name`` +will be specified as a ``#define`` rather than an enum value. + +Operations +========== + +Operations are named ``$family-CMD-$operation``. +If ``name-prefix`` is specified it replaces the ``$family-CMD`` +portion of the name. + +Similarly to attribute enums operation enums end with special count and max +attributes. For operations those attributes can be renamed with +``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define`` +is ``true``. + +Multicast groups +================ + +Each multicast group gets a define rendered into the kernel uAPI header. +The name of the define is ``$family-MCGRP-$group``, and can be overwritten +with the ``c-define-name`` property. + +Code generation +=============== + +uAPI header is assumed to come from ``<linux/$family.h>`` in the default header +search path. It can be changed using the ``uapi-header`` global property. diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst new file mode 100644 index 000000000000..70a77387f6c4 --- /dev/null +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -0,0 +1,282 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +================================================================= +Netlink specification support for legacy Generic Netlink families +================================================================= + +This document describes the many additional quirks and properties +required to describe older Generic Netlink families which form +the ``genetlink-legacy`` protocol level. + +Specification +============= + +Globals +------- + +Attributes listed directly at the root level of the spec file. + +version +~~~~~~~ + +Generic Netlink family version, default is 1. + +``version`` has historically been used to introduce family changes +which may break backwards compatibility. Since compatibility breaking changes +are generally not allowed ``version`` is very rarely used. + +Attribute type nests +-------------------- + +New Netlink families should use ``multi-attr`` to define arrays. +Older families (e.g. ``genetlink`` control family) attempted to +define array types reusing attribute type to carry information. + +For reference the ``multi-attr`` array may look like this:: + + [ARRAY-ATTR] + [INDEX (optionally)] + [MEMBER1] + [MEMBER2] + [SOME-OTHER-ATTR] + [ARRAY-ATTR] + [INDEX (optionally)] + [MEMBER1] + [MEMBER2] + +where ``ARRAY-ATTR`` is the array entry type. + +array-nest +~~~~~~~~~~ + +``array-nest`` creates the following structure:: + + [SOME-OTHER-ATTR] + [ARRAY-ATTR] + [ENTRY] + [MEMBER1] + [MEMBER2] + [ENTRY] + [MEMBER1] + [MEMBER2] + +It wraps the entire array in an extra attribute (hence limiting its size +to 64kB). The ``ENTRY`` nests are special and have the index of the entry +as their type instead of normal attribute type. + +type-value +~~~~~~~~~~ + +``type-value`` is a construct which uses attribute types to carry +information about a single object (often used when array is dumped +entry-by-entry). + +``type-value`` can have multiple levels of nesting, for example +genetlink's policy dumps create the following structures:: + + [POLICY-IDX] + [ATTR-IDX] + [POLICY-INFO-ATTR1] + [POLICY-INFO-ATTR2] + +Where the first level of nest has the policy index as it's attribute +type, it contains a single nest which has the attribute index as its +type. Inside the attr-index nest are the policy attributes. Modern +Netlink families should have instead defined this as a flat structure, +the nesting serves no good purpose here. + +Operations +========== + +Enum (message ID) model +----------------------- + +unified +~~~~~~~ + +Modern families use the ``unified`` message ID model, which uses +a single enumeration for all messages within family. Requests and +responses share the same message ID. Notifications have separate +IDs from the same space. For example given the following list +of operations: + +.. code-block:: yaml + + - + name: a + value: 1 + do: ... + - + name: b + do: ... + - + name: c + value: 4 + notify: a + - + name: d + do: ... + +Requests and responses for operation ``a`` will have the ID of 1, +the requests and responses of ``b`` - 2 (since there is no explicit +``value`` it's previous operation ``+ 1``). Notification ``c`` will +use the ID of 4, operation ``d`` 5 etc. + +directional +~~~~~~~~~~~ + +The ``directional`` model splits the ID assignment by the direction of +the message. Messages from and to the kernel can't be confused with +each other so this conserves the ID space (at the cost of making +the programming more cumbersome). + +In this case ``value`` attribute should be specified in the ``request`` +``reply`` sections of the operations (if an operation has both ``do`` +and ``dump`` the IDs are shared, ``value`` should be set in ``do``). +For notifications the ``value`` is provided at the op level but it +only allocates a ``reply`` (i.e. a "from-kernel" ID). Let's look +at an example: + +.. code-block:: yaml + + - + name: a + do: + request: + value: 2 + attributes: ... + reply: + value: 1 + attributes: ... + - + name: b + notify: a + - + name: c + notify: a + value: 7 + - + name: d + do: ... + +In this case ``a`` will use 2 when sending the message to the kernel +and expects message with ID 1 in response. Notification ``b`` allocates +a "from-kernel" ID which is 2. ``c`` allocates "from-kernel" ID of 7. +If operation ``d`` does not set ``values`` explicitly in the spec +it will be allocated 3 for the request (``a`` is the previous operation +with a request section and the value of 2) and 8 for response (``c`` is +the previous operation in the "from-kernel" direction). + +Other quirks +============ + +Structures +---------- + +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. + +members +~~~~~~~ + + - ``name`` - The attribute name of the struct member + - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, + ``s16``, ``s32``, ``s64``, ``string``, ``binary`` or ``bitfield32``. + - ``byte-order`` - ``big-endian`` or ``little-endian`` + - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for + :ref:`attribute definitions <attribute_properties>` + +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 +---------------- + +New Netlink families should never respond to a DO operation with multiple +replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead. + +At the spec level we can define a ``dumps`` property for the ``do``, +perhaps with values of ``combine`` and ``multi-object`` depending +on how the parsing should be implemented (parse into a single reply +vs list of objects i.e. pretty much a dump). diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst new file mode 100644 index 000000000000..c1b6765cc963 --- /dev/null +++ b/Documentation/userspace-api/netlink/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +================ +Netlink Handbook +================ + +Netlink documentation for users. + +.. toctree:: + :maxdepth: 2 + + intro + intro-specs + specs + c-code-gen + genetlink-legacy + netlink-raw + +See also: + - :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` + - :ref:`Documentation/networking/netlink_spec/index.rst <specs>` diff --git a/Documentation/userspace-api/netlink/intro-specs.rst b/Documentation/userspace-api/netlink/intro-specs.rst new file mode 100644 index 000000000000..bada89699455 --- /dev/null +++ b/Documentation/userspace-api/netlink/intro-specs.rst @@ -0,0 +1,159 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +===================================== +Using Netlink protocol specifications +===================================== + +This document is a quick starting guide for using Netlink protocol +specifications. For more detailed description of the specs see :doc:`specs`. + +Simple CLI +========== + +Kernel comes with a simple CLI tool which should be useful when +developing Netlink related code. The tool is implemented in Python +and can use a YAML specification to issue Netlink requests +to the kernel. Only Generic Netlink is supported. + +The tool is located at ``tools/net/ynl/cli.py``. It accepts +a handul of arguments, the most important ones are: + + - ``--spec`` - point to the spec file + - ``--do $name`` / ``--dump $name`` - issue request ``$name`` + - ``--json $attrs`` - provide attributes for the request + - ``--subscribe $group`` - receive notifications from ``$group`` + +YAML specs can be found under ``Documentation/netlink/specs/``. + +Example use:: + + $ ./tools/net/ynl/cli.py --spec Documentation/netlink/specs/ethtool.yaml \ + --do rings-get \ + --json '{"header":{"dev-index": 18}}' + {'header': {'dev-index': 18, 'dev-name': 'eni1np1'}, + 'rx': 0, + 'rx-jumbo': 0, + 'rx-jumbo-max': 4096, + 'rx-max': 4096, + 'rx-mini': 0, + 'rx-mini-max': 4096, + 'tx': 0, + 'tx-max': 4096, + 'tx-push': 0} + +The input arguments are parsed as JSON, while the output is only +Python-pretty-printed. This is because some Netlink types can't +be expressed as JSON directly. If such attributes are needed in +the input some hacking of the script will be necessary. + +The spec and Netlink internals are factored out as a standalone +library - it should be easy to write Python tools / tests reusing +code from ``cli.py``. + +Generating kernel code +====================== + +``tools/net/ynl/ynl-regen.sh`` scans the kernel tree in search of +auto-generated files which need to be updated. Using this tool is the easiest +way to generate / update auto-generated code. + +By default code is re-generated only if spec is newer than the source, +to force regeneration use ``-f``. + +``ynl-regen.sh`` searches for ``YNL-GEN`` in the contents of files +(note that it only scans files in the git index, that is only files +tracked by git!) For instance the ``fou_nl.c`` kernel source contains:: + + /* Documentation/netlink/specs/fou.yaml */ + /* YNL-GEN kernel source */ + +``ynl-regen.sh`` will find this marker and replace the file with +kernel source based on fou.yaml. + +The simplest way to generate a new file based on a spec is to add +the two marker lines like above to a file, add that file to git, +and run the regeneration tool. Grep the tree for ``YNL-GEN`` +to see other examples. + +The code generation itself is performed by ``tools/net/ynl/ynl-gen-c.py`` +but it takes a few arguments so calling it directly for each file +quickly becomes tedious. + +YNL lib +======= + +``tools/net/ynl/lib/`` contains an implementation of a C library +(based on libmnl) which integrates with code generated by +``tools/net/ynl/ynl-gen-c.py`` to create easy to use netlink wrappers. + +YNL basics +---------- + +The YNL library consists of two parts - the generic code (functions +prefix by ``ynl_``) and per-family auto-generated code (prefixed +with the name of the family). + +To create a YNL socket call ynl_sock_create() passing the family +struct (family structs are exported by the auto-generated code). +ynl_sock_destroy() closes the socket. + +YNL requests +------------ + +Steps for issuing YNL requests are best explained on an example. +All the functions and types in this example come from the auto-generated +code (for the netdev family in this case): + +.. code-block:: c + + // 0. Request and response pointers + struct netdev_dev_get_req *req; + struct netdev_dev_get_rsp *d; + + // 1. Allocate a request + req = netdev_dev_get_req_alloc(); + // 2. Set request parameters (as needed) + netdev_dev_get_req_set_ifindex(req, ifindex); + + // 3. Issues the request + d = netdev_dev_get(ys, req); + // 4. Free the request arguments + netdev_dev_get_req_free(req); + // 5. Error check (the return value from step 3) + if (!d) { + // 6. Print the YNL-generated error + fprintf(stderr, "YNL: %s\n", ys->err.msg); + return -1; + } + + // ... do stuff with the response @d + + // 7. Free response + netdev_dev_get_rsp_free(d); + +YNL dumps +--------- + +Performing dumps follows similar pattern as requests. +Dumps return a list of objects terminated by a special marker, +or NULL on error. Use ``ynl_dump_foreach()`` to iterate over +the result. + +YNL notifications +----------------- + +YNL lib supports using the same socket for notifications and +requests. In case notifications arrive during processing of a request +they are queued internally and can be retrieved at a later time. + +To subscribed to notifications use ``ynl_subscribe()``. +The notifications have to be read out from the socket, +``ynl_socket_get_fd()`` returns the underlying socket fd which can +be plugged into appropriate asynchronous IO API like ``poll``, +or ``select``. + +Notifications can be retrieved using ``ynl_ntf_dequeue()`` and have +to be freed using ``ynl_ntf_free()``. Since we don't know the notification +type upfront the notifications are returned as ``struct ynl_ntf_base_type *`` +and user is expected to cast them to the appropriate full type based +on the ``cmd`` member. diff --git a/Documentation/userspace-api/netlink/intro.rst b/Documentation/userspace-api/netlink/intro.rst new file mode 100644 index 000000000000..aacffade8f84 --- /dev/null +++ b/Documentation/userspace-api/netlink/intro.rst @@ -0,0 +1,687 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +======================= +Introduction to Netlink +======================= + +Netlink is often described as an ioctl() replacement. +It aims to replace fixed-format C structures as supplied +to ioctl() with a format which allows an easy way to add +or extended the arguments. + +To achieve this Netlink uses a minimal fixed-format metadata header +followed by multiple attributes in the TLV (type, length, value) format. + +Unfortunately the protocol has evolved over the years, in an organic +and undocumented fashion, making it hard to coherently explain. +To make the most practical sense this document starts by describing +netlink as it is used today and dives into more "historical" uses +in later sections. + +Opening a socket +================ + +Netlink communication happens over sockets, a socket needs to be +opened first: + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + +The use of sockets allows for a natural way of exchanging information +in both directions (to and from the kernel). The operations are still +performed synchronously when applications send() the request but +a separate recv() system call is needed to read the reply. + +A very simplified flow of a Netlink "call" will therefore look +something like: + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + + /* format the request */ + send(fd, &request, sizeof(request)); + n = recv(fd, &response, RSP_BUFFER_SIZE); + /* interpret the response */ + +Netlink also provides natural support for "dumping", i.e. communicating +to user space all objects of a certain type (e.g. dumping all network +interfaces). + +.. code-block:: c + + fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); + + /* format the dump request */ + send(fd, &request, sizeof(request)); + while (1) { + n = recv(fd, &buffer, RSP_BUFFER_SIZE); + /* one recv() call can read multiple messages, hence the loop below */ + for (nl_msg in buffer) { + if (nl_msg.nlmsg_type == NLMSG_DONE) + goto dump_finished; + /* process the object */ + } + } + dump_finished: + +The first two arguments of the socket() call require little explanation - +it is opening a Netlink socket, with all headers provided by the user +(hence NETLINK, RAW). The last argument is the protocol within Netlink. +This field used to identify the subsystem with which the socket will +communicate. + +Classic vs Generic Netlink +-------------------------- + +Initial implementation of Netlink depended on a static allocation +of IDs to subsystems and provided little supporting infrastructure. +Let us refer to those protocols collectively as **Classic Netlink**. +The list of them is defined on top of the ``include/uapi/linux/netlink.h`` +file, they include among others - general networking (NETLINK_ROUTE), +iSCSI (NETLINK_ISCSI), and audit (NETLINK_AUDIT). + +**Generic Netlink** (introduced in 2005) allows for dynamic registration of +subsystems (and subsystem ID allocation), introspection and simplifies +implementing the kernel side of the interface. + +The following section describes how to use Generic Netlink, as the +number of subsystems using Generic Netlink outnumbers the older +protocols by an order of magnitude. There are also no plans for adding +more Classic Netlink protocols to the kernel. +Basic information on how communicating with core networking parts of +the Linux kernel (or another of the 20 subsystems using Classic +Netlink) differs from Generic Netlink is provided later in this document. + +Generic Netlink +=============== + +In addition to the Netlink fixed metadata header each Netlink protocol +defines its own fixed metadata header. (Similarly to how network +headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.) + +A Netlink message always starts with struct nlmsghdr, which is followed +by a protocol-specific header. In case of Generic Netlink the protocol +header is struct genlmsghdr. + +The practical meaning of the fields in case of Generic Netlink is as follows: + +.. code-block:: c + + struct nlmsghdr { + __u32 nlmsg_len; /* Length of message including headers */ + __u16 nlmsg_type; /* Generic Netlink Family (subsystem) ID */ + __u16 nlmsg_flags; /* Flags - request or dump */ + __u32 nlmsg_seq; /* Sequence number */ + __u32 nlmsg_pid; /* Port ID, set to 0 */ + }; + struct genlmsghdr { + __u8 cmd; /* Command, as defined by the Family */ + __u8 version; /* Irrelevant, set to 1 */ + __u16 reserved; /* Reserved, set to 0 */ + }; + /* TLV attributes follow... */ + +In Classic Netlink :c:member:`nlmsghdr.nlmsg_type` used to identify +which operation within the subsystem the message was referring to +(e.g. get information about a netdev). Generic Netlink needs to mux +multiple subsystems in a single protocol so it uses this field to +identify the subsystem, and :c:member:`genlmsghdr.cmd` identifies +the operation instead. (See :ref:`res_fam` for +information on how to find the Family ID of the subsystem of interest.) +Note that the first 16 values (0 - 15) of this field are reserved for +control messages both in Classic Netlink and Generic Netlink. +See :ref:`nl_msg_type` for more details. + +There are 3 usual types of message exchanges on a Netlink socket: + + - performing a single action (``do``); + - dumping information (``dump``); + - getting asynchronous notifications (``multicast``). + +Classic Netlink is very flexible and presumably allows other types +of exchanges to happen, but in practice those are the three that get +used. + +Asynchronous notifications are sent by the kernel and received by +the user sockets which subscribed to them. ``do`` and ``dump`` requests +are initiated by the user. :c:member:`nlmsghdr.nlmsg_flags` should +be set as follows: + + - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK`` + - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP`` + +:c:member:`nlmsghdr.nlmsg_seq` should be a set to a monotonically +increasing value. The value gets echoed back in responses and doesn't +matter in practice, but setting it to an increasing value for each +message sent is considered good hygiene. The purpose of the field is +matching responses to requests. Asynchronous notifications will have +:c:member:`nlmsghdr.nlmsg_seq` of ``0``. + +:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. +This field can be set to ``0`` when talking to the kernel. +See :ref:`nlmsg_pid` for the (uncommon) uses of the field. + +The expected use for :c:member:`genlmsghdr.version` was to allow +versioning of the APIs provided by the subsystems. No subsystem to +date made significant use of this field, so setting it to ``1`` seems +like a safe bet. + +.. _nl_msg_type: + +Netlink message types +--------------------- + +As previously mentioned :c:member:`nlmsghdr.nlmsg_type` carries +protocol specific values but the first 16 identifiers are reserved +(first subsystem specific message type should be equal to +``NLMSG_MIN_TYPE`` which is ``0x10``). + +There are only 4 Netlink control messages defined: + + - ``NLMSG_NOOP`` - ignore the message, not used in practice; + - ``NLMSG_ERROR`` - carries the return code of an operation; + - ``NLMSG_DONE`` - marks the end of a dump; + - ``NLMSG_OVERRUN`` - socket buffer has overflown, not used to date. + +``NLMSG_ERROR`` and ``NLMSG_DONE`` are of practical importance. +They carry return codes for operations. Note that unless +the ``NLM_F_ACK`` flag is set on the request Netlink will not respond +with ``NLMSG_ERROR`` if there is no error. To avoid having to special-case +this quirk it is recommended to always set ``NLM_F_ACK``. + +The format of ``NLMSG_ERROR`` is described by struct nlmsgerr:: + + ---------------------------------------------- + | struct nlmsghdr - response header | + ---------------------------------------------- + | int error | + ---------------------------------------------- + | struct nlmsghdr - original request header | + ---------------------------------------------- + | ** optionally (1) payload of the request | + ---------------------------------------------- + | ** optionally (2) extended ACK | + ---------------------------------------------- + +There are two instances of struct nlmsghdr here, first of the response +and second of the request. ``NLMSG_ERROR`` carries the information about +the request which led to the error. This could be useful when trying +to match requests to responses or re-parse the request to dump it into +logs. + +The payload of the request is not echoed in messages reporting success +(``error == 0``) or if ``NETLINK_CAP_ACK`` setsockopt() was set. +The latter is common +and perhaps recommended as having to read a copy of every request back +from the kernel is rather wasteful. The absence of request payload +is indicated by ``NLM_F_CAPPED`` in :c:member:`nlmsghdr.nlmsg_flags`. + +The second optional element of ``NLMSG_ERROR`` are the extended ACK +attributes. See :ref:`ext_ack` for more details. The presence +of extended ACK is indicated by ``NLM_F_ACK_TLVS`` in +:c:member:`nlmsghdr.nlmsg_flags`. + +``NLMSG_DONE`` is simpler, the request is never echoed but the extended +ACK attributes may be present:: + + ---------------------------------------------- + | struct nlmsghdr - response header | + ---------------------------------------------- + | int error | + ---------------------------------------------- + | ** optionally extended ACK | + ---------------------------------------------- + +Note that some implementations may issue custom ``NLMSG_DONE`` messages +in reply to ``do`` action requests. In that case the payload is +implementation-specific and may also be absent. + +.. _res_fam: + +Resolving the Family ID +----------------------- + +This section explains how to find the Family ID of a subsystem. +It also serves as an example of Generic Netlink communication. + +Generic Netlink is itself a subsystem exposed via the Generic Netlink API. +To avoid a circular dependency Generic Netlink has a statically allocated +Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``). +The Generic Netlink family implements a command used to find out information +about other families (``CTRL_CMD_GETFAMILY``). + +To get information about the Generic Netlink family named for example +``"test1"`` we need to send a message on the previously opened Generic Netlink +socket. The message should target the Generic Netlink Family (1), be a +``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). A ``dump`` version of this +call would make the kernel respond with information about *all* the families +it knows about. Last but not least the name of the family in question has +to be specified (4) as an attribute with the appropriate type:: + + struct nlmsghdr: + __u32 nlmsg_len: 32 + __u16 nlmsg_type: GENL_ID_CTRL // (1) + __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK // (2) + __u32 nlmsg_seq: 1 + __u32 nlmsg_pid: 0 + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_GETFAMILY // (3) + __u8 version: 2 /* or 1, doesn't matter */ + __u16 reserved: 0 + + struct nlattr: // (4) + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + char data: \0\0 + +The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len` +and :c:member:`nlattr.nla_len`) always *include* the header. +Attribute headers in netlink must be aligned to 4 bytes from the start +of the message, hence the extra ``\0\0`` after ``CTRL_ATTR_FAMILY_NAME``. +The attribute lengths *exclude* the padding. + +If the family is found kernel will reply with two messages, the response +with all the information about the family:: + + /* Message #1 - reply */ + struct nlmsghdr: + __u32 nlmsg_len: 136 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: 0 + __u32 nlmsg_seq: 1 /* echoed from our request */ + __u32 nlmsg_pid: 5831 /* The PID of our user space process */ + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_GETFAMILY + __u8 version: 2 + __u16 reserved: 0 + + struct nlattr: + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + data: \0\0 + + struct nlattr: + __u16 nla_len: 6 + __u16 nla_type: CTRL_ATTR_FAMILY_ID + __u16: 123 /* The Family ID we are after */ + + (padding:) + char data: \0\0 + + struct nlattr: + __u16 nla_len: 9 + __u16 nla_type: CTRL_ATTR_FAMILY_VERSION + __u16: 1 + + /* ... etc, more attributes will follow. */ + +And the error code (success) since ``NLM_F_ACK`` had been set on the request:: + + /* Message #2 - the ACK */ + struct nlmsghdr: + __u32 nlmsg_len: 36 + __u16 nlmsg_type: NLMSG_ERROR + __u16 nlmsg_flags: NLM_F_CAPPED /* There won't be a payload */ + __u32 nlmsg_seq: 1 /* echoed from our request */ + __u32 nlmsg_pid: 5831 /* The PID of our user space process */ + + int error: 0 + + struct nlmsghdr: /* Copy of the request header as we sent it */ + __u32 nlmsg_len: 32 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK + __u32 nlmsg_seq: 1 + __u32 nlmsg_pid: 0 + +The order of attributes (struct nlattr) is not guaranteed so the user +has to walk the attributes and parse them. + +Note that Generic Netlink sockets are not associated or bound to a single +family. A socket can be used to exchange messages with many different +families, selecting the recipient family on message-by-message basis using +the :c:member:`nlmsghdr.nlmsg_type` field. + +.. _ext_ack: + +Extended ACK +------------ + +Extended ACK controls reporting of additional error/warning TLVs +in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages. To maintain backward +compatibility this feature has to be explicitly enabled by setting +the ``NETLINK_EXT_ACK`` setsockopt() to ``1``. + +Types of extended ack attributes are defined in enum nlmsgerr_attrs. +The most commonly used attributes are ``NLMSGERR_ATTR_MSG``, +``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MISS_*``. + +``NLMSGERR_ATTR_MSG`` carries a message in English describing +the encountered problem. These messages are far more detailed +than what can be expressed thru standard UNIX error codes. + +``NLMSGERR_ATTR_OFFS`` points to the attribute which caused the problem. + +``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATTR_MISS_NEST`` +inform about a missing attribute. + +Extended ACKs can be reported on errors as well as in case of success. +The latter should be treated as a warning. + +Extended ACKs greatly improve the usability of Netlink and should +always be enabled, appropriately parsed and reported to the user. + +Advanced topics +=============== + +Dump consistency +---------------- + +Some of the data structures kernel uses for storing objects make +it hard to provide an atomic snapshot of all the objects in a dump +(without impacting the fast-paths updating them). + +Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump +(including the ``NLMSG_DONE`` message) if the dump was interrupted and +may be inconsistent (e.g. missing objects). User space should retry +the dump if it sees the flag set. + +Introspection +------------- + +The basic introspection abilities are enabled by access to the Family +object as reported in :ref:`res_fam`. User can query information about +the Generic Netlink family, including which operations are supported +by the kernel and what attributes the kernel understands. +Family information includes the highest ID of an attribute kernel can parse, +a separate command (``CTRL_CMD_GETPOLICY``) provides detailed information +about supported attributes, including ranges of values the kernel accepts. + +Querying family information is useful in cases when user space needs +to make sure that the kernel has support for a feature before issuing +a request. + +.. _nlmsg_pid: + +nlmsg_pid +--------- + +:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. +It is referred to as Port ID, sometimes Process ID because for historical +reasons if the application does not select (bind() to) an explicit Port ID +kernel will automatically assign it the ID equal to its Process ID +(as reported by the getpid() system call). + +Similarly to the bind() semantics of the TCP/IP network protocols the value +of zero means "assign automatically", hence it is common for applications +to leave the :c:member:`nlmsghdr.nlmsg_pid` field initialized to ``0``. + +The field is still used today in rare cases when kernel needs to send +a unicast notification. User space application can use bind() to associate +its socket with a specific PID, it then communicates its PID to the kernel. +This way the kernel can reach the specific user space process. + +This sort of communication is utilized in UMH (User Mode Helper)-like +scenarios when kernel needs to trigger user space processing or ask user +space for a policy decision. + +Multicast notifications +----------------------- + +One of the strengths of Netlink is the ability to send event notifications +to user space. This is a unidirectional form of communication (kernel -> +user) and does not involve any control messages like ``NLMSG_ERROR`` or +``NLMSG_DONE``. + +For example the Generic Netlink family itself defines a set of multicast +notifications about registered families. When a new family is added the +sockets subscribed to the notifications will get the following message:: + + struct nlmsghdr: + __u32 nlmsg_len: 136 + __u16 nlmsg_type: GENL_ID_CTRL + __u16 nlmsg_flags: 0 + __u32 nlmsg_seq: 0 + __u32 nlmsg_pid: 0 + + struct genlmsghdr: + __u8 cmd: CTRL_CMD_NEWFAMILY + __u8 version: 2 + __u16 reserved: 0 + + struct nlattr: + __u16 nla_len: 10 + __u16 nla_type: CTRL_ATTR_FAMILY_NAME + char data: test1\0 + + (padding:) + data: \0\0 + + struct nlattr: + __u16 nla_len: 6 + __u16 nla_type: CTRL_ATTR_FAMILY_ID + __u16: 123 /* The Family ID we are after */ + + (padding:) + char data: \0\0 + + struct nlattr: + __u16 nla_len: 9 + __u16 nla_type: CTRL_ATTR_FAMILY_VERSION + __u16: 1 + + /* ... etc, more attributes will follow. */ + +The notification contains the same information as the response +to the ``CTRL_CMD_GETFAMILY`` request. + +The Netlink headers of the notification are mostly 0 and irrelevant. +The :c:member:`nlmsghdr.nlmsg_seq` may be either zero or a monotonically +increasing notification sequence number maintained by the family. + +To receive notifications the user socket must subscribe to the relevant +notification group. Much like the Family ID, the Group ID for a given +multicast group is dynamic and can be found inside the Family information. +The ``CTRL_ATTR_MCAST_GROUPS`` attribute contains nests with names +(``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL_ATTR_MCAST_GRP_ID``) of +the groups family. + +Once the Group ID is known a setsockopt() call adds the socket to the group: + +.. code-block:: c + + unsigned int group_id; + + /* .. find the group ID... */ + + setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, + &group_id, sizeof(group_id)); + +The socket will now receive notifications. + +It is recommended to use separate sockets for receiving notifications +and sending requests to the kernel. The asynchronous nature of notifications +means that they may get mixed in with the responses making the message +handling much harder. + +Buffer sizing +------------- + +Netlink sockets are datagram sockets rather than stream sockets, +meaning that each message must be received in its entirety by a single +recv()/recvmsg() system call. If the buffer provided by the user is too +short, the message will be truncated and the ``MSG_TRUNC`` flag set +in struct msghdr (struct msghdr is the second argument +of the recvmsg() system call, *not* a Netlink header). + +Upon truncation the remaining part of the message is discarded. + +Netlink expects that the user buffer will be at least 8kB or a page +size of the CPU architecture, whichever is bigger. Particular Netlink +families may, however, require a larger buffer. 32kB buffer is recommended +for most efficient handling of dumps (larger buffer fits more dumped +objects and therefore fewer recvmsg() calls are needed). + +.. _classic_netlink: + +Classic Netlink +=============== + +The main differences between Classic and Generic Netlink are the dynamic +allocation of subsystem identifiers and availability of introspection. +In theory the protocol does not differ significantly, however, in practice +Classic Netlink experimented with concepts which were abandoned in Generic +Netlink (really, they usually only found use in a small corner of a single +subsystem). This section is meant as an explainer of a few of such concepts, +with the explicit goal of giving the Generic Netlink +users the confidence to ignore them when reading the uAPI headers. + +Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family, +which covers much of the configuration of the Linux networking stack. +Real documentation of that family, deserves a chapter (or a book) of its own. + +Families +-------- + +Netlink refers to subsystems as families. This is a remnant of using +sockets and the concept of protocol families, which are part of message +demultiplexing in ``NETLINK_ROUTE``. + +Sadly every layer of encapsulation likes to refer to whatever it's carrying +as "families" making the term very confusing: + + 1. AF_NETLINK is a bona fide socket protocol family + 2. AF_NETLINK's documentation refers to what comes after its own + header (struct nlmsghdr) in a message as a "Family Header" + 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows + struct nlmsghdr), yet it also calls its users "Families". + +Note that the Generic Netlink Family IDs are in a different "ID space" +and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO`` +has the Classic Netlink protocol ID of 21 which Generic Netlink will +happily allocate to one of its families as well). + +Strict checking +--------------- + +The ``NETLINK_GET_STRICT_CHK`` socket option enables strict input checking +in ``NETLINK_ROUTE``. It was needed because historically kernel did not +validate the fields of structures it didn't process. This made it impossible +to start using those fields later without risking regressions in applications +which initialized them incorrectly or not at all. + +``NETLINK_GET_STRICT_CHK`` declares that the application is initializing +all fields correctly. It also opts into validating that message does not +contain trailing data and requests that kernel rejects attributes with +type higher than largest attribute type known to the kernel. + +``NETLINK_GET_STRICT_CHK`` is not used outside of ``NETLINK_ROUTE``. + +Unknown attributes +------------------ + +Historically Netlink ignored all unknown attributes. The thinking was that +it would free the application from having to probe what kernel supports. +The application could make a request to change the state and check which +parts of the request "stuck". + +This is no longer the case for new Generic Netlink families and those opting +in to strict checking. See enum netlink_validation for validation types +performed. + +Fixed metadata and structures +----------------------------- + +Classic Netlink made liberal use of fixed-format structures within +the messages. Messages would commonly have a structure with +a considerable number of fields after struct nlmsghdr. It was also +common to put structures with multiple members inside attributes, +without breaking each member into an attribute of its own. + +This has caused problems with validation and extensibility and +therefore using binary structures is actively discouraged for new +attributes. + +Request types +------------- + +``NETLINK_ROUTE`` categorized requests into 4 types ``NEW``, ``DEL``, ``GET``, +and ``SET``. Each object can handle all or some of those requests +(objects being netdevs, routes, addresses, qdiscs etc.) Request type +is defined by the 2 lowest bits of the message type, so commands for +new objects would always be allocated with a stride of 4. + +Each object would also have its own fixed metadata shared by all request +types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address +requests, struct tcmsg for qdisc requests). + +Even though other protocols and Generic Netlink commands often use +the same verbs in their message names (``GET``, ``SET``) the concept +of request types did not find wider adoption. + +Notification echo +----------------- + +``NLM_F_ECHO`` requests for notifications resulting from the request +to be queued onto the requesting socket. This is useful to discover +the impact of the request. + +Note that this feature is not universally implemented. + +Other request-type-specific flags +--------------------------------- + +Classic Netlink defined various flags for its ``GET``, ``NEW`` +and ``DEL`` requests in the upper byte of nlmsg_flags in struct nlmsghdr. +Since request types have not been generalized the request type specific +flags are rarely used (and considered deprecated for new families). + +For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into +``NLM_F_DUMP``, and not used separately. ``NLM_F_ATOMIC`` is never used. + +For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK`` +only by FDB some operations. + +The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately, +the meaning is not crystal clear. The following description is based on the +best guess of the intention of the authors, and in practice all families +stray from it in one way or another. ``NLM_F_REPLACE`` asks to replace +an existing object, if no matching object exists the operation should fail. +``NLM_F_EXCL`` has the opposite semantics and only succeeds if object already +existed. +``NLM_F_CREATE`` asks for the object to be created if it does not +exist, it can be combined with ``NLM_F_REPLACE`` and ``NLM_F_EXCL``. + +A comment in the main Netlink uAPI header states:: + + 4.4BSD ADD NLM_F_CREATE|NLM_F_EXCL + 4.4BSD CHANGE NLM_F_REPLACE + + True CHANGE NLM_F_CREATE|NLM_F_REPLACE + Append NLM_F_CREATE + Check NLM_F_EXCL + +which seems to indicate that those flags predate request types. +``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was initially used instead +of ``SET`` commands. +``NLM_F_EXCL`` without ``NLM_F_CREATE`` was used to check if object exists +without creating it, presumably predating ``GET`` commands. + +``NLM_F_APPEND`` indicates that if one key can have multiple objects associated +with it (e.g. multiple next-hop objects for a route) the new object should be +added to the list rather than replacing the entire list. + +uAPI reference +============== + +.. kernel-doc:: include/uapi/linux/netlink.h diff --git a/Documentation/userspace-api/netlink/netlink-raw.rst b/Documentation/userspace-api/netlink/netlink-raw.rst new file mode 100644 index 000000000000..1990eea772d0 --- /dev/null +++ b/Documentation/userspace-api/netlink/netlink-raw.rst @@ -0,0 +1,194 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +====================================================== +Netlink specification support for raw Netlink families +====================================================== + +This document describes the additional properties required by raw Netlink +families such as ``NETLINK_ROUTE`` which use the ``netlink-raw`` protocol +specification. + +Specification +============= + +The netlink-raw schema extends the :doc:`genetlink-legacy <genetlink-legacy>` +schema with properties that are needed to specify the protocol numbers and +multicast IDs used by raw netlink families. See :ref:`classic_netlink` for more +information. The raw netlink families also make use of type-specific +sub-messages. + +Globals +------- + +protonum +~~~~~~~~ + +The ``protonum`` property is used to specify the protocol number to use when +opening a netlink socket. + +.. code-block:: yaml + + # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + + name: rt-addr + protocol: netlink-raw + protonum: 0 # part of the NETLINK_ROUTE protocol + + +Multicast group properties +-------------------------- + +value +~~~~~ + +The ``value`` property is used to specify the group ID to use for multicast +group registration. + +.. code-block:: yaml + + mcast-groups: + list: + - + name: rtnlgrp-ipv4-ifaddr + value: 5 + - + name: rtnlgrp-ipv6-ifaddr + value: 9 + - + name: rtnlgrp-mctp-ifaddr + value: 34 + +Sub-messages +------------ + +Several raw netlink families such as +:doc:`rt_link<../../networking/netlink_spec/rt_link>` and +:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an +abstraction to carry module specific information. + +Conceptually it looks as follows:: + + [OUTER NEST OR MESSAGE LEVEL] + [GENERIC ATTR 1] + [GENERIC ATTR 2] + [GENERIC ATTR 3] + [GENERIC ATTR - wrapper] + [MODULE SPECIFIC ATTR 1] + [MODULE SPECIFIC ATTR 2] + +The ``GENERIC ATTRs`` at the outer level are defined in the core (or rt_link or +core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their +own information wrapped in the ``GENERIC ATTR - wrapper``. Even though the +example above shows attributes nesting inside the wrapper, the modules generally +have full freedom to define the format of the nest. In practice the payload of +the wrapper attr has very similar characteristics to a netlink message. It may +contain a fixed header / structure, netlink attributes, or both. Because of +those shared characteristics we refer to the payload of the wrapper attribute as +a sub-message. + +A sub-message attribute uses the value of another attribute as a selector key to +choose the right sub-message format. For example if the following attribute has +already been decoded: + +.. code-block:: json + + { "kind": "gre" } + +and we encounter the following attribute spec: + +.. code-block:: yaml + + - + name: data + type: sub-message + sub-message: linkinfo-data-msg + selector: kind + +Then we look for a sub-message definition called ``linkinfo-data-msg`` and use +the value of the ``kind`` attribute i.e. ``gre`` as the key to choose the +correct format for the sub-message: + +.. code-block:: yaml + + sub-messages: + name: linkinfo-data-msg + formats: + - + value: bridge + attribute-set: linkinfo-bridge-attrs + - + value: gre + attribute-set: linkinfo-gre-attrs + - + value: geneve + attribute-set: linkinfo-geneve-attrs + +This would decode the attribute value as a sub-message with the attribute-set +called ``linkinfo-gre-attrs`` as the attribute space. + +A sub-message can have an optional ``fixed-header`` followed by zero or more +attributes from an ``attribute-set``. For example the following +``tc-options-msg`` sub-message defines message formats that use a mixture of +``fixed-header``, ``attribute-set`` or both together: + +.. code-block:: yaml + + sub-messages: + - + name: tc-options-msg + formats: + - + value: bfifo + fixed-header: tc-fifo-qopt + - + value: cake + attribute-set: tc-cake-attrs + - + value: netem + fixed-header: tc-netem-qopt + attribute-set: tc-netem-attrs + +Note that a selector attribute must appear in a netlink message before any +sub-message attributes that depend on it. + +If an attribute such as ``kind`` is defined at more than one nest level, then a +sub-message selector will be resolved using the value 'closest' to the selector. +For example, if the same attribute name is defined in a nested ``attribute-set`` +alongside a sub-message selector and also in a top level ``attribute-set``, then +the selector will be resolved using the value 'closest' to the selector. If the +value is not present in the message at the same level as defined in the spec +then this is an error. + +Nested struct definitions +------------------------- + +Many raw netlink families such as :doc:`tc<../../networking/netlink_spec/tc>` +make use of nested struct definitions. The ``netlink-raw`` schema makes it +possible to embed a struct within a struct definition using the ``struct`` +property. For example, the following struct definition embeds the +``tc-ratespec`` struct definition for both the ``rate`` and the ``peakrate`` +members of ``struct tc-tbf-qopt``. + +.. code-block:: yaml + + - + name: tc-tbf-qopt + type: struct + members: + - + name: rate + type: binary + struct: tc-ratespec + - + name: peakrate + type: binary + struct: tc-ratespec + - + name: limit + type: u32 + - + name: buffer + type: u32 + - + name: mtu + type: u32 diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst new file mode 100644 index 000000000000..1b50d97d8d7c --- /dev/null +++ b/Documentation/userspace-api/netlink/specs.rst @@ -0,0 +1,467 @@ +.. SPDX-License-Identifier: BSD-3-Clause + +========================================= +Netlink protocol specifications (in YAML) +========================================= + +Netlink protocol specifications are complete, machine readable descriptions of +Netlink protocols written in YAML. The goal of the specifications is to allow +separating Netlink parsing from user space logic and minimize the amount of +hand written Netlink code for each new family, command, attribute. +Netlink specs should be complete and not depend on any other spec +or C header file, making it easy to use in languages which can't include +kernel headers directly. + +Internally kernel uses the YAML specs to generate: + + - the C uAPI header + - documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>` + - policy tables for input attribute validation + - operation tables + +YAML specifications can be found under ``Documentation/netlink/specs/`` + +This document describes details of the schema. +See :doc:`intro-specs` for a practical starting guide. + +All specs must be licensed under +``((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)`` +to allow for easy adoption in user space code. + +Compatibility levels +==================== + +There are four schema levels for Netlink specs, from the simplest used +by new families to the most complex covering all the quirks of the old ones. +Each next level inherits the attributes of the previous level, meaning that +user capable of parsing more complex ``genetlink`` schemas is also compatible +with simpler ones. The levels are: + + - ``genetlink`` - most streamlined, should be used by all new families + - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing + customization of define and enum type and value names; this schema should + be equivalent to ``genetlink`` for all implementations which don't interact + directly with C uAPI headers + - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of + all old genetlink families, strange attribute formats, binary structures etc. + - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols + such as ``NETLINK_ROUTE`` + +The definition of the schemas (in ``jsonschema``) can be found +under ``Documentation/netlink/``. + +Schema structure +================ + +YAML schema has the following conceptual sections: + + - globals + - definitions + - attributes + - operations + - multicast groups + +Most properties in the schema accept (or in fact require) a ``doc`` +sub-property documenting the defined object. + +The following sections describe the properties of the most modern ``genetlink`` +schema. See the documentation of :doc:`genetlink-c <c-code-gen>` +for information on how C names are derived from name properties. + +See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>` for +information on the Netlink specification properties that are only relevant to +the kernel space and not part of the user space API. + +genetlink +========= + +Globals +------- + +Attributes listed directly at the root level of the spec file. + +name +~~~~ + +Name of the family. Name identifies the family in a unique way, since +the Family IDs are allocated dynamically. + +protocol +~~~~~~~~ + +The schema level, default is ``genetlink``, which is the only value +allowed for new ``genetlink`` families. + +definitions +----------- + +Array of type and constant definitions. + +name +~~~~ + +Name of the type / constant. + +type +~~~~ + +One of the following types: + + - const - a single, standalone constant + - enum - defines an integer enumeration, with values for each entry + incrementing by 1, (e.g. 0, 1, 2, 3) + - flags - defines an integer enumeration, with values for each entry + occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8) + +value +~~~~~ + +The value for the ``const``. + +value-start +~~~~~~~~~~~ + +The first value for ``enum`` and ``flags``, allows overriding the default +start value of ``0`` (for ``enum``) and starting bit (for ``flags``). +For ``flags`` ``value-start`` selects the starting bit, not the shifted value. + +Sparse enumerations are not supported. + +entries +~~~~~~~ + +Array of names of the entries for ``enum`` and ``flags``. + +header +~~~~~~ + +For C-compatible languages, header which already defines this value. +In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``) +code generators for C-compatible languages may prefer to add an appropriate +include instead of rendering a new definition. + +attribute-sets +-------------- + +This property contains information about netlink attributes of the family. +All families have at least one attribute set, most have multiple. +``attribute-sets`` is an array, with each entry describing a single set. + +Note that the spec is "flattened" and is not meant to visually resemble +the format of the netlink messages (unlike certain ad-hoc documentation +formats seen in kernel comments). In the spec subordinate attribute sets +are not defined inline as a nest, but defined in a separate attribute set +referred to with a ``nested-attributes`` property of the container. + +Spec may also contain fractional sets - sets which contain a ``subset-of`` +property. Such sets describe a section of a full set, allowing narrowing down +which attributes are allowed in a nest or refining the validation criteria. +Fractional sets can only be used in nests. They are not rendered to the uAPI +in any fashion. + +name +~~~~ + +Uniquely identifies the attribute set, operations and nested attributes +refer to the sets by the ``name``. + +subset-of +~~~~~~~~~ + +Re-defines a portion of another set (a fractional set). +Allows narrowing down fields and changing validation criteria +or even types of attributes depending on the nest in which they +are contained. The ``value`` of each attribute in the fractional +set is implicitly the same as in the main set. + +attributes +~~~~~~~~~~ + +List of attributes in the set. + +.. _attribute_properties: + +Attribute properties +-------------------- + +name +~~~~ + +Identifies the attribute, unique within the set. + +type +~~~~ + +Netlink attribute type, see :ref:`attr_types`. + +.. _assign_val: + +value +~~~~~ + +Numerical attribute ID, used in serialized Netlink messages. +The ``value`` property can be skipped, in which case the attribute ID +will be the value of the previous attribute plus one (recursively) +and ``1`` for the first attribute in the attribute set. + +Attributes (and operations) use ``1`` as the default value for the first +entry (unlike enums in definitions which start from ``0``) because +entry ``0`` is almost always reserved as undefined. Spec can explicitly +set value to ``0`` if needed. + +Note that the ``value`` of an attribute is defined only in its main set +(not in subsets). + +enum +~~~~ + +For integer types specifies that values in the attribute belong +to an ``enum`` or ``flags`` from the ``definitions`` section. + +enum-as-flags +~~~~~~~~~~~~~ + +Treat ``enum`` as ``flags`` regardless of its type in ``definitions``. +When both ``enum`` and ``flags`` forms are needed ``definitions`` should +contain an ``enum`` and attributes which need the ``flags`` form should +use this attribute. + +nested-attributes +~~~~~~~~~~~~~~~~~ + +Identifies the attribute space for attributes nested within given attribute. +Only valid for complex attributes which may have sub-attributes. + +multi-attr (arrays) +~~~~~~~~~~~~~~~~~~~ + +Boolean property signifying that the attribute may be present multiple times. +Allowing an attribute to repeat is the recommended way of implementing arrays +(no extra nesting). + +byte-order +~~~~~~~~~~ + +For integer types specifies attribute byte order - ``little-endian`` +or ``big-endian``. + +checks +~~~~~~ + +Input validation constraints used by the kernel. User space should query +the policy of the running kernel using Generic Netlink introspection, +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`. + +display-hint +~~~~~~~~~~~~ + +Optional format indicator that is intended only for choosing the right +formatting mechanism when displaying values of this type. Currently supported +hints are ``hex``, ``mac``, ``fddi``, ``ipv4``, ``ipv6`` and ``uuid``. + +operations +---------- + +This section describes messages passed between the kernel and the user space. +There are three types of entries in this section - operations, notifications +and events. + +Operations describe the most common request - response communication. User +sends a request and kernel replies. Each operation may contain any combination +of the two modes familiar to netlink users - ``do`` and ``dump``. +``do`` and ``dump`` in turn contain a combination of ``request`` and +``response`` properties. If no explicit message with attributes is passed +in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do`` +of a SET operation to which the kernel responds with just the netlink error +code) ``request`` or ``response`` section can be skipped. +``request`` and ``response`` sections list the attributes allowed in a message. +The list contains only the names of attributes from a set referred +to by the ``attribute-set`` property. + +Notifications and events both refer to the asynchronous messages sent by +the kernel to members of a multicast group. The difference between the +two is that a notification shares its contents with a GET operation +(the name of the GET operation is specified in the ``notify`` property). +This arrangement is commonly used for notifications about +objects where the notification carries the full object definition. + +Events are more focused and carry only a subset of information rather than full +object state (a made up example would be a link state change event with just +the interface name and the new link state). Events contain the ``event`` +property. Events are considered less idiomatic for netlink and notifications +should be preferred. + +list +~~~~ + +The only property of ``operations`` for ``genetlink``, holds the list of +operations, notifications etc. + +Operation properties +-------------------- + +name +~~~~ + +Identifies the operation. + +value +~~~~~ + +Numerical message ID, used in serialized Netlink messages. +The same enumeration rules are applied as to +:ref:`attribute values<assign_val>`. + +attribute-set +~~~~~~~~~~~~~ + +Specifies the attribute set contained within the message. + +do +~~~ + +Specification for the ``doit`` request. Should contain ``request``, ``reply`` +or both of these properties, each holding a :ref:`attr_list`. + +dump +~~~~ + +Specification for the ``dumpit`` request. Should contain ``request``, ``reply`` +or both of these properties, each holding a :ref:`attr_list`. + +notify +~~~~~~ + +Designates the message as a notification. Contains the name of the operation +(possibly the same as the operation holding this property) which shares +the contents with the notification (``do``). + +event +~~~~~ + +Specification of attributes in the event, holds a :ref:`attr_list`. +``event`` property is mutually exclusive with ``notify``. + +mcgrp +~~~~~ + +Used with ``event`` and ``notify``, specifies which multicast group +message belongs to. + +.. _attr_list: + +Message attribute list +---------------------- + +``request``, ``reply`` and ``event`` properties have a single ``attributes`` +property which holds the list of attribute names. + +Messages can also define ``pre`` and ``post`` properties which will be rendered +as ``pre_doit`` and ``post_doit`` calls in the kernel (these properties should +be ignored by user space). + +mcast-groups +------------ + +This section lists the multicast groups of the family. + +list +~~~~ + +The only property of ``mcast-groups`` for ``genetlink``, holds the list +of groups. + +Multicast group properties +-------------------------- + +name +~~~~ + +Uniquely identifies the multicast group in the family. Similarly to +Family ID, Multicast Group ID needs to be resolved at runtime, based +on the name. + +.. _attr_types: + +Attribute types +=============== + +This section describes the attribute types supported by the ``genetlink`` +compatibility level. Refer to documentation of different levels for additional +attribute types. + +Common integer types +-------------------- + +``sint`` and ``uint`` represent signed and unsigned 64 bit integers. +If the value can fit on 32 bits only 32 bits are carried in netlink +messages, otherwise full 64 bits are carried. Note that the payload +is only aligned to 4B, so the full 64 bit value may be unaligned! + +Common integer types should be preferred over fix-width types in majority +of cases. + +Fix-width integer types +----------------------- + +Fixed-width integer types include: +``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. + +Note that types smaller than 32 bit should be avoided as using them +does not save any memory in Netlink messages (due to alignment). +See :ref:`pad_type` for padding of 64 bit attributes. + +The payload of the attribute is the integer in host order unless ``byte-order`` +specifies otherwise. + +64 bit values are usually aligned by the kernel but it is recommended +that the user space is able to deal with unaligned values. + +.. _pad_type: + +pad +--- + +Special attribute type used for padding attributes which require alignment +bigger than standard 4B alignment required by netlink (e.g. 64 bit integers). +There can only be a single attribute of the ``pad`` type in any attribute set +and it should be automatically used for padding when needed. + +flag +---- + +Attribute with no payload, its presence is the entire information. + +binary +------ + +Raw binary data attribute, the contents are opaque to generic code. + +string +------ + +Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true`` +the string is required to be null terminated. +``max-len`` in ``checks`` indicates the longest possible string, +if not present the length of the string is unbounded. + +Note that ``max-len`` does not count the terminating character. + +nest +---- + +Attribute containing other (nested) attributes. +``nested-attributes`` specifies which attribute set is used inside. diff --git a/Documentation/userspace-api/perf_ring_buffer.rst b/Documentation/userspace-api/perf_ring_buffer.rst new file mode 100644 index 000000000000..bde9d8cbc106 --- /dev/null +++ b/Documentation/userspace-api/perf_ring_buffer.rst @@ -0,0 +1,830 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +Perf ring buffer +================ + +.. CONTENTS + + 1. Introduction + + 2. Ring buffer implementation + 2.1 Basic algorithm + 2.2 Ring buffer for different tracing modes + 2.2.1 Default mode + 2.2.2 Per-thread mode + 2.2.3 Per-CPU mode + 2.2.4 System wide mode + 2.3 Accessing buffer + 2.3.1 Producer-consumer model + 2.3.2 Properties of the ring buffers + 2.3.3 Writing samples into buffer + 2.3.4 Reading samples from buffer + 2.3.5 Memory synchronization + + 3. The mechanism of AUX ring buffer + 3.1 The relationship between AUX and regular ring buffers + 3.2 AUX events + 3.3 Snapshot mode + + +1. Introduction +=============== + +The ring buffer is a fundamental mechanism for data transfer. perf uses +ring buffers to transfer event data from kernel to user space, another +kind of ring buffer which is so called auxiliary (AUX) ring buffer also +plays an important role for hardware tracing with Intel PT, Arm +CoreSight, etc. + +The ring buffer implementation is critical but it's also a very +challenging work. On the one hand, the kernel and perf tool in the user +space use the ring buffer to exchange data and stores data into data +file, thus the ring buffer needs to transfer data with high throughput; +on the other hand, the ring buffer management should avoid significant +overload to distract profiling results. + +This documentation dives into the details for perf ring buffer with two +parts: firstly it explains the perf ring buffer implementation, then the +second part discusses the AUX ring buffer mechanism. + +2. Ring buffer implementation +============================= + +2.1 Basic algorithm +------------------- + +That said, a typical ring buffer is managed by a head pointer and a tail +pointer; the head pointer is manipulated by a writer and the tail +pointer is updated by a reader respectively. + +:: + + +---------------------------+ + | | |***|***|***| | | + +---------------------------+ + `-> Tail `-> Head + + * : the data is filled by the writer. + + Figure 1. Ring buffer + +Perf uses the same way to manage its ring buffer. In the implementation +there are two key data structures held together in a set of consecutive +pages, the control structure and then the ring buffer itself. The page +with the control structure in is known as the "user page". Being held +in continuous virtual addresses simplifies locating the ring buffer +address, it is in the pages after the page with the user page. + +The control structure is named as ``perf_event_mmap_page``, it contains a +head pointer ``data_head`` and a tail pointer ``data_tail``. When the +kernel starts to fill records into the ring buffer, it updates the head +pointer to reserve the memory so later it can safely store events into +the buffer. On the other side, when the user page is a writable mapping, +the perf tool has the permission to update the tail pointer after consuming +data from the ring buffer. Yet another case is for the user page's +read-only mapping, which is to be addressed in the section +:ref:`writing_samples_into_buffer`. + +:: + + user page ring buffer + +---------+---------+ +---------------------------------------+ + |data_head|data_tail|...| | |***|***|***|***|***| | | | + +---------+---------+ +---------------------------------------+ + ` `----------------^ ^ + `----------------------------------------------| + + * : the data is filled by the writer. + + Figure 2. Perf ring buffer + +When using the ``perf record`` tool, we can specify the ring buffer size +with option ``-m`` or ``--mmap-pages=``, the given size will be rounded up +to a power of two that is a multiple of a page size. Though the kernel +allocates at once for all memory pages, it's deferred to map the pages +to VMA area until the perf tool accesses the buffer from the user space. +In other words, at the first time accesses the buffer's page from user +space in the perf tool, a data abort exception for page fault is taken +and the kernel uses this occasion to map the page into process VMA +(see ``perf_mmap_fault()``), thus the perf tool can continue to access +the page after returning from the exception. + +2.2 Ring buffer for different tracing modes +------------------------------------------- + +The perf profiles programs with different modes: default mode, per thread +mode, per cpu mode, and system wide mode. This section describes these +modes and how the ring buffer meets requirements for them. At last we +will review the race conditions caused by these modes. + +2.2.1 Default mode +^^^^^^^^^^^^^^^^^^ + +Usually we execute ``perf record`` command followed by a profiling program +name, like below command:: + + perf record test_program + +This command doesn't specify any options for CPU and thread modes, the +perf tool applies the default mode on the perf event. It maps all the +CPUs in the system and the profiled program's PID on the perf event, and +it enables inheritance mode on the event so that child tasks inherits +the events. As a result, the perf event is attributed as:: + + evsel::cpus::map[] = { 0 .. _SC_NPROCESSORS_ONLN-1 } + evsel::threads::map[] = { pid } + evsel::attr::inherit = 1 + +These attributions finally will be reflected on the deployment of ring +buffers. As shown below, the perf tool allocates individual ring buffer +for each CPU, but it only enables events for the profiled program rather +than for all threads in the system. The *T1* thread represents the +thread context of the 'test_program', whereas *T2* and *T3* are irrelevant +threads in the system. The perf samples are exclusively collected for +the *T1* thread and stored in the ring buffer associated with the CPU on +which the *T1* thread is running. + +:: + + T1 T2 T1 + +----+ +-----------+ +----+ + CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| + +----+--------------+-----------+----------+----+--------> + | | + v v + +-----------------------------------------------------+ + | Ring buffer 0 | + +-----------------------------------------------------+ + + T1 + +-----+ + CPU1 |xxxxx| + -----+-----+---------------------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 1 | + +-----------------------------------------------------+ + + T1 T3 + +----+ +-------+ + CPU2 |xxxx| |xxxxxxx| + --------------------------+----+--------+-------+--------> + | + v + +-----------------------------------------------------+ + | Ring buffer 2 | + +-----------------------------------------------------+ + + T1 + +--------------+ + CPU3 |xxxxxxxxxxxxxx| + -----------+--------------+------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 3 | + +-----------------------------------------------------+ + + T1: Thread 1; T2: Thread 2; T3: Thread 3 + x: Thread is in running state + + Figure 3. Ring buffer for default mode + +2.2.2 Per-thread mode +^^^^^^^^^^^^^^^^^^^^^ + +By specifying option ``--per-thread`` in perf command, e.g. + +:: + + perf record --per-thread test_program + +The perf event doesn't map to any CPUs and is only bound to the +profiled process, thus, the perf event's attributions are:: + + evsel::cpus::map[0] = { -1 } + evsel::threads::map[] = { pid } + evsel::attr::inherit = 0 + +In this mode, a single ring buffer is allocated for the profiled thread; +if the thread is scheduled on a CPU, the events on that CPU will be +enabled; and if the thread is scheduled out from the CPU, the events on +the CPU will be disabled. When the thread is migrated from one CPU to +another, the events are to be disabled on the previous CPU and enabled +on the next CPU correspondingly. + +:: + + T1 T2 T1 + +----+ +-----------+ +----+ + CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| + +----+--------------+-----------+----------+----+--------> + | | + | T1 | + | +-----+ | + CPU1 | |xxxxx| | + --|--+-----+----------------------------------|----------> + | | | + | | T1 T3 | + | | +----+ +---+ | + CPU2 | | |xxxx| |xxx| | + --|-----|-----------------+----+--------+---+-|----------> + | | | | + | | T1 | | + | | +--------------+ | | + CPU3 | | |xxxxxxxxxxxxxx| | | + --|-----|--+--------------+-|-----------------|----------> + | | | | | + v v v v v + +-----------------------------------------------------+ + | Ring buffer | + +-----------------------------------------------------+ + + T1: Thread 1 + x: Thread is in running state + + Figure 4. Ring buffer for per-thread mode + +When perf runs in per-thread mode, a ring buffer is allocated for the +profiled thread *T1*. The ring buffer is dedicated for thread *T1*, if the +thread *T1* is running, the perf events will be recorded into the ring +buffer; when the thread is sleeping, all associated events will be +disabled, thus no trace data will be recorded into the ring buffer. + +2.2.3 Per-CPU mode +^^^^^^^^^^^^^^^^^^ + +The option ``-C`` is used to collect samples on the list of CPUs, for +example the below perf command receives option ``-C 0,2``:: + + perf record -C 0,2 test_program + +It maps the perf event to CPUs 0 and 2, and the event is not associated to any +PID. Thus the perf event attributions are set as:: + + evsel::cpus::map[0] = { 0, 2 } + evsel::threads::map[] = { -1 } + evsel::attr::inherit = 0 + +This results in the session of ``perf record`` will sample all threads on CPU0 +and CPU2, and be terminated until test_program exits. Even there have tasks +running on CPU1 and CPU3, since the ring buffer is absent for them, any +activities on these two CPUs will be ignored. A usage case is to combine the +options for per-thread mode and per-CPU mode, e.g. the options ``–C 0,2`` and +``––per–thread`` are specified together, the samples are recorded only when +the profiled thread is scheduled on any of the listed CPUs. + +:: + + T1 T2 T1 + +----+ +-----------+ +----+ + CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| + +----+--------------+-----------+----------+----+--------> + | | | + v v v + +-----------------------------------------------------+ + | Ring buffer 0 | + +-----------------------------------------------------+ + + T1 + +-----+ + CPU1 |xxxxx| + -----+-----+---------------------------------------------> + + T1 T3 + +----+ +-------+ + CPU2 |xxxx| |xxxxxxx| + --------------------------+----+--------+-------+--------> + | | + v v + +-----------------------------------------------------+ + | Ring buffer 1 | + +-----------------------------------------------------+ + + T1 + +--------------+ + CPU3 |xxxxxxxxxxxxxx| + -----------+--------------+------------------------------> + + T1: Thread 1; T2: Thread 2; T3: Thread 3 + x: Thread is in running state + + Figure 5. Ring buffer for per-CPU mode + +2.2.4 System wide mode +^^^^^^^^^^^^^^^^^^^^^^ + +By using option ``–a`` or ``––all–cpus``, perf collects samples on all CPUs +for all tasks, we call it as the system wide mode, the command is:: + + perf record -a test_program + +Similar to the per-CPU mode, the perf event doesn't bind to any PID, and +it maps to all CPUs in the system:: + + evsel::cpus::map[] = { 0 .. _SC_NPROCESSORS_ONLN-1 } + evsel::threads::map[] = { -1 } + evsel::attr::inherit = 0 + +In the system wide mode, every CPU has its own ring buffer, all threads +are monitored during the running state and the samples are recorded into +the ring buffer belonging to the CPU which the events occurred on. + +:: + + T1 T2 T1 + +----+ +-----------+ +----+ + CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| + +----+--------------+-----------+----------+----+--------> + | | | + v v v + +-----------------------------------------------------+ + | Ring buffer 0 | + +-----------------------------------------------------+ + + T1 + +-----+ + CPU1 |xxxxx| + -----+-----+---------------------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 1 | + +-----------------------------------------------------+ + + T1 T3 + +----+ +-------+ + CPU2 |xxxx| |xxxxxxx| + --------------------------+----+--------+-------+--------> + | | + v v + +-----------------------------------------------------+ + | Ring buffer 2 | + +-----------------------------------------------------+ + + T1 + +--------------+ + CPU3 |xxxxxxxxxxxxxx| + -----------+--------------+------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 3 | + +-----------------------------------------------------+ + + T1: Thread 1; T2: Thread 2; T3: Thread 3 + x: Thread is in running state + + Figure 6. Ring buffer for system wide mode + +2.3 Accessing buffer +-------------------- + +Based on the understanding of how the ring buffer is allocated in +various modes, this section explains access the ring buffer. + +2.3.1 Producer-consumer model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the Linux kernel, the PMU events can produce samples which are stored +into the ring buffer; the perf command in user space consumes the +samples by reading out data from the ring buffer and finally saves the +data into the file for post analysis. It’s a typical producer-consumer +model for using the ring buffer. + +The perf process polls on the PMU events and sleeps when no events are +incoming. To prevent frequent exchanges between the kernel and user +space, the kernel event core layer introduces a watermark, which is +stored in the ``perf_buffer::watermark``. When a sample is recorded into +the ring buffer, and if the used buffer exceeds the watermark, the +kernel wakes up the perf process to read samples from the ring buffer. + +:: + + Perf + / | Read samples + Polling / `--------------| Ring buffer + v v ;---------------------v + +----------------+ +---------+---------+ +-------------------+ + |Event wait queue| |data_head|data_tail| |***|***| | |***| + +----------------+ +---------+---------+ +-------------------+ + ^ ^ `------------------------^ + | Wake up tasks | Store samples + +-----------------------------+ + | Kernel event core layer | + +-----------------------------+ + + * : the data is filled by the writer. + + Figure 7. Writing and reading the ring buffer + +When the kernel event core layer notifies the user space, because +multiple events might share the same ring buffer for recording samples, +the core layer iterates every event associated with the ring buffer and +wakes up tasks waiting on the event. This is fulfilled by the kernel +function ``ring_buffer_wakeup()``. + +After the perf process is woken up, it starts to check the ring buffers +one by one, if it finds any ring buffer containing samples it will read +out the samples for statistics or saving into the data file. Given the +perf process is able to run on any CPU, this leads to the ring buffer +potentially being accessed from multiple CPUs simultaneously, which +causes race conditions. The race condition handling is described in the +section :ref:`memory_synchronization`. + +2.3.2 Properties of the ring buffers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Linux kernel supports two write directions for the ring buffer: forward and +backward. The forward writing saves samples from the beginning of the ring +buffer, the backward writing stores data from the end of the ring buffer with +the reversed direction. The perf tool determines the writing direction. + +Additionally, the tool can map buffers in either read-write mode or read-only +mode to the user space. + +The ring buffer in the read-write mode is mapped with the property +``PROT_READ | PROT_WRITE``. With the write permission, the perf tool +updates the ``data_tail`` to indicate the data start position. Combining +with the head pointer ``data_head``, which works as the end position of +the current data, the perf tool can easily know where read out the data +from. + +Alternatively, in the read-only mode, only the kernel keeps to update +the ``data_head`` while the user space cannot access the ``data_tail`` due +to the mapping property ``PROT_READ``. + +As a result, the matrix below illustrates the various combinations of +direction and mapping characteristics. The perf tool employs two of these +combinations to support buffer types: the non-overwrite buffer and the +overwritable buffer. + +.. list-table:: + :widths: 1 1 1 + :header-rows: 1 + + * - Mapping mode + - Forward + - Backward + * - read-write + - Non-overwrite ring buffer + - Not used + * - read-only + - Not used + - Overwritable ring buffer + +The non-overwrite ring buffer uses the read-write mapping with forward +writing. It starts to save data from the beginning of the ring buffer +and wrap around when overflow, which is used with the read-write mode in +the normal ring buffer. When the consumer doesn't keep up with the +producer, it would lose some data, the kernel keeps how many records it +lost and generates the ``PERF_RECORD_LOST`` records in the next time +when it finds a space in the ring buffer. + +The overwritable ring buffer uses the backward writing with the +read-only mode. It saves the data from the end of the ring buffer and +the ``data_head`` keeps the position of current data, the perf always +knows where it starts to read and until the end of the ring buffer, thus +it don't need the ``data_tail``. In this mode, it will not generate the +``PERF_RECORD_LOST`` records. + +.. _writing_samples_into_buffer: + +2.3.3 Writing samples into buffer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When a sample is taken and saved into the ring buffer, the kernel +prepares sample fields based on the sample type; then it prepares the +info for writing ring buffer which is stored in the structure +``perf_output_handle``. In the end, the kernel outputs the sample into +the ring buffer and updates the head pointer in the user page so the +perf tool can see the latest value. + +The structure ``perf_output_handle`` serves as a temporary context for +tracking the information related to the buffer. The advantages of it is +that it enables concurrent writing to the buffer by different events. +For example, a software event and a hardware PMU event both are enabled +for profiling, two instances of ``perf_output_handle`` serve as separate +contexts for the software event and the hardware event respectively. +This allows each event to reserve its own memory space for populating +the record data. + +2.3.4 Reading samples from buffer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the user space, the perf tool utilizes the ``perf_event_mmap_page`` +structure to handle the head and tail of the buffer. It also uses +``perf_mmap`` structure to keep track of a context for the ring buffer, this +context includes information about the buffer's starting and ending +addresses. Additionally, the mask value can be utilized to compute the +circular buffer pointer even for an overflow. + +Similar to the kernel, the perf tool in the user space first reads out +the recorded data from the ring buffer, and then updates the buffer's +tail pointer ``perf_event_mmap_page::data_tail``. + +.. _memory_synchronization: + +2.3.5 Memory synchronization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The modern CPUs with relaxed memory model cannot promise the memory +ordering, this means it’s possible to access the ring buffer and the +``perf_event_mmap_page`` structure out of order. To assure the specific +sequence for memory accessing perf ring buffer, memory barriers are +used to assure the data dependency. The rationale for the memory +synchronization is as below:: + + Kernel User space + + if (LOAD ->data_tail) { LOAD ->data_head + (A) smp_rmb() (C) + STORE $data LOAD $data + smp_wmb() (B) smp_mb() (D) + STORE ->data_head STORE ->data_tail + } + +The comments in tools/include/linux/ring_buffer.h gives nice description +for why and how to use memory barriers, here we will just provide an +alternative explanation: + +(A) is a control dependency so that CPU assures order between checking +pointer ``perf_event_mmap_page::data_tail`` and filling sample into ring +buffer; + +(D) pairs with (A). (D) separates the ring buffer data reading from +writing the pointer ``data_tail``, perf tool first consumes samples and then +tells the kernel that the data chunk has been released. Since a reading +operation is followed by a writing operation, thus (D) is a full memory +barrier. + +(B) is a writing barrier in the middle of two writing operations, which +makes sure that recording a sample must be prior to updating the head +pointer. + +(C) pairs with (B). (C) is a read memory barrier to ensure the head +pointer is fetched before reading samples. + +To implement the above algorithm, the ``perf_output_put_handle()`` function +in the kernel and two helpers ``ring_buffer_read_head()`` and +``ring_buffer_write_tail()`` in the user space are introduced, they rely +on memory barriers as described above to ensure the data dependency. + +Some architectures support one-way permeable barrier with load-acquire +and store-release operations, these barriers are more relaxed with less +performance penalty, so (C) and (D) can be optimized to use barriers +``smp_load_acquire()`` and ``smp_store_release()`` respectively. + +If an architecture doesn’t support load-acquire and store-release in its +memory model, it will roll back to the old fashion of memory barrier +operations. In this case, ``smp_load_acquire()`` encapsulates +``READ_ONCE()`` + ``smp_mb()``, since ``smp_mb()`` is costly, +``ring_buffer_read_head()`` doesn't invoke ``smp_load_acquire()`` and it uses +the barriers ``READ_ONCE()`` + ``smp_rmb()`` instead. + +3. The mechanism of AUX ring buffer +=================================== + +In this chapter, we will explain the implementation of the AUX ring +buffer. In the first part it will discuss the connection between the +AUX ring buffer and the regular ring buffer, then the second part will +examine how the AUX ring buffer co-works with the regular ring buffer, +as well as the additional features introduced by the AUX ring buffer for +the sampling mechanism. + +3.1 The relationship between AUX and regular ring buffers +--------------------------------------------------------- + +Generally, the AUX ring buffer is an auxiliary for the regular ring +buffer. The regular ring buffer is primarily used to store the event +samples and every event format complies with the definition in the +union ``perf_event``; the AUX ring buffer is for recording the hardware +trace data and the trace data format is hardware IP dependent. + +The general use and advantage of the AUX ring buffer is that it is +written directly by hardware rather than by the kernel. For example, +regular profile samples that write to the regular ring buffer cause an +interrupt. Tracing execution requires a high number of samples and +using interrupts would be overwhelming for the regular ring buffer +mechanism. Having an AUX buffer allows for a region of memory more +decoupled from the kernel and written to directly by hardware tracing. + +The AUX ring buffer reuses the same algorithm with the regular ring +buffer for the buffer management. The control structure +``perf_event_mmap_page`` extends the new fields ``aux_head`` and ``aux_tail`` +for the head and tail pointers of the AUX ring buffer. + +During the initialisation phase, besides the mmap()-ed regular ring +buffer, the perf tool invokes a second syscall in the +``auxtrace_mmap__mmap()`` function for the mmap of the AUX buffer with +non-zero file offset; ``rb_alloc_aux()`` in the kernel allocates pages +correspondingly, these pages will be deferred to map into VMA when +handling the page fault, which is the same lazy mechanism with the +regular ring buffer. + +AUX events and AUX trace data are two different things. Let's see an +example:: + + perf record -a -e cycles -e cs_etm/@tmc_etr0/ -- sleep 2 + +The above command enables two events: one is the event *cycles* from PMU +and another is the AUX event *cs_etm* from Arm CoreSight, both are saved +into the regular ring buffer while the CoreSight's AUX trace data is +stored in the AUX ring buffer. + +As a result, we can see the regular ring buffer and the AUX ring buffer +are allocated in pairs. The perf in default mode allocates the regular +ring buffer and the AUX ring buffer per CPU-wise, which is the same as +the system wide mode, however, the default mode records samples only for +the profiled program, whereas the latter mode profiles for all programs +in the system. For per-thread mode, the perf tool allocates only one +regular ring buffer and one AUX ring buffer for the whole session. For +the per-CPU mode, the perf allocates two kinds of ring buffers for +selected CPUs specified by the option ``-C``. + +The below figure demonstrates the buffers' layout in the system wide +mode; if there are any activities on one CPU, the AUX event samples and +the hardware trace data will be recorded into the dedicated buffers for +the CPU. + +:: + + T1 T2 T1 + +----+ +-----------+ +----+ + CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| + +----+--------------+-----------+----------+----+--------> + | | | + v v v + +-----------------------------------------------------+ + | Ring buffer 0 | + +-----------------------------------------------------+ + | | | + v v v + +-----------------------------------------------------+ + | AUX Ring buffer 0 | + +-----------------------------------------------------+ + + T1 + +-----+ + CPU1 |xxxxx| + -----+-----+---------------------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 1 | + +-----------------------------------------------------+ + | + v + +-----------------------------------------------------+ + | AUX Ring buffer 1 | + +-----------------------------------------------------+ + + T1 T3 + +----+ +-------+ + CPU2 |xxxx| |xxxxxxx| + --------------------------+----+--------+-------+--------> + | | + v v + +-----------------------------------------------------+ + | Ring buffer 2 | + +-----------------------------------------------------+ + | | + v v + +-----------------------------------------------------+ + | AUX Ring buffer 2 | + +-----------------------------------------------------+ + + T1 + +--------------+ + CPU3 |xxxxxxxxxxxxxx| + -----------+--------------+------------------------------> + | + v + +-----------------------------------------------------+ + | Ring buffer 3 | + +-----------------------------------------------------+ + | + v + +-----------------------------------------------------+ + | AUX Ring buffer 3 | + +-----------------------------------------------------+ + + T1: Thread 1; T2: Thread 2; T3: Thread 3 + x: Thread is in running state + + Figure 8. AUX ring buffer for system wide mode + +3.2 AUX events +-------------- + +Similar to ``perf_output_begin()`` and ``perf_output_end()``'s working for the +regular ring buffer, ``perf_aux_output_begin()`` and ``perf_aux_output_end()`` +serve for the AUX ring buffer for processing the hardware trace data. + +Once the hardware trace data is stored into the AUX ring buffer, the PMU +driver will stop hardware tracing by calling the ``pmu::stop()`` callback. +Similar to the regular ring buffer, the AUX ring buffer needs to apply +the memory synchronization mechanism as discussed in the section +:ref:`memory_synchronization`. Since the AUX ring buffer is managed by the +PMU driver, the barrier (B), which is a writing barrier to ensure the trace +data is externally visible prior to updating the head pointer, is asked +to be implemented in the PMU driver. + +Then ``pmu::stop()`` can safely call the ``perf_aux_output_end()`` function to +finish two things: + +- It fills an event ``PERF_RECORD_AUX`` into the regular ring buffer, this + event delivers the information of the start address and data size for a + chunk of hardware trace data has been stored into the AUX ring buffer; + +- Since the hardware trace driver has stored new trace data into the AUX + ring buffer, the argument *size* indicates how many bytes have been + consumed by the hardware tracing, thus ``perf_aux_output_end()`` updates the + header pointer ``perf_buffer::aux_head`` to reflect the latest buffer usage. + +At the end, the PMU driver will restart hardware tracing. During this +temporary suspending period, it will lose hardware trace data, which +will introduce a discontinuity during decoding phase. + +The event ``PERF_RECORD_AUX`` presents an AUX event which is handled in the +kernel, but it lacks the information for saving the AUX trace data in +the perf file. When the perf tool copies the trace data from AUX ring +buffer to the perf data file, it synthesizes a ``PERF_RECORD_AUXTRACE`` +event which is not a kernel ABI, it's defined by the perf tool to describe +which portion of data in the AUX ring buffer is saved. Afterwards, the perf +tool reads out the AUX trace data from the perf file based on the +``PERF_RECORD_AUXTRACE`` events, and the ``PERF_RECORD_AUX`` event is used to +decode a chunk of data by correlating with time order. + +3.3 Snapshot mode +----------------- + +Perf supports snapshot mode for AUX ring buffer, in this mode, users +only record AUX trace data at a specific time point which users are +interested in. E.g. below gives an example of how to take snapshots +with 1 second interval with Arm CoreSight:: + + perf record -e cs_etm/@tmc_etr0/u -S -a program & + PERFPID=$! + while true; do + kill -USR2 $PERFPID + sleep 1 + done + +The main flow for snapshot mode is: + +- Before a snapshot is taken, the AUX ring buffer acts in free run mode. + During free run mode the perf doesn't record any of the AUX events and + trace data; + +- Once the perf tool receives the *USR2* signal, it triggers the callback + function ``auxtrace_record::snapshot_start()`` to deactivate hardware + tracing. The kernel driver then populates the AUX ring buffer with the + hardware trace data, and the event ``PERF_RECORD_AUX`` is stored in the + regular ring buffer; + +- Then perf tool takes a snapshot, ``record__read_auxtrace_snapshot()`` + reads out the hardware trace data from the AUX ring buffer and saves it + into perf data file; + +- After the snapshot is finished, ``auxtrace_record::snapshot_finish()`` + restarts the PMU event for AUX tracing. + +The perf only accesses the head pointer ``perf_event_mmap_page::aux_head`` +in snapshot mode and doesn’t touch tail pointer ``aux_tail``, this is +because the AUX ring buffer can overflow in free run mode, the tail +pointer is useless in this case. Alternatively, the callback +``auxtrace_record::find_snapshot()`` is introduced for making the decision +of whether the AUX ring buffer has been wrapped around or not, at the +end it fixes up the AUX buffer's head which are used to calculate the +trace data size. + +As we know, the buffers' deployment can be per-thread mode, per-CPU +mode, or system wide mode, and the snapshot can be applied to any of +these modes. Below is an example of taking snapshot with system wide +mode. + +:: + + Snapshot is taken + | + v + +------------------------+ + | AUX Ring buffer 0 | <- aux_head + +------------------------+ + v + +--------------------------------+ + | AUX Ring buffer 1 | <- aux_head + +--------------------------------+ + v + +--------------------------------------------+ + | AUX Ring buffer 2 | <- aux_head + +--------------------------------------------+ + v + +---------------------------------------+ + | AUX Ring buffer 3 | <- aux_head + +---------------------------------------+ + + Figure 9. Snapshot with system wide mode diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index d1e2b9193f09..cff0fa7f3175 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -274,7 +274,7 @@ value will be the injected file descriptor number. The notifying process can be preempted, resulting in the notification being aborted. This can be problematic when trying to take actions on behalf of the notifying process that are long-running and typically retryable (mounting a -filesytem). Alternatively, at filter installation time, the +filesystem). Alternatively, at filter installation time, the ``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it such that when a user notification is received by the supervisor, the notifying process will ignore non-fatal signals until the response is sent. Signals that diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst index c33a71263d9e..4fccde2e4563 100644 --- a/Documentation/userspace-api/sysfs-platform_profile.rst +++ b/Documentation/userspace-api/sysfs-platform_profile.rst @@ -37,6 +37,6 @@ representation onto this fixed set. If there is no good match when mapping then a new profile name may be added. Drivers which wish to introduce new profile names must: - 1. Explain why the existing profile names canot be used. + 1. Explain why the existing profile names cannot be used. 2. Add the new profile name, along with a clear description of the expected behaviour, to the sysfs-platform_profile ABI documentation. diff --git a/Documentation/userspace-api/tee.rst b/Documentation/userspace-api/tee.rst new file mode 100644 index 000000000000..e2368dbc3451 --- /dev/null +++ b/Documentation/userspace-api/tee.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. tee: + +================================================== +TEE (Trusted Execution Environment) Userspace API +================================================== + +include/uapi/linux/tee.h defines the generic interface to a TEE. + +User space (the client) connects to the driver by opening /dev/tee[0-9]* or +/dev/teepriv[0-9]*. + +- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor + which user space can mmap. When user space doesn't need the file + descriptor any more, it should be closed. When shared memory isn't needed + any longer it should be unmapped with munmap() to allow the reuse of + memory. + +- TEE_IOC_VERSION lets user space know which TEE this driver handles and + its capabilities. + +- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application. + +- TEE_IOC_INVOKE invokes a function in a Trusted Application. + +- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE. + +- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application. + +There are two classes of clients, normal clients and supplicants. The latter is +a helper process for the TEE to access resources in Linux, for example file +system access. A normal client opens /dev/tee[0-9]* and a supplicant opens +/dev/teepriv[0-9]. + +Much of the communication between clients and the TEE is opaque to the +driver. The main job for the driver is to receive requests from the +clients, forward them to the TEE and send back the results. In the case of +supplicants the communication goes in the other direction, the TEE sends +requests to the supplicant which then sends back the result. |