요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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_SUBDEV_G_CLIENT_CAP:
6
************************************************************
7
ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP
8
************************************************************
10
Name
11
====
13
VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client
14
capabilities.
16
Synopsis
17
========
19
.. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP
21
``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
23
.. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP
25
``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
27
Arguments
28
=========
30
``fd``
31
File descriptor returned by :ref:`open() <func-open>`.
33
``argp``
34
Pointer to struct :c:type:`v4l2_subdev_client_capability`.
36
Description
37
===========
39
These ioctls are used to get and set the client (the application using the
40
subdevice ioctls) capabilities. The client capabilities are stored in the file
41
handle of the opened subdev device node, and the client must set the
42
capabilities for each opened subdev separately.
44
By default no client capabilities are set when a subdev device node is opened.
46
The purpose of the client capabilities are to inform the kernel of the behavior
47
of the client, mainly related to maintaining compatibility with different
48
kernel and userspace versions.
50
The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities
51
associated with the file handle ``fd``.
53
The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file
54
handle ``fd``. The new capabilities fully replace the current capabilities, the
55
ioctl can therefore also be used to remove capabilities that have previously
56
been set.
58
``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct
59
:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have
60
been accepted. A common case for the kernel not accepting a capability is that
61
the kernel is older than the headers the userspace uses, and thus the capability
62
is unknown to the kernel.
64
.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}|
66
.. c:type:: v4l2_subdev_client_capability
68
.. flat-table:: struct v4l2_subdev_client_capability
69
:header-rows: 0
70
:stub-columns: 0
71
:widths: 3 4 20
73
* - __u64
74
- ``capabilities``
75
- Sub-device client capabilities of the opened device.
77
.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}|
79
.. flat-table:: Client Capabilities
80
:header-rows: 1
82
* - Capability
83
- Description
84
* - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS``
85
- The client is aware of streams. Setting this flag enables the use
86
of 'stream' fields (referring to the stream number) with various
87
ioctls. If this is not set (which is the default), the 'stream' fields
88
will be forced to 0 by the kernel.
89
* - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH``
90
- The client is aware of the :c:type:`v4l2_subdev_frame_interval`
91
``which`` field. If this is not set (which is the default), the
92
``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the
93
kernel.
95
Return Value
96
============
98
On success 0 is returned, on error -1 and the ``errno`` variable is set
99
appropriately. The generic error codes are described at the
100
:ref:`Generic Error Codes <gen-errors>` chapter.
102
ENOIOCTLCMD
103
The kernel does not support this ioctl.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-35`VIDIOC_SUBDEV_G_CLIENT_CAP`과 `VIDIOC_SUBDEV_S_CLIENT_CAP`은 서브디바이스 ioctl을 사용하는 클라이언트의 capability를 조회하거나 설정합니다. `argp`는 `struct v4l2_subdev_client_capability`를 가리킵니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_SUBDEV_G_CLIENT_CAP:
************************************************************
ioctl VIDIOC_SUBDEV_G_CLIENT_CAP, VIDIOC_SUBDEV_S_CLIENT_CAP
************************************************************
Name
====
VIDIOC_SUBDEV_G_CLIENT_CAP - VIDIOC_SUBDEV_S_CLIENT_CAP - Get or set client
capabilities.
Synopsis
========
.. c:macro:: VIDIOC_SUBDEV_G_CLIENT_CAP
``int ioctl(int fd, VIDIOC_SUBDEV_G_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
.. c:macro:: VIDIOC_SUBDEV_S_CLIENT_CAP
``int ioctl(int fd, VIDIOC_SUBDEV_S_CLIENT_CAP, struct v4l2_subdev_client_capability *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <func-open>`.
``argp``
Pointer to struct :c:type:`v4l2_subdev_client_capability`.
파일 핸들별 설정과 커널 승인
36-62클라이언트 capability는 열린 서브디바이스 장치 노드의 파일 핸들에 저장됩니다. 같은 장치를 여러 번 열었다면 각 파일 핸들에 대해 별도로 설정해야 하며, 새로 연 노드의 기본값은 capability 없음입니다.
이 정보는 주로 서로 다른 커널과 사용자 공간 버전 사이의 호환성을 유지할 수 있도록 클라이언트의 동작 방식을 커널에 알리는 데 사용됩니다.
`VIDIOC_SUBDEV_G_CLIENT_CAP`은 `fd`에 연결된 현재 capability를 반환합니다. `VIDIOC_SUBDEV_S_CLIENT_CAP`은 새 비트 집합으로 현재 값을 완전히 교체하므로, 이전에 설정한 capability를 제거하는 용도로도 사용할 수 있습니다.
S_CLIENT_CAP 호출 뒤 구조체의 값은 커널이 실제로 승인한 capability로 수정됩니다. 사용자 공간 헤더가 커널보다 새로워 커널이 어떤 비트를 모르면 그 비트는 승인 결과에서 빠질 수 있으므로, 응용 프로그램은 반환된 값을 다시 확인해야 합니다.
서브디바이스 노드를 열어 파일 핸들 생성→원하는 capability 비트 집합으로 S_CLIENT_CAP 호출→커널이 알고 지원하는 비트만 승인→수정되어 돌아온 capabilities를 실제 적용값으로 저장→필요하면 G_CLIENT_CAP으로 현재 파일 핸들 상태 재조회
요청한 비트와 실제 적용된 비트를 구분합니다.
Description
===========
These ioctls are used to get and set the client (the application using the
subdevice ioctls) capabilities. The client capabilities are stored in the file
handle of the opened subdev device node, and the client must set the
capabilities for each opened subdev separately.
By default no client capabilities are set when a subdev device node is opened.
The purpose of the client capabilities are to inform the kernel of the behavior
of the client, mainly related to maintaining compatibility with different
kernel and userspace versions.
The ``VIDIOC_SUBDEV_G_CLIENT_CAP`` ioctl returns the current client capabilities
associated with the file handle ``fd``.
The ``VIDIOC_SUBDEV_S_CLIENT_CAP`` ioctl sets client capabilities for the file
handle ``fd``. The new capabilities fully replace the current capabilities, the
ioctl can therefore also be used to remove capabilities that have previously
been set.
``VIDIOC_SUBDEV_S_CLIENT_CAP`` modifies the struct
:c:type:`v4l2_subdev_client_capability` to reflect the capabilities that have
been accepted. A common case for the kernel not accepting a capability is that
the kernel is older than the headers the userspace uses, and thus the capability
is unknown to the kernel.구조체와 capability 비트
63-94형식필드의미
`__u64``capabilities`열린 서브디바이스의 클라이언트 capability 비트 집합
열린 장치에 적용할 클라이언트 동작 인식 수준을 나타냅니다.
capability설정했을 때설정하지 않았을 때
`V4L2_SUBDEV_CLIENT_CAP_STREAMS`클라이언트가 stream 번호를 인식하며 여러 ioctl의 `stream` 필드를 사용할 수 있음커널이 `stream` 필드를 0으로 강제
`V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH`클라이언트가 `v4l2_subdev_frame_interval.which`를 인식함커널이 `which`를 `V4L2_SUBDEV_FORMAT_ACTIVE`로 강제
비트를 설정하지 않으면 커널이 구형 클라이언트 호환 기본값을 강제합니다.
capability를 설정하는 것은 기능을 무조건 활성화하는 요청이 아니라 클라이언트가 해당 필드 의미를 이해한다고 커널에 알리는 계약입니다.
.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}|
.. c:type:: v4l2_subdev_client_capability
.. flat-table:: struct v4l2_subdev_client_capability
:header-rows: 0
:stub-columns: 0
:widths: 3 4 20
* - __u64
- ``capabilities``
- Sub-device client capabilities of the opened device.
.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}|
.. flat-table:: Client Capabilities
:header-rows: 1
* - Capability
- Description
* - ``V4L2_SUBDEV_CLIENT_CAP_STREAMS``
- The client is aware of streams. Setting this flag enables the use
of 'stream' fields (referring to the stream number) with various
ioctls. If this is not set (which is the default), the 'stream' fields
will be forced to 0 by the kernel.
* - ``V4L2_SUBDEV_CLIENT_CAP_INTERVAL_USES_WHICH``
- The client is aware of the :c:type:`v4l2_subdev_frame_interval`
``which`` field. If this is not set (which is the default), the
``which`` field is forced to ``V4L2_SUBDEV_FORMAT_ACTIVE`` by the
kernel.
반환값과 ENOIOCTLCMD
95-103성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.
errno조건
`ENOIOCTLCMD`커널이 이 ioctl을 지원하지 않음
구형 커널에서는 ioctl 자체가 없을 수 있습니다.
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.
ENOIOCTLCMD
The kernel does not support this ioctl.
요약·해설
vidioc-subdev-g-client-cap.rst:1-103S_CLIENT_CAP에 넣은 요청값보다 호출 뒤 구조체에 남은 커널 승인값이 중요하며, 각 열린 서브디바이스 파일 핸들마다 별도로 협상해야 합니다.