162306a36Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
262306a36Sopenharmony_ci
362306a36Sopenharmony_ci.. _v4l2-meta-fmt-uvc:
462306a36Sopenharmony_ci
562306a36Sopenharmony_ci*******************************
662306a36Sopenharmony_ciV4L2_META_FMT_UVC ('UVCH')
762306a36Sopenharmony_ci*******************************
862306a36Sopenharmony_ci
962306a36Sopenharmony_ciUVC Payload Header Data
1062306a36Sopenharmony_ci
1162306a36Sopenharmony_ci
1262306a36Sopenharmony_ciDescription
1362306a36Sopenharmony_ci===========
1462306a36Sopenharmony_ci
1562306a36Sopenharmony_ciThis format describes standard UVC metadata, extracted from UVC packet headers
1662306a36Sopenharmony_ciand provided by the UVC driver through metadata video nodes. That data includes
1762306a36Sopenharmony_ciexact copies of the standard part of UVC Payload Header contents and auxiliary
1862306a36Sopenharmony_citiming information, required for precise interpretation of timestamps, contained
1962306a36Sopenharmony_ciin those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of
2062306a36Sopenharmony_cithe "UVC 1.5 Class specification" for details.
2162306a36Sopenharmony_ci
2262306a36Sopenharmony_ciEach UVC payload header can be between 2 and 12 bytes large. Buffers can
2362306a36Sopenharmony_cicontain multiple headers, if multiple such headers have been transmitted by the
2462306a36Sopenharmony_cicamera for the respective frame. However, the driver may drop headers when the
2562306a36Sopenharmony_cibuffer is full, when they contain no useful information (e.g. those without the
2662306a36Sopenharmony_ciSCR field or with that field identical to the previous header), or generally to
2762306a36Sopenharmony_ciperform rate limiting when the device sends a large number of headers.
2862306a36Sopenharmony_ci
2962306a36Sopenharmony_ciEach individual block contains the following fields:
3062306a36Sopenharmony_ci
3162306a36Sopenharmony_ci.. flat-table:: UVC Metadata Block
3262306a36Sopenharmony_ci    :widths: 1 4
3362306a36Sopenharmony_ci    :header-rows:  1
3462306a36Sopenharmony_ci    :stub-columns: 0
3562306a36Sopenharmony_ci
3662306a36Sopenharmony_ci    * - Field
3762306a36Sopenharmony_ci      - Description
3862306a36Sopenharmony_ci    * - __u64 ts;
3962306a36Sopenharmony_ci      - system timestamp in host byte order, measured by the driver upon
4062306a36Sopenharmony_ci        reception of the payload
4162306a36Sopenharmony_ci    * - __u16 sof;
4262306a36Sopenharmony_ci      - USB Frame Number in host byte order, also obtained by the driver as
4362306a36Sopenharmony_ci        close as possible to the above timestamp to enable correlation between
4462306a36Sopenharmony_ci        them
4562306a36Sopenharmony_ci    * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*
4662306a36Sopenharmony_ci    * - __u8 length;
4762306a36Sopenharmony_ci      - length of the rest of the block, including this field
4862306a36Sopenharmony_ci    * - __u8 flags;
4962306a36Sopenharmony_ci      - Flags, indicating presence of other standard UVC fields
5062306a36Sopenharmony_ci    * - __u8 buf[];
5162306a36Sopenharmony_ci      - The rest of the header, possibly including UVC PTS and SCR fields
52