Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_G_MODULATOR: |
5377d91f MH |
4 | |
5 | ******************************************** | |
6 | ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR | |
7 | ******************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp ) |
19 | :name: VIDIOC_G_MODULATOR | |
5377d91f | 20 | |
41d80465 MCC |
21 | .. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp ) |
22 | :name: VIDIOC_S_MODULATOR | |
5377d91f | 23 | |
586027ce | 24 | |
15e7d615 | 25 | Arguments |
5377d91f MH |
26 | ========= |
27 | ||
28 | ``fd`` | |
29 | File descriptor returned by :ref:`open() <func-open>`. | |
30 | ||
5377d91f MH |
31 | ``argp`` |
32 | ||
33 | ||
15e7d615 | 34 | Description |
5377d91f MH |
35 | =========== |
36 | ||
37 | To query the attributes of a modulator applications initialize the | |
38 | ``index`` field and zero out the ``reserved`` array of a struct | |
e8be7e97 | 39 | :c:type:`v4l2_modulator` and call the |
4e03cb76 | 40 | :ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers |
cdb4af0f | 41 | fill the rest of the structure or return an ``EINVAL`` error code when the |
5377d91f MH |
42 | index is out of bounds. To enumerate all modulators applications shall |
43 | begin at index zero, incrementing by one until the driver returns | |
44 | EINVAL. | |
45 | ||
46 | Modulators have two writable properties, an audio modulation set and the | |
47 | radio frequency. To change the modulated audio subprograms, applications | |
48 | initialize the ``index`` and ``txsubchans`` fields and the ``reserved`` | |
2212ff25 | 49 | array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a |
5377d91f MH |
50 | different audio modulation if the request cannot be satisfied. However |
51 | this is a write-only ioctl, it does not return the actual audio | |
52 | modulation selected. | |
53 | ||
54 | :ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and | |
55 | ``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be | |
56 | initialized to zero. The term 'modulator' means SDR transmitter in this | |
57 | context. | |
58 | ||
59 | To change the radio frequency the | |
af4a4d0d | 60 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. |
5377d91f MH |
61 | |
62 | ||
5bd4bb78 MCC |
63 | .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| |
64 | ||
e8be7e97 | 65 | .. c:type:: v4l2_modulator |
fa92b04d | 66 | |
5377d91f MH |
67 | .. flat-table:: struct v4l2_modulator |
68 | :header-rows: 0 | |
69 | :stub-columns: 0 | |
70 | :widths: 1 1 2 1 1 | |
71 | ||
72 | ||
73 | - .. row 1 | |
74 | ||
75 | - __u32 | |
76 | ||
77 | - ``index`` | |
78 | ||
79 | - Identifies the modulator, set by the application. | |
80 | ||
81 | - .. row 2 | |
82 | ||
83 | - __u8 | |
84 | ||
8968da9b | 85 | - ``name``\ [32] |
5377d91f | 86 | |
ef76c068 MCC |
87 | - Name of the modulator, a NUL-terminated ASCII string. |
88 | ||
89 | This information is intended for the user. | |
5377d91f MH |
90 | |
91 | - .. row 3 | |
92 | ||
93 | - __u32 | |
94 | ||
95 | - ``capability`` | |
96 | ||
97 | - Modulator capability flags. No flags are defined for this field, | |
e8be7e97 | 98 | the tuner flags in struct :c:type:`v4l2_tuner` are |
0579e6e3 MCC |
99 | used accordingly. The audio flags indicate the ability to encode |
100 | audio subprograms. They will *not* change for example with the | |
101 | current video standard. | |
5377d91f MH |
102 | |
103 | - .. row 4 | |
104 | ||
105 | - __u32 | |
106 | ||
107 | - ``rangelow`` | |
108 | ||
109 | - The lowest tunable frequency in units of 62.5 KHz, or if the | |
0579e6e3 MCC |
110 | ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of |
111 | 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is | |
112 | set, in units of 1 Hz. | |
5377d91f MH |
113 | |
114 | - .. row 5 | |
115 | ||
116 | - __u32 | |
117 | ||
118 | - ``rangehigh`` | |
119 | ||
120 | - The highest tunable frequency in units of 62.5 KHz, or if the | |
0579e6e3 MCC |
121 | ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of |
122 | 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is | |
123 | set, in units of 1 Hz. | |
5377d91f MH |
124 | |
125 | - .. row 6 | |
126 | ||
127 | - __u32 | |
128 | ||
129 | - ``txsubchans`` | |
130 | ||
131 | - With this field applications can determine how audio sub-carriers | |
0579e6e3 | 132 | shall be modulated. It contains a set of flags as defined in |
706f8a99 MCC |
133 | :ref:`modulator-txsubchans`. |
134 | ||
b6b6e678 MCC |
135 | .. note:: |
136 | ||
137 | The tuner ``rxsubchans`` flags are reused, but the | |
706f8a99 MCC |
138 | semantics are different. Video output devices |
139 | are assumed to have an analog or PCM audio input with 1-3 | |
140 | channels. The ``txsubchans`` flags select one or more channels | |
141 | for modulation, together with some audio subprogram indicator, | |
142 | for example, a stereo pilot tone. | |
5377d91f MH |
143 | |
144 | - .. row 7 | |
145 | ||
146 | - __u32 | |
147 | ||
148 | - ``type`` | |
149 | ||
56683d7d | 150 | - :cspan:`2` Type of the modulator, see :c:type:`v4l2_tuner_type`. |
5377d91f MH |
151 | |
152 | - .. row 8 | |
153 | ||
154 | - __u32 | |
155 | ||
8968da9b | 156 | - ``reserved``\ [3] |
5377d91f | 157 | |
ef76c068 MCC |
158 | - Reserved for future extensions. |
159 | ||
160 | Drivers and applications must set the array to zero. | |
5377d91f MH |
161 | |
162 | ||
163 | ||
5bd4bb78 MCC |
164 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
165 | ||
fa92b04d MCC |
166 | .. _modulator-txsubchans: |
167 | ||
5377d91f MH |
168 | .. flat-table:: Modulator Audio Transmission Flags |
169 | :header-rows: 0 | |
170 | :stub-columns: 0 | |
171 | :widths: 3 1 4 | |
172 | ||
173 | ||
174 | - .. row 1 | |
175 | ||
176 | - ``V4L2_TUNER_SUB_MONO`` | |
177 | ||
178 | - 0x0001 | |
179 | ||
180 | - Modulate channel 1 as mono audio, when the input has more | |
0579e6e3 MCC |
181 | channels, a down-mix of channel 1 and 2. This flag does not |
182 | combine with ``V4L2_TUNER_SUB_STEREO`` or | |
183 | ``V4L2_TUNER_SUB_LANG1``. | |
5377d91f MH |
184 | |
185 | - .. row 2 | |
186 | ||
187 | - ``V4L2_TUNER_SUB_STEREO`` | |
188 | ||
189 | - 0x0002 | |
190 | ||
191 | - Modulate channel 1 and 2 as left and right channel of a stereo | |
0579e6e3 MCC |
192 | audio signal. When the input has only one channel or two channels |
193 | and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as | |
194 | left and right channel. This flag does not combine with | |
195 | ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the | |
196 | driver does not support stereo audio it shall fall back to mono. | |
5377d91f MH |
197 | |
198 | - .. row 3 | |
199 | ||
200 | - ``V4L2_TUNER_SUB_LANG1`` | |
201 | ||
202 | - 0x0008 | |
203 | ||
204 | - Modulate channel 1 and 2 as primary and secondary language of a | |
0579e6e3 MCC |
205 | bilingual audio signal. When the input has only one channel it is |
206 | used for both languages. It is not possible to encode the primary | |
207 | or secondary language only. This flag does not combine with | |
208 | ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or | |
209 | ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the | |
210 | respective audio matrix, or the current video standard does not | |
211 | permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall | |
212 | return an ``EINVAL`` error code and the driver shall fall back to mono | |
213 | or stereo mode. | |
5377d91f MH |
214 | |
215 | - .. row 4 | |
216 | ||
217 | - ``V4L2_TUNER_SUB_LANG2`` | |
218 | ||
219 | - 0x0004 | |
220 | ||
221 | - Same effect as ``V4L2_TUNER_SUB_SAP``. | |
222 | ||
223 | - .. row 5 | |
224 | ||
225 | - ``V4L2_TUNER_SUB_SAP`` | |
226 | ||
227 | - 0x0004 | |
228 | ||
229 | - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is | |
0579e6e3 MCC |
230 | encoded as mono audio, the last channel as Second Audio Program. |
231 | When the input has only one channel it is used for both audio | |
232 | tracks. When the input has three channels the mono track is a | |
233 | down-mix of channel 1 and 2. When combined with | |
234 | ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and | |
235 | right stereo audio, channel 3 as Second Audio Program. When the | |
236 | input has only two channels, the first is encoded as left and | |
237 | right channel and the second as SAP. When the input has only one | |
238 | channel it is used for all audio tracks. It is not possible to | |
239 | encode a Second Audio Program only. This flag must combine with | |
240 | ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the | |
241 | hardware does not support the respective audio matrix, or the | |
242 | current video standard does not permit SAP the | |
243 | :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and | |
244 | driver shall fall back to mono or stereo mode. | |
5377d91f MH |
245 | |
246 | - .. row 6 | |
247 | ||
248 | - ``V4L2_TUNER_SUB_RDS`` | |
249 | ||
250 | - 0x0010 | |
251 | ||
252 | - Enable the RDS encoder for a radio FM transmitter. | |
253 | ||
254 | ||
15e7d615 | 255 | Return Value |
5377d91f MH |
256 | ============ |
257 | ||
258 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
259 | appropriately. The generic error codes are described at the | |
260 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
261 | ||
262 | EINVAL | |
e8be7e97 | 263 | The struct :c:type:`v4l2_modulator` ``index`` is |
5377d91f | 264 | out of bounds. |