aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/dvb
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/dvb')
-rw-r--r--Documentation/DocBook/media/dvb/.gitignore1
-rw-r--r--Documentation/DocBook/media/dvb/audio.xml1314
-rw-r--r--Documentation/DocBook/media/dvb/ca.xml582
-rw-r--r--Documentation/DocBook/media/dvb/demux.xml1130
-rw-r--r--Documentation/DocBook/media/dvb/dvbapi.xml141
-rw-r--r--Documentation/DocBook/media/dvb/dvbproperty.xml1105
-rw-r--r--Documentation/DocBook/media/dvb/dvbstb.pdfbin0 -> 1881 bytes
-rw-r--r--Documentation/DocBook/media/dvb/examples.xml365
-rw-r--r--Documentation/DocBook/media/dvb/frontend.xml1548
-rw-r--r--Documentation/DocBook/media/dvb/intro.xml212
-rw-r--r--Documentation/DocBook/media/dvb/kdapi.xml2309
-rw-r--r--Documentation/DocBook/media/dvb/net.xml156
-rw-r--r--Documentation/DocBook/media/dvb/video.xml1968
13 files changed, 10831 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/dvb/.gitignore b/Documentation/DocBook/media/dvb/.gitignore
new file mode 100644
index 00000000000..d7ec32eafac
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/.gitignore
@@ -0,0 +1 @@
!*.xml
diff --git a/Documentation/DocBook/media/dvb/audio.xml b/Documentation/DocBook/media/dvb/audio.xml
new file mode 100644
index 00000000000..a7ea56c71a2
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/audio.xml
@@ -0,0 +1,1314 @@
1<title>DVB Audio Device</title>
2<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/audio.h</emphasis> in your
5application.
6</para>
7<para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
8the omission of the audio and video device.
9</para>
10<para>
11These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use
12of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls
13have been created to replace that functionality.</para>
14
15<section id="audio_data_types">
16<title>Audio Data Types</title>
17<para>This section describes the structures, data types and defines used when talking to the
18audio device.
19</para>
20
21<section id="audio-stream-source-t">
22<title>audio_stream_source_t</title>
23<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
24the following values, depending on whether we are replaying from an internal (demux) or
25external (user write) source.
26</para>
27<programlisting>
28typedef enum {
29 AUDIO_SOURCE_DEMUX,
30 AUDIO_SOURCE_MEMORY
31} audio_stream_source_t;
32</programlisting>
33<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
34DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
35is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
36call.
37</para>
38
39</section>
40<section id="audio-play-state-t">
41<title>audio_play_state_t</title>
42<para>The following values can be returned by the AUDIO_GET_STATUS call representing the
43state of audio playback.
44</para>
45<programlisting>
46typedef enum {
47 AUDIO_STOPPED,
48 AUDIO_PLAYING,
49 AUDIO_PAUSED
50} audio_play_state_t;
51</programlisting>
52
53</section>
54<section id="audio-channel-select-t">
55<title>audio_channel_select_t</title>
56<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
57following values.
58</para>
59<programlisting>
60typedef enum {
61 AUDIO_STEREO,
62 AUDIO_MONO_LEFT,
63 AUDIO_MONO_RIGHT,
64 AUDIO_MONO,
65 AUDIO_STEREO_SWAPPED
66} audio_channel_select_t;
67</programlisting>
68
69</section>
70<section id="audio-status">
71<title>struct audio_status</title>
72<para>The AUDIO_GET_STATUS call returns the following structure informing about various
73states of the playback operation.
74</para>
75<programlisting>
76typedef struct audio_status {
77 boolean AV_sync_state;
78 boolean mute_state;
79 audio_play_state_t play_state;
80 audio_stream_source_t stream_source;
81 audio_channel_select_t channel_select;
82 boolean bypass_mode;
83 audio_mixer_t mixer_state;
84} audio_status_t;
85</programlisting>
86
87</section>
88<section id="audio-mixer">
89<title>struct audio_mixer</title>
90<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
91volume.
92</para>
93<programlisting>
94typedef struct audio_mixer {
95 unsigned int volume_left;
96 unsigned int volume_right;
97} audio_mixer_t;
98</programlisting>
99
100</section>
101<section id="audio_encodings">
102<title>audio encodings</title>
103<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
104bits set according to the hardwares capabilities.
105</para>
106<programlisting>
107 #define AUDIO_CAP_DTS 1
108 #define AUDIO_CAP_LPCM 2
109 #define AUDIO_CAP_MP1 4
110 #define AUDIO_CAP_MP2 8
111 #define AUDIO_CAP_MP3 16
112 #define AUDIO_CAP_AAC 32
113 #define AUDIO_CAP_OGG 64
114 #define AUDIO_CAP_SDDS 128
115 #define AUDIO_CAP_AC3 256
116</programlisting>
117
118</section>
119<section id="audio-karaoke">
120<title>struct audio_karaoke</title>
121<para>The ioctl AUDIO_SET_KARAOKE uses the following format:
122</para>
123<programlisting>
124typedef
125struct audio_karaoke {
126 int vocal1;
127 int vocal2;
128 int melody;
129} audio_karaoke_t;
130</programlisting>
131<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both,
132Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
133right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
134and right.
135</para>
136
137</section>
138<section id="audio-attributes-t">
139<title>audio attributes</title>
140<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
141</para>
142<programlisting>
143 typedef uint16_t audio_attributes_t;
144 /&#x22C6; bits: descr. &#x22C6;/
145 /&#x22C6; 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
146 /&#x22C6; 12 multichannel extension &#x22C6;/
147 /&#x22C6; 11-10 audio type (0=not spec, 1=language included) &#x22C6;/
148 /&#x22C6; 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
149 /&#x22C6; 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, &#x22C6;/
150 /&#x22C6; 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
151 /&#x22C6; 2- 0 number of audio channels (n+1 channels) &#x22C6;/
152</programlisting>
153 </section></section>
154<section id="audio_function_calls">
155<title>Audio Function Calls</title>
156
157
158<section id="audio_fopen">
159<title>open()</title>
160<para>DESCRIPTION
161</para>
162<informaltable><tgroup cols="1"><tbody><row><entry
163 align="char">
164<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0)
165 for subsequent use. When an open() call has succeeded, the device will be ready
166 for use. The significance of blocking or non-blocking mode is described in the
167 documentation for functions where there is a difference. It does not affect the
168 semantics of the open() call itself. A device opened in blocking mode can later
169 be put into non-blocking mode (and vice versa) using the F_SETFL command
170 of the fcntl system call. This is a standard system call, documented in the Linux
171 manual page for fcntl. Only one user can open the Audio Device in O_RDWR
172 mode. All other attempts to open the device in this mode will fail, and an error
173 code will be returned. If the Audio Device is opened in O_RDONLY mode, the
174 only ioctl call that can be used is AUDIO_GET_STATUS. All other call will
175 return with an error code.</para>
176</entry>
177 </row></tbody></tgroup></informaltable>
178<para>SYNOPSIS
179</para>
180<informaltable><tgroup cols="1"><tbody><row><entry
181 align="char">
182<para>int open(const char &#x22C6;deviceName, int flags);</para>
183</entry>
184 </row></tbody></tgroup></informaltable>
185<para>PARAMETERS
186</para>
187<informaltable><tgroup cols="2"><tbody><row><entry
188 align="char">
189<para>const char
190 *deviceName</para>
191</entry><entry
192 align="char">
193<para>Name of specific audio device.</para>
194</entry>
195 </row><row><entry
196 align="char">
197<para>int flags</para>
198</entry><entry
199 align="char">
200<para>A bit-wise OR of the following flags:</para>
201</entry>
202 </row><row><entry
203 align="char">
204</entry><entry
205 align="char">
206<para>O_RDONLY read-only access</para>
207</entry>
208 </row><row><entry
209 align="char">
210</entry><entry
211 align="char">
212<para>O_RDWR read/write access</para>
213</entry>
214 </row><row><entry
215 align="char">
216</entry><entry
217 align="char">
218<para>O_NONBLOCK open in non-blocking mode</para>
219</entry>
220 </row><row><entry
221 align="char">
222</entry><entry
223 align="char">
224<para>(blocking mode is the default)</para>
225</entry>
226 </row></tbody></tgroup></informaltable>
227<para>RETURN VALUE</para>
228<informaltable><tgroup cols="2"><tbody><row><entry
229 align="char">
230<para>ENODEV</para>
231</entry><entry
232 align="char">
233<para>Device driver not loaded/available.</para>
234</entry>
235 </row><row><entry
236 align="char">
237<para>EBUSY</para>
238</entry><entry
239 align="char">
240<para>Device or resource busy.</para>
241</entry>
242 </row><row><entry
243 align="char">
244<para>EINVAL</para>
245</entry><entry
246 align="char">
247<para>Invalid argument.</para>
248</entry>
249 </row></tbody></tgroup></informaltable>
250
251</section>
252<section id="audio_fclose">
253<title>close()</title>
254<para>DESCRIPTION
255</para>
256<informaltable><tgroup cols="1"><tbody><row><entry
257 align="char">
258<para>This system call closes a previously opened audio device.</para>
259</entry>
260 </row></tbody></tgroup></informaltable>
261<para>SYNOPSIS
262</para>
263<informaltable><tgroup cols="1"><tbody><row><entry
264 align="char">
265<para>int close(int fd);</para>
266</entry>
267 </row></tbody></tgroup></informaltable>
268<para>PARAMETERS
269</para>
270<informaltable><tgroup cols="2"><tbody><row><entry
271 align="char">
272<para>int fd</para>
273</entry><entry
274 align="char">
275<para>File descriptor returned by a previous call to open().</para>
276</entry>
277 </row></tbody></tgroup></informaltable>
278<para>RETURN VALUE</para>
279<informaltable><tgroup cols="2"><tbody><row><entry
280 align="char">
281<para>EBADF</para>
282</entry><entry
283 align="char">
284<para>fd is not a valid open file descriptor.</para>
285</entry>
286 </row></tbody></tgroup></informaltable>
287
288</section>
289<section id="audio_fwrite">
290<title>write()</title>
291<para>DESCRIPTION
292</para>
293<informaltable><tgroup cols="1"><tbody><row><entry
294 align="char">
295<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected
296 in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
297 PES format. If O_NONBLOCK is not specified the function will block until
298 buffer space is available. The amount of data to be transferred is implied by
299 count.</para>
300</entry>
301 </row></tbody></tgroup></informaltable>
302<para>SYNOPSIS
303</para>
304<informaltable><tgroup cols="1"><tbody><row><entry
305 align="char">
306<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
307</entry>
308 </row></tbody></tgroup></informaltable>
309<para>PARAMETERS
310</para>
311<informaltable><tgroup cols="2"><tbody><row><entry
312 align="char">
313<para>int fd</para>
314</entry><entry
315 align="char">
316<para>File descriptor returned by a previous call to open().</para>
317</entry>
318 </row><row><entry
319 align="char">
320<para>void *buf</para>
321</entry><entry
322 align="char">
323<para>Pointer to the buffer containing the PES data.</para>
324</entry>
325 </row><row><entry
326 align="char">
327<para>size_t count</para>
328</entry><entry
329 align="char">
330<para>Size of buf.</para>
331</entry>
332 </row></tbody></tgroup></informaltable>
333<para>RETURN VALUE</para>
334<informaltable><tgroup cols="2"><tbody><row><entry
335 align="char">
336<para>EPERM</para>
337</entry><entry
338 align="char">
339<para>Mode AUDIO_SOURCE_MEMORY not selected.</para>
340</entry>
341 </row><row><entry
342 align="char">
343<para>ENOMEM</para>
344</entry><entry
345 align="char">
346<para>Attempted to write more data than the internal buffer can
347 hold.</para>
348</entry>
349 </row><row><entry
350 align="char">
351<para>EBADF</para>
352</entry><entry
353 align="char">
354<para>fd is not a valid open file descriptor.</para>
355</entry>
356 </row></tbody></tgroup></informaltable>
357
358</section><section id="AUDIO_STOP"
359role="subsection"><title>AUDIO_STOP</title>
360<para>DESCRIPTION
361</para>
362<informaltable><tgroup cols="1"><tbody><row><entry
363 align="char">
364<para>This ioctl call asks the Audio Device to stop playing the current stream.</para>
365</entry>
366 </row></tbody></tgroup></informaltable>
367<para>SYNOPSIS
368</para>
369<informaltable><tgroup cols="1"><tbody><row><entry
370 align="char">
371<para>int ioctl(int fd, int request = AUDIO_STOP);</para>
372</entry>
373 </row></tbody></tgroup></informaltable>
374<para>PARAMETERS
375</para>
376<informaltable><tgroup cols="2"><tbody><row><entry
377 align="char">
378<para>int fd</para>
379</entry><entry
380 align="char">
381<para>File descriptor returned by a previous call to open().</para>
382</entry>
383 </row><row><entry
384 align="char">
385<para>int request</para>
386</entry><entry
387 align="char">
388<para>Equals AUDIO_STOP for this command.</para>
389</entry>
390 </row></tbody></tgroup></informaltable>
391&return-value-dvb;
392
393</section><section id="AUDIO_PLAY"
394role="subsection"><title>AUDIO_PLAY</title>
395<para>DESCRIPTION
396</para>
397<informaltable><tgroup cols="1"><tbody><row><entry
398 align="char">
399<para>This ioctl call asks the Audio Device to start playing an audio stream from the
400 selected source.</para>
401</entry>
402 </row></tbody></tgroup></informaltable>
403<para>SYNOPSIS
404</para>
405<informaltable><tgroup cols="1"><tbody><row><entry
406 align="char">
407<para>int ioctl(int fd, int request = AUDIO_PLAY);</para>
408</entry>
409 </row></tbody></tgroup></informaltable>
410<para>PARAMETERS
411</para>
412<informaltable><tgroup cols="2"><tbody><row><entry
413 align="char">
414<para>int fd</para>
415</entry><entry
416 align="char">
417<para>File descriptor returned by a previous call to open().</para>
418</entry>
419 </row><row><entry
420 align="char">
421<para>int request</para>
422</entry><entry
423 align="char">
424<para>Equals AUDIO_PLAY for this command.</para>
425</entry>
426 </row></tbody></tgroup></informaltable>
427&return-value-dvb;
428
429</section><section id="AUDIO_PAUSE"
430role="subsection"><title>AUDIO_PAUSE</title>
431<para>DESCRIPTION
432</para>
433<informaltable><tgroup cols="1"><tbody><row><entry
434 align="char">
435<para>This ioctl call suspends the audio stream being played. Decoding and playing
436 are paused. It is then possible to restart again decoding and playing process of
437 the audio stream using AUDIO_CONTINUE command.</para>
438</entry>
439 </row><row><entry
440 align="char">
441<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call
442 AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume)
443 any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is
444 performed.</para>
445</entry>
446 </row></tbody></tgroup></informaltable>
447<para>SYNOPSIS
448</para>
449<informaltable><tgroup cols="1"><tbody><row><entry
450 align="char">
451<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para>
452</entry>
453 </row></tbody></tgroup></informaltable>
454<para>PARAMETERS
455</para>
456<informaltable><tgroup cols="2"><tbody><row><entry
457 align="char">
458<para>int fd</para>
459</entry><entry
460 align="char">
461<para>File descriptor returned by a previous call to open().</para>
462</entry>
463 </row><row><entry
464 align="char">
465<para>int request</para>
466</entry><entry
467 align="char">
468<para>Equals AUDIO_PAUSE for this command.</para>
469</entry>
470 </row></tbody></tgroup></informaltable>
471&return-value-dvb;
472
473</section><section id="AUDIO_CONTINUE"
474role="subsection"><title>AUDIO_CONTINUE</title>
475<para>DESCRIPTION
476</para>
477<informaltable><tgroup cols="1"><tbody><row><entry
478 align="char">
479<para>This ioctl restarts the decoding and playing process previously paused
480with AUDIO_PAUSE command.</para>
481</entry>
482 </row><row><entry
483 align="char">
484<para>It only works if the stream were previously stopped with AUDIO_PAUSE</para>
485</entry>
486 </row></tbody></tgroup></informaltable>
487<para>SYNOPSIS
488</para>
489<informaltable><tgroup cols="1"><tbody><row><entry
490 align="char">
491<para>int ioctl(int fd, int request = AUDIO_CONTINUE);</para>
492</entry>
493 </row></tbody></tgroup></informaltable>
494<para>PARAMETERS
495</para>
496<informaltable><tgroup cols="2"><tbody><row><entry
497 align="char">
498<para>int fd</para>
499</entry><entry
500 align="char">
501<para>File descriptor returned by a previous call to open().</para>
502</entry>
503 </row><row><entry
504 align="char">
505<para>int request</para>
506</entry><entry
507 align="char">
508<para>Equals AUDIO_CONTINUE for this command.</para>
509</entry>
510 </row></tbody></tgroup></informaltable>
511&return-value-dvb;
512
513</section><section id="AUDIO_SELECT_SOURCE"
514role="subsection"><title>AUDIO_SELECT_SOURCE</title>
515<para>DESCRIPTION
516</para>
517<informaltable><tgroup cols="1"><tbody><row><entry
518 align="char">
519<para>This ioctl call informs the audio device which source shall be used
520 for the input data. The possible sources are demux or memory. If
521 AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
522 through the write command.</para>
523</entry>
524 </row></tbody></tgroup></informaltable>
525<para>SYNOPSIS
526</para>
527<informaltable><tgroup cols="1"><tbody><row><entry
528 align="char">
529<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
530 audio_stream_source_t source);</para>
531</entry>
532 </row></tbody></tgroup></informaltable>
533<para>PARAMETERS
534</para>
535<informaltable><tgroup cols="2"><tbody><row><entry
536 align="char">
537<para>int fd</para>
538</entry><entry
539 align="char">
540<para>File descriptor returned by a previous call to open().</para>
541</entry>
542 </row><row><entry
543 align="char">
544<para>int request</para>
545</entry><entry
546 align="char">
547<para>Equals AUDIO_SELECT_SOURCE for this command.</para>
548</entry>
549 </row><row><entry
550 align="char">
551<para>audio_stream_source_t
552 source</para>
553</entry><entry
554 align="char">
555<para>Indicates the source that shall be used for the Audio
556 stream.</para>
557</entry>
558 </row></tbody></tgroup></informaltable>
559&return-value-dvb;
560
561</section><section id="AUDIO_SET_MUTE"
562role="subsection"><title>AUDIO_SET_MUTE</title>
563<para>DESCRIPTION
564</para>
565<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
566&VIDIOC-DECODER-CMD; with the <constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant> flag instead.</para>
567<informaltable><tgroup cols="1"><tbody><row><entry
568 align="char">
569<para>This ioctl call asks the audio device to mute the stream that is currently being
570 played.</para>
571</entry>
572 </row></tbody></tgroup></informaltable>
573<para>SYNOPSIS
574</para>
575<informaltable><tgroup cols="1"><tbody><row><entry
576 align="char">
577<para>int ioctl(int fd, int request = AUDIO_SET_MUTE,
578 boolean state);</para>
579</entry>
580 </row></tbody></tgroup></informaltable>
581<para>PARAMETERS
582</para>
583<informaltable><tgroup cols="2"><tbody><row><entry
584 align="char">
585<para>int fd</para>
586</entry><entry
587 align="char">
588<para>File descriptor returned by a previous call to open().</para>
589</entry>
590 </row><row><entry
591 align="char">
592<para>int request</para>
593</entry><entry
594 align="char">
595<para>Equals AUDIO_SET_MUTE for this command.</para>
596</entry>
597 </row><row><entry
598 align="char">
599<para>boolean state</para>
600</entry><entry
601 align="char">
602<para>Indicates if audio device shall mute or not.</para>
603</entry>
604 </row><row><entry
605 align="char">
606</entry><entry
607 align="char">
608<para>TRUE Audio Mute</para>
609</entry>
610 </row><row><entry
611 align="char">
612</entry><entry
613 align="char">
614<para>FALSE Audio Un-mute</para>
615</entry>
616 </row></tbody></tgroup></informaltable>
617&return-value-dvb;
618
619</section><section id="AUDIO_SET_AV_SYNC"
620role="subsection"><title>AUDIO_SET_AV_SYNC</title>
621<para>DESCRIPTION
622</para>
623<informaltable><tgroup cols="1"><tbody><row><entry
624 align="char">
625<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para>
626</entry>
627 </row></tbody></tgroup></informaltable>
628<para>SYNOPSIS
629</para>
630<informaltable><tgroup cols="1"><tbody><row><entry
631 align="char">
632<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC,
633 boolean state);</para>
634</entry>
635 </row></tbody></tgroup></informaltable>
636<para>PARAMETERS
637</para>
638<informaltable><tgroup cols="2"><tbody><row><entry
639 align="char">
640<para>int fd</para>
641</entry><entry
642 align="char">
643<para>File descriptor returned by a previous call to open().</para>
644</entry>
645 </row><row><entry
646 align="char">
647<para>int request</para>
648</entry><entry
649 align="char">
650<para>Equals AUDIO_AV_SYNC for this command.</para>
651</entry>
652 </row><row><entry
653 align="char">
654<para>boolean state</para>
655</entry><entry
656 align="char">
657<para>Tells the DVB subsystem if A/V synchronization shall be
658 ON or OFF.</para>
659</entry>
660 </row><row><entry
661 align="char">
662</entry><entry
663 align="char">
664<para>TRUE AV-sync ON</para>
665</entry>
666 </row><row><entry
667 align="char">
668</entry><entry
669 align="char">
670<para>FALSE AV-sync OFF</para>
671</entry>
672 </row></tbody></tgroup></informaltable>
673&return-value-dvb;
674
675</section><section id="AUDIO_SET_BYPASS_MODE"
676role="subsection"><title>AUDIO_SET_BYPASS_MODE</title>
677<para>DESCRIPTION
678</para>
679<informaltable><tgroup cols="1"><tbody><row><entry
680 align="char">
681<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward
682 the stream without decoding. This mode shall be used if streams that can&#8217;t be
683 handled by the DVB system shall be decoded. Dolby DigitalTM streams are
684 automatically forwarded by the DVB subsystem if the hardware can handle it.</para>
685</entry>
686 </row></tbody></tgroup></informaltable>
687<para>SYNOPSIS
688</para>
689<informaltable><tgroup cols="1"><tbody><row><entry
690 align="char">
691<para>int ioctl(int fd, int request =
692 AUDIO_SET_BYPASS_MODE, boolean mode);</para>
693</entry>
694 </row></tbody></tgroup></informaltable>
695<para>PARAMETERS
696</para>
697<informaltable><tgroup cols="2"><tbody><row><entry
698 align="char">
699<para>int fd</para>
700</entry><entry
701 align="char">
702<para>File descriptor returned by a previous call to open().</para>
703</entry>
704 </row><row><entry
705 align="char">
706<para>int request</para>
707</entry><entry
708 align="char">
709<para>Equals AUDIO_SET_BYPASS_MODE for this
710 command.</para>
711</entry>
712 </row><row><entry
713 align="char">
714<para>boolean mode</para>
715</entry><entry
716 align="char">
717<para>Enables or disables the decoding of the current Audio
718 stream in the DVB subsystem.</para>
719</entry>
720 </row><row><entry
721 align="char">
722</entry><entry
723 align="char">
724<para>TRUE Bypass is disabled</para>
725</entry>
726 </row><row><entry
727 align="char">
728</entry><entry
729 align="char">
730<para>FALSE Bypass is enabled</para>
731</entry>
732 </row></tbody></tgroup></informaltable>
733&return-value-dvb;
734
735</section><section id="AUDIO_CHANNEL_SELECT"
736role="subsection"><title>AUDIO_CHANNEL_SELECT</title>
737<para>DESCRIPTION
738</para>
739<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
740<constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> control instead.</para>
741<informaltable><tgroup cols="1"><tbody><row><entry
742 align="char">
743<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para>
744</entry>
745 </row></tbody></tgroup></informaltable>
746<para>SYNOPSIS
747</para>
748<informaltable><tgroup cols="1"><tbody><row><entry
749 align="char">
750<para>int ioctl(int fd, int request =
751 AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para>
752</entry>
753 </row></tbody></tgroup></informaltable>
754<para>PARAMETERS
755</para>
756<informaltable><tgroup cols="2"><tbody><row><entry
757 align="char">
758<para>int fd</para>
759</entry><entry
760 align="char">
761<para>File descriptor returned by a previous call to open().</para>
762</entry>
763 </row><row><entry
764 align="char">
765<para>int request</para>
766</entry><entry
767 align="char">
768<para>Equals AUDIO_CHANNEL_SELECT for this
769 command.</para>
770</entry>
771 </row><row><entry
772 align="char">
773<para>audio_channel_select_t
774 ch</para>
775</entry><entry
776 align="char">
777<para>Select the output format of the audio (mono left/right,
778 stereo).</para>
779</entry>
780 </row></tbody></tgroup></informaltable>
781&return-value-dvb;
782
783</section><section id="AUDIO_BILINGUAL_CHANNEL_SELECT"
784role="subsection"><title>AUDIO_BILINGUAL_CHANNEL_SELECT</title>
785<para>DESCRIPTION
786</para>
787<para>This ioctl is obsolete. Do not use in new drivers. It has been replaced by
788the V4L2 <constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> control
789for MPEG decoders controlled through V4L2.</para>
790<informaltable><tgroup cols="1"><tbody><row><entry
791 align="char">
792<para>This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible.</para>
793</entry>
794 </row></tbody></tgroup></informaltable>
795<para>SYNOPSIS
796</para>
797<informaltable><tgroup cols="1"><tbody><row><entry
798 align="char">
799<para>int ioctl(int fd, int request =
800 AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t);</para>
801</entry>
802 </row></tbody></tgroup></informaltable>
803<para>PARAMETERS
804</para>
805<informaltable><tgroup cols="2"><tbody><row><entry
806 align="char">
807<para>int fd</para>
808</entry><entry
809 align="char">
810<para>File descriptor returned by a previous call to open().</para>
811</entry>
812 </row><row><entry
813 align="char">
814<para>int request</para>
815</entry><entry
816 align="char">
817<para>Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this
818 command.</para>
819</entry>
820 </row><row><entry
821 align="char">
822<para>audio_channel_select_t
823ch</para>
824</entry><entry
825 align="char">
826<para>Select the output format of the audio (mono left/right,
827 stereo).</para>
828</entry>
829 </row>
830</tbody></tgroup></informaltable>
831&return-value-dvb;
832
833</section><section id="AUDIO_GET_PTS"
834role="subsection"><title>AUDIO_GET_PTS</title>
835<para>DESCRIPTION
836</para>
837<para>This ioctl is obsolete. Do not use in new drivers. If you need this functionality,
838then please contact the linux-media mailing list (&v4l-ml;).</para>
839<informaltable><tgroup cols="1"><tbody><row><entry
840 align="char">
841<para>This ioctl call asks the Audio Device to return the current PTS timestamp.</para>
842</entry>
843 </row></tbody></tgroup></informaltable>
844<para>SYNOPSIS
845</para>
846<informaltable><tgroup cols="1"><tbody><row><entry
847 align="char">
848<para>int ioctl(int fd, int request =
849 AUDIO_GET_PTS, __u64 *pts);</para>
850</entry>
851 </row></tbody></tgroup></informaltable>
852<para>PARAMETERS
853</para>
854<informaltable><tgroup cols="2"><tbody><row><entry
855 align="char">
856<para>int fd</para>
857</entry><entry
858 align="char">
859<para>File descriptor returned by a previous call to open().</para>
860</entry>
861 </row><row><entry
862 align="char">
863<para>int request</para>
864</entry><entry
865 align="char">
866<para>Equals AUDIO_GET_PTS for this
867 command.</para>
868</entry>
869 </row><row><entry
870 align="char">
871<para>__u64 *pts
872</para>
873</entry><entry
874 align="char">
875<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
876</para>
877<para>
878The PTS should belong to the currently played
879frame if possible, but may also be a value close to it
880like the PTS of the last decoded frame or the last PTS
881extracted by the PES parser.</para>
882</entry>
883 </row></tbody></tgroup></informaltable>
884&return-value-dvb;
885
886</section><section id="AUDIO_GET_STATUS"
887role="subsection"><title>AUDIO_GET_STATUS</title>
888<para>DESCRIPTION
889</para>
890<informaltable><tgroup cols="1"><tbody><row><entry
891 align="char">
892<para>This ioctl call asks the Audio Device to return the current state of the Audio
893 Device.</para>
894</entry>
895 </row></tbody></tgroup></informaltable>
896<para>SYNOPSIS
897</para>
898<informaltable><tgroup cols="1"><tbody><row><entry
899 align="char">
900<para>int ioctl(int fd, int request = AUDIO_GET_STATUS,
901 struct audio_status &#x22C6;status);</para>
902</entry>
903 </row></tbody></tgroup></informaltable>
904<para>PARAMETERS
905</para>
906<informaltable><tgroup cols="2"><tbody><row><entry
907 align="char">
908<para>int fd</para>
909</entry><entry
910 align="char">
911<para>File descriptor returned by a previous call to open().</para>
912</entry>
913 </row><row><entry
914 align="char">
915<para>int request</para>
916</entry><entry
917 align="char">
918<para>Equals AUDIO_GET_STATUS for this command.</para>
919</entry>
920 </row><row><entry
921 align="char">
922<para>struct audio_status
923 *status</para>
924</entry><entry
925 align="char">
926<para>Returns the current state of Audio Device.</para>
927</entry>
928 </row></tbody></tgroup></informaltable>
929&return-value-dvb;
930
931</section><section id="AUDIO_GET_CAPABILITIES"
932role="subsection"><title>AUDIO_GET_CAPABILITIES</title>
933<para>DESCRIPTION
934</para>
935<informaltable><tgroup cols="1"><tbody><row><entry
936 align="char">
937<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities
938 of the audio hardware.</para>
939</entry>
940 </row></tbody></tgroup></informaltable>
941<para>SYNOPSIS
942</para>
943<informaltable><tgroup cols="1"><tbody><row><entry
944 align="char">
945<para>int ioctl(int fd, int request =
946 AUDIO_GET_CAPABILITIES, unsigned int &#x22C6;cap);</para>
947</entry>
948 </row></tbody></tgroup></informaltable>
949<para>PARAMETERS
950</para>
951<informaltable><tgroup cols="2"><tbody><row><entry
952 align="char">
953<para>int fd</para>
954</entry><entry
955 align="char">
956<para>File descriptor returned by a previous call to open().</para>
957</entry>
958 </row><row><entry
959 align="char">
960<para>int request</para>
961</entry><entry
962 align="char">
963<para>Equals AUDIO_GET_CAPABILITIES for this
964 command.</para>
965</entry>
966 </row><row><entry
967 align="char">
968<para>unsigned int *cap</para>
969</entry><entry
970 align="char">
971<para>Returns a bit array of supported sound formats.</para>
972</entry>
973 </row></tbody></tgroup></informaltable>
974&return-value-dvb;
975
976</section><section id="AUDIO_CLEAR_BUFFER"
977role="subsection"><title>AUDIO_CLEAR_BUFFER</title>
978<para>DESCRIPTION
979</para>
980<informaltable><tgroup cols="1"><tbody><row><entry
981 align="char">
982<para>This ioctl call asks the Audio Device to clear all software and hardware buffers
983 of the audio decoder device.</para>
984</entry>
985 </row></tbody></tgroup></informaltable>
986<para>SYNOPSIS
987</para>
988<informaltable><tgroup cols="1"><tbody><row><entry
989 align="char">
990<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para>
991</entry>
992 </row></tbody></tgroup></informaltable>
993<para>PARAMETERS
994</para>
995<informaltable><tgroup cols="2"><tbody><row><entry
996 align="char">
997<para>int fd</para>
998</entry><entry
999 align="char">
1000<para>File descriptor returned by a previous call to open().</para>
1001</entry>
1002 </row><row><entry
1003 align="char">
1004<para>int request</para>
1005</entry><entry
1006 align="char">
1007<para>Equals AUDIO_CLEAR_BUFFER for this command.</para>
1008</entry>
1009 </row></tbody></tgroup></informaltable>
1010&return-value-dvb;
1011
1012</section><section id="AUDIO_SET_ID"
1013role="subsection"><title>AUDIO_SET_ID</title>
1014<para>DESCRIPTION
1015</para>
1016<informaltable><tgroup cols="1"><tbody><row><entry
1017 align="char">
1018<para>This ioctl selects which sub-stream is to be decoded if a program or system
1019 stream is sent to the video device. If no audio stream type is set the id has to be
1020 in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7]
1021 for LPCM. More specifications may follow for other stream types. If the stream
1022 type is set the id just specifies the substream id of the audio stream and only
1023 the first 5 bits are recognized.</para>
1024</entry>
1025 </row></tbody></tgroup></informaltable>
1026<para>SYNOPSIS
1027</para>
1028<informaltable><tgroup cols="1"><tbody><row><entry
1029 align="char">
1030<para>int ioctl(int fd, int request = AUDIO_SET_ID, int
1031 id);</para>
1032</entry>
1033 </row></tbody></tgroup></informaltable>
1034<para>PARAMETERS
1035</para>
1036<informaltable><tgroup cols="2"><tbody><row><entry
1037 align="char">
1038<para>int fd</para>
1039</entry><entry
1040 align="char">
1041<para>File descriptor returned by a previous call to open().</para>
1042</entry>
1043 </row><row><entry
1044 align="char">
1045<para>int request</para>
1046</entry><entry
1047 align="char">
1048<para>Equals AUDIO_SET_ID for this command.</para>
1049</entry>
1050 </row><row><entry
1051 align="char">
1052<para>int id</para>
1053</entry><entry
1054 align="char">
1055<para>audio sub-stream id</para>
1056</entry>
1057 </row></tbody></tgroup></informaltable>
1058&return-value-dvb;
1059
1060</section><section id="AUDIO_SET_MIXER"
1061role="subsection"><title>AUDIO_SET_MIXER</title>
1062<para>DESCRIPTION
1063</para>
1064<informaltable><tgroup cols="1"><tbody><row><entry
1065 align="char">
1066<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para>
1067</entry>
1068 </row></tbody></tgroup></informaltable>
1069<para>SYNOPSIS
1070</para>
1071<informaltable><tgroup cols="1"><tbody><row><entry
1072 align="char">
1073<para>int ioctl(int fd, int request = AUDIO_SET_MIXER,
1074 audio_mixer_t &#x22C6;mix);</para>
1075</entry>
1076 </row></tbody></tgroup></informaltable>
1077<para>PARAMETERS
1078</para>
1079<informaltable><tgroup cols="2"><tbody><row><entry
1080 align="char">
1081<para>int fd</para>
1082</entry><entry
1083 align="char">
1084<para>File descriptor returned by a previous call to open().</para>
1085</entry>
1086 </row><row><entry
1087 align="char">
1088<para>int request</para>
1089</entry><entry
1090 align="char">
1091<para>Equals AUDIO_SET_ID for this command.</para>
1092</entry>
1093 </row><row><entry
1094 align="char">
1095<para>audio_mixer_t *mix</para>
1096</entry><entry
1097 align="char">
1098<para>mixer settings.</para>
1099</entry>
1100 </row></tbody></tgroup></informaltable>
1101&return-value-dvb;
1102
1103</section><section id="AUDIO_SET_STREAMTYPE"
1104role="subsection"><title>AUDIO_SET_STREAMTYPE</title>
1105<para>DESCRIPTION
1106</para>
1107<informaltable><tgroup cols="1"><tbody><row><entry
1108 align="char">
1109<para>This ioctl tells the driver which kind of audio stream to expect. This is useful
1110 if the stream offers several audio sub-streams like LPCM and AC3.</para>
1111</entry>
1112 </row></tbody></tgroup></informaltable>
1113<para>SYNOPSIS
1114</para>
1115<informaltable><tgroup cols="1"><tbody><row><entry
1116 align="char">
1117<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
1118 int type);</para>
1119</entry>
1120 </row></tbody></tgroup></informaltable>
1121<para>PARAMETERS
1122</para>
1123<informaltable><tgroup cols="2"><tbody><row><entry
1124 align="char">
1125<para>int fd</para>
1126</entry><entry
1127 align="char">
1128<para>File descriptor returned by a previous call to open().</para>
1129</entry>
1130 </row><row><entry
1131 align="char">
1132<para>int request</para>
1133</entry><entry
1134 align="char">
1135<para>Equals AUDIO_SET_STREAMTYPE for this
1136 command.</para>
1137</entry>
1138 </row><row><entry
1139 align="char">
1140<para>int type</para>
1141</entry><entry
1142 align="char">
1143<para>stream type</para>
1144</entry>
1145 </row></tbody></tgroup></informaltable>
1146&return-value-dvb;
1147<informaltable><tgroup cols="2"><tbody><row><entry
1148 align="char">
1149<para>EINVAL</para>
1150</entry><entry
1151 align="char">
1152<para>type is not a valid or supported stream type.</para>
1153</entry>
1154 </row></tbody></tgroup></informaltable>
1155
1156</section><section id="AUDIO_SET_EXT_ID"
1157role="subsection"><title>AUDIO_SET_EXT_ID</title>
1158<para>DESCRIPTION
1159</para>
1160<informaltable><tgroup cols="1"><tbody><row><entry
1161 align="char">
1162<para>This ioctl can be used to set the extension id for MPEG streams in DVD
1163 playback. Only the first 3 bits are recognized.</para>
1164</entry>
1165 </row></tbody></tgroup></informaltable>
1166<para>SYNOPSIS
1167</para>
1168<informaltable><tgroup cols="1"><tbody><row><entry
1169 align="char">
1170<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int
1171 id);</para>
1172</entry>
1173 </row></tbody></tgroup></informaltable>
1174<para>PARAMETERS
1175</para>
1176<informaltable><tgroup cols="2"><tbody><row><entry
1177 align="char">
1178<para>int fd</para>
1179</entry><entry
1180 align="char">
1181<para>File descriptor returned by a previous call to open().</para>
1182</entry>
1183 </row><row><entry
1184 align="char">
1185<para>int request</para>
1186</entry><entry
1187 align="char">
1188<para>Equals AUDIO_SET_EXT_ID for this command.</para>
1189</entry>
1190 </row><row><entry
1191 align="char">
1192<para>int id</para>
1193</entry><entry
1194 align="char">
1195<para>audio sub_stream_id</para>
1196</entry>
1197 </row></tbody></tgroup></informaltable>
1198&return-value-dvb;
1199<informaltable><tgroup cols="2"><tbody><row><entry
1200 align="char">
1201<para>EINVAL</para>
1202</entry><entry
1203 align="char">
1204<para>id is not a valid id.</para>
1205</entry>
1206 </row></tbody></tgroup></informaltable>
1207
1208</section><section id="AUDIO_SET_ATTRIBUTES"
1209role="subsection"><title>AUDIO_SET_ATTRIBUTES</title>
1210<para>DESCRIPTION
1211</para>
1212<informaltable><tgroup cols="1"><tbody><row><entry
1213 align="char">
1214<para>This ioctl is intended for DVD playback and allows you to set certain
1215 information about the audio stream.</para>
1216</entry>
1217 </row></tbody></tgroup></informaltable>
1218<para>SYNOPSIS
1219</para>
1220<informaltable><tgroup cols="1"><tbody><row><entry
1221 align="char">
1222<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES,
1223 audio_attributes_t attr );</para>
1224</entry>
1225 </row></tbody></tgroup></informaltable>
1226<para>PARAMETERS
1227</para>
1228<informaltable><tgroup cols="2"><tbody><row><entry
1229 align="char">
1230<para>int fd</para>
1231</entry><entry
1232 align="char">
1233<para>File descriptor returned by a previous call to open().</para>
1234</entry>
1235 </row><row><entry
1236 align="char">
1237<para>int request</para>
1238</entry><entry
1239 align="char">
1240<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para>
1241</entry>
1242 </row><row><entry
1243 align="char">
1244<para>audio_attributes_t
1245 attr</para>
1246</entry><entry
1247 align="char">
1248<para>audio attributes according to section ??</para>
1249</entry>
1250 </row></tbody></tgroup></informaltable>
1251&return-value-dvb;
1252<informaltable><tgroup cols="2"><tbody><row><entry
1253 align="char">
1254<para>EINVAL</para>
1255</entry><entry
1256 align="char">
1257<para>attr is not a valid or supported attribute setting.</para>
1258</entry>
1259 </row></tbody></tgroup></informaltable>
1260
1261</section><section id="AUDIO_SET_KARAOKE"
1262role="subsection"><title>AUDIO_SET_KARAOKE</title>
1263<para>DESCRIPTION
1264</para>
1265<informaltable><tgroup cols="1"><tbody><row><entry
1266 align="char">
1267<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para>
1268</entry>
1269 </row></tbody></tgroup></informaltable>
1270<para>SYNOPSIS
1271</para>
1272<informaltable><tgroup cols="1"><tbody><row><entry
1273 align="char">
1274<para>int ioctl(fd, int request = AUDIO_SET_KARAOKE,
1275 audio_karaoke_t &#x22C6;karaoke);</para>
1276</entry>
1277 </row></tbody></tgroup></informaltable>
1278<para>PARAMETERS
1279</para>
1280<informaltable><tgroup cols="2"><tbody><row><entry
1281 align="char">
1282<para>int fd</para>
1283</entry><entry
1284 align="char">
1285<para>File descriptor returned by a previous call to open().</para>
1286</entry>
1287 </row><row><entry
1288 align="char">
1289<para>int request</para>
1290</entry><entry
1291 align="char">
1292<para>Equals AUDIO_SET_KARAOKE for this
1293 command.</para>
1294</entry>
1295 </row><row><entry
1296 align="char">
1297<para>audio_karaoke_t
1298 *karaoke</para>
1299</entry><entry
1300 align="char">
1301<para>karaoke settings according to section ??.</para>
1302</entry>
1303 </row></tbody></tgroup></informaltable>
1304&return-value-dvb;
1305<informaltable><tgroup cols="2"><tbody><row><entry
1306 align="char">
1307<para>EINVAL</para>
1308</entry><entry
1309 align="char">
1310<para>karaoke is not a valid or supported karaoke setting.</para>
1311</entry>
1312 </row></tbody></tgroup></informaltable>
1313 </section>
1314</section>
diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml
new file mode 100644
index 00000000000..85eaf4fe293
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/ca.xml
@@ -0,0 +1,582 @@
1<title>DVB CA Device</title>
2<para>The DVB CA device controls the conditional access hardware. It can be accessed through
3<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
4including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
5</para>
6
7<section id="ca_data_types">
8<title>CA Data Types</title>
9
10
11<section id="ca-slot-info">
12<title>ca_slot_info_t</title>
13 <programlisting>
14typedef struct ca_slot_info {
15 int num; /&#x22C6; slot number &#x22C6;/
16
17 int type; /&#x22C6; CA interface this slot supports &#x22C6;/
18#define CA_CI 1 /&#x22C6; CI high level interface &#x22C6;/
19#define CA_CI_LINK 2 /&#x22C6; CI link layer level interface &#x22C6;/
20#define CA_CI_PHYS 4 /&#x22C6; CI physical layer level interface &#x22C6;/
21#define CA_DESCR 8 /&#x22C6; built-in descrambler &#x22C6;/
22#define CA_SC 128 /&#x22C6; simple smart card interface &#x22C6;/
23
24 unsigned int flags;
25#define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
26#define CA_CI_MODULE_READY 2
27} ca_slot_info_t;
28</programlisting>
29
30</section>
31<section id="ca-descr-info">
32<title>ca_descr_info_t</title>
33<programlisting>
34typedef struct ca_descr_info {
35 unsigned int num; /&#x22C6; number of available descramblers (keys) &#x22C6;/
36 unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
37#define CA_ECD 1
38#define CA_NDS 2
39#define CA_DSS 4
40} ca_descr_info_t;
41</programlisting>
42
43</section>
44<section id="ca-caps">
45<title>ca_caps_t</title>
46<programlisting>
47typedef struct ca_caps {
48 unsigned int slot_num; /&#x22C6; total number of CA card and module slots &#x22C6;/
49 unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
50 unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
51 unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
52 } ca_cap_t;
53</programlisting>
54
55</section>
56<section id="ca-msg">
57<title>ca_msg_t</title>
58<programlisting>
59/&#x22C6; a message to/from a CI-CAM &#x22C6;/
60typedef struct ca_msg {
61 unsigned int index;
62 unsigned int type;
63 unsigned int length;
64 unsigned char msg[256];
65} ca_msg_t;
66</programlisting>
67
68</section>
69<section id="ca-descr">
70<title>ca_descr_t</title>
71<programlisting>
72typedef struct ca_descr {
73 unsigned int index;
74 unsigned int parity;
75 unsigned char cw[8];
76} ca_descr_t;
77</programlisting>
78</section>
79
80<section id="ca-pid">
81<title>ca-pid</title>
82<programlisting>
83typedef struct ca_pid {
84 unsigned int pid;
85 int index; /&#x22C6; -1 == disable&#x22C6;/
86} ca_pid_t;
87</programlisting>
88</section></section>
89
90<section id="ca_function_calls">
91<title>CA Function Calls</title>
92
93
94<section id="ca_fopen">
95<title>open()</title>
96<para>DESCRIPTION
97</para>
98<informaltable><tgroup cols="1"><tbody><row><entry
99 align="char">
100<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
101<para>When an open() call has succeeded, the device will be ready for use.
102 The significance of blocking or non-blocking mode is described in the
103 documentation for functions where there is a difference. It does not affect the
104 semantics of the open() call itself. A device opened in blocking mode can later
105 be put into non-blocking mode (and vice versa) using the F_SETFL command
106 of the fcntl system call. This is a standard system call, documented in the Linux
107 manual page for fcntl. Only one user can open the CA Device in O_RDWR
108 mode. All other attempts to open the device in this mode will fail, and an error
109 code will be returned.</para>
110</entry>
111 </row></tbody></tgroup></informaltable>
112<para>SYNOPSIS
113</para>
114<informaltable><tgroup cols="1"><tbody><row><entry
115 align="char">
116<para>int open(const char &#x22C6;deviceName, int flags);</para>
117</entry>
118 </row></tbody></tgroup></informaltable>
119<para>PARAMETERS
120</para>
121<informaltable><tgroup cols="2"><tbody><row><entry
122 align="char">
123<para>const char
124 *deviceName</para>
125</entry><entry
126 align="char">
127<para>Name of specific video device.</para>
128</entry>
129 </row><row><entry
130 align="char">
131<para>int flags</para>
132</entry><entry
133 align="char">
134<para>A bit-wise OR of the following flags:</para>
135</entry>
136 </row><row><entry
137 align="char">
138</entry><entry
139 align="char">
140<para>O_RDONLY read-only access</para>
141</entry>
142 </row><row><entry
143 align="char">
144</entry><entry
145 align="char">
146<para>O_RDWR read/write access</para>
147</entry>
148 </row><row><entry
149 align="char">
150</entry><entry
151 align="char">
152<para>O_NONBLOCK open in non-blocking mode</para>
153</entry>
154 </row><row><entry
155 align="char">
156</entry><entry
157 align="char">
158<para>(blocking mode is the default)</para>
159</entry>
160 </row></tbody></tgroup></informaltable>
161<para>RETURN VALUE</para>
162<informaltable><tgroup cols="2"><tbody><row><entry
163 align="char">
164<para>ENODEV</para>
165</entry><entry
166 align="char">
167<para>Device driver not loaded/available.</para>
168</entry>
169 </row><row><entry
170 align="char">
171<para>EINTERNAL</para>
172</entry><entry
173 align="char">
174<para>Internal error.</para>
175</entry>
176 </row><row><entry
177 align="char">
178<para>EBUSY</para>
179</entry><entry
180 align="char">
181<para>Device or resource busy.</para>
182</entry>
183 </row><row><entry
184 align="char">
185<para>EINVAL</para>
186</entry><entry
187 align="char">
188<para>Invalid argument.</para>
189</entry>
190 </row></tbody></tgroup></informaltable>
191
192</section>
193<section id="ca_fclose">
194<title>close()</title>
195<para>DESCRIPTION
196</para>
197<informaltable><tgroup cols="1"><tbody><row><entry
198 align="char">
199<para>This system call closes a previously opened audio device.</para>
200</entry>
201 </row></tbody></tgroup></informaltable>
202<para>SYNOPSIS
203</para>
204<informaltable><tgroup cols="1"><tbody><row><entry
205 align="char">
206<para>int close(int fd);</para>
207</entry>
208 </row></tbody></tgroup></informaltable>
209<para>PARAMETERS
210</para>
211<informaltable><tgroup cols="2"><tbody><row><entry
212 align="char">
213<para>int fd</para>
214</entry><entry
215 align="char">
216<para>File descriptor returned by a previous call to open().</para>
217</entry>
218 </row></tbody></tgroup></informaltable>
219<para>RETURN VALUE</para>
220<informaltable><tgroup cols="2"><tbody><row><entry
221 align="char">
222<para>EBADF</para>
223</entry><entry
224 align="char">
225<para>fd is not a valid open file descriptor.</para>
226</entry>
227 </row></tbody></tgroup></informaltable>
228 </section>
229
230<section id="CA_RESET"
231role="subsection"><title>CA_RESET</title>
232<para>DESCRIPTION
233</para>
234<informaltable><tgroup cols="1"><tbody><row><entry
235 align="char">
236<para>This ioctl is undocumented. Documentation is welcome.</para>
237</entry>
238 </row></tbody></tgroup></informaltable>
239<para>SYNOPSIS
240</para>
241<informaltable><tgroup cols="1"><tbody><row><entry
242 align="char">
243<para>int ioctl(fd, int request = CA_RESET);
244</para>
245</entry>
246 </row></tbody></tgroup></informaltable>
247<para>PARAMETERS
248</para>
249<informaltable><tgroup cols="2"><tbody><row><entry
250 align="char">
251<para>int fd</para>
252</entry><entry
253 align="char">
254<para>File descriptor returned by a previous call to open().</para>
255</entry>
256 </row><row><entry
257 align="char">
258<para>int request</para>
259</entry><entry
260 align="char">
261<para>Equals CA_RESET for this command.</para>
262</entry>
263 </row></tbody></tgroup></informaltable>
264&return-value-dvb;
265</section>
266
267<section id="CA_GET_CAP"
268role="subsection"><title>CA_GET_CAP</title>
269<para>DESCRIPTION
270</para>
271<informaltable><tgroup cols="1"><tbody><row><entry
272 align="char">
273<para>This ioctl is undocumented. Documentation is welcome.</para>
274</entry>
275 </row></tbody></tgroup></informaltable>
276<para>SYNOPSIS
277</para>
278<informaltable><tgroup cols="1"><tbody><row><entry
279 align="char">
280<para>int ioctl(fd, int request = CA_GET_CAP,
281 ca_caps_t *);</para>
282</entry>
283 </row></tbody></tgroup></informaltable>
284<para>PARAMETERS
285</para>
286<informaltable><tgroup cols="2"><tbody><row><entry
287 align="char">
288<para>int fd</para>
289</entry><entry
290 align="char">
291<para>File descriptor returned by a previous call to open().</para>
292</entry>
293 </row><row><entry
294 align="char">
295<para>int request</para>
296</entry><entry
297 align="char">
298<para>Equals CA_GET_CAP for this command.</para>
299</entry>
300 </row><row><entry
301 align="char">
302<para>ca_caps_t *
303</para>
304</entry><entry
305 align="char">
306<para>Undocumented.</para>
307</entry>
308 </row></tbody></tgroup></informaltable>
309&return-value-dvb;
310</section>
311
312<section id="CA_GET_SLOT_INFO"
313role="subsection"><title>CA_GET_SLOT_INFO</title>
314<para>DESCRIPTION
315</para>
316<informaltable><tgroup cols="1"><tbody><row><entry
317 align="char">
318<para>This ioctl is undocumented. Documentation is welcome.</para>
319</entry>
320 </row></tbody></tgroup></informaltable>
321<para>SYNOPSIS
322</para>
323<informaltable><tgroup cols="1"><tbody><row><entry
324 align="char">
325<para>int ioctl(fd, int request = CA_GET_SLOT_INFO,
326 ca_slot_info_t *);</para>
327</entry>
328 </row></tbody></tgroup></informaltable>
329<para>PARAMETERS
330</para>
331<informaltable><tgroup cols="2"><tbody><row><entry
332 align="char">
333<para>int fd</para>
334</entry><entry
335 align="char">
336<para>File descriptor returned by a previous call to open().</para>
337</entry>
338 </row><row><entry
339 align="char">
340<para>int request</para>
341</entry><entry
342 align="char">
343<para>Equals CA_GET_SLOT_INFO for this command.</para>
344</entry>
345 </row><row><entry
346 align="char">
347<para>ca_slot_info_t *
348</para>
349</entry><entry
350 align="char">
351<para>Undocumented.</para>
352</entry>
353 </row></tbody></tgroup></informaltable>
354&return-value-dvb;
355</section>
356
357<section id="CA_GET_DESCR_INFO"
358role="subsection"><title>CA_GET_DESCR_INFO</title>
359<para>DESCRIPTION
360</para>
361<informaltable><tgroup cols="1"><tbody><row><entry
362 align="char">
363<para>This ioctl is undocumented. Documentation is welcome.</para>
364</entry>
365 </row></tbody></tgroup></informaltable>
366<para>SYNOPSIS
367</para>
368<informaltable><tgroup cols="1"><tbody><row><entry
369 align="char">
370<para>int ioctl(fd, int request = CA_GET_DESCR_INFO,
371 ca_descr_info_t *);</para>
372</entry>
373 </row></tbody></tgroup></informaltable>
374<para>PARAMETERS
375</para>
376<informaltable><tgroup cols="2"><tbody><row><entry
377 align="char">
378<para>int fd</para>
379</entry><entry
380 align="char">
381<para>File descriptor returned by a previous call to open().</para>
382</entry>
383 </row><row><entry
384 align="char">
385<para>int request</para>
386</entry><entry
387 align="char">
388<para>Equals CA_GET_DESCR_INFO for this command.</para>
389</entry>
390 </row><row><entry
391 align="char">
392<para>ca_descr_info_t *
393</para>
394</entry><entry
395 align="char">
396<para>Undocumented.</para>
397</entry>
398 </row></tbody></tgroup></informaltable>
399&return-value-dvb;
400</section>
401
402<section id="CA_GET_MSG"
403role="subsection"><title>CA_GET_MSG</title>
404<para>DESCRIPTION
405</para>
406<informaltable><tgroup cols="1"><tbody><row><entry
407 align="char">
408<para>This ioctl is undocumented. Documentation is welcome.</para>
409</entry>
410 </row></tbody></tgroup></informaltable>
411<para>SYNOPSIS
412</para>
413<informaltable><tgroup cols="1"><tbody><row><entry
414 align="char">
415<para>int ioctl(fd, int request = CA_GET_MSG,
416 ca_msg_t *);</para>
417</entry>
418 </row></tbody></tgroup></informaltable>
419<para>PARAMETERS
420</para>
421<informaltable><tgroup cols="2"><tbody><row><entry
422 align="char">
423<para>int fd</para>
424</entry><entry
425 align="char">
426<para>File descriptor returned by a previous call to open().</para>
427</entry>
428 </row><row><entry
429 align="char">
430<para>int request</para>
431</entry><entry
432 align="char">
433<para>Equals CA_GET_MSG for this command.</para>
434</entry>
435 </row><row><entry
436 align="char">
437<para>ca_msg_t *
438</para>
439</entry><entry
440 align="char">
441<para>Undocumented.</para>
442</entry>
443 </row></tbody></tgroup></informaltable>
444&return-value-dvb;
445</section>
446
447<section id="CA_SEND_MSG"
448role="subsection"><title>CA_SEND_MSG</title>
449<para>DESCRIPTION
450</para>
451<informaltable><tgroup cols="1"><tbody><row><entry
452 align="char">
453<para>This ioctl is undocumented. Documentation is welcome.</para>
454</entry>
455 </row></tbody></tgroup></informaltable>
456<para>SYNOPSIS
457</para>
458<informaltable><tgroup cols="1"><tbody><row><entry
459 align="char">
460<para>int ioctl(fd, int request = CA_SEND_MSG,
461 ca_msg_t *);</para>
462</entry>
463 </row></tbody></tgroup></informaltable>
464<para>PARAMETERS
465</para>
466<informaltable><tgroup cols="2"><tbody><row><entry
467 align="char">
468<para>int fd</para>
469</entry><entry
470 align="char">
471<para>File descriptor returned by a previous call to open().</para>
472</entry>
473 </row><row><entry
474 align="char">
475<para>int request</para>
476</entry><entry
477 align="char">
478<para>Equals CA_SEND_MSG for this command.</para>
479</entry>
480 </row><row><entry
481 align="char">
482<para>ca_msg_t *
483</para>
484</entry><entry
485 align="char">
486<para>Undocumented.</para>
487</entry>
488 </row></tbody></tgroup></informaltable>
489&return-value-dvb;
490</section>
491
492<section id="CA_SET_DESCR"
493role="subsection"><title>CA_SET_DESCR</title>
494<para>DESCRIPTION
495</para>
496<informaltable><tgroup cols="1"><tbody><row><entry
497 align="char">
498<para>This ioctl is undocumented. Documentation is welcome.</para>
499</entry>
500 </row></tbody></tgroup></informaltable>
501<para>SYNOPSIS
502</para>
503<informaltable><tgroup cols="1"><tbody><row><entry
504 align="char">
505<para>int ioctl(fd, int request = CA_SET_DESCR,
506 ca_descr_t *);</para>
507</entry>
508 </row></tbody></tgroup></informaltable>
509<para>PARAMETERS
510</para>
511<informaltable><tgroup cols="2"><tbody><row><entry
512 align="char">
513<para>int fd</para>
514</entry><entry
515 align="char">
516<para>File descriptor returned by a previous call to open().</para>
517</entry>
518 </row><row><entry
519 align="char">
520<para>int request</para>
521</entry><entry
522 align="char">
523<para>Equals CA_SET_DESCR for this command.</para>
524</entry>
525 </row><row><entry
526 align="char">
527<para>ca_descr_t *
528</para>
529</entry><entry
530 align="char">
531<para>Undocumented.</para>
532</entry>
533 </row></tbody></tgroup></informaltable>
534&return-value-dvb;
535</section>
536
537<section id="CA_SET_PID"
538role="subsection"><title>CA_SET_PID</title>
539<para>DESCRIPTION
540</para>
541<informaltable><tgroup cols="1"><tbody><row><entry
542 align="char">
543<para>This ioctl is undocumented. Documentation is welcome.</para>
544</entry>
545 </row></tbody></tgroup></informaltable>
546<para>SYNOPSIS
547</para>
548<informaltable><tgroup cols="1"><tbody><row><entry
549 align="char">
550<para>int ioctl(fd, int request = CA_SET_PID,
551 ca_pid_t *);</para>
552</entry>
553 </row></tbody></tgroup></informaltable>
554<para>PARAMETERS
555</para>
556<informaltable><tgroup cols="2"><tbody><row><entry
557 align="char">
558<para>int fd</para>
559</entry><entry
560 align="char">
561<para>File descriptor returned by a previous call to open().</para>
562</entry>
563 </row><row><entry
564 align="char">
565<para>int request</para>
566</entry><entry
567 align="char">
568<para>Equals CA_SET_PID for this command.</para>
569</entry>
570 </row><row><entry
571 align="char">
572<para>ca_pid_t *
573</para>
574</entry><entry
575 align="char">
576<para>Undocumented.</para>
577</entry>
578 </row></tbody></tgroup></informaltable>
579&return-value-dvb;
580</section>
581
582</section>
diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml
new file mode 100644
index 00000000000..86de89cfbd6
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/demux.xml
@@ -0,0 +1,1130 @@
1<title>DVB Demux Device</title>
2
3<para>The DVB demux device controls the filters of the DVB hardware/software. It can be
4accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
5accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
6</para>
7<section id="dmx_types">
8<title>Demux Data Types</title>
9
10<section id="dmx-output-t">
11<title>dmx_output_t</title>
12<programlisting>
13typedef enum
14{
15 DMX_OUT_DECODER, /&#x22C6; Streaming directly to decoder. &#x22C6;/
16 DMX_OUT_TAP, /&#x22C6; Output going to a memory buffer &#x22C6;/
17 /&#x22C6; (to be retrieved via the read command).&#x22C6;/
18 DMX_OUT_TS_TAP, /&#x22C6; Output multiplexed into a new TS &#x22C6;/
19 /&#x22C6; (to be retrieved by reading from the &#x22C6;/
20 /&#x22C6; logical DVR device). &#x22C6;/
21 DMX_OUT_TSDEMUX_TAP /&#x22C6; Like TS_TAP but retrieved from the DMX device &#x22C6;/
22} dmx_output_t;
23</programlisting>
24<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
25called.
26</para>
27<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
28which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
29specified.
30</para>
31</section>
32
33<section id="dmx-input-t">
34<title>dmx_input_t</title>
35<programlisting>
36typedef enum
37{
38 DMX_IN_FRONTEND, /&#x22C6; Input from a front-end device. &#x22C6;/
39 DMX_IN_DVR /&#x22C6; Input from the logical DVR device. &#x22C6;/
40} dmx_input_t;
41</programlisting>
42</section>
43
44<section id="dmx-pes-type-t">
45<title>dmx_pes_type_t</title>
46<programlisting>
47typedef enum
48{
49 DMX_PES_AUDIO0,
50 DMX_PES_VIDEO0,
51 DMX_PES_TELETEXT0,
52 DMX_PES_SUBTITLE0,
53 DMX_PES_PCR0,
54
55 DMX_PES_AUDIO1,
56 DMX_PES_VIDEO1,
57 DMX_PES_TELETEXT1,
58 DMX_PES_SUBTITLE1,
59 DMX_PES_PCR1,
60
61 DMX_PES_AUDIO2,
62 DMX_PES_VIDEO2,
63 DMX_PES_TELETEXT2,
64 DMX_PES_SUBTITLE2,
65 DMX_PES_PCR2,
66
67 DMX_PES_AUDIO3,
68 DMX_PES_VIDEO3,
69 DMX_PES_TELETEXT3,
70 DMX_PES_SUBTITLE3,
71 DMX_PES_PCR3,
72
73 DMX_PES_OTHER
74} dmx_pes_type_t;
75</programlisting>
76</section>
77
78<section id="dmx-filter">
79<title>struct dmx_filter</title>
80 <programlisting>
81 typedef struct dmx_filter
82{
83 __u8 filter[DMX_FILTER_SIZE];
84 __u8 mask[DMX_FILTER_SIZE];
85 __u8 mode[DMX_FILTER_SIZE];
86} dmx_filter_t;
87</programlisting>
88</section>
89
90<section id="dmx-sct-filter-params">
91<title>struct dmx_sct_filter_params</title>
92<programlisting>
93struct dmx_sct_filter_params
94{
95 __u16 pid;
96 dmx_filter_t filter;
97 __u32 timeout;
98 __u32 flags;
99#define DMX_CHECK_CRC 1
100#define DMX_ONESHOT 2
101#define DMX_IMMEDIATE_START 4
102#define DMX_KERNEL_CLIENT 0x8000
103};
104</programlisting>
105</section>
106
107<section id="dmx-pes-filter-params">
108<title>struct dmx_pes_filter_params</title>
109<programlisting>
110struct dmx_pes_filter_params
111{
112 __u16 pid;
113 dmx_input_t input;
114 dmx_output_t output;
115 dmx_pes_type_t pes_type;
116 __u32 flags;
117};
118</programlisting>
119</section>
120
121<section id="dmx-event">
122<title>struct dmx_event</title>
123 <programlisting>
124 struct dmx_event
125 {
126 dmx_event_t event;
127 time_t timeStamp;
128 union
129 {
130 dmx_scrambling_status_t scrambling;
131 } u;
132 };
133</programlisting>
134</section>
135
136<section id="dmx-stc">
137<title>struct dmx_stc</title>
138<programlisting>
139struct dmx_stc {
140 unsigned int num; /&#x22C6; input : which STC? 0..N &#x22C6;/
141 unsigned int base; /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
142 __u64 stc; /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
143};
144</programlisting>
145</section>
146
147<section id="dmx-caps">
148<title>struct dmx_caps</title>
149<programlisting>
150 typedef struct dmx_caps {
151 __u32 caps;
152 int num_decoders;
153} dmx_caps_t;
154</programlisting>
155</section>
156
157<section id="dmx-source-t">
158<title>enum dmx_source_t</title>
159<programlisting>
160typedef enum {
161 DMX_SOURCE_FRONT0 = 0,
162 DMX_SOURCE_FRONT1,
163 DMX_SOURCE_FRONT2,
164 DMX_SOURCE_FRONT3,
165 DMX_SOURCE_DVR0 = 16,
166 DMX_SOURCE_DVR1,
167 DMX_SOURCE_DVR2,
168 DMX_SOURCE_DVR3
169} dmx_source_t;
170</programlisting>
171</section>
172
173</section>
174<section id="dmx_fcalls">
175<title>Demux Function Calls</title>
176
177<section id="dmx_fopen">
178<title>open()</title>
179<para>DESCRIPTION
180</para>
181<informaltable><tgroup cols="1"><tbody><row><entry
182 align="char">
183<para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
184 allocates a new filter and returns a handle which can be used for subsequent
185 control of that filter. This call has to be made for each filter to be used, i.e. every
186 returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
187 is a logical device to be used for retrieving Transport Streams for digital
188 video recording. When reading from this device a transport stream containing
189 the packets from all PES filters set in the corresponding demux device
190 (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
191 recorded Transport Stream is replayed by writing to this device. </para>
192<para>The significance of blocking or non-blocking mode is described in the
193 documentation for functions where there is a difference. It does not affect the
194 semantics of the open() call itself. A device opened in blocking mode can later
195 be put into non-blocking mode (and vice versa) using the F_SETFL command
196 of the fcntl system call.</para>
197</entry>
198 </row></tbody></tgroup></informaltable>
199<para>SYNOPSIS
200</para>
201<informaltable><tgroup cols="1"><tbody><row><entry
202 align="char">
203<para>int open(const char &#x22C6;deviceName, int flags);</para>
204</entry>
205 </row></tbody></tgroup></informaltable>
206<para>PARAMETERS
207</para>
208<informaltable><tgroup cols="2"><tbody><row><entry
209 align="char">
210<para>const char
211 *deviceName</para>
212</entry><entry
213 align="char">
214<para>Name of demux device.</para>
215</entry>
216 </row><row><entry
217 align="char">
218<para>int flags</para>
219</entry><entry
220 align="char">
221<para>A bit-wise OR of the following flags:</para>
222</entry>
223 </row><row><entry
224 align="char">
225</entry><entry
226 align="char">
227<para>O_RDWR read/write access</para>
228</entry>
229 </row><row><entry
230 align="char">
231</entry><entry
232 align="char">
233<para>O_NONBLOCK open in non-blocking mode</para>
234</entry>
235 </row><row><entry
236 align="char">
237</entry><entry
238 align="char">
239<para>(blocking mode is the default)</para>
240</entry>
241 </row></tbody></tgroup></informaltable>
242<para>RETURN VALUE</para>
243<informaltable><tgroup cols="2"><tbody><row><entry
244 align="char">
245<para>ENODEV</para>
246</entry><entry
247 align="char">
248<para>Device driver not loaded/available.</para>
249</entry>
250 </row><row><entry
251 align="char">
252<para>EINVAL</para>
253</entry><entry
254 align="char">
255<para>Invalid argument.</para>
256</entry>
257 </row><row><entry
258 align="char">
259<para>EMFILE</para>
260</entry><entry
261 align="char">
262<para>&#8220;Too many open files&#8221;, i.e. no more filters available.</para>
263</entry>
264 </row><row><entry
265 align="char">
266<para>ENOMEM</para>
267</entry><entry
268 align="char">
269<para>The driver failed to allocate enough memory.</para>
270</entry>
271 </row></tbody></tgroup></informaltable>
272</section>
273
274<section id="dmx_fclose">
275<title>close()</title>
276<para>DESCRIPTION
277</para>
278<informaltable><tgroup cols="1"><tbody><row><entry
279 align="char">
280<para>This system call deactivates and deallocates a filter that was previously
281 allocated via the open() call.</para>
282</entry>
283 </row></tbody></tgroup></informaltable>
284<para>SYNOPSIS
285</para>
286<informaltable><tgroup cols="1"><tbody><row><entry
287 align="char">
288<para>int close(int fd);</para>
289</entry>
290 </row></tbody></tgroup></informaltable>
291<para>PARAMETERS
292</para>
293<informaltable><tgroup cols="2"><tbody><row><entry
294 align="char">
295<para>int fd</para>
296</entry><entry
297 align="char">
298<para>File descriptor returned by a previous call to open().</para>
299</entry>
300 </row></tbody></tgroup></informaltable>
301<para>RETURN VALUE</para>
302<informaltable><tgroup cols="2"><tbody><row><entry
303 align="char">
304<para>EBADF</para>
305</entry><entry
306 align="char">
307<para>fd is not a valid open file descriptor.</para>
308</entry>
309 </row></tbody></tgroup></informaltable>
310</section>
311
312<section id="dmx_fread">
313<title>read()</title>
314<para>DESCRIPTION
315</para>
316<informaltable><tgroup cols="1"><tbody><row><entry
317 align="char">
318<para>This system call returns filtered data, which might be section or PES data. The
319 filtered data is transferred from the driver&#8217;s internal circular buffer to buf. The
320 maximum amount of data to be transferred is implied by count.</para>
321</entry>
322 </row><row><entry
323 align="char">
324<para>When returning section data the driver always tries to return a complete single
325 section (even though buf would provide buffer space for more data). If the size
326 of the buffer is smaller than the section as much as possible will be returned,
327 and the remaining data will be provided in subsequent calls.</para>
328</entry>
329 </row><row><entry
330 align="char">
331<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
332 sized sections) by default. The size of this buffer may be changed by using the
333 DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
334 the read operations are not performed fast enough, this may result in a buffer
335 overflow error. In this case EOVERFLOW will be returned, and the circular
336 buffer will be emptied. This call is blocking if there is no data to return, i.e. the
337 process will be put to sleep waiting for data, unless the O_NONBLOCK flag
338 is specified.</para>
339</entry>
340 </row><row><entry
341 align="char">
342<para>Note that in order to be able to read, the filtering process has to be started
343 by defining either a section or a PES filter by means of the ioctl functions,
344 and then starting the filtering process via the DMX_START ioctl function
345 or by setting the DMX_IMMEDIATE_START flag. If the reading is done
346 from a logical DVR demux device, the data will constitute a Transport Stream
347 including the packets from all PES filters in the corresponding demux device
348 /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
349</entry>
350 </row></tbody></tgroup></informaltable>
351<para>SYNOPSIS
352</para>
353<informaltable><tgroup cols="1"><tbody><row><entry
354 align="char">
355<para>size_t read(int fd, void &#x22C6;buf, size_t count);</para>
356</entry>
357 </row></tbody></tgroup></informaltable>
358<para>PARAMETERS
359</para>
360<informaltable><tgroup cols="2"><tbody><row><entry
361 align="char">
362<para>int fd</para>
363</entry><entry
364 align="char">
365<para>File descriptor returned by a previous call to open().</para>
366</entry>
367 </row><row><entry
368 align="char">
369<para>void *buf</para>
370</entry><entry
371 align="char">
372<para>Pointer to the buffer to be used for returned filtered data.</para>
373</entry>
374 </row><row><entry
375 align="char">
376<para>size_t count</para>
377</entry><entry
378 align="char">
379<para>Size of buf.</para>
380</entry>
381 </row></tbody></tgroup></informaltable>
382<para>RETURN VALUE</para>
383<informaltable><tgroup cols="2"><tbody><row><entry
384 align="char">
385<para>EWOULDBLOCK</para>
386</entry><entry
387 align="char">
388<para>No data to return and O_NONBLOCK was specified.</para>
389</entry>
390 </row><row><entry
391 align="char">
392<para>EBADF</para>
393</entry><entry
394 align="char">
395<para>fd is not a valid open file descriptor.</para>
396</entry>
397 </row><row><entry
398 align="char">
399<para>ECRC</para>
400</entry><entry
401 align="char">
402<para>Last section had a CRC error - no data returned. The
403 buffer is flushed.</para>
404</entry>
405 </row><row><entry
406 align="char">
407<para>EOVERFLOW</para>
408</entry><entry
409 align="char">
410</entry>
411 </row><row><entry
412 align="char">
413</entry><entry
414 align="char">
415<para>The filtered data was not read from the buffer in due
416 time, resulting in non-read data being lost. The buffer is
417 flushed.</para>
418</entry>
419 </row><row><entry
420 align="char">
421<para>ETIMEDOUT</para>
422</entry><entry
423 align="char">
424<para>The section was not loaded within the stated timeout
425 period. See ioctl DMX_SET_FILTER for how to set a
426 timeout.</para>
427</entry>
428 </row><row><entry
429 align="char">
430<para>EFAULT</para>
431</entry><entry
432 align="char">
433<para>The driver failed to write to the callers buffer due to an
434 invalid *buf pointer.</para>
435</entry>
436 </row></tbody></tgroup></informaltable>
437</section>
438
439<section id="dmx_fwrite">
440<title>write()</title>
441<para>DESCRIPTION
442</para>
443<informaltable><tgroup cols="1"><tbody><row><entry
444 align="char">
445<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
446 associated with the physical demux device that provides the actual DVR
447 functionality. It is used for replay of a digitally recorded Transport Stream.
448 Matching filters have to be defined in the corresponding physical demux
449 device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
450 implied by count.</para>
451</entry>
452 </row></tbody></tgroup></informaltable>
453<para>SYNOPSIS
454</para>
455<informaltable><tgroup cols="1"><tbody><row><entry
456 align="char">
457<para>ssize_t write(int fd, const void &#x22C6;buf, size_t
458 count);</para>
459</entry>
460 </row></tbody></tgroup></informaltable>
461<para>PARAMETERS
462</para>
463<informaltable><tgroup cols="2"><tbody><row><entry
464 align="char">
465<para>int fd</para>
466</entry><entry
467 align="char">
468<para>File descriptor returned by a previous call to open().</para>
469</entry>
470 </row><row><entry
471 align="char">
472<para>void *buf</para>
473</entry><entry
474 align="char">
475<para>Pointer to the buffer containing the Transport Stream.</para>
476</entry>
477 </row><row><entry
478 align="char">
479<para>size_t count</para>
480</entry><entry
481 align="char">
482<para>Size of buf.</para>
483</entry>
484 </row></tbody></tgroup></informaltable>
485<para>RETURN VALUE</para>
486<informaltable><tgroup cols="2"><tbody><row><entry
487 align="char">
488<para>EWOULDBLOCK</para>
489</entry><entry
490 align="char">
491<para>No data was written. This
492 might happen if O_NONBLOCK was specified and there
493 is no more buffer space available (if O_NONBLOCK is
494 not specified the function will block until buffer space is
495 available).</para>
496</entry>
497 </row><row><entry
498 align="char">
499<para>EBUSY</para>
500</entry><entry
501 align="char">
502<para>This error code indicates that there are conflicting
503 requests. The corresponding demux device is setup to
504 receive data from the front- end. Make sure that these
505 filters are stopped and that the filters with input set to
506 DMX_IN_DVR are started.</para>
507</entry>
508 </row><row><entry
509 align="char">
510<para>EBADF</para>
511</entry><entry
512 align="char">
513<para>fd is not a valid open file descriptor.</para>
514</entry>
515 </row></tbody></tgroup></informaltable>
516</section>
517
518<section id="DMX_START">
519<title>DMX_START</title>
520<para>DESCRIPTION
521</para>
522<informaltable><tgroup cols="1"><tbody><row><entry
523 align="char">
524<para>This ioctl call is used to start the actual filtering operation defined via the ioctl
525 calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
526</entry>
527 </row></tbody></tgroup></informaltable>
528<para>SYNOPSIS
529</para>
530<informaltable><tgroup cols="1"><tbody><row><entry
531 align="char">
532<para>int ioctl( int fd, int request = DMX_START);</para>
533</entry>
534 </row></tbody></tgroup></informaltable>
535<para>PARAMETERS
536</para>
537<informaltable><tgroup cols="2"><tbody><row><entry
538 align="char">
539<para>int fd</para>
540</entry><entry
541 align="char">
542<para>File descriptor returned by a previous call to open().</para>
543</entry>
544 </row><row><entry
545 align="char">
546<para>int request</para>
547</entry><entry
548 align="char">
549<para>Equals DMX_START for this command.</para>
550</entry>
551 </row></tbody></tgroup></informaltable>
552&return-value-dvb;
553<informaltable><tgroup cols="2"><tbody><row><entry
554 align="char">
555<para>EINVAL</para>
556</entry><entry
557 align="char">
558<para>Invalid argument, i.e. no filtering parameters provided via
559 the DMX_SET_FILTER or DMX_SET_PES_FILTER
560 functions.</para>
561</entry>
562 </row><row><entry
563 align="char">
564<para>EBUSY</para>
565</entry><entry
566 align="char">
567<para>This error code indicates that there are conflicting
568 requests. There are active filters filtering data from
569 another input source. Make sure that these filters are
570 stopped before starting this filter.</para>
571</entry>
572 </row></tbody></tgroup></informaltable>
573</section>
574
575<section id="DMX_STOP">
576<title>DMX_STOP</title>
577<para>DESCRIPTION
578</para>
579<informaltable><tgroup cols="1"><tbody><row><entry
580 align="char">
581<para>This ioctl call is used to stop the actual filtering operation defined via the
582 ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
583 the DMX_START command.</para>
584</entry>
585 </row></tbody></tgroup></informaltable>
586<para>SYNOPSIS
587</para>
588<informaltable><tgroup cols="1"><tbody><row><entry
589 align="char">
590<para>int ioctl( int fd, int request = DMX_STOP);</para>
591</entry>
592 </row></tbody></tgroup></informaltable>
593<para>PARAMETERS
594</para>
595<informaltable><tgroup cols="2"><tbody><row><entry
596 align="char">
597<para>int fd</para>
598</entry><entry
599 align="char">
600<para>File descriptor returned by a previous call to open().</para>
601</entry>
602 </row><row><entry
603 align="char">
604<para>int request</para>
605</entry><entry
606 align="char">
607<para>Equals DMX_STOP for this command.</para>
608</entry>
609 </row></tbody></tgroup></informaltable>
610&return-value-dvb;
611</section>
612
613<section id="DMX_SET_FILTER">
614<title>DMX_SET_FILTER</title>
615<para>DESCRIPTION
616</para>
617<informaltable><tgroup cols="1"><tbody><row><entry
618 align="char">
619<para>This ioctl call sets up a filter according to the filter and mask parameters
620 provided. A timeout may be defined stating number of seconds to wait for a
621 section to be loaded. A value of 0 means that no timeout should be applied.
622 Finally there is a flag field where it is possible to state whether a section should
623 be CRC-checked, whether the filter should be a &#8221;one-shot&#8221; filter, i.e. if the
624 filtering operation should be stopped after the first section is received, and
625 whether the filtering operation should be started immediately (without waiting
626 for a DMX_START ioctl call). If a filter was previously set-up, this filter will
627 be canceled, and the receive buffer will be flushed.</para>
628</entry>
629 </row></tbody></tgroup></informaltable>
630<para>SYNOPSIS
631</para>
632<informaltable><tgroup cols="1"><tbody><row><entry
633 align="char">
634<para>int ioctl( int fd, int request = DMX_SET_FILTER,
635 struct dmx_sct_filter_params &#x22C6;params);</para>
636</entry>
637 </row></tbody></tgroup></informaltable>
638<para>PARAMETERS
639</para>
640<informaltable><tgroup cols="2"><tbody><row><entry
641 align="char">
642<para>int fd</para>
643</entry><entry
644 align="char">
645<para>File descriptor returned by a previous call to open().</para>
646</entry>
647 </row><row><entry
648 align="char">
649<para>int request</para>
650</entry><entry
651 align="char">
652<para>Equals DMX_SET_FILTER for this command.</para>
653</entry>
654 </row><row><entry
655 align="char">
656<para>struct
657 dmx_sct_filter_params
658 *params</para>
659</entry><entry
660 align="char">
661<para>Pointer to structure containing filter parameters.</para>
662</entry>
663 </row></tbody></tgroup></informaltable>
664&return-value-dvb;
665</section>
666
667<section id="DMX_SET_PES_FILTER">
668<title>DMX_SET_PES_FILTER</title>
669<para>DESCRIPTION
670</para>
671<informaltable><tgroup cols="1"><tbody><row><entry
672 align="char">
673<para>This ioctl call sets up a PES filter according to the parameters provided. By a
674 PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
675 no PES header or payload filtering capability is supported.</para>
676</entry>
677 </row><row><entry
678 align="char">
679<para>The transport stream destination for the filtered output may be set. Also the
680 PES type may be stated in order to be able to e.g. direct a video stream directly
681 to the video decoder. Finally there is a flag field where it is possible to state
682 whether the filtering operation should be started immediately (without waiting
683 for a DMX_START ioctl call). If a filter was previously set-up, this filter will
684 be cancelled, and the receive buffer will be flushed.</para>
685</entry>
686 </row></tbody></tgroup></informaltable>
687<para>SYNOPSIS
688</para>
689<informaltable><tgroup cols="1"><tbody><row><entry
690 align="char">
691<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
692 struct dmx_pes_filter_params &#x22C6;params);</para>
693</entry>
694 </row></tbody></tgroup></informaltable>
695<para>PARAMETERS
696</para>
697<informaltable><tgroup cols="2"><tbody><row><entry
698 align="char">
699<para>int fd</para>
700</entry><entry
701 align="char">
702<para>File descriptor returned by a previous call to open().</para>
703</entry>
704 </row><row><entry
705 align="char">
706<para>int request</para>
707</entry><entry
708 align="char">
709<para>Equals DMX_SET_PES_FILTER for this command.</para>
710</entry>
711 </row><row><entry
712 align="char">
713<para>struct
714 dmx_pes_filter_params
715 *params</para>
716</entry><entry
717 align="char">
718<para>Pointer to structure containing filter parameters.</para>
719</entry>
720 </row></tbody></tgroup></informaltable>
721&return-value-dvb;
722<informaltable><tgroup cols="2"><tbody><row><entry
723 align="char">
724<para>EBUSY</para>
725</entry><entry
726 align="char">
727<para>This error code indicates that there are conflicting
728 requests. There are active filters filtering data from
729 another input source. Make sure that these filters are
730 stopped before starting this filter.</para>
731</entry>
732 </row></tbody></tgroup></informaltable>
733</section>
734
735<section id="DMX_SET_BUFFER_SIZE">
736<title>DMX_SET_BUFFER_SIZE</title>
737<para>DESCRIPTION
738</para>
739<informaltable><tgroup cols="1"><tbody><row><entry
740 align="char">
741<para>This ioctl call is used to set the size of the circular buffer used for filtered data.
742 The default size is two maximum sized sections, i.e. if this function is not called
743 a buffer size of 2 * 4096 bytes will be used.</para>
744</entry>
745 </row></tbody></tgroup></informaltable>
746<para>SYNOPSIS
747</para>
748<informaltable><tgroup cols="1"><tbody><row><entry
749 align="char">
750<para>int ioctl( int fd, int request =
751 DMX_SET_BUFFER_SIZE, unsigned long size);</para>
752</entry>
753 </row></tbody></tgroup></informaltable>
754<para>PARAMETERS
755</para>
756<informaltable><tgroup cols="2"><tbody><row><entry
757 align="char">
758<para>int fd</para>
759</entry><entry
760 align="char">
761<para>File descriptor returned by a previous call to open().</para>
762</entry>
763 </row><row><entry
764 align="char">
765<para>int request</para>
766</entry><entry
767 align="char">
768<para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
769</entry>
770 </row><row><entry
771 align="char">
772<para>unsigned long size</para>
773</entry><entry
774 align="char">
775<para>Size of circular buffer.</para>
776</entry>
777 </row></tbody></tgroup></informaltable>
778&return-value-dvb;
779</section>
780
781<section id="DMX_GET_EVENT">
782<title>DMX_GET_EVENT</title>
783<para>DESCRIPTION
784</para>
785<informaltable><tgroup cols="1"><tbody><row><entry
786 align="char">
787<para>This ioctl call returns an event if available. If an event is not available,
788 the behavior depends on whether the device is in blocking or non-blocking
789 mode. In the latter case, the call fails immediately with errno set to
790 EWOULDBLOCK. In the former case, the call blocks until an event becomes
791 available.</para>
792</entry>
793 </row><row><entry
794 align="char">
795<para>The standard Linux poll() and/or select() system calls can be used with the
796 device file descriptor to watch for new events. For select(), the file descriptor
797 should be included in the exceptfds argument, and for poll(), POLLPRI should
798 be specified as the wake-up condition. Only the latest event for each filter is
799 saved.</para>
800</entry>
801 </row></tbody></tgroup></informaltable>
802<para>SYNOPSIS
803</para>
804<informaltable><tgroup cols="1"><tbody><row><entry
805 align="char">
806<para>int ioctl( int fd, int request = DMX_GET_EVENT,
807 struct dmx_event &#x22C6;ev);</para>
808</entry>
809 </row></tbody></tgroup></informaltable>
810<para>PARAMETERS
811</para>
812<informaltable><tgroup cols="2"><tbody><row><entry
813 align="char">
814<para>int fd</para>
815</entry><entry
816 align="char">
817<para>File descriptor returned by a previous call to open().</para>
818</entry>
819 </row><row><entry
820 align="char">
821<para>int request</para>
822</entry><entry
823 align="char">
824<para>Equals DMX_GET_EVENT for this command.</para>
825</entry>
826 </row><row><entry
827 align="char">
828<para>struct dmx_event *ev</para>
829</entry><entry
830 align="char">
831<para>Pointer to the location where the event is to be stored.</para>
832</entry>
833 </row></tbody></tgroup></informaltable>
834&return-value-dvb;
835<informaltable><tgroup cols="2"><tbody><row><entry
836 align="char">
837<para>EWOULDBLOCK</para>
838</entry><entry
839 align="char">
840<para>There is no event pending, and the device is in
841 non-blocking mode.</para>
842</entry>
843 </row></tbody></tgroup></informaltable>
844</section>
845
846<section id="DMX_GET_STC">
847<title>DMX_GET_STC</title>
848<para>DESCRIPTION
849</para>
850<informaltable><tgroup cols="1"><tbody><row><entry
851 align="char">
852<para>This ioctl call returns the current value of the system time counter (which is driven
853 by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
854 STC, so you must specify which one by setting the num field of stc before the ioctl
855 (range 0...n). The result is returned in form of a ratio with a 64 bit numerator
856 and a 32 bit denominator, so the real 90kHz STC value is stc-&#x003E;stc /
857 stc-&#x003E;base
858 .</para>
859</entry>
860 </row></tbody></tgroup></informaltable>
861<para>SYNOPSIS
862</para>
863<informaltable><tgroup cols="1"><tbody><row><entry
864 align="char">
865<para>int ioctl( int fd, int request = DMX_GET_STC, struct
866 dmx_stc &#x22C6;stc);</para>
867</entry>
868 </row></tbody></tgroup></informaltable>
869<para>PARAMETERS
870</para>
871<informaltable><tgroup cols="2"><tbody><row><entry
872 align="char">
873<para>int fd</para>
874</entry><entry
875 align="char">
876<para>File descriptor returned by a previous call to open().</para>
877</entry>
878 </row><row><entry
879 align="char">
880<para>int request</para>
881</entry><entry
882 align="char">
883<para>Equals DMX_GET_STC for this command.</para>
884</entry>
885 </row><row><entry
886 align="char">
887<para>struct dmx_stc *stc</para>
888</entry><entry
889 align="char">
890<para>Pointer to the location where the stc is to be stored.</para>
891</entry>
892 </row></tbody></tgroup></informaltable>
893&return-value-dvb;
894<informaltable><tgroup cols="2"><tbody><row><entry
895 align="char">
896<para>EINVAL</para>
897</entry><entry
898 align="char">
899<para>Invalid stc number.</para>
900</entry>
901 </row></tbody></tgroup></informaltable>
902 </section>
903
904<section id="DMX_GET_PES_PIDS"
905role="subsection"><title>DMX_GET_PES_PIDS</title>
906<para>DESCRIPTION
907</para>
908<informaltable><tgroup cols="1"><tbody><row><entry
909 align="char">
910<para>This ioctl is undocumented. Documentation is welcome.</para>
911</entry>
912 </row></tbody></tgroup></informaltable>
913<para>SYNOPSIS
914</para>
915<informaltable><tgroup cols="1"><tbody><row><entry
916 align="char">
917<para>int ioctl(fd, int request = DMX_GET_PES_PIDS,
918 __u16[5]);</para>
919</entry>
920 </row></tbody></tgroup></informaltable>
921<para>PARAMETERS
922</para>
923<informaltable><tgroup cols="2"><tbody><row><entry
924 align="char">
925<para>int fd</para>
926</entry><entry
927 align="char">
928<para>File descriptor returned by a previous call to open().</para>
929</entry>
930 </row><row><entry
931 align="char">
932<para>int request</para>
933</entry><entry
934 align="char">
935<para>Equals DMX_GET_PES_PIDS for this command.</para>
936</entry>
937 </row><row><entry
938 align="char">
939<para>__u16[5]
940</para>
941</entry><entry
942 align="char">
943<para>Undocumented.</para>
944</entry>
945 </row></tbody></tgroup></informaltable>
946&return-value-dvb;
947</section>
948
949<section id="DMX_GET_CAPS"
950role="subsection"><title>DMX_GET_CAPS</title>
951<para>DESCRIPTION
952</para>
953<informaltable><tgroup cols="1"><tbody><row><entry
954 align="char">
955<para>This ioctl is undocumented. Documentation is welcome.</para>
956</entry>
957 </row></tbody></tgroup></informaltable>
958<para>SYNOPSIS
959</para>
960<informaltable><tgroup cols="1"><tbody><row><entry
961 align="char">
962<para>int ioctl(fd, int request = DMX_GET_CAPS,
963 dmx_caps_t *);</para>
964</entry>
965 </row></tbody></tgroup></informaltable>
966<para>PARAMETERS
967</para>
968<informaltable><tgroup cols="2"><tbody><row><entry
969 align="char">
970<para>int fd</para>
971</entry><entry
972 align="char">
973<para>File descriptor returned by a previous call to open().</para>
974</entry>
975 </row><row><entry
976 align="char">
977<para>int request</para>
978</entry><entry
979 align="char">
980<para>Equals DMX_GET_CAPS for this command.</para>
981</entry>
982 </row><row><entry
983 align="char">
984<para>dmx_caps_t *
985</para>
986</entry><entry
987 align="char">
988<para>Undocumented.</para>
989</entry>
990 </row></tbody></tgroup></informaltable>
991&return-value-dvb;
992</section>
993
994<section id="DMX_SET_SOURCE"
995role="subsection"><title>DMX_SET_SOURCE</title>
996<para>DESCRIPTION
997</para>
998<informaltable><tgroup cols="1"><tbody><row><entry
999 align="char">
1000<para>This ioctl is undocumented. Documentation is welcome.</para>
1001</entry>
1002 </row></tbody></tgroup></informaltable>
1003<para>SYNOPSIS
1004</para>
1005<informaltable><tgroup cols="1"><tbody><row><entry
1006 align="char">
1007<para>int ioctl(fd, int request = DMX_SET_SOURCE,
1008 dmx_source_t *);</para>
1009</entry>
1010 </row></tbody></tgroup></informaltable>
1011<para>PARAMETERS
1012</para>
1013<informaltable><tgroup cols="2"><tbody><row><entry
1014 align="char">
1015<para>int fd</para>
1016</entry><entry
1017 align="char">
1018<para>File descriptor returned by a previous call to open().</para>
1019</entry>
1020 </row><row><entry
1021 align="char">
1022<para>int request</para>
1023</entry><entry
1024 align="char">
1025<para>Equals DMX_SET_SOURCE for this command.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>dmx_source_t *
1030</para>
1031</entry><entry
1032 align="char">
1033<para>Undocumented.</para>
1034</entry>
1035 </row></tbody></tgroup></informaltable>
1036&return-value-dvb;
1037</section>
1038
1039<section id="DMX_ADD_PID"
1040role="subsection"><title>DMX_ADD_PID</title>
1041<para>DESCRIPTION
1042</para>
1043<informaltable><tgroup cols="1"><tbody><row><entry
1044 align="char">
1045<para>This ioctl is undocumented. Documentation is welcome.</para>
1046</entry>
1047 </row></tbody></tgroup></informaltable>
1048<para>SYNOPSIS
1049</para>
1050<informaltable><tgroup cols="1"><tbody><row><entry
1051 align="char">
1052<para>int ioctl(fd, int request = DMX_ADD_PID,
1053 __u16 *);</para>
1054</entry>
1055 </row></tbody></tgroup></informaltable>
1056<para>PARAMETERS
1057</para>
1058<informaltable><tgroup cols="2"><tbody><row><entry
1059 align="char">
1060<para>int fd</para>
1061</entry><entry
1062 align="char">
1063<para>File descriptor returned by a previous call to open().</para>
1064</entry>
1065 </row><row><entry
1066 align="char">
1067<para>int request</para>
1068</entry><entry
1069 align="char">
1070<para>Equals DMX_ADD_PID for this command.</para>
1071</entry>
1072 </row><row><entry
1073 align="char">
1074<para>__u16 *
1075</para>
1076</entry><entry
1077 align="char">
1078<para>Undocumented.</para>
1079</entry>
1080 </row></tbody></tgroup></informaltable>
1081&return-value-dvb;
1082</section>
1083
1084<section id="DMX_REMOVE_PID"
1085role="subsection"><title>DMX_REMOVE_PID</title>
1086<para>DESCRIPTION
1087</para>
1088<informaltable><tgroup cols="1"><tbody><row><entry
1089 align="char">
1090<para>This ioctl is undocumented. Documentation is welcome.</para>
1091</entry>
1092 </row></tbody></tgroup></informaltable>
1093<para>SYNOPSIS
1094</para>
1095<informaltable><tgroup cols="1"><tbody><row><entry
1096 align="char">
1097<para>int ioctl(fd, int request = DMX_REMOVE_PID,
1098 __u16 *);</para>
1099</entry>
1100 </row></tbody></tgroup></informaltable>
1101<para>PARAMETERS
1102</para>
1103<informaltable><tgroup cols="2"><tbody><row><entry
1104 align="char">
1105<para>int fd</para>
1106</entry><entry
1107 align="char">
1108<para>File descriptor returned by a previous call to open().</para>
1109</entry>
1110 </row><row><entry
1111 align="char">
1112<para>int request</para>
1113</entry><entry
1114 align="char">
1115<para>Equals DMX_REMOVE_PID for this command.</para>
1116</entry>
1117 </row><row><entry
1118 align="char">
1119<para>__u16 *
1120</para>
1121</entry><entry
1122 align="char">
1123<para>Undocumented.</para>
1124</entry>
1125 </row></tbody></tgroup></informaltable>
1126&return-value-dvb;
1127</section>
1128
1129
1130</section>
diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
new file mode 100644
index 00000000000..757488b24f4
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbapi.xml
@@ -0,0 +1,141 @@
1<partinfo>
2<authorgroup>
3<author>
4<firstname>Ralph</firstname>
5<surname>Metzler</surname>
6<othername role="mi">J. K.</othername>
7<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
8</author>
9<author>
10<firstname>Marcus</firstname>
11<surname>Metzler</surname>
12<othername role="mi">O. C.</othername>
13<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
14</author>
15</authorgroup>
16<authorgroup>
17<author>
18<firstname>Mauro</firstname>
19<othername role="mi">Carvalho</othername>
20<surname>Chehab</surname>
21<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
22<contrib>Ported document to Docbook XML.</contrib>
23</author>
24</authorgroup>
25<copyright>
26 <year>2002</year>
27 <year>2003</year>
28 <holder>Convergence GmbH</holder>
29</copyright>
30<copyright>
31 <year>2009-2012</year>
32 <holder>Mauro Carvalho Chehab</holder>
33</copyright>
34
35<revhistory>
36<!-- Put document revisions here, newest first. -->
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>
46 <revnumber>2.0.3</revnumber>
47 <date>2010-07-03</date>
48 <authorinitials>mcc</authorinitials>
49 <revremark>
50 Add some frontend capabilities flags, present on kernel, but missing at the specs.
51 </revremark>
52</revision>
53<revision>
54 <revnumber>2.0.2</revnumber>
55 <date>2009-10-25</date>
56 <authorinitials>mcc</authorinitials>
57 <revremark>
58 documents FE_SET_FRONTEND_TUNE_MODE and FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
59 </revremark>
60</revision>
61<revision>
62<revnumber>2.0.1</revnumber>
63<date>2009-09-16</date>
64<authorinitials>mcc</authorinitials>
65<revremark>
66Added ISDB-T test originally written by Patrick Boettcher
67</revremark>
68</revision>
69<revision>
70<revnumber>2.0.0</revnumber>
71<date>2009-09-06</date>
72<authorinitials>mcc</authorinitials>
73<revremark>Conversion from LaTex to DocBook XML. The
74 contents is the same as the original LaTex version.</revremark>
75</revision>
76<revision>
77<revnumber>1.0.0</revnumber>
78<date>2003-07-24</date>
79<authorinitials>rjkm</authorinitials>
80<revremark>Initial revision on LaTEX.</revremark>
81</revision>
82</revhistory>
83</partinfo>
84
85
86<title>LINUX DVB API</title>
87<subtitle>Version 5.8</subtitle>
88<!-- ADD THE CHAPTERS HERE -->
89 <chapter id="dvb_introdution">
90 &sub-intro;
91 </chapter>
92 <chapter id="dvb_frontend">
93 &sub-frontend;
94 </chapter>
95 <chapter id="dvb_demux">
96 &sub-demux;
97 </chapter>
98 <chapter id="dvb_video">
99 &sub-video;
100 </chapter>
101 <chapter id="dvb_audio">
102 &sub-audio;
103 </chapter>
104 <chapter id="dvb_ca">
105 &sub-ca;
106 </chapter>
107 <chapter id="dvb_net">
108 &sub-net;
109 </chapter>
110 <chapter id="dvb_kdapi">
111 &sub-kdapi;
112 </chapter>
113 <chapter id="dvb_examples">
114 &sub-examples;
115 </chapter>
116<!-- END OF CHAPTERS -->
117 <appendix id="audio_h">
118 <title>DVB Audio Header File</title>
119 &sub-audio-h;
120 </appendix>
121 <appendix id="ca_h">
122 <title>DVB Conditional Access Header File</title>
123 &sub-ca-h;
124 </appendix>
125 <appendix id="dmx_h">
126 <title>DVB Demux Header File</title>
127 &sub-dmx-h;
128 </appendix>
129 <appendix id="frontend_h">
130 <title>DVB Frontend Header File</title>
131 &sub-frontend-h;
132 </appendix>
133 <appendix id="net_h">
134 <title>DVB Network Header File</title>
135 &sub-net-h;
136 </appendix>
137 <appendix id="video_h">
138 <title>DVB Video Header File</title>
139 &sub-video-h;
140 </appendix>
141
diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
new file mode 100644
index 00000000000..957e3acaae8
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -0,0 +1,1105 @@
1<section id="FE_GET_SET_PROPERTY">
2<title><constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></title>
3<para>This section describes the DVB version 5 extention of the DVB-API, also
4called "S2API", as this API were added to provide support for DVB-S2. It was
5designed to be able to replace the old frontend API. Yet, the DISEQC and
6the capability ioctls weren't implemented yet via the new way.</para>
7<para>The typical usage for the <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant>
8API is to replace the ioctl's were the <link linkend="dvb-frontend-parameters">
9struct <constant>dvb_frontend_parameters</constant></link> were used.</para>
10<section id="dtv-property">
11<title>DTV property type</title>
12<programlisting>
13/* Reserved fields should be set to 0 */
14struct dtv_property {
15 __u32 cmd;
16 union {
17 __u32 data;
18 struct {
19 __u8 data[32];
20 __u32 len;
21 __u32 reserved1[3];
22 void *reserved2;
23 } buffer;
24 } u;
25 int result;
26} __attribute__ ((packed));
27
28/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
29#define DTV_IOCTL_MAX_MSGS 64
30</programlisting>
31</section>
32<section id="dtv-properties">
33<title>DTV properties type</title>
34<programlisting>
35struct dtv_properties {
36 __u32 num;
37 struct dtv_property *props;
38};
39</programlisting>
40</section>
41
42<section id="FE_GET_PROPERTY">
43<title>FE_GET_PROPERTY</title>
44<para>DESCRIPTION
45</para>
46<informaltable><tgroup cols="1"><tbody><row><entry
47 align="char">
48<para>This ioctl call returns one or more frontend properties. This call only
49 requires read-only access to the device.</para>
50</entry>
51 </row></tbody></tgroup></informaltable>
52<para>SYNOPSIS
53</para>
54<informaltable><tgroup cols="1"><tbody><row><entry
55 align="char">
56<para>int ioctl(int fd, int request = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>,
57 dtv_properties &#x22C6;props);</para>
58</entry>
59 </row></tbody></tgroup></informaltable>
60<para>PARAMETERS
61</para>
62<informaltable><tgroup cols="2"><tbody><row><entry align="char">
63<para>int fd</para>
64</entry><entry
65 align="char">
66<para>File descriptor returned by a previous call to open().</para>
67</entry>
68 </row><row><entry
69 align="char">
70<para>int num</para>
71</entry><entry
72 align="char">
73<para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para>
74</entry>
75 </row><row><entry
76 align="char">
77<para>struct dtv_property *props</para>
78</entry><entry
79 align="char">
80<para>Points to the location where the front-end property commands are stored.</para>
81</entry>
82 </row></tbody></tgroup></informaltable>
83&return-value-dvb;
84<informaltable><tgroup cols="2"><tbody><row>
85 <entry align="char"><para>EOPNOTSUPP</para></entry>
86 <entry align="char"><para>Property type not supported.</para></entry>
87 </row></tbody></tgroup></informaltable>
88</section>
89
90<section id="FE_SET_PROPERTY">
91<title>FE_SET_PROPERTY</title>
92<para>DESCRIPTION
93</para>
94<informaltable><tgroup cols="1"><tbody><row><entry
95 align="char">
96<para>This ioctl call sets one or more frontend properties. This call only
97 requires read-only access to the device.</para>
98</entry>
99 </row></tbody></tgroup></informaltable>
100<para>SYNOPSIS
101</para>
102<informaltable><tgroup cols="1"><tbody><row><entry
103 align="char">
104<para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
105 dtv_properties &#x22C6;props);</para>
106</entry>
107 </row></tbody></tgroup></informaltable>
108<para>PARAMETERS
109</para>
110<informaltable><tgroup cols="2"><tbody><row><entry align="char">
111<para>int fd</para>
112</entry><entry
113 align="char">
114<para>File descriptor returned by a previous call to open().</para>
115</entry>
116 </row><row><entry
117 align="char">
118<para>int num</para>
119</entry><entry
120 align="char">
121<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para>
122</entry>
123 </row><row><entry
124 align="char">
125<para>struct dtv_property *props</para>
126</entry><entry
127 align="char">
128<para>Points to the location where the front-end property commands are stored.</para>
129</entry>
130 </row></tbody></tgroup></informaltable>
131&return-value-dvb;
132<informaltable><tgroup cols="2"><tbody><row>
133 <entry align="char"><para>EOPNOTSUPP</para></entry>
134 <entry align="char"><para>Property type not supported.</para></entry>
135 </row></tbody></tgroup></informaltable>
136</section>
137
138<section>
139 <title>Property types</title>
140<para>
141On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
142the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to
143get/set up to 64 properties. The actual meaning of each property is described on the next sections.
144</para>
145
146<para>The available frontend property types are shown on the next section.</para>
147</section>
148
149<section id="fe_property_parameters">
150 <title>Digital TV property parameters</title>
151 <section id="DTV-UNDEFINED">
152 <title><constant>DTV_UNDEFINED</constant></title>
153 <para>Used internally. A GET/SET operation for it won't change or return anything.</para>
154 </section>
155 <section id="DTV-TUNE">
156 <title><constant>DTV_TUNE</constant></title>
157 <para>Interpret the cache of data, build either a traditional frontend tunerequest so we can pass validation in the <constant>FE_SET_FRONTEND</constant> ioctl.</para>
158 </section>
159 <section id="DTV-CLEAR">
160 <title><constant>DTV_CLEAR</constant></title>
161 <para>Reset a cache of data specific to the frontend here. This does not effect hardware.</para>
162 </section>
163 <section id="DTV-FREQUENCY">
164 <title><constant>DTV_FREQUENCY</constant></title>
165
166 <para>Central frequency of the channel.</para>
167
168 <para>Notes:</para>
169 <para>1)For satellital delivery systems, it is measured in kHz.
170 For the other ones, it is measured in Hz.</para>
171 <para>2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
172 E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
173 the channel which is 6MHz.</para>
174
175 <para>3)As in ISDB-Tsb the channel consists of only one or three segments the
176 frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
177 central frequency of the channel is expected.</para>
178 </section>
179 <section id="DTV-MODULATION">
180 <title><constant>DTV_MODULATION</constant></title>
181<para>Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:</para>
182<programlisting>
183 typedef enum fe_modulation {
184 QPSK,
185 QAM_16,
186 QAM_32,
187 QAM_64,
188 QAM_128,
189 QAM_256,
190 QAM_AUTO,
191 VSB_8,
192 VSB_16,
193 PSK_8,
194 APSK_16,
195 APSK_32,
196 DQPSK,
197 QAM_4_NR,
198 } fe_modulation_t;
199</programlisting>
200 </section>
201 <section id="DTV-BANDWIDTH-HZ">
202 <title><constant>DTV_BANDWIDTH_HZ</constant></title>
203
204 <para>Bandwidth for the channel, in HZ.</para>
205
206 <para>Possible values:
207 <constant>1712000</constant>,
208 <constant>5000000</constant>,
209 <constant>6000000</constant>,
210 <constant>7000000</constant>,
211 <constant>8000000</constant>,
212 <constant>10000000</constant>.
213 </para>
214
215 <para>Notes:</para>
216
217 <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
218 <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
219 <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
220 for DVB-C depends on the symbol rate</para>
221 <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
222 other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
223 DTV_ISDBT_SB_SEGMENT_COUNT).</para>
224 <para>5) DVB-T supports 6, 7 and 8MHz.</para>
225 <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para>
226 </section>
227 <section id="DTV-INVERSION">
228 <title><constant>DTV_INVERSION</constant></title>
229 <para>The Inversion field can take one of these values:
230 </para>
231 <programlisting>
232 typedef enum fe_spectral_inversion {
233 INVERSION_OFF,
234 INVERSION_ON,
235 INVERSION_AUTO
236 } fe_spectral_inversion_t;
237 </programlisting>
238 <para>It indicates if spectral inversion should be presumed or not. In the automatic setting
239 (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
240 itself.
241 </para>
242 </section>
243 <section id="DTV-DISEQC-MASTER">
244 <title><constant>DTV_DISEQC_MASTER</constant></title>
245 <para>Currently not implemented.</para>
246 </section>
247 <section id="DTV-SYMBOL-RATE">
248 <title><constant>DTV_SYMBOL_RATE</constant></title>
249 <para>Digital TV symbol rate, in bauds (symbols/second). Used on cable standards.</para>
250 </section>
251 <section id="DTV-INNER-FEC">
252 <title><constant>DTV_INNER_FEC</constant></title>
253 <para>Used cable/satellite transmissions. The acceptable values are:
254 </para>
255 <programlisting>
256typedef enum fe_code_rate {
257 FEC_NONE = 0,
258 FEC_1_2,
259 FEC_2_3,
260 FEC_3_4,
261 FEC_4_5,
262 FEC_5_6,
263 FEC_6_7,
264 FEC_7_8,
265 FEC_8_9,
266 FEC_AUTO,
267 FEC_3_5,
268 FEC_9_10,
269 FEC_2_5,
270} fe_code_rate_t;
271 </programlisting>
272 <para>which correspond to error correction rates of 1/2, 2/3, etc.,
273 no error correction or auto detection.</para>
274 </section>
275 <section id="DTV-VOLTAGE">
276 <title><constant>DTV_VOLTAGE</constant></title>
277 <para>The voltage is usually used with non-DiSEqC capable LNBs to switch
278 the polarzation (horizontal/vertical). When using DiSEqC epuipment this
279 voltage has to be switched consistently to the DiSEqC commands as
280 described in the DiSEqC spec.</para>
281 <programlisting>
282 typedef enum fe_sec_voltage {
283 SEC_VOLTAGE_13,
284 SEC_VOLTAGE_18
285 } fe_sec_voltage_t;
286 </programlisting>
287 </section>
288 <section id="DTV-TONE">
289 <title><constant>DTV_TONE</constant></title>
290 <para>Currently not used.</para>
291 </section>
292 <section id="DTV-PILOT">
293 <title><constant>DTV_PILOT</constant></title>
294 <para>Sets DVB-S2 pilot</para>
295 <section id="fe-pilot-t">
296 <title>fe_pilot type</title>
297 <programlisting>
298typedef enum fe_pilot {
299 PILOT_ON,
300 PILOT_OFF,
301 PILOT_AUTO,
302} fe_pilot_t;
303 </programlisting>
304 </section>
305 </section>
306 <section id="DTV-ROLLOFF">
307 <title><constant>DTV_ROLLOFF</constant></title>
308 <para>Sets DVB-S2 rolloff</para>
309
310 <section id="fe-rolloff-t">
311 <title>fe_rolloff type</title>
312 <programlisting>
313typedef enum fe_rolloff {
314 ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
315 ROLLOFF_20,
316 ROLLOFF_25,
317 ROLLOFF_AUTO,
318} fe_rolloff_t;
319 </programlisting>
320 </section>
321 </section>
322 <section id="DTV-DISEQC-SLAVE-REPLY">
323 <title><constant>DTV_DISEQC_SLAVE_REPLY</constant></title>
324 <para>Currently not implemented.</para>
325 </section>
326 <section id="DTV-FE-CAPABILITY-COUNT">
327 <title><constant>DTV_FE_CAPABILITY_COUNT</constant></title>
328 <para>Currently not implemented.</para>
329 </section>
330 <section id="DTV-FE-CAPABILITY">
331 <title><constant>DTV_FE_CAPABILITY</constant></title>
332 <para>Currently not implemented.</para>
333 </section>
334 <section id="DTV-DELIVERY-SYSTEM">
335 <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
336 <para>Specifies the type of Delivery system</para>
337 <section id="fe-delivery-system-t">
338 <title>fe_delivery_system type</title>
339 <para>Possible values: </para>
340<programlisting>
341
342typedef enum fe_delivery_system {
343 SYS_UNDEFINED,
344 SYS_DVBC_ANNEX_A,
345 SYS_DVBC_ANNEX_B,
346 SYS_DVBT,
347 SYS_DSS,
348 SYS_DVBS,
349 SYS_DVBS2,
350 SYS_DVBH,
351 SYS_ISDBT,
352 SYS_ISDBS,
353 SYS_ISDBC,
354 SYS_ATSC,
355 SYS_ATSCMH,
356 SYS_DTMB,
357 SYS_CMMB,
358 SYS_DAB,
359 SYS_DVBT2,
360 SYS_TURBO,
361 SYS_DVBC_ANNEX_C,
362} fe_delivery_system_t;
363</programlisting>
364 </section>
365 </section>
366 <section id="DTV-ISDBT-PARTIAL-RECEPTION">
367 <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
368
369 <para>If <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
370 the channel is in partial reception mode or not.</para>
371
372 <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
373 <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
374
375 <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
376 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
377 is consisting of one segment and layer or three segments and two layers.</para>
378
379 <para>Possible values: 0, 1, -1 (AUTO)</para>
380 </section>
381 <section id="DTV-ISDBT-SOUND-BROADCASTING">
382 <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
383
384 <para>This field represents whether the other DTV_ISDBT_*-parameters are
385 referring to an ISDB-T and an ISDB-Tsb channel. (See also
386 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
387
388 <para>Possible values: 0, 1, -1 (AUTO)</para>
389 </section>
390 <section id="DTV-ISDBT-SB-SUBCHANNEL-ID">
391 <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
392
393 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
394
395 <para>(Note of the author: This might not be the correct description of the
396 <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
397 background needed to program a device)</para>
398
399 <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
400 set of connected ISDB-Tsb channels. In this set of channels every
401 channel can be received independently. The number of connected
402 ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
403 bandwidth available.</para>
404
405 <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
406 broadcaster has several possibilities to put those channels in the
407 air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
408 segments from position 1-8 to 5-13 or anything in between.</para>
409
410 <para>The underlying layer of segments are subchannels: each segment is
411 consisting of several subchannels with a predefined IDs. A sub-channel
412 is used to help the demodulator to synchronize on the channel.</para>
413
414 <para>An ISDB-T channel is always centered over all sub-channels. As for
415 the example above, in ISDB-Tsb it is no longer as simple as that.</para>
416
417 <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
418 sub-channel ID of the segment to be demodulated.</para>
419
420 <para>Possible values: 0 .. 41, -1 (AUTO)</para>
421 </section>
422 <section id="DTV-ISDBT-SB-SEGMENT-IDX">
423 <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
424 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
425 <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
426 demodulated for an ISDB-Tsb channel where several of them are
427 transmitted in the connected manner.</para>
428 <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
429 <para>Note: This value cannot be determined by an automatic channel search.</para>
430 </section>
431 <section id="DTV-ISDBT-SB-SEGMENT-COUNT">
432 <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
433 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
434 <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
435 channels.</para>
436 <para>Possible values: 1 .. 13</para>
437 <para>Note: This value cannot be determined by an automatic channel search.</para>
438 </section>
439 <section id="isdb-hierq-layers">
440 <title><constant>DTV-ISDBT-LAYER*</constant> parameters</title>
441 <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
442 ISDB-T hierarchical layers can be decoded simultaneously. For that
443 reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para>
444 <para>ISDB-T has 3 hierarchical layers which each can use a part of the
445 available segments. The total number of segments over all layers has
446 to 13 in ISDB-T.</para>
447 <para>There are 3 parameter sets, for Layers A, B and C.</para>
448 <section id="DTV-ISDBT-LAYER-ENABLED">
449 <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
450 <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
451 layers in the decoding process. Setting all bits of
452 <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
453 demodulated. This is the default.</para>
454 <para>If the channel is in the partial reception mode
455 (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
456 independently of the other 12 segments. In that mode layer A has to
457 have a <constant>SEGMENT_COUNT</constant> of 1.</para>
458 <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
459 according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
460 accordingly.</para>
461 <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
462 <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
463 <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
464 <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
465 <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
466 </section>
467 <section id="DTV-ISDBT-LAYER-FEC">
468 <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
469 <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para>
470 </section>
471 <section id="DTV-ISDBT-LAYER-MODULATION">
472 <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
473 <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
474 <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
475 and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
476 </section>
477 <section id="DTV-ISDBT-LAYER-SEGMENT-COUNT">
478 <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
479 <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
480 <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
481 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
482 <informaltable id="isdbt-layer_seg-cnt-table">
483 <tgroup cols="6">
484 <tbody>
485 <row>
486 <entry>PR</entry>
487 <entry>SB</entry>
488 <entry>Layer A width</entry>
489 <entry>Layer B width</entry>
490 <entry>Layer C width</entry>
491 <entry>total width</entry>
492 </row>
493 <row>
494 <entry>0</entry>
495 <entry>0</entry>
496 <entry>1 .. 13</entry>
497 <entry>1 .. 13</entry>
498 <entry>1 .. 13</entry>
499 <entry>13</entry>
500 </row>
501 <row>
502 <entry>1</entry>
503 <entry>0</entry>
504 <entry>1</entry>
505 <entry>1 .. 13</entry>
506 <entry>1 .. 13</entry>
507 <entry>13</entry>
508 </row>
509 <row>
510 <entry>0</entry>
511 <entry>1</entry>
512 <entry>1</entry>
513 <entry>0</entry>
514 <entry>0</entry>
515 <entry>1</entry>
516 </row>
517 <row>
518 <entry>1</entry>
519 <entry>1</entry>
520 <entry>1</entry>
521 <entry>2</entry>
522 <entry>0</entry>
523 <entry>13</entry>
524 </row>
525 </tbody>
526 </tgroup>
527 </informaltable>
528 </section>
529 <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
530 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
531 <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
532 <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
533 here are referring to what can be found in the TMCC-structure -
534 independent of the mode.</para>
535 </section>
536 <section id="DTV-ATSCMH-FIC-VER">
537 <title><constant>DTV_ATSCMH_FIC_VER</constant></title>
538 <para>Version number of the FIC (Fast Information Channel) signaling data.</para>
539 <para>FIC is used for relaying information to allow rapid service acquisition by the receiver.</para>
540 <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para>
541 </section>
542 <section id="DTV-ATSCMH-PARADE-ID">
543 <title><constant>DTV_ATSCMH_PARADE_ID</constant></title>
544 <para>Parade identification number</para>
545 <para>A parade is a collection of up to eight MH groups, conveying one or two ensembles.</para>
546 <para>Possible values: 0, 1, 2, 3, ..., 126, 127</para>
547 </section>
548 <section id="DTV-ATSCMH-NOG">
549 <title><constant>DTV_ATSCMH_NOG</constant></title>
550 <para>Number of MH groups per MH subframe for a designated parade.</para>
551 <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para>
552 </section>
553 <section id="DTV-ATSCMH-TNOG">
554 <title><constant>DTV_ATSCMH_TNOG</constant></title>
555 <para>Total number of MH groups including all MH groups belonging to all MH parades in one MH subframe.</para>
556 <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para>
557 </section>
558 <section id="DTV-ATSCMH-SGN">
559 <title><constant>DTV_ATSCMH_SGN</constant></title>
560 <para>Start group number.</para>
561 <para>Possible values: 0, 1, 2, 3, ..., 14, 15</para>
562 </section>
563 <section id="DTV-ATSCMH-PRC">
564 <title><constant>DTV_ATSCMH_PRC</constant></title>
565 <para>Parade repetition cycle.</para>
566 <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para>
567 </section>
568 <section id="DTV-ATSCMH-RS-FRAME-MODE">
569 <title><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></title>
570 <para>RS frame mode.</para>
571 <para>Possible values are:</para>
572 <para id="atscmh-rs-frame-mode">
573<programlisting>
574typedef enum atscmh_rs_frame_mode {
575 ATSCMH_RSFRAME_PRI_ONLY = 0,
576 ATSCMH_RSFRAME_PRI_SEC = 1,
577} atscmh_rs_frame_mode_t;
578</programlisting>
579 </para>
580 </section>
581 <section id="DTV-ATSCMH-RS-FRAME-ENSEMBLE">
582 <title><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></title>
583 <para>RS frame ensemble.</para>
584 <para>Possible values are:</para>
585 <para id="atscmh-rs-frame-ensemble">
586<programlisting>
587typedef enum atscmh_rs_frame_ensemble {
588 ATSCMH_RSFRAME_ENS_PRI = 0,
589 ATSCMH_RSFRAME_ENS_SEC = 1,
590} atscmh_rs_frame_ensemble_t;
591</programlisting>
592 </para>
593 </section>
594 <section id="DTV-ATSCMH-RS-CODE-MODE-PRI">
595 <title><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></title>
596 <para>RS code mode (primary).</para>
597 <para>Possible values are:</para>
598 <para id="atscmh-rs-code-mode">
599<programlisting>
600typedef enum atscmh_rs_code_mode {
601 ATSCMH_RSCODE_211_187 = 0,
602 ATSCMH_RSCODE_223_187 = 1,
603 ATSCMH_RSCODE_235_187 = 2,
604} atscmh_rs_code_mode_t;
605</programlisting>
606 </para>
607 </section>
608 <section id="DTV-ATSCMH-RS-CODE-MODE-SEC">
609 <title><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></title>
610 <para>RS code mode (secondary).</para>
611 <para>Possible values are:</para>
612<programlisting>
613typedef enum atscmh_rs_code_mode {
614 ATSCMH_RSCODE_211_187 = 0,
615 ATSCMH_RSCODE_223_187 = 1,
616 ATSCMH_RSCODE_235_187 = 2,
617} atscmh_rs_code_mode_t;
618</programlisting>
619 </section>
620 <section id="DTV-ATSCMH-SCCC-BLOCK-MODE">
621 <title><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></title>
622 <para>Series Concatenated Convolutional Code Block Mode.</para>
623 <para>Possible values are:</para>
624 <para id="atscmh-sccc-block-mode">
625<programlisting>
626typedef enum atscmh_sccc_block_mode {
627 ATSCMH_SCCC_BLK_SEP = 0,
628 ATSCMH_SCCC_BLK_COMB = 1,
629} atscmh_sccc_block_mode_t;
630</programlisting>
631 </para>
632 </section>
633 <section id="DTV-ATSCMH-SCCC-CODE-MODE-A">
634 <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></title>
635 <para>Series Concatenated Convolutional Code Rate.</para>
636 <para>Possible values are:</para>
637 <para id="atscmh-sccc-code-mode">
638<programlisting>
639typedef enum atscmh_sccc_code_mode {
640 ATSCMH_SCCC_CODE_HLF = 0,
641 ATSCMH_SCCC_CODE_QTR = 1,
642} atscmh_sccc_code_mode_t;
643</programlisting>
644 </para>
645 </section>
646 <section id="DTV-ATSCMH-SCCC-CODE-MODE-B">
647 <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></title>
648 <para>Series Concatenated Convolutional Code Rate.</para>
649 <para>Possible values are:</para>
650<programlisting>
651typedef enum atscmh_sccc_code_mode {
652 ATSCMH_SCCC_CODE_HLF = 0,
653 ATSCMH_SCCC_CODE_QTR = 1,
654} atscmh_sccc_code_mode_t;
655</programlisting>
656 </section>
657 <section id="DTV-ATSCMH-SCCC-CODE-MODE-C">
658 <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></title>
659 <para>Series Concatenated Convolutional Code Rate.</para>
660 <para>Possible values are:</para>
661<programlisting>
662typedef enum atscmh_sccc_code_mode {
663 ATSCMH_SCCC_CODE_HLF = 0,
664 ATSCMH_SCCC_CODE_QTR = 1,
665} atscmh_sccc_code_mode_t;
666</programlisting>
667 </section>
668 <section id="DTV-ATSCMH-SCCC-CODE-MODE-D">
669 <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></title>
670 <para>Series Concatenated Convolutional Code Rate.</para>
671 <para>Possible values are:</para>
672<programlisting>
673typedef enum atscmh_sccc_code_mode {
674 ATSCMH_SCCC_CODE_HLF = 0,
675 ATSCMH_SCCC_CODE_QTR = 1,
676} atscmh_sccc_code_mode_t;
677</programlisting>
678 </section>
679 </section>
680 <section id="DTV-API-VERSION">
681 <title><constant>DTV_API_VERSION</constant></title>
682 <para>Returns the major/minor version of the DVB API</para>
683 </section>
684 <section id="DTV-CODE-RATE-HP">
685 <title><constant>DTV_CODE_RATE_HP</constant></title>
686 <para>Used on terrestrial transmissions. The acceptable values are:
687 </para>
688 <programlisting>
689typedef enum fe_code_rate {
690 FEC_NONE = 0,
691 FEC_1_2,
692 FEC_2_3,
693 FEC_3_4,
694 FEC_4_5,
695 FEC_5_6,
696 FEC_6_7,
697 FEC_7_8,
698 FEC_8_9,
699 FEC_AUTO,
700 FEC_3_5,
701 FEC_9_10,
702} fe_code_rate_t;
703 </programlisting>
704 </section>
705 <section id="DTV-CODE-RATE-LP">
706 <title><constant>DTV_CODE_RATE_LP</constant></title>
707 <para>Used on terrestrial transmissions. The acceptable values are:
708 </para>
709 <programlisting>
710typedef enum fe_code_rate {
711 FEC_NONE = 0,
712 FEC_1_2,
713 FEC_2_3,
714 FEC_3_4,
715 FEC_4_5,
716 FEC_5_6,
717 FEC_6_7,
718 FEC_7_8,
719 FEC_8_9,
720 FEC_AUTO,
721 FEC_3_5,
722 FEC_9_10,
723} fe_code_rate_t;
724 </programlisting>
725 </section>
726 <section id="DTV-GUARD-INTERVAL">
727 <title><constant>DTV_GUARD_INTERVAL</constant></title>
728
729 <para>Possible values are:</para>
730<programlisting>
731typedef enum fe_guard_interval {
732 GUARD_INTERVAL_1_32,
733 GUARD_INTERVAL_1_16,
734 GUARD_INTERVAL_1_8,
735 GUARD_INTERVAL_1_4,
736 GUARD_INTERVAL_AUTO,
737 GUARD_INTERVAL_1_128,
738 GUARD_INTERVAL_19_128,
739 GUARD_INTERVAL_19_256,
740 GUARD_INTERVAL_PN420,
741 GUARD_INTERVAL_PN595,
742 GUARD_INTERVAL_PN945,
743} fe_guard_interval_t;
744</programlisting>
745
746 <para>Notes:</para>
747 <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
748 try to find the correct guard interval (if capable) and will use TMCC to fill
749 in the missing parameters.</para>
750 <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para>
751 <para>3) DTMB specifies PN420, PN595 and PN945.</para>
752 </section>
753 <section id="DTV-TRANSMISSION-MODE">
754 <title><constant>DTV_TRANSMISSION_MODE</constant></title>
755
756 <para>Specifies the number of carriers used by the standard</para>
757
758 <para>Possible values are:</para>
759<programlisting>
760typedef enum fe_transmit_mode {
761 TRANSMISSION_MODE_2K,
762 TRANSMISSION_MODE_8K,
763 TRANSMISSION_MODE_AUTO,
764 TRANSMISSION_MODE_4K,
765 TRANSMISSION_MODE_1K,
766 TRANSMISSION_MODE_16K,
767 TRANSMISSION_MODE_32K,
768 TRANSMISSION_MODE_C1,
769 TRANSMISSION_MODE_C3780,
770} fe_transmit_mode_t;
771</programlisting>
772 <para>Notes:</para>
773 <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
774 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
775
776 <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
777 hardware will try to find the correct FFT-size (if capable) and will
778 use TMCC to fill in the missing parameters.</para>
779 <para>3) DVB-T specifies 2K and 8K as valid sizes.</para>
780 <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para>
781 <para>5) DTMB specifies C1 and C3780.</para>
782 </section>
783 <section id="DTV-HIERARCHY">
784 <title><constant>DTV_HIERARCHY</constant></title>
785 <para>Frontend hierarchy</para>
786 <programlisting>
787typedef enum fe_hierarchy {
788 HIERARCHY_NONE,
789 HIERARCHY_1,
790 HIERARCHY_2,
791 HIERARCHY_4,
792 HIERARCHY_AUTO
793 } fe_hierarchy_t;
794 </programlisting>
795 </section>
796 <section id="DTV-STREAM-ID">
797 <title><constant>DTV_STREAM_ID</constant></title>
798 <para>DVB-S2, DVB-T2 and ISDB-S support the transmission of several
799 streams on a single transport stream.
800 This property enables the DVB driver to handle substream filtering,
801 when supported by the hardware.
802 By default, substream filtering is disabled.
803 </para><para>
804 For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255.
805 </para><para>
806 For ISDB, the valid substream id range is from 1 to 65535.
807 </para><para>
808 To disable it, you should use the special macro NO_STREAM_ID_FILTER.
809 </para><para>
810 Note: any value outside the id range also disables filtering.
811 </para>
812 </section>
813 <section id="DTV-DVBT2-PLP-ID-LEGACY">
814 <title><constant>DTV_DVBT2_PLP_ID_LEGACY</constant></title>
815 <para>Obsolete, replaced with DTV_STREAM_ID.</para>
816 </section>
817 <section id="DTV-ENUM-DELSYS">
818 <title><constant>DTV_ENUM_DELSYS</constant></title>
819 <para>A Multi standard frontend needs to advertise the delivery systems provided.
820 Applications need to enumerate the provided delivery systems, before using
821 any other operation with the frontend. Prior to it's introduction,
822 FE_GET_INFO was used to determine a frontend type. A frontend which
823 provides more than a single delivery system, FE_GET_INFO doesn't help much.
824 Applications which intends to use a multistandard frontend must enumerate
825 the delivery systems associated with it, rather than trying to use
826 FE_GET_INFO. In the case of a legacy frontend, the result is just the same
827 as with FE_GET_INFO, but in a more structured format </para>
828 </section>
829 <section id="DTV-INTERLEAVING">
830 <title><constant>DTV_INTERLEAVING</constant></title>
831 <para id="fe-interleaving">Interleaving mode</para>
832 <programlisting>
833enum fe_interleaving {
834 INTERLEAVING_NONE,
835 INTERLEAVING_AUTO,
836 INTERLEAVING_240,
837 INTERLEAVING_720,
838};
839 </programlisting>
840 </section>
841 <section id="DTV-LNA">
842 <title><constant>DTV_LNA</constant></title>
843 <para>Low-noise amplifier.</para>
844 <para>Hardware might offer controllable LNA which can be set manually
845 using that parameter. Usually LNA could be found only from
846 terrestrial devices if at all.</para>
847 <para>Possible values: 0, 1, LNA_AUTO</para>
848 <para>0, LNA off</para>
849 <para>1, LNA on</para>
850 <para>use the special macro LNA_AUTO to set LNA auto</para>
851 </section>
852</section>
853 <section id="frontend-property-terrestrial-systems">
854 <title>Properties used on terrestrial delivery systems</title>
855 <section id="dvbt-params">
856 <title>DVB-T delivery system</title>
857 <para>The following parameters are valid for DVB-T:</para>
858 <itemizedlist mark='opencircle'>
859 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
860 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
861 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
862 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
863 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
864 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
865 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
866 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
867 <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
868 <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
869 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
870 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
871 <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
872 <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
873 </itemizedlist>
874 </section>
875 <section id="dvbt2-params">
876 <title>DVB-T2 delivery system</title>
877 <para>DVB-T2 support is currently in the early stages
878 of development, so expect that this section maygrow and become
879 more detailed with time.</para>
880 <para>The following parameters are valid for DVB-T2:</para>
881 <itemizedlist mark='opencircle'>
882 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
883 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
884 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
885 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
886 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
887 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
888 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
889 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
890 <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
891 <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
892 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
893 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
894 <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
895 <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
896 <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
897 </itemizedlist>
898 </section>
899 <section id="isdbt">
900 <title>ISDB-T delivery system</title>
901 <para>This ISDB-T/ISDB-Tsb API extension should reflect all information
902 needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
903 that some very sophisticated devices won't need certain parameters to
904 tune.</para>
905 <para>The information given here should help application writers to know how
906 to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
907 <para>The details given here about ISDB-T and ISDB-Tsb are just enough to
908 basically show the dependencies between the needed parameter values,
909 but surely some information is left out. For more detailed information
910 see the following documents:</para>
911 <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
912 Television Broadcasting" and</para>
913 <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
914 Television Broadcasting".</para>
915 <para>In order to understand the ISDB specific parameters,
916 one has to have some knowledge the channel structure in
917 ISDB-T and ISDB-Tsb. I.e. it has to be known to
918 the reader that an ISDB-T channel consists of 13 segments,
919 that it can have up to 3 layer sharing those segments,
920 and things like that.</para>
921 <para>The following parameters are valid for ISDB-T:</para>
922 <itemizedlist mark='opencircle'>
923 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
924 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
925 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
926 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
927 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
928 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
929 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
930 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
931 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
932 <listitem><para><link linkend="DTV-ISDBT-LAYER-ENABLED"><constant>DTV_ISDBT_LAYER_ENABLED</constant></link></para></listitem>
933 <listitem><para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION"><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></link></para></listitem>
934 <listitem><para><link linkend="DTV-ISDBT-SOUND-BROADCASTING"><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></link></para></listitem>
935 <listitem><para><link linkend="DTV-ISDBT-SB-SUBCHANNEL-ID"><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></link></para></listitem>
936 <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-IDX"><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></link></para></listitem>
937 <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-COUNT"><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></link></para></listitem>
938 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERA_FEC</constant></link></para></listitem>
939 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERA_MODULATION</constant></link></para></listitem>
940 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant></link></para></listitem>
941 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERA_TIME_INTERLEAVING</constant></link></para></listitem>
942 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERB_FEC</constant></link></para></listitem>
943 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERB_MODULATION</constant></link></para></listitem>
944 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERB_SEGMENT_COUNT</constant></link></para></listitem>
945 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERB_TIME_INTERLEAVING</constant></link></para></listitem>
946 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERC_FEC</constant></link></para></listitem>
947 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERC_MODULATION</constant></link></para></listitem>
948 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERC_SEGMENT_COUNT</constant></link></para></listitem>
949 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERC_TIME_INTERLEAVING</constant></link></para></listitem>
950 </itemizedlist>
951 </section>
952 <section id="atsc-params">
953 <title>ATSC delivery system</title>
954 <para>The following parameters are valid for ATSC:</para>
955 <itemizedlist mark='opencircle'>
956 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
957 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
958 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
959 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
960 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
961 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
962 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
963 </itemizedlist>
964 </section>
965 <section id="atscmh-params">
966 <title>ATSC-MH delivery system</title>
967 <para>The following parameters are valid for ATSC-MH:</para>
968 <itemizedlist mark='opencircle'>
969 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
970 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
971 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
972 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
973 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
974 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
975 <listitem><para><link linkend="DTV-ATSCMH-FIC-VER"><constant>DTV_ATSCMH_FIC_VER</constant></link></para></listitem>
976 <listitem><para><link linkend="DTV-ATSCMH-PARADE-ID"><constant>DTV_ATSCMH_PARADE_ID</constant></link></para></listitem>
977 <listitem><para><link linkend="DTV-ATSCMH-NOG"><constant>DTV_ATSCMH_NOG</constant></link></para></listitem>
978 <listitem><para><link linkend="DTV-ATSCMH-TNOG"><constant>DTV_ATSCMH_TNOG</constant></link></para></listitem>
979 <listitem><para><link linkend="DTV-ATSCMH-SGN"><constant>DTV_ATSCMH_SGN</constant></link></para></listitem>
980 <listitem><para><link linkend="DTV-ATSCMH-PRC"><constant>DTV_ATSCMH_PRC</constant></link></para></listitem>
981 <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-MODE"><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></link></para></listitem>
982 <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-ENSEMBLE"><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></link></para></listitem>
983 <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-PRI"><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></link></para></listitem>
984 <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-SEC"><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></link></para></listitem>
985 <listitem><para><link linkend="DTV-ATSCMH-SCCC-BLOCK-MODE"><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></link></para></listitem>
986 <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-A"><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></link></para></listitem>
987 <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-B"><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></link></para></listitem>
988 <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-C"><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></link></para></listitem>
989 <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-D"><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></link></para></listitem>
990 </itemizedlist>
991 </section>
992 <section id="dtmb-params">
993 <title>DTMB delivery system</title>
994 <para>The following parameters are valid for DTMB:</para>
995 <itemizedlist mark='opencircle'>
996 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
997 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
998 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
999 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
1000 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
1001 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
1002 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
1003 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
1004 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
1005 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
1006 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
1007 <listitem><para><link linkend="DTV-INTERLEAVING"><constant>DTV_INTERLEAVING</constant></link></para></listitem>
1008 <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
1009 </itemizedlist>
1010 </section>
1011 </section>
1012 <section id="frontend-property-cable-systems">
1013 <title>Properties used on cable delivery systems</title>
1014 <section id="dvbc-params">
1015 <title>DVB-C delivery system</title>
1016 <para>The DVB-C Annex-A is the widely used cable standard. Transmission uses QAM modulation.</para>
1017 <para>The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It supports a subset of the Annex A modulation types, and a roll-off of 0.13, instead of 0.15</para>
1018 <para>The following parameters are valid for DVB-C Annex A/C:</para>
1019 <itemizedlist mark='opencircle'>
1020 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
1021 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
1022 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
1023 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
1024 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
1025 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
1026 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
1027 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
1028 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
1029 <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
1030 </itemizedlist>
1031 </section>
1032 <section id="dvbc-annex-b-params">
1033 <title>DVB-C Annex B delivery system</title>
1034 <para>The DVB-C Annex-B is only used on a few Countries like the United States.</para>
1035 <para>The following parameters are valid for DVB-C Annex B:</para>
1036 <itemizedlist mark='opencircle'>
1037 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
1038 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
1039 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
1040 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
1041 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
1042 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
1043 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
1044 <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem>
1045 </itemizedlist>
1046 </section>
1047 </section>
1048 <section id="frontend-property-satellital-systems">
1049 <title>Properties used on satellital delivery systems</title>
1050 <section id="dvbs-params">
1051 <title>DVB-S delivery system</title>
1052 <para>The following parameters are valid for DVB-S:</para>
1053 <itemizedlist mark='opencircle'>
1054 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
1055 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
1056 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
1057 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
1058 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
1059 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
1060 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
1061 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
1062 <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
1063 <listitem><para><link linkend="DTV-TONE"><constant>DTV_TONE</constant></link></para></listitem>
1064 </itemizedlist>
1065 <para>Future implementations might add those two missing parameters:</para>
1066 <itemizedlist mark='opencircle'>
1067 <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem>
1068 <listitem><para><link linkend="DTV-DISEQC-SLAVE-REPLY"><constant>DTV_DISEQC_SLAVE_REPLY</constant></link></para></listitem>
1069 </itemizedlist>
1070 </section>
1071 <section id="dvbs2-params">
1072 <title>DVB-S2 delivery system</title>
1073 <para>In addition to all parameters valid for DVB-S, DVB-S2 supports the following parameters:</para>
1074 <itemizedlist mark='opencircle'>
1075 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
1076 <listitem><para><link linkend="DTV-PILOT"><constant>DTV_PILOT</constant></link></para></listitem>
1077 <listitem><para><link linkend="DTV-ROLLOFF"><constant>DTV_ROLLOFF</constant></link></para></listitem>
1078 <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
1079 </itemizedlist>
1080 </section>
1081 <section id="turbo-params">
1082 <title>Turbo code delivery system</title>
1083 <para>In addition to all parameters valid for DVB-S, turbo code supports the following parameters:</para>
1084 <itemizedlist mark='opencircle'>
1085 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
1086 </itemizedlist>
1087 </section>
1088 <section id="isdbs-params">
1089 <title>ISDB-S delivery system</title>
1090 <para>The following parameters are valid for ISDB-S:</para>
1091 <itemizedlist mark='opencircle'>
1092 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
1093 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
1094 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
1095 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
1096 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
1097 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
1098 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
1099 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
1100 <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
1101 <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem>
1102 </itemizedlist>
1103 </section>
1104 </section>
1105</section>
diff --git a/Documentation/DocBook/media/dvb/dvbstb.pdf b/Documentation/DocBook/media/dvb/dvbstb.pdf
new file mode 100644
index 00000000000..0fa75d90c3e
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbstb.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml
new file mode 100644
index 00000000000..f037e568eb6
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/examples.xml
@@ -0,0 +1,365 @@
1<title>Examples</title>
2<para>In this section we would like to present some examples for using the DVB API.
3</para>
4<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged
5with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />.
6</para>
7
8<section id="tuning">
9<title>Tuning</title>
10<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as
11the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
12QAM.
13</para>
14<programlisting>
15 #include &#x003C;sys/ioctl.h&#x003E;
16 #include &#x003C;stdio.h&#x003E;
17 #include &#x003C;stdint.h&#x003E;
18 #include &#x003C;sys/types.h&#x003E;
19 #include &#x003C;sys/stat.h&#x003E;
20 #include &#x003C;fcntl.h&#x003E;
21 #include &#x003C;time.h&#x003E;
22 #include &#x003C;unistd.h&#x003E;
23
24 #include &#x003C;linux/dvb/dmx.h&#x003E;
25 #include &#x003C;linux/dvb/frontend.h&#x003E;
26 #include &#x003C;linux/dvb/sec.h&#x003E;
27 #include &#x003C;sys/poll.h&#x003E;
28
29 #define DMX "/dev/dvb/adapter0/demux1"
30 #define FRONT "/dev/dvb/adapter0/frontend1"
31 #define SEC "/dev/dvb/adapter0/sec1"
32
33 /&#x22C6; routine for checking if we have a signal and other status information&#x22C6;/
34 int FEReadStatus(int fd, fe_status_t &#x22C6;stat)
35 {
36 int ans;
37
38 if ( (ans = ioctl(fd,FE_READ_STATUS,stat) &#x003C; 0)){
39 perror("FE READ STATUS: ");
40 return -1;
41 }
42
43 if (&#x22C6;stat &amp; FE_HAS_POWER)
44 printf("FE HAS POWER\n");
45
46 if (&#x22C6;stat &amp; FE_HAS_SIGNAL)
47 printf("FE HAS SIGNAL\n");
48
49 if (&#x22C6;stat &amp; FE_SPECTRUM_INV)
50 printf("SPEKTRUM INV\n");
51
52 return 0;
53 }
54
55
56 /&#x22C6; tune qpsk &#x22C6;/
57 /&#x22C6; freq: frequency of transponder &#x22C6;/
58 /&#x22C6; vpid, apid, tpid: PIDs of video, audio and teletext TS packets &#x22C6;/
59 /&#x22C6; diseqc: DiSEqC address of the used LNB &#x22C6;/
60 /&#x22C6; pol: Polarisation &#x22C6;/
61 /&#x22C6; srate: Symbol Rate &#x22C6;/
62 /&#x22C6; fec. FEC &#x22C6;/
63 /&#x22C6; lnb_lof1: local frequency of lower LNB band &#x22C6;/
64 /&#x22C6; lnb_lof2: local frequency of upper LNB band &#x22C6;/
65 /&#x22C6; lnb_slof: switch frequency of LNB &#x22C6;/
66
67 int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
68 int diseqc, int pol, int srate, int fec, int lnb_lof1,
69 int lnb_lof2, int lnb_slof)
70 {
71 struct secCommand scmd;
72 struct secCmdSequence scmds;
73 struct dmx_pes_filter_params pesFilterParams;
74 FrontendParameters frp;
75 struct pollfd pfd[1];
76 FrontendEvent event;
77 int demux1, demux2, demux3, front;
78
79 frequency = (uint32_t) freq;
80 symbolrate = (uint32_t) srate;
81
82 if((front = open(FRONT,O_RDWR)) &#x003C; 0){
83 perror("FRONTEND DEVICE: ");
84 return -1;
85 }
86
87 if((sec = open(SEC,O_RDWR)) &#x003C; 0){
88 perror("SEC DEVICE: ");
89 return -1;
90 }
91
92 if (demux1 &#x003C; 0){
93 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
94 &#x003C; 0){
95 perror("DEMUX DEVICE: ");
96 return -1;
97 }
98 }
99
100 if (demux2 &#x003C; 0){
101 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
102 &#x003C; 0){
103 perror("DEMUX DEVICE: ");
104 return -1;
105 }
106 }
107
108 if (demux3 &#x003C; 0){
109 if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
110 &#x003C; 0){
111 perror("DEMUX DEVICE: ");
112 return -1;
113 }
114 }
115
116 if (freq &#x003C; lnb_slof) {
117 frp.Frequency = (freq - lnb_lof1);
118 scmds.continuousTone = SEC_TONE_OFF;
119 } else {
120 frp.Frequency = (freq - lnb_lof2);
121 scmds.continuousTone = SEC_TONE_ON;
122 }
123 frp.Inversion = INVERSION_AUTO;
124 if (pol) scmds.voltage = SEC_VOLTAGE_18;
125 else scmds.voltage = SEC_VOLTAGE_13;
126
127 scmd.type=0;
128 scmd.u.diseqc.addr=0x10;
129 scmd.u.diseqc.cmd=0x38;
130 scmd.u.diseqc.numParams=1;
131 scmd.u.diseqc.params[0] = 0xF0 | ((diseqc &#x22C6; 4) &amp; 0x0F) |
132 (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
133 (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
134
135 scmds.miniCommand=SEC_MINI_NONE;
136 scmds.numCommands=1;
137 scmds.commands=&amp;scmd;
138 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
139 perror("SEC SEND: ");
140 return -1;
141 }
142
143 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
144 perror("SEC SEND: ");
145 return -1;
146 }
147
148 frp.u.qpsk.SymbolRate = srate;
149 frp.u.qpsk.FEC_inner = fec;
150
151 if (ioctl(front, FE_SET_FRONTEND, &amp;frp) &#x003C; 0){
152 perror("QPSK TUNE: ");
153 return -1;
154 }
155
156 pfd[0].fd = front;
157 pfd[0].events = POLLIN;
158
159 if (poll(pfd,1,3000)){
160 if (pfd[0].revents &amp; POLLIN){
161 printf("Getting QPSK event\n");
162 if ( ioctl(front, FE_GET_EVENT, &amp;event)
163
164 == -EOVERFLOW){
165 perror("qpsk get event");
166 return -1;
167 }
168 printf("Received ");
169 switch(event.type){
170 case FE_UNEXPECTED_EV:
171 printf("unexpected event\n");
172 return -1;
173 case FE_FAILURE_EV:
174 printf("failure event\n");
175 return -1;
176
177 case FE_COMPLETION_EV:
178 printf("completion event\n");
179 }
180 }
181 }
182
183
184 pesFilterParams.pid = vpid;
185 pesFilterParams.input = DMX_IN_FRONTEND;
186 pesFilterParams.output = DMX_OUT_DECODER;
187 pesFilterParams.pes_type = DMX_PES_VIDEO;
188 pesFilterParams.flags = DMX_IMMEDIATE_START;
189 if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
190 perror("set_vpid");
191 return -1;
192 }
193
194 pesFilterParams.pid = apid;
195 pesFilterParams.input = DMX_IN_FRONTEND;
196 pesFilterParams.output = DMX_OUT_DECODER;
197 pesFilterParams.pes_type = DMX_PES_AUDIO;
198 pesFilterParams.flags = DMX_IMMEDIATE_START;
199 if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
200 perror("set_apid");
201 return -1;
202 }
203
204 pesFilterParams.pid = tpid;
205 pesFilterParams.input = DMX_IN_FRONTEND;
206 pesFilterParams.output = DMX_OUT_DECODER;
207 pesFilterParams.pes_type = DMX_PES_TELETEXT;
208 pesFilterParams.flags = DMX_IMMEDIATE_START;
209 if (ioctl(demux3, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
210 perror("set_tpid");
211 return -1;
212 }
213
214 return has_signal(fds);
215 }
216
217</programlisting>
218<para>The program assumes that you are using a universal LNB and a standard DiSEqC
219switch with up to 4 addresses. Of course, you could build in some more checking if
220tuning was successful and maybe try to repeat the tuning process. Depending on the
221external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
222necessary.
223</para>
224</section>
225
226<section id="the_dvr_device">
227<title>The DVR device</title>
228<para>The following program code shows how to use the DVR device for recording.
229</para>
230<programlisting>
231 #include &#x003C;sys/ioctl.h&#x003E;
232 #include &#x003C;stdio.h&#x003E;
233 #include &#x003C;stdint.h&#x003E;
234 #include &#x003C;sys/types.h&#x003E;
235 #include &#x003C;sys/stat.h&#x003E;
236 #include &#x003C;fcntl.h&#x003E;
237 #include &#x003C;time.h&#x003E;
238 #include &#x003C;unistd.h&#x003E;
239
240 #include &#x003C;linux/dvb/dmx.h&#x003E;
241 #include &#x003C;linux/dvb/video.h&#x003E;
242 #include &#x003C;sys/poll.h&#x003E;
243 #define DVR "/dev/dvb/adapter0/dvr1"
244 #define AUDIO "/dev/dvb/adapter0/audio1"
245 #define VIDEO "/dev/dvb/adapter0/video1"
246
247 #define BUFFY (188&#x22C6;20)
248 #define MAX_LENGTH (1024&#x22C6;1024&#x22C6;5) /&#x22C6; record 5MB &#x22C6;/
249
250
251 /&#x22C6; switch the demuxes to recording, assuming the transponder is tuned &#x22C6;/
252
253 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
254 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
255
256 int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
257 {
258 struct dmx_pes_filter_params pesFilterParams;
259
260 if (demux1 &#x003C; 0){
261 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
262 &#x003C; 0){
263 perror("DEMUX DEVICE: ");
264 return -1;
265 }
266 }
267
268 if (demux2 &#x003C; 0){
269 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
270 &#x003C; 0){
271 perror("DEMUX DEVICE: ");
272 return -1;
273 }
274 }
275
276 pesFilterParams.pid = vpid;
277 pesFilterParams.input = DMX_IN_FRONTEND;
278 pesFilterParams.output = DMX_OUT_TS_TAP;
279 pesFilterParams.pes_type = DMX_PES_VIDEO;
280 pesFilterParams.flags = DMX_IMMEDIATE_START;
281 if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
282 perror("DEMUX DEVICE");
283 return -1;
284 }
285 pesFilterParams.pid = apid;
286 pesFilterParams.input = DMX_IN_FRONTEND;
287 pesFilterParams.output = DMX_OUT_TS_TAP;
288 pesFilterParams.pes_type = DMX_PES_AUDIO;
289 pesFilterParams.flags = DMX_IMMEDIATE_START;
290 if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
291 perror("DEMUX DEVICE");
292 return -1;
293 }
294 return 0;
295 }
296
297 /&#x22C6; start recording MAX_LENGTH , assuming the transponder is tuned &#x22C6;/
298
299 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
300 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
301 int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
302 {
303 int i;
304 int len;
305 int written;
306 uint8_t buf[BUFFY];
307 uint64_t length;
308 struct pollfd pfd[1];
309 int dvr, dvr_out;
310
311 /&#x22C6; open dvr device &#x22C6;/
312 if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) &#x003C; 0){
313 perror("DVR DEVICE");
314 return -1;
315 }
316
317 /&#x22C6; switch video and audio demuxes to dvr &#x22C6;/
318 printf ("Switching dvr on\n");
319 i = switch_to_record(demux1, demux2, vpid, apid);
320 printf("finished: ");
321
322 printf("Recording %2.0f MB of test file in TS format\n",
323 MAX_LENGTH/(1024.0&#x22C6;1024.0));
324 length = 0;
325
326 /&#x22C6; open output file &#x22C6;/
327 if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
328 |O_TRUNC, S_IRUSR|S_IWUSR
329 |S_IRGRP|S_IWGRP|S_IROTH|
330 S_IWOTH)) &#x003C; 0){
331 perror("Can't open file for dvr test");
332 return -1;
333 }
334
335 pfd[0].fd = dvr;
336 pfd[0].events = POLLIN;
337
338 /&#x22C6; poll for dvr data and write to file &#x22C6;/
339 while (length &#x003C; MAX_LENGTH ) {
340 if (poll(pfd,1,1)){
341 if (pfd[0].revents &amp; POLLIN){
342 len = read(dvr, buf, BUFFY);
343 if (len &#x003C; 0){
344 perror("recording");
345 return -1;
346 }
347 if (len &#x003E; 0){
348 written = 0;
349 while (written &#x003C; len)
350 written +=
351 write (dvr_out,
352 buf, len);
353 length += len;
354 printf("written %2.0f MB\r",
355 length/1024./1024.);
356 }
357 }
358 }
359 }
360 return 0;
361 }
362
363</programlisting>
364
365</section>
diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml
new file mode 100644
index 00000000000..426c2526a45
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/frontend.xml
@@ -0,0 +1,1548 @@
1<title>DVB Frontend API</title>
2
3<para>The DVB frontend device controls the tuner and DVB demodulator
4hardware. It can be accessed through <emphasis
5role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and
6ioctl definitions can be accessed by including <emphasis
7role="tt">linux/dvb/frontend.h</emphasis> in your application.</para>
8
9<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C
10(cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP)
11is not yet handled by this API but a future extension is possible. For
12DVB-S the frontend device also supports satellite equipment control
13(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
14specification is available from
15<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para>
16
17<para>Note that the DVB API may also be used for MPEG decoder-only PCI
18cards, in which case there exists no frontend device.</para>
19
20<section id="frontend_types">
21<title>Frontend Data Types</title>
22
23<section id="fe-type-t">
24<title>Frontend type</title>
25
26<para>For historical reasons, frontend types are named by the type of modulation used in
27transmission. The fontend types are given by fe_type_t type, defined as:</para>
28
29<table pgwide="1" frame="none" id="fe-type">
30<title>Frontend types</title>
31<tgroup cols="3">
32 &cs-def;
33 <thead>
34 <row>
35 <entry>fe_type</entry>
36 <entry>Description</entry>
37 <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry>
38 </row>
39 </thead>
40 <tbody valign="top">
41 <row>
42 <entry id="FE_QPSK"><constant>FE_QPSK</constant></entry>
43 <entry>For DVB-S standard</entry>
44 <entry><constant>SYS_DVBS</constant></entry>
45 </row>
46 <row>
47 <entry id="FE_QAM"><constant>FE_QAM</constant></entry>
48 <entry>For DVB-C annex A standard</entry>
49 <entry><constant>SYS_DVBC_ANNEX_A</constant></entry>
50 </row>
51 <row>
52 <entry id="FE_OFDM"><constant>FE_OFDM</constant></entry>
53 <entry>For DVB-T standard</entry>
54 <entry><constant>SYS_DVBT</constant></entry>
55 </row>
56 <row>
57 <entry id="FE_ATSC"><constant>FE_ATSC</constant></entry>
58 <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry>
59 <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry>
60 </row>
61</tbody></tgroup></table>
62
63<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're
64supported via the new <link linkend="FE_GET_SET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter.
65</para>
66
67<para>The usage of this field is deprecated, as it doesn't report all supported standards, and
68will provide an incomplete information for frontends that support multiple delivery systems.
69Please use <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead.</para>
70</section>
71
72<section id="fe-caps-t">
73<title>frontend capabilities</title>
74
75<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for
76a specific frontend type.</para>
77<programlisting>
78 typedef enum fe_caps {
79 FE_IS_STUPID = 0,
80 FE_CAN_INVERSION_AUTO = 0x1,
81 FE_CAN_FEC_1_2 = 0x2,
82 FE_CAN_FEC_2_3 = 0x4,
83 FE_CAN_FEC_3_4 = 0x8,
84 FE_CAN_FEC_4_5 = 0x10,
85 FE_CAN_FEC_5_6 = 0x20,
86 FE_CAN_FEC_6_7 = 0x40,
87 FE_CAN_FEC_7_8 = 0x80,
88 FE_CAN_FEC_8_9 = 0x100,
89 FE_CAN_FEC_AUTO = 0x200,
90 FE_CAN_QPSK = 0x400,
91 FE_CAN_QAM_16 = 0x800,
92 FE_CAN_QAM_32 = 0x1000,
93 FE_CAN_QAM_64 = 0x2000,
94 FE_CAN_QAM_128 = 0x4000,
95 FE_CAN_QAM_256 = 0x8000,
96 FE_CAN_QAM_AUTO = 0x10000,
97 FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
98 FE_CAN_BANDWIDTH_AUTO = 0x40000,
99 FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
100 FE_CAN_HIERARCHY_AUTO = 0x100000,
101 FE_CAN_8VSB = 0x200000,
102 FE_CAN_16VSB = 0x400000,
103 FE_HAS_EXTENDED_CAPS = 0x800000,
104 FE_CAN_MULTISTREAM = 0x4000000,
105 FE_CAN_TURBO_FEC = 0x8000000,
106 FE_CAN_2G_MODULATION = 0x10000000,
107 FE_NEEDS_BENDING = 0x20000000,
108 FE_CAN_RECOVER = 0x40000000,
109 FE_CAN_MUTE_TS = 0x80000000
110 } fe_caps_t;
111</programlisting>
112</section>
113
114<section id="dvb-frontend-info">
115<title>frontend information</title>
116
117<para>Information about the frontend ca be queried with
118 <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
119
120<programlisting>
121 struct dvb_frontend_info {
122 char name[128];
123 fe_type_t type;
124 uint32_t frequency_min;
125 uint32_t frequency_max;
126 uint32_t frequency_stepsize;
127 uint32_t frequency_tolerance;
128 uint32_t symbol_rate_min;
129 uint32_t symbol_rate_max;
130 uint32_t symbol_rate_tolerance; /&#x22C6; ppm &#x22C6;/
131 uint32_t notifier_delay; /&#x22C6; ms &#x22C6;/
132 fe_caps_t caps;
133 };
134</programlisting>
135</section>
136
137<section id="dvb-diseqc-master-cmd">
138<title>diseqc master command</title>
139
140<para>A message sent from the frontend to DiSEqC capable equipment.</para>
141<programlisting>
142 struct dvb_diseqc_master_cmd {
143 uint8_t msg [6]; /&#x22C6; { framing, address, command, data[3] } &#x22C6;/
144 uint8_t msg_len; /&#x22C6; valid values are 3...6 &#x22C6;/
145 };
146</programlisting>
147</section>
148<section role="subsection" id="dvb-diseqc-slave-reply">
149<title>diseqc slave reply</title>
150
151<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para>
152<programlisting>
153 struct dvb_diseqc_slave_reply {
154 uint8_t msg [4]; /&#x22C6; { framing, data [3] } &#x22C6;/
155 uint8_t msg_len; /&#x22C6; valid values are 0...4, 0 means no msg &#x22C6;/
156 int timeout; /&#x22C6; return from ioctl after timeout ms with &#x22C6;/
157 }; /&#x22C6; errorcode when no message was received &#x22C6;/
158</programlisting>
159</section>
160
161<section id="fe-sec-voltage-t">
162<title>diseqc slave reply</title>
163<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation
164(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched
165consistently to the DiSEqC commands as described in the DiSEqC spec.</para>
166<programlisting>
167 typedef enum fe_sec_voltage {
168 SEC_VOLTAGE_13,
169 SEC_VOLTAGE_18
170 } fe_sec_voltage_t;
171</programlisting>
172</section>
173
174<section id="fe-sec-tone-mode-t">
175<title>SEC continuous tone</title>
176
177<para>The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the
178high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
179be switched consistently to the DiSEqC commands as described in the DiSEqC
180spec.</para>
181<programlisting>
182 typedef enum fe_sec_tone_mode {
183 SEC_TONE_ON,
184 SEC_TONE_OFF
185 } fe_sec_tone_mode_t;
186</programlisting>
187</section>
188
189<section id="fe-sec-mini-cmd-t">
190<title>SEC tone burst</title>
191
192<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select
193between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to
194be switched consistently to the DiSEqC commands as described in the DiSEqC
195spec.</para>
196<programlisting>
197 typedef enum fe_sec_mini_cmd {
198 SEC_MINI_A,
199 SEC_MINI_B
200 } fe_sec_mini_cmd_t;
201</programlisting>
202
203<para></para>
204</section>
205
206<section id="fe-status-t">
207<title>frontend status</title>
208<para>Several functions of the frontend device use the fe_status data type defined
209by</para>
210<programlisting>
211typedef enum fe_status {
212 FE_HAS_SIGNAL = 0x01,
213 FE_HAS_CARRIER = 0x02,
214 FE_HAS_VITERBI = 0x04,
215 FE_HAS_SYNC = 0x08,
216 FE_HAS_LOCK = 0x10,
217 FE_TIMEDOUT = 0x20,
218 FE_REINIT = 0x40,
219} fe_status_t;
220</programlisting>
221<para>to indicate the current state and/or state changes of the frontend hardware:
222</para>
223
224<informaltable><tgroup cols="2"><tbody>
225<row>
226<entry align="char">FE_HAS_SIGNAL</entry>
227<entry align="char">The frontend has found something above the noise level</entry>
228</row><row>
229<entry align="char">FE_HAS_CARRIER</entry>
230<entry align="char">The frontend has found a DVB signal</entry>
231</row><row>
232<entry align="char">FE_HAS_VITERBI</entry>
233<entry align="char">The frontend FEC code is stable</entry>
234</row><row>
235<entry align="char">FE_HAS_SYNC</entry>
236<entry align="char">Syncronization bytes was found</entry>
237</row><row>
238<entry align="char">FE_HAS_LOCK</entry>
239<entry align="char">The DVB were locked and everything is working</entry>
240</row><row>
241<entry align="char">FE_TIMEDOUT</entry>
242<entry align="char">no lock within the last about 2 seconds</entry>
243</row><row>
244<entry align="char">FE_REINIT</entry>
245<entry align="char">The frontend was reinitialized, application is
246recommended to reset DiSEqC, tone and parameters</entry>
247</row>
248</tbody></tgroup></informaltable>
249
250</section>
251
252<section id="dvb-frontend-parameters">
253<title>frontend parameters</title>
254<para>The kind of parameters passed to the frontend device for tuning depend on
255the kind of hardware you are using.</para>
256<para>The struct <constant>dvb_frontend_parameters</constant> uses an
257union with specific per-system parameters. However, as newer delivery systems
258required more data, the structure size weren't enough to fit, and just
259extending its size would break the existing applications. So, those parameters
260were replaced by the usage of <link linkend="FE_GET_SET_PROPERTY">
261<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The
262new API is flexible enough to add new parameters to existing delivery systems,
263and to add newer delivery systems.</para>
264<para>So, newer applications should use <link linkend="FE_GET_SET_PROPERTY">
265<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in
266order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
267DVB-C2, ISDB, etc.</para>
268<para>All kinds of parameters are combined as an union in the FrontendParameters structure:
269<programlisting>
270struct dvb_frontend_parameters {
271 uint32_t frequency; /&#x22C6; (absolute) frequency in Hz for QAM/OFDM &#x22C6;/
272 /&#x22C6; intermediate frequency in kHz for QPSK &#x22C6;/
273 fe_spectral_inversion_t inversion;
274 union {
275 struct dvb_qpsk_parameters qpsk;
276 struct dvb_qam_parameters qam;
277 struct dvb_ofdm_parameters ofdm;
278 struct dvb_vsb_parameters vsb;
279 } u;
280};
281</programlisting></para>
282<para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate
283frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
284the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
285OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz.
286</para>
287
288<section id="dvb-qpsk-parameters">
289<title>QPSK parameters</title>
290<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para>
291<programlisting>
292 struct dvb_qpsk_parameters {
293 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
294 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
295 };
296</programlisting>
297</section>
298<section id="dvb-qam-parameters">
299<title>QAM parameters</title>
300<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para>
301<programlisting>
302 struct dvb_qam_parameters {
303 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
304 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
305 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
306 };
307</programlisting>
308</section>
309<section id="dvb-vsb-parameters">
310<title>VSB parameters</title>
311<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para>
312<programlisting>
313struct dvb_vsb_parameters {
314 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
315};
316</programlisting>
317</section>
318<section id="dvb-ofdm-parameters">
319<title>OFDM parameters</title>
320<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para>
321<programlisting>
322 struct dvb_ofdm_parameters {
323 fe_bandwidth_t bandwidth;
324 fe_code_rate_t code_rate_HP; /&#x22C6; high priority stream code rate &#x22C6;/
325 fe_code_rate_t code_rate_LP; /&#x22C6; low priority stream code rate &#x22C6;/
326 fe_modulation_t constellation; /&#x22C6; modulation type (see above) &#x22C6;/
327 fe_transmit_mode_t transmission_mode;
328 fe_guard_interval_t guard_interval;
329 fe_hierarchy_t hierarchy_information;
330 };
331</programlisting>
332</section>
333<section id="fe-spectral-inversion-t">
334<title>frontend spectral inversion</title>
335<para>The Inversion field can take one of these values:
336</para>
337<programlisting>
338typedef enum fe_spectral_inversion {
339 INVERSION_OFF,
340 INVERSION_ON,
341 INVERSION_AUTO
342} fe_spectral_inversion_t;
343</programlisting>
344<para>It indicates if spectral inversion should be presumed or not. In the automatic setting
345(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
346itself.
347</para>
348</section>
349<section id="fe-code-rate-t">
350<title>frontend code rate</title>
351<para>The possible values for the <constant>fec_inner</constant> field used on
352<link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
353<link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
354</para>
355<programlisting>
356typedef enum fe_code_rate {
357 FEC_NONE = 0,
358 FEC_1_2,
359 FEC_2_3,
360 FEC_3_4,
361 FEC_4_5,
362 FEC_5_6,
363 FEC_6_7,
364 FEC_7_8,
365 FEC_8_9,
366 FEC_AUTO,
367 FEC_3_5,
368 FEC_9_10,
369} fe_code_rate_t;
370</programlisting>
371<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
372detection.
373</para>
374</section>
375<section id="fe-modulation-t">
376<title>frontend modulation type for QAM, OFDM and VSB</title>
377<para>For cable and terrestrial frontends, e. g. for
378<link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>,
379<link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and
380<link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>,
381it needs to specify the quadrature modulation mode which can be one of the following:
382</para>
383<programlisting>
384 typedef enum fe_modulation {
385 QPSK,
386 QAM_16,
387 QAM_32,
388 QAM_64,
389 QAM_128,
390 QAM_256,
391 QAM_AUTO,
392 VSB_8,
393 VSB_16,
394 PSK_8,
395 APSK_16,
396 APSK_32,
397 DQPSK,
398 } fe_modulation_t;
399</programlisting>
400</section>
401<section>
402<title>More OFDM parameters</title>
403<section id="fe-transmit-mode-t">
404<title>Number of carriers per channel</title>
405<programlisting>
406typedef enum fe_transmit_mode {
407 TRANSMISSION_MODE_2K,
408 TRANSMISSION_MODE_8K,
409 TRANSMISSION_MODE_AUTO,
410 TRANSMISSION_MODE_4K,
411 TRANSMISSION_MODE_1K,
412 TRANSMISSION_MODE_16K,
413 TRANSMISSION_MODE_32K,
414 } fe_transmit_mode_t;
415</programlisting>
416</section>
417<section id="fe-bandwidth-t">
418<title>frontend bandwidth</title>
419<programlisting>
420typedef enum fe_bandwidth {
421 BANDWIDTH_8_MHZ,
422 BANDWIDTH_7_MHZ,
423 BANDWIDTH_6_MHZ,
424 BANDWIDTH_AUTO,
425 BANDWIDTH_5_MHZ,
426 BANDWIDTH_10_MHZ,
427 BANDWIDTH_1_712_MHZ,
428} fe_bandwidth_t;
429</programlisting>
430</section>
431<section id="fe-guard-interval-t">
432<title>frontend guard inverval</title>
433<programlisting>
434typedef enum fe_guard_interval {
435 GUARD_INTERVAL_1_32,
436 GUARD_INTERVAL_1_16,
437 GUARD_INTERVAL_1_8,
438 GUARD_INTERVAL_1_4,
439 GUARD_INTERVAL_AUTO,
440 GUARD_INTERVAL_1_128,
441 GUARD_INTERVAL_19_128,
442 GUARD_INTERVAL_19_256,
443} fe_guard_interval_t;
444</programlisting>
445</section>
446<section id="fe-hierarchy-t">
447<title>frontend hierarchy</title>
448<programlisting>
449typedef enum fe_hierarchy {
450 HIERARCHY_NONE,
451 HIERARCHY_1,
452 HIERARCHY_2,
453 HIERARCHY_4,
454 HIERARCHY_AUTO
455 } fe_hierarchy_t;
456</programlisting>
457</section>
458</section>
459
460</section>
461
462<section id="dvb-frontend-event">
463<title>frontend events</title>
464 <programlisting>
465 struct dvb_frontend_event {
466 fe_status_t status;
467 struct dvb_frontend_parameters parameters;
468 };
469</programlisting>
470 </section>
471</section>
472
473
474<section id="frontend_fcalls">
475<title>Frontend Function Calls</title>
476
477<section id="frontend_f_open">
478<title>open()</title>
479<para>DESCRIPTION</para>
480<informaltable><tgroup cols="1"><tbody><row>
481<entry align="char">
482<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
483 for subsequent use. Usually the first thing to do after a successful open is to
484 find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
485<para>The device can be opened in read-only mode, which only allows monitoring of
486 device status and statistics, or read/write mode, which allows any kind of use
487 (e.g. performing tuning operations.)
488</para>
489<para>In a system with multiple front-ends, it is usually the case that multiple devices
490 cannot be open in read/write mode simultaneously. As long as a front-end
491 device is opened in read/write mode, other open() calls in read/write mode will
492 either fail or block, depending on whether non-blocking or blocking mode was
493 specified. A front-end device opened in blocking mode can later be put into
494 non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
495 system call. This is a standard system call, documented in the Linux manual
496 page for fcntl. When an open() call has succeeded, the device will be ready
497 for use in the specified mode. This implies that the corresponding hardware is
498 powered up, and that other front-ends may have been powered down to make
499 that possible.</para>
500</entry>
501 </row></tbody></tgroup></informaltable>
502
503<para>SYNOPSIS</para>
504<informaltable><tgroup cols="1"><tbody><row><entry
505 align="char">
506<para>int open(const char &#x22C6;deviceName, int flags);</para>
507</entry>
508 </row></tbody></tgroup></informaltable>
509<para>PARAMETERS
510</para>
511<informaltable><tgroup cols="2"><tbody><row><entry
512 align="char">
513<para>const char
514 *deviceName</para>
515</entry><entry
516 align="char">
517<para>Name of specific video device.</para>
518</entry>
519 </row><row><entry
520 align="char">
521<para>int flags</para>
522</entry><entry
523 align="char">
524<para>A bit-wise OR of the following flags:</para>
525</entry>
526 </row><row><entry
527 align="char">
528</entry><entry
529 align="char">
530<para>O_RDONLY read-only access</para>
531</entry>
532 </row><row><entry
533 align="char">
534</entry><entry
535 align="char">
536<para>O_RDWR read/write access</para>
537</entry>
538 </row><row><entry
539 align="char">
540</entry><entry
541 align="char">
542<para>O_NONBLOCK open in non-blocking mode</para>
543</entry>
544 </row><row><entry
545 align="char">
546</entry><entry
547 align="char">
548<para>(blocking mode is the default)</para>
549</entry>
550 </row></tbody></tgroup></informaltable>
551<para>RETURN VALUE</para>
552<informaltable><tgroup cols="2"><tbody><row><entry
553 align="char">
554<para>ENODEV</para>
555</entry><entry
556 align="char">
557<para>Device driver not loaded/available.</para>
558</entry>
559 </row><row><entry
560 align="char">
561<para>EINTERNAL</para>
562</entry><entry
563 align="char">
564<para>Internal error.</para>
565</entry>
566 </row><row><entry
567 align="char">
568<para>EBUSY</para>
569</entry><entry
570 align="char">
571<para>Device or resource busy.</para>
572</entry>
573 </row><row><entry
574 align="char">
575<para>EINVAL</para>
576</entry><entry
577 align="char">
578<para>Invalid argument.</para>
579</entry>
580 </row></tbody></tgroup></informaltable>
581</section>
582
583<section id="frontend_f_close">
584<title>close()</title>
585<para>DESCRIPTION
586</para>
587<informaltable><tgroup cols="1"><tbody><row><entry
588 align="char">
589<para>This system call closes a previously opened front-end device. After closing
590 a front-end device, its corresponding hardware might be powered down
591 automatically.</para>
592</entry>
593 </row></tbody></tgroup></informaltable>
594<para>SYNOPSIS
595</para>
596<informaltable><tgroup cols="1"><tbody><row><entry
597 align="char">
598<para>int close(int fd);</para>
599</entry>
600 </row></tbody></tgroup></informaltable>
601<para>PARAMETERS
602</para>
603<informaltable><tgroup cols="2"><tbody><row><entry
604 align="char">
605<para>int fd</para>
606</entry><entry
607 align="char">
608<para>File descriptor returned by a previous call to open().</para>
609</entry>
610 </row></tbody></tgroup></informaltable>
611<para>RETURN VALUE</para>
612<informaltable><tgroup cols="2"><tbody><row><entry
613 align="char">
614<para>EBADF</para>
615</entry><entry
616 align="char">
617<para>fd is not a valid open file descriptor.</para>
618</entry>
619 </row></tbody></tgroup></informaltable>
620</section>
621
622<section id="FE_READ_STATUS">
623<title>FE_READ_STATUS</title>
624<para>DESCRIPTION
625</para>
626<informaltable><tgroup cols="1"><tbody><row><entry
627 align="char">
628<para>This ioctl call returns status information about the front-end. This call only
629 requires read-only access to the device.</para>
630</entry>
631 </row></tbody></tgroup></informaltable>
632<para>SYNOPSIS
633</para>
634<informaltable><tgroup cols="1"><tbody><row><entry
635 align="char">
636<para>int ioctl(int fd, int request = <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>,
637 fe_status_t &#x22C6;status);</para>
638</entry>
639 </row></tbody></tgroup></informaltable>
640<para>PARAMETERS
641</para>
642
643<informaltable><tgroup cols="2"><tbody><row><entry
644 align="char">
645<para>int fd</para>
646</entry><entry
647 align="char">
648<para>File descriptor returned by a previous call to open().</para>
649</entry>
650 </row><row><entry
651 align="char">
652<para>int request</para>
653</entry><entry
654 align="char">
655<para>Equals <link linkend="FE_READ_STATUS">FE_READ_STATUS</link> for this command.</para>
656</entry>
657 </row><row><entry
658 align="char">
659<para>struct fe_status_t
660 *status</para>
661</entry><entry
662 align="char">
663<para>Points to the location where the front-end status word is
664 to be stored.</para>
665</entry>
666 </row></tbody></tgroup></informaltable>
667<para>RETURN VALUE</para>
668<informaltable><tgroup cols="2"><tbody><row><entry
669 align="char">
670<para>EBADF</para>
671</entry><entry
672 align="char">
673<para>fd is not a valid open file descriptor.</para>
674</entry>
675 </row><row><entry
676 align="char">
677<para>EFAULT</para>
678</entry><entry
679 align="char">
680<para>status points to invalid address.</para>
681</entry>
682 </row></tbody></tgroup></informaltable>
683</section>
684
685<section id="FE_READ_BER">
686<title>FE_READ_BER</title>
687<para>DESCRIPTION
688</para>
689<informaltable><tgroup cols="1"><tbody><row><entry
690 align="char">
691<para>This ioctl call returns the bit error rate for the signal currently
692 received/demodulated by the front-end. For this command, read-only access to
693 the device is sufficient.</para>
694</entry>
695 </row></tbody></tgroup></informaltable>
696<para>SYNOPSIS
697</para>
698<informaltable><tgroup cols="1"><tbody><row><entry
699 align="char">
700<para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>,
701 uint32_t &#x22C6;ber);</para>
702</entry>
703 </row></tbody></tgroup></informaltable>
704<para>PARAMETERS
705</para>
706<informaltable><tgroup cols="2"><tbody><row><entry
707 align="char">
708<para>int fd</para>
709</entry><entry
710 align="char">
711<para>File descriptor returned by a previous call to open().</para>
712</entry>
713 </row><row><entry
714 align="char">
715<para>int request</para>
716</entry><entry
717 align="char">
718<para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para>
719</entry>
720 </row><row><entry
721 align="char">
722<para>uint32_t *ber</para>
723</entry><entry
724 align="char">
725<para>The bit error rate is stored into *ber.</para>
726</entry>
727 </row></tbody></tgroup></informaltable>
728
729&return-value-dvb;
730</section>
731
732<section id="FE_READ_SNR">
733<title>FE_READ_SNR</title>
734
735<para>DESCRIPTION
736</para>
737<informaltable><tgroup cols="1"><tbody><row><entry
738 align="char">
739<para>This ioctl call returns the signal-to-noise ratio for the signal currently received
740 by the front-end. For this command, read-only access to the device is sufficient.</para>
741</entry>
742 </row></tbody></tgroup></informaltable>
743<para>SYNOPSIS
744</para>
745<informaltable><tgroup cols="1"><tbody><row><entry
746 align="char">
747<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, int16_t
748 &#x22C6;snr);</para>
749</entry>
750 </row></tbody></tgroup></informaltable>
751<para>PARAMETERS
752</para>
753<informaltable><tgroup cols="2"><tbody><row><entry
754 align="char">
755<para>int fd</para>
756</entry><entry
757 align="char">
758<para>File descriptor returned by a previous call to open().</para>
759</entry>
760 </row><row><entry
761 align="char">
762<para>int request</para>
763</entry><entry
764 align="char">
765<para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para>
766</entry>
767 </row><row><entry
768 align="char">
769<para>int16_t *snr</para>
770</entry><entry
771 align="char">
772<para>The signal-to-noise ratio is stored into *snr.</para>
773</entry>
774 </row></tbody></tgroup></informaltable>
775
776&return-value-dvb;
777</section>
778
779<section id="FE_READ_SIGNAL_STRENGTH">
780<title>FE_READ_SIGNAL_STRENGTH</title>
781<para>DESCRIPTION
782</para>
783<informaltable><tgroup cols="1"><tbody><row><entry
784 align="char">
785<para>This ioctl call returns the signal strength value for the signal currently received
786 by the front-end. For this command, read-only access to the device is sufficient.</para>
787</entry>
788 </row></tbody></tgroup></informaltable>
789<para>SYNOPSIS
790</para>
791<informaltable><tgroup cols="1"><tbody><row><entry
792 align="char">
793<para>int ioctl( int fd, int request =
794 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, int16_t &#x22C6;strength);</para>
795</entry>
796 </row></tbody></tgroup></informaltable>
797
798<para>PARAMETERS
799</para>
800<informaltable><tgroup cols="2"><tbody><row><entry
801 align="char">
802<para>int fd</para>
803</entry><entry
804 align="char">
805<para>File descriptor returned by a previous call to open().</para>
806</entry>
807 </row><row><entry
808 align="char">
809<para>int request</para>
810</entry><entry
811 align="char">
812<para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this
813 command.</para>
814</entry>
815 </row><row><entry
816 align="char">
817<para>int16_t *strength</para>
818</entry><entry
819 align="char">
820<para>The signal strength value is stored into *strength.</para>
821</entry>
822 </row></tbody></tgroup></informaltable>
823
824&return-value-dvb;
825</section>
826
827<section id="FE_READ_UNCORRECTED_BLOCKS">
828<title>FE_READ_UNCORRECTED_BLOCKS</title>
829<para>DESCRIPTION
830</para>
831<informaltable><tgroup cols="1"><tbody><row><entry
832 align="char">
833<para>This ioctl call returns the number of uncorrected blocks detected by the device
834 driver during its lifetime. For meaningful measurements, the increment in block
835 count during a specific time interval should be calculated. For this command,
836 read-only access to the device is sufficient.</para>
837</entry>
838 </row><row><entry
839 align="char">
840<para>Note that the counter will wrap to zero after its maximum count has been
841 reached.</para>
842</entry>
843 </row></tbody></tgroup></informaltable>
844<para>SYNOPSIS
845</para>
846<informaltable><tgroup cols="1"><tbody><row><entry
847 align="char">
848<para>int ioctl( int fd, int request =
849 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t &#x22C6;ublocks);</para>
850</entry>
851 </row></tbody></tgroup></informaltable>
852<para>PARAMETERS
853</para>
854<informaltable><tgroup cols="2"><tbody><row><entry
855 align="char">
856<para>int fd</para>
857</entry><entry
858 align="char">
859<para>File descriptor returned by a previous call to open().</para>
860</entry>
861 </row><row><entry
862 align="char">
863<para>int request</para>
864</entry><entry
865 align="char">
866<para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this
867 command.</para>
868</entry>
869 </row><row><entry
870 align="char">
871<para>uint32_t *ublocks</para>
872</entry><entry
873 align="char">
874<para>The total number of uncorrected blocks seen by the driver
875 so far.</para>
876</entry>
877 </row></tbody></tgroup></informaltable>
878
879&return-value-dvb;
880</section>
881
882<section id="FE_SET_FRONTEND">
883<title>FE_SET_FRONTEND</title>
884<para>DESCRIPTION
885</para>
886<informaltable><tgroup cols="1"><tbody><row><entry
887 align="char">
888<para>This ioctl call starts a tuning operation using specified parameters. The result
889 of this call will be successful if the parameters were valid and the tuning could
890 be initiated. The result of the tuning operation in itself, however, will arrive
891 asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and
892 FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before
893 the previous one was completed, the previous operation will be aborted in favor
894 of the new one. This command requires read/write access to the device.</para>
895</entry>
896 </row></tbody></tgroup></informaltable>
897
898<para>SYNOPSIS
899</para>
900<informaltable><tgroup cols="1"><tbody><row><entry
901 align="char">
902<para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>,
903 struct dvb_frontend_parameters &#x22C6;p);</para>
904</entry>
905 </row></tbody></tgroup></informaltable>
906<para>PARAMETERS
907</para>
908<informaltable><tgroup cols="2"><tbody><row><entry
909 align="char">
910<para>int fd</para>
911</entry><entry
912 align="char">
913<para>File descriptor returned by a previous call to open().</para>
914</entry>
915 </row><row><entry
916 align="char">
917<para>int request</para>
918</entry><entry
919 align="char">
920<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
921</entry>
922 </row><row><entry
923 align="char">
924<para>struct
925 dvb_frontend_parameters
926 *p</para>
927</entry><entry
928 align="char">
929<para>Points to parameters for tuning operation.</para>
930</entry>
931 </row></tbody></tgroup></informaltable>
932
933&return-value-dvb;
934<informaltable><tgroup cols="2"><tbody><row><entry
935 align="char">
936<para>EINVAL</para>
937</entry><entry
938 align="char">
939<para>Maximum supported symbol rate reached.</para>
940</entry>
941</row></tbody></tgroup></informaltable>
942</section>
943
944<section id="FE_GET_FRONTEND">
945<title>FE_GET_FRONTEND</title>
946<para>DESCRIPTION
947</para>
948<informaltable><tgroup cols="1"><tbody><row><entry
949 align="char">
950<para>This ioctl call queries the currently effective frontend parameters. For this
951 command, read-only access to the device is sufficient.</para>
952</entry>
953 </row></tbody></tgroup></informaltable>
954
955<para>SYNOPSIS
956</para>
957<informaltable><tgroup cols="1"><tbody><row><entry
958 align="char">
959<para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>,
960 struct dvb_frontend_parameters &#x22C6;p);</para>
961</entry>
962 </row></tbody></tgroup></informaltable>
963
964<para>PARAMETERS
965</para>
966<informaltable><tgroup cols="2"><tbody><row><entry
967 align="char">
968<para>int fd</para>
969</entry><entry
970 align="char">
971<para>File descriptor returned by a previous call to open().</para>
972</entry>
973 </row><row><entry
974 align="char">
975<para>int request</para>
976</entry><entry
977 align="char">
978<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
979</entry>
980 </row><row><entry
981 align="char">
982<para>struct
983 dvb_frontend_parameters
984 *p</para>
985</entry><entry
986 align="char">
987<para>Points to parameters for tuning operation.</para>
988</entry>
989 </row></tbody></tgroup></informaltable>
990
991&return-value-dvb;
992<informaltable><tgroup cols="2"><tbody><row><entry
993 align="char">
994<para>EINVAL</para>
995</entry><entry
996 align="char">
997<para>Maximum supported symbol rate reached.</para>
998</entry>
999 </row></tbody></tgroup></informaltable>
1000
1001</section>
1002
1003<section id="FE_GET_EVENT">
1004<title>FE_GET_EVENT</title>
1005<para>DESCRIPTION
1006</para>
1007<informaltable><tgroup cols="1"><tbody><row><entry
1008 align="char">
1009<para>This ioctl call returns a frontend event if available. If an event is not
1010 available, the behavior depends on whether the device is in blocking or
1011 non-blocking mode. In the latter case, the call fails immediately with errno
1012 set to EWOULDBLOCK. In the former case, the call blocks until an event
1013 becomes available.</para>
1014</entry>
1015 </row><row><entry
1016 align="char">
1017<para>The standard Linux poll() and/or select() system calls can be used with the
1018 device file descriptor to watch for new events. For select(), the file descriptor
1019 should be included in the exceptfds argument, and for poll(), POLLPRI should
1020 be specified as the wake-up condition. Since the event queue allocated is
1021 rather small (room for 8 events), the queue must be serviced regularly to avoid
1022 overflow. If an overflow happens, the oldest event is discarded from the queue,
1023 and an error (EOVERFLOW) occurs the next time the queue is read. After
1024 reporting the error condition in this fashion, subsequent
1025 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link>
1026 calls will return events from the queue as usual.</para>
1027</entry>
1028 </row><row><entry
1029 align="char">
1030<para>For the sake of implementation simplicity, this command requires read/write
1031 access to the device.</para>
1032</entry>
1033 </row></tbody></tgroup></informaltable>
1034
1035<para>SYNOPSIS
1036</para>
1037<informaltable><tgroup cols="1"><tbody><row><entry
1038 align="char">
1039<para>int ioctl(int fd, int request = QPSK_GET_EVENT,
1040 struct dvb_frontend_event &#x22C6;ev);</para>
1041</entry>
1042 </row></tbody></tgroup></informaltable>
1043
1044<para>PARAMETERS
1045</para>
1046<informaltable><tgroup cols="2"><tbody><row><entry
1047 align="char">
1048<para>int fd</para>
1049</entry><entry
1050 align="char">
1051<para>File descriptor returned by a previous call to open().</para>
1052</entry>
1053 </row><row><entry
1054 align="char">
1055<para>int request</para>
1056</entry><entry
1057 align="char">
1058<para>Equals <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para>
1059</entry>
1060 </row><row><entry
1061 align="char">
1062<para>struct
1063 dvb_frontend_event
1064 *ev</para>
1065</entry><entry
1066 align="char">
1067<para>Points to the location where the event,</para>
1068</entry>
1069 </row><row><entry
1070 align="char">
1071</entry><entry
1072 align="char">
1073<para>if any, is to be stored.</para>
1074</entry>
1075 </row></tbody></tgroup></informaltable>
1076
1077&return-value-dvb;
1078<informaltable><tgroup cols="2"><tbody><row><entry
1079 align="char">
1080<para>EWOULDBLOCK</para>
1081</entry><entry
1082 align="char">
1083<para>There is no event pending, and the device is in
1084 non-blocking mode.</para>
1085</entry>
1086 </row><row><entry
1087 align="char">
1088<para>EOVERFLOW</para>
1089</entry><entry
1090 align="char">
1091<para>Overflow in event queue - one or more events were lost.</para>
1092</entry>
1093</row></tbody></tgroup></informaltable>
1094</section>
1095
1096<section id="FE_GET_INFO">
1097<title>FE_GET_INFO</title>
1098<para>DESCRIPTION
1099</para>
1100<informaltable><tgroup cols="1"><tbody><row><entry
1101 align="char">
1102<para>This ioctl call returns information about the front-end. This call only requires
1103 read-only access to the device.</para>
1104</entry>
1105 </row></tbody></tgroup></informaltable>
1106<para>SYNOPSIS
1107</para>
1108
1109<informaltable><tgroup cols="1"><tbody><row><entry
1110 align="char">
1111<para> int ioctl(int fd, int request = <link linkend="FE_GET_INFO">FE_GET_INFO</link>, struct
1112 dvb_frontend_info &#x22C6;info);</para>
1113</entry>
1114 </row></tbody></tgroup></informaltable>
1115<para>PARAMETERS
1116</para>
1117
1118<informaltable><tgroup cols="2"><tbody><row><entry
1119 align="char">
1120<para>int fd</para>
1121</entry><entry
1122 align="char">
1123<para>File descriptor returned by a previous call to open().</para>
1124</entry>
1125 </row><row><entry
1126 align="char">
1127<para>int request</para>
1128</entry><entry
1129 align="char">
1130<para>Equals <link linkend="FE_GET_INFO">FE_GET_INFO</link> for this command.</para>
1131</entry>
1132 </row><row><entry
1133 align="char">
1134<para>struct
1135 dvb_frontend_info
1136 *info</para>
1137</entry><entry
1138 align="char">
1139<para>Points to the location where the front-end information is
1140 to be stored.</para>
1141</entry>
1142 </row></tbody></tgroup></informaltable>
1143&return-value-dvb;
1144</section>
1145
1146<section id="FE_DISEQC_RESET_OVERLOAD">
1147<title>FE_DISEQC_RESET_OVERLOAD</title>
1148<para>DESCRIPTION
1149</para>
1150<informaltable><tgroup cols="1"><tbody><row><entry
1151 align="char">
1152<para>If the bus has been automatically powered off due to power overload, this ioctl
1153 call restores the power to the bus. The call requires read/write access to the
1154 device. This call has no effect if the device is manually powered off. Not all
1155 DVB adapters support this ioctl.</para>
1156</entry>
1157 </row></tbody></tgroup></informaltable>
1158
1159<para>SYNOPSIS
1160</para>
1161<informaltable><tgroup cols="1"><tbody><row><entry
1162 align="char">
1163<para>int ioctl(int fd, int request =
1164 <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</para>
1165</entry>
1166 </row></tbody></tgroup></informaltable>
1167<para>PARAMETERS
1168</para>
1169<informaltable><tgroup cols="2"><tbody><row><entry
1170 align="char">
1171<para>int fd</para>
1172</entry><entry
1173 align="char">
1174<para>File descriptor returned by a previous call to open().</para>
1175</entry>
1176 </row><row><entry
1177 align="char">
1178<para>int request</para>
1179</entry><entry
1180 align="char">
1181<para>Equals <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this
1182 command.</para>
1183</entry>
1184 </row></tbody></tgroup></informaltable>
1185
1186&return-value-dvb;
1187</section>
1188
1189<section id="FE_DISEQC_SEND_MASTER_CMD">
1190<title>FE_DISEQC_SEND_MASTER_CMD</title>
1191<para>DESCRIPTION
1192</para>
1193<informaltable><tgroup cols="1"><tbody><row><entry
1194 align="char">
1195<para>This ioctl call is used to send a a DiSEqC command.</para>
1196</entry>
1197 </row></tbody></tgroup></informaltable>
1198<para>SYNOPSIS
1199</para>
1200<informaltable><tgroup cols="1"><tbody><row><entry
1201 align="char">
1202<para>int ioctl(int fd, int request =
1203 <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, struct
1204 dvb_diseqc_master_cmd &#x22C6;cmd);</para>
1205</entry>
1206 </row></tbody></tgroup></informaltable>
1207
1208<para>PARAMETERS
1209</para>
1210<informaltable><tgroup cols="2"><tbody><row><entry
1211 align="char">
1212<para>int fd</para>
1213</entry><entry
1214 align="char">
1215<para>File descriptor returned by a previous call to open().</para>
1216</entry>
1217 </row><row><entry
1218 align="char">
1219<para>int request</para>
1220</entry><entry
1221 align="char">
1222<para>Equals <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> for this
1223 command.</para>
1224</entry>
1225 </row><row><entry
1226 align="char">
1227<para>struct
1228 dvb_diseqc_master_cmd
1229 *cmd</para>
1230</entry><entry
1231 align="char">
1232<para>Pointer to the command to be transmitted.</para>
1233</entry>
1234 </row></tbody></tgroup></informaltable>
1235
1236&return-value-dvb;
1237</section>
1238
1239<section id="FE_DISEQC_RECV_SLAVE_REPLY">
1240<title>FE_DISEQC_RECV_SLAVE_REPLY</title>
1241<para>DESCRIPTION
1242</para>
1243<informaltable><tgroup cols="1"><tbody><row><entry
1244 align="char">
1245<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para>
1246</entry>
1247 </row></tbody></tgroup></informaltable>
1248
1249<para>SYNOPSIS
1250</para>
1251<informaltable><tgroup cols="1"><tbody><row><entry
1252 align="char">
1253<para>int ioctl(int fd, int request =
1254 <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, struct
1255 dvb_diseqc_slave_reply &#x22C6;reply);</para>
1256</entry>
1257 </row></tbody></tgroup></informaltable>
1258
1259<para>PARAMETERS
1260</para>
1261<informaltable><tgroup cols="2"><tbody><row><entry
1262 align="char">
1263<para>int fd</para>
1264</entry><entry
1265 align="char">
1266<para>File descriptor returned by a previous call to open().</para>
1267</entry>
1268 </row><row><entry
1269 align="char">
1270<para>int request</para>
1271</entry><entry
1272 align="char">
1273<para>Equals <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> for this
1274 command.</para>
1275</entry>
1276 </row><row><entry
1277 align="char">
1278<para>struct
1279 dvb_diseqc_slave_reply
1280 *reply</para>
1281</entry><entry
1282 align="char">
1283<para>Pointer to the command to be received.</para>
1284</entry>
1285 </row></tbody></tgroup></informaltable>
1286&return-value-dvb;
1287</section>
1288
1289<section id="FE_DISEQC_SEND_BURST">
1290<title>FE_DISEQC_SEND_BURST</title>
1291<para>DESCRIPTION
1292</para>
1293<informaltable><tgroup cols="1"><tbody><row><entry
1294 align="char">
1295<para>This ioctl call is used to send a 22KHz tone burst.</para>
1296</entry>
1297 </row></tbody></tgroup></informaltable>
1298
1299<para>SYNOPSIS
1300</para>
1301<informaltable><tgroup cols="1"><tbody><row><entry
1302 align="char">
1303<para>int ioctl(int fd, int request =
1304 <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link>, fe_sec_mini_cmd_t burst);</para>
1305</entry>
1306 </row></tbody></tgroup></informaltable>
1307
1308<para>PARAMETERS
1309</para>
1310<informaltable><tgroup cols="2"><tbody><row><entry
1311 align="char">
1312<para>int fd</para>
1313</entry><entry
1314 align="char">
1315<para>File descriptor returned by a previous call to open().</para>
1316</entry>
1317 </row><row><entry
1318 align="char">
1319<para>int request</para>
1320</entry><entry
1321 align="char">
1322<para>Equals <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link> for this command.</para>
1323</entry>
1324 </row><row><entry
1325 align="char">
1326<para>fe_sec_mini_cmd_t
1327 burst</para>
1328</entry><entry
1329 align="char">
1330<para>burst A or B.</para>
1331</entry>
1332 </row></tbody></tgroup></informaltable>
1333
1334&return-value-dvb;
1335</section>
1336
1337<section id="FE_SET_TONE">
1338<title>FE_SET_TONE</title>
1339<para>DESCRIPTION
1340</para>
1341<informaltable><tgroup cols="1"><tbody><row><entry
1342 align="char">
1343<para>This call is used to set the generation of the continuous 22kHz tone. This call
1344 requires read/write permissions.</para>
1345</entry>
1346 </row></tbody></tgroup></informaltable>
1347<para>SYNOPSIS
1348</para>
1349<informaltable><tgroup cols="1"><tbody><row><entry
1350 align="char">
1351<para>int ioctl(int fd, int request = <link linkend="FE_SET_TONE">FE_SET_TONE</link>,
1352 fe_sec_tone_mode_t tone);</para>
1353</entry>
1354 </row></tbody></tgroup></informaltable>
1355<para>PARAMETERS
1356</para>
1357<informaltable><tgroup cols="2"><tbody><row><entry
1358 align="char">
1359<para>int fd</para>
1360</entry><entry
1361 align="char">
1362<para>File descriptor returned by a previous call to open().</para>
1363</entry>
1364 </row><row><entry
1365 align="char">
1366<para>int request</para>
1367</entry><entry
1368 align="char">
1369<para>Equals <link linkend="FE_SET_TONE">FE_SET_TONE</link> for this command.</para>
1370</entry>
1371 </row><row><entry
1372 align="char">
1373<para>fe_sec_tone_mode_t
1374 tone</para>
1375</entry><entry
1376 align="char">
1377<para>The requested tone generation mode (on/off).</para>
1378</entry>
1379 </row></tbody></tgroup></informaltable>
1380&return-value-dvb;
1381</section>
1382
1383<section id="FE_SET_VOLTAGE">
1384<title>FE_SET_VOLTAGE</title>
1385<para>DESCRIPTION
1386</para>
1387<informaltable><tgroup cols="1"><tbody><row><entry
1388 align="char">
1389<para>This call is used to set the bus voltage. This call requires read/write
1390 permissions.</para>
1391</entry>
1392 </row></tbody></tgroup></informaltable>
1393<para>SYNOPSIS
1394</para>
1395<informaltable><tgroup cols="1"><tbody><row><entry
1396 align="char">
1397<para>int ioctl(int fd, int request = <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link>,
1398 fe_sec_voltage_t voltage);</para>
1399</entry>
1400 </row></tbody></tgroup></informaltable>
1401
1402<para>PARAMETERS
1403</para>
1404<informaltable><tgroup cols="2"><tbody><row><entry
1405 align="char">
1406<para>int fd</para>
1407</entry><entry
1408 align="char">
1409<para>File descriptor returned by a previous call to open().</para>
1410</entry>
1411 </row><row><entry
1412 align="char">
1413<para>int request</para>
1414</entry><entry
1415 align="char">
1416<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1417</entry>
1418 </row><row><entry
1419 align="char">
1420<para>fe_sec_voltage_t
1421 voltage</para>
1422</entry><entry
1423 align="char">
1424<para>The requested bus voltage.</para>
1425</entry>
1426 </row></tbody></tgroup></informaltable>
1427
1428&return-value-dvb;
1429</section>
1430
1431<section id="FE_ENABLE_HIGH_LNB_VOLTAGE">
1432<title>FE_ENABLE_HIGH_LNB_VOLTAGE</title>
1433<para>DESCRIPTION
1434</para>
1435<informaltable><tgroup cols="1"><tbody><row><entry
1436 align="char">
1437<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate
1438 for long cables). This call requires read/write permissions. Not all DVB
1439 adapters support this ioctl.</para>
1440</entry>
1441 </row></tbody></tgroup></informaltable>
1442
1443<para>SYNOPSIS
1444</para>
1445<informaltable><tgroup cols="1"><tbody><row><entry
1446 align="char">
1447<para>int ioctl(int fd, int request =
1448 <link linkend="FE_ENABLE_HIGH_LNB_VOLTAGE">FE_ENABLE_HIGH_LNB_VOLTAGE</link>, int high);</para>
1449</entry>
1450 </row></tbody></tgroup></informaltable>
1451
1452<para>PARAMETERS
1453</para>
1454<informaltable><tgroup cols="2"><tbody><row><entry
1455 align="char">
1456<para>int fd</para>
1457</entry><entry
1458 align="char">
1459<para>File descriptor returned by a previous call to open().</para>
1460</entry>
1461 </row><row><entry
1462 align="char">
1463<para>int request</para>
1464</entry><entry
1465 align="char">
1466<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1467</entry>
1468 </row><row><entry
1469 align="char">
1470<para>int high</para>
1471</entry><entry
1472 align="char">
1473<para>The requested bus voltage.</para>
1474</entry>
1475 </row></tbody></tgroup></informaltable>
1476
1477&return-value-dvb;
1478</section>
1479
1480<section id="FE_SET_FRONTEND_TUNE_MODE">
1481<title>FE_SET_FRONTEND_TUNE_MODE</title>
1482<para>DESCRIPTION</para>
1483<informaltable><tgroup cols="1"><tbody><row>
1484<entry align="char">
1485<para>Allow setting tuner mode flags to the frontend.</para>
1486</entry>
1487</row></tbody></tgroup></informaltable>
1488
1489<para>SYNOPSIS</para>
1490<informaltable><tgroup cols="1"><tbody><row>
1491<entry align="char">
1492<para>int ioctl(int fd, int request =
1493<link linkend="FE_SET_FRONTEND_TUNE_MODE">FE_SET_FRONTEND_TUNE_MODE</link>, unsigned int flags);</para>
1494</entry>
1495</row></tbody></tgroup></informaltable>
1496
1497<para>PARAMETERS</para>
1498<informaltable><tgroup cols="2"><tbody><row>
1499<entry align="char">
1500 <para>unsigned int flags</para>
1501</entry>
1502<entry align="char">
1503<para>
1504FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "normal" tuning behaviour. Additionally, there will be no automatic monitoring of the lock status, and hence no frontend events will be generated. If a frontend device is closed, this flag will be automatically turned off when the device is reopened read-write.
1505</para>
1506</entry>
1507 </row></tbody></tgroup></informaltable>
1508
1509&return-value-dvb;
1510</section>
1511
1512<section id="FE_DISHNETWORK_SEND_LEGACY_CMD">
1513 <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title>
1514<para>DESCRIPTION</para>
1515<informaltable><tgroup cols="1"><tbody><row>
1516<entry align="char">
1517<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para>
1518<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para>
1519<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para>
1520</entry>
1521</row></tbody></tgroup></informaltable>
1522
1523<para>SYNOPSIS</para>
1524<informaltable><tgroup cols="1"><tbody><row>
1525<entry align="char">
1526<para>int ioctl(int fd, int request =
1527 <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para>
1528</entry>
1529</row></tbody></tgroup></informaltable>
1530
1531<para>PARAMETERS</para>
1532<informaltable><tgroup cols="2"><tbody><row>
1533<entry align="char">
1534 <para>unsigned long cmd</para>
1535</entry>
1536<entry align="char">
1537<para>
1538sends the specified raw cmd to the dish via DISEqC.
1539</para>
1540</entry>
1541 </row></tbody></tgroup></informaltable>
1542
1543&return-value-dvb;
1544</section>
1545
1546</section>
1547
1548&sub-dvbproperty;
diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml
new file mode 100644
index 00000000000..2048b53d19b
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/intro.xml
@@ -0,0 +1,212 @@
1<title>Introduction</title>
2
3<section id="requisites">
4<title>What you need to know</title>
5
6<para>The reader of this document is required to have some knowledge in
7the area of digital video broadcasting (DVB) and should be familiar with
8part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
9you should know what a program/transport stream (PS/TS) is and what is
10meant by a packetized elementary stream (PES) or an I-frame.</para>
11
12<para>Various DVB standards documents are available from
13<ulink url="http://www.dvb.org" /> and/or
14<ulink url="http://www.etsi.org" />.</para>
15
16<para>It is also necessary to know how to access unix/linux devices and
17how to use ioctl calls. This also includes the knowledge of C or C++.
18</para>
19</section>
20
21<section id="history">
22<title>History</title>
23
24<para>The first API for DVB cards we used at Convergence in late 1999
25was an extension of the Video4Linux API which was primarily developed
26for frame grabber cards. As such it was not really well suited to be
27used for DVB cards and their new features like recording MPEG streams
28and filtering several section and PES data streams at the same time.
29</para>
30
31<para>In early 2000, we were approached by Nokia with a proposal for a
32new standard Linux DVB API. As a commitment to the development of
33terminals based on open standards, Nokia and Convergence made it
34available to all Linux developers and published it on
35<ulink url="http://www.linuxtv.org/" /> in September 2000.
36Convergence is the maintainer of the Linux DVB API. Together with the
37LinuxTV community (i.e. you, the reader of this document), the Linux DVB
38API will be constantly reviewed and improved. With the Linux driver for
39the Siemens/Hauppauge DVB PCI card Convergence provides a first
40implementation of the Linux DVB API.</para>
41</section>
42
43<section id="overview">
44<title>Overview</title>
45
46<figure id="stb_components">
47<title>Components of a DVB card/STB</title>
48<mediaobject>
49<imageobject>
50<imagedata fileref="dvbstb.pdf" format="PS" />
51</imageobject>
52<imageobject>
53<imagedata fileref="dvbstb.png" format="PNG" />
54</imageobject>
55</mediaobject>
56</figure>
57
58<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
59following main hardware components: </para>
60
61<itemizedlist>
62 <listitem>
63
64<para>Frontend consisting of tuner and DVB demodulator</para>
65
66<para>Here the raw signal reaches the DVB hardware from a satellite dish
67or antenna or directly from cable. The frontend down-converts and
68demodulates this signal into an MPEG transport stream (TS). In case of a
69satellite frontend, this includes a facility for satellite equipment
70control (SEC), which allows control of LNB polarization, multi feed
71switches or dish rotors.</para>
72
73</listitem>
74 <listitem>
75
76<para>Conditional Access (CA) hardware like CI adapters and smartcard slots
77</para>
78
79<para>The complete TS is passed through the CA hardware. Programs to
80which the user has access (controlled by the smart card) are decoded in
81real time and re-inserted into the TS.</para>
82
83</listitem>
84 <listitem>
85 <para>Demultiplexer which filters the incoming DVB stream</para>
86
87<para>The demultiplexer splits the TS into its components like audio and
88video streams. Besides usually several of such audio and video streams
89it also contains data streams with information about the programs
90offered in this or other streams of the same provider.</para>
91
92</listitem>
93<listitem>
94
95<para>MPEG2 audio and video decoder</para>
96
97<para>The main targets of the demultiplexer are the MPEG2 audio and
98video decoders. After decoding they pass on the uncompressed audio and
99video to the computer screen or (through a PAL/NTSC encoder) to a TV
100set.</para>
101
102
103</listitem>
104</itemizedlist>
105
106<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
107between those components.</para>
108
109<para>On a DVB PCI card not all of these have to be present since some
110functionality can be provided by the main CPU of the PC (e.g. MPEG
111picture and sound decoding) or is not needed (e.g. for data-only uses
112like &#8220;internet over satellite&#8221;). Also not every card or STB
113provides conditional access hardware.</para>
114
115</section>
116
117<section id="dvb_devices">
118<title>Linux DVB Devices</title>
119
120<para>The Linux DVB API lets you control these hardware components
121through currently six Unix-style character devices for video, audio,
122frontend, demux, CA and IP-over-DVB networking. The video and audio
123devices control the MPEG2 decoder hardware, the frontend device the
124tuner and the DVB demodulator. The demux device gives you control over
125the PES and section filters of the hardware. If the hardware does not
126support filtering these filters can be implemented in software. Finally,
127the CA device controls all the conditional access capabilities of the
128hardware. It can depend on the individual security requirements of the
129platform, if and how many of the CA functions are made available to the
130application through this device.</para>
131
132<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
133tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
134are called:</para>
135
136<itemizedlist>
137<listitem>
138
139<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para>
140</listitem>
141<listitem>
142<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para>
143</listitem>
144<listitem>
145<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para>
146</listitem>
147 <listitem>
148
149<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para>
150</listitem>
151 <listitem>
152
153<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para>
154</listitem>
155 <listitem>
156
157<para><emphasis role="tt">/dev/dvb/adapterN/dvrM</emphasis>,</para>
158</listitem>
159 <listitem>
160
161<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist>
162
163<para>where N enumerates the DVB PCI cards in a system starting
164from&#x00A0;0, and M enumerates the devices of each type within each
165adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
166role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
167of these devices. The naming scheme for the devices is the same wheter
168devfs is used or not.</para>
169
170<para>More details about the data structures and function calls of all
171the devices are described in the following chapters.</para>
172
173</section>
174
175<section id="include_files">
176<title>API include files</title>
177
178<para>For each of the DVB devices a corresponding include file exists.
179The DVB API include files should be included in application sources with
180a partial path like:</para>
181
182<programlisting>
183 #include &#x003C;linux/dvb/audio.h&#x003E;
184</programlisting>
185<programlisting>
186 #include &#x003C;linux/dvb/ca.h&#x003E;
187</programlisting>
188<programlisting>
189 #include &#x003C;linux/dvb/dmx.h&#x003E;
190</programlisting>
191<programlisting>
192 #include &#x003C;linux/dvb/frontend.h&#x003E;
193</programlisting>
194<programlisting>
195 #include &#x003C;linux/dvb/net.h&#x003E;
196</programlisting>
197<programlisting>
198 #include &#x003C;linux/dvb/osd.h&#x003E;
199</programlisting>
200<programlisting>
201 #include &#x003C;linux/dvb/video.h&#x003E;
202</programlisting>
203
204<para>To enable applications to support different API version, an
205additional include file <emphasis
206role="tt">linux/dvb/version.h</emphasis> exists, which defines the
207constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
208describes <emphasis role="tt">DVB_API_VERSION 5.8</emphasis>.
209</para>
210
211</section>
212
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
new file mode 100644
index 00000000000..6c11ec52cbe
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -0,0 +1,2309 @@
1<title>Kernel Demux API</title>
2<para>The kernel demux API defines a driver-internal interface for registering low-level,
3hardware specific driver to a hardware independent demux layer. It is only of interest for
4DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in
5<emphasis role="tt">drivers/media/dvb-core</emphasis>.
6</para>
7<para>Maintainer note: This section must be reviewed. It is probably out of date.
8</para>
9
10<section id="kernel_demux_data_types">
11<title>Kernel Demux Data Types</title>
12
13
14<section id="dmx_success_t">
15<title>dmx_success_t</title>
16 <programlisting>
17 typedef enum {
18 DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
19 DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
20 DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
21 DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
22 DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
23 DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
24 DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
25 } dmx_success_t;
26</programlisting>
27
28</section>
29<section id="ts_filter_types">
30<title>TS filter types</title>
31 <programlisting>
32 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
33 /&#x22C6; TS packet reception &#x22C6;/
34 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
35
36 /&#x22C6; TS filter type for set_type() &#x22C6;/
37
38 #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
39 #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
40 payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
41 #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
42</programlisting>
43
44</section>
45<section id="dmx_ts_pes_t">
46<title>dmx_ts_pes_t</title>
47<para>The structure
48</para>
49<programlisting>
50 typedef enum
51 {
52 DMX_TS_PES_AUDIO, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
53 DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
54 DMX_TS_PES_TELETEXT,
55 DMX_TS_PES_SUBTITLE,
56 DMX_TS_PES_PCR,
57 DMX_TS_PES_OTHER,
58 } dmx_ts_pes_t;
59</programlisting>
60<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
61should be kept identical) to the types in the demux device.
62</para>
63<programlisting>
64 struct dmx_ts_feed_s {
65 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
66 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
67 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
68 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
69 __u16 pid,
70 size_t callback_length,
71 size_t circular_buffer_size,
72 int descramble,
73 struct timespec timeout);
74 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
75 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
76 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
77 int type,
78 dmx_ts_pes_t pes_type);
79 };
80
81 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
82</programlisting>
83 <programlisting>
84 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
85 /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
86 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
87
88 typedef struct dmx_pes_filter_s {
89 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
90 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
91 } dmx_pes_filter_t;
92</programlisting>
93 <programlisting>
94 typedef struct dmx_pes_feed_s {
95 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
96 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
97 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
98 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
99 __u16 pid,
100 size_t circular_buffer_size,
101 int descramble,
102 struct timespec timeout);
103 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
104 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
105 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
106 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
107 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
108 dmx_pes_filter_t&#x22C6; filter);
109 } dmx_pes_feed_t;
110</programlisting>
111 <programlisting>
112 typedef struct {
113 __u8 filter_value [DMX_MAX_FILTER_SIZE];
114 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
115 struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
116 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
117 } dmx_section_filter_t;
118</programlisting>
119 <programlisting>
120 struct dmx_section_feed_s {
121 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
122 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
123 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
124 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
125 __u16 pid,
126 size_t circular_buffer_size,
127 int descramble,
128 int check_crc);
129 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
130 dmx_section_filter_t&#x22C6;&#x22C6; filter);
131 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
132 dmx_section_filter_t&#x22C6; filter);
133 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
134 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
135 };
136 typedef struct dmx_section_feed_s dmx_section_feed_t;
137
138 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
139 /&#x22C6; Callback functions &#x22C6;/
140 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
141
142 typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
143 size_t buffer1_length,
144 __u8 &#x22C6; buffer2,
145 size_t buffer2_length,
146 dmx_ts_feed_t&#x22C6; source,
147 dmx_success_t success);
148
149 typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
150 size_t buffer1_len,
151 __u8 &#x22C6; buffer2,
152 size_t buffer2_len,
153 dmx_section_filter_t &#x22C6; source,
154 dmx_success_t success);
155
156 typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
157 size_t buffer1_len,
158 __u8 &#x22C6; buffer2,
159 size_t buffer2_len,
160 dmx_pes_filter_t&#x22C6; source,
161 dmx_success_t success);
162
163 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
164 /&#x22C6; DVB Front-End &#x22C6;/
165 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
166
167 typedef enum {
168 DMX_OTHER_FE = 0,
169 DMX_SATELLITE_FE,
170 DMX_CABLE_FE,
171 DMX_TERRESTRIAL_FE,
172 DMX_LVDS_FE,
173 DMX_ASI_FE, /&#x22C6; DVB-ASI interface &#x22C6;/
174 DMX_MEMORY_FE
175 } dmx_frontend_source_t;
176
177 typedef struct {
178 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
179 char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
180 char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
181 char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
182 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
183 be connected to a particular
184 demux &#x22C6;/
185 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
186 dmx_frontend_source_t source;
187 } dmx_frontend_t;
188
189 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
190 /&#x22C6; MPEG-2 TS Demux &#x22C6;/
191 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
192
193 /&#x22C6;
194 &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
195 &#x22C6;/
196
197 #define DMX_TS_FILTERING 1
198 #define DMX_PES_FILTERING 2
199 #define DMX_SECTION_FILTERING 4
200 #define DMX_MEMORY_BASED_FILTERING 8 /&#x22C6; write() available &#x22C6;/
201 #define DMX_CRC_CHECKING 16
202 #define DMX_TS_DESCRAMBLING 32
203 #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
204 #define DMX_MAC_ADDRESS_DESCRAMBLING 128
205</programlisting>
206
207</section>
208<section id="demux_demux_t">
209<title>demux_demux_t</title>
210 <programlisting>
211 /&#x22C6;
212 &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
213 &#x22C6; front-ends from the generic type struct list_head
214 &#x22C6; to the type &#x22C6; dmx_frontend_t
215 &#x22C6;.
216 &#x22C6;/
217
218 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
219
220 struct dmx_demux_s {
221 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
222 char&#x22C6; id; /&#x22C6; Unique demux identifier &#x22C6;/
223 char&#x22C6; vendor; /&#x22C6; Name of the demux vendor &#x22C6;/
224 char&#x22C6; model; /&#x22C6; Name of the demux model &#x22C6;/
225 __u32 capabilities; /&#x22C6; Bitfield of capability flags &#x22C6;/
226 dmx_frontend_t&#x22C6; frontend; /&#x22C6; Front-end connected to the demux &#x22C6;/
227 struct list_head reg_list; /&#x22C6; List of registered demuxes &#x22C6;/
228 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
229 int users; /&#x22C6; Number of users &#x22C6;/
230 int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
231 int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
232 int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
233 int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
234 dmx_ts_feed_t&#x22C6;&#x22C6; feed,
235 dmx_ts_cb callback);
236 int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
237 dmx_ts_feed_t&#x22C6; feed);
238 int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
239 dmx_pes_feed_t&#x22C6;&#x22C6; feed,
240 dmx_pes_cb callback);
241 int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
242 dmx_pes_feed_t&#x22C6; feed);
243 int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
244 dmx_section_feed_t&#x22C6;&#x22C6; feed,
245 dmx_section_cb callback);
246 int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
247 dmx_section_feed_t&#x22C6; feed);
248 int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
249 __u8&#x22C6; buffer1,
250 size_t buffer1_length,
251 __u8&#x22C6; buffer2,
252 size_t buffer2_length,
253 __u16 pid);
254 int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
255 __u8&#x22C6; buffer1,
256 size_t buffer1_length,
257 __u8&#x22C6; buffer2, size_t buffer2_length,
258 __u16 pid);
259 int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
260 dmx_frontend_t&#x22C6; frontend);
261 int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
262 dmx_frontend_t&#x22C6; frontend);
263 struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
264 int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
265 dmx_frontend_t&#x22C6; frontend);
266 int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
267
268
269 /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
270 int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;pids);
271 };
272 typedef struct dmx_demux_s dmx_demux_t;
273</programlisting>
274
275</section>
276<section id="demux_directory">
277<title>Demux directory</title>
278 <programlisting>
279 /&#x22C6;
280 &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
281 &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
282 &#x22C6;.
283 &#x22C6;/
284
285 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
286
287 int dmx_register_demux (dmx_demux_t&#x22C6; demux);
288 int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
289 struct list_head&#x22C6; dmx_get_demuxes (void);
290</programlisting>
291 </section></section>
292<section id="demux_directory_api">
293<title>Demux Directory API</title>
294<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
295MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
296is possible using this API.
297</para>
298<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
299</para>
300
301<section
302role="subsection"><title>dmx_register_demux()</title>
303<para>DESCRIPTION
304</para>
305<informaltable><tgroup cols="1"><tbody><row><entry
306 align="char">
307<para>This function makes a demux driver interface available to the Linux kernel. It is
308 usually called by the init_module() function of the kernel module that contains
309 the demux driver. The caller of this function is responsible for allocating
310 dynamic or static memory for the demux structure and for initializing its fields
311 before calling this function. The memory allocated for the demux structure
312 must not be freed before calling dmx_unregister_demux(),</para>
313</entry>
314 </row></tbody></tgroup></informaltable>
315<para>SYNOPSIS
316</para>
317<informaltable><tgroup cols="1"><tbody><row><entry
318 align="char">
319<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
320</entry>
321 </row></tbody></tgroup></informaltable>
322<para>PARAMETERS
323</para>
324<informaltable><tgroup cols="2"><tbody><row><entry
325 align="char">
326<para>dmx_demux_t*
327 demux</para>
328</entry><entry
329 align="char">
330<para>Pointer to the demux structure.</para>
331</entry>
332 </row></tbody></tgroup></informaltable>
333<para>RETURNS
334</para>
335<informaltable><tgroup cols="2"><tbody><row><entry
336 align="char">
337<para>0</para>
338</entry><entry
339 align="char">
340<para>The function was completed without errors.</para>
341</entry>
342 </row><row><entry
343 align="char">
344<para>-EEXIST</para>
345</entry><entry
346 align="char">
347<para>A demux with the same value of the id field already stored
348 in the directory.</para>
349</entry>
350 </row><row><entry
351 align="char">
352<para>-ENOSPC</para>
353</entry><entry
354 align="char">
355<para>No space left in the directory.</para>
356</entry>
357 </row></tbody></tgroup></informaltable>
358
359</section><section
360role="subsection"><title>dmx_unregister_demux()</title>
361<para>DESCRIPTION
362</para>
363<informaltable><tgroup cols="1"><tbody><row><entry
364 align="char">
365<para>This function is called to indicate that the given demux interface is no
366 longer available. The caller of this function is responsible for freeing the
367 memory of the demux structure, if it was dynamically allocated before calling
368 dmx_register_demux(). The cleanup_module() function of the kernel module
369 that contains the demux driver should call this function. Note that this function
370 fails if the demux is currently in use, i.e., release_demux() has not been called
371 for the interface.</para>
372</entry>
373 </row></tbody></tgroup></informaltable>
374<para>SYNOPSIS
375</para>
376<informaltable><tgroup cols="1"><tbody><row><entry
377 align="char">
378<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
379</entry>
380 </row></tbody></tgroup></informaltable>
381<para>PARAMETERS
382</para>
383<informaltable><tgroup cols="2"><tbody><row><entry
384 align="char">
385<para>dmx_demux_t*
386 demux</para>
387</entry><entry
388 align="char">
389<para>Pointer to the demux structure which is to be
390 unregistered.</para>
391</entry>
392 </row></tbody></tgroup></informaltable>
393<para>RETURNS
394</para>
395<informaltable><tgroup cols="2"><tbody><row><entry
396 align="char">
397<para>0</para>
398</entry><entry
399 align="char">
400<para>The function was completed without errors.</para>
401</entry>
402 </row><row><entry
403 align="char">
404<para>ENODEV</para>
405</entry><entry
406 align="char">
407<para>The specified demux is not registered in the demux
408 directory.</para>
409</entry>
410 </row><row><entry
411 align="char">
412<para>EBUSY</para>
413</entry><entry
414 align="char">
415<para>The specified demux is currently in use.</para>
416</entry>
417 </row></tbody></tgroup></informaltable>
418
419</section><section
420role="subsection"><title>dmx_get_demuxes()</title>
421<para>DESCRIPTION
422</para>
423<informaltable><tgroup cols="1"><tbody><row><entry
424 align="char">
425<para>Provides the caller with the list of registered demux interfaces, using the
426 standard list structure defined in the include file linux/list.h. The include file
427 demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
428 the generic type struct list_head* to the type dmx_demux_t*. The caller must
429 not free the memory of any of the elements obtained via this function call.</para>
430</entry>
431 </row></tbody></tgroup></informaltable>
432<para>SYNOPSIS
433</para>
434<informaltable><tgroup cols="1"><tbody><row><entry
435 align="char">
436<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
437</entry>
438 </row></tbody></tgroup></informaltable>
439<para>PARAMETERS
440</para>
441<informaltable><tgroup cols="2"><tbody><row><entry
442 align="char">
443<para>none</para>
444</entry>
445 </row></tbody></tgroup></informaltable>
446<para>RETURNS
447</para>
448<informaltable><tgroup cols="2"><tbody><row><entry
449 align="char">
450<para>struct list_head *</para>
451</entry><entry
452 align="char">
453<para>A list of demux interfaces, or NULL in the case of an
454 empty list.</para>
455</entry>
456 </row></tbody></tgroup></informaltable>
457 </section></section>
458<section id="demux_api">
459<title>Demux API</title>
460<para>The demux API should be implemented for each demux in the system. It is used to select
461the TS source of a demux and to manage the demux resources. When the demux
462client allocates a resource via the demux API, it receives a pointer to the API of that
463resource.
464</para>
465<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
466demux API. In a system with more than one front-end, the API can be used to select one of
467the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
468demux API only controls front-ends regarding their connections with demuxes; the APIs
469used to set the other front-end parameters, such as tuning, are not defined in this
470document.
471</para>
472<para>The functions that implement the abstract interface demux should be defined static or
473module private and registered to the Demux Directory for external access. It is not necessary
474to implement every function in the demux_t struct, however (for example, a demux interface
475might support Section filtering, but not TS or PES filtering). The API client is expected to
476check the value of any function pointer before calling the function: the value of NULL means
477&#8220;function not available&#8221;.
478</para>
479<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
480update and race condition problems should be addressed, e.g. by protecting parts of code with
481mutexes. This is especially important on multi-processor hosts.
482</para>
483<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
484kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
485swapping is needed. For example, the Linux kernel calls the functions of a network device
486interface from a bottom half context. Thus, if a demux API function is called from network
487device code, the function must not sleep.
488</para>
489
490
491<section id="kdapi_fopen">
492<title>open()</title>
493<para>DESCRIPTION
494</para>
495<informaltable><tgroup cols="1"><tbody><row><entry
496 align="char">
497<para>This function reserves the demux for use by the caller and, if necessary,
498 initializes the demux. When the demux is no longer needed, the function close()
499 should be called. It should be possible for multiple clients to access the demux
500 at the same time. Thus, the function implementation should increment the
501 demux usage count when open() is called and decrement it when close() is
502 called.</para>
503</entry>
504 </row></tbody></tgroup></informaltable>
505<para>SYNOPSIS
506</para>
507<informaltable><tgroup cols="1"><tbody><row><entry
508 align="char">
509<para>int open ( demux_t&#x22C6; demux );</para>
510</entry>
511 </row></tbody></tgroup></informaltable>
512<para>PARAMETERS
513</para>
514<informaltable><tgroup cols="2"><tbody><row><entry
515 align="char">
516<para>demux_t* demux</para>
517</entry><entry
518 align="char">
519<para>Pointer to the demux API and instance data.</para>
520</entry>
521 </row></tbody></tgroup></informaltable>
522<para>RETURNS
523</para>
524<informaltable><tgroup cols="2"><tbody><row><entry
525 align="char">
526<para>0</para>
527</entry><entry
528 align="char">
529<para>The function was completed without errors.</para>
530</entry>
531 </row><row><entry
532 align="char">
533<para>-EUSERS</para>
534</entry><entry
535 align="char">
536<para>Maximum usage count reached.</para>
537</entry>
538 </row><row><entry
539 align="char">
540<para>-EINVAL</para>
541</entry><entry
542 align="char">
543<para>Bad parameter.</para>
544</entry>
545 </row></tbody></tgroup></informaltable>
546
547</section>
548<section id="kdapi_fclose">
549<title>close()</title>
550<para>DESCRIPTION
551</para>
552<informaltable><tgroup cols="1"><tbody><row><entry
553 align="char">
554<para>This function reserves the demux for use by the caller and, if necessary,
555 initializes the demux. When the demux is no longer needed, the function close()
556 should be called. It should be possible for multiple clients to access the demux
557 at the same time. Thus, the function implementation should increment the
558 demux usage count when open() is called and decrement it when close() is
559 called.</para>
560</entry>
561 </row></tbody></tgroup></informaltable>
562<para>SYNOPSIS
563</para>
564<informaltable><tgroup cols="1"><tbody><row><entry
565 align="char">
566<para>int close(demux_t&#x22C6; demux);</para>
567</entry>
568 </row></tbody></tgroup></informaltable>
569<para>PARAMETERS
570</para>
571<informaltable><tgroup cols="2"><tbody><row><entry
572 align="char">
573<para>demux_t* demux</para>
574</entry><entry
575 align="char">
576<para>Pointer to the demux API and instance data.</para>
577</entry>
578 </row></tbody></tgroup></informaltable>
579<para>RETURNS
580</para>
581<informaltable><tgroup cols="2"><tbody><row><entry
582 align="char">
583<para>0</para>
584</entry><entry
585 align="char">
586<para>The function was completed without errors.</para>
587</entry>
588 </row><row><entry
589 align="char">
590<para>-ENODEV</para>
591</entry><entry
592 align="char">
593<para>The demux was not in use.</para>
594</entry>
595 </row><row><entry
596 align="char">
597<para>-EINVAL</para>
598</entry><entry
599 align="char">
600<para>Bad parameter.</para>
601</entry>
602 </row></tbody></tgroup></informaltable>
603
604</section>
605<section id="kdapi_fwrite">
606<title>write()</title>
607<para>DESCRIPTION
608</para>
609<informaltable><tgroup cols="1"><tbody><row><entry
610 align="char">
611<para>This function provides the demux driver with a memory buffer containing TS
612 packets. Instead of receiving TS packets from the DVB front-end, the demux
613 driver software will read packets from memory. Any clients of this demux
614 with active TS, PES or Section filters will receive filtered data via the Demux
615 callback API (see 0). The function returns when all the data in the buffer has
616 been consumed by the demux. Demux hardware typically cannot read TS from
617 memory. If this is the case, memory-based filtering has to be implemented
618 entirely in software.</para>
619</entry>
620 </row></tbody></tgroup></informaltable>
621<para>SYNOPSIS
622</para>
623<informaltable><tgroup cols="1"><tbody><row><entry
624 align="char">
625<para>int write(demux_t&#x22C6; demux, const char&#x22C6; buf, size_t
626 count);</para>
627</entry>
628 </row></tbody></tgroup></informaltable>
629<para>PARAMETERS
630</para>
631<informaltable><tgroup cols="2"><tbody><row><entry
632 align="char">
633<para>demux_t* demux</para>
634</entry><entry
635 align="char">
636<para>Pointer to the demux API and instance data.</para>
637</entry>
638 </row><row><entry
639 align="char">
640<para>const char* buf</para>
641</entry><entry
642 align="char">
643<para>Pointer to the TS data in kernel-space memory.</para>
644</entry>
645 </row><row><entry
646 align="char">
647<para>size_t length</para>
648</entry><entry
649 align="char">
650<para>Length of the TS data.</para>
651</entry>
652 </row></tbody></tgroup></informaltable>
653<para>RETURNS
654</para>
655<informaltable><tgroup cols="2"><tbody><row><entry
656 align="char">
657<para>0</para>
658</entry><entry
659 align="char">
660<para>The function was completed without errors.</para>
661</entry>
662 </row><row><entry
663 align="char">
664<para>-ENOSYS</para>
665</entry><entry
666 align="char">
667<para>The command is not implemented.</para>
668</entry>
669 </row><row><entry
670 align="char">
671<para>-EINVAL</para>
672</entry><entry
673 align="char">
674<para>Bad parameter.</para>
675</entry>
676 </row></tbody></tgroup></informaltable>
677
678</section><section
679role="subsection"><title>allocate_ts_feed()</title>
680<para>DESCRIPTION
681</para>
682<informaltable><tgroup cols="1"><tbody><row><entry
683 align="char">
684<para>Allocates a new TS feed, which is used to filter the TS packets carrying a
685 certain PID. The TS feed normally corresponds to a hardware PID filter on the
686 demux chip.</para>
687</entry>
688 </row></tbody></tgroup></informaltable>
689<para>SYNOPSIS
690</para>
691<informaltable><tgroup cols="1"><tbody><row><entry
692 align="char">
693<para>int allocate_ts_feed(dmx_demux_t&#x22C6; demux,
694 dmx_ts_feed_t&#x22C6;&#x22C6; feed, dmx_ts_cb callback);</para>
695</entry>
696 </row></tbody></tgroup></informaltable>
697<para>PARAMETERS
698</para>
699<informaltable><tgroup cols="2"><tbody><row><entry
700 align="char">
701<para>demux_t* demux</para>
702</entry><entry
703 align="char">
704<para>Pointer to the demux API and instance data.</para>
705</entry>
706 </row><row><entry
707 align="char">
708<para>dmx_ts_feed_t**
709 feed</para>
710</entry><entry
711 align="char">
712<para>Pointer to the TS feed API and instance data.</para>
713</entry>
714 </row><row><entry
715 align="char">
716<para>dmx_ts_cb callback</para>
717</entry><entry
718 align="char">
719<para>Pointer to the callback function for passing received TS
720 packet</para>
721</entry>
722 </row></tbody></tgroup></informaltable>
723<para>RETURNS
724</para>
725<informaltable><tgroup cols="2"><tbody><row><entry
726 align="char">
727<para>0</para>
728</entry><entry
729 align="char">
730<para>The function was completed without errors.</para>
731</entry>
732 </row><row><entry
733 align="char">
734<para>-EBUSY</para>
735</entry><entry
736 align="char">
737<para>No more TS feeds available.</para>
738</entry>
739 </row><row><entry
740 align="char">
741<para>-ENOSYS</para>
742</entry><entry
743 align="char">
744<para>The command is not implemented.</para>
745</entry>
746 </row><row><entry
747 align="char">
748<para>-EINVAL</para>
749</entry><entry
750 align="char">
751<para>Bad parameter.</para>
752</entry>
753 </row></tbody></tgroup></informaltable>
754
755</section><section
756role="subsection"><title>release_ts_feed()</title>
757<para>DESCRIPTION
758</para>
759<informaltable><tgroup cols="1"><tbody><row><entry
760 align="char">
761<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in
762 progress on the TS feed should be stopped before calling this function.</para>
763</entry>
764 </row></tbody></tgroup></informaltable>
765<para>SYNOPSIS
766</para>
767<informaltable><tgroup cols="1"><tbody><row><entry
768 align="char">
769<para>int release_ts_feed(dmx_demux_t&#x22C6; demux,
770 dmx_ts_feed_t&#x22C6; feed);</para>
771</entry>
772 </row></tbody></tgroup></informaltable>
773<para>PARAMETERS
774</para>
775<informaltable><tgroup cols="2"><tbody><row><entry
776 align="char">
777<para>demux_t* demux</para>
778</entry><entry
779 align="char">
780<para>Pointer to the demux API and instance data.</para>
781</entry>
782 </row><row><entry
783 align="char">
784<para>dmx_ts_feed_t* feed</para>
785</entry><entry
786 align="char">
787<para>Pointer to the TS feed API and instance data.</para>
788</entry>
789 </row></tbody></tgroup></informaltable>
790<para>RETURNS
791</para>
792<informaltable><tgroup cols="2"><tbody><row><entry
793 align="char">
794<para>0</para>
795</entry><entry
796 align="char">
797<para>The function was completed without errors.</para>
798</entry>
799 </row><row><entry
800 align="char">
801<para>-EINVAL</para>
802</entry><entry
803 align="char">
804<para>Bad parameter.</para>
805</entry>
806 </row></tbody></tgroup></informaltable>
807
808</section><section
809role="subsection"><title>allocate_section_feed()</title>
810<para>DESCRIPTION
811</para>
812<informaltable><tgroup cols="1"><tbody><row><entry
813 align="char">
814<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving
815 sections. On platforms with hardware support for section filtering, a section
816 feed is directly mapped to the demux HW. On other platforms, TS packets are
817 first PID filtered in hardware and a hardware section filter then emulated in
818 software. The caller obtains an API pointer of type dmx_section_feed_t as an
819 out parameter. Using this API the caller can set filtering parameters and start
820 receiving sections.</para>
821</entry>
822 </row></tbody></tgroup></informaltable>
823<para>SYNOPSIS
824</para>
825<informaltable><tgroup cols="1"><tbody><row><entry
826 align="char">
827<para>int allocate_section_feed(dmx_demux_t&#x22C6; demux,
828 dmx_section_feed_t &#x22C6;&#x22C6;feed, dmx_section_cb callback);</para>
829</entry>
830 </row></tbody></tgroup></informaltable>
831<para>PARAMETERS
832</para>
833<informaltable><tgroup cols="2"><tbody><row><entry
834 align="char">
835<para>demux_t *demux</para>
836</entry><entry
837 align="char">
838<para>Pointer to the demux API and instance data.</para>
839</entry>
840 </row><row><entry
841 align="char">
842<para>dmx_section_feed_t
843 **feed</para>
844</entry><entry
845 align="char">
846<para>Pointer to the section feed API and instance data.</para>
847</entry>
848 </row><row><entry
849 align="char">
850<para>dmx_section_cb
851 callback</para>
852</entry><entry
853 align="char">
854<para>Pointer to the callback function for passing received
855 sections.</para>
856</entry>
857 </row></tbody></tgroup></informaltable>
858<para>RETURNS
859</para>
860<informaltable><tgroup cols="2"><tbody><row><entry
861 align="char">
862<para>0</para>
863</entry><entry
864 align="char">
865<para>The function was completed without errors.</para>
866</entry>
867 </row><row><entry
868 align="char">
869<para>-EBUSY</para>
870</entry><entry
871 align="char">
872<para>No more section feeds available.</para>
873</entry>
874 </row><row><entry
875 align="char">
876<para>-ENOSYS</para>
877</entry><entry
878 align="char">
879<para>The command is not implemented.</para>
880</entry>
881 </row><row><entry
882 align="char">
883<para>-EINVAL</para>
884</entry><entry
885 align="char">
886<para>Bad parameter.</para>
887</entry>
888 </row></tbody></tgroup></informaltable>
889
890</section><section
891role="subsection"><title>release_section_feed()</title>
892<para>DESCRIPTION
893</para>
894<informaltable><tgroup cols="1"><tbody><row><entry
895 align="char">
896<para>Releases the resources allocated with allocate_section_feed(), including
897 allocated filters. Any filtering in progress on the section feed should be stopped
898 before calling this function.</para>
899</entry>
900 </row></tbody></tgroup></informaltable>
901<para>SYNOPSIS
902</para>
903<informaltable><tgroup cols="1"><tbody><row><entry
904 align="char">
905<para>int release_section_feed(dmx_demux_t&#x22C6; demux,
906 dmx_section_feed_t &#x22C6;feed);</para>
907</entry>
908 </row></tbody></tgroup></informaltable>
909<para>PARAMETERS
910</para>
911<informaltable><tgroup cols="2"><tbody><row><entry
912 align="char">
913<para>demux_t *demux</para>
914</entry><entry
915 align="char">
916<para>Pointer to the demux API and instance data.</para>
917</entry>
918 </row><row><entry
919 align="char">
920<para>dmx_section_feed_t
921 *feed</para>
922</entry><entry
923 align="char">
924<para>Pointer to the section feed API and instance data.</para>
925</entry>
926 </row></tbody></tgroup></informaltable>
927<para>RETURNS
928</para>
929<informaltable><tgroup cols="2"><tbody><row><entry
930 align="char">
931<para>0</para>
932</entry><entry
933 align="char">
934<para>The function was completed without errors.</para>
935</entry>
936 </row><row><entry
937 align="char">
938<para>-EINVAL</para>
939</entry><entry
940 align="char">
941<para>Bad parameter.</para>
942</entry>
943 </row></tbody></tgroup></informaltable>
944
945</section><section
946role="subsection"><title>descramble_mac_address()</title>
947<para>DESCRIPTION
948</para>
949<informaltable><tgroup cols="1"><tbody><row><entry
950 align="char">
951<para>This function runs a descrambling algorithm on the destination MAC
952 address field of a DVB Datagram Section, replacing the original address
953 with its un-encrypted version. Otherwise, the description on the function
954 descramble_section_payload() applies also to this function.</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957<para>SYNOPSIS
958</para>
959<informaltable><tgroup cols="1"><tbody><row><entry
960 align="char">
961<para>int descramble_mac_address(dmx_demux_t&#x22C6; demux, __u8
962 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
963 size_t buffer2_length, __u16 pid);</para>
964</entry>
965 </row></tbody></tgroup></informaltable>
966<para>PARAMETERS
967</para>
968<informaltable><tgroup cols="2"><tbody><row><entry
969 align="char">
970<para>dmx_demux_t
971 *demux</para>
972</entry><entry
973 align="char">
974<para>Pointer to the demux API and instance data.</para>
975</entry>
976 </row><row><entry
977 align="char">
978<para>__u8 *buffer1</para>
979</entry><entry
980 align="char">
981<para>Pointer to the first byte of the section.</para>
982</entry>
983 </row><row><entry
984 align="char">
985<para>size_t buffer1_length</para>
986</entry><entry
987 align="char">
988<para>Length of the section data, including headers and CRC,
989 in buffer1.</para>
990</entry>
991 </row><row><entry
992 align="char">
993<para>__u8* buffer2</para>
994</entry><entry
995 align="char">
996<para>Pointer to the tail of the section data, or NULL. The
997 pointer has a non-NULL value if the section wraps past
998 the end of a circular buffer.</para>
999</entry>
1000 </row><row><entry
1001 align="char">
1002<para>size_t buffer2_length</para>
1003</entry><entry
1004 align="char">
1005<para>Length of the section data, including headers and CRC,
1006 in buffer2.</para>
1007</entry>
1008 </row><row><entry
1009 align="char">
1010<para>__u16 pid</para>
1011</entry><entry
1012 align="char">
1013<para>The PID on which the section was received. Useful
1014 for obtaining the descrambling key, e.g. from a DVB
1015 Common Access facility.</para>
1016</entry>
1017 </row></tbody></tgroup></informaltable>
1018<para>RETURNS
1019</para>
1020<informaltable><tgroup cols="2"><tbody><row><entry
1021 align="char">
1022<para>0</para>
1023</entry><entry
1024 align="char">
1025<para>The function was completed without errors.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>-ENOSYS</para>
1030</entry><entry
1031 align="char">
1032<para>No descrambling facility available.</para>
1033</entry>
1034 </row><row><entry
1035 align="char">
1036<para>-EINVAL</para>
1037</entry><entry
1038 align="char">
1039<para>Bad parameter.</para>
1040</entry>
1041 </row></tbody></tgroup></informaltable>
1042
1043</section><section
1044role="subsection"><title>descramble_section_payload()</title>
1045<para>DESCRIPTION
1046</para>
1047<informaltable><tgroup cols="1"><tbody><row><entry
1048 align="char">
1049<para>This function runs a descrambling algorithm on the payload of a DVB
1050 Datagram Section, replacing the original payload with its un-encrypted
1051 version. The function will be called from the demux API implementation;
1052 the API client need not call this function directly. Section-level scrambling
1053 algorithms are currently standardized only for DVB-RCC (return channel
1054 over 2-directional cable TV network) systems. For all other DVB networks,
1055 encryption schemes are likely to be proprietary to each data broadcaster. Thus,
1056 it is expected that this function pointer will have the value of NULL (i.e.,
1057 function not available) in most demux API implementations. Nevertheless, it
1058 should be possible to use the function pointer as a hook for dynamically adding
1059 a &#8220;plug-in&#8221; descrambling facility to a demux driver.</para>
1060</entry>
1061 </row><row><entry
1062 align="char">
1063<para>While this function is not needed with hardware-based section descrambling,
1064 the descramble_section_payload function pointer can be used to override the
1065 default hardware-based descrambling algorithm: if the function pointer has a
1066 non-NULL value, the corresponding function should be used instead of any
1067 descrambling hardware.</para>
1068</entry>
1069 </row></tbody></tgroup></informaltable>
1070<para>SYNOPSIS
1071</para>
1072<informaltable><tgroup cols="1"><tbody><row><entry
1073 align="char">
1074<para>int descramble_section_payload(dmx_demux_t&#x22C6; demux,
1075 __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
1076 size_t buffer2_length, __u16 pid);</para>
1077</entry>
1078 </row></tbody></tgroup></informaltable>
1079<para>PARAMETERS
1080</para>
1081<informaltable><tgroup cols="2"><tbody><row><entry
1082 align="char">
1083<para>dmx_demux_t
1084 *demux</para>
1085</entry><entry
1086 align="char">
1087<para>Pointer to the demux API and instance data.</para>
1088</entry>
1089 </row><row><entry
1090 align="char">
1091<para>__u8 *buffer1</para>
1092</entry><entry
1093 align="char">
1094<para>Pointer to the first byte of the section.</para>
1095</entry>
1096 </row><row><entry
1097 align="char">
1098<para>size_t buffer1_length</para>
1099</entry><entry
1100 align="char">
1101<para>Length of the section data, including headers and CRC,
1102 in buffer1.</para>
1103</entry>
1104 </row><row><entry
1105 align="char">
1106<para>__u8 *buffer2</para>
1107</entry><entry
1108 align="char">
1109<para>Pointer to the tail of the section data, or NULL. The
1110 pointer has a non-NULL value if the section wraps past
1111 the end of a circular buffer.</para>
1112</entry>
1113 </row><row><entry
1114 align="char">
1115<para>size_t buffer2_length</para>
1116</entry><entry
1117 align="char">
1118<para>Length of the section data, including headers and CRC,
1119 in buffer2.</para>
1120</entry>
1121 </row><row><entry
1122 align="char">
1123<para>__u16 pid</para>
1124</entry><entry
1125 align="char">
1126<para>The PID on which the section was received. Useful
1127 for obtaining the descrambling key, e.g. from a DVB
1128 Common Access facility.</para>
1129</entry>
1130 </row></tbody></tgroup></informaltable>
1131<para>RETURNS
1132</para>
1133<informaltable><tgroup cols="2"><tbody><row><entry
1134 align="char">
1135<para>0</para>
1136</entry><entry
1137 align="char">
1138<para>The function was completed without errors.</para>
1139</entry>
1140 </row><row><entry
1141 align="char">
1142<para>-ENOSYS</para>
1143</entry><entry
1144 align="char">
1145<para>No descrambling facility available.</para>
1146</entry>
1147 </row><row><entry
1148 align="char">
1149<para>-EINVAL</para>
1150</entry><entry
1151 align="char">
1152<para>Bad parameter.</para>
1153</entry>
1154 </row></tbody></tgroup></informaltable>
1155
1156</section><section
1157role="subsection"><title>add_frontend()</title>
1158<para>DESCRIPTION
1159</para>
1160<informaltable><tgroup cols="1"><tbody><row><entry
1161 align="char">
1162<para>Registers a connectivity between a demux and a front-end, i.e., indicates that
1163 the demux can be connected via a call to connect_frontend() to use the given
1164 front-end as a TS source. The client of this function has to allocate dynamic or
1165 static memory for the frontend structure and initialize its fields before calling
1166 this function. This function is normally called during the driver initialization.
1167 The caller must not free the memory of the frontend struct before successfully
1168 calling remove_frontend().</para>
1169</entry>
1170 </row></tbody></tgroup></informaltable>
1171<para>SYNOPSIS
1172</para>
1173<informaltable><tgroup cols="1"><tbody><row><entry
1174 align="char">
1175<para>int add_frontend(dmx_demux_t &#x22C6;demux, dmx_frontend_t
1176 &#x22C6;frontend);</para>
1177</entry>
1178 </row></tbody></tgroup></informaltable>
1179<para>PARAMETERS
1180</para>
1181<informaltable><tgroup cols="2"><tbody><row><entry
1182 align="char">
1183<para>dmx_demux_t*
1184 demux</para>
1185</entry><entry
1186 align="char">
1187<para>Pointer to the demux API and instance data.</para>
1188</entry>
1189 </row><row><entry
1190 align="char">
1191<para>dmx_frontend_t*
1192 frontend</para>
1193</entry><entry
1194 align="char">
1195<para>Pointer to the front-end instance data.</para>
1196</entry>
1197 </row></tbody></tgroup></informaltable>
1198<para>RETURNS
1199</para>
1200<informaltable><tgroup cols="2"><tbody><row><entry
1201 align="char">
1202<para>0</para>
1203</entry><entry
1204 align="char">
1205<para>The function was completed without errors.</para>
1206</entry>
1207 </row><row><entry
1208 align="char">
1209<para>-EEXIST</para>
1210</entry><entry
1211 align="char">
1212<para>A front-end with the same value of the id field already
1213 registered.</para>
1214</entry>
1215 </row><row><entry
1216 align="char">
1217<para>-EINUSE</para>
1218</entry><entry
1219 align="char">
1220<para>The demux is in use.</para>
1221</entry>
1222 </row><row><entry
1223 align="char">
1224<para>-ENOMEM</para>
1225</entry><entry
1226 align="char">
1227<para>No more front-ends can be added.</para>
1228</entry>
1229 </row><row><entry
1230 align="char">
1231<para>-EINVAL</para>
1232</entry><entry
1233 align="char">
1234<para>Bad parameter.</para>
1235</entry>
1236 </row></tbody></tgroup></informaltable>
1237
1238</section><section
1239role="subsection"><title>remove_frontend()</title>
1240<para>DESCRIPTION
1241</para>
1242<informaltable><tgroup cols="1"><tbody><row><entry
1243 align="char">
1244<para>Indicates that the given front-end, registered by a call to add_frontend(), can
1245 no longer be connected as a TS source by this demux. The function should be
1246 called when a front-end driver or a demux driver is removed from the system.
1247 If the front-end is in use, the function fails with the return value of -EBUSY.
1248 After successfully calling this function, the caller can free the memory of
1249 the frontend struct if it was dynamically allocated before the add_frontend()
1250 operation.</para>
1251</entry>
1252 </row></tbody></tgroup></informaltable>
1253<para>SYNOPSIS
1254</para>
1255<informaltable><tgroup cols="1"><tbody><row><entry
1256 align="char">
1257<para>int remove_frontend(dmx_demux_t&#x22C6; demux,
1258 dmx_frontend_t&#x22C6; frontend);</para>
1259</entry>
1260 </row></tbody></tgroup></informaltable>
1261<para>PARAMETERS
1262</para>
1263<informaltable><tgroup cols="2"><tbody><row><entry
1264 align="char">
1265<para>dmx_demux_t*
1266 demux</para>
1267</entry><entry
1268 align="char">
1269<para>Pointer to the demux API and instance data.</para>
1270</entry>
1271 </row><row><entry
1272 align="char">
1273<para>dmx_frontend_t*
1274 frontend</para>
1275</entry><entry
1276 align="char">
1277<para>Pointer to the front-end instance data.</para>
1278</entry>
1279 </row></tbody></tgroup></informaltable>
1280<para>RETURNS
1281</para>
1282<informaltable><tgroup cols="2"><tbody><row><entry
1283 align="char">
1284<para>0</para>
1285</entry><entry
1286 align="char">
1287<para>The function was completed without errors.</para>
1288</entry>
1289 </row><row><entry
1290 align="char">
1291<para>-EINVAL</para>
1292</entry><entry
1293 align="char">
1294<para>Bad parameter.</para>
1295</entry>
1296 </row><row><entry
1297 align="char">
1298<para>-EBUSY</para>
1299</entry><entry
1300 align="char">
1301<para>The front-end is in use, i.e. a call to connect_frontend()
1302 has not been followed by a call to disconnect_frontend().</para>
1303</entry>
1304 </row></tbody></tgroup></informaltable>
1305
1306</section><section
1307role="subsection"><title>get_frontends()</title>
1308<para>DESCRIPTION
1309</para>
1310<informaltable><tgroup cols="1"><tbody><row><entry
1311 align="char">
1312<para>Provides the APIs of the front-ends that have been registered for this demux.
1313 Any of the front-ends obtained with this call can be used as a parameter for
1314 connect_frontend().</para>
1315</entry>
1316 </row><row><entry
1317 align="char">
1318<para>The include file demux.h contains the macro DMX_FE_ENTRY() for
1319 converting an element of the generic type struct list_head* to the type
1320 dmx_frontend_t*. The caller must not free the memory of any of the elements
1321 obtained via this function call.</para>
1322</entry>
1323 </row></tbody></tgroup></informaltable>
1324<para>SYNOPSIS
1325</para>
1326<informaltable><tgroup cols="1"><tbody><row><entry
1327 align="char">
1328<para>struct list_head&#x22C6; get_frontends(dmx_demux_t&#x22C6; demux);</para>
1329</entry>
1330 </row></tbody></tgroup></informaltable>
1331<para>PARAMETERS
1332</para>
1333<informaltable><tgroup cols="2"><tbody><row><entry
1334 align="char">
1335<para>dmx_demux_t*
1336 demux</para>
1337</entry><entry
1338 align="char">
1339<para>Pointer to the demux API and instance data.</para>
1340</entry>
1341 </row></tbody></tgroup></informaltable>
1342<para>RETURNS
1343</para>
1344<informaltable><tgroup cols="2"><tbody><row><entry
1345 align="char">
1346<para>dmx_demux_t*</para>
1347</entry><entry
1348 align="char">
1349<para>A list of front-end interfaces, or NULL in the case of an
1350 empty list.</para>
1351</entry>
1352 </row></tbody></tgroup></informaltable>
1353
1354</section><section
1355role="subsection"><title>connect_frontend()</title>
1356<para>DESCRIPTION
1357</para>
1358<informaltable><tgroup cols="1"><tbody><row><entry
1359 align="char">
1360<para>Connects the TS output of the front-end to the input of the demux. A demux
1361 can only be connected to a front-end registered to the demux with the function
1362 add_frontend().</para>
1363</entry>
1364 </row><row><entry
1365 align="char">
1366<para>It may or may not be possible to connect multiple demuxes to the same
1367 front-end, depending on the capabilities of the HW platform. When not used,
1368 the front-end should be released by calling disconnect_frontend().</para>
1369</entry>
1370 </row></tbody></tgroup></informaltable>
1371<para>SYNOPSIS
1372</para>
1373<informaltable><tgroup cols="1"><tbody><row><entry
1374 align="char">
1375<para>int connect_frontend(dmx_demux_t&#x22C6; demux,
1376 dmx_frontend_t&#x22C6; frontend);</para>
1377</entry>
1378 </row></tbody></tgroup></informaltable>
1379<para>PARAMETERS
1380</para>
1381<informaltable><tgroup cols="2"><tbody><row><entry
1382 align="char">
1383<para>dmx_demux_t*
1384 demux</para>
1385</entry><entry
1386 align="char">
1387<para>Pointer to the demux API and instance data.</para>
1388</entry>
1389 </row><row><entry
1390 align="char">
1391<para>dmx_frontend_t*
1392 frontend</para>
1393</entry><entry
1394 align="char">
1395<para>Pointer to the front-end instance data.</para>
1396</entry>
1397 </row></tbody></tgroup></informaltable>
1398<para>RETURNS
1399</para>
1400<informaltable><tgroup cols="2"><tbody><row><entry
1401 align="char">
1402<para>0</para>
1403</entry><entry
1404 align="char">
1405<para>The function was completed without errors.</para>
1406</entry>
1407 </row><row><entry
1408 align="char">
1409<para>-EINVAL</para>
1410</entry><entry
1411 align="char">
1412<para>Bad parameter.</para>
1413</entry>
1414 </row><row><entry
1415 align="char">
1416<para>-EBUSY</para>
1417</entry><entry
1418 align="char">
1419<para>The front-end is in use.</para>
1420</entry>
1421 </row></tbody></tgroup></informaltable>
1422
1423</section><section
1424role="subsection"><title>disconnect_frontend()</title>
1425<para>DESCRIPTION
1426</para>
1427<informaltable><tgroup cols="1"><tbody><row><entry
1428 align="char">
1429<para>Disconnects the demux and a front-end previously connected by a
1430 connect_frontend() call.</para>
1431</entry>
1432 </row></tbody></tgroup></informaltable>
1433<para>SYNOPSIS
1434</para>
1435<informaltable><tgroup cols="1"><tbody><row><entry
1436 align="char">
1437<para>int disconnect_frontend(dmx_demux_t&#x22C6; demux);</para>
1438</entry>
1439 </row></tbody></tgroup></informaltable>
1440<para>PARAMETERS
1441</para>
1442<informaltable><tgroup cols="2"><tbody><row><entry
1443 align="char">
1444<para>dmx_demux_t*
1445 demux</para>
1446</entry><entry
1447 align="char">
1448<para>Pointer to the demux API and instance data.</para>
1449</entry>
1450 </row></tbody></tgroup></informaltable>
1451<para>RETURNS
1452</para>
1453<informaltable><tgroup cols="2"><tbody><row><entry
1454 align="char">
1455<para>0</para>
1456</entry><entry
1457 align="char">
1458<para>The function was completed without errors.</para>
1459</entry>
1460 </row><row><entry
1461 align="char">
1462<para>-EINVAL</para>
1463</entry><entry
1464 align="char">
1465<para>Bad parameter.</para>
1466</entry>
1467 </row></tbody></tgroup></informaltable>
1468 </section></section>
1469<section id="demux_callback_api">
1470<title>Demux Callback API</title>
1471<para>This kernel-space API comprises the callback functions that deliver filtered data to the
1472demux client. Unlike the other APIs, these API functions are provided by the client and called
1473from the demux code.
1474</para>
1475<para>The function pointers of this abstract interface are not packed into a structure as in the
1476other demux APIs, because the callback functions are registered and used independent
1477of each other. As an example, it is possible for the API client to provide several
1478callback functions for receiving TS packets and no callbacks for PES packets or
1479sections.
1480</para>
1481<para>The functions that implement the callback API need not be re-entrant: when a demux
1482driver calls one of these functions, the driver is not allowed to call the function again before
1483the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
1484to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
1485function call directly from a hardware interrupt.
1486</para>
1487
1488<section
1489role="subsection"><title>dmx_ts_cb()</title>
1490<para>DESCRIPTION
1491</para>
1492<informaltable><tgroup cols="1"><tbody><row><entry
1493 align="char">
1494<para>This function, provided by the client of the demux API, is called from the
1495 demux code. The function is only called when filtering on this TS feed has
1496 been enabled using the start_filtering() function.</para>
1497</entry>
1498 </row><row><entry
1499 align="char">
1500<para>Any TS packets that match the filter settings are copied to a circular buffer. The
1501 filtered TS packets are delivered to the client using this callback function. The
1502 size of the circular buffer is controlled by the circular_buffer_size parameter
1503 of the set() function in the TS Feed API. It is expected that the buffer1 and
1504 buffer2 callback parameters point to addresses within the circular buffer, but
1505 other implementations are also possible. Note that the called party should not
1506 try to free the memory the buffer1 and buffer2 parameters point to.</para>
1507</entry>
1508 </row><row><entry
1509 align="char">
1510<para>When this function is called, the buffer1 parameter typically points to the
1511 start of the first undelivered TS packet within a circular buffer. The buffer2
1512 buffer parameter is normally NULL, except when the received TS packets have
1513 crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
1514 of the buffer. In the latter case the buffer1 parameter would contain an address
1515 within the circular buffer, while the buffer2 parameter would contain the first
1516 address of the circular buffer.</para>
1517</entry>
1518 </row><row><entry
1519 align="char">
1520<para>The number of bytes delivered with this function (i.e. buffer1_length +
1521 buffer2_length) is usually equal to the value of callback_length parameter
1522 given in the set() function, with one exception: if a timeout occurs before
1523 receiving callback_length bytes of TS data, any undelivered packets are
1524 immediately delivered to the client by calling this function. The timeout
1525 duration is controlled by the set() function in the TS Feed API.</para>
1526</entry>
1527 </row><row><entry
1528 align="char">
1529<para>If a TS packet is received with errors that could not be fixed by the TS-level
1530 forward error correction (FEC), the Transport_error_indicator flag of the TS
1531 packet header should be set. The TS packet should not be discarded, as
1532 the error can possibly be corrected by a higher layer protocol. If the called
1533 party is slow in processing the callback, it is possible that the circular buffer
1534 eventually fills up. If this happens, the demux driver should discard any TS
1535 packets received while the buffer is full. The error should be indicated to the
1536 client on the next callback by setting the success parameter to the value of
1537 DMX_OVERRUN_ERROR.</para>
1538</entry>
1539 </row><row><entry
1540 align="char">
1541<para>The type of data returned to the callback can be selected by the new
1542 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
1543 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
1544 include file ost/demux.h) The type parameter decides if the raw TS packet
1545 (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
1546 should be returned. If additionally the TS_DECODER bit is set the stream
1547 will also be sent to the hardware MPEG decoder. In this case, the second
1548 flag decides as what kind of data the stream should be interpreted. The
1549 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
1550 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
1551 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
1552</entry>
1553 </row></tbody></tgroup></informaltable>
1554<para>SYNOPSIS
1555</para>
1556<informaltable><tgroup cols="1"><tbody><row><entry
1557 align="char">
1558<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
1559 __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
1560 source, dmx_success_t success);</para>
1561</entry>
1562 </row></tbody></tgroup></informaltable>
1563<para>PARAMETERS
1564</para>
1565<informaltable><tgroup cols="2"><tbody><row><entry
1566 align="char">
1567<para>__u8* buffer1</para>
1568</entry><entry
1569 align="char">
1570<para>Pointer to the start of the filtered TS packets.</para>
1571</entry>
1572 </row><row><entry
1573 align="char">
1574<para>size_t buffer1_length</para>
1575</entry><entry
1576 align="char">
1577<para>Length of the TS data in buffer1.</para>
1578</entry>
1579 </row><row><entry
1580 align="char">
1581<para>__u8* buffer2</para>
1582</entry><entry
1583 align="char">
1584<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
1585</entry>
1586 </row><row><entry
1587 align="char">
1588<para>size_t buffer2_length</para>
1589</entry><entry
1590 align="char">
1591<para>Length of the TS data in buffer2.</para>
1592</entry>
1593 </row><row><entry
1594 align="char">
1595<para>dmx_ts_feed_t*
1596 source</para>
1597</entry><entry
1598 align="char">
1599<para>Indicates which TS feed is the source of the callback.</para>
1600</entry>
1601 </row><row><entry
1602 align="char">
1603<para>dmx_success_t
1604 success</para>
1605</entry><entry
1606 align="char">
1607<para>Indicates if there was an error in TS reception.</para>
1608</entry>
1609 </row></tbody></tgroup></informaltable>
1610<para>RETURNS
1611</para>
1612<informaltable><tgroup cols="2"><tbody><row><entry
1613 align="char">
1614<para>0</para>
1615</entry><entry
1616 align="char">
1617<para>Continue filtering.</para>
1618</entry>
1619 </row><row><entry
1620 align="char">
1621<para>-1</para>
1622</entry><entry
1623 align="char">
1624<para>Stop filtering - has the same effect as a call to
1625 stop_filtering() on the TS Feed API.</para>
1626</entry>
1627 </row></tbody></tgroup></informaltable>
1628
1629</section><section
1630role="subsection"><title>dmx_section_cb()</title>
1631<para>DESCRIPTION
1632</para>
1633<informaltable><tgroup cols="1"><tbody><row><entry
1634 align="char">
1635<para>This function, provided by the client of the demux API, is called from the
1636 demux code. The function is only called when filtering of sections has been
1637 enabled using the function start_filtering() of the section feed API. When the
1638 demux driver has received a complete section that matches at least one section
1639 filter, the client is notified via this callback function. Normally this function is
1640 called for each received section; however, it is also possible to deliver multiple
1641 sections with one callback, for example when the system load is high. If an
1642 error occurs while receiving a section, this function should be called with
1643 the corresponding error type set in the success field, whether or not there is
1644 data to deliver. The Section Feed implementation should maintain a circular
1645 buffer for received sections. However, this is not necessary if the Section Feed
1646 API is implemented as a client of the TS Feed API, because the TS Feed
1647 implementation then buffers the received data. The size of the circular buffer
1648 can be configured using the set() function in the Section Feed API. If there
1649 is no room in the circular buffer when a new section is received, the section
1650 must be discarded. If this happens, the value of the success parameter should
1651 be DMX_OVERRUN_ERROR on the next callback.</para>
1652</entry>
1653 </row></tbody></tgroup></informaltable>
1654<para>SYNOPSIS
1655</para>
1656<informaltable><tgroup cols="1"><tbody><row><entry
1657 align="char">
1658<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
1659 buffer1_length, __u8&#x22C6; buffer2, size_t
1660 buffer2_length, dmx_section_filter_t&#x22C6; source,
1661 dmx_success_t success);</para>
1662</entry>
1663 </row></tbody></tgroup></informaltable>
1664<para>PARAMETERS
1665</para>
1666<informaltable><tgroup cols="2"><tbody><row><entry
1667 align="char">
1668<para>__u8* buffer1</para>
1669</entry><entry
1670 align="char">
1671<para>Pointer to the start of the filtered section, e.g. within the
1672 circular buffer of the demux driver.</para>
1673</entry>
1674 </row><row><entry
1675 align="char">
1676<para>size_t buffer1_length</para>
1677</entry><entry
1678 align="char">
1679<para>Length of the filtered section data in buffer1, including
1680 headers and CRC.</para>
1681</entry>
1682 </row><row><entry
1683 align="char">
1684<para>__u8* buffer2</para>
1685</entry><entry
1686 align="char">
1687<para>Pointer to the tail of the filtered section data, or NULL.
1688 Useful to handle the wrapping of a circular buffer.</para>
1689</entry>
1690 </row><row><entry
1691 align="char">
1692<para>size_t buffer2_length</para>
1693</entry><entry
1694 align="char">
1695<para>Length of the filtered section data in buffer2, including
1696 headers and CRC.</para>
1697</entry>
1698 </row><row><entry
1699 align="char">
1700<para>dmx_section_filter_t*
1701 filter</para>
1702</entry><entry
1703 align="char">
1704<para>Indicates the filter that triggered the callback.</para>
1705</entry>
1706 </row><row><entry
1707 align="char">
1708<para>dmx_success_t
1709 success</para>
1710</entry><entry
1711 align="char">
1712<para>Indicates if there was an error in section reception.</para>
1713</entry>
1714 </row></tbody></tgroup></informaltable>
1715<para>RETURNS
1716</para>
1717<informaltable><tgroup cols="2"><tbody><row><entry
1718 align="char">
1719<para>0</para>
1720</entry><entry
1721 align="char">
1722<para>Continue filtering.</para>
1723</entry>
1724 </row><row><entry
1725 align="char">
1726<para>-1</para>
1727</entry><entry
1728 align="char">
1729<para>Stop filtering - has the same effect as a call to
1730 stop_filtering() on the Section Feed API.</para>
1731</entry>
1732 </row></tbody></tgroup></informaltable>
1733 </section></section>
1734<section id="ts_feed_api">
1735<title>TS Feed API</title>
1736<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
1737Using this API, the client can set the filtering properties to start/stop filtering TS
1738packets on a particular TS feed. The API is defined as an abstract interface of the type
1739dmx_ts_feed_t.
1740</para>
1741<para>The functions that implement the interface should be defined static or module private. The
1742client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
1743demux API.
1744</para>
1745
1746<section
1747role="subsection"><title>set()</title>
1748<para>DESCRIPTION
1749</para>
1750<informaltable><tgroup cols="1"><tbody><row><entry
1751 align="char">
1752<para>This function sets the parameters of a TS feed. Any filtering in progress on the
1753 TS feed must be stopped before calling this function.</para>
1754</entry>
1755 </row></tbody></tgroup></informaltable>
1756<para>SYNOPSIS
1757</para>
1758<informaltable><tgroup cols="1"><tbody><row><entry
1759 align="char">
1760<para>int set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
1761 callback_length, size_t circular_buffer_size, int
1762 descramble, struct timespec timeout);</para>
1763</entry>
1764 </row></tbody></tgroup></informaltable>
1765<para>PARAMETERS
1766</para>
1767<informaltable><tgroup cols="2"><tbody><row><entry
1768 align="char">
1769<para>dmx_ts_feed_t* feed</para>
1770</entry><entry
1771 align="char">
1772<para>Pointer to the TS feed API and instance data.</para>
1773</entry>
1774 </row><row><entry
1775 align="char">
1776<para>__u16 pid</para>
1777</entry><entry
1778 align="char">
1779<para>PID value to filter. Only the TS packets carrying the
1780 specified PID will be passed to the API client.</para>
1781</entry>
1782 </row><row><entry
1783 align="char">
1784<para>size_t
1785 callback_length</para>
1786</entry><entry
1787 align="char">
1788<para>Number of bytes to deliver with each call to the
1789 dmx_ts_cb() callback function. The value of this
1790 parameter should be a multiple of 188.</para>
1791</entry>
1792 </row><row><entry
1793 align="char">
1794<para>size_t
1795 circular_buffer_size</para>
1796</entry><entry
1797 align="char">
1798<para>Size of the circular buffer for the filtered TS packets.</para>
1799</entry>
1800 </row><row><entry
1801 align="char">
1802<para>int descramble</para>
1803</entry><entry
1804 align="char">
1805<para>If non-zero, descramble the filtered TS packets.</para>
1806</entry>
1807 </row><row><entry
1808 align="char">
1809<para>struct timespec
1810 timeout</para>
1811</entry><entry
1812 align="char">
1813<para>Maximum time to wait before delivering received TS
1814 packets to the client.</para>
1815</entry>
1816 </row></tbody></tgroup></informaltable>
1817<para>RETURNS
1818</para>
1819<informaltable><tgroup cols="2"><tbody><row><entry
1820 align="char">
1821<para>0</para>
1822</entry><entry
1823 align="char">
1824<para>The function was completed without errors.</para>
1825</entry>
1826 </row><row><entry
1827 align="char">
1828<para>-ENOMEM</para>
1829</entry><entry
1830 align="char">
1831<para>Not enough memory for the requested buffer size.</para>
1832</entry>
1833 </row><row><entry
1834 align="char">
1835<para>-ENOSYS</para>
1836</entry><entry
1837 align="char">
1838<para>No descrambling facility available for TS.</para>
1839</entry>
1840 </row><row><entry
1841 align="char">
1842<para>-EINVAL</para>
1843</entry><entry
1844 align="char">
1845<para>Bad parameter.</para>
1846</entry>
1847 </row></tbody></tgroup></informaltable>
1848
1849</section><section
1850role="subsection"><title>start_filtering()</title>
1851<para>DESCRIPTION
1852</para>
1853<informaltable><tgroup cols="1"><tbody><row><entry
1854 align="char">
1855<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
1856 value to filter can be set by the API client. All matching TS packets are
1857 delivered asynchronously to the client, using the callback function registered
1858 with allocate_ts_feed().</para>
1859</entry>
1860 </row></tbody></tgroup></informaltable>
1861<para>SYNOPSIS
1862</para>
1863<informaltable><tgroup cols="1"><tbody><row><entry
1864 align="char">
1865<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1866</entry>
1867 </row></tbody></tgroup></informaltable>
1868<para>PARAMETERS
1869</para>
1870<informaltable><tgroup cols="2"><tbody><row><entry
1871 align="char">
1872<para>dmx_ts_feed_t* feed</para>
1873</entry><entry
1874 align="char">
1875<para>Pointer to the TS feed API and instance data.</para>
1876</entry>
1877 </row></tbody></tgroup></informaltable>
1878<para>RETURNS
1879</para>
1880<informaltable><tgroup cols="2"><tbody><row><entry
1881 align="char">
1882<para>0</para>
1883</entry><entry
1884 align="char">
1885<para>The function was completed without errors.</para>
1886</entry>
1887 </row><row><entry
1888 align="char">
1889<para>-EINVAL</para>
1890</entry><entry
1891 align="char">
1892<para>Bad parameter.</para>
1893</entry>
1894 </row></tbody></tgroup></informaltable>
1895
1896</section><section
1897role="subsection"><title>stop_filtering()</title>
1898<para>DESCRIPTION
1899</para>
1900<informaltable><tgroup cols="1"><tbody><row><entry
1901 align="char">
1902<para>Stops filtering TS packets on this TS feed.</para>
1903</entry>
1904 </row></tbody></tgroup></informaltable>
1905<para>SYNOPSIS
1906</para>
1907<informaltable><tgroup cols="1"><tbody><row><entry
1908 align="char">
1909<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1910</entry>
1911 </row></tbody></tgroup></informaltable>
1912<para>PARAMETERS
1913</para>
1914<informaltable><tgroup cols="2"><tbody><row><entry
1915 align="char">
1916<para>dmx_ts_feed_t* feed</para>
1917</entry><entry
1918 align="char">
1919<para>Pointer to the TS feed API and instance data.</para>
1920</entry>
1921 </row></tbody></tgroup></informaltable>
1922<para>RETURNS
1923</para>
1924<informaltable><tgroup cols="2"><tbody><row><entry
1925 align="char">
1926<para>0</para>
1927</entry><entry
1928 align="char">
1929<para>The function was completed without errors.</para>
1930</entry>
1931 </row><row><entry
1932 align="char">
1933<para>-EINVAL</para>
1934</entry><entry
1935 align="char">
1936<para>Bad parameter.</para>
1937</entry>
1938 </row></tbody></tgroup></informaltable>
1939 </section></section>
1940<section id="section_feed_api">
1941<title>Section Feed API</title>
1942<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
1943API, the client can set the properties of a section feed and to start/stop filtering. The API is
1944defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
1945the interface should be defined static or module private. The client can get the handle of
1946a section feed API by calling the function allocate_section_feed() in the demux
1947API.
1948</para>
1949<para>On demux platforms that provide section filtering in hardware, the Section Feed API
1950implementation provides a software wrapper for the demux hardware. Other platforms may
1951support only PID filtering in hardware, requiring that TS packets are converted to sections in
1952software. In the latter case the Section Feed API implementation can be a client of the TS
1953Feed API.
1954</para>
1955
1956</section>
1957<section id="kdapi_set">
1958<title>set()</title>
1959<para>DESCRIPTION
1960</para>
1961<informaltable><tgroup cols="1"><tbody><row><entry
1962 align="char">
1963<para>This function sets the parameters of a section feed. Any filtering in progress on
1964 the section feed must be stopped before calling this function. If descrambling
1965 is enabled, the payload_scrambling_control and address_scrambling_control
1966 fields of received DVB datagram sections should be observed. If either one is
1967 non-zero, the section should be descrambled either in hardware or using the
1968 functions descramble_mac_address() and descramble_section_payload() of the
1969 demux API. Note that according to the MPEG-2 Systems specification, only
1970 the payloads of private sections can be scrambled while the rest of the section
1971 data must be sent in the clear.</para>
1972</entry>
1973 </row></tbody></tgroup></informaltable>
1974<para>SYNOPSIS
1975</para>
1976<informaltable><tgroup cols="1"><tbody><row><entry
1977 align="char">
1978<para>int set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
1979 circular_buffer_size, int descramble, int
1980 check_crc);</para>
1981</entry>
1982 </row></tbody></tgroup></informaltable>
1983<para>PARAMETERS
1984</para>
1985<informaltable><tgroup cols="2"><tbody><row><entry
1986 align="char">
1987<para>dmx_section_feed_t*
1988 feed</para>
1989</entry><entry
1990 align="char">
1991<para>Pointer to the section feed API and instance data.</para>
1992</entry>
1993 </row><row><entry
1994 align="char">
1995<para>__u16 pid</para>
1996</entry><entry
1997 align="char">
1998<para>PID value to filter; only the TS packets carrying the
1999 specified PID will be accepted.</para>
2000</entry>
2001 </row><row><entry
2002 align="char">
2003<para>size_t
2004 circular_buffer_size</para>
2005</entry><entry
2006 align="char">
2007<para>Size of the circular buffer for filtered sections.</para>
2008</entry>
2009 </row><row><entry
2010 align="char">
2011<para>int descramble</para>
2012</entry><entry
2013 align="char">
2014<para>If non-zero, descramble any sections that are scrambled.</para>
2015</entry>
2016 </row><row><entry
2017 align="char">
2018<para>int check_crc</para>
2019</entry><entry
2020 align="char">
2021<para>If non-zero, check the CRC values of filtered sections.</para>
2022</entry>
2023 </row></tbody></tgroup></informaltable>
2024<para>RETURNS
2025</para>
2026<informaltable><tgroup cols="2"><tbody><row><entry
2027 align="char">
2028<para>0</para>
2029</entry><entry
2030 align="char">
2031<para>The function was completed without errors.</para>
2032</entry>
2033 </row><row><entry
2034 align="char">
2035<para>-ENOMEM</para>
2036</entry><entry
2037 align="char">
2038<para>Not enough memory for the requested buffer size.</para>
2039</entry>
2040 </row><row><entry
2041 align="char">
2042<para>-ENOSYS</para>
2043</entry><entry
2044 align="char">
2045<para>No descrambling facility available for sections.</para>
2046</entry>
2047 </row><row><entry
2048 align="char">
2049<para>-EINVAL</para>
2050</entry><entry
2051 align="char">
2052<para>Bad parameters.</para>
2053</entry>
2054 </row></tbody></tgroup></informaltable>
2055
2056</section><section
2057role="subsection"><title>allocate_filter()</title>
2058<para>DESCRIPTION
2059</para>
2060<informaltable><tgroup cols="1"><tbody><row><entry
2061 align="char">
2062<para>This function is used to allocate a section filter on the demux. It should only be
2063 called when no filtering is in progress on this section feed. If a filter cannot be
2064 allocated, the function fails with -ENOSPC. See in section ?? for the format of
2065 the section filter.</para>
2066</entry>
2067 </row><row><entry
2068 align="char">
2069<para>The bitfields filter_mask and filter_value should only be modified when no
2070 filtering is in progress on this section feed. filter_mask controls which bits of
2071 filter_value are compared with the section headers/payload. On a binary value
2072 of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
2073 sections that are equal to filter_value in all the tested bit positions. Any changes
2074 to the values of filter_mask and filter_value are guaranteed to take effect only
2075 when the start_filtering() function is called next time. The parent pointer in
2076 the struct is initialized by the API implementation to the value of the feed
2077 parameter. The priv pointer is not used by the API implementation, and can
2078 thus be freely utilized by the caller of this function. Any data pointed to by the
2079 priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
2080</entry>
2081 </row><row><entry
2082 align="char">
2083<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
2084 currently set at 16 bytes, hardware filters of that size are not available on all
2085 platforms. Therefore, section filtering will often take place first in hardware,
2086 followed by filtering in software for the header bytes that were not covered
2087 by a hardware filter. The filter_mask field can be checked to determine how
2088 many bytes of the section filter are actually used, and if the hardware filter will
2089 suffice. Additionally, software-only section filters can optionally be allocated
2090 to clients when all hardware section filters are in use. Note that on most demux
2091 hardware it is not possible to filter on the section_length field of the section
2092 header &#8211; thus this field is ignored, even though it is included in filter_value and
2093 filter_mask fields.</para>
2094</entry>
2095 </row></tbody></tgroup></informaltable>
2096<para>SYNOPSIS
2097</para>
2098<informaltable><tgroup cols="1"><tbody><row><entry
2099 align="char">
2100<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
2101 dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
2102</entry>
2103 </row></tbody></tgroup></informaltable>
2104<para>PARAMETERS
2105</para>
2106<informaltable><tgroup cols="2"><tbody><row><entry
2107 align="char">
2108<para>dmx_section_feed_t*
2109 feed</para>
2110</entry><entry
2111 align="char">
2112<para>Pointer to the section feed API and instance data.</para>
2113</entry>
2114 </row><row><entry
2115 align="char">
2116<para>dmx_section_filter_t**
2117 filter</para>
2118</entry><entry
2119 align="char">
2120<para>Pointer to the allocated filter.</para>
2121</entry>
2122 </row></tbody></tgroup></informaltable>
2123<para>RETURNS
2124</para>
2125<informaltable><tgroup cols="2"><tbody><row><entry
2126 align="char">
2127<para>0</para>
2128</entry><entry
2129 align="char">
2130<para>The function was completed without errors.</para>
2131</entry>
2132 </row><row><entry
2133 align="char">
2134<para>-ENOSPC</para>
2135</entry><entry
2136 align="char">
2137<para>No filters of given type and length available.</para>
2138</entry>
2139 </row><row><entry
2140 align="char">
2141<para>-EINVAL</para>
2142</entry><entry
2143 align="char">
2144<para>Bad parameters.</para>
2145</entry>
2146 </row></tbody></tgroup></informaltable>
2147
2148</section><section
2149role="subsection"><title>release_filter()</title>
2150<para>DESCRIPTION
2151</para>
2152<informaltable><tgroup cols="1"><tbody><row><entry
2153 align="char">
2154<para>This function releases all the resources of a previously allocated section filter.
2155 The function should not be called while filtering is in progress on this section
2156 feed. After calling this function, the caller should not try to dereference the
2157 filter pointer.</para>
2158</entry>
2159 </row></tbody></tgroup></informaltable>
2160<para>SYNOPSIS
2161</para>
2162<informaltable><tgroup cols="1"><tbody><row><entry
2163 align="char">
2164<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
2165 dmx_section_filter_t&#x22C6; filter);</para>
2166</entry>
2167 </row></tbody></tgroup></informaltable>
2168<para>PARAMETERS
2169</para>
2170<informaltable><tgroup cols="2"><tbody><row><entry
2171 align="char">
2172<para>dmx_section_feed_t*
2173 feed</para>
2174</entry><entry
2175 align="char">
2176<para>Pointer to the section feed API and instance data.</para>
2177</entry>
2178 </row><row><entry
2179 align="char">
2180<para>dmx_section_filter_t*
2181 filter</para>
2182</entry><entry
2183 align="char">
2184<para>I/O Pointer to the instance data of a section filter.</para>
2185</entry>
2186 </row></tbody></tgroup></informaltable>
2187<para>RETURNS
2188</para>
2189<informaltable><tgroup cols="2"><tbody><row><entry
2190 align="char">
2191<para>0</para>
2192</entry><entry
2193 align="char">
2194<para>The function was completed without errors.</para>
2195</entry>
2196 </row><row><entry
2197 align="char">
2198<para>-ENODEV</para>
2199</entry><entry
2200 align="char">
2201<para>No such filter allocated.</para>
2202</entry>
2203 </row><row><entry
2204 align="char">
2205<para>-EINVAL</para>
2206</entry><entry
2207 align="char">
2208<para>Bad parameter.</para>
2209</entry>
2210 </row></tbody></tgroup></informaltable>
2211
2212</section><section
2213role="subsection"><title>start_filtering()</title>
2214<para>DESCRIPTION
2215</para>
2216<informaltable><tgroup cols="1"><tbody><row><entry
2217 align="char">
2218<para>Starts filtering sections on this section feed, according to its settings. Sections
2219 are first filtered based on their PID and then matched with the section
2220 filters allocated for this feed. If the section matches the PID filter and
2221 at least one section filter, it is delivered to the API client. The section
2222 is delivered asynchronously using the callback function registered with
2223 allocate_section_feed().</para>
2224</entry>
2225 </row></tbody></tgroup></informaltable>
2226<para>SYNOPSIS
2227</para>
2228<informaltable><tgroup cols="1"><tbody><row><entry
2229 align="char">
2230<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2231</entry>
2232 </row></tbody></tgroup></informaltable>
2233<para>PARAMETERS
2234</para>
2235<informaltable><tgroup cols="2"><tbody><row><entry
2236 align="char">
2237<para>dmx_section_feed_t*
2238 feed</para>
2239</entry><entry
2240 align="char">
2241<para>Pointer to the section feed API and instance data.</para>
2242</entry>
2243 </row></tbody></tgroup></informaltable>
2244<para>RETURNS
2245</para>
2246<informaltable><tgroup cols="2"><tbody><row><entry
2247 align="char">
2248<para>0</para>
2249</entry><entry
2250 align="char">
2251<para>The function was completed without errors.</para>
2252</entry>
2253 </row><row><entry
2254 align="char">
2255<para>-EINVAL</para>
2256</entry><entry
2257 align="char">
2258<para>Bad parameter.</para>
2259</entry>
2260 </row></tbody></tgroup></informaltable>
2261
2262</section><section
2263role="subsection"><title>stop_filtering()</title>
2264<para>DESCRIPTION
2265</para>
2266<informaltable><tgroup cols="1"><tbody><row><entry
2267 align="char">
2268<para>Stops filtering sections on this section feed. Note that any changes to the
2269 filtering parameters (filter_value, filter_mask, etc.) should only be made when
2270 filtering is stopped.</para>
2271</entry>
2272 </row></tbody></tgroup></informaltable>
2273<para>SYNOPSIS
2274</para>
2275<informaltable><tgroup cols="1"><tbody><row><entry
2276 align="char">
2277<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2278</entry>
2279 </row></tbody></tgroup></informaltable>
2280<para>PARAMETERS
2281</para>
2282<informaltable><tgroup cols="2"><tbody><row><entry
2283 align="char">
2284<para>dmx_section_feed_t*
2285 feed</para>
2286</entry><entry
2287 align="char">
2288<para>Pointer to the section feed API and instance data.</para>
2289</entry>
2290 </row></tbody></tgroup></informaltable>
2291<para>RETURNS
2292</para>
2293<informaltable><tgroup cols="2"><tbody><row><entry
2294 align="char">
2295<para>0</para>
2296</entry><entry
2297 align="char">
2298<para>The function was completed without errors.</para>
2299</entry>
2300 </row><row><entry
2301 align="char">
2302<para>-EINVAL</para>
2303</entry><entry
2304 align="char">
2305<para>Bad parameter.</para>
2306</entry>
2307 </row></tbody></tgroup></informaltable>
2308
2309</section>
diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml
new file mode 100644
index 00000000000..a193e86941b
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/net.xml
@@ -0,0 +1,156 @@
1<title>DVB Network API</title>
2<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
3received via DVB into the Linux network protocol stack, e.g. for internet via satellite
4applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
5and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
6application.
7</para>
8<section id="dvb_net_types">
9<title>DVB Net Data Types</title>
10
11<section id="dvb-net-if">
12<title>struct dvb_net_if</title>
13<programlisting>
14struct dvb_net_if {
15 __u16 pid;
16 __u16 if_num;
17 __u8 feedtype;
18#define DVB_NET_FEEDTYPE_MPE 0 /&#x22C6; multi protocol encapsulation &#x22C6;/
19#define DVB_NET_FEEDTYPE_ULE 1 /&#x22C6; ultra lightweight encapsulation &#x22C6;/
20};
21</programlisting>
22</section>
23
24</section>
25<section id="net_fcalls">
26<title>DVB net Function Calls</title>
27<para>To be written&#x2026;
28</para>
29
30<section id="NET_ADD_IF"
31role="subsection"><title>NET_ADD_IF</title>
32<para>DESCRIPTION
33</para>
34<informaltable><tgroup cols="1"><tbody><row><entry
35 align="char">
36<para>This ioctl is undocumented. Documentation is welcome.</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(fd, int request = NET_ADD_IF,
44 struct dvb_net_if *if);</para>
45</entry>
46 </row></tbody></tgroup></informaltable>
47<para>PARAMETERS
48</para>
49<informaltable><tgroup cols="2"><tbody><row><entry
50 align="char">
51<para>int fd</para>
52</entry><entry
53 align="char">
54<para>File descriptor returned by a previous call to open().</para>
55</entry>
56 </row><row><entry
57 align="char">
58<para>int request</para>
59</entry><entry
60 align="char">
61<para>Equals NET_ADD_IF for this command.</para>
62</entry>
63 </row><row><entry
64 align="char">
65<para>struct dvb_net_if *if
66</para>
67</entry><entry
68 align="char">
69<para>Undocumented.</para>
70</entry>
71 </row></tbody></tgroup></informaltable>
72&return-value-dvb;
73</section>
74
75<section id="NET_REMOVE_IF"
76role="subsection"><title>NET_REMOVE_IF</title>
77<para>DESCRIPTION
78</para>
79<informaltable><tgroup cols="1"><tbody><row><entry
80 align="char">
81<para>This ioctl is undocumented. Documentation is welcome.</para>
82</entry>
83 </row></tbody></tgroup></informaltable>
84<para>SYNOPSIS
85</para>
86<informaltable><tgroup cols="1"><tbody><row><entry
87 align="char">
88<para>int ioctl(fd, int request = NET_REMOVE_IF);
89</para>
90</entry>
91 </row></tbody></tgroup></informaltable>
92<para>PARAMETERS
93</para>
94<informaltable><tgroup cols="2"><tbody><row><entry
95 align="char">
96<para>int fd</para>
97</entry><entry
98 align="char">
99<para>File descriptor returned by a previous call to open().</para>
100</entry>
101 </row><row><entry
102 align="char">
103<para>int request</para>
104</entry><entry
105 align="char">
106<para>Equals NET_REMOVE_IF for this command.</para>
107</entry>
108 </row></tbody></tgroup></informaltable>
109&return-value-dvb;
110</section>
111
112<section id="NET_GET_IF"
113role="subsection"><title>NET_GET_IF</title>
114<para>DESCRIPTION
115</para>
116<informaltable><tgroup cols="1"><tbody><row><entry
117 align="char">
118<para>This ioctl is undocumented. Documentation is welcome.</para>
119</entry>
120 </row></tbody></tgroup></informaltable>
121<para>SYNOPSIS
122</para>
123<informaltable><tgroup cols="1"><tbody><row><entry
124 align="char">
125<para>int ioctl(fd, int request = NET_GET_IF,
126 struct dvb_net_if *if);</para>
127</entry>
128 </row></tbody></tgroup></informaltable>
129<para>PARAMETERS
130</para>
131<informaltable><tgroup cols="2"><tbody><row><entry
132 align="char">
133<para>int fd</para>
134</entry><entry
135 align="char">
136<para>File descriptor returned by a previous call to open().</para>
137</entry>
138 </row><row><entry
139 align="char">
140<para>int request</para>
141</entry><entry
142 align="char">
143<para>Equals NET_GET_IF for this command.</para>
144</entry>
145 </row><row><entry
146 align="char">
147<para>struct dvb_net_if *if
148</para>
149</entry><entry
150 align="char">
151<para>Undocumented.</para>
152</entry>
153 </row></tbody></tgroup></informaltable>
154&return-value-dvb;
155</section>
156</section>
diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml
new file mode 100644
index 00000000000..3ea1ca7e785
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/video.xml
@@ -0,0 +1,1968 @@
1<title>DVB Video Device</title>
2<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
5application.
6</para>
7<para>Note that the DVB video device only controls decoding of the MPEG video stream, not
8its presentation on the TV or computer screen. On PCs this is typically handled by an
9associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output
10windows.
11</para>
12<para>Some DVB cards don&#8217;t have their own MPEG decoder, which results in the omission of
13the audio and video device as well as the video4linux device.
14</para>
15<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only
16supported on some MPEG decoders made for DVD playback.
17</para>
18<para>
19These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use
20of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls
21have been created to replace that functionality.</para>
22<section id="video_types">
23<title>Video Data Types</title>
24
25<section id="video-format-t">
26<title>video_format_t</title>
27<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by
28</para>
29<programlisting>
30typedef enum {
31 VIDEO_FORMAT_4_3, /&#x22C6; Select 4:3 format &#x22C6;/
32 VIDEO_FORMAT_16_9, /&#x22C6; Select 16:9 format. &#x22C6;/
33 VIDEO_FORMAT_221_1 /&#x22C6; 2.21:1 &#x22C6;/
34} video_format_t;
35</programlisting>
36<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio
37the output hardware (e.g. TV) has. It is also used in the data structures video_status
38(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by
39VIDEO_GET_EVENT (??) which report about the display format of the current video
40stream.
41</para>
42</section>
43
44<section id="video-displayformat-t">
45<title>video_displayformat_t</title>
46<para>In case the display format of the video stream and of the display hardware differ the
47application has to specify how to handle the cropping of the picture. This can be done using
48the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
49</para>
50<programlisting>
51typedef enum {
52 VIDEO_PAN_SCAN, /&#x22C6; use pan and scan format &#x22C6;/
53 VIDEO_LETTER_BOX, /&#x22C6; use letterbox format &#x22C6;/
54 VIDEO_CENTER_CUT_OUT /&#x22C6; use center cut out format &#x22C6;/
55} video_displayformat_t;
56</programlisting>
57<para>as argument.
58</para>
59</section>
60
61<section id="video-stream-source-t">
62<title>video_stream_source_t</title>
63<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take
64the following values, depending on whether we are replaying from an internal (demuxer) or
65external (user write) source.
66</para>
67<programlisting>
68typedef enum {
69 VIDEO_SOURCE_DEMUX, /&#x22C6; Select the demux as the main source &#x22C6;/
70 VIDEO_SOURCE_MEMORY /&#x22C6; If this source is selected, the stream
71 comes from the user through the write
72 system call &#x22C6;/
73} video_stream_source_t;
74</programlisting>
75<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
76DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY
77is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
78call.
79</para>
80</section>
81
82<section id="video-play-state-t">
83<title>video_play_state_t</title>
84<para>The following values can be returned by the VIDEO_GET_STATUS call representing the
85state of video playback.
86</para>
87<programlisting>
88typedef enum {
89 VIDEO_STOPPED, /&#x22C6; Video is stopped &#x22C6;/
90 VIDEO_PLAYING, /&#x22C6; Video is currently playing &#x22C6;/
91 VIDEO_FREEZED /&#x22C6; Video is freezed &#x22C6;/
92} video_play_state_t;
93</programlisting>
94</section>
95
96<section id="video-command">
97<title>struct video_command</title>
98<para>The structure must be zeroed before use by the application
99This ensures it can be extended safely in the future.</para>
100<programlisting>
101struct video_command {
102 __u32 cmd;
103 __u32 flags;
104 union {
105 struct {
106 __u64 pts;
107 } stop;
108
109 struct {
110 /&#x22C6; 0 or 1000 specifies normal speed,
111 1 specifies forward single stepping,
112 -1 specifies backward single stepping,
113 &gt;>1: playback at speed/1000 of the normal speed,
114 &lt;-1: reverse playback at (-speed/1000) of the normal speed. &#x22C6;/
115 __s32 speed;
116 __u32 format;
117 } play;
118
119 struct {
120 __u32 data[16];
121 } raw;
122 };
123};
124</programlisting>
125</section>
126
127<section id="video-size-t">
128<title>video_size_t</title>
129<programlisting>
130typedef struct {
131 int w;
132 int h;
133 video_format_t aspect_ratio;
134} video_size_t;
135</programlisting>
136</section>
137
138
139<section id="video-event">
140<title>struct video_event</title>
141<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT
142call.
143</para>
144<programlisting>
145struct video_event {
146 __s32 type;
147#define VIDEO_EVENT_SIZE_CHANGED 1
148#define VIDEO_EVENT_FRAME_RATE_CHANGED 2
149#define VIDEO_EVENT_DECODER_STOPPED 3
150#define VIDEO_EVENT_VSYNC 4
151 __kernel_time_t timestamp;
152 union {
153 video_size_t size;
154 unsigned int frame_rate; /&#x22C6; in frames per 1000sec &#x22C6;/
155 unsigned char vsync_field; /&#x22C6; unknown/odd/even/progressive &#x22C6;/
156 } u;
157};
158</programlisting>
159</section>
160
161<section id="video-status">
162<title>struct video_status</title>
163<para>The VIDEO_GET_STATUS call returns the following structure informing about various
164states of the playback operation.
165</para>
166<programlisting>
167struct video_status {
168 int video_blank; /&#x22C6; blank video on freeze? &#x22C6;/
169 video_play_state_t play_state; /&#x22C6; current state of playback &#x22C6;/
170 video_stream_source_t stream_source; /&#x22C6; current source (demux/memory) &#x22C6;/
171 video_format_t video_format; /&#x22C6; current aspect ratio of stream &#x22C6;/
172 video_displayformat_t display_format;/&#x22C6; selected cropping mode &#x22C6;/
173};
174</programlisting>
175<para>If video_blank is set video will be blanked out if the channel is changed or if playback is
176stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is
177currently frozen, stopped, or being played back. The stream_source corresponds to the seleted
178source for the video stream. It can come either from the demultiplexer or from memory.
179The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently
180played video stream. Finally, display_format corresponds to the selected cropping
181mode in case the source video format is not the same as the format of the output
182device.
183</para>
184</section>
185
186<section id="video-still-picture">
187<title>struct video_still_picture</title>
188<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the
189following structure.
190</para>
191<programlisting>
192/&#x22C6; pointer to and size of a single iframe in memory &#x22C6;/
193struct video_still_picture {
194 char &#x22C6;iFrame; /&#x22C6; pointer to a single iframe in memory &#x22C6;/
195 int32_t size;
196};
197</programlisting>
198</section>
199
200<section id="video_caps">
201<title>video capabilities</title>
202<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following
203bits set according to the hardwares capabilities.
204</para>
205<programlisting>
206 /&#x22C6; bit definitions for capabilities: &#x22C6;/
207 /&#x22C6; can the hardware decode MPEG1 and/or MPEG2? &#x22C6;/
208 #define VIDEO_CAP_MPEG1 1
209 #define VIDEO_CAP_MPEG2 2
210 /&#x22C6; can you send a system and/or program stream to video device?
211 (you still have to open the video and the audio device but only
212 send the stream to the video device) &#x22C6;/
213 #define VIDEO_CAP_SYS 4
214 #define VIDEO_CAP_PROG 8
215 /&#x22C6; can the driver also handle SPU, NAVI and CSS encoded data?
216 (CSS API is not present yet) &#x22C6;/
217 #define VIDEO_CAP_SPU 16
218 #define VIDEO_CAP_NAVI 32
219 #define VIDEO_CAP_CSS 64
220</programlisting>
221</section>
222
223<section id="video-system">
224<title>video_system_t</title>
225<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The
226following system types can be set:
227</para>
228<programlisting>
229typedef enum {
230 VIDEO_SYSTEM_PAL,
231 VIDEO_SYSTEM_NTSC,
232 VIDEO_SYSTEM_PALN,
233 VIDEO_SYSTEM_PALNc,
234 VIDEO_SYSTEM_PALM,
235 VIDEO_SYSTEM_NTSC60,
236 VIDEO_SYSTEM_PAL60,
237 VIDEO_SYSTEM_PALM60
238} video_system_t;
239</programlisting>
240</section>
241
242<section id="video-highlight">
243<title>struct video_highlight</title>
244<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The
245call expects the following format for that information:
246</para>
247<programlisting>
248 typedef
249 struct video_highlight {
250 boolean active; /&#x22C6; 1=show highlight, 0=hide highlight &#x22C6;/
251 uint8_t contrast1; /&#x22C6; 7- 4 Pattern pixel contrast &#x22C6;/
252 /&#x22C6; 3- 0 Background pixel contrast &#x22C6;/
253 uint8_t contrast2; /&#x22C6; 7- 4 Emphasis pixel-2 contrast &#x22C6;/
254 /&#x22C6; 3- 0 Emphasis pixel-1 contrast &#x22C6;/
255 uint8_t color1; /&#x22C6; 7- 4 Pattern pixel color &#x22C6;/
256 /&#x22C6; 3- 0 Background pixel color &#x22C6;/
257 uint8_t color2; /&#x22C6; 7- 4 Emphasis pixel-2 color &#x22C6;/
258 /&#x22C6; 3- 0 Emphasis pixel-1 color &#x22C6;/
259 uint32_t ypos; /&#x22C6; 23-22 auto action mode &#x22C6;/
260 /&#x22C6; 21-12 start y &#x22C6;/
261 /&#x22C6; 9- 0 end y &#x22C6;/
262 uint32_t xpos; /&#x22C6; 23-22 button color number &#x22C6;/
263 /&#x22C6; 21-12 start x &#x22C6;/
264 /&#x22C6; 9- 0 end x &#x22C6;/
265 } video_highlight_t;
266</programlisting>
267
268</section>
269<section id="video-spu">
270<title>struct video_spu</title>
271<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the
272following format:
273</para>
274<programlisting>
275 typedef
276 struct video_spu {
277 boolean active;
278 int stream_id;
279 } video_spu_t;
280</programlisting>
281
282</section>
283<section id="video-spu-palette">
284<title>struct video_spu_palette</title>
285<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE:
286</para>
287<programlisting>
288 typedef
289 struct video_spu_palette {
290 int length;
291 uint8_t &#x22C6;palette;
292 } video_spu_palette_t;
293</programlisting>
294
295</section>
296<section id="video-navi-pack">
297<title>struct video_navi_pack</title>
298<para>In order to get the navigational data the following structure has to be passed to the ioctl
299VIDEO_GET_NAVI:
300</para>
301<programlisting>
302 typedef
303 struct video_navi_pack {
304 int length; /&#x22C6; 0 ... 1024 &#x22C6;/
305 uint8_t data[1024];
306 } video_navi_pack_t;
307</programlisting>
308</section>
309
310
311<section id="video-attributes-t">
312<title>video_attributes_t</title>
313<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
314</para>
315<programlisting>
316 typedef uint16_t video_attributes_t;
317 /&#x22C6; bits: descr. &#x22C6;/
318 /&#x22C6; 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) &#x22C6;/
319 /&#x22C6; 13-12 TV system (0=525/60, 1=625/50) &#x22C6;/
320 /&#x22C6; 11-10 Aspect ratio (0=4:3, 3=16:9) &#x22C6;/
321 /&#x22C6; 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca &#x22C6;/
322 /&#x22C6; 7 line 21-1 data present in GOP (1=yes, 0=no) &#x22C6;/
323 /&#x22C6; 6 line 21-2 data present in GOP (1=yes, 0=no) &#x22C6;/
324 /&#x22C6; 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 &#x22C6;/
325 /&#x22C6; 2 source letterboxed (1=yes, 0=no) &#x22C6;/
326 /&#x22C6; 0 film/camera mode (0=camera, 1=film (625/50 only)) &#x22C6;/
327</programlisting>
328</section></section>
329
330
331<section id="video_function_calls">
332<title>Video Function Calls</title>
333
334
335<section id="video_fopen">
336<title>open()</title>
337<para>DESCRIPTION
338</para>
339<informaltable><tgroup cols="1"><tbody><row><entry
340 align="char">
341<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0)
342 for subsequent use.</para>
343<para>When an open() call has succeeded, the device will be ready for use.
344 The significance of blocking or non-blocking mode is described in the
345 documentation for functions where there is a difference. It does not affect the
346 semantics of the open() call itself. A device opened in blocking mode can later
347 be put into non-blocking mode (and vice versa) using the F_SETFL command
348 of the fcntl system call. This is a standard system call, documented in the Linux
349 manual page for fcntl. Only one user can open the Video Device in O_RDWR
350 mode. All other attempts to open the device in this mode will fail, and an
351 error-code will be returned. If the Video Device is opened in O_RDONLY
352 mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other
353 call will return an error code.</para>
354</entry>
355 </row></tbody></tgroup></informaltable>
356
357<para>SYNOPSIS
358</para>
359<informaltable><tgroup cols="1"><tbody><row><entry
360 align="char">
361<para>int open(const char &#x22C6;deviceName, int flags);</para>
362</entry>
363 </row></tbody></tgroup></informaltable>
364<para>PARAMETERS
365</para>
366<informaltable><tgroup cols="2"><tbody><row><entry
367 align="char">
368<para>const char
369 *deviceName</para>
370</entry><entry
371 align="char">
372<para>Name of specific video device.</para>
373</entry>
374 </row><row><entry
375 align="char">
376<para>int flags</para>
377</entry><entry
378 align="char">
379<para>A bit-wise OR of the following flags:</para>
380</entry>
381 </row><row><entry
382 align="char">
383</entry><entry
384 align="char">
385<para>O_RDONLY read-only access</para>
386</entry>
387 </row><row><entry
388 align="char">
389</entry><entry
390 align="char">
391<para>O_RDWR read/write access</para>
392</entry>
393 </row><row><entry
394 align="char">
395</entry><entry
396 align="char">
397<para>O_NONBLOCK open in non-blocking mode</para>
398</entry>
399 </row><row><entry
400 align="char">
401</entry><entry
402 align="char">
403<para>(blocking mode is the default)</para>
404</entry>
405 </row></tbody></tgroup></informaltable>
406<para>RETURN VALUE</para>
407<informaltable><tgroup cols="2"><tbody><row><entry
408 align="char">
409<para>ENODEV</para>
410</entry><entry
411 align="char">
412<para>Device driver not loaded/available.</para>
413</entry>
414 </row><row><entry
415 align="char">
416<para>EINTERNAL</para>
417</entry><entry
418 align="char">
419<para>Internal error.</para>
420</entry>
421 </row><row><entry
422 align="char">
423<para>EBUSY</para>
424</entry><entry
425 align="char">
426<para>Device or resource busy.</para>
427</entry>
428 </row><row><entry
429 align="char">
430<para>EINVAL</para>
431</entry><entry
432 align="char">
433<para>Invalid argument.</para>
434</entry>
435 </row></tbody></tgroup></informaltable>
436
437</section>
438<section id="video_fclose">
439<title>close()</title>
440<para>DESCRIPTION
441</para>
442<informaltable><tgroup cols="1"><tbody><row><entry
443 align="char">
444<para>This system call closes a previously opened video device.</para>
445</entry>
446 </row></tbody></tgroup></informaltable>
447<para>SYNOPSIS
448</para>
449<informaltable><tgroup cols="1"><tbody><row><entry
450 align="char">
451<para>int close(int fd);</para>
452</entry>
453 </row></tbody></tgroup></informaltable>
454<para>PARAMETERS
455</para>
456<informaltable><tgroup cols="2"><tbody><row><entry
457 align="char">
458<para>int fd</para>
459</entry><entry
460 align="char">
461<para>File descriptor returned by a previous call to open().</para>
462</entry>
463 </row></tbody></tgroup></informaltable>
464<para>RETURN VALUE</para>
465<informaltable><tgroup cols="2"><tbody><row><entry
466 align="char">
467<para>EBADF</para>
468</entry><entry
469 align="char">
470<para>fd is not a valid open file descriptor.</para>
471</entry>
472 </row></tbody></tgroup></informaltable>
473
474</section>
475<section id="video_fwrite">
476<title>write()</title>
477<para>DESCRIPTION
478</para>
479<informaltable><tgroup cols="1"><tbody><row><entry
480 align="char">
481<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected
482 in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
483 PES format, unless the capability allows other formats. If O_NONBLOCK is
484 not specified the function will block until buffer space is available. The amount
485 of data to be transferred is implied by count.</para>
486</entry>
487 </row></tbody></tgroup></informaltable>
488<para>SYNOPSIS
489</para>
490<informaltable><tgroup cols="1"><tbody><row><entry
491 align="char">
492<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
493</entry>
494 </row></tbody></tgroup></informaltable>
495<para>PARAMETERS
496</para>
497<informaltable><tgroup cols="2"><tbody><row><entry
498 align="char">
499<para>int fd</para>
500</entry><entry
501 align="char">
502<para>File descriptor returned by a previous call to open().</para>
503</entry>
504 </row><row><entry
505 align="char">
506<para>void *buf</para>
507</entry><entry
508 align="char">
509<para>Pointer to the buffer containing the PES data.</para>
510</entry>
511 </row><row><entry
512 align="char">
513<para>size_t count</para>
514</entry><entry
515 align="char">
516<para>Size of buf.</para>
517</entry>
518 </row></tbody></tgroup></informaltable>
519<para>RETURN VALUE</para>
520<informaltable><tgroup cols="2"><tbody><row><entry
521 align="char">
522<para>EPERM</para>
523</entry><entry
524 align="char">
525<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
526</entry>
527 </row><row><entry
528 align="char">
529<para>ENOMEM</para>
530</entry><entry
531 align="char">
532<para>Attempted to write more data than the internal buffer can
533 hold.</para>
534</entry>
535 </row><row><entry
536 align="char">
537<para>EBADF</para>
538</entry><entry
539 align="char">
540<para>fd is not a valid open file descriptor.</para>
541</entry>
542 </row></tbody></tgroup></informaltable>
543
544</section><section id="VIDEO_STOP"
545role="subsection"><title>VIDEO_STOP</title>
546<para>DESCRIPTION
547</para>
548<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
549&VIDIOC-DECODER-CMD; instead.</para>
550<informaltable><tgroup cols="1"><tbody><row><entry
551 align="char">
552<para>This ioctl call asks the Video Device to stop playing the current stream.
553 Depending on the input parameter, the screen can be blanked out or displaying
554 the last decoded frame.</para>
555</entry>
556 </row></tbody></tgroup></informaltable>
557<para>SYNOPSIS
558</para>
559<informaltable><tgroup cols="1"><tbody><row><entry
560 align="char">
561<para>int ioctl(fd, int request = VIDEO_STOP, boolean
562 mode);</para>
563</entry>
564 </row></tbody></tgroup></informaltable>
565<para>PARAMETERS
566</para>
567<informaltable><tgroup cols="2"><tbody><row><entry
568 align="char">
569<para>int fd</para>
570</entry><entry
571 align="char">
572<para>File descriptor returned by a previous call to open().</para>
573</entry>
574 </row><row><entry
575 align="char">
576<para>int request</para>
577</entry><entry
578 align="char">
579<para>Equals VIDEO_STOP for this command.</para>
580</entry>
581 </row><row><entry
582 align="char">
583<para>Boolean mode</para>
584</entry><entry
585 align="char">
586<para>Indicates how the screen shall be handled.</para>
587</entry>
588 </row><row><entry
589 align="char">
590</entry><entry
591 align="char">
592<para>TRUE: Blank screen when stop.</para>
593</entry>
594 </row><row><entry
595 align="char">
596</entry><entry
597 align="char">
598<para>FALSE: Show last decoded frame.</para>
599</entry>
600 </row></tbody></tgroup></informaltable>
601&return-value-dvb;
602
603</section><section id="VIDEO_PLAY"
604role="subsection"><title>VIDEO_PLAY</title>
605<para>DESCRIPTION
606</para>
607<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
608&VIDIOC-DECODER-CMD; instead.</para>
609<informaltable><tgroup cols="1"><tbody><row><entry
610 align="char">
611<para>This ioctl call asks the Video Device to start playing a video stream from the
612 selected source.</para>
613</entry>
614 </row></tbody></tgroup></informaltable>
615<para>SYNOPSIS
616</para>
617<informaltable><tgroup cols="1"><tbody><row><entry
618 align="char">
619<para>int ioctl(fd, int request = VIDEO_PLAY);</para>
620</entry>
621 </row></tbody></tgroup></informaltable>
622<para>PARAMETERS
623</para>
624<informaltable><tgroup cols="2"><tbody><row><entry
625 align="char">
626<para>int fd</para>
627</entry><entry
628 align="char">
629<para>File descriptor returned by a previous call to open().</para>
630</entry>
631 </row><row><entry
632 align="char">
633<para>int request</para>
634</entry><entry
635 align="char">
636<para>Equals VIDEO_PLAY for this command.</para>
637</entry>
638 </row></tbody></tgroup></informaltable>
639&return-value-dvb;
640
641</section><section id="VIDEO_FREEZE"
642role="subsection"><title>VIDEO_FREEZE</title>
643<para>DESCRIPTION
644</para>
645<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
646&VIDIOC-DECODER-CMD; instead.</para>
647<informaltable><tgroup cols="1"><tbody><row><entry
648 align="char">
649<para>This ioctl call suspends the live video stream being played. Decoding
650 and playing are frozen. It is then possible to restart the decoding
651 and playing process of the video stream using the VIDEO_CONTINUE
652 command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call
653 VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more
654 data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para>
655</entry>
656 </row></tbody></tgroup></informaltable>
657<para>SYNOPSIS
658</para>
659<informaltable><tgroup cols="1"><tbody><row><entry
660 align="char">
661<para>int ioctl(fd, int request = VIDEO_FREEZE);</para>
662</entry>
663 </row></tbody></tgroup></informaltable>
664<para>PARAMETERS
665</para>
666<informaltable><tgroup cols="2"><tbody><row><entry
667 align="char">
668<para>int fd</para>
669</entry><entry
670 align="char">
671<para>File descriptor returned by a previous call to open().</para>
672</entry>
673 </row><row><entry
674 align="char">
675<para>int request</para>
676</entry><entry
677 align="char">
678<para>Equals VIDEO_FREEZE for this command.</para>
679</entry>
680 </row></tbody></tgroup></informaltable>
681&return-value-dvb;
682
683</section><section id="VIDEO_CONTINUE"
684role="subsection"><title>VIDEO_CONTINUE</title>
685<para>DESCRIPTION
686</para>
687<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
688&VIDIOC-DECODER-CMD; instead.</para>
689<informaltable><tgroup cols="1"><tbody><row><entry
690 align="char">
691<para>This ioctl call restarts decoding and playing processes of the video stream
692 which was played before a call to VIDEO_FREEZE was made.</para>
693</entry>
694 </row></tbody></tgroup></informaltable>
695<para>SYNOPSIS
696</para>
697<informaltable><tgroup cols="1"><tbody><row><entry
698 align="char">
699<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para>
700</entry>
701 </row></tbody></tgroup></informaltable>
702<para>PARAMETERS
703</para>
704<informaltable><tgroup cols="2"><tbody><row><entry
705 align="char">
706<para>int fd</para>
707</entry><entry
708 align="char">
709<para>File descriptor returned by a previous call to open().</para>
710</entry>
711 </row><row><entry
712 align="char">
713<para>int request</para>
714</entry><entry
715 align="char">
716<para>Equals VIDEO_CONTINUE for this command.</para>
717</entry>
718 </row></tbody></tgroup></informaltable>
719&return-value-dvb;
720
721</section><section id="VIDEO_SELECT_SOURCE"
722role="subsection"><title>VIDEO_SELECT_SOURCE</title>
723<para>DESCRIPTION
724</para>
725<para>This ioctl is for DVB devices only. This ioctl was also supported by the
726V4L2 ivtv driver, but that has been replaced by the ivtv-specific
727<constant>IVTV_IOC_PASSTHROUGH_MODE</constant> ioctl.</para>
728<informaltable><tgroup cols="1"><tbody><row><entry
729 align="char">
730<para>This ioctl call informs the video device which source shall be used for the input
731 data. The possible sources are demux or memory. If memory is selected, the
732 data is fed to the video device through the write command.</para>
733</entry>
734 </row></tbody></tgroup></informaltable>
735<para>SYNOPSIS
736</para>
737<informaltable><tgroup cols="1"><tbody><row><entry
738 align="char">
739<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
740 video_stream_source_t source);</para>
741</entry>
742 </row></tbody></tgroup></informaltable>
743<para>PARAMETERS
744</para>
745<informaltable><tgroup cols="2"><tbody><row><entry
746 align="char">
747<para>int fd</para>
748</entry><entry
749 align="char">
750<para>File descriptor returned by a previous call to open().</para>
751</entry>
752 </row><row><entry
753 align="char">
754<para>int request</para>
755</entry><entry
756 align="char">
757<para>Equals VIDEO_SELECT_SOURCE for this command.</para>
758</entry>
759 </row><row><entry
760 align="char">
761<para>video_stream_source_t
762 source</para>
763</entry><entry
764 align="char">
765<para>Indicates which source shall be used for the Video stream.</para>
766</entry>
767 </row></tbody></tgroup></informaltable>
768&return-value-dvb;
769
770</section><section id="VIDEO_SET_BLANK"
771role="subsection"><title>VIDEO_SET_BLANK</title>
772<para>DESCRIPTION
773</para>
774<informaltable><tgroup cols="1"><tbody><row><entry
775 align="char">
776<para>This ioctl call asks the Video Device to blank out the picture.</para>
777</entry>
778 </row></tbody></tgroup></informaltable>
779<para>SYNOPSIS
780</para>
781<informaltable><tgroup cols="1"><tbody><row><entry
782 align="char">
783<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean
784 mode);</para>
785</entry>
786 </row></tbody></tgroup></informaltable>
787<para>PARAMETERS
788</para>
789<informaltable><tgroup cols="2"><tbody><row><entry
790 align="char">
791<para>int fd</para>
792</entry><entry
793 align="char">
794<para>File descriptor returned by a previous call to open().</para>
795</entry>
796 </row><row><entry
797 align="char">
798<para>int request</para>
799</entry><entry
800 align="char">
801<para>Equals VIDEO_SET_BLANK for this command.</para>
802</entry>
803 </row><row><entry
804 align="char">
805<para>boolean mode</para>
806</entry><entry
807 align="char">
808<para>TRUE: Blank screen when stop.</para>
809</entry>
810 </row><row><entry
811 align="char">
812</entry><entry
813 align="char">
814<para>FALSE: Show last decoded frame.</para>
815</entry>
816 </row></tbody></tgroup></informaltable>
817&return-value-dvb;
818
819</section><section id="VIDEO_GET_STATUS"
820role="subsection"><title>VIDEO_GET_STATUS</title>
821<para>DESCRIPTION
822</para>
823<informaltable><tgroup cols="1"><tbody><row><entry
824 align="char">
825<para>This ioctl call asks the Video Device to return the current status of the device.</para>
826</entry>
827 </row></tbody></tgroup></informaltable>
828<para>SYNOPSIS
829</para>
830<informaltable><tgroup cols="1"><tbody><row><entry
831 align="char">
832<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct
833 video_status &#x22C6;status);</para>
834</entry>
835 </row></tbody></tgroup></informaltable>
836<para>PARAMETERS
837</para>
838<informaltable><tgroup cols="2"><tbody><row><entry
839 align="char">
840<para>int fd</para>
841</entry><entry
842 align="char">
843<para>File descriptor returned by a previous call to open().</para>
844</entry>
845 </row><row><entry
846 align="char">
847<para>int request</para>
848</entry><entry
849 align="char">
850<para>Equals VIDEO_GET_STATUS for this command.</para>
851</entry>
852 </row><row><entry
853 align="char">
854<para>struct video_status
855 *status</para>
856</entry><entry
857 align="char">
858<para>Returns the current status of the Video Device.</para>
859</entry>
860 </row></tbody></tgroup></informaltable>
861&return-value-dvb;
862
863</section><section id="VIDEO_GET_FRAME_COUNT"
864role="subsection"><title>VIDEO_GET_FRAME_COUNT</title>
865<para>DESCRIPTION
866</para>
867<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
868ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> control.</para>
869<informaltable><tgroup cols="1"><tbody><row><entry
870 align="char">
871<para>This ioctl call asks the Video Device to return the number of displayed frames
872since the decoder was started.</para>
873</entry>
874 </row></tbody></tgroup></informaltable>
875<para>SYNOPSIS
876</para>
877<informaltable><tgroup cols="1"><tbody><row><entry
878 align="char">
879<para>int ioctl(int fd, int request =
880 VIDEO_GET_FRAME_COUNT, __u64 *pts);</para>
881</entry>
882 </row></tbody></tgroup></informaltable>
883<para>PARAMETERS
884</para>
885<informaltable><tgroup cols="2"><tbody><row><entry
886 align="char">
887<para>int fd</para>
888</entry><entry
889 align="char">
890<para>File descriptor returned by a previous call to open().</para>
891</entry>
892 </row><row><entry
893 align="char">
894<para>int request</para>
895</entry><entry
896 align="char">
897<para>Equals VIDEO_GET_FRAME_COUNT for this
898 command.</para>
899</entry>
900 </row><row><entry
901 align="char">
902<para>__u64 *pts
903</para>
904</entry><entry
905 align="char">
906<para>Returns the number of frames displayed since the decoder was started.
907</para>
908</entry>
909 </row></tbody></tgroup></informaltable>
910&return-value-dvb;
911
912</section><section id="VIDEO_GET_PTS"
913role="subsection"><title>VIDEO_GET_PTS</title>
914<para>DESCRIPTION
915</para>
916<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
917ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> control.</para>
918<informaltable><tgroup cols="1"><tbody><row><entry
919 align="char">
920<para>This ioctl call asks the Video Device to return the current PTS timestamp.</para>
921</entry>
922 </row></tbody></tgroup></informaltable>
923<para>SYNOPSIS
924</para>
925<informaltable><tgroup cols="1"><tbody><row><entry
926 align="char">
927<para>int ioctl(int fd, int request =
928 VIDEO_GET_PTS, __u64 *pts);</para>
929</entry>
930 </row></tbody></tgroup></informaltable>
931<para>PARAMETERS
932</para>
933<informaltable><tgroup cols="2"><tbody><row><entry
934 align="char">
935<para>int fd</para>
936</entry><entry
937 align="char">
938<para>File descriptor returned by a previous call to open().</para>
939</entry>
940 </row><row><entry
941 align="char">
942<para>int request</para>
943</entry><entry
944 align="char">
945<para>Equals VIDEO_GET_PTS for this
946 command.</para>
947</entry>
948 </row><row><entry
949 align="char">
950<para>__u64 *pts
951</para>
952</entry><entry
953 align="char">
954<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
955</para>
956<para>
957The PTS should belong to the currently played
958frame if possible, but may also be a value close to it
959like the PTS of the last decoded frame or the last PTS
960extracted by the PES parser.</para>
961</entry>
962 </row></tbody></tgroup></informaltable>
963&return-value-dvb;
964
965</section><section id="VIDEO_GET_FRAME_RATE"
966role="subsection"><title>VIDEO_GET_FRAME_RATE</title>
967<para>DESCRIPTION
968</para>
969<informaltable><tgroup cols="1"><tbody><row><entry
970 align="char">
971<para>This ioctl call asks the Video Device to return the current framerate.</para>
972</entry>
973 </row></tbody></tgroup></informaltable>
974<para>SYNOPSIS
975</para>
976<informaltable><tgroup cols="1"><tbody><row><entry
977 align="char">
978<para>int ioctl(int fd, int request =
979 VIDEO_GET_FRAME_RATE, unsigned int *rate);</para>
980</entry>
981 </row></tbody></tgroup></informaltable>
982<para>PARAMETERS
983</para>
984<informaltable><tgroup cols="2"><tbody><row><entry
985 align="char">
986<para>int fd</para>
987</entry><entry
988 align="char">
989<para>File descriptor returned by a previous call to open().</para>
990</entry>
991 </row><row><entry
992 align="char">
993<para>int request</para>
994</entry><entry
995 align="char">
996<para>Equals VIDEO_GET_FRAME_RATE for this
997 command.</para>
998</entry>
999 </row><row><entry
1000 align="char">
1001<para>unsigned int *rate
1002</para>
1003</entry><entry
1004 align="char">
1005<para>Returns the framerate in number of frames per 1000 seconds.
1006</para>
1007</entry>
1008 </row></tbody></tgroup></informaltable>
1009&return-value-dvb;
1010
1011</section><section id="VIDEO_GET_EVENT"
1012role="subsection"><title>VIDEO_GET_EVENT</title>
1013<para>DESCRIPTION
1014</para>
1015<para>This ioctl is for DVB devices only. To get events from a V4L2 decoder use the V4L2
1016&VIDIOC-DQEVENT; ioctl instead.</para>
1017<informaltable><tgroup cols="1"><tbody><row><entry
1018 align="char">
1019<para>This ioctl call returns an event of type video_event if available. If an event is
1020 not available, the behavior depends on whether the device is in blocking or
1021 non-blocking mode. In the latter case, the call fails immediately with errno
1022 set to EWOULDBLOCK. In the former case, the call blocks until an event
1023 becomes available. The standard Linux poll() and/or select() system calls can
1024 be used with the device file descriptor to watch for new events. For select(),
1025 the file descriptor should be included in the exceptfds argument, and for
1026 poll(), POLLPRI should be specified as the wake-up condition. Read-only
1027 permissions are sufficient for this ioctl call.</para>
1028</entry>
1029 </row></tbody></tgroup></informaltable>
1030<para>SYNOPSIS
1031</para>
1032<informaltable><tgroup cols="1"><tbody><row><entry
1033 align="char">
1034<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct
1035 video_event &#x22C6;ev);</para>
1036</entry>
1037 </row></tbody></tgroup></informaltable>
1038<para>PARAMETERS
1039</para>
1040<informaltable><tgroup cols="2"><tbody><row><entry
1041 align="char">
1042<para>int fd</para>
1043</entry><entry
1044 align="char">
1045<para>File descriptor returned by a previous call to open().</para>
1046</entry>
1047 </row><row><entry
1048 align="char">
1049<para>int request</para>
1050</entry><entry
1051 align="char">
1052<para>Equals VIDEO_GET_EVENT for this command.</para>
1053</entry>
1054 </row><row><entry
1055 align="char">
1056<para>struct video_event
1057 *ev</para>
1058</entry><entry
1059 align="char">
1060<para>Points to the location where the event, if any, is to be
1061 stored.</para>
1062</entry>
1063 </row></tbody></tgroup></informaltable>
1064&return-value-dvb;
1065<informaltable><tgroup cols="2"><tbody><row><entry
1066 align="char">
1067<para>EWOULDBLOCK</para>
1068</entry><entry
1069 align="char">
1070<para>There is no event pending, and the device is in
1071 non-blocking mode.</para>
1072</entry>
1073 </row><row><entry
1074 align="char">
1075<para>EOVERFLOW</para>
1076</entry><entry
1077 align="char">
1078<para>Overflow in event queue - one or more events were lost.</para>
1079</entry>
1080 </row></tbody></tgroup></informaltable>
1081
1082</section><section id="VIDEO_COMMAND"
1083role="subsection"><title>VIDEO_COMMAND</title>
1084<para>DESCRIPTION
1085</para>
1086<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
1087ioctl has been replaced by the &VIDIOC-DECODER-CMD; ioctl.</para>
1088<informaltable><tgroup cols="1"><tbody><row><entry
1089 align="char">
1090<para>This ioctl commands the decoder. The <constant>video_command</constant> struct
1091is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the
1092&VIDIOC-DECODER-CMD; documentation for more information.</para>
1093</entry>
1094 </row></tbody></tgroup></informaltable>
1095<para>SYNOPSIS
1096</para>
1097<informaltable><tgroup cols="1"><tbody><row><entry
1098 align="char">
1099<para>int ioctl(int fd, int request =
1100 VIDEO_COMMAND, struct video_command *cmd);</para>
1101</entry>
1102 </row></tbody></tgroup></informaltable>
1103<para>PARAMETERS
1104</para>
1105<informaltable><tgroup cols="2"><tbody><row><entry
1106 align="char">
1107<para>int fd</para>
1108</entry><entry
1109 align="char">
1110<para>File descriptor returned by a previous call to open().</para>
1111</entry>
1112 </row><row><entry
1113 align="char">
1114<para>int request</para>
1115</entry><entry
1116 align="char">
1117<para>Equals VIDEO_COMMAND for this
1118 command.</para>
1119</entry>
1120 </row><row><entry
1121 align="char">
1122<para>struct video_command *cmd
1123</para>
1124</entry><entry
1125 align="char">
1126<para>Commands the decoder.
1127</para>
1128</entry>
1129 </row></tbody></tgroup></informaltable>
1130&return-value-dvb;
1131
1132</section><section id="VIDEO_TRY_COMMAND"
1133role="subsection"><title>VIDEO_TRY_COMMAND</title>
1134<para>DESCRIPTION
1135</para>
1136<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this
1137ioctl has been replaced by the &VIDIOC-TRY-DECODER-CMD; ioctl.</para>
1138<informaltable><tgroup cols="1"><tbody><row><entry
1139 align="char">
1140<para>This ioctl tries a decoder command. The <constant>video_command</constant> struct
1141is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the
1142&VIDIOC-TRY-DECODER-CMD; documentation for more information.</para>
1143</entry>
1144 </row></tbody></tgroup></informaltable>
1145<para>SYNOPSIS
1146</para>
1147<informaltable><tgroup cols="1"><tbody><row><entry
1148 align="char">
1149<para>int ioctl(int fd, int request =
1150 VIDEO_TRY_COMMAND, struct video_command *cmd);</para>
1151</entry>
1152 </row></tbody></tgroup></informaltable>
1153<para>PARAMETERS
1154</para>
1155<informaltable><tgroup cols="2"><tbody><row><entry
1156 align="char">
1157<para>int fd</para>
1158</entry><entry
1159 align="char">
1160<para>File descriptor returned by a previous call to open().</para>
1161</entry>
1162 </row><row><entry
1163 align="char">
1164<para>int request</para>
1165</entry><entry
1166 align="char">
1167<para>Equals VIDEO_TRY_COMMAND for this
1168 command.</para>
1169</entry>
1170 </row><row><entry
1171 align="char">
1172<para>struct video_command *cmd
1173</para>
1174</entry><entry
1175 align="char">
1176<para>Try a decoder command.
1177</para>
1178</entry>
1179 </row></tbody></tgroup></informaltable>
1180&return-value-dvb;
1181
1182</section><section id="VIDEO_GET_SIZE"
1183role="subsection"><title>VIDEO_GET_SIZE</title>
1184<para>DESCRIPTION
1185</para>
1186<informaltable><tgroup cols="1"><tbody><row><entry
1187 align="char">
1188<para>This ioctl returns the size and aspect ratio.</para>
1189</entry>
1190 </row></tbody></tgroup></informaltable>
1191<para>SYNOPSIS
1192</para>
1193<informaltable><tgroup cols="1"><tbody><row><entry
1194 align="char">
1195<para>int ioctl(int fd, int request =
1196 VIDEO_GET_SIZE, video_size_t *size);</para>
1197</entry>
1198 </row></tbody></tgroup></informaltable>
1199<para>PARAMETERS
1200</para>
1201<informaltable><tgroup cols="2"><tbody><row><entry
1202 align="char">
1203<para>int fd</para>
1204</entry><entry
1205 align="char">
1206<para>File descriptor returned by a previous call to open().</para>
1207</entry>
1208 </row><row><entry
1209 align="char">
1210<para>int request</para>
1211</entry><entry
1212 align="char">
1213<para>Equals VIDEO_GET_SIZE for this
1214 command.</para>
1215</entry>
1216 </row><row><entry
1217 align="char">
1218<para>video_size_t *size
1219</para>
1220</entry><entry
1221 align="char">
1222<para>Returns the size and aspect ratio.
1223</para>
1224</entry>
1225 </row></tbody></tgroup></informaltable>
1226&return-value-dvb;
1227
1228</section><section id="VIDEO_SET_DISPLAY_FORMAT"
1229role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title>
1230<para>DESCRIPTION
1231</para>
1232<informaltable><tgroup cols="1"><tbody><row><entry
1233 align="char">
1234<para>This ioctl call asks the Video Device to select the video format to be applied
1235 by the MPEG chip on the video.</para>
1236</entry>
1237 </row></tbody></tgroup></informaltable>
1238<para>SYNOPSIS
1239</para>
1240<informaltable><tgroup cols="1"><tbody><row><entry
1241 align="char">
1242<para> int ioctl(fd, int request =
1243 VIDEO_SET_DISPLAY_FORMAT, video_display_format_t
1244 format);</para>
1245</entry>
1246 </row></tbody></tgroup></informaltable>
1247<para>PARAMETERS
1248</para>
1249<informaltable><tgroup cols="2"><tbody><row><entry
1250 align="char">
1251<para>int fd</para>
1252</entry><entry
1253 align="char">
1254<para>File descriptor returned by a previous call to open().</para>
1255</entry>
1256 </row><row><entry
1257 align="char">
1258<para>int request</para>
1259</entry><entry
1260 align="char">
1261<para>Equals VIDEO_SET_DISPLAY_FORMAT for this
1262 command.</para>
1263</entry>
1264 </row><row><entry
1265 align="char">
1266<para>video_display_format_t
1267 format</para>
1268</entry><entry
1269 align="char">
1270<para>Selects the video format to be used.</para>
1271</entry>
1272 </row></tbody></tgroup></informaltable>
1273&return-value-dvb;
1274
1275</section><section id="VIDEO_STILLPICTURE"
1276role="subsection"><title>VIDEO_STILLPICTURE</title>
1277<para>DESCRIPTION
1278</para>
1279<informaltable><tgroup cols="1"><tbody><row><entry
1280 align="char">
1281<para>This ioctl call asks the Video Device to display a still picture (I-frame). The
1282 input data shall contain an I-frame. If the pointer is NULL, then the current
1283 displayed still picture is blanked.</para>
1284</entry>
1285 </row></tbody></tgroup></informaltable>
1286<para>SYNOPSIS
1287</para>
1288<informaltable><tgroup cols="1"><tbody><row><entry
1289 align="char">
1290<para>int ioctl(fd, int request = VIDEO_STILLPICTURE,
1291 struct video_still_picture &#x22C6;sp);</para>
1292</entry>
1293 </row></tbody></tgroup></informaltable>
1294<para>PARAMETERS
1295</para>
1296<informaltable><tgroup cols="2"><tbody><row><entry
1297 align="char">
1298<para>int fd</para>
1299</entry><entry
1300 align="char">
1301<para>File descriptor returned by a previous call to open().</para>
1302</entry>
1303 </row><row><entry
1304 align="char">
1305<para>int request</para>
1306</entry><entry
1307 align="char">
1308<para>Equals VIDEO_STILLPICTURE for this command.</para>
1309</entry>
1310 </row><row><entry
1311 align="char">
1312<para>struct
1313 video_still_picture
1314 *sp</para>
1315</entry><entry
1316 align="char">
1317<para>Pointer to a location where an I-frame and size is stored.</para>
1318</entry>
1319 </row></tbody></tgroup></informaltable>
1320&return-value-dvb;
1321
1322</section><section id="VIDEO_FAST_FORWARD"
1323role="subsection"><title>VIDEO_FAST_FORWARD</title>
1324<para>DESCRIPTION
1325</para>
1326<informaltable><tgroup cols="1"><tbody><row><entry
1327 align="char">
1328<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames.
1329 This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1330</entry>
1331 </row></tbody></tgroup></informaltable>
1332<para>SYNOPSIS
1333</para>
1334<informaltable><tgroup cols="1"><tbody><row><entry
1335 align="char">
1336<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int
1337 nFrames);</para>
1338</entry>
1339 </row></tbody></tgroup></informaltable>
1340<para>PARAMETERS
1341</para>
1342<informaltable><tgroup cols="2"><tbody><row><entry
1343 align="char">
1344<para>int fd</para>
1345</entry><entry
1346 align="char">
1347<para>File descriptor returned by a previous call to open().</para>
1348</entry>
1349 </row><row><entry
1350 align="char">
1351<para>int request</para>
1352</entry><entry
1353 align="char">
1354<para>Equals VIDEO_FAST_FORWARD for this command.</para>
1355</entry>
1356 </row><row><entry
1357 align="char">
1358<para>int nFrames</para>
1359</entry><entry
1360 align="char">
1361<para>The number of frames to skip.</para>
1362</entry>
1363 </row></tbody></tgroup></informaltable>
1364&return-value-dvb;
1365<informaltable><tgroup cols="2"><tbody><row><entry
1366 align="char">
1367<para>EPERM</para>
1368</entry><entry
1369 align="char">
1370<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1371</entry>
1372 </row></tbody></tgroup></informaltable>
1373
1374</section><section id="VIDEO_SLOWMOTION"
1375role="subsection"><title>VIDEO_SLOWMOTION</title>
1376<para>DESCRIPTION
1377</para>
1378<informaltable><tgroup cols="1"><tbody><row><entry
1379 align="char">
1380<para>This ioctl call asks the video device to repeat decoding frames N number of
1381 times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1382</entry>
1383 </row></tbody></tgroup></informaltable>
1384<para>SYNOPSIS
1385</para>
1386<informaltable><tgroup cols="1"><tbody><row><entry
1387 align="char">
1388<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int
1389 nFrames);</para>
1390</entry>
1391 </row></tbody></tgroup></informaltable>
1392<para>PARAMETERS
1393</para>
1394<informaltable><tgroup cols="2"><tbody><row><entry
1395 align="char">
1396<para>int fd</para>
1397</entry><entry
1398 align="char">
1399<para>File descriptor returned by a previous call to open().</para>
1400</entry>
1401 </row><row><entry
1402 align="char">
1403<para>int request</para>
1404</entry><entry
1405 align="char">
1406<para>Equals VIDEO_SLOWMOTION for this command.</para>
1407</entry>
1408 </row><row><entry
1409 align="char">
1410<para>int nFrames</para>
1411</entry><entry
1412 align="char">
1413<para>The number of times to repeat each frame.</para>
1414</entry>
1415 </row></tbody></tgroup></informaltable>
1416&return-value-dvb;
1417<informaltable><tgroup cols="2"><tbody><row><entry
1418 align="char">
1419<para>EPERM</para>
1420</entry><entry
1421 align="char">
1422<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1423</entry>
1424 </row></tbody></tgroup></informaltable>
1425
1426</section><section id="VIDEO_GET_CAPABILITIES"
1427role="subsection"><title>VIDEO_GET_CAPABILITIES</title>
1428<para>DESCRIPTION
1429</para>
1430<informaltable><tgroup cols="1"><tbody><row><entry
1431 align="char">
1432<para>This ioctl call asks the video device about its decoding capabilities. On success
1433 it returns and integer which has bits set according to the defines in section ??.</para>
1434</entry>
1435 </row></tbody></tgroup></informaltable>
1436<para>SYNOPSIS
1437</para>
1438<informaltable><tgroup cols="1"><tbody><row><entry
1439 align="char">
1440<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES,
1441 unsigned int &#x22C6;cap);</para>
1442</entry>
1443 </row></tbody></tgroup></informaltable>
1444<para>PARAMETERS
1445</para>
1446<informaltable><tgroup cols="2"><tbody><row><entry
1447 align="char">
1448<para>int fd</para>
1449</entry><entry
1450 align="char">
1451<para>File descriptor returned by a previous call to open().</para>
1452</entry>
1453 </row><row><entry
1454 align="char">
1455<para>int request</para>
1456</entry><entry
1457 align="char">
1458<para>Equals VIDEO_GET_CAPABILITIES for this
1459 command.</para>
1460</entry>
1461 </row><row><entry
1462 align="char">
1463<para>unsigned int *cap</para>
1464</entry><entry
1465 align="char">
1466<para>Pointer to a location where to store the capability
1467 information.</para>
1468</entry>
1469 </row></tbody></tgroup></informaltable>
1470&return-value-dvb;
1471
1472</section><section id="VIDEO_SET_ID"
1473role="subsection"><title>VIDEO_SET_ID</title>
1474<para>DESCRIPTION
1475</para>
1476<informaltable><tgroup cols="1"><tbody><row><entry
1477 align="char">
1478<para>This ioctl selects which sub-stream is to be decoded if a program or system
1479 stream is sent to the video device.</para>
1480</entry>
1481 </row></tbody></tgroup></informaltable>
1482<para>SYNOPSIS
1483</para>
1484<informaltable><tgroup cols="1"><tbody><row><entry
1485 align="char">
1486<para>int ioctl(int fd, int request = VIDEO_SET_ID, int
1487 id);</para>
1488</entry>
1489 </row></tbody></tgroup></informaltable>
1490<para>PARAMETERS
1491</para>
1492<informaltable><tgroup cols="2"><tbody><row><entry
1493 align="char">
1494<para>int fd</para>
1495</entry><entry
1496 align="char">
1497<para>File descriptor returned by a previous call to open().</para>
1498</entry>
1499 </row><row><entry
1500 align="char">
1501<para>int request</para>
1502</entry><entry
1503 align="char">
1504<para>Equals VIDEO_SET_ID for this command.</para>
1505</entry>
1506 </row><row><entry
1507 align="char">
1508<para>int id</para>
1509</entry><entry
1510 align="char">
1511<para>video sub-stream id</para>
1512</entry>
1513 </row></tbody></tgroup></informaltable>
1514&return-value-dvb;
1515<informaltable><tgroup cols="2"><tbody><row><entry
1516 align="char">
1517<para>EINVAL</para>
1518</entry><entry
1519 align="char">
1520<para>Invalid sub-stream id.</para>
1521</entry>
1522 </row></tbody></tgroup></informaltable>
1523
1524</section><section id="VIDEO_CLEAR_BUFFER"
1525role="subsection"><title>VIDEO_CLEAR_BUFFER</title>
1526<para>DESCRIPTION
1527</para>
1528<informaltable><tgroup cols="1"><tbody><row><entry
1529 align="char">
1530<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para>
1531</entry>
1532 </row></tbody></tgroup></informaltable>
1533<para>SYNOPSIS
1534</para>
1535<informaltable><tgroup cols="1"><tbody><row><entry
1536 align="char">
1537<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para>
1538</entry>
1539 </row></tbody></tgroup></informaltable>
1540<para>PARAMETERS
1541</para>
1542<informaltable><tgroup cols="2"><tbody><row><entry
1543 align="char">
1544<para>int fd</para>
1545</entry><entry
1546 align="char">
1547<para>File descriptor returned by a previous call to open().</para>
1548</entry>
1549 </row><row><entry
1550 align="char">
1551<para>int request</para>
1552</entry><entry
1553 align="char">
1554<para>Equals VIDEO_CLEAR_BUFFER for this command.</para>
1555</entry>
1556 </row></tbody></tgroup></informaltable>
1557&return-value-dvb;
1558
1559</section><section id="VIDEO_SET_STREAMTYPE"
1560role="subsection"><title>VIDEO_SET_STREAMTYPE</title>
1561<para>DESCRIPTION
1562</para>
1563<informaltable><tgroup cols="1"><tbody><row><entry
1564 align="char">
1565<para>This ioctl tells the driver which kind of stream to expect being written to it. If
1566 this call is not used the default of video PES is used. Some drivers might not
1567 support this call and always expect PES.</para>
1568</entry>
1569 </row></tbody></tgroup></informaltable>
1570<para>SYNOPSIS
1571</para>
1572<informaltable><tgroup cols="1"><tbody><row><entry
1573 align="char">
1574<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE,
1575 int type);</para>
1576</entry>
1577 </row></tbody></tgroup></informaltable>
1578<para>PARAMETERS
1579</para>
1580<informaltable><tgroup cols="2"><tbody><row><entry
1581 align="char">
1582<para>int fd</para>
1583</entry><entry
1584 align="char">
1585<para>File descriptor returned by a previous call to open().</para>
1586</entry>
1587 </row><row><entry
1588 align="char">
1589<para>int request</para>
1590</entry><entry
1591 align="char">
1592<para>Equals VIDEO_SET_STREAMTYPE for this command.</para>
1593</entry>
1594 </row><row><entry
1595 align="char">
1596<para>int type</para>
1597</entry><entry
1598 align="char">
1599<para>stream type</para>
1600</entry>
1601 </row></tbody></tgroup></informaltable>
1602&return-value-dvb;
1603
1604</section><section id="VIDEO_SET_FORMAT"
1605role="subsection"><title>VIDEO_SET_FORMAT</title>
1606<para>DESCRIPTION
1607</para>
1608<informaltable><tgroup cols="1"><tbody><row><entry
1609 align="char">
1610<para>This ioctl sets the screen format (aspect ratio) of the connected output device
1611 (TV) so that the output of the decoder can be adjusted accordingly.</para>
1612</entry>
1613 </row></tbody></tgroup></informaltable>
1614<para>SYNOPSIS
1615</para>
1616<informaltable><tgroup cols="1"><tbody><row><entry
1617 align="char">
1618<para> int ioctl(fd, int request = VIDEO_SET_FORMAT,
1619 video_format_t format);</para>
1620</entry>
1621 </row></tbody></tgroup></informaltable>
1622<para>PARAMETERS
1623</para>
1624<informaltable><tgroup cols="2"><tbody><row><entry
1625 align="char">
1626<para>int fd</para>
1627</entry><entry
1628 align="char">
1629<para>File descriptor returned by a previous call to open().</para>
1630</entry>
1631 </row><row><entry
1632 align="char">
1633<para>int request</para>
1634</entry><entry
1635 align="char">
1636<para>Equals VIDEO_SET_FORMAT for this command.</para>
1637</entry>
1638 </row><row><entry
1639 align="char">
1640<para>video_format_t
1641 format</para>
1642</entry><entry
1643 align="char">
1644<para>video format of TV as defined in section ??.</para>
1645</entry>
1646 </row></tbody></tgroup></informaltable>
1647&return-value-dvb;
1648<informaltable><tgroup cols="2"><tbody><row><entry
1649 align="char">
1650<para>EINVAL</para>
1651</entry><entry
1652 align="char">
1653<para>format is not a valid video format.</para>
1654</entry>
1655 </row></tbody></tgroup></informaltable>
1656
1657</section><section id="VIDEO_SET_SYSTEM"
1658role="subsection"><title>VIDEO_SET_SYSTEM</title>
1659<para>DESCRIPTION
1660</para>
1661<informaltable><tgroup cols="1"><tbody><row><entry
1662 align="char">
1663<para>This ioctl sets the television output format. The format (see section ??) may
1664 vary from the color format of the displayed MPEG stream. If the hardware is
1665 not able to display the requested format the call will return an error.</para>
1666</entry>
1667 </row></tbody></tgroup></informaltable>
1668<para>SYNOPSIS
1669</para>
1670<informaltable><tgroup cols="1"><tbody><row><entry
1671 align="char">
1672<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM ,
1673 video_system_t system);</para>
1674</entry>
1675 </row></tbody></tgroup></informaltable>
1676<para>PARAMETERS
1677</para>
1678<informaltable><tgroup cols="2"><tbody><row><entry
1679 align="char">
1680<para>int fd</para>
1681</entry><entry
1682 align="char">
1683<para>File descriptor returned by a previous call to open().</para>
1684</entry>
1685 </row><row><entry
1686 align="char">
1687<para>int request</para>
1688</entry><entry
1689 align="char">
1690<para>Equals VIDEO_SET_FORMAT for this command.</para>
1691</entry>
1692 </row><row><entry
1693 align="char">
1694<para>video_system_t
1695 system</para>
1696</entry><entry
1697 align="char">
1698<para>video system of TV output.</para>
1699</entry>
1700 </row></tbody></tgroup></informaltable>
1701&return-value-dvb;
1702<informaltable><tgroup cols="2"><tbody><row><entry
1703 align="char">
1704<para>EINVAL</para>
1705</entry><entry
1706 align="char">
1707<para>system is not a valid or supported video system.</para>
1708</entry>
1709 </row></tbody></tgroup></informaltable>
1710
1711</section><section id="VIDEO_SET_HIGHLIGHT"
1712role="subsection"><title>VIDEO_SET_HIGHLIGHT</title>
1713<para>DESCRIPTION
1714</para>
1715<informaltable><tgroup cols="1"><tbody><row><entry
1716 align="char">
1717<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para>
1718</entry>
1719 </row></tbody></tgroup></informaltable>
1720<para>SYNOPSIS
1721</para>
1722<informaltable><tgroup cols="1"><tbody><row><entry
1723 align="char">
1724<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT
1725 ,video_highlight_t &#x22C6;vhilite)</para>
1726</entry>
1727 </row></tbody></tgroup></informaltable>
1728<para>PARAMETERS
1729</para>
1730<informaltable><tgroup cols="2"><tbody><row><entry
1731 align="char">
1732<para>int fd</para>
1733</entry><entry
1734 align="char">
1735<para>File descriptor returned by a previous call to open().</para>
1736</entry>
1737 </row><row><entry
1738 align="char">
1739<para>int request</para>
1740</entry><entry
1741 align="char">
1742<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para>
1743</entry>
1744 </row><row><entry
1745 align="char">
1746<para>video_highlight_t
1747 *vhilite</para>
1748</entry><entry
1749 align="char">
1750<para>SPU Highlight information according to section ??.</para>
1751</entry>
1752 </row></tbody></tgroup></informaltable>
1753&return-value-dvb;
1754
1755</section><section id="VIDEO_SET_SPU"
1756role="subsection"><title>VIDEO_SET_SPU</title>
1757<para>DESCRIPTION
1758</para>
1759<informaltable><tgroup cols="1"><tbody><row><entry
1760 align="char">
1761<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can
1762 only be used, if the driver is able to handle a DVD stream.</para>
1763</entry>
1764 </row></tbody></tgroup></informaltable>
1765<para>SYNOPSIS
1766</para>
1767<informaltable><tgroup cols="1"><tbody><row><entry
1768 align="char">
1769<para> int ioctl(fd, int request = VIDEO_SET_SPU ,
1770 video_spu_t &#x22C6;spu)</para>
1771</entry>
1772 </row></tbody></tgroup></informaltable>
1773<para>PARAMETERS
1774</para>
1775<informaltable><tgroup cols="2"><tbody><row><entry
1776 align="char">
1777<para>int fd</para>
1778</entry><entry
1779 align="char">
1780<para>File descriptor returned by a previous call to open().</para>
1781</entry>
1782 </row><row><entry
1783 align="char">
1784<para>int request</para>
1785</entry><entry
1786 align="char">
1787<para>Equals VIDEO_SET_SPU for this command.</para>
1788</entry>
1789 </row><row><entry
1790 align="char">
1791<para>video_spu_t *spu</para>
1792</entry><entry
1793 align="char">
1794<para>SPU decoding (de)activation and subid setting according
1795 to section ??.</para>
1796</entry>
1797 </row></tbody></tgroup></informaltable>
1798&return-value-dvb;
1799<informaltable><tgroup cols="2"><tbody><row><entry
1800 align="char">
1801<para>EINVAL</para>
1802</entry><entry
1803 align="char">
1804<para>input is not a valid spu setting or driver cannot handle
1805 SPU.</para>
1806</entry>
1807 </row></tbody></tgroup></informaltable>
1808
1809</section><section id="VIDEO_SET_SPU_PALETTE"
1810role="subsection"><title>VIDEO_SET_SPU_PALETTE</title>
1811<para>DESCRIPTION
1812</para>
1813<informaltable><tgroup cols="1"><tbody><row><entry
1814 align="char">
1815<para>This ioctl sets the SPU color palette.</para>
1816</entry>
1817 </row></tbody></tgroup></informaltable>
1818<para>SYNOPSIS
1819</para>
1820<informaltable><tgroup cols="1"><tbody><row><entry
1821 align="char">
1822<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
1823 ,video_spu_palette_t &#x22C6;palette )</para>
1824</entry>
1825 </row></tbody></tgroup></informaltable>
1826<para>PARAMETERS
1827</para>
1828<informaltable><tgroup cols="2"><tbody><row><entry
1829 align="char">
1830<para>int fd</para>
1831</entry><entry
1832 align="char">
1833<para>File descriptor returned by a previous call to open().</para>
1834</entry>
1835 </row><row><entry
1836 align="char">
1837<para>int request</para>
1838</entry><entry
1839 align="char">
1840<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para>
1841</entry>
1842 </row><row><entry
1843 align="char">
1844<para>video_spu_palette_t
1845 *palette</para>
1846</entry><entry
1847 align="char">
1848<para>SPU palette according to section ??.</para>
1849</entry>
1850 </row></tbody></tgroup></informaltable>
1851&return-value-dvb;
1852<informaltable><tgroup cols="2"><tbody><row><entry
1853 align="char">
1854<para>EINVAL</para>
1855</entry><entry
1856 align="char">
1857<para>input is not a valid palette or driver doesn&#8217;t handle SPU.</para>
1858</entry>
1859 </row></tbody></tgroup></informaltable>
1860
1861</section><section id="VIDEO_GET_NAVI"
1862role="subsection"><title>VIDEO_GET_NAVI</title>
1863<para>DESCRIPTION
1864</para>
1865<informaltable><tgroup cols="1"><tbody><row><entry
1866 align="char">
1867<para>This ioctl returns navigational information from the DVD stream. This is
1868 especially needed if an encoded stream has to be decoded by the hardware.</para>
1869</entry>
1870 </row></tbody></tgroup></informaltable>
1871<para>SYNOPSIS
1872</para>
1873<informaltable><tgroup cols="1"><tbody><row><entry
1874 align="char">
1875<para> int ioctl(fd, int request = VIDEO_GET_NAVI ,
1876 video_navi_pack_t &#x22C6;navipack)</para>
1877</entry>
1878 </row></tbody></tgroup></informaltable>
1879<para>PARAMETERS
1880</para>
1881<informaltable><tgroup cols="2"><tbody><row><entry
1882 align="char">
1883<para>int fd</para>
1884</entry><entry
1885 align="char">
1886<para>File descriptor returned by a previous call to open().</para>
1887</entry>
1888 </row><row><entry
1889 align="char">
1890<para>int request</para>
1891</entry><entry
1892 align="char">
1893<para>Equals VIDEO_GET_NAVI for this command.</para>
1894</entry>
1895 </row><row><entry
1896 align="char">
1897<para>video_navi_pack_t
1898 *navipack</para>
1899</entry><entry
1900 align="char">
1901<para>PCI or DSI pack (private stream 2) according to section
1902 ??.</para>
1903</entry>
1904 </row></tbody></tgroup></informaltable>
1905&return-value-dvb;
1906<informaltable><tgroup cols="2"><tbody><row><entry
1907 align="char">
1908<para>EFAULT</para>
1909</entry><entry
1910 align="char">
1911<para>driver is not able to return navigational information</para>
1912</entry>
1913 </row></tbody></tgroup></informaltable>
1914
1915</section><section id="VIDEO_SET_ATTRIBUTES"
1916role="subsection"><title>VIDEO_SET_ATTRIBUTES</title>
1917<para>DESCRIPTION
1918</para>
1919<informaltable><tgroup cols="1"><tbody><row><entry
1920 align="char">
1921<para>This ioctl is intended for DVD playback and allows you to set certain
1922 information about the stream. Some hardware may not need this information,
1923 but the call also tells the hardware to prepare for DVD playback.</para>
1924</entry>
1925 </row></tbody></tgroup></informaltable>
1926<para>SYNOPSIS
1927</para>
1928<informaltable><tgroup cols="1"><tbody><row><entry
1929 align="char">
1930<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE
1931 ,video_attributes_t vattr)</para>
1932</entry>
1933 </row></tbody></tgroup></informaltable>
1934<para>PARAMETERS
1935</para>
1936<informaltable><tgroup cols="2"><tbody><row><entry
1937 align="char">
1938<para>int fd</para>
1939</entry><entry
1940 align="char">
1941<para>File descriptor returned by a previous call to open().</para>
1942</entry>
1943 </row><row><entry
1944 align="char">
1945<para>int request</para>
1946</entry><entry
1947 align="char">
1948<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para>
1949</entry>
1950 </row><row><entry
1951 align="char">
1952<para>video_attributes_t
1953 vattr</para>
1954</entry><entry
1955 align="char">
1956<para>video attributes according to section ??.</para>
1957</entry>
1958 </row></tbody></tgroup></informaltable>
1959&return-value-dvb;
1960<informaltable><tgroup cols="2"><tbody><row><entry
1961 align="char">
1962<para>EINVAL</para>
1963</entry><entry
1964 align="char">
1965<para>input is not a valid attribute setting.</para>
1966</entry>
1967 </row></tbody></tgroup></informaltable>
1968 </section></section>
generated by cgit v1.2.2 (git 2.25.0) at 2025-07-22 12:31:12 -0400