UVC Payload Header 데이터 | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

metafmt-uvc.rst:UVCH block은 host timestamp와 USB SOF 뒤에 2~12바이트 UVC payload header 사본을 두어 PTS/SCR의 정확한 해석을 돕습니다.

1-53

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

3 .. _v4l2-meta-fmt-uvc:

5 *******************************

6 V4L2_META_FMT_UVC ('UVCH')

7 *******************************

9 UVC Payload Header Data

12 Description

13 ===========

15 This format describes standard UVC metadata, extracted from UVC packet headers

16 and provided by the UVC driver through metadata video nodes. That data includes

17 exact copies of the standard part of UVC Payload Header contents and auxiliary

18 timing information, required for precise interpretation of timestamps, contained

19 in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of

20 the "UVC 1.5 Class specification" for details.

22 Each UVC payload header can be between 2 and 12 bytes large. Buffers can

23 contain multiple headers, if multiple such headers have been transmitted by the

24 camera for the respective frame. However, the driver may drop headers when the

25 buffer is full, when they contain no useful information (e.g. those without the

26 SCR field or with that field identical to the previous header), or generally to

27 perform rate limiting when the device sends a large number of headers.

29 Each individual block contains the following fields:

31 .. flat-table:: UVC Metadata Block

32 :widths: 1 4

33 :header-rows: 1

34 :stub-columns: 0

36 * - Field

37 - Description

38 * - __u64 ts;

39 - system timestamp in host byte order, measured by the driver upon

40 reception of the payload

41 * - __u16 sof;

42 - USB Frame Number in host byte order, also obtained by the driver as

43 close as possible to the above timestamp to enable correlation between

44 them

45 * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*

46 * - __u8 length;

47 - length of the rest of the block, including this field. Please note that

48 regardless of this value, for V4L2_META_FMT_UVC the kernel will never

49 copy more than 2-12 bytes.

50 * - __u8 flags;

51 - Flags, indicating presence of other standard UVC fields

52 * - __u8 buf[];

53 - The rest of the header, possibly including UVC PTS and SCR fields

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

표준 UVC metadata block

1-53

`V4L2_META_FMT_UVC`는 UVC packet header에서 추출해 metadata video node로 제공하는 표준 UVC 메타데이터입니다. UVC Payload Header 표준 부분의 정확한 사본과 header timestamp를 정밀하게 해석하는 데 필요한 보조 시간 정보가 들어갑니다.

UVC payload header 하나는 2~12바이트입니다. 프레임 하나에 camera가 header를 여러 개 전송했다면 한 버퍼에 여러 block이 들어갈 수 있습니다. 버퍼가 가득 찼거나 SCR이 없거나 직전 header와 SCR이 같아 유용하지 않거나, 장치가 너무 많은 header를 보내 rate limiting이 필요하면 드라이버가 일부를 버릴 수 있습니다.

UVC metadata block

항목설명

`__u64 ts`payload 수신 시 드라이버가 측정한 system timestamp이며 host byte order입니다.

`__u16 sof`USB Frame Number입니다. timestamp와 상관관계를 만들 수 있도록 가능한 한 같은 시점에 얻으며 host byte order입니다.

`__u8 length`이 필드를 포함한 block 나머지 길이입니다. 값과 무관하게 `V4L2_META_FMT_UVC`에서 kernel은 payload header 2~12바이트만 복사합니다.

`__u8 flags`다른 표준 UVC 필드가 존재하는지 나타냅니다.

`__u8 buf[]`UVC PTS와 SCR을 포함할 수 있는 header 나머지의 정확한 사본입니다.

드라이버가 추가한 host 정보 뒤에 payload header 사본이 이어집니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _v4l2-meta-fmt-uvc:

*******************************
V4L2_META_FMT_UVC ('UVCH')
*******************************

UVC Payload Header Data


Description
===========

This format describes standard UVC metadata, extracted from UVC packet headers
and provided by the UVC driver through metadata video nodes. That data includes
exact copies of the standard part of UVC Payload Header contents and auxiliary
timing information, required for precise interpretation of timestamps, contained
in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of
the "UVC 1.5 Class specification" for details.

Each UVC payload header can be between 2 and 12 bytes large. Buffers can
contain multiple headers, if multiple such headers have been transmitted by the
camera for the respective frame. However, the driver may drop headers when the
buffer is full, when they contain no useful information (e.g. those without the
SCR field or with that field identical to the previous header), or generally to
perform rate limiting when the device sends a large number of headers.

Each individual block contains the following fields:

.. flat-table:: UVC Metadata Block
    :widths: 1 4
    :header-rows:  1
    :stub-columns: 0

    * - Field
      - Description
    * - __u64 ts;
      - system timestamp in host byte order, measured by the driver upon
        reception of the payload
    * - __u16 sof;
      - USB Frame Number in host byte order, also obtained by the driver as
        close as possible to the above timestamp to enable correlation between
        them
    * - :cspan:`1` *The rest is an exact copy of the UVC payload header:*
    * - __u8 length;
      - length of the rest of the block, including this field. Please note that
        regardless of this value, for V4L2_META_FMT_UVC the kernel will never
        copy more than 2-12 bytes.
    * - __u8 flags;
      - Flags, indicating presence of other standard UVC fields
    * - __u8 buf[];
      - The rest of the header, possibly including UVC PTS and SCR fields