← Documents Documentation/userspace-api/media/v4l/vidioc-g-priority.rst GitHub 원문 ↗

Linux 6.18.37 · 사용자 공간 API

VIDIOC_G_PRIORITY·VIDIOC_S_PRIORITY ioctl

파일 디스크립터별 V4L2 장치 접근 priority를 조회·요청하고 background·interactive·record 우선권 충돌을 처리하는 방법을 설명합니다.

Source pathDocumentation/userspace-api/media/v4l/vidioc-g-priority.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

요약·해설

vidioc-g-priority.rst:1-91

파일 디스크립터의 장치 접근 우선순위와 충돌 규칙을 다룹니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_G_PRIORITY:
5
6 ******************************************
7 ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
8 ******************************************
9
10 Name
11 ====
12
13 VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_G_PRIORITY
19
20 ``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)``
21
22 .. c:macro:: VIDIOC_S_PRIORITY
23
24 ``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)``
25
26 Arguments
27 =========
28
29 ``fd``
30 File descriptor returned by :c:func:`open()`.
31
32 ``argp``
33 Pointer to an enum :c:type:`v4l2_priority` type.
34
35 Description
36 ===========
37
38 To query the current access priority applications call the
39 :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
40 variable where the driver stores the current priority.
41
42 To request an access priority applications store the desired priority in
43 an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
44 with a pointer to this variable.
45
46 .. c:type:: v4l2_priority
47
48 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
49
50 .. flat-table:: enum v4l2_priority
51 :header-rows: 0
52 :stub-columns: 0
53 :widths: 3 1 4
54
55 * - ``V4L2_PRIORITY_UNSET``
56 - 0
57 -
58 * - ``V4L2_PRIORITY_BACKGROUND``
59 - 1
60 - Lowest priority, usually applications running in background, for
61 example monitoring VBI transmissions. A proxy application running
62 in user space will be necessary if multiple applications want to
63 read from a device at this priority.
64 * - ``V4L2_PRIORITY_INTERACTIVE``
65 - 2
66 -
67 * - ``V4L2_PRIORITY_DEFAULT``
68 - 2
69 - Medium priority, usually applications started and interactively
70 controlled by the user. For example TV viewers, Teletext browsers,
71 or just "panel" applications to change the channel or video
72 controls. This is the default priority unless an application
73 requests another.
74 * - ``V4L2_PRIORITY_RECORD``
75 - 3
76 - Highest priority. Only one file descriptor can have this priority,
77 it blocks any other fd from changing device properties. Usually
78 applications which must not be interrupted, like video recording.
79
80 Return Value
81 ============
82
83 On success 0 is returned, on error -1 and the ``errno`` variable is set
84 appropriately. The generic error codes are described at the
85 :ref:`Generic Error Codes <gen-errors>` chapter.
86
87 EINVAL
88 The requested priority value is invalid.
89
90 EBUSY
91 Another application already requested higher priority.
92

3. 한국어 전문 번역

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

목적, 호출 형식과 인자

1-34

`VIDIOC_G_PRIORITY`와 `VIDIOC_S_PRIORITY`는 파일 디스크립터에 연결된 V4L2 장치 접근 우선순위를 조회하거나 요청합니다.

두 명령은 `enum v4l2_priority` 포인터를 사용합니다. 조회는 수정 가능한 포인터, 설정은 const 포인터를 받고 `fd`는 `open()`이 반환한 파일 디스크립터입니다.

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

.. _VIDIOC_G_PRIORITY:

******************************************
ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
******************************************

Name
====

VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor

Synopsis
========

.. c:macro:: VIDIOC_G_PRIORITY

``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)``

.. c:macro:: VIDIOC_S_PRIORITY

``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to an enum :c:type:`v4l2_priority` type.

현재 우선순위 조회와 요청

35-45

현재 접근 우선순위를 조회하려면 enum 변수 포인터로 G_PRIORITY를 호출합니다. 드라이버가 현재 priority를 저장합니다.

원하는 priority를 요청하려면 enum 변수에 값을 저장해 S_PRIORITY를 호출합니다. 더 높은 priority를 다른 애플리케이션이 이미 요청했다면 `EBUSY`입니다.

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

To query the current access priority applications call the
:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
variable where the driver stores the current priority.

To request an access priority applications store the desired priority in
an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
with a pointer to this variable.

enum v4l2_priority

46-79
v4l2_priority 값
상수값용도
`V4L2_PRIORITY_UNSET``0`우선순위를 설정하지 않은 상태
`V4L2_PRIORITY_BACKGROUND``1`최저 우선순위. VBI 감시 같은 background 작업
`V4L2_PRIORITY_INTERACTIVE``2`사용자가 대화식으로 제어하는 중간 우선순위
`V4L2_PRIORITY_DEFAULT``2`INTERACTIVE의 별칭이며 별도 요청이 없을 때 기본값
`V4L2_PRIORITY_RECORD``3`최고 우선순위. 중단되면 안 되는 video recording

값이 높을수록 장치 속성 변경에 강한 접근 우선권을 갖습니다.

BACKGROUND priority에서 여러 애플리케이션이 같은 장치를 읽으려면 사용자 공간 proxy 애플리케이션이 필요합니다.

INTERACTIVE·DEFAULT는 TV viewer, Teletext browser, channel·video control panel 같은 대화형 프로그램에 쓰입니다.

RECORD priority는 하나의 파일 디스크립터만 가질 수 있으며 다른 fd가 장치 속성을 바꾸지 못하게 막습니다.

.. c:type:: v4l2_priority

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. flat-table:: enum v4l2_priority
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_PRIORITY_UNSET``
      - 0
      -
    * - ``V4L2_PRIORITY_BACKGROUND``
      - 1
      - Lowest priority, usually applications running in background, for
	example monitoring VBI transmissions. A proxy application running
	in user space will be necessary if multiple applications want to
	read from a device at this priority.
    * - ``V4L2_PRIORITY_INTERACTIVE``
      - 2
      -
    * - ``V4L2_PRIORITY_DEFAULT``
      - 2
      - Medium priority, usually applications started and interactively
	controlled by the user. For example TV viewers, Teletext browsers,
	or just "panel" applications to change the channel or video
	controls. This is the default priority unless an application
	requests another.
    * - ``V4L2_PRIORITY_RECORD``
      - 3
      - Highest priority. Only one file descriptor can have this priority,
	it blocks any other fd from changing device properties. Usually
	applications which must not be interrupted, like video recording.

반환값과 오류

80-91

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며 Generic Error Codes 장의 공통 오류도 적용됩니다.

priority 오류
errno조건
`EINVAL`요청한 priority 값이 유효하지 않음
`EBUSY`다른 애플리케이션이 이미 더 높은 priority를 요청함

요청값과 기존 우선권 충돌에 따른 오류입니다.

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.

EINVAL
    The requested priority value is invalid.

EBUSY
    Another application already requested higher priority.