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