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