xref: /linux/Documentation/userspace-api/media/v4l/metafmt-uvc.rst (revision 778b8ebe5192e7a7f00563a7456517dfa63e1d90) 
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _v4l2-meta-fmt-uvc:
5
6*******************************
7V4L2_META_FMT_UVC ('UVCH')
8*******************************
9
10UVC Payload Header Data
11
12
13Description
14===========
15
16This format describes standard UVC metadata, extracted from UVC packet headers
17and provided by the UVC driver through metadata video nodes. That data includes
18exact copies of the standard part of UVC Payload Header contents and auxiliary
19timing information, required for precise interpretation of timestamps, contained
20in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of
21the "UVC 1.5 Class specification" for details.
22
23Each UVC payload header can be between 2 and 12 bytes large. Buffers can
24contain multiple headers, if multiple such headers have been transmitted by the
25camera for the respective frame. However, the driver may drop headers when the
26buffer is full, when they contain no useful information (e.g. those without the
27SCR field or with that field identical to the previous header), or generally to
28perform rate limiting when the device sends a large number of headers.
29
30Each individual block contains the following fields:
31
32.. flat-table:: UVC Metadata Block
33    :widths: 1 4
34    :header-rows:  1
35    :stub-columns: 0
36
37    * - Field
38      - Description
39    * - __u64 ts;
40      - system timestamp in host byte order, measured by the driver upon
41        reception of the payload
42    * - __u16 sof;
43      - USB Frame Number in host byte order, also obtained by the driver as
44        close as possible to the above timestamp to enable correlation between
45        them
46    * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*
47    * - __u8 length;
48      - length of the rest of the block, including this field. Please note that
49        regardless of this value, for V4L2_META_FMT_UVC the kernel will never
50        copy more than 2-12 bytes.
51    * - __u8 flags;
52      - Flags, indicating presence of other standard UVC fields
53    * - __u8 buf[];
54      - The rest of the header, possibly including UVC PTS and SCR fields
55