Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _v4l2-meta-fmt-uvc:
  11
  12 *******************************
  13 V4L2_META_FMT_UVC ('UVCH')
  14 *******************************
  15
  16 UVC Payload Header Data
  17
  18
  19 Description
  20 ===========
  21
  22 This format describes standard UVC metadata, extracted from UVC packet headers
  23 and provided by the UVC driver through metadata video nodes. That data includes
  24 exact copies of the standard part of UVC Payload Header contents and auxiliary
  25 timing information, required for precise interpretation of timestamps, contained
  26 in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of
  27 the "UVC 1.5 Class specification" for details.
  28
  29 Each UVC payload header can be between 2 and 12 bytes large. Buffers can
  30 contain multiple headers, if multiple such headers have been transmitted by the
  31 camera for the respective frame. However, the driver may drop headers when the
  32 buffer is full, when they contain no useful information (e.g. those without the
  33 SCR field or with that field identical to the previous header), or generally to
  34 perform rate limiting when the device sends a large number of headers.
  35
  36 Each individual block contains the following fields:
  37
  38 .. flat-table:: UVC Metadata Block
  39     :widths: 1 4
  40     :header-rows:  1
  41     :stub-columns: 0
  42
  43     * - Field
  44       - Description
  45     * - __u64 ts;
  46       - system timestamp in host byte order, measured by the driver upon
  47         reception of the payload
  48     * - __u16 sof;
  49       - USB Frame Number in host byte order, also obtained by the driver as
  50         close as possible to the above timestamp to enable correlation between
  51         them
  52     * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*
  53     * - __u8 length;
  54       - length of the rest of the block, including this field
  55     * - __u8 flags;
  56       - Flags, indicating presence of other standard UVC fields
  57     * - __u8 buf[];
  58       - The rest of the header, possibly including UVC PTS and SCR fields