요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _VIDIOC_QUERY_DV_TIMINGS:
6
*****************************
7
ioctl VIDIOC_QUERY_DV_TIMINGS
8
*****************************
10
Name
11
====
13
VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_QUERY_DV_TIMINGS
20
``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
22
.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
24
``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
26
Arguments
27
=========
29
``fd``
30
File descriptor returned by :c:func:`open()`.
32
``argp``
33
Pointer to struct :c:type:`v4l2_dv_timings`.
35
Description
36
===========
38
The hardware may be able to detect the current DV timings automatically,
39
similar to sensing the video standard. To do so, applications call
40
:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
41
:c:type:`v4l2_dv_timings`. Once the hardware detects
42
the timings, it will fill in the timings structure.
44
.. note::
46
Drivers shall *not* switch timings automatically if new
47
timings are detected. Instead, drivers should send the
48
``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
49
that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
50
The reason is that new timings usually mean different buffer sizes as
51
well, and you cannot change buffer sizes on the fly. In general,
52
applications that receive the Source Change event will have to call
53
:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
54
will have to stop streaming, set the new timings, allocate new buffers
55
and start streaming again.
57
If the timings could not be detected because there was no signal, then
58
ENOLINK is returned. If a signal was detected, but it was unstable and
59
the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
60
the receiver could lock to the signal, but the format is unsupported
61
(e.g. because the pixelclock is out of range of the hardware
62
capabilities), then the driver fills in whatever timings it could find
63
and returns ``ERANGE``. In that case the application can call
64
:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
65
found timings with the hardware's capabilities in order to give more
66
precise feedback to the user.
68
Return Value
69
============
71
On success 0 is returned, on error -1 and the ``errno`` variable is set
72
appropriately. The generic error codes are described at the
73
:ref:`Generic Error Codes <gen-errors>` chapter.
75
ENODATA
76
Digital video timings are not supported for this input or output.
78
ENOLINK
79
No timings could be detected because no signal was found.
81
ENOLCK
82
The signal was unstable and the hardware could not lock on to it.
84
ERANGE
85
Timings were found, but they are out of range of the hardware
86
capabilities.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-34`VIDIOC_QUERY_DV_TIMINGS`와 `VIDIOC_SUBDEV_QUERY_DV_TIMINGS`는 현재 입력에서 감지된 digital video timing을 `struct v4l2_dv_timings`에 보고합니다. 전자는 일반 V4L2 device, 후자는 subdevice node에 사용합니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_QUERY_DV_TIMINGS:
*****************************
ioctl VIDIOC_QUERY_DV_TIMINGS
*****************************
Name
====
VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
Synopsis
========
.. c:macro:: VIDIOC_QUERY_DV_TIMINGS
``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_dv_timings`.
자동 감지와 source change 처리
35-56하드웨어가 현재 DV timing을 자동 감지할 수 있으면 애플리케이션은 timing 구조체 포인터로 이 ioctl을 호출합니다. Lock에 성공한 하드웨어가 구조체를 채웁니다.
새 timing을 발견해도 드라이버가 자동으로 전환해서는 안 됩니다. 지원하는 경우 `V4L2_EVENT_SOURCE_CHANGE`를 보내고 사용자 공간이 `VIDIOC_QUERY_DV_TIMINGS`를 호출해 대응하도록 해야 합니다.
1. `V4L2_EVENT_SOURCE_CHANGE` 수신→2. `VIDIOC_QUERY_DV_TIMINGS`로 새 timing 감지→3. 감지값이 유효하면 streaming 중지→4. 새 timing 설정→5. 새 크기로 buffer 재할당→6. streaming 재시작
Timing 변경은 보통 buffer 크기 변경도 요구하므로 streaming 중 즉시 적용할 수 없습니다.
Description
===========
The hardware may be able to detect the current DV timings automatically,
similar to sensing the video standard. To do so, applications call
:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
:c:type:`v4l2_dv_timings`. Once the hardware detects
the timings, it will fill in the timings structure.
.. note::
Drivers shall *not* switch timings automatically if new
timings are detected. Instead, drivers should send the
``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
The reason is that new timings usually mean different buffer sizes as
well, and you cannot change buffer sizes on the fly. In general,
applications that receive the Source Change event will have to call
:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
will have to stop streaming, set the new timings, allocate new buffers
and start streaming again.
신호 상태별 감지 결과
57-67상태결과
신호 없음`ENOLINK`
신호가 불안정해 receiver가 lock하지 못함`ENOLCK`
lock은 했지만 pixelclock 등 timing이 하드웨어 범위 밖찾은 timing을 가능한 만큼 채우고 `ERANGE`
신호 존재, lock 여부, 하드웨어 지원 범위를 구분합니다.
`ERANGE`일 때 애플리케이션은 `VIDIOC_DV_TIMINGS_CAP`으로 감지값과 하드웨어 capability를 비교해 사용자에게 더 정확한 원인을 제시할 수 있습니다.
If the timings could not be detected because there was no signal, then
ENOLINK is returned. If a signal was detected, but it was unstable and
the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
the receiver could lock to the signal, but the format is unsupported
(e.g. because the pixelclock is out of range of the hardware
capabilities), then the driver fills in whatever timings it could find
and returns ``ERANGE``. In that case the application can call
:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
found timings with the hardware's capabilities in order to give more
precise feedback to the user.
반환값과 오류
68-86성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`ENODATA`현재 input 또는 output이 digital video timing을 지원하지 않음
`ENOLINK`신호가 없어 timing을 감지할 수 없음
`ENOLCK`신호가 불안정해 하드웨어가 lock하지 못함
`ERANGE`timing은 찾았지만 하드웨어 capability 범위 밖
입출력의 기능과 감지 단계에 따른 오류입니다.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
ENODATA
Digital video timings are not supported for this input or output.
ENOLINK
No timings could be detected because no signal was found.
ENOLCK
The signal was unstable and the hardware could not lock on to it.
ERANGE
Timings were found, but they are out of range of the hardware
capabilities.
요약·해설
vidioc-query-dv-timings.rst:1-86Timing 변경은 buffer 크기까지 바꿀 수 있으므로 드라이버 자동 전환이 아니라 사용자 공간 재협상이 필요합니다.