18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
28c2ecf20Sopenharmony_ci
38c2ecf20Sopenharmony_ci.. _v4l2-meta-fmt-uvc:
48c2ecf20Sopenharmony_ci
58c2ecf20Sopenharmony_ci*******************************
68c2ecf20Sopenharmony_ciV4L2_META_FMT_UVC ('UVCH')
78c2ecf20Sopenharmony_ci*******************************
88c2ecf20Sopenharmony_ci
98c2ecf20Sopenharmony_ciUVC Payload Header Data
108c2ecf20Sopenharmony_ci
118c2ecf20Sopenharmony_ci
128c2ecf20Sopenharmony_ciDescription
138c2ecf20Sopenharmony_ci===========
148c2ecf20Sopenharmony_ci
158c2ecf20Sopenharmony_ciThis format describes standard UVC metadata, extracted from UVC packet headers
168c2ecf20Sopenharmony_ciand provided by the UVC driver through metadata video nodes. That data includes
178c2ecf20Sopenharmony_ciexact copies of the standard part of UVC Payload Header contents and auxiliary
188c2ecf20Sopenharmony_citiming information, required for precise interpretation of timestamps, contained
198c2ecf20Sopenharmony_ciin those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of
208c2ecf20Sopenharmony_cithe "UVC 1.5 Class specification" for details.
218c2ecf20Sopenharmony_ci
228c2ecf20Sopenharmony_ciEach UVC payload header can be between 2 and 12 bytes large. Buffers can
238c2ecf20Sopenharmony_cicontain multiple headers, if multiple such headers have been transmitted by the
248c2ecf20Sopenharmony_cicamera for the respective frame. However, the driver may drop headers when the
258c2ecf20Sopenharmony_cibuffer is full, when they contain no useful information (e.g. those without the
268c2ecf20Sopenharmony_ciSCR field or with that field identical to the previous header), or generally to
278c2ecf20Sopenharmony_ciperform rate limiting when the device sends a large number of headers.
288c2ecf20Sopenharmony_ci
298c2ecf20Sopenharmony_ciEach individual block contains the following fields:
308c2ecf20Sopenharmony_ci
318c2ecf20Sopenharmony_ci.. flat-table:: UVC Metadata Block
328c2ecf20Sopenharmony_ci    :widths: 1 4
338c2ecf20Sopenharmony_ci    :header-rows:  1
348c2ecf20Sopenharmony_ci    :stub-columns: 0
358c2ecf20Sopenharmony_ci
368c2ecf20Sopenharmony_ci    * - Field
378c2ecf20Sopenharmony_ci      - Description
388c2ecf20Sopenharmony_ci    * - __u64 ts;
398c2ecf20Sopenharmony_ci      - system timestamp in host byte order, measured by the driver upon
408c2ecf20Sopenharmony_ci        reception of the payload
418c2ecf20Sopenharmony_ci    * - __u16 sof;
428c2ecf20Sopenharmony_ci      - USB Frame Number in host byte order, also obtained by the driver as
438c2ecf20Sopenharmony_ci        close as possible to the above timestamp to enable correlation between
448c2ecf20Sopenharmony_ci        them
458c2ecf20Sopenharmony_ci    * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*
468c2ecf20Sopenharmony_ci    * - __u8 length;
478c2ecf20Sopenharmony_ci      - length of the rest of the block, including this field
488c2ecf20Sopenharmony_ci    * - __u8 flags;
498c2ecf20Sopenharmony_ci      - Flags, indicating presence of other standard UVC fields
508c2ecf20Sopenharmony_ci    * - __u8 buf[];
518c2ecf20Sopenharmony_ci      - The rest of the header, possibly including UVC PTS and SCR fields
52