1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _VIDIOC_ENCODER_CMD: 4 .. _VIDIOC_ENCODER_CMD:
5 5
6 ********************************************** 6 ************************************************
7 ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_C 7 ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
8 ********************************************** 8 ************************************************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - 13 VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: VIDIOC_ENCODER_CMD 18 .. c:macro:: VIDIOC_ENCODER_CMD
19 19
20 ``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct 20 ``int ioctl(int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
21 21
22 .. c:macro:: VIDIOC_TRY_ENCODER_CMD 22 .. c:macro:: VIDIOC_TRY_ENCODER_CMD
23 23
24 ``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, st 24 ``int ioctl(int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp)``
25 25
26 Arguments 26 Arguments
27 ========= 27 =========
28 28
29 ``fd`` 29 ``fd``
30 File descriptor returned by :c:func:`open( 30 File descriptor returned by :c:func:`open()`.
31 31
32 ``argp`` 32 ``argp``
33 Pointer to struct :c:type:`v4l2_encoder_cm 33 Pointer to struct :c:type:`v4l2_encoder_cmd`.
34 34
35 Description 35 Description
36 =========== 36 ===========
37 37
38 These ioctls control an audio/video (usually M 38 These ioctls control an audio/video (usually MPEG-) encoder.
39 ``VIDIOC_ENCODER_CMD`` sends a command to the 39 ``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
40 ``VIDIOC_TRY_ENCODER_CMD`` can be used to try 40 ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
41 executing it. 41 executing it.
42 42
43 To send a command applications must initialize 43 To send a command applications must initialize all fields of a struct
44 :c:type:`v4l2_encoder_cmd` and call 44 :c:type:`v4l2_encoder_cmd` and call
45 ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER 45 ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
46 this structure. 46 this structure.
47 47
48 The ``cmd`` field must contain the command cod 48 The ``cmd`` field must contain the command code. Some commands use the
49 ``flags`` field for additional information. 49 ``flags`` field for additional information.
50 50
51 After a STOP command, :c:func:`read()` calls w 51 After a STOP command, :c:func:`read()` calls will read
52 the remaining data buffered by the driver. Whe 52 the remaining data buffered by the driver. When the buffer is empty,
53 :c:func:`read()` will return zero and the next 53 :c:func:`read()` will return zero and the next :c:func:`read()`
54 call will restart the encoder. 54 call will restart the encoder.
55 55
56 A :c:func:`read()` or :ref:`VIDIOC_STREAMON <V 56 A :c:func:`read()` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
57 call sends an implicit START command to the en 57 call sends an implicit START command to the encoder if it has not been
58 started yet. Applies to both queues of mem2mem 58 started yet. Applies to both queues of mem2mem encoders.
59 59
60 A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF 60 A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
61 call of a streaming file descriptor sends an i 61 call of a streaming file descriptor sends an implicit immediate STOP to
62 the encoder, and all buffered data is discarde 62 the encoder, and all buffered data is discarded. Applies to both queues of
63 mem2mem encoders. 63 mem2mem encoders.
64 64
65 These ioctls are optional, not all drivers may 65 These ioctls are optional, not all drivers may support them. They were
66 introduced in Linux 2.6.21. They are, however, 66 introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem
67 encoders (as further documented in :ref:`encod 67 encoders (as further documented in :ref:`encoder`).
68 68
69 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm 69 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
70 70
71 .. c:type:: v4l2_encoder_cmd 71 .. c:type:: v4l2_encoder_cmd
72 72
73 .. flat-table:: struct v4l2_encoder_cmd 73 .. flat-table:: struct v4l2_encoder_cmd
74 :header-rows: 0 74 :header-rows: 0
75 :stub-columns: 0 75 :stub-columns: 0
76 :widths: 1 1 2 76 :widths: 1 1 2
77 77
78 * - __u32 78 * - __u32
79 - ``cmd`` 79 - ``cmd``
80 - The encoder command, see :ref:`encoder 80 - The encoder command, see :ref:`encoder-cmds`.
81 * - __u32 81 * - __u32
82 - ``flags`` 82 - ``flags``
83 - Flags to go with the command, see :ref 83 - Flags to go with the command, see :ref:`encoder-flags`. If no
84 flags are defined for this command, dr 84 flags are defined for this command, drivers and applications must
85 set this field to zero. 85 set this field to zero.
86 * - __u32 86 * - __u32
87 - ``data``\ [8] 87 - ``data``\ [8]
88 - Reserved for future extensions. Driver 88 - Reserved for future extensions. Drivers and applications must set
89 the array to zero. 89 the array to zero.
90 90
91 91
92 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm 92 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
93 93
94 .. _encoder-cmds: 94 .. _encoder-cmds:
95 95
96 .. flat-table:: Encoder Commands 96 .. flat-table:: Encoder Commands
97 :header-rows: 0 97 :header-rows: 0
98 :stub-columns: 0 98 :stub-columns: 0
99 :widths: 3 1 4 99 :widths: 3 1 4
100 100
101 * - ``V4L2_ENC_CMD_START`` 101 * - ``V4L2_ENC_CMD_START``
102 - 0 102 - 0
103 - Start the encoder. When the encoder is 103 - Start the encoder. When the encoder is already running or paused,
104 this command does nothing. No flags ar 104 this command does nothing. No flags are defined for this command.
105 105
106 For a device implementing the :ref:`en 106 For a device implementing the :ref:`encoder`, once the drain sequence
107 is initiated with the ``V4L2_ENC_CMD_S 107 is initiated with the ``V4L2_ENC_CMD_STOP`` command, it must be driven
108 to completion before this command can 108 to completion before this command can be invoked. Any attempt to
109 invoke the command while the drain seq 109 invoke the command while the drain sequence is in progress will trigger
110 an ``EBUSY`` error code. See :ref:`enc 110 an ``EBUSY`` error code. See :ref:`encoder` for more details.
111 * - ``V4L2_ENC_CMD_STOP`` 111 * - ``V4L2_ENC_CMD_STOP``
112 - 1 112 - 1
113 - Stop the encoder. When the ``V4L2_ENC_ 113 - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
114 is set, encoding will continue until t 114 is set, encoding will continue until the end of the current *Group
115 Of Pictures*, otherwise encoding will 115 Of Pictures*, otherwise encoding will stop immediately. When the
116 encoder is already stopped, this comma 116 encoder is already stopped, this command does nothing.
117 117
118 For a device implementing the :ref:`en 118 For a device implementing the :ref:`encoder`, the command will initiate
119 the drain sequence as documented in :r 119 the drain sequence as documented in :ref:`encoder`. No flags or other
120 arguments are accepted in this case. A 120 arguments are accepted in this case. Any attempt to invoke the command
121 again before the sequence completes wi 121 again before the sequence completes will trigger an ``EBUSY`` error
122 code. 122 code.
123 * - ``V4L2_ENC_CMD_PAUSE`` 123 * - ``V4L2_ENC_CMD_PAUSE``
124 - 2 124 - 2
125 - Pause the encoder. When the encoder ha 125 - Pause the encoder. When the encoder has not been started yet, the
126 driver will return an ``EPERM`` error 126 driver will return an ``EPERM`` error code. When the encoder is
127 already paused, this command does noth 127 already paused, this command does nothing. No flags are defined
128 for this command. 128 for this command.
129 * - ``V4L2_ENC_CMD_RESUME`` 129 * - ``V4L2_ENC_CMD_RESUME``
130 - 3 130 - 3
131 - Resume encoding after a PAUSE command. 131 - Resume encoding after a PAUSE command. When the encoder has not
132 been started yet, the driver will retu 132 been started yet, the driver will return an ``EPERM`` error code. When
133 the encoder is already running, this c 133 the encoder is already running, this command does nothing. No
134 flags are defined for this command. 134 flags are defined for this command.
135 135
136 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm 136 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
137 137
138 .. _encoder-flags: 138 .. _encoder-flags:
139 139
140 .. flat-table:: Encoder Command Flags 140 .. flat-table:: Encoder Command Flags
141 :header-rows: 0 141 :header-rows: 0
142 :stub-columns: 0 142 :stub-columns: 0
143 :widths: 3 1 4 143 :widths: 3 1 4
144 144
145 * - ``V4L2_ENC_CMD_STOP_AT_GOP_END`` 145 * - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
146 - 0x0001 146 - 0x0001
147 - Stop encoding at the end of the curren 147 - Stop encoding at the end of the current *Group Of Pictures*,
148 rather than immediately. 148 rather than immediately.
149 149
150 Does not apply to :ref:`encoder`. 150 Does not apply to :ref:`encoder`.
151 151
152 Return Value 152 Return Value
153 ============ 153 ============
154 154
155 On success 0 is returned, on error -1 and the 155 On success 0 is returned, on error -1 and the ``errno`` variable is set
156 appropriately. The generic error codes are des 156 appropriately. The generic error codes are described at the
157 :ref:`Generic Error Codes <gen-errors>` chapte 157 :ref:`Generic Error Codes <gen-errors>` chapter.
158 158
159 EBUSY 159 EBUSY
160 A drain sequence of a device implementing 160 A drain sequence of a device implementing the :ref:`encoder` is still in
161 progress. It is not allowed to issue anoth 161 progress. It is not allowed to issue another encoder command until it
162 completes. 162 completes.
163 163
164 EINVAL 164 EINVAL
165 The ``cmd`` field is invalid. 165 The ``cmd`` field is invalid.
166 166
167 EPERM 167 EPERM
168 The application sent a PAUSE or RESUME com 168 The application sent a PAUSE or RESUME command when the encoder was
169 not running. 169 not running.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.