tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
DocBook/dvb: Improve description of the DVB API v5
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
+315
-68
+8
Documentation/DocBook/dvb/dvbapi.xml
+8
Documentation/DocBook/dvb/dvbapi.xml
···
35
35
<revhistory>
36
36
<!-- Put document revisions here, newest first. -->
37
37
<revision>
38
+
<revnumber>2.0.4</revnumber>
39
+
<date>2011-05-06</date>
40
+
<authorinitials>mcc</authorinitials>
41
+
<revremark>
42
+
Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's.
43
+
</revremark>
44
+
</revision>
45
+
<revision>
38
46
<revnumber>2.0.3</revnumber>
39
47
<date>2010-07-03</date>
40
48
<authorinitials>mcc</authorinitials>
+307
-68
Documentation/DocBook/dvb/dvbproperty.xml
+307
-68
Documentation/DocBook/dvb/dvbproperty.xml
···
1
-
<section id="FE_GET_PROPERTY">
1
+
<section id="FE_GET_SET_PROPERTY">
2
2
<title>FE_GET_PROPERTY/FE_SET_PROPERTY</title>
3
+
4
+
<programlisting>
5
+
/* Reserved fields should be set to 0 */
6
+
struct dtv_property {
7
+
__u32 cmd;
8
+
union {
9
+
__u32 data;
10
+
struct {
11
+
__u8 data[32];
12
+
__u32 len;
13
+
__u32 reserved1[3];
14
+
void *reserved2;
15
+
} buffer;
16
+
} u;
17
+
int result;
18
+
} __attribute__ ((packed));
19
+
20
+
/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
21
+
#define DTV_IOCTL_MAX_MSGS 64
22
+
23
+
struct dtv_properties {
24
+
__u32 num;
25
+
struct dtv_property *props;
26
+
};
27
+
</programlisting>
28
+
29
+
<section id="FE_GET_PROPERTY">
30
+
<title>FE_GET_PROPERTY</title>
31
+
<para>DESCRIPTION
32
+
</para>
33
+
<informaltable><tgroup cols="1"><tbody><row><entry
34
+
align="char">
35
+
<para>This ioctl call returns one or more frontend properties. This call only
36
+
requires read-only access to the device.</para>
37
+
</entry>
38
+
</row></tbody></tgroup></informaltable>
39
+
<para>SYNOPSIS
40
+
</para>
41
+
<informaltable><tgroup cols="1"><tbody><row><entry
42
+
align="char">
43
+
<para>int ioctl(int fd, int request = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>,
44
+
dtv_properties ⋆props);</para>
45
+
</entry>
46
+
</row></tbody></tgroup></informaltable>
47
+
<para>PARAMETERS
48
+
</para>
49
+
<informaltable><tgroup cols="2"><tbody><row><entry align="char">
50
+
<para>int fd</para>
51
+
</entry><entry
52
+
align="char">
53
+
<para>File descriptor returned by a previous call to open().</para>
54
+
</entry>
55
+
</row><row><entry
56
+
align="char">
57
+
<para>int num</para>
58
+
</entry><entry
59
+
align="char">
60
+
<para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para>
61
+
</entry>
62
+
</row><row><entry
63
+
align="char">
64
+
<para>struct dtv_property *props</para>
65
+
</entry><entry
66
+
align="char">
67
+
<para>Points to the location where the front-end property commands are stored.</para>
68
+
</entry>
69
+
</row></tbody></tgroup></informaltable>
70
+
<para>ERRORS</para>
71
+
<informaltable><tgroup cols="2"><tbody><row>
72
+
<entry align="char"><para>EINVAL</para></entry>
73
+
<entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
74
+
</row><row>
75
+
<entry align="char"><para>ENOMEM</para></entry>
76
+
<entry align="char"><para>Out of memory.</para></entry>
77
+
</row><row>
78
+
<entry align="char"><para>EFAULT</para></entry>
79
+
<entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
80
+
</row><row>
81
+
<entry align="char"><para>EOPNOTSUPP</para></entry>
82
+
<entry align="char"><para>Property type not supported.</para></entry>
83
+
</row></tbody></tgroup></informaltable>
84
+
</section>
85
+
86
+
<section id="FE_SET_PROPERTY">
87
+
<title>FE_SET_PROPERTY</title>
88
+
<para>DESCRIPTION
89
+
</para>
90
+
<informaltable><tgroup cols="1"><tbody><row><entry
91
+
align="char">
92
+
<para>This ioctl call sets one or more frontend properties. This call only
93
+
requires read-only access to the device.</para>
94
+
</entry>
95
+
</row></tbody></tgroup></informaltable>
96
+
<para>SYNOPSIS
97
+
</para>
98
+
<informaltable><tgroup cols="1"><tbody><row><entry
99
+
align="char">
100
+
<para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
101
+
dtv_properties ⋆props);</para>
102
+
</entry>
103
+
</row></tbody></tgroup></informaltable>
104
+
<para>PARAMETERS
105
+
</para>
106
+
<informaltable><tgroup cols="2"><tbody><row><entry align="char">
107
+
<para>int fd</para>
108
+
</entry><entry
109
+
align="char">
110
+
<para>File descriptor returned by a previous call to open().</para>
111
+
</entry>
112
+
</row><row><entry
113
+
align="char">
114
+
<para>int num</para>
115
+
</entry><entry
116
+
align="char">
117
+
<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para>
118
+
</entry>
119
+
</row><row><entry
120
+
align="char">
121
+
<para>struct dtv_property *props</para>
122
+
</entry><entry
123
+
align="char">
124
+
<para>Points to the location where the front-end property commands are stored.</para>
125
+
</entry>
126
+
</row></tbody></tgroup></informaltable>
127
+
<para>ERRORS
128
+
</para>
129
+
<informaltable><tgroup cols="2"><tbody><row>
130
+
<entry align="char"><para>EINVAL</para></entry>
131
+
<entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
132
+
</row><row>
133
+
<entry align="char"><para>ENOMEM</para></entry>
134
+
<entry align="char"><para>Out of memory.</para></entry>
135
+
</row><row>
136
+
<entry align="char"><para>EFAULT</para></entry>
137
+
<entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
138
+
</row><row>
139
+
<entry align="char"><para>EOPNOTSUPP</para></entry>
140
+
<entry align="char"><para>Property type not supported.</para></entry>
141
+
</row></tbody></tgroup></informaltable>
142
+
</section>
143
+
144
+
<para>
145
+
On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
146
+
the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to
147
+
get/set up to 64 properties. The actual meaning of each property is described on the next sections.
148
+
</para>
149
+
150
+
<para>The Available frontend property types are:</para>
151
+
<programlisting>
152
+
#define DTV_UNDEFINED 0
153
+
#define DTV_TUNE 1
154
+
#define DTV_CLEAR 2
155
+
#define DTV_FREQUENCY 3
156
+
#define DTV_MODULATION 4
157
+
#define DTV_BANDWIDTH_HZ 5
158
+
#define DTV_INVERSION 6
159
+
#define DTV_DISEQC_MASTER 7
160
+
#define DTV_SYMBOL_RATE 8
161
+
#define DTV_INNER_FEC 9
162
+
#define DTV_VOLTAGE 10
163
+
#define DTV_TONE 11
164
+
#define DTV_PILOT 12
165
+
#define DTV_ROLLOFF 13
166
+
#define DTV_DISEQC_SLAVE_REPLY 14
167
+
#define DTV_FE_CAPABILITY_COUNT 15
168
+
#define DTV_FE_CAPABILITY 16
169
+
#define DTV_DELIVERY_SYSTEM 17
170
+
#define DTV_ISDBT_PARTIAL_RECEPTION 18
171
+
#define DTV_ISDBT_SOUND_BROADCASTING 19
172
+
#define DTV_ISDBT_SB_SUBCHANNEL_ID 20
173
+
#define DTV_ISDBT_SB_SEGMENT_IDX 21
174
+
#define DTV_ISDBT_SB_SEGMENT_COUNT 22
175
+
#define DTV_ISDBT_LAYERA_FEC 23
176
+
#define DTV_ISDBT_LAYERA_MODULATION 24
177
+
#define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25
178
+
#define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26
179
+
#define DTV_ISDBT_LAYERB_FEC 27
180
+
#define DTV_ISDBT_LAYERB_MODULATION 28
181
+
#define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29
182
+
#define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30
183
+
#define DTV_ISDBT_LAYERC_FEC 31
184
+
#define DTV_ISDBT_LAYERC_MODULATION 32
185
+
#define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33
186
+
#define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34
187
+
#define DTV_API_VERSION 35
188
+
#define DTV_CODE_RATE_HP 36
189
+
#define DTV_CODE_RATE_LP 37
190
+
#define DTV_GUARD_INTERVAL 38
191
+
#define DTV_TRANSMISSION_MODE 39
192
+
#define DTV_HIERARCHY 40
193
+
#define DTV_ISDBT_LAYER_ENABLED 41
194
+
#define DTV_ISDBS_TS_ID 42
195
+
</programlisting>
196
+
197
+
<section id="fe_property_common">
198
+
<title>Parameters that are common to all Digital TV standards</title>
199
+
<section id="DTV_FREQUENCY">
200
+
<title><constant>DTV_FREQUENCY</constant></title>
201
+
202
+
<para>Central frequency of the channel, in HZ.</para>
203
+
204
+
<para>Notes:</para>
205
+
<para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
206
+
E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
207
+
the channel which is 6MHz.</para>
208
+
209
+
<para>2)As in ISDB-Tsb the channel consists of only one or three segments the
210
+
frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
211
+
central frequency of the channel is expected.</para>
212
+
</section>
213
+
214
+
<section id="DTV_BANDWIDTH_HZ">
215
+
<title><constant>DTV_BANDWIDTH_HZ</constant></title>
216
+
217
+
<para>Bandwidth for the channel, in HZ.</para>
218
+
219
+
<para>Possible values:
220
+
<constant>6000000</constant>,
221
+
<constant>7000000</constant>,
222
+
<constant>8000000</constant>.
223
+
</para>
224
+
225
+
<para>Notes:</para>
226
+
227
+
<para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
228
+
<para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
229
+
<para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
230
+
for DVB-C depends on the symbol rate</para>
231
+
<para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
232
+
other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
233
+
DTV_ISDBT_SB_SEGMENT_COUNT).</para>
234
+
</section>
235
+
236
+
<section id="DTV_DELIVERY_SYSTEM">
237
+
<title><constant>DTV_DELIVERY_SYSTEM</constant></title>
238
+
239
+
<para>Specifies the type of Delivery system</para>
240
+
241
+
<para>Possible values: </para>
242
+
<programlisting>
243
+
typedef enum fe_delivery_system {
244
+
SYS_UNDEFINED,
245
+
SYS_DVBC_ANNEX_AC,
246
+
SYS_DVBC_ANNEX_B,
247
+
SYS_DVBT,
248
+
SYS_DSS,
249
+
SYS_DVBS,
250
+
SYS_DVBS2,
251
+
SYS_DVBH,
252
+
SYS_ISDBT,
253
+
SYS_ISDBS,
254
+
SYS_ISDBC,
255
+
SYS_ATSC,
256
+
SYS_ATSCMH,
257
+
SYS_DMBTH,
258
+
SYS_CMMB,
259
+
SYS_DAB,
260
+
} fe_delivery_system_t;
261
+
</programlisting>
262
+
263
+
</section>
264
+
265
+
<section id="DTV_TRANSMISSION_MODE">
266
+
<title><constant>DTV_TRANSMISSION_MODE</constant></title>
267
+
268
+
<para>Specifies the number of carriers used by the standard</para>
269
+
270
+
<para>Possible values are:</para>
271
+
<programlisting>
272
+
typedef enum fe_transmit_mode {
273
+
TRANSMISSION_MODE_2K,
274
+
TRANSMISSION_MODE_8K,
275
+
TRANSMISSION_MODE_AUTO,
276
+
TRANSMISSION_MODE_4K
277
+
} fe_transmit_mode_t;
278
+
</programlisting>
279
+
280
+
<para>Notes:</para>
281
+
<para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
282
+
'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
283
+
284
+
<para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
285
+
hardware will try to find the correct FFT-size (if capable) and will
286
+
use TMCC to fill in the missing parameters.</para>
287
+
</section>
288
+
289
+
<section id="DTV_GUARD_INTERVAL">
290
+
<title><constant>DTV_GUARD_INTERVAL</constant></title>
291
+
292
+
<para>Possible values are:</para>
293
+
<programlisting>
294
+
typedef enum fe_guard_interval {
295
+
GUARD_INTERVAL_1_32,
296
+
GUARD_INTERVAL_1_16,
297
+
GUARD_INTERVAL_1_8,
298
+
GUARD_INTERVAL_1_4,
299
+
GUARD_INTERVAL_AUTO
300
+
} fe_guard_interval_t;
301
+
</programlisting>
302
+
303
+
<para>Notes:</para>
304
+
<para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
305
+
try to find the correct guard interval (if capable) and will use TMCC to fill
306
+
in the missing parameters.</para>
307
+
</section>
308
+
</section>
3
309
4
310
<section id="isdbt">
5
311
<title>ISDB-T frontend</title>
···
338
32
339
33
<para>Parameters used by ISDB-T and ISDB-Tsb.</para>
340
34
341
-
<section id="isdbt-parms">
342
-
<title>Parameters that are common with DVB-T and ATSC</title>
343
-
344
-
<section id="isdbt-freq">
345
-
<title><constant>DTV_FREQUENCY</constant></title>
346
-
347
-
<para>Central frequency of the channel.</para>
348
-
349
-
<para>For ISDB-T the channels are usually transmitted with an offset of 143kHz. E.g. a
350
-
valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
351
-
the channel which is 6MHz.</para>
352
-
353
-
<para>As in ISDB-Tsb the channel consists of only one or three segments the
354
-
frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
355
-
central frequency of the channel is expected.</para>
356
-
</section>
357
-
358
-
<section id="isdbt-bw">
359
-
<title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title>
360
-
361
-
<para>Possible values:</para>
362
-
363
-
<para>For ISDB-T it should be always 6000000Hz (6MHz)</para>
364
-
<para>For ISDB-Tsb it can vary depending on the number of connected segments</para>
365
-
366
-
<para>Note: Hardware specific values might be given here, but standard
367
-
applications should not bother to set a value to this field as
368
-
standard demods are ignoring it anyway.</para>
369
-
370
-
<para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
371
-
other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
372
-
DTV_ISDBT_SB_SEGMENT_COUNT).</para>
373
-
</section>
374
-
375
-
<section id="isdbt-delivery-sys">
376
-
<title><constant>DTV_DELIVERY_SYSTEM</constant></title>
377
-
378
-
<para>Possible values: <constant>SYS_ISDBT</constant></para>
379
-
</section>
380
-
381
-
<section id="isdbt-tx-mode">
382
-
<title><constant>DTV_TRANSMISSION_MODE</constant></title>
383
-
384
-
<para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
385
-
'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
386
-
387
-
<para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>,
388
-
<constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para>
389
-
390
-
<para>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
391
-
hardware will try to find the correct FFT-size (if capable) and will
392
-
use TMCC to fill in the missing parameters.</para>
393
-
394
-
<para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para>
395
-
</section>
396
-
397
-
<section id="isdbt-guard-interval">
398
-
<title><constant>DTV_GUARD_INTERVAL</constant></title>
399
-
400
-
<para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>,
401
-
<constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para>
402
-
403
-
<para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
404
-
try to find the correct guard interval (if capable) and will use TMCC to fill
405
-
in the missing parameters.</para>
406
-
</section>
407
-
</section>
408
35
<section id="isdbt-new-parms">
409
36
<title>ISDB-T only parameters</title>
410
37