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.xml1203
-rw-r--r--Documentation/DocBook/media/dvb/ca.xml229
-rw-r--r--Documentation/DocBook/media/dvb/demux.xml902
-rw-r--r--Documentation/DocBook/media/dvb/dvbapi.xml141
-rw-r--r--Documentation/DocBook/media/dvb/dvbproperty.xml859
-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.xml1515
-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.xml29
-rw-r--r--Documentation/DocBook/media/dvb/video.xml1657
13 files changed, 9422 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/dvb/.gitignore b/Documentation/DocBook/media/dvb/.gitignore
new file mode 100644
index 000000000000..d7ec32eafac9
--- /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 000000000000..d64386237207
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/audio.xml
@@ -0,0 +1,1203 @@
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/video.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
11<section id="audio_data_types">
12<title>Audio Data Types</title>
13<para>This section describes the structures, data types and defines used when talking to the
14audio device.
15</para>
16
17<section id="audio-stream-source-t">
18<title>audio_stream_source_t</title>
19<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
20the following values, depending on whether we are replaying from an internal (demux) or
21external (user write) source.
22</para>
23<programlisting>
24typedef enum {
25 AUDIO_SOURCE_DEMUX,
26 AUDIO_SOURCE_MEMORY
27} audio_stream_source_t;
28</programlisting>
29<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
30DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
31is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
32call.
33</para>
34
35</section>
36<section id="audio-play-state-t">
37<title>audio_play_state_t</title>
38<para>The following values can be returned by the AUDIO_GET_STATUS call representing the
39state of audio playback.
40</para>
41<programlisting>
42typedef enum {
43 AUDIO_STOPPED,
44 AUDIO_PLAYING,
45 AUDIO_PAUSED
46} audio_play_state_t;
47</programlisting>
48
49</section>
50<section id="audio-channel-select-t">
51<title>audio_channel_select_t</title>
52<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
53following values.
54</para>
55<programlisting>
56typedef enum {
57 AUDIO_STEREO,
58 AUDIO_MONO_LEFT,
59 AUDIO_MONO_RIGHT,
60 AUDIO_MONO,
61 AUDIO_STEREO_SWAPPED
62} audio_channel_select_t;
63</programlisting>
64
65</section>
66<section id="audio-status">
67<title>struct audio_status</title>
68<para>The AUDIO_GET_STATUS call returns the following structure informing about various
69states of the playback operation.
70</para>
71<programlisting>
72typedef struct audio_status {
73 boolean AV_sync_state;
74 boolean mute_state;
75 audio_play_state_t play_state;
76 audio_stream_source_t stream_source;
77 audio_channel_select_t channel_select;
78 boolean bypass_mode;
79 audio_mixer_t mixer_state;
80} audio_status_t;
81</programlisting>
82
83</section>
84<section id="audio-mixer">
85<title>struct audio_mixer</title>
86<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
87volume.
88</para>
89<programlisting>
90typedef struct audio_mixer {
91 unsigned int volume_left;
92 unsigned int volume_right;
93} audio_mixer_t;
94</programlisting>
95
96</section>
97<section id="audio_encodings">
98<title>audio encodings</title>
99<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
100bits set according to the hardwares capabilities.
101</para>
102<programlisting>
103 #define AUDIO_CAP_DTS 1
104 #define AUDIO_CAP_LPCM 2
105 #define AUDIO_CAP_MP1 4
106 #define AUDIO_CAP_MP2 8
107 #define AUDIO_CAP_MP3 16
108 #define AUDIO_CAP_AAC 32
109 #define AUDIO_CAP_OGG 64
110 #define AUDIO_CAP_SDDS 128
111 #define AUDIO_CAP_AC3 256
112</programlisting>
113
114</section>
115<section id="audio-karaoke">
116<title>struct audio_karaoke</title>
117<para>The ioctl AUDIO_SET_KARAOKE uses the following format:
118</para>
119<programlisting>
120typedef
121struct audio_karaoke {
122 int vocal1;
123 int vocal2;
124 int melody;
125} audio_karaoke_t;
126</programlisting>
127<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both,
128Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
129right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
130and right.
131</para>
132
133</section>
134<section id="audio-attributes-t">
135<title>audio attributes</title>
136<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
137</para>
138<programlisting>
139 typedef uint16_t audio_attributes_t;
140 /&#x22C6; bits: descr. &#x22C6;/
141 /&#x22C6; 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
142 /&#x22C6; 12 multichannel extension &#x22C6;/
143 /&#x22C6; 11-10 audio type (0=not spec, 1=language included) &#x22C6;/
144 /&#x22C6; 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
145 /&#x22C6; 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, &#x22C6;/
146 /&#x22C6; 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
147 /&#x22C6; 2- 0 number of audio channels (n+1 channels) &#x22C6;/
148</programlisting>
149 </section></section>
150<section id="audio_function_calls">
151<title>Audio Function Calls</title>
152
153
154<section id="audio_fopen">
155<title>open()</title>
156<para>DESCRIPTION
157</para>
158<informaltable><tgroup cols="1"><tbody><row><entry
159 align="char">
160<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0)
161 for subsequent use. When an open() call has succeeded, the device will be ready
162 for use. The significance of blocking or non-blocking mode is described in the
163 documentation for functions where there is a difference. It does not affect the
164 semantics of the open() call itself. A device opened in blocking mode can later
165 be put into non-blocking mode (and vice versa) using the F_SETFL command
166 of the fcntl system call. This is a standard system call, documented in the Linux
167 manual page for fcntl. Only one user can open the Audio Device in O_RDWR
168 mode. All other attempts to open the device in this mode will fail, and an error
169 code will be returned. If the Audio Device is opened in O_RDONLY mode, the
170 only ioctl call that can be used is AUDIO_GET_STATUS. All other call will
171 return with an error code.</para>
172</entry>
173 </row></tbody></tgroup></informaltable>
174<para>SYNOPSIS
175</para>
176<informaltable><tgroup cols="1"><tbody><row><entry
177 align="char">
178<para>int open(const char &#x22C6;deviceName, int flags);</para>
179</entry>
180 </row></tbody></tgroup></informaltable>
181<para>PARAMETERS
182</para>
183<informaltable><tgroup cols="2"><tbody><row><entry
184 align="char">
185<para>const char
186 *deviceName</para>
187</entry><entry
188 align="char">
189<para>Name of specific audio device.</para>
190</entry>
191 </row><row><entry
192 align="char">
193<para>int flags</para>
194</entry><entry
195 align="char">
196<para>A bit-wise OR of the following flags:</para>
197</entry>
198 </row><row><entry
199 align="char">
200</entry><entry
201 align="char">
202<para>O_RDONLY read-only access</para>
203</entry>
204 </row><row><entry
205 align="char">
206</entry><entry
207 align="char">
208<para>O_RDWR read/write access</para>
209</entry>
210 </row><row><entry
211 align="char">
212</entry><entry
213 align="char">
214<para>O_NONBLOCK open in non-blocking mode</para>
215</entry>
216 </row><row><entry
217 align="char">
218</entry><entry
219 align="char">
220<para>(blocking mode is the default)</para>
221</entry>
222 </row></tbody></tgroup></informaltable>
223<para>RETURN VALUE</para>
224<informaltable><tgroup cols="2"><tbody><row><entry
225 align="char">
226<para>ENODEV</para>
227</entry><entry
228 align="char">
229<para>Device driver not loaded/available.</para>
230</entry>
231 </row><row><entry
232 align="char">
233<para>EBUSY</para>
234</entry><entry
235 align="char">
236<para>Device or resource busy.</para>
237</entry>
238 </row><row><entry
239 align="char">
240<para>EINVAL</para>
241</entry><entry
242 align="char">
243<para>Invalid argument.</para>
244</entry>
245 </row></tbody></tgroup></informaltable>
246
247</section>
248<section id="audio_fclose">
249<title>close()</title>
250<para>DESCRIPTION
251</para>
252<informaltable><tgroup cols="1"><tbody><row><entry
253 align="char">
254<para>This system call closes a previously opened audio device.</para>
255</entry>
256 </row></tbody></tgroup></informaltable>
257<para>SYNOPSIS
258</para>
259<informaltable><tgroup cols="1"><tbody><row><entry
260 align="char">
261<para>int close(int fd);</para>
262</entry>
263 </row></tbody></tgroup></informaltable>
264<para>PARAMETERS
265</para>
266<informaltable><tgroup cols="2"><tbody><row><entry
267 align="char">
268<para>int fd</para>
269</entry><entry
270 align="char">
271<para>File descriptor returned by a previous call to open().</para>
272</entry>
273 </row></tbody></tgroup></informaltable>
274<para>RETURN VALUE</para>
275<informaltable><tgroup cols="2"><tbody><row><entry
276 align="char">
277<para>EBADF</para>
278</entry><entry
279 align="char">
280<para>fd is not a valid open file descriptor.</para>
281</entry>
282 </row></tbody></tgroup></informaltable>
283
284</section>
285<section id="audio_fwrite">
286<title>write()</title>
287<para>DESCRIPTION
288</para>
289<informaltable><tgroup cols="1"><tbody><row><entry
290 align="char">
291<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected
292 in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
293 PES format. If O_NONBLOCK is not specified the function will block until
294 buffer space is available. The amount of data to be transferred is implied by
295 count.</para>
296</entry>
297 </row></tbody></tgroup></informaltable>
298<para>SYNOPSIS
299</para>
300<informaltable><tgroup cols="1"><tbody><row><entry
301 align="char">
302<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
303</entry>
304 </row></tbody></tgroup></informaltable>
305<para>PARAMETERS
306</para>
307<informaltable><tgroup cols="2"><tbody><row><entry
308 align="char">
309<para>int fd</para>
310</entry><entry
311 align="char">
312<para>File descriptor returned by a previous call to open().</para>
313</entry>
314 </row><row><entry
315 align="char">
316<para>void *buf</para>
317</entry><entry
318 align="char">
319<para>Pointer to the buffer containing the PES data.</para>
320</entry>
321 </row><row><entry
322 align="char">
323<para>size_t count</para>
324</entry><entry
325 align="char">
326<para>Size of buf.</para>
327</entry>
328 </row></tbody></tgroup></informaltable>
329<para>RETURN VALUE</para>
330<informaltable><tgroup cols="2"><tbody><row><entry
331 align="char">
332<para>EPERM</para>
333</entry><entry
334 align="char">
335<para>Mode AUDIO_SOURCE_MEMORY not selected.</para>
336</entry>
337 </row><row><entry
338 align="char">
339<para>ENOMEM</para>
340</entry><entry
341 align="char">
342<para>Attempted to write more data than the internal buffer can
343 hold.</para>
344</entry>
345 </row><row><entry
346 align="char">
347<para>EBADF</para>
348</entry><entry
349 align="char">
350<para>fd is not a valid open file descriptor.</para>
351</entry>
352 </row></tbody></tgroup></informaltable>
353
354</section><section id="AUDIO_STOP"
355role="subsection"><title>AUDIO_STOP</title>
356<para>DESCRIPTION
357</para>
358<informaltable><tgroup cols="1"><tbody><row><entry
359 align="char">
360<para>This ioctl call asks the Audio Device to stop playing the current stream.</para>
361</entry>
362 </row></tbody></tgroup></informaltable>
363<para>SYNOPSIS
364</para>
365<informaltable><tgroup cols="1"><tbody><row><entry
366 align="char">
367<para>int ioctl(int fd, int request = AUDIO_STOP);</para>
368</entry>
369 </row></tbody></tgroup></informaltable>
370<para>PARAMETERS
371</para>
372<informaltable><tgroup cols="2"><tbody><row><entry
373 align="char">
374<para>int fd</para>
375</entry><entry
376 align="char">
377<para>File descriptor returned by a previous call to open().</para>
378</entry>
379 </row><row><entry
380 align="char">
381<para>int request</para>
382</entry><entry
383 align="char">
384<para>Equals AUDIO_STOP for this command.</para>
385</entry>
386 </row></tbody></tgroup></informaltable>
387&return-value-dvb;
388
389</section><section id="AUDIO_PLAY"
390role="subsection"><title>AUDIO_PLAY</title>
391<para>DESCRIPTION
392</para>
393<informaltable><tgroup cols="1"><tbody><row><entry
394 align="char">
395<para>This ioctl call asks the Audio Device to start playing an audio stream from the
396 selected source.</para>
397</entry>
398 </row></tbody></tgroup></informaltable>
399<para>SYNOPSIS
400</para>
401<informaltable><tgroup cols="1"><tbody><row><entry
402 align="char">
403<para>int ioctl(int fd, int request = AUDIO_PLAY);</para>
404</entry>
405 </row></tbody></tgroup></informaltable>
406<para>PARAMETERS
407</para>
408<informaltable><tgroup cols="2"><tbody><row><entry
409 align="char">
410<para>int fd</para>
411</entry><entry
412 align="char">
413<para>File descriptor returned by a previous call to open().</para>
414</entry>
415 </row><row><entry
416 align="char">
417<para>int request</para>
418</entry><entry
419 align="char">
420<para>Equals AUDIO_PLAY for this command.</para>
421</entry>
422 </row></tbody></tgroup></informaltable>
423&return-value-dvb;
424
425</section><section id="AUDIO_PAUSE"
426role="subsection"><title>AUDIO_PAUSE</title>
427<para>DESCRIPTION
428</para>
429<informaltable><tgroup cols="1"><tbody><row><entry
430 align="char">
431<para>This ioctl call suspends the audio stream being played. Decoding and playing
432 are paused. It is then possible to restart again decoding and playing process of
433 the audio stream using AUDIO_CONTINUE command.</para>
434</entry>
435 </row><row><entry
436 align="char">
437<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call
438 AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume)
439 any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is
440 performed.</para>
441</entry>
442 </row></tbody></tgroup></informaltable>
443<para>SYNOPSIS
444</para>
445<informaltable><tgroup cols="1"><tbody><row><entry
446 align="char">
447<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para>
448</entry>
449 </row></tbody></tgroup></informaltable>
450<para>PARAMETERS
451</para>
452<informaltable><tgroup cols="2"><tbody><row><entry
453 align="char">
454<para>int fd</para>
455</entry><entry
456 align="char">
457<para>File descriptor returned by a previous call to open().</para>
458</entry>
459 </row><row><entry
460 align="char">
461<para>int request</para>
462</entry><entry
463 align="char">
464<para>Equals AUDIO_PAUSE for this command.</para>
465</entry>
466 </row></tbody></tgroup></informaltable>
467&return-value-dvb;
468
469</section><section id="AUDIO_CONTINUE"
470role="subsection"><title>AUDIO_CONTINUE</title>
471<para>DESCRIPTION
472</para>
473<informaltable><tgroup cols="1"><tbody><row><entry
474 align="char">
475<para>This ioctl restarts the decoding and playing process previously paused
476with AUDIO_PAUSE command.</para>
477</entry>
478 </row><row><entry
479 align="char">
480<para>It only works if the stream were previously stopped with AUDIO_PAUSE</para>
481</entry>
482 </row></tbody></tgroup></informaltable>
483<para>SYNOPSIS
484</para>
485<informaltable><tgroup cols="1"><tbody><row><entry
486 align="char">
487<para>int ioctl(int fd, int request = AUDIO_CONTINUE);</para>
488</entry>
489 </row></tbody></tgroup></informaltable>
490<para>PARAMETERS
491</para>
492<informaltable><tgroup cols="2"><tbody><row><entry
493 align="char">
494<para>int fd</para>
495</entry><entry
496 align="char">
497<para>File descriptor returned by a previous call to open().</para>
498</entry>
499 </row><row><entry
500 align="char">
501<para>int request</para>
502</entry><entry
503 align="char">
504<para>Equals AUDIO_CONTINUE for this command.</para>
505</entry>
506 </row></tbody></tgroup></informaltable>
507&return-value-dvb;
508
509</section><section id="AUDIO_SELECT_SOURCE"
510role="subsection"><title>AUDIO_SELECT_SOURCE</title>
511<para>DESCRIPTION
512</para>
513<informaltable><tgroup cols="1"><tbody><row><entry
514 align="char">
515<para>This ioctl call informs the audio device which source shall be used
516 for the input data. The possible sources are demux or memory. If
517 AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
518 through the write command.</para>
519</entry>
520 </row></tbody></tgroup></informaltable>
521<para>SYNOPSIS
522</para>
523<informaltable><tgroup cols="1"><tbody><row><entry
524 align="char">
525<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
526 audio_stream_source_t source);</para>
527</entry>
528 </row></tbody></tgroup></informaltable>
529<para>PARAMETERS
530</para>
531<informaltable><tgroup cols="2"><tbody><row><entry
532 align="char">
533<para>int fd</para>
534</entry><entry
535 align="char">
536<para>File descriptor returned by a previous call to open().</para>
537</entry>
538 </row><row><entry
539 align="char">
540<para>int request</para>
541</entry><entry
542 align="char">
543<para>Equals AUDIO_SELECT_SOURCE for this command.</para>
544</entry>
545 </row><row><entry
546 align="char">
547<para>audio_stream_source_t
548 source</para>
549</entry><entry
550 align="char">
551<para>Indicates the source that shall be used for the Audio
552 stream.</para>
553</entry>
554 </row></tbody></tgroup></informaltable>
555&return-value-dvb;
556
557</section><section id="AUDIO_SET_MUTE"
558role="subsection"><title>AUDIO_SET_MUTE</title>
559<para>DESCRIPTION
560</para>
561<informaltable><tgroup cols="1"><tbody><row><entry
562 align="char">
563<para>This ioctl call asks the audio device to mute the stream that is currently being
564 played.</para>
565</entry>
566 </row></tbody></tgroup></informaltable>
567<para>SYNOPSIS
568</para>
569<informaltable><tgroup cols="1"><tbody><row><entry
570 align="char">
571<para>int ioctl(int fd, int request = AUDIO_SET_MUTE,
572 boolean state);</para>
573</entry>
574 </row></tbody></tgroup></informaltable>
575<para>PARAMETERS
576</para>
577<informaltable><tgroup cols="2"><tbody><row><entry
578 align="char">
579<para>int fd</para>
580</entry><entry
581 align="char">
582<para>File descriptor returned by a previous call to open().</para>
583</entry>
584 </row><row><entry
585 align="char">
586<para>int request</para>
587</entry><entry
588 align="char">
589<para>Equals AUDIO_SET_MUTE for this command.</para>
590</entry>
591 </row><row><entry
592 align="char">
593<para>boolean state</para>
594</entry><entry
595 align="char">
596<para>Indicates if audio device shall mute or not.</para>
597</entry>
598 </row><row><entry
599 align="char">
600</entry><entry
601 align="char">
602<para>TRUE Audio Mute</para>
603</entry>
604 </row><row><entry
605 align="char">
606</entry><entry
607 align="char">
608<para>FALSE Audio Un-mute</para>
609</entry>
610 </row></tbody></tgroup></informaltable>
611&return-value-dvb;
612
613</section><section id="AUDIO_SET_AV_SYNC"
614role="subsection"><title>AUDIO_SET_AV_SYNC</title>
615<para>DESCRIPTION
616</para>
617<informaltable><tgroup cols="1"><tbody><row><entry
618 align="char">
619<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para>
620</entry>
621 </row></tbody></tgroup></informaltable>
622<para>SYNOPSIS
623</para>
624<informaltable><tgroup cols="1"><tbody><row><entry
625 align="char">
626<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC,
627 boolean state);</para>
628</entry>
629 </row></tbody></tgroup></informaltable>
630<para>PARAMETERS
631</para>
632<informaltable><tgroup cols="2"><tbody><row><entry
633 align="char">
634<para>int fd</para>
635</entry><entry
636 align="char">
637<para>File descriptor returned by a previous call to open().</para>
638</entry>
639 </row><row><entry
640 align="char">
641<para>int request</para>
642</entry><entry
643 align="char">
644<para>Equals AUDIO_AV_SYNC for this command.</para>
645</entry>
646 </row><row><entry
647 align="char">
648<para>boolean state</para>
649</entry><entry
650 align="char">
651<para>Tells the DVB subsystem if A/V synchronization shall be
652 ON or OFF.</para>
653</entry>
654 </row><row><entry
655 align="char">
656</entry><entry
657 align="char">
658<para>TRUE AV-sync ON</para>
659</entry>
660 </row><row><entry
661 align="char">
662</entry><entry
663 align="char">
664<para>FALSE AV-sync OFF</para>
665</entry>
666 </row></tbody></tgroup></informaltable>
667&return-value-dvb;
668
669</section><section id="AUDIO_SET_BYPASS_MODE"
670role="subsection"><title>AUDIO_SET_BYPASS_MODE</title>
671<para>DESCRIPTION
672</para>
673<informaltable><tgroup cols="1"><tbody><row><entry
674 align="char">
675<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward
676 the stream without decoding. This mode shall be used if streams that can&#8217;t be
677 handled by the DVB system shall be decoded. Dolby DigitalTM streams are
678 automatically forwarded by the DVB subsystem if the hardware can handle it.</para>
679</entry>
680 </row></tbody></tgroup></informaltable>
681<para>SYNOPSIS
682</para>
683<informaltable><tgroup cols="1"><tbody><row><entry
684 align="char">
685<para>int ioctl(int fd, int request =
686 AUDIO_SET_BYPASS_MODE, boolean mode);</para>
687</entry>
688 </row></tbody></tgroup></informaltable>
689<para>PARAMETERS
690</para>
691<informaltable><tgroup cols="2"><tbody><row><entry
692 align="char">
693<para>int fd</para>
694</entry><entry
695 align="char">
696<para>File descriptor returned by a previous call to open().</para>
697</entry>
698 </row><row><entry
699 align="char">
700<para>int request</para>
701</entry><entry
702 align="char">
703<para>Equals AUDIO_SET_BYPASS_MODE for this
704 command.</para>
705</entry>
706 </row><row><entry
707 align="char">
708<para>boolean mode</para>
709</entry><entry
710 align="char">
711<para>Enables or disables the decoding of the current Audio
712 stream in the DVB subsystem.</para>
713</entry>
714 </row><row><entry
715 align="char">
716</entry><entry
717 align="char">
718<para>TRUE Bypass is disabled</para>
719</entry>
720 </row><row><entry
721 align="char">
722</entry><entry
723 align="char">
724<para>FALSE Bypass is enabled</para>
725</entry>
726 </row></tbody></tgroup></informaltable>
727&return-value-dvb;
728
729</section><section id="AUDIO_CHANNEL_SELECT"
730role="subsection"><title>AUDIO_CHANNEL_SELECT</title>
731<para>DESCRIPTION
732</para>
733<informaltable><tgroup cols="1"><tbody><row><entry
734 align="char">
735<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para>
736</entry>
737 </row></tbody></tgroup></informaltable>
738<para>SYNOPSIS
739</para>
740<informaltable><tgroup cols="1"><tbody><row><entry
741 align="char">
742<para>int ioctl(int fd, int request =
743 AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para>
744</entry>
745 </row></tbody></tgroup></informaltable>
746<para>PARAMETERS
747</para>
748<informaltable><tgroup cols="2"><tbody><row><entry
749 align="char">
750<para>int fd</para>
751</entry><entry
752 align="char">
753<para>File descriptor returned by a previous call to open().</para>
754</entry>
755 </row><row><entry
756 align="char">
757<para>int request</para>
758</entry><entry
759 align="char">
760<para>Equals AUDIO_CHANNEL_SELECT for this
761 command.</para>
762</entry>
763 </row><row><entry
764 align="char">
765<para>audio_channel_select_t
766 ch</para>
767</entry><entry
768 align="char">
769<para>Select the output format of the audio (mono left/right,
770 stereo).</para>
771</entry>
772 </row></tbody></tgroup></informaltable>
773&return-value-dvb;
774
775</section><section id="AUDIO_GET_STATUS"
776role="subsection"><title>AUDIO_GET_STATUS</title>
777<para>DESCRIPTION
778</para>
779<informaltable><tgroup cols="1"><tbody><row><entry
780 align="char">
781<para>This ioctl call asks the Audio Device to return the current state of the Audio
782 Device.</para>
783</entry>
784 </row></tbody></tgroup></informaltable>
785<para>SYNOPSIS
786</para>
787<informaltable><tgroup cols="1"><tbody><row><entry
788 align="char">
789<para>int ioctl(int fd, int request = AUDIO_GET_STATUS,
790 struct audio_status &#x22C6;status);</para>
791</entry>
792 </row></tbody></tgroup></informaltable>
793<para>PARAMETERS
794</para>
795<informaltable><tgroup cols="2"><tbody><row><entry
796 align="char">
797<para>int fd</para>
798</entry><entry
799 align="char">
800<para>File descriptor returned by a previous call to open().</para>
801</entry>
802 </row><row><entry
803 align="char">
804<para>int request</para>
805</entry><entry
806 align="char">
807<para>Equals AUDIO_GET_STATUS for this command.</para>
808</entry>
809 </row><row><entry
810 align="char">
811<para>struct audio_status
812 *status</para>
813</entry><entry
814 align="char">
815<para>Returns the current state of Audio Device.</para>
816</entry>
817 </row></tbody></tgroup></informaltable>
818&return-value-dvb;
819
820</section><section id="AUDIO_GET_CAPABILITIES"
821role="subsection"><title>AUDIO_GET_CAPABILITIES</title>
822<para>DESCRIPTION
823</para>
824<informaltable><tgroup cols="1"><tbody><row><entry
825 align="char">
826<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities
827 of the audio hardware.</para>
828</entry>
829 </row></tbody></tgroup></informaltable>
830<para>SYNOPSIS
831</para>
832<informaltable><tgroup cols="1"><tbody><row><entry
833 align="char">
834<para>int ioctl(int fd, int request =
835 AUDIO_GET_CAPABILITIES, unsigned int &#x22C6;cap);</para>
836</entry>
837 </row></tbody></tgroup></informaltable>
838<para>PARAMETERS
839</para>
840<informaltable><tgroup cols="2"><tbody><row><entry
841 align="char">
842<para>int fd</para>
843</entry><entry
844 align="char">
845<para>File descriptor returned by a previous call to open().</para>
846</entry>
847 </row><row><entry
848 align="char">
849<para>int request</para>
850</entry><entry
851 align="char">
852<para>Equals AUDIO_GET_CAPABILITIES for this
853 command.</para>
854</entry>
855 </row><row><entry
856 align="char">
857<para>unsigned int *cap</para>
858</entry><entry
859 align="char">
860<para>Returns a bit array of supported sound formats.</para>
861</entry>
862 </row></tbody></tgroup></informaltable>
863&return-value-dvb;
864
865</section><section id="AUDIO_CLEAR_BUFFER"
866role="subsection"><title>AUDIO_CLEAR_BUFFER</title>
867<para>DESCRIPTION
868</para>
869<informaltable><tgroup cols="1"><tbody><row><entry
870 align="char">
871<para>This ioctl call asks the Audio Device to clear all software and hardware buffers
872 of the audio decoder device.</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 = AUDIO_CLEAR_BUFFER);</para>
880</entry>
881 </row></tbody></tgroup></informaltable>
882<para>PARAMETERS
883</para>
884<informaltable><tgroup cols="2"><tbody><row><entry
885 align="char">
886<para>int fd</para>
887</entry><entry
888 align="char">
889<para>File descriptor returned by a previous call to open().</para>
890</entry>
891 </row><row><entry
892 align="char">
893<para>int request</para>
894</entry><entry
895 align="char">
896<para>Equals AUDIO_CLEAR_BUFFER for this command.</para>
897</entry>
898 </row></tbody></tgroup></informaltable>
899&return-value-dvb;
900
901</section><section id="AUDIO_SET_ID"
902role="subsection"><title>AUDIO_SET_ID</title>
903<para>DESCRIPTION
904</para>
905<informaltable><tgroup cols="1"><tbody><row><entry
906 align="char">
907<para>This ioctl selects which sub-stream is to be decoded if a program or system
908 stream is sent to the video device. If no audio stream type is set the id has to be
909 in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7]
910 for LPCM. More specifications may follow for other stream types. If the stream
911 type is set the id just specifies the substream id of the audio stream and only
912 the first 5 bits are recognized.</para>
913</entry>
914 </row></tbody></tgroup></informaltable>
915<para>SYNOPSIS
916</para>
917<informaltable><tgroup cols="1"><tbody><row><entry
918 align="char">
919<para>int ioctl(int fd, int request = AUDIO_SET_ID, int
920 id);</para>
921</entry>
922 </row></tbody></tgroup></informaltable>
923<para>PARAMETERS
924</para>
925<informaltable><tgroup cols="2"><tbody><row><entry
926 align="char">
927<para>int fd</para>
928</entry><entry
929 align="char">
930<para>File descriptor returned by a previous call to open().</para>
931</entry>
932 </row><row><entry
933 align="char">
934<para>int request</para>
935</entry><entry
936 align="char">
937<para>Equals AUDIO_SET_ID for this command.</para>
938</entry>
939 </row><row><entry
940 align="char">
941<para>int id</para>
942</entry><entry
943 align="char">
944<para>audio sub-stream id</para>
945</entry>
946 </row></tbody></tgroup></informaltable>
947&return-value-dvb;
948
949</section><section id="AUDIO_SET_MIXER"
950role="subsection"><title>AUDIO_SET_MIXER</title>
951<para>DESCRIPTION
952</para>
953<informaltable><tgroup cols="1"><tbody><row><entry
954 align="char">
955<para>This ioctl lets you adjust the mixer settings of the audio decoder.</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(int fd, int request = AUDIO_SET_MIXER,
963 audio_mixer_t &#x22C6;mix);</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 AUDIO_SET_ID for this command.</para>
981</entry>
982 </row><row><entry
983 align="char">
984<para>audio_mixer_t *mix</para>
985</entry><entry
986 align="char">
987<para>mixer settings.</para>
988</entry>
989 </row></tbody></tgroup></informaltable>
990&return-value-dvb;
991
992</section><section id="AUDIO_SET_STREAMTYPE"
993role="subsection"><title>AUDIO_SET_STREAMTYPE</title>
994<para>DESCRIPTION
995</para>
996<informaltable><tgroup cols="1"><tbody><row><entry
997 align="char">
998<para>This ioctl tells the driver which kind of audio stream to expect. This is useful
999 if the stream offers several audio sub-streams like LPCM and AC3.</para>
1000</entry>
1001 </row></tbody></tgroup></informaltable>
1002<para>SYNOPSIS
1003</para>
1004<informaltable><tgroup cols="1"><tbody><row><entry
1005 align="char">
1006<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
1007 int type);</para>
1008</entry>
1009 </row></tbody></tgroup></informaltable>
1010<para>PARAMETERS
1011</para>
1012<informaltable><tgroup cols="2"><tbody><row><entry
1013 align="char">
1014<para>int fd</para>
1015</entry><entry
1016 align="char">
1017<para>File descriptor returned by a previous call to open().</para>
1018</entry>
1019 </row><row><entry
1020 align="char">
1021<para>int request</para>
1022</entry><entry
1023 align="char">
1024<para>Equals AUDIO_SET_STREAMTYPE for this
1025 command.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>int type</para>
1030</entry><entry
1031 align="char">
1032<para>stream type</para>
1033</entry>
1034 </row></tbody></tgroup></informaltable>
1035&return-value-dvb;
1036<informaltable><tgroup cols="2"><tbody><row><entry
1037 align="char">
1038<para>EINVAL</para>
1039</entry><entry
1040 align="char">
1041<para>type is not a valid or supported stream type.</para>
1042</entry>
1043 </row></tbody></tgroup></informaltable>
1044
1045</section><section id="AUDIO_SET_EXT_ID"
1046role="subsection"><title>AUDIO_SET_EXT_ID</title>
1047<para>DESCRIPTION
1048</para>
1049<informaltable><tgroup cols="1"><tbody><row><entry
1050 align="char">
1051<para>This ioctl can be used to set the extension id for MPEG streams in DVD
1052 playback. Only the first 3 bits are recognized.</para>
1053</entry>
1054 </row></tbody></tgroup></informaltable>
1055<para>SYNOPSIS
1056</para>
1057<informaltable><tgroup cols="1"><tbody><row><entry
1058 align="char">
1059<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int
1060 id);</para>
1061</entry>
1062 </row></tbody></tgroup></informaltable>
1063<para>PARAMETERS
1064</para>
1065<informaltable><tgroup cols="2"><tbody><row><entry
1066 align="char">
1067<para>int fd</para>
1068</entry><entry
1069 align="char">
1070<para>File descriptor returned by a previous call to open().</para>
1071</entry>
1072 </row><row><entry
1073 align="char">
1074<para>int request</para>
1075</entry><entry
1076 align="char">
1077<para>Equals AUDIO_SET_EXT_ID for this command.</para>
1078</entry>
1079 </row><row><entry
1080 align="char">
1081<para>int id</para>
1082</entry><entry
1083 align="char">
1084<para>audio sub_stream_id</para>
1085</entry>
1086 </row></tbody></tgroup></informaltable>
1087&return-value-dvb;
1088<informaltable><tgroup cols="2"><tbody><row><entry
1089 align="char">
1090<para>EINVAL</para>
1091</entry><entry
1092 align="char">
1093<para>id is not a valid id.</para>
1094</entry>
1095 </row></tbody></tgroup></informaltable>
1096
1097</section><section id="AUDIO_SET_ATTRIBUTES"
1098role="subsection"><title>AUDIO_SET_ATTRIBUTES</title>
1099<para>DESCRIPTION
1100</para>
1101<informaltable><tgroup cols="1"><tbody><row><entry
1102 align="char">
1103<para>This ioctl is intended for DVD playback and allows you to set certain
1104 information about the audio stream.</para>
1105</entry>
1106 </row></tbody></tgroup></informaltable>
1107<para>SYNOPSIS
1108</para>
1109<informaltable><tgroup cols="1"><tbody><row><entry
1110 align="char">
1111<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES,
1112 audio_attributes_t attr );</para>
1113</entry>
1114 </row></tbody></tgroup></informaltable>
1115<para>PARAMETERS
1116</para>
1117<informaltable><tgroup cols="2"><tbody><row><entry
1118 align="char">
1119<para>int fd</para>
1120</entry><entry
1121 align="char">
1122<para>File descriptor returned by a previous call to open().</para>
1123</entry>
1124 </row><row><entry
1125 align="char">
1126<para>int request</para>
1127</entry><entry
1128 align="char">
1129<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para>
1130</entry>
1131 </row><row><entry
1132 align="char">
1133<para>audio_attributes_t
1134 attr</para>
1135</entry><entry
1136 align="char">
1137<para>audio attributes according to section ??</para>
1138</entry>
1139 </row></tbody></tgroup></informaltable>
1140&return-value-dvb;
1141<informaltable><tgroup cols="2"><tbody><row><entry
1142 align="char">
1143<para>EINVAL</para>
1144</entry><entry
1145 align="char">
1146<para>attr is not a valid or supported attribute setting.</para>
1147</entry>
1148 </row></tbody></tgroup></informaltable>
1149
1150</section><section id="AUDIO_SET_KARAOKE"
1151role="subsection"><title>AUDIO_SET_KARAOKE</title>
1152<para>DESCRIPTION
1153</para>
1154<informaltable><tgroup cols="1"><tbody><row><entry
1155 align="char">
1156<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para>
1157</entry>
1158 </row></tbody></tgroup></informaltable>
1159<para>SYNOPSIS
1160</para>
1161<informaltable><tgroup cols="1"><tbody><row><entry
1162 align="char">
1163<para>int ioctl(fd, int request = AUDIO_SET_KARAOKE,
1164 audio_karaoke_t &#x22C6;karaoke);</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 AUDIO_SET_KARAOKE for this
1182 command.</para>
1183</entry>
1184 </row><row><entry
1185 align="char">
1186<para>audio_karaoke_t
1187 *karaoke</para>
1188</entry><entry
1189 align="char">
1190<para>karaoke settings according to section ??.</para>
1191</entry>
1192 </row></tbody></tgroup></informaltable>
1193&return-value-dvb;
1194<informaltable><tgroup cols="2"><tbody><row><entry
1195 align="char">
1196<para>EINVAL</para>
1197</entry><entry
1198 align="char">
1199<para>karaoke is not a valid or supported karaoke setting.</para>
1200</entry>
1201 </row></tbody></tgroup></informaltable>
1202 </section>
1203</section>
diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml
new file mode 100644
index 000000000000..5c4adb44b1c1
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/ca.xml
@@ -0,0 +1,229 @@
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</section>
diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml
new file mode 100644
index 000000000000..37c17908aa40
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/demux.xml
@@ -0,0 +1,902 @@
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></section>
diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
new file mode 100644
index 000000000000..2ab6ddcfc4e0
--- /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-2011</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.2</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 000000000000..207e1a5bf8f0
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -0,0 +1,859 @@
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, in HZ.</para>
167
168 <para>Notes:</para>
169 <para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
170 E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
171 the channel which is 6MHz.</para>
172
173 <para>2)As in ISDB-Tsb the channel consists of only one or three segments the
174 frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
175 central frequency of the channel is expected.</para>
176 </section>
177 <section id="DTV-MODULATION">
178 <title><constant>DTV_MODULATION</constant></title>
179<para>Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:</para>
180<programlisting>
181 typedef enum fe_modulation {
182 QPSK,
183 QAM_16,
184 QAM_32,
185 QAM_64,
186 QAM_128,
187 QAM_256,
188 QAM_AUTO,
189 VSB_8,
190 VSB_16,
191 PSK_8,
192 APSK_16,
193 APSK_32,
194 DQPSK,
195 } fe_modulation_t;
196</programlisting>
197 </section>
198 <section id="DTV-BANDWIDTH-HZ">
199 <title><constant>DTV_BANDWIDTH_HZ</constant></title>
200
201 <para>Bandwidth for the channel, in HZ.</para>
202
203 <para>Possible values:
204 <constant>1712000</constant>,
205 <constant>5000000</constant>,
206 <constant>6000000</constant>,
207 <constant>7000000</constant>,
208 <constant>8000000</constant>,
209 <constant>10000000</constant>.
210 </para>
211
212 <para>Notes:</para>
213
214 <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
215 <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
216 <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
217 for DVB-C depends on the symbol rate</para>
218 <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
219 other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
220 DTV_ISDBT_SB_SEGMENT_COUNT).</para>
221 <para>5) DVB-T supports 6, 7 and 8MHz.</para>
222 <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para>
223 </section>
224 <section id="DTV-INVERSION">
225 <title><constant>DTV_INVERSION</constant></title>
226 <para>The Inversion field can take one of these values:
227 </para>
228 <programlisting>
229 typedef enum fe_spectral_inversion {
230 INVERSION_OFF,
231 INVERSION_ON,
232 INVERSION_AUTO
233 } fe_spectral_inversion_t;
234 </programlisting>
235 <para>It indicates if spectral inversion should be presumed or not. In the automatic setting
236 (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
237 itself.
238 </para>
239 </section>
240 <section id="DTV-DISEQC-MASTER">
241 <title><constant>DTV_DISEQC_MASTER</constant></title>
242 <para>Currently not implemented.</para>
243 </section>
244 <section id="DTV-SYMBOL-RATE">
245 <title><constant>DTV_SYMBOL_RATE</constant></title>
246 <para>Digital TV symbol rate, in bauds (symbols/second). Used on cable standards.</para>
247 </section>
248 <section id="DTV-INNER-FEC">
249 <title><constant>DTV_INNER_FEC</constant></title>
250 <para>Used cable/satellite transmissions. The acceptable values are:
251 </para>
252 <programlisting>
253typedef enum fe_code_rate {
254 FEC_NONE = 0,
255 FEC_1_2,
256 FEC_2_3,
257 FEC_3_4,
258 FEC_4_5,
259 FEC_5_6,
260 FEC_6_7,
261 FEC_7_8,
262 FEC_8_9,
263 FEC_AUTO,
264 FEC_3_5,
265 FEC_9_10,
266} fe_code_rate_t;
267 </programlisting>
268 <para>which correspond to error correction rates of 1/2, 2/3, etc.,
269 no error correction or auto detection.</para>
270 </section>
271 <section id="DTV-VOLTAGE">
272 <title><constant>DTV_VOLTAGE</constant></title>
273 <para>The voltage is usually used with non-DiSEqC capable LNBs to switch
274 the polarzation (horizontal/vertical). When using DiSEqC epuipment this
275 voltage has to be switched consistently to the DiSEqC commands as
276 described in the DiSEqC spec.</para>
277 <programlisting>
278 typedef enum fe_sec_voltage {
279 SEC_VOLTAGE_13,
280 SEC_VOLTAGE_18
281 } fe_sec_voltage_t;
282 </programlisting>
283 </section>
284 <section id="DTV-TONE">
285 <title><constant>DTV_TONE</constant></title>
286 <para>Currently not used.</para>
287 </section>
288 <section id="DTV-PILOT">
289 <title><constant>DTV_PILOT</constant></title>
290 <para>Sets DVB-S2 pilot</para>
291 <section id="fe-pilot-t">
292 <title>fe_pilot type</title>
293 <programlisting>
294typedef enum fe_pilot {
295 PILOT_ON,
296 PILOT_OFF,
297 PILOT_AUTO,
298} fe_pilot_t;
299 </programlisting>
300 </section>
301 </section>
302 <section id="DTV-ROLLOFF">
303 <title><constant>DTV_ROLLOFF</constant></title>
304 <para>Sets DVB-S2 rolloff</para>
305
306 <section id="fe-rolloff-t">
307 <title>fe_rolloff type</title>
308 <programlisting>
309typedef enum fe_rolloff {
310 ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
311 ROLLOFF_20,
312 ROLLOFF_25,
313 ROLLOFF_AUTO,
314} fe_rolloff_t;
315 </programlisting>
316 </section>
317 </section>
318 <section id="DTV-DISEQC-SLAVE-REPLY">
319 <title><constant>DTV_DISEQC_SLAVE_REPLY</constant></title>
320 <para>Currently not implemented.</para>
321 </section>
322 <section id="DTV-FE-CAPABILITY-COUNT">
323 <title><constant>DTV_FE_CAPABILITY_COUNT</constant></title>
324 <para>Currently not implemented.</para>
325 </section>
326 <section id="DTV-FE-CAPABILITY">
327 <title><constant>DTV_FE_CAPABILITY</constant></title>
328 <para>Currently not implemented.</para>
329 </section>
330 <section id="DTV-DELIVERY-SYSTEM">
331 <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
332 <para>Specifies the type of Delivery system</para>
333 <section id="fe-delivery-system-t">
334 <title>fe_delivery_system type</title>
335 <para>Possible values: </para>
336<programlisting>
337typedef enum fe_delivery_system {
338 SYS_UNDEFINED,
339 SYS_DVBC_ANNEX_AC,
340 SYS_DVBC_ANNEX_B,
341 SYS_DVBT,
342 SYS_DSS,
343 SYS_DVBS,
344 SYS_DVBS2,
345 SYS_DVBH,
346 SYS_ISDBT,
347 SYS_ISDBS,
348 SYS_ISDBC,
349 SYS_ATSC,
350 SYS_ATSCMH,
351 SYS_DMBTH,
352 SYS_CMMB,
353 SYS_DAB,
354 SYS_DVBT2,
355} fe_delivery_system_t;
356</programlisting>
357 </section>
358 </section>
359 <section id="DTV-ISDBT-PARTIAL-RECEPTION">
360 <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
361
362 <para>If <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
363 the channel is in partial reception mode or not.</para>
364
365 <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
366 <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
367
368 <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
369 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
370 is consisting of one segment and layer or three segments and two layers.</para>
371
372 <para>Possible values: 0, 1, -1 (AUTO)</para>
373 </section>
374 <section id="DTV-ISDBT-SOUND-BROADCASTING">
375 <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
376
377 <para>This field represents whether the other DTV_ISDBT_*-parameters are
378 referring to an ISDB-T and an ISDB-Tsb channel. (See also
379 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
380
381 <para>Possible values: 0, 1, -1 (AUTO)</para>
382 </section>
383 <section id="DTV-ISDBT-SB-SUBCHANNEL-ID">
384 <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
385
386 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
387
388 <para>(Note of the author: This might not be the correct description of the
389 <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
390 background needed to program a device)</para>
391
392 <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
393 set of connected ISDB-Tsb channels. In this set of channels every
394 channel can be received independently. The number of connected
395 ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
396 bandwidth available.</para>
397
398 <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
399 broadcaster has several possibilities to put those channels in the
400 air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
401 segments from position 1-8 to 5-13 or anything in between.</para>
402
403 <para>The underlying layer of segments are subchannels: each segment is
404 consisting of several subchannels with a predefined IDs. A sub-channel
405 is used to help the demodulator to synchronize on the channel.</para>
406
407 <para>An ISDB-T channel is always centered over all sub-channels. As for
408 the example above, in ISDB-Tsb it is no longer as simple as that.</para>
409
410 <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
411 sub-channel ID of the segment to be demodulated.</para>
412
413 <para>Possible values: 0 .. 41, -1 (AUTO)</para>
414 </section>
415 <section id="DTV-ISDBT-SB-SEGMENT-IDX">
416 <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
417 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
418 <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
419 demodulated for an ISDB-Tsb channel where several of them are
420 transmitted in the connected manner.</para>
421 <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
422 <para>Note: This value cannot be determined by an automatic channel search.</para>
423 </section>
424 <section id="DTV-ISDBT-SB-SEGMENT-COUNT">
425 <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
426 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
427 <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
428 channels.</para>
429 <para>Possible values: 1 .. 13</para>
430 <para>Note: This value cannot be determined by an automatic channel search.</para>
431 </section>
432 <section id="isdb-hierq-layers">
433 <title><constant>DTV-ISDBT-LAYER*</constant> parameters</title>
434 <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
435 ISDB-T hierarchical layers can be decoded simultaneously. For that
436 reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para>
437 <para>ISDB-T has 3 hierarchical layers which each can use a part of the
438 available segments. The total number of segments over all layers has
439 to 13 in ISDB-T.</para>
440 <para>There are 3 parameter sets, for Layers A, B and C.</para>
441 <section id="DTV-ISDBT-LAYER-ENABLED">
442 <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
443 <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
444 layers in the decoding process. Setting all bits of
445 <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
446 demodulated. This is the default.</para>
447 <para>If the channel is in the partial reception mode
448 (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
449 independently of the other 12 segments. In that mode layer A has to
450 have a <constant>SEGMENT_COUNT</constant> of 1.</para>
451 <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
452 according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
453 accordingly.</para>
454 <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
455 <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
456 <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
457 <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
458 <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
459 </section>
460 <section id="DTV-ISDBT-LAYER-FEC">
461 <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
462 <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>
463 </section>
464 <section id="DTV-ISDBT-LAYER-MODULATION">
465 <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
466 <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
467 <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
468 and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
469 </section>
470 <section id="DTV-ISDBT-LAYER-SEGMENT-COUNT">
471 <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
472 <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
473 <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
474 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
475 <informaltable id="isdbt-layer_seg-cnt-table">
476 <tgroup cols="6">
477 <tbody>
478 <row>
479 <entry>PR</entry>
480 <entry>SB</entry>
481 <entry>Layer A width</entry>
482 <entry>Layer B width</entry>
483 <entry>Layer C width</entry>
484 <entry>total width</entry>
485 </row>
486 <row>
487 <entry>0</entry>
488 <entry>0</entry>
489 <entry>1 .. 13</entry>
490 <entry>1 .. 13</entry>
491 <entry>1 .. 13</entry>
492 <entry>13</entry>
493 </row>
494 <row>
495 <entry>1</entry>
496 <entry>0</entry>
497 <entry>1</entry>
498 <entry>1 .. 13</entry>
499 <entry>1 .. 13</entry>
500 <entry>13</entry>
501 </row>
502 <row>
503 <entry>0</entry>
504 <entry>1</entry>
505 <entry>1</entry>
506 <entry>0</entry>
507 <entry>0</entry>
508 <entry>1</entry>
509 </row>
510 <row>
511 <entry>1</entry>
512 <entry>1</entry>
513 <entry>1</entry>
514 <entry>2</entry>
515 <entry>0</entry>
516 <entry>13</entry>
517 </row>
518 </tbody>
519 </tgroup>
520 </informaltable>
521 </section>
522 <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
523 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
524 <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
525 <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
526 here are referring to what can be found in the TMCC-structure -
527 independent of the mode.</para>
528 </section>
529 </section>
530 <section id="DTV-API-VERSION">
531 <title><constant>DTV_API_VERSION</constant></title>
532 <para>Returns the major/minor version of the DVB API</para>
533 </section>
534 <section id="DTV-CODE-RATE-HP">
535 <title><constant>DTV_CODE_RATE_HP</constant></title>
536 <para>Used on terrestrial transmissions. The acceptable values are:
537 </para>
538 <programlisting>
539typedef enum fe_code_rate {
540 FEC_NONE = 0,
541 FEC_1_2,
542 FEC_2_3,
543 FEC_3_4,
544 FEC_4_5,
545 FEC_5_6,
546 FEC_6_7,
547 FEC_7_8,
548 FEC_8_9,
549 FEC_AUTO,
550 FEC_3_5,
551 FEC_9_10,
552} fe_code_rate_t;
553 </programlisting>
554 </section>
555 <section id="DTV-CODE-RATE-LP">
556 <title><constant>DTV_CODE_RATE_LP</constant></title>
557 <para>Used on terrestrial transmissions. The acceptable values are:
558 </para>
559 <programlisting>
560typedef enum fe_code_rate {
561 FEC_NONE = 0,
562 FEC_1_2,
563 FEC_2_3,
564 FEC_3_4,
565 FEC_4_5,
566 FEC_5_6,
567 FEC_6_7,
568 FEC_7_8,
569 FEC_8_9,
570 FEC_AUTO,
571 FEC_3_5,
572 FEC_9_10,
573} fe_code_rate_t;
574 </programlisting>
575 </section>
576 <section id="DTV-GUARD-INTERVAL">
577 <title><constant>DTV_GUARD_INTERVAL</constant></title>
578
579 <para>Possible values are:</para>
580<programlisting>
581typedef enum fe_guard_interval {
582 GUARD_INTERVAL_1_32,
583 GUARD_INTERVAL_1_16,
584 GUARD_INTERVAL_1_8,
585 GUARD_INTERVAL_1_4,
586 GUARD_INTERVAL_AUTO,
587 GUARD_INTERVAL_1_128,
588 GUARD_INTERVAL_19_128,
589 GUARD_INTERVAL_19_256,
590} fe_guard_interval_t;
591</programlisting>
592
593 <para>Notes:</para>
594 <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
595 try to find the correct guard interval (if capable) and will use TMCC to fill
596 in the missing parameters.</para>
597 <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para>
598 </section>
599 <section id="DTV-TRANSMISSION-MODE">
600 <title><constant>DTV_TRANSMISSION_MODE</constant></title>
601
602 <para>Specifies the number of carriers used by the standard</para>
603
604 <para>Possible values are:</para>
605<programlisting>
606typedef enum fe_transmit_mode {
607 TRANSMISSION_MODE_2K,
608 TRANSMISSION_MODE_8K,
609 TRANSMISSION_MODE_AUTO,
610 TRANSMISSION_MODE_4K,
611 TRANSMISSION_MODE_1K,
612 TRANSMISSION_MODE_16K,
613 TRANSMISSION_MODE_32K,
614} fe_transmit_mode_t;
615</programlisting>
616 <para>Notes:</para>
617 <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
618 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
619
620 <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
621 hardware will try to find the correct FFT-size (if capable) and will
622 use TMCC to fill in the missing parameters.</para>
623 <para>3) DVB-T specifies 2K and 8K as valid sizes.</para>
624 <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para>
625 </section>
626 <section id="DTV-HIERARCHY">
627 <title><constant>DTV_HIERARCHY</constant></title>
628 <para>Frontend hierarchy</para>
629 <programlisting>
630typedef enum fe_hierarchy {
631 HIERARCHY_NONE,
632 HIERARCHY_1,
633 HIERARCHY_2,
634 HIERARCHY_4,
635 HIERARCHY_AUTO
636 } fe_hierarchy_t;
637 </programlisting>
638 </section>
639 <section id="DTV-ISDBS-TS-ID">
640 <title><constant>DTV_ISDBS_TS_ID</constant></title>
641 <para>Currently unused.</para>
642 </section>
643 <section id="DTV-DVBT2-PLP-ID">
644 <title><constant>DTV_DVBT2_PLP_ID</constant></title>
645 <para>DVB-T2 supports Physical Layer Pipes (PLP) to allow transmission of
646 many data types via a single multiplex. The API will soon support this
647 at which point this section will be expanded.</para>
648 </section>
649</section>
650 <section id="frontend-property-terrestrial-systems">
651 <title>Properties used on terrestrial delivery systems</title>
652 <section id="dvbt-params">
653 <title>DVB-T delivery system</title>
654 <para>The following parameters are valid for DVB-T:</para>
655 <itemizedlist mark='opencircle'>
656 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
657 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
658 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
659 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
660 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
661 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
662 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
663 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
664 <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
665 <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
666 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
667 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
668 <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
669 </itemizedlist>
670 </section>
671 <section id="dvbt2-params">
672 <title>DVB-T2 delivery system</title>
673 <para>DVB-T2 support is currently in the early stages
674 of development, so expect that this section maygrow and become
675 more detailed with time.</para>
676 <para>The following parameters are valid for DVB-T2:</para>
677 <itemizedlist mark='opencircle'>
678 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
679 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
680 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
681 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
682 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
683 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
684 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
685 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
686 <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
687 <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
688 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
689 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
690 <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
691 <listitem><para><link linkend="DTV-DVBT2-PLP-ID"><constant>DTV_DVBT2_PLP_ID</constant></link></para></listitem>
692 </itemizedlist>
693 </section>
694 <section id="isdbt">
695 <title>ISDB-T delivery system</title>
696 <para>This ISDB-T/ISDB-Tsb API extension should reflect all information
697 needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
698 that some very sophisticated devices won't need certain parameters to
699 tune.</para>
700 <para>The information given here should help application writers to know how
701 to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
702 <para>The details given here about ISDB-T and ISDB-Tsb are just enough to
703 basically show the dependencies between the needed parameter values,
704 but surely some information is left out. For more detailed information
705 see the following documents:</para>
706 <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
707 Television Broadcasting" and</para>
708 <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
709 Television Broadcasting".</para>
710 <para>In order to understand the ISDB specific parameters,
711 one has to have some knowledge the channel structure in
712 ISDB-T and ISDB-Tsb. I.e. it has to be known to
713 the reader that an ISDB-T channel consists of 13 segments,
714 that it can have up to 3 layer sharing those segments,
715 and things like that.</para>
716 <para>The following parameters are valid for ISDB-T:</para>
717 <itemizedlist mark='opencircle'>
718 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
719 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
720 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
721 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
722 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
723 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
724 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
725 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
726 <listitem><para><link linkend="DTV-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem>
727 <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</constant></link></para></listitem>
728 <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem>
729 <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem>
730 <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem>
731 <listitem><para><link linkend="DTV-ISDBT-LAYER-ENABLED"><constant>DTV_ISDBT_LAYER_ENABLED</constant></link></para></listitem>
732 <listitem><para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION"><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></link></para></listitem>
733 <listitem><para><link linkend="DTV-ISDBT-SOUND-BROADCASTING"><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></link></para></listitem>
734 <listitem><para><link linkend="DTV-ISDBT-SB-SUBCHANNEL-ID"><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></link></para></listitem>
735 <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-IDX"><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></link></para></listitem>
736 <listitem><para><link linkend="DTV-ISDBT-SB-SEGMENT-COUNT"><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></link></para></listitem>
737 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERA_FEC</constant></link></para></listitem>
738 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERA_MODULATION</constant></link></para></listitem>
739 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant></link></para></listitem>
740 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERA_TIME_INTERLEAVING</constant></link></para></listitem>
741 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERB_FEC</constant></link></para></listitem>
742 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERB_MODULATION</constant></link></para></listitem>
743 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERB_SEGMENT_COUNT</constant></link></para></listitem>
744 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERB_TIME_INTERLEAVING</constant></link></para></listitem>
745 <listitem><para><link linkend="DTV-ISDBT-LAYER-FEC"><constant>DTV_ISDBT_LAYERC_FEC</constant></link></para></listitem>
746 <listitem><para><link linkend="DTV-ISDBT-LAYER-MODULATION"><constant>DTV_ISDBT_LAYERC_MODULATION</constant></link></para></listitem>
747 <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERC_SEGMENT_COUNT</constant></link></para></listitem>
748 <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERC_TIME_INTERLEAVING</constant></link></para></listitem>
749 </itemizedlist>
750 </section>
751 <section id="atsc-params">
752 <title>ATSC delivery system</title>
753 <para>The following parameters are valid for ATSC:</para>
754 <itemizedlist mark='opencircle'>
755 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
756 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
757 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
758 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
759 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
760 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
761 <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem>
762 </itemizedlist>
763 </section>
764 </section>
765 <section id="frontend-property-cable-systems">
766 <title>Properties used on cable delivery systems</title>
767 <section id="dvbc-params">
768 <title>DVB-C delivery system</title>
769 <para>The DVB-C Annex-A/C is the widely used cable standard. Transmission uses QAM modulation.</para>
770 <para>The following parameters are valid for DVB-C Annex A/C:</para>
771 <itemizedlist mark='opencircle'>
772 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
773 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
774 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
775 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
776 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
777 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
778 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
779 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
780 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
781 </itemizedlist>
782 </section>
783 <section id="dvbc-annex-b-params">
784 <title>DVB-C Annex B delivery system</title>
785 <para>The DVB-C Annex-B is only used on a few Countries like the United States.</para>
786 <para>The following parameters are valid for DVB-C Annex B:</para>
787 <itemizedlist mark='opencircle'>
788 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
789 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
790 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
791 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
792 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
793 <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem>
794 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
795 </itemizedlist>
796 </section>
797 </section>
798 <section id="frontend-property-satellital-systems">
799 <title>Properties used on satellital delivery systems</title>
800 <section id="dvbs-params">
801 <title>DVB-S delivery system</title>
802 <para>The following parameters are valid for DVB-S:</para>
803 <itemizedlist mark='opencircle'>
804 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
805 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
806 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
807 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
808 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
809 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
810 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
811 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
812 </itemizedlist>
813 <para>Future implementations might add those two missing parameters:</para>
814 <itemizedlist mark='opencircle'>
815 <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem>
816 <listitem><para><link linkend="DTV-DISEQC-SLAVE-REPLY"><constant>DTV_DISEQC_SLAVE_REPLY</constant></link></para></listitem>
817 </itemizedlist>
818 </section>
819 <section id="dvbs2-params">
820 <title>DVB-S2 delivery system</title>
821 <para>The following parameters are valid for DVB-S2:</para>
822 <itemizedlist mark='opencircle'>
823 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
824 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
825 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
826 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
827 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
828 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
829 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
830 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
831 <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
832 <listitem><para><link linkend="DTV-TONE"><constant>DTV_TONE</constant></link></para></listitem>
833 <listitem><para><link linkend="DTV-PILOT"><constant>DTV_PILOT</constant></link></para></listitem>
834 <listitem><para><link linkend="DTV-ROLLOFF"><constant>DTV_ROLLOFF</constant></link></para></listitem>
835 </itemizedlist>
836 <para>Future implementations might add those two missing parameters:</para>
837 <itemizedlist mark='opencircle'>
838 <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem>
839 <listitem><para><link linkend="DTV-DISEQC-SLAVE-REPLY"><constant>DTV_DISEQC_SLAVE_REPLY</constant></link></para></listitem>
840 </itemizedlist>
841 </section>
842 <section id="isdbs-params">
843 <title>ISDB-S delivery system</title>
844 <para>The following parameters are valid for ISDB-S:</para>
845 <itemizedlist mark='opencircle'>
846 <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem>
847 <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem>
848 <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem>
849 <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem>
850 <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem>
851 <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem>
852 <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem>
853 <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem>
854 <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem>
855 <listitem><para><link linkend="DTV-ISDBS-TS-ID"><constant>DTV_ISDBS_TS_ID</constant></link></para></listitem>
856 </itemizedlist>
857 </section>
858 </section>
859</section>
diff --git a/Documentation/DocBook/media/dvb/dvbstb.pdf b/Documentation/DocBook/media/dvb/dvbstb.pdf
new file mode 100644
index 000000000000..0fa75d90c3eb
--- /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 000000000000..f037e568eb6e
--- /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 000000000000..61407eaba020
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/frontend.xml
@@ -0,0 +1,1515 @@
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/C standard</entry>
49 <entry><constant>SYS_DVBC_ANNEX_AC</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</section>
67
68<section id="fe-caps-t">
69<title>frontend capabilities</title>
70
71<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for
72a specific frontend type.</para>
73<programlisting>
74 typedef enum fe_caps {
75 FE_IS_STUPID = 0,
76 FE_CAN_INVERSION_AUTO = 0x1,
77 FE_CAN_FEC_1_2 = 0x2,
78 FE_CAN_FEC_2_3 = 0x4,
79 FE_CAN_FEC_3_4 = 0x8,
80 FE_CAN_FEC_4_5 = 0x10,
81 FE_CAN_FEC_5_6 = 0x20,
82 FE_CAN_FEC_6_7 = 0x40,
83 FE_CAN_FEC_7_8 = 0x80,
84 FE_CAN_FEC_8_9 = 0x100,
85 FE_CAN_FEC_AUTO = 0x200,
86 FE_CAN_QPSK = 0x400,
87 FE_CAN_QAM_16 = 0x800,
88 FE_CAN_QAM_32 = 0x1000,
89 FE_CAN_QAM_64 = 0x2000,
90 FE_CAN_QAM_128 = 0x4000,
91 FE_CAN_QAM_256 = 0x8000,
92 FE_CAN_QAM_AUTO = 0x10000,
93 FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
94 FE_CAN_BANDWIDTH_AUTO = 0x40000,
95 FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
96 FE_CAN_HIERARCHY_AUTO = 0x100000,
97 FE_CAN_8VSB = 0x200000,
98 FE_CAN_16VSB = 0x400000,
99 FE_HAS_EXTENDED_CAPS = 0x800000,
100 FE_CAN_TURBO_FEC = 0x8000000,
101 FE_CAN_2G_MODULATION = 0x10000000,
102 FE_NEEDS_BENDING = 0x20000000,
103 FE_CAN_RECOVER = 0x40000000,
104 FE_CAN_MUTE_TS = 0x80000000
105 } fe_caps_t;
106</programlisting>
107</section>
108
109<section id="dvb-frontend-info">
110<title>frontend information</title>
111
112<para>Information about the frontend ca be queried with
113 <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
114
115<programlisting>
116 struct dvb_frontend_info {
117 char name[128];
118 fe_type_t type;
119 uint32_t frequency_min;
120 uint32_t frequency_max;
121 uint32_t frequency_stepsize;
122 uint32_t frequency_tolerance;
123 uint32_t symbol_rate_min;
124 uint32_t symbol_rate_max;
125 uint32_t symbol_rate_tolerance; /&#x22C6; ppm &#x22C6;/
126 uint32_t notifier_delay; /&#x22C6; ms &#x22C6;/
127 fe_caps_t caps;
128 };
129</programlisting>
130</section>
131
132<section id="dvb-diseqc-master-cmd">
133<title>diseqc master command</title>
134
135<para>A message sent from the frontend to DiSEqC capable equipment.</para>
136<programlisting>
137 struct dvb_diseqc_master_cmd {
138 uint8_t msg [6]; /&#x22C6; { framing, address, command, data[3] } &#x22C6;/
139 uint8_t msg_len; /&#x22C6; valid values are 3...6 &#x22C6;/
140 };
141</programlisting>
142</section>
143<section role="subsection" id="dvb-diseqc-slave-reply">
144<title>diseqc slave reply</title>
145
146<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para>
147<programlisting>
148 struct dvb_diseqc_slave_reply {
149 uint8_t msg [4]; /&#x22C6; { framing, data [3] } &#x22C6;/
150 uint8_t msg_len; /&#x22C6; valid values are 0...4, 0 means no msg &#x22C6;/
151 int timeout; /&#x22C6; return from ioctl after timeout ms with &#x22C6;/
152 }; /&#x22C6; errorcode when no message was received &#x22C6;/
153</programlisting>
154</section>
155
156<section id="fe-sec-voltage-t">
157<title>diseqc slave reply</title>
158<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation
159(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched
160consistently to the DiSEqC commands as described in the DiSEqC spec.</para>
161<programlisting>
162 typedef enum fe_sec_voltage {
163 SEC_VOLTAGE_13,
164 SEC_VOLTAGE_18
165 } fe_sec_voltage_t;
166</programlisting>
167</section>
168
169<section id="fe-sec-tone-mode-t">
170<title>SEC continuous tone</title>
171
172<para>The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the
173high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
174be switched consistently to the DiSEqC commands as described in the DiSEqC
175spec.</para>
176<programlisting>
177 typedef enum fe_sec_tone_mode {
178 SEC_TONE_ON,
179 SEC_TONE_OFF
180 } fe_sec_tone_mode_t;
181</programlisting>
182</section>
183
184<section id="fe-sec-mini-cmd-t">
185<title>SEC tone burst</title>
186
187<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select
188between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to
189be switched consistently to the DiSEqC commands as described in the DiSEqC
190spec.</para>
191<programlisting>
192 typedef enum fe_sec_mini_cmd {
193 SEC_MINI_A,
194 SEC_MINI_B
195 } fe_sec_mini_cmd_t;
196</programlisting>
197
198<para></para>
199</section>
200
201<section id="fe-status-t">
202<title>frontend status</title>
203<para>Several functions of the frontend device use the fe_status data type defined
204by</para>
205<programlisting>
206 typedef enum fe_status {
207 FE_HAS_SIGNAL = 0x01, /&#x22C6; found something above the noise level &#x22C6;/
208 FE_HAS_CARRIER = 0x02, /&#x22C6; found a DVB signal &#x22C6;/
209 FE_HAS_VITERBI = 0x04, /&#x22C6; FEC is stable &#x22C6;/
210 FE_HAS_SYNC = 0x08, /&#x22C6; found sync bytes &#x22C6;/
211 FE_HAS_LOCK = 0x10, /&#x22C6; everything's working... &#x22C6;/
212 FE_TIMEDOUT = 0x20, /&#x22C6; no lock within the last ~2 seconds &#x22C6;/
213 FE_REINIT = 0x40 /&#x22C6; frontend was reinitialized, &#x22C6;/
214 } fe_status_t; /&#x22C6; application is recommned to reset &#x22C6;/
215</programlisting>
216<para>to indicate the current state and/or state changes of the frontend hardware.
217</para>
218
219</section>
220
221<section id="dvb-frontend-parameters">
222<title>frontend parameters</title>
223<para>The kind of parameters passed to the frontend device for tuning depend on
224the kind of hardware you are using.</para>
225<para>The struct <constant>dvb_frontend_parameters</constant> uses an
226union with specific per-system parameters. However, as newer delivery systems
227required more data, the structure size weren't enough to fit, and just
228extending its size would break the existing applications. So, those parameters
229were replaced by the usage of <link linkend="FE_GET_SET_PROPERTY">
230<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The
231new API is flexible enough to add new parameters to existing delivery systems,
232and to add newer delivery systems.</para>
233<para>So, newer applications should use <link linkend="FE_GET_SET_PROPERTY">
234<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in
235order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
236DVB-C2, ISDB, etc.</para>
237<para>All kinds of parameters are combined as an union in the FrontendParameters structure:</para>
238<programlisting>
239struct dvb_frontend_parameters {
240 uint32_t frequency; /&#x22C6; (absolute) frequency in Hz for QAM/OFDM &#x22C6;/
241 /&#x22C6; intermediate frequency in kHz for QPSK &#x22C6;/
242 fe_spectral_inversion_t inversion;
243 union {
244 struct dvb_qpsk_parameters qpsk;
245 struct dvb_qam_parameters qam;
246 struct dvb_ofdm_parameters ofdm;
247 struct dvb_vsb_parameters vsb;
248 } u;
249};
250</programlisting>
251<para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate
252frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
253the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
254OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz.
255</para>
256<section id="dvb-qpsk-parameters">
257<title>QPSK parameters</title>
258<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para>
259<programlisting>
260 struct dvb_qpsk_parameters {
261 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
262 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
263 };
264</programlisting>
265</section>
266<section id="dvb-qam-parameters">
267<title>QAM parameters</title>
268<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para>
269<programlisting>
270 struct dvb_qam_parameters {
271 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
272 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
273 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
274 };
275</programlisting>
276</section>
277<section id="dvb-vsb-parameters">
278<title>VSB parameters</title>
279<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para>
280<programlisting>
281struct dvb_vsb_parameters {
282 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
283};
284</programlisting>
285</section>
286<section id="dvb-ofdm-parameters">
287<title>OFDM parameters</title>
288<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para>
289<programlisting>
290 struct dvb_ofdm_parameters {
291 fe_bandwidth_t bandwidth;
292 fe_code_rate_t code_rate_HP; /&#x22C6; high priority stream code rate &#x22C6;/
293 fe_code_rate_t code_rate_LP; /&#x22C6; low priority stream code rate &#x22C6;/
294 fe_modulation_t constellation; /&#x22C6; modulation type (see above) &#x22C6;/
295 fe_transmit_mode_t transmission_mode;
296 fe_guard_interval_t guard_interval;
297 fe_hierarchy_t hierarchy_information;
298 };
299</programlisting>
300</section>
301<section id="fe-spectral-inversion-t">
302<title>frontend spectral inversion</title>
303<para>The Inversion field can take one of these values:
304</para>
305<programlisting>
306typedef enum fe_spectral_inversion {
307 INVERSION_OFF,
308 INVERSION_ON,
309 INVERSION_AUTO
310} fe_spectral_inversion_t;
311</programlisting>
312<para>It indicates if spectral inversion should be presumed or not. In the automatic setting
313(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
314itself.
315</para>
316</section>
317<section id="fe-code-rate-t">
318<title>frontend code rate</title>
319<para>The possible values for the <constant>fec_inner</constant> field used on
320<link refend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
321<link refend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
322</para>
323<programlisting>
324typedef enum fe_code_rate {
325 FEC_NONE = 0,
326 FEC_1_2,
327 FEC_2_3,
328 FEC_3_4,
329 FEC_4_5,
330 FEC_5_6,
331 FEC_6_7,
332 FEC_7_8,
333 FEC_8_9,
334 FEC_AUTO,
335 FEC_3_5,
336 FEC_9_10,
337} fe_code_rate_t;
338</programlisting>
339<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
340detection.
341</para>
342</section>
343<section id="fe-modulation-t">
344<title>frontend modulation type for QAM, OFDM and VSB</title>
345<para>For cable and terrestrial frontends, e. g. for
346<link refend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>,
347<link refend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and
348<link refend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>,
349it needs to specify the quadrature modulation mode which can be one of the following:
350</para>
351<programlisting>
352 typedef enum fe_modulation {
353 QPSK,
354 QAM_16,
355 QAM_32,
356 QAM_64,
357 QAM_128,
358 QAM_256,
359 QAM_AUTO,
360 VSB_8,
361 VSB_16,
362 PSK_8,
363 APSK_16,
364 APSK_32,
365 DQPSK,
366 } fe_modulation_t;
367</programlisting>
368</section>
369<para>Finally, there are several more parameters for OFDM:
370</para>
371<section id="fe-transmit-mode-t">
372<title>Number of carriers per channel</title>
373<programlisting>
374typedef enum fe_transmit_mode {
375 TRANSMISSION_MODE_2K,
376 TRANSMISSION_MODE_8K,
377 TRANSMISSION_MODE_AUTO,
378 TRANSMISSION_MODE_4K,
379 TRANSMISSION_MODE_1K,
380 TRANSMISSION_MODE_16K,
381 TRANSMISSION_MODE_32K,
382 } fe_transmit_mode_t;
383</programlisting>
384</section>
385<section id="fe-bandwidth-t">
386<title>frontend bandwidth</title>
387<programlisting>
388typedef enum fe_bandwidth {
389 BANDWIDTH_8_MHZ,
390 BANDWIDTH_7_MHZ,
391 BANDWIDTH_6_MHZ,
392 BANDWIDTH_AUTO,
393 BANDWIDTH_5_MHZ,
394 BANDWIDTH_10_MHZ,
395 BANDWIDTH_1_712_MHZ,
396} fe_bandwidth_t;
397</programlisting>
398</section>
399<section id="fe-guard-interval-t">
400<title>frontend guard inverval</title>
401<programlisting>
402typedef enum fe_guard_interval {
403 GUARD_INTERVAL_1_32,
404 GUARD_INTERVAL_1_16,
405 GUARD_INTERVAL_1_8,
406 GUARD_INTERVAL_1_4,
407 GUARD_INTERVAL_AUTO,
408 GUARD_INTERVAL_1_128,
409 GUARD_INTERVAL_19_128,
410 GUARD_INTERVAL_19_256,
411} fe_guard_interval_t;
412</programlisting>
413</section>
414<section id="fe-hierarchy-t">
415<title>frontend hierarchy</title>
416<programlisting>
417typedef enum fe_hierarchy {
418 HIERARCHY_NONE,
419 HIERARCHY_1,
420 HIERARCHY_2,
421 HIERARCHY_4,
422 HIERARCHY_AUTO
423 } fe_hierarchy_t;
424</programlisting>
425</section>
426
427</section>
428
429<section id="dvb-frontend-event">
430<title>frontend events</title>
431 <programlisting>
432 struct dvb_frontend_event {
433 fe_status_t status;
434 struct dvb_frontend_parameters parameters;
435 };
436</programlisting>
437 </section>
438</section>
439
440
441<section id="frontend_fcalls">
442<title>Frontend Function Calls</title>
443
444<section id="frontend_f_open">
445<title>open()</title>
446<para>DESCRIPTION</para>
447<informaltable><tgroup cols="1"><tbody><row>
448<entry align="char">
449<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
450 for subsequent use. Usually the first thing to do after a successful open is to
451 find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
452<para>The device can be opened in read-only mode, which only allows monitoring of
453 device status and statistics, or read/write mode, which allows any kind of use
454 (e.g. performing tuning operations.)
455</para>
456<para>In a system with multiple front-ends, it is usually the case that multiple devices
457 cannot be open in read/write mode simultaneously. As long as a front-end
458 device is opened in read/write mode, other open() calls in read/write mode will
459 either fail or block, depending on whether non-blocking or blocking mode was
460 specified. A front-end device opened in blocking mode can later be put into
461 non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
462 system call. This is a standard system call, documented in the Linux manual
463 page for fcntl. When an open() call has succeeded, the device will be ready
464 for use in the specified mode. This implies that the corresponding hardware is
465 powered up, and that other front-ends may have been powered down to make
466 that possible.</para>
467</entry>
468 </row></tbody></tgroup></informaltable>
469
470<para>SYNOPSIS</para>
471<informaltable><tgroup cols="1"><tbody><row><entry
472 align="char">
473<para>int open(const char &#x22C6;deviceName, int flags);</para>
474</entry>
475 </row></tbody></tgroup></informaltable>
476<para>PARAMETERS
477</para>
478<informaltable><tgroup cols="2"><tbody><row><entry
479 align="char">
480<para>const char
481 *deviceName</para>
482</entry><entry
483 align="char">
484<para>Name of specific video device.</para>
485</entry>
486 </row><row><entry
487 align="char">
488<para>int flags</para>
489</entry><entry
490 align="char">
491<para>A bit-wise OR of the following flags:</para>
492</entry>
493 </row><row><entry
494 align="char">
495</entry><entry
496 align="char">
497<para>O_RDONLY read-only access</para>
498</entry>
499 </row><row><entry
500 align="char">
501</entry><entry
502 align="char">
503<para>O_RDWR read/write access</para>
504</entry>
505 </row><row><entry
506 align="char">
507</entry><entry
508 align="char">
509<para>O_NONBLOCK open in non-blocking mode</para>
510</entry>
511 </row><row><entry
512 align="char">
513</entry><entry
514 align="char">
515<para>(blocking mode is the default)</para>
516</entry>
517 </row></tbody></tgroup></informaltable>
518<para>RETURN VALUE</para>
519<informaltable><tgroup cols="2"><tbody><row><entry
520 align="char">
521<para>ENODEV</para>
522</entry><entry
523 align="char">
524<para>Device driver not loaded/available.</para>
525</entry>
526 </row><row><entry
527 align="char">
528<para>EINTERNAL</para>
529</entry><entry
530 align="char">
531<para>Internal error.</para>
532</entry>
533 </row><row><entry
534 align="char">
535<para>EBUSY</para>
536</entry><entry
537 align="char">
538<para>Device or resource busy.</para>
539</entry>
540 </row><row><entry
541 align="char">
542<para>EINVAL</para>
543</entry><entry
544 align="char">
545<para>Invalid argument.</para>
546</entry>
547 </row></tbody></tgroup></informaltable>
548</section>
549
550<section id="frontend_f_close">
551<title>close()</title>
552<para>DESCRIPTION
553</para>
554<informaltable><tgroup cols="1"><tbody><row><entry
555 align="char">
556<para>This system call closes a previously opened front-end device. After closing
557 a front-end device, its corresponding hardware might be powered down
558 automatically.</para>
559</entry>
560 </row></tbody></tgroup></informaltable>
561<para>SYNOPSIS
562</para>
563<informaltable><tgroup cols="1"><tbody><row><entry
564 align="char">
565<para>int close(int fd);</para>
566</entry>
567 </row></tbody></tgroup></informaltable>
568<para>PARAMETERS
569</para>
570<informaltable><tgroup cols="2"><tbody><row><entry
571 align="char">
572<para>int fd</para>
573</entry><entry
574 align="char">
575<para>File descriptor returned by a previous call to open().</para>
576</entry>
577 </row></tbody></tgroup></informaltable>
578<para>RETURN VALUE</para>
579<informaltable><tgroup cols="2"><tbody><row><entry
580 align="char">
581<para>EBADF</para>
582</entry><entry
583 align="char">
584<para>fd is not a valid open file descriptor.</para>
585</entry>
586 </row></tbody></tgroup></informaltable>
587</section>
588
589<section id="FE_READ_STATUS">
590<title>FE_READ_STATUS</title>
591<para>DESCRIPTION
592</para>
593<informaltable><tgroup cols="1"><tbody><row><entry
594 align="char">
595<para>This ioctl call returns status information about the front-end. This call only
596 requires read-only access to the device.</para>
597</entry>
598 </row></tbody></tgroup></informaltable>
599<para>SYNOPSIS
600</para>
601<informaltable><tgroup cols="1"><tbody><row><entry
602 align="char">
603<para>int ioctl(int fd, int request = <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>,
604 fe_status_t &#x22C6;status);</para>
605</entry>
606 </row></tbody></tgroup></informaltable>
607<para>PARAMETERS
608</para>
609
610<informaltable><tgroup cols="2"><tbody><row><entry
611 align="char">
612<para>int fd</para>
613</entry><entry
614 align="char">
615<para>File descriptor returned by a previous call to open().</para>
616</entry>
617 </row><row><entry
618 align="char">
619<para>int request</para>
620</entry><entry
621 align="char">
622<para>Equals <link linkend="FE_READ_STATUS">FE_READ_STATUS</link> for this command.</para>
623</entry>
624 </row><row><entry
625 align="char">
626<para>struct fe_status_t
627 *status</para>
628</entry><entry
629 align="char">
630<para>Points to the location where the front-end status word is
631 to be stored.</para>
632</entry>
633 </row></tbody></tgroup></informaltable>
634<para>RETURN VALUE</para>
635<informaltable><tgroup cols="2"><tbody><row><entry
636 align="char">
637<para>EBADF</para>
638</entry><entry
639 align="char">
640<para>fd is not a valid open file descriptor.</para>
641</entry>
642 </row><row><entry
643 align="char">
644<para>EFAULT</para>
645</entry><entry
646 align="char">
647<para>status points to invalid address.</para>
648</entry>
649 </row></tbody></tgroup></informaltable>
650</section>
651
652<section id="FE_READ_BER">
653<title>FE_READ_BER</title>
654<para>DESCRIPTION
655</para>
656<informaltable><tgroup cols="1"><tbody><row><entry
657 align="char">
658<para>This ioctl call returns the bit error rate for the signal currently
659 received/demodulated by the front-end. For this command, read-only access to
660 the device is sufficient.</para>
661</entry>
662 </row></tbody></tgroup></informaltable>
663<para>SYNOPSIS
664</para>
665<informaltable><tgroup cols="1"><tbody><row><entry
666 align="char">
667<para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>,
668 uint32_t &#x22C6;ber);</para>
669</entry>
670 </row></tbody></tgroup></informaltable>
671<para>PARAMETERS
672</para>
673<informaltable><tgroup cols="2"><tbody><row><entry
674 align="char">
675<para>int fd</para>
676</entry><entry
677 align="char">
678<para>File descriptor returned by a previous call to open().</para>
679</entry>
680 </row><row><entry
681 align="char">
682<para>int request</para>
683</entry><entry
684 align="char">
685<para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para>
686</entry>
687 </row><row><entry
688 align="char">
689<para>uint32_t *ber</para>
690</entry><entry
691 align="char">
692<para>The bit error rate is stored into *ber.</para>
693</entry>
694 </row></tbody></tgroup></informaltable>
695
696&return-value-dvb;
697</section>
698
699<section id="FE_READ_SNR">
700<title>FE_READ_SNR</title>
701
702<para>DESCRIPTION
703</para>
704<informaltable><tgroup cols="1"><tbody><row><entry
705 align="char">
706<para>This ioctl call returns the signal-to-noise ratio for the signal currently received
707 by the front-end. For this command, read-only access to the device is sufficient.</para>
708</entry>
709 </row></tbody></tgroup></informaltable>
710<para>SYNOPSIS
711</para>
712<informaltable><tgroup cols="1"><tbody><row><entry
713 align="char">
714<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, int16_t
715 &#x22C6;snr);</para>
716</entry>
717 </row></tbody></tgroup></informaltable>
718<para>PARAMETERS
719</para>
720<informaltable><tgroup cols="2"><tbody><row><entry
721 align="char">
722<para>int fd</para>
723</entry><entry
724 align="char">
725<para>File descriptor returned by a previous call to open().</para>
726</entry>
727 </row><row><entry
728 align="char">
729<para>int request</para>
730</entry><entry
731 align="char">
732<para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para>
733</entry>
734 </row><row><entry
735 align="char">
736<para>int16_t *snr</para>
737</entry><entry
738 align="char">
739<para>The signal-to-noise ratio is stored into *snr.</para>
740</entry>
741 </row></tbody></tgroup></informaltable>
742
743&return-value-dvb;
744</section>
745
746<section id="FE_READ_SIGNAL_STRENGTH">
747<title>FE_READ_SIGNAL_STRENGTH</title>
748<para>DESCRIPTION
749</para>
750<informaltable><tgroup cols="1"><tbody><row><entry
751 align="char">
752<para>This ioctl call returns the signal strength value for the signal currently received
753 by the front-end. For this command, read-only access to the device is sufficient.</para>
754</entry>
755 </row></tbody></tgroup></informaltable>
756<para>SYNOPSIS
757</para>
758<informaltable><tgroup cols="1"><tbody><row><entry
759 align="char">
760<para>int ioctl( int fd, int request =
761 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, int16_t &#x22C6;strength);</para>
762</entry>
763 </row></tbody></tgroup></informaltable>
764
765<para>PARAMETERS
766</para>
767<informaltable><tgroup cols="2"><tbody><row><entry
768 align="char">
769<para>int fd</para>
770</entry><entry
771 align="char">
772<para>File descriptor returned by a previous call to open().</para>
773</entry>
774 </row><row><entry
775 align="char">
776<para>int request</para>
777</entry><entry
778 align="char">
779<para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this
780 command.</para>
781</entry>
782 </row><row><entry
783 align="char">
784<para>int16_t *strength</para>
785</entry><entry
786 align="char">
787<para>The signal strength value is stored into *strength.</para>
788</entry>
789 </row></tbody></tgroup></informaltable>
790
791&return-value-dvb;
792</section>
793
794<section id="FE_READ_UNCORRECTED_BLOCKS">
795<title>FE_READ_UNCORRECTED_BLOCKS</title>
796<para>DESCRIPTION
797</para>
798<informaltable><tgroup cols="1"><tbody><row><entry
799 align="char">
800<para>This ioctl call returns the number of uncorrected blocks detected by the device
801 driver during its lifetime. For meaningful measurements, the increment in block
802 count during a specific time interval should be calculated. For this command,
803 read-only access to the device is sufficient.</para>
804</entry>
805 </row><row><entry
806 align="char">
807<para>Note that the counter will wrap to zero after its maximum count has been
808 reached.</para>
809</entry>
810 </row></tbody></tgroup></informaltable>
811<para>SYNOPSIS
812</para>
813<informaltable><tgroup cols="1"><tbody><row><entry
814 align="char">
815<para>int ioctl( int fd, int request =
816 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t &#x22C6;ublocks);</para>
817</entry>
818 </row></tbody></tgroup></informaltable>
819<para>PARAMETERS
820</para>
821<informaltable><tgroup cols="2"><tbody><row><entry
822 align="char">
823<para>int fd</para>
824</entry><entry
825 align="char">
826<para>File descriptor returned by a previous call to open().</para>
827</entry>
828 </row><row><entry
829 align="char">
830<para>int request</para>
831</entry><entry
832 align="char">
833<para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this
834 command.</para>
835</entry>
836 </row><row><entry
837 align="char">
838<para>uint32_t *ublocks</para>
839</entry><entry
840 align="char">
841<para>The total number of uncorrected blocks seen by the driver
842 so far.</para>
843</entry>
844 </row></tbody></tgroup></informaltable>
845
846&return-value-dvb;
847</section>
848
849<section id="FE_SET_FRONTEND">
850<title>FE_SET_FRONTEND</title>
851<para>DESCRIPTION
852</para>
853<informaltable><tgroup cols="1"><tbody><row><entry
854 align="char">
855<para>This ioctl call starts a tuning operation using specified parameters. The result
856 of this call will be successful if the parameters were valid and the tuning could
857 be initiated. The result of the tuning operation in itself, however, will arrive
858 asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and
859 FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before
860 the previous one was completed, the previous operation will be aborted in favor
861 of the new one. This command requires read/write access to the device.</para>
862</entry>
863 </row></tbody></tgroup></informaltable>
864
865<para>SYNOPSIS
866</para>
867<informaltable><tgroup cols="1"><tbody><row><entry
868 align="char">
869<para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>,
870 struct dvb_frontend_parameters &#x22C6;p);</para>
871</entry>
872 </row></tbody></tgroup></informaltable>
873<para>PARAMETERS
874</para>
875<informaltable><tgroup cols="2"><tbody><row><entry
876 align="char">
877<para>int fd</para>
878</entry><entry
879 align="char">
880<para>File descriptor returned by a previous call to open().</para>
881</entry>
882 </row><row><entry
883 align="char">
884<para>int request</para>
885</entry><entry
886 align="char">
887<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
888</entry>
889 </row><row><entry
890 align="char">
891<para>struct
892 dvb_frontend_parameters
893 *p</para>
894</entry><entry
895 align="char">
896<para>Points to parameters for tuning operation.</para>
897</entry>
898 </row></tbody></tgroup></informaltable>
899
900&return-value-dvb;
901<informaltable><tgroup cols="2"><tbody><row><entry
902 align="char">
903<para>EINVAL</para>
904</entry><entry
905 align="char">
906<para>Maximum supported symbol rate reached.</para>
907</entry>
908</row></tbody></tgroup></informaltable>
909</section>
910
911<section id="FE_GET_FRONTEND">
912<title>FE_GET_FRONTEND</title>
913<para>DESCRIPTION
914</para>
915<informaltable><tgroup cols="1"><tbody><row><entry
916 align="char">
917<para>This ioctl call queries the currently effective frontend parameters. For this
918 command, read-only access to the device is sufficient.</para>
919</entry>
920 </row></tbody></tgroup></informaltable>
921
922<para>SYNOPSIS
923</para>
924<informaltable><tgroup cols="1"><tbody><row><entry
925 align="char">
926<para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>,
927 struct dvb_frontend_parameters &#x22C6;p);</para>
928</entry>
929 </row></tbody></tgroup></informaltable>
930
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 <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
946</entry>
947 </row><row><entry
948 align="char">
949<para>struct
950 dvb_frontend_parameters
951 *p</para>
952</entry><entry
953 align="char">
954<para>Points to parameters for tuning operation.</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957
958&return-value-dvb;
959<informaltable><tgroup cols="2"><tbody><row><entry
960 align="char">
961<para>EINVAL</para>
962</entry><entry
963 align="char">
964<para>Maximum supported symbol rate reached.</para>
965</entry>
966 </row></tbody></tgroup></informaltable>
967
968</section>
969
970<section id="FE_GET_EVENT">
971<title>FE_GET_EVENT</title>
972<para>DESCRIPTION
973</para>
974<informaltable><tgroup cols="1"><tbody><row><entry
975 align="char">
976<para>This ioctl call returns a frontend event if available. If an event is not
977 available, the behavior depends on whether the device is in blocking or
978 non-blocking mode. In the latter case, the call fails immediately with errno
979 set to EWOULDBLOCK. In the former case, the call blocks until an event
980 becomes available.</para>
981</entry>
982 </row><row><entry
983 align="char">
984<para>The standard Linux poll() and/or select() system calls can be used with the
985 device file descriptor to watch for new events. For select(), the file descriptor
986 should be included in the exceptfds argument, and for poll(), POLLPRI should
987 be specified as the wake-up condition. Since the event queue allocated is
988 rather small (room for 8 events), the queue must be serviced regularly to avoid
989 overflow. If an overflow happens, the oldest event is discarded from the queue,
990 and an error (EOVERFLOW) occurs the next time the queue is read. After
991 reporting the error condition in this fashion, subsequent
992 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link>
993 calls will return events from the queue as usual.</para>
994</entry>
995 </row><row><entry
996 align="char">
997<para>For the sake of implementation simplicity, this command requires read/write
998 access to the device.</para>
999</entry>
1000 </row></tbody></tgroup></informaltable>
1001
1002<para>SYNOPSIS
1003</para>
1004<informaltable><tgroup cols="1"><tbody><row><entry
1005 align="char">
1006<para>int ioctl(int fd, int request = QPSK_GET_EVENT,
1007 struct dvb_frontend_event &#x22C6;ev);</para>
1008</entry>
1009 </row></tbody></tgroup></informaltable>
1010
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 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>struct
1030 dvb_frontend_event
1031 *ev</para>
1032</entry><entry
1033 align="char">
1034<para>Points to the location where the event,</para>
1035</entry>
1036 </row><row><entry
1037 align="char">
1038</entry><entry
1039 align="char">
1040<para>if any, is to be stored.</para>
1041</entry>
1042 </row></tbody></tgroup></informaltable>
1043
1044&return-value-dvb;
1045<informaltable><tgroup cols="2"><tbody><row><entry
1046 align="char">
1047<para>EWOULDBLOCK</para>
1048</entry><entry
1049 align="char">
1050<para>There is no event pending, and the device is in
1051 non-blocking mode.</para>
1052</entry>
1053 </row><row><entry
1054 align="char">
1055<para>EOVERFLOW</para>
1056</entry><entry
1057 align="char">
1058<para>Overflow in event queue - one or more events were lost.</para>
1059</entry>
1060</row></tbody></tgroup></informaltable>
1061</section>
1062
1063<section id="FE_GET_INFO">
1064<title>FE_GET_INFO</title>
1065<para>DESCRIPTION
1066</para>
1067<informaltable><tgroup cols="1"><tbody><row><entry
1068 align="char">
1069<para>This ioctl call returns information about the front-end. This call only requires
1070 read-only access to the device.</para>
1071</entry>
1072 </row></tbody></tgroup></informaltable>
1073<para>SYNOPSIS
1074</para>
1075
1076<informaltable><tgroup cols="1"><tbody><row><entry
1077 align="char">
1078<para> int ioctl(int fd, int request = <link linkend="FE_GET_INFO">FE_GET_INFO</link>, struct
1079 dvb_frontend_info &#x22C6;info);</para>
1080</entry>
1081 </row></tbody></tgroup></informaltable>
1082<para>PARAMETERS
1083</para>
1084
1085<informaltable><tgroup cols="2"><tbody><row><entry
1086 align="char">
1087<para>int fd</para>
1088</entry><entry
1089 align="char">
1090<para>File descriptor returned by a previous call to open().</para>
1091</entry>
1092 </row><row><entry
1093 align="char">
1094<para>int request</para>
1095</entry><entry
1096 align="char">
1097<para>Equals <link linkend="FE_GET_INFO">FE_GET_INFO</link> for this command.</para>
1098</entry>
1099 </row><row><entry
1100 align="char">
1101<para>struct
1102 dvb_frontend_info
1103 *info</para>
1104</entry><entry
1105 align="char">
1106<para>Points to the location where the front-end information is
1107 to be stored.</para>
1108</entry>
1109 </row></tbody></tgroup></informaltable>
1110&return-value-dvb;
1111</section>
1112
1113<section id="FE_DISEQC_RESET_OVERLOAD">
1114<title>FE_DISEQC_RESET_OVERLOAD</title>
1115<para>DESCRIPTION
1116</para>
1117<informaltable><tgroup cols="1"><tbody><row><entry
1118 align="char">
1119<para>If the bus has been automatically powered off due to power overload, this ioctl
1120 call restores the power to the bus. The call requires read/write access to the
1121 device. This call has no effect if the device is manually powered off. Not all
1122 DVB adapters support this ioctl.</para>
1123</entry>
1124 </row></tbody></tgroup></informaltable>
1125
1126<para>SYNOPSIS
1127</para>
1128<informaltable><tgroup cols="1"><tbody><row><entry
1129 align="char">
1130<para>int ioctl(int fd, int request =
1131 <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</para>
1132</entry>
1133 </row></tbody></tgroup></informaltable>
1134<para>PARAMETERS
1135</para>
1136<informaltable><tgroup cols="2"><tbody><row><entry
1137 align="char">
1138<para>int fd</para>
1139</entry><entry
1140 align="char">
1141<para>File descriptor returned by a previous call to open().</para>
1142</entry>
1143 </row><row><entry
1144 align="char">
1145<para>int request</para>
1146</entry><entry
1147 align="char">
1148<para>Equals <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this
1149 command.</para>
1150</entry>
1151 </row></tbody></tgroup></informaltable>
1152
1153&return-value-dvb;
1154</section>
1155
1156<section id="FE_DISEQC_SEND_MASTER_CMD">
1157<title>FE_DISEQC_SEND_MASTER_CMD</title>
1158<para>DESCRIPTION
1159</para>
1160<informaltable><tgroup cols="1"><tbody><row><entry
1161 align="char">
1162<para>This ioctl call is used to send a a DiSEqC command.</para>
1163</entry>
1164 </row></tbody></tgroup></informaltable>
1165<para>SYNOPSIS
1166</para>
1167<informaltable><tgroup cols="1"><tbody><row><entry
1168 align="char">
1169<para>int ioctl(int fd, int request =
1170 <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, struct
1171 dvb_diseqc_master_cmd &#x22C6;cmd);</para>
1172</entry>
1173 </row></tbody></tgroup></informaltable>
1174
1175<para>PARAMETERS
1176</para>
1177<informaltable><tgroup cols="2"><tbody><row><entry
1178 align="char">
1179<para>int fd</para>
1180</entry><entry
1181 align="char">
1182<para>File descriptor returned by a previous call to open().</para>
1183</entry>
1184 </row><row><entry
1185 align="char">
1186<para>int request</para>
1187</entry><entry
1188 align="char">
1189<para>Equals <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> for this
1190 command.</para>
1191</entry>
1192 </row><row><entry
1193 align="char">
1194<para>struct
1195 dvb_diseqc_master_cmd
1196 *cmd</para>
1197</entry><entry
1198 align="char">
1199<para>Pointer to the command to be transmitted.</para>
1200</entry>
1201 </row></tbody></tgroup></informaltable>
1202
1203&return-value-dvb;
1204</section>
1205
1206<section id="FE_DISEQC_RECV_SLAVE_REPLY">
1207<title>FE_DISEQC_RECV_SLAVE_REPLY</title>
1208<para>DESCRIPTION
1209</para>
1210<informaltable><tgroup cols="1"><tbody><row><entry
1211 align="char">
1212<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para>
1213</entry>
1214 </row></tbody></tgroup></informaltable>
1215
1216<para>SYNOPSIS
1217</para>
1218<informaltable><tgroup cols="1"><tbody><row><entry
1219 align="char">
1220<para>int ioctl(int fd, int request =
1221 <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, struct
1222 dvb_diseqc_slave_reply &#x22C6;reply);</para>
1223</entry>
1224 </row></tbody></tgroup></informaltable>
1225
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 <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> for this
1241 command.</para>
1242</entry>
1243 </row><row><entry
1244 align="char">
1245<para>struct
1246 dvb_diseqc_slave_reply
1247 *reply</para>
1248</entry><entry
1249 align="char">
1250<para>Pointer to the command to be received.</para>
1251</entry>
1252 </row></tbody></tgroup></informaltable>
1253&return-value-dvb;
1254</section>
1255
1256<section id="FE_DISEQC_SEND_BURST">
1257<title>FE_DISEQC_SEND_BURST</title>
1258<para>DESCRIPTION
1259</para>
1260<informaltable><tgroup cols="1"><tbody><row><entry
1261 align="char">
1262<para>This ioctl call is used to send a 22KHz tone burst.</para>
1263</entry>
1264 </row></tbody></tgroup></informaltable>
1265
1266<para>SYNOPSIS
1267</para>
1268<informaltable><tgroup cols="1"><tbody><row><entry
1269 align="char">
1270<para>int ioctl(int fd, int request =
1271 <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link>, fe_sec_mini_cmd_t burst);</para>
1272</entry>
1273 </row></tbody></tgroup></informaltable>
1274
1275<para>PARAMETERS
1276</para>
1277<informaltable><tgroup cols="2"><tbody><row><entry
1278 align="char">
1279<para>int fd</para>
1280</entry><entry
1281 align="char">
1282<para>File descriptor returned by a previous call to open().</para>
1283</entry>
1284 </row><row><entry
1285 align="char">
1286<para>int request</para>
1287</entry><entry
1288 align="char">
1289<para>Equals <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link> for this command.</para>
1290</entry>
1291 </row><row><entry
1292 align="char">
1293<para>fe_sec_mini_cmd_t
1294 burst</para>
1295</entry><entry
1296 align="char">
1297<para>burst A or B.</para>
1298</entry>
1299 </row></tbody></tgroup></informaltable>
1300
1301&return-value-dvb;
1302</section>
1303
1304<section id="FE_SET_TONE">
1305<title>FE_SET_TONE</title>
1306<para>DESCRIPTION
1307</para>
1308<informaltable><tgroup cols="1"><tbody><row><entry
1309 align="char">
1310<para>This call is used to set the generation of the continuous 22kHz tone. This call
1311 requires read/write permissions.</para>
1312</entry>
1313 </row></tbody></tgroup></informaltable>
1314<para>SYNOPSIS
1315</para>
1316<informaltable><tgroup cols="1"><tbody><row><entry
1317 align="char">
1318<para>int ioctl(int fd, int request = <link linkend="FE_SET_TONE">FE_SET_TONE</link>,
1319 fe_sec_tone_mode_t tone);</para>
1320</entry>
1321 </row></tbody></tgroup></informaltable>
1322<para>PARAMETERS
1323</para>
1324<informaltable><tgroup cols="2"><tbody><row><entry
1325 align="char">
1326<para>int fd</para>
1327</entry><entry
1328 align="char">
1329<para>File descriptor returned by a previous call to open().</para>
1330</entry>
1331 </row><row><entry
1332 align="char">
1333<para>int request</para>
1334</entry><entry
1335 align="char">
1336<para>Equals <link linkend="FE_SET_TONE">FE_SET_TONE</link> for this command.</para>
1337</entry>
1338 </row><row><entry
1339 align="char">
1340<para>fe_sec_tone_mode_t
1341 tone</para>
1342</entry><entry
1343 align="char">
1344<para>The requested tone generation mode (on/off).</para>
1345</entry>
1346 </row></tbody></tgroup></informaltable>
1347&return-value-dvb;
1348</section>
1349
1350<section id="FE_SET_VOLTAGE">
1351<title>FE_SET_VOLTAGE</title>
1352<para>DESCRIPTION
1353</para>
1354<informaltable><tgroup cols="1"><tbody><row><entry
1355 align="char">
1356<para>This call is used to set the bus voltage. This call requires read/write
1357 permissions.</para>
1358</entry>
1359 </row></tbody></tgroup></informaltable>
1360<para>SYNOPSIS
1361</para>
1362<informaltable><tgroup cols="1"><tbody><row><entry
1363 align="char">
1364<para>int ioctl(int fd, int request = <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link>,
1365 fe_sec_voltage_t voltage);</para>
1366</entry>
1367 </row></tbody></tgroup></informaltable>
1368
1369<para>PARAMETERS
1370</para>
1371<informaltable><tgroup cols="2"><tbody><row><entry
1372 align="char">
1373<para>int fd</para>
1374</entry><entry
1375 align="char">
1376<para>File descriptor returned by a previous call to open().</para>
1377</entry>
1378 </row><row><entry
1379 align="char">
1380<para>int request</para>
1381</entry><entry
1382 align="char">
1383<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1384</entry>
1385 </row><row><entry
1386 align="char">
1387<para>fe_sec_voltage_t
1388 voltage</para>
1389</entry><entry
1390 align="char">
1391<para>The requested bus voltage.</para>
1392</entry>
1393 </row></tbody></tgroup></informaltable>
1394
1395&return-value-dvb;
1396</section>
1397
1398<section id="FE_ENABLE_HIGH_LNB_VOLTAGE">
1399<title>FE_ENABLE_HIGH_LNB_VOLTAGE</title>
1400<para>DESCRIPTION
1401</para>
1402<informaltable><tgroup cols="1"><tbody><row><entry
1403 align="char">
1404<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate
1405 for long cables). This call requires read/write permissions. Not all DVB
1406 adapters support this ioctl.</para>
1407</entry>
1408 </row></tbody></tgroup></informaltable>
1409
1410<para>SYNOPSIS
1411</para>
1412<informaltable><tgroup cols="1"><tbody><row><entry
1413 align="char">
1414<para>int ioctl(int fd, int request =
1415 <link linkend="FE_ENABLE_HIGH_LNB_VOLTAGE">FE_ENABLE_HIGH_LNB_VOLTAGE</link>, int high);</para>
1416</entry>
1417 </row></tbody></tgroup></informaltable>
1418
1419<para>PARAMETERS
1420</para>
1421<informaltable><tgroup cols="2"><tbody><row><entry
1422 align="char">
1423<para>int fd</para>
1424</entry><entry
1425 align="char">
1426<para>File descriptor returned by a previous call to open().</para>
1427</entry>
1428 </row><row><entry
1429 align="char">
1430<para>int request</para>
1431</entry><entry
1432 align="char">
1433<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1434</entry>
1435 </row><row><entry
1436 align="char">
1437<para>int high</para>
1438</entry><entry
1439 align="char">
1440<para>The requested bus voltage.</para>
1441</entry>
1442 </row></tbody></tgroup></informaltable>
1443
1444&return-value-dvb;
1445</section>
1446
1447<section id="FE_SET_FRONTEND_TUNE_MODE">
1448<title>FE_SET_FRONTEND_TUNE_MODE</title>
1449<para>DESCRIPTION</para>
1450<informaltable><tgroup cols="1"><tbody><row>
1451<entry align="char">
1452<para>Allow setting tuner mode flags to the frontend.</para>
1453</entry>
1454</row></tbody></tgroup></informaltable>
1455
1456<para>SYNOPSIS</para>
1457<informaltable><tgroup cols="1"><tbody><row>
1458<entry align="char">
1459<para>int ioctl(int fd, int request =
1460<link linkend="FE_SET_FRONTEND_TUNE_MODE">FE_SET_FRONTEND_TUNE_MODE</link>, unsigned int flags);</para>
1461</entry>
1462</row></tbody></tgroup></informaltable>
1463
1464<para>PARAMETERS</para>
1465<informaltable><tgroup cols="2"><tbody><row>
1466<entry align="char">
1467 <para>unsigned int flags</para>
1468</entry>
1469<entry align="char">
1470<para>
1471FE_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.
1472</para>
1473</entry>
1474 </row></tbody></tgroup></informaltable>
1475
1476&return-value-dvb;
1477</section>
1478
1479<section id="FE_DISHNETWORK_SEND_LEGACY_CMD">
1480 <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title>
1481<para>DESCRIPTION</para>
1482<informaltable><tgroup cols="1"><tbody><row>
1483<entry align="char">
1484<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para>
1485<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para>
1486<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para>
1487</entry>
1488</row></tbody></tgroup></informaltable>
1489
1490<para>SYNOPSIS</para>
1491<informaltable><tgroup cols="1"><tbody><row>
1492<entry align="char">
1493<para>int ioctl(int fd, int request =
1494 <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para>
1495</entry>
1496</row></tbody></tgroup></informaltable>
1497
1498<para>PARAMETERS</para>
1499<informaltable><tgroup cols="2"><tbody><row>
1500<entry align="char">
1501 <para>unsigned long cmd</para>
1502</entry>
1503<entry align="char">
1504<para>
1505sends the specified raw cmd to the dish via DISEqC.
1506</para>
1507</entry>
1508 </row></tbody></tgroup></informaltable>
1509
1510&return-value-dvb;
1511</section>
1512
1513</section>
1514
1515&sub-dvbproperty;
diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml
new file mode 100644
index 000000000000..c75dc7cc3e9b
--- /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&#x00A0;3</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 000000000000..6c67481eaa4b
--- /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/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 000000000000..67d37e5ce597
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/net.xml
@@ -0,0 +1,29 @@
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</section>
diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml
new file mode 100644
index 000000000000..25fb823226b4
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/video.xml
@@ -0,0 +1,1657 @@
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<section id="video_types">
19<title>Video Data Types</title>
20
21<section id="video-format-t">
22<title>video_format_t</title>
23<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by
24</para>
25<programlisting>
26typedef enum {
27 VIDEO_FORMAT_4_3, /&#x22C6; Select 4:3 format &#x22C6;/
28 VIDEO_FORMAT_16_9, /&#x22C6; Select 16:9 format. &#x22C6;/
29 VIDEO_FORMAT_221_1 /&#x22C6; 2.21:1 &#x22C6;/
30} video_format_t;
31</programlisting>
32<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio
33the output hardware (e.g. TV) has. It is also used in the data structures video_status
34(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by
35VIDEO_GET_EVENT (??) which report about the display format of the current video
36stream.
37</para>
38</section>
39
40<section id="video-displayformat-t">
41<title>video_displayformat_t</title>
42<para>In case the display format of the video stream and of the display hardware differ the
43application has to specify how to handle the cropping of the picture. This can be done using
44the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
45</para>
46<programlisting>
47typedef enum {
48 VIDEO_PAN_SCAN, /&#x22C6; use pan and scan format &#x22C6;/
49 VIDEO_LETTER_BOX, /&#x22C6; use letterbox format &#x22C6;/
50 VIDEO_CENTER_CUT_OUT /&#x22C6; use center cut out format &#x22C6;/
51} video_displayformat_t;
52</programlisting>
53<para>as argument.
54</para>
55</section>
56
57<section id="video-stream-source-t">
58<title>video stream source</title>
59<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take
60the following values, depending on whether we are replaying from an internal (demuxer) or
61external (user write) source.
62</para>
63<programlisting>
64typedef enum {
65 VIDEO_SOURCE_DEMUX, /&#x22C6; Select the demux as the main source &#x22C6;/
66 VIDEO_SOURCE_MEMORY /&#x22C6; If this source is selected, the stream
67 comes from the user through the write
68 system call &#x22C6;/
69} video_stream_source_t;
70</programlisting>
71<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
72DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY
73is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
74call.
75</para>
76</section>
77
78<section id="video-play-state-t">
79<title>video play state</title>
80<para>The following values can be returned by the VIDEO_GET_STATUS call representing the
81state of video playback.
82</para>
83<programlisting>
84typedef enum {
85 VIDEO_STOPPED, /&#x22C6; Video is stopped &#x22C6;/
86 VIDEO_PLAYING, /&#x22C6; Video is currently playing &#x22C6;/
87 VIDEO_FREEZED /&#x22C6; Video is freezed &#x22C6;/
88} video_play_state_t;
89</programlisting>
90</section>
91
92<section id="video-command">
93<para>The structure must be zeroed before use by the application
94This ensures it can be extended safely in the future.</para>
95<title>struct video-command</title>
96<programlisting>
97struct video_command {
98 __u32 cmd;
99 __u32 flags;
100 union {
101 struct {
102 __u64 pts;
103 } stop;
104
105 struct {
106 /&#x22C6; 0 or 1000 specifies normal speed,
107 1 specifies forward single stepping,
108 -1 specifies backward single stepping,
109 &gt;>1: playback at speed/1000 of the normal speed,
110 &lt;-1: reverse playback at (-speed/1000) of the normal speed. &#x22C6;/
111 __s32 speed;
112 __u32 format;
113 } play;
114
115 struct {
116 __u32 data[16];
117 } raw;
118 };
119};
120</programlisting>
121</section>
122
123<section id="video-size-t">
124<title>struct video_size-t</title>
125<programlisting>
126typedef struct {
127 int w;
128 int h;
129 video_format_t aspect_ratio;
130} video_size_t;
131</programlisting>
132</section>
133
134
135<section id="video-event">
136<title>struct video_event</title>
137<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT
138call.
139</para>
140<programlisting>
141struct video_event {
142 __s32 type;
143#define VIDEO_EVENT_SIZE_CHANGED 1
144#define VIDEO_EVENT_FRAME_RATE_CHANGED 2
145#define VIDEO_EVENT_DECODER_STOPPED 3
146#define VIDEO_EVENT_VSYNC 4
147 __kernel_time_t timestamp;
148 union {
149 video_size_t size;
150 unsigned int frame_rate; /&#x22C6; in frames per 1000sec &#x22C6;/
151 unsigned char vsync_field; /&#x22C6; unknown/odd/even/progressive &#x22C6;/
152 } u;
153};
154</programlisting>
155</section>
156
157<section id="video-status">
158<title>struct video_status</title>
159<para>The VIDEO_GET_STATUS call returns the following structure informing about various
160states of the playback operation.
161</para>
162<programlisting>
163struct video_status {
164 int video_blank; /&#x22C6; blank video on freeze? &#x22C6;/
165 video_play_state_t play_state; /&#x22C6; current state of playback &#x22C6;/
166 video_stream_source_t stream_source; /&#x22C6; current source (demux/memory) &#x22C6;/
167 video_format_t video_format; /&#x22C6; current aspect ratio of stream &#x22C6;/
168 video_displayformat_t display_format;/&#x22C6; selected cropping mode &#x22C6;/
169};
170</programlisting>
171<para>If video_blank is set video will be blanked out if the channel is changed or if playback is
172stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is
173currently frozen, stopped, or being played back. The stream_source corresponds to the seleted
174source for the video stream. It can come either from the demultiplexer or from memory.
175The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently
176played video stream. Finally, display_format corresponds to the selected cropping
177mode in case the source video format is not the same as the format of the output
178device.
179</para>
180</section>
181
182<section id="video-still-picture">
183<title>struct video_still_picture</title>
184<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the
185following structure.
186</para>
187<programlisting>
188/&#x22C6; pointer to and size of a single iframe in memory &#x22C6;/
189struct video_still_picture {
190 char &#x22C6;iFrame; /&#x22C6; pointer to a single iframe in memory &#x22C6;/
191 int32_t size;
192};
193</programlisting>
194</section>
195
196<section id="video_caps">
197<title>video capabilities</title>
198<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following
199bits set according to the hardwares capabilities.
200</para>
201<programlisting>
202 /&#x22C6; bit definitions for capabilities: &#x22C6;/
203 /&#x22C6; can the hardware decode MPEG1 and/or MPEG2? &#x22C6;/
204 #define VIDEO_CAP_MPEG1 1
205 #define VIDEO_CAP_MPEG2 2
206 /&#x22C6; can you send a system and/or program stream to video device?
207 (you still have to open the video and the audio device but only
208 send the stream to the video device) &#x22C6;/
209 #define VIDEO_CAP_SYS 4
210 #define VIDEO_CAP_PROG 8
211 /&#x22C6; can the driver also handle SPU, NAVI and CSS encoded data?
212 (CSS API is not present yet) &#x22C6;/
213 #define VIDEO_CAP_SPU 16
214 #define VIDEO_CAP_NAVI 32
215 #define VIDEO_CAP_CSS 64
216</programlisting>
217</section>
218
219<section id="video-system">
220<title>video system</title>
221<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The
222following system types can be set:
223</para>
224<programlisting>
225typedef enum {
226 VIDEO_SYSTEM_PAL,
227 VIDEO_SYSTEM_NTSC,
228 VIDEO_SYSTEM_PALN,
229 VIDEO_SYSTEM_PALNc,
230 VIDEO_SYSTEM_PALM,
231 VIDEO_SYSTEM_NTSC60,
232 VIDEO_SYSTEM_PAL60,
233 VIDEO_SYSTEM_PALM60
234} video_system_t;
235</programlisting>
236</section>
237
238<section id="video-highlight">
239<title>struct video_highlight</title>
240<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The
241call expects the following format for that information:
242</para>
243<programlisting>
244 typedef
245 struct video_highlight {
246 boolean active; /&#x22C6; 1=show highlight, 0=hide highlight &#x22C6;/
247 uint8_t contrast1; /&#x22C6; 7- 4 Pattern pixel contrast &#x22C6;/
248 /&#x22C6; 3- 0 Background pixel contrast &#x22C6;/
249 uint8_t contrast2; /&#x22C6; 7- 4 Emphasis pixel-2 contrast &#x22C6;/
250 /&#x22C6; 3- 0 Emphasis pixel-1 contrast &#x22C6;/
251 uint8_t color1; /&#x22C6; 7- 4 Pattern pixel color &#x22C6;/
252 /&#x22C6; 3- 0 Background pixel color &#x22C6;/
253 uint8_t color2; /&#x22C6; 7- 4 Emphasis pixel-2 color &#x22C6;/
254 /&#x22C6; 3- 0 Emphasis pixel-1 color &#x22C6;/
255 uint32_t ypos; /&#x22C6; 23-22 auto action mode &#x22C6;/
256 /&#x22C6; 21-12 start y &#x22C6;/
257 /&#x22C6; 9- 0 end y &#x22C6;/
258 uint32_t xpos; /&#x22C6; 23-22 button color number &#x22C6;/
259 /&#x22C6; 21-12 start x &#x22C6;/
260 /&#x22C6; 9- 0 end x &#x22C6;/
261 } video_highlight_t;
262</programlisting>
263
264</section>
265<section id="video-spu">
266<title>video SPU</title>
267<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the
268following format:
269</para>
270<programlisting>
271 typedef
272 struct video_spu {
273 boolean active;
274 int stream_id;
275 } video_spu_t;
276</programlisting>
277
278</section>
279<section id="video-spu-palette">
280<title>video SPU palette</title>
281<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE:
282</para>
283<programlisting>
284 typedef
285 struct video_spu_palette{
286 int length;
287 uint8_t &#x22C6;palette;
288 } video_spu_palette_t;
289</programlisting>
290
291</section>
292<section id="video-navi-pack">
293<title>video NAVI pack</title>
294<para>In order to get the navigational data the following structure has to be passed to the ioctl
295VIDEO_GET_NAVI:
296</para>
297<programlisting>
298 typedef
299 struct video_navi_pack{
300 int length; /&#x22C6; 0 ... 1024 &#x22C6;/
301 uint8_t data[1024];
302 } video_navi_pack_t;
303</programlisting>
304</section>
305
306
307<section id="video-attributes-t">
308<title>video attributes</title>
309<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
310</para>
311<programlisting>
312 typedef uint16_t video_attributes_t;
313 /&#x22C6; bits: descr. &#x22C6;/
314 /&#x22C6; 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) &#x22C6;/
315 /&#x22C6; 13-12 TV system (0=525/60, 1=625/50) &#x22C6;/
316 /&#x22C6; 11-10 Aspect ratio (0=4:3, 3=16:9) &#x22C6;/
317 /&#x22C6; 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca &#x22C6;/
318 /&#x22C6; 7 line 21-1 data present in GOP (1=yes, 0=no) &#x22C6;/
319 /&#x22C6; 6 line 21-2 data present in GOP (1=yes, 0=no) &#x22C6;/
320 /&#x22C6; 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 &#x22C6;/
321 /&#x22C6; 2 source letterboxed (1=yes, 0=no) &#x22C6;/
322 /&#x22C6; 0 film/camera mode (0=camera, 1=film (625/50 only)) &#x22C6;/
323</programlisting>
324</section></section>
325
326
327<section id="video_function_calls">
328<title>Video Function Calls</title>
329
330
331<section id="video_fopen">
332<title>open()</title>
333<para>DESCRIPTION
334</para>
335<informaltable><tgroup cols="1"><tbody><row><entry
336 align="char">
337<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0)
338 for subsequent use.</para>
339<para>When an open() call has succeeded, the device will be ready for use.
340 The significance of blocking or non-blocking mode is described in the
341 documentation for functions where there is a difference. It does not affect the
342 semantics of the open() call itself. A device opened in blocking mode can later
343 be put into non-blocking mode (and vice versa) using the F_SETFL command
344 of the fcntl system call. This is a standard system call, documented in the Linux
345 manual page for fcntl. Only one user can open the Video Device in O_RDWR
346 mode. All other attempts to open the device in this mode will fail, and an
347 error-code will be returned. If the Video Device is opened in O_RDONLY
348 mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other
349 call will return an error code.</para>
350</entry>
351 </row></tbody></tgroup></informaltable>
352
353<para>SYNOPSIS
354</para>
355<informaltable><tgroup cols="1"><tbody><row><entry
356 align="char">
357<para>int open(const char &#x22C6;deviceName, int flags);</para>
358</entry>
359 </row></tbody></tgroup></informaltable>
360<para>PARAMETERS
361</para>
362<informaltable><tgroup cols="2"><tbody><row><entry
363 align="char">
364<para>const char
365 *deviceName</para>
366</entry><entry
367 align="char">
368<para>Name of specific video device.</para>
369</entry>
370 </row><row><entry
371 align="char">
372<para>int flags</para>
373</entry><entry
374 align="char">
375<para>A bit-wise OR of the following flags:</para>
376</entry>
377 </row><row><entry
378 align="char">
379</entry><entry
380 align="char">
381<para>O_RDONLY read-only access</para>
382</entry>
383 </row><row><entry
384 align="char">
385</entry><entry
386 align="char">
387<para>O_RDWR read/write access</para>
388</entry>
389 </row><row><entry
390 align="char">
391</entry><entry
392 align="char">
393<para>O_NONBLOCK open in non-blocking mode</para>
394</entry>
395 </row><row><entry
396 align="char">
397</entry><entry
398 align="char">
399<para>(blocking mode is the default)</para>
400</entry>
401 </row></tbody></tgroup></informaltable>
402<para>RETURN VALUE</para>
403<informaltable><tgroup cols="2"><tbody><row><entry
404 align="char">
405<para>ENODEV</para>
406</entry><entry
407 align="char">
408<para>Device driver not loaded/available.</para>
409</entry>
410 </row><row><entry
411 align="char">
412<para>EINTERNAL</para>
413</entry><entry
414 align="char">
415<para>Internal error.</para>
416</entry>
417 </row><row><entry
418 align="char">
419<para>EBUSY</para>
420</entry><entry
421 align="char">
422<para>Device or resource busy.</para>
423</entry>
424 </row><row><entry
425 align="char">
426<para>EINVAL</para>
427</entry><entry
428 align="char">
429<para>Invalid argument.</para>
430</entry>
431 </row></tbody></tgroup></informaltable>
432
433</section>
434<section id="video_fclose">
435<title>close()</title>
436<para>DESCRIPTION
437</para>
438<informaltable><tgroup cols="1"><tbody><row><entry
439 align="char">
440<para>This system call closes a previously opened video device.</para>
441</entry>
442 </row></tbody></tgroup></informaltable>
443<para>SYNOPSIS
444</para>
445<informaltable><tgroup cols="1"><tbody><row><entry
446 align="char">
447<para>int close(int fd);</para>
448</entry>
449 </row></tbody></tgroup></informaltable>
450<para>PARAMETERS
451</para>
452<informaltable><tgroup cols="2"><tbody><row><entry
453 align="char">
454<para>int fd</para>
455</entry><entry
456 align="char">
457<para>File descriptor returned by a previous call to open().</para>
458</entry>
459 </row></tbody></tgroup></informaltable>
460<para>RETURN VALUE</para>
461<informaltable><tgroup cols="2"><tbody><row><entry
462 align="char">
463<para>EBADF</para>
464</entry><entry
465 align="char">
466<para>fd is not a valid open file descriptor.</para>
467</entry>
468 </row></tbody></tgroup></informaltable>
469
470</section>
471<section id="video_fwrite">
472<title>write()</title>
473<para>DESCRIPTION
474</para>
475<informaltable><tgroup cols="1"><tbody><row><entry
476 align="char">
477<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected
478 in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
479 PES format, unless the capability allows other formats. If O_NONBLOCK is
480 not specified the function will block until buffer space is available. The amount
481 of data to be transferred is implied by count.</para>
482</entry>
483 </row></tbody></tgroup></informaltable>
484<para>SYNOPSIS
485</para>
486<informaltable><tgroup cols="1"><tbody><row><entry
487 align="char">
488<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
489</entry>
490 </row></tbody></tgroup></informaltable>
491<para>PARAMETERS
492</para>
493<informaltable><tgroup cols="2"><tbody><row><entry
494 align="char">
495<para>int fd</para>
496</entry><entry
497 align="char">
498<para>File descriptor returned by a previous call to open().</para>
499</entry>
500 </row><row><entry
501 align="char">
502<para>void *buf</para>
503</entry><entry
504 align="char">
505<para>Pointer to the buffer containing the PES data.</para>
506</entry>
507 </row><row><entry
508 align="char">
509<para>size_t count</para>
510</entry><entry
511 align="char">
512<para>Size of buf.</para>
513</entry>
514 </row></tbody></tgroup></informaltable>
515<para>RETURN VALUE</para>
516<informaltable><tgroup cols="2"><tbody><row><entry
517 align="char">
518<para>EPERM</para>
519</entry><entry
520 align="char">
521<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
522</entry>
523 </row><row><entry
524 align="char">
525<para>ENOMEM</para>
526</entry><entry
527 align="char">
528<para>Attempted to write more data than the internal buffer can
529 hold.</para>
530</entry>
531 </row><row><entry
532 align="char">
533<para>EBADF</para>
534</entry><entry
535 align="char">
536<para>fd is not a valid open file descriptor.</para>
537</entry>
538 </row></tbody></tgroup></informaltable>
539
540</section><section id="VIDEO_STOP"
541role="subsection"><title>VIDEO_STOP</title>
542<para>DESCRIPTION
543</para>
544<informaltable><tgroup cols="1"><tbody><row><entry
545 align="char">
546<para>This ioctl call asks the Video Device to stop playing the current stream.
547 Depending on the input parameter, the screen can be blanked out or displaying
548 the last decoded frame.</para>
549</entry>
550 </row></tbody></tgroup></informaltable>
551<para>SYNOPSIS
552</para>
553<informaltable><tgroup cols="1"><tbody><row><entry
554 align="char">
555<para>int ioctl(fd, int request = VIDEO_STOP, boolean
556 mode);</para>
557</entry>
558 </row></tbody></tgroup></informaltable>
559<para>PARAMETERS
560</para>
561<informaltable><tgroup cols="2"><tbody><row><entry
562 align="char">
563<para>int fd</para>
564</entry><entry
565 align="char">
566<para>File descriptor returned by a previous call to open().</para>
567</entry>
568 </row><row><entry
569 align="char">
570<para>int request</para>
571</entry><entry
572 align="char">
573<para>Equals VIDEO_STOP for this command.</para>
574</entry>
575 </row><row><entry
576 align="char">
577<para>Boolean mode</para>
578</entry><entry
579 align="char">
580<para>Indicates how the screen shall be handled.</para>
581</entry>
582 </row><row><entry
583 align="char">
584</entry><entry
585 align="char">
586<para>TRUE: Blank screen when stop.</para>
587</entry>
588 </row><row><entry
589 align="char">
590</entry><entry
591 align="char">
592<para>FALSE: Show last decoded frame.</para>
593</entry>
594 </row></tbody></tgroup></informaltable>
595&return-value-dvb;
596
597</section><section id="VIDEO_PLAY"
598role="subsection"><title>VIDEO_PLAY</title>
599<para>DESCRIPTION
600</para>
601<informaltable><tgroup cols="1"><tbody><row><entry
602 align="char">
603<para>This ioctl call asks the Video Device to start playing a video stream from the
604 selected source.</para>
605</entry>
606 </row></tbody></tgroup></informaltable>
607<para>SYNOPSIS
608</para>
609<informaltable><tgroup cols="1"><tbody><row><entry
610 align="char">
611<para>int ioctl(fd, int request = VIDEO_PLAY);</para>
612</entry>
613 </row></tbody></tgroup></informaltable>
614<para>PARAMETERS
615</para>
616<informaltable><tgroup cols="2"><tbody><row><entry
617 align="char">
618<para>int fd</para>
619</entry><entry
620 align="char">
621<para>File descriptor returned by a previous call to open().</para>
622</entry>
623 </row><row><entry
624 align="char">
625<para>int request</para>
626</entry><entry
627 align="char">
628<para>Equals VIDEO_PLAY for this command.</para>
629</entry>
630 </row></tbody></tgroup></informaltable>
631&return-value-dvb;
632
633</section><section id="VIDEO_FREEZE"
634role="subsection"><title>VIDEO_FREEZE</title>
635<para>DESCRIPTION
636</para>
637<informaltable><tgroup cols="1"><tbody><row><entry
638 align="char">
639<para>This ioctl call suspends the live video stream being played. Decoding
640 and playing are frozen. It is then possible to restart the decoding
641 and playing process of the video stream using the VIDEO_CONTINUE
642 command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call
643 VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more
644 data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para>
645</entry>
646 </row></tbody></tgroup></informaltable>
647<para>SYNOPSIS
648</para>
649<informaltable><tgroup cols="1"><tbody><row><entry
650 align="char">
651<para>int ioctl(fd, int request = VIDEO_FREEZE);</para>
652</entry>
653 </row></tbody></tgroup></informaltable>
654<para>PARAMETERS
655</para>
656<informaltable><tgroup cols="2"><tbody><row><entry
657 align="char">
658<para>int fd</para>
659</entry><entry
660 align="char">
661<para>File descriptor returned by a previous call to open().</para>
662</entry>
663 </row><row><entry
664 align="char">
665<para>int request</para>
666</entry><entry
667 align="char">
668<para>Equals VIDEO_FREEZE for this command.</para>
669</entry>
670 </row></tbody></tgroup></informaltable>
671&return-value-dvb;
672
673</section><section id="VIDEO_CONTINUE"
674role="subsection"><title>VIDEO_CONTINUE</title>
675<para>DESCRIPTION
676</para>
677<informaltable><tgroup cols="1"><tbody><row><entry
678 align="char">
679<para>This ioctl call restarts decoding and playing processes of the video stream
680 which was played before a call to VIDEO_FREEZE was made.</para>
681</entry>
682 </row></tbody></tgroup></informaltable>
683<para>SYNOPSIS
684</para>
685<informaltable><tgroup cols="1"><tbody><row><entry
686 align="char">
687<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para>
688</entry>
689 </row></tbody></tgroup></informaltable>
690<para>PARAMETERS
691</para>
692<informaltable><tgroup cols="2"><tbody><row><entry
693 align="char">
694<para>int fd</para>
695</entry><entry
696 align="char">
697<para>File descriptor returned by a previous call to open().</para>
698</entry>
699 </row><row><entry
700 align="char">
701<para>int request</para>
702</entry><entry
703 align="char">
704<para>Equals VIDEO_CONTINUE for this command.</para>
705</entry>
706 </row></tbody></tgroup></informaltable>
707&return-value-dvb;
708
709</section><section id="VIDEO_SELECT_SOURCE"
710role="subsection"><title>VIDEO_SELECT_SOURCE</title>
711<para>DESCRIPTION
712</para>
713<informaltable><tgroup cols="1"><tbody><row><entry
714 align="char">
715<para>This ioctl call informs the video device which source shall be used for the input
716 data. The possible sources are demux or memory. If memory is selected, the
717 data is fed to the video device through the write command.</para>
718</entry>
719 </row></tbody></tgroup></informaltable>
720<para>SYNOPSIS
721</para>
722<informaltable><tgroup cols="1"><tbody><row><entry
723 align="char">
724<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
725 video_stream_source_t source);</para>
726</entry>
727 </row></tbody></tgroup></informaltable>
728<para>PARAMETERS
729</para>
730<informaltable><tgroup cols="2"><tbody><row><entry
731 align="char">
732<para>int fd</para>
733</entry><entry
734 align="char">
735<para>File descriptor returned by a previous call to open().</para>
736</entry>
737 </row><row><entry
738 align="char">
739<para>int request</para>
740</entry><entry
741 align="char">
742<para>Equals VIDEO_SELECT_SOURCE for this command.</para>
743</entry>
744 </row><row><entry
745 align="char">
746<para>video_stream_source_t
747 source</para>
748</entry><entry
749 align="char">
750<para>Indicates which source shall be used for the Video stream.</para>
751</entry>
752 </row></tbody></tgroup></informaltable>
753&return-value-dvb;
754
755</section><section id="VIDEO_SET_BLANK"
756role="subsection"><title>VIDEO_SET_BLANK</title>
757<para>DESCRIPTION
758</para>
759<informaltable><tgroup cols="1"><tbody><row><entry
760 align="char">
761<para>This ioctl call asks the Video Device to blank out the picture.</para>
762</entry>
763 </row></tbody></tgroup></informaltable>
764<para>SYNOPSIS
765</para>
766<informaltable><tgroup cols="1"><tbody><row><entry
767 align="char">
768<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean
769 mode);</para>
770</entry>
771 </row></tbody></tgroup></informaltable>
772<para>PARAMETERS
773</para>
774<informaltable><tgroup cols="2"><tbody><row><entry
775 align="char">
776<para>int fd</para>
777</entry><entry
778 align="char">
779<para>File descriptor returned by a previous call to open().</para>
780</entry>
781 </row><row><entry
782 align="char">
783<para>int request</para>
784</entry><entry
785 align="char">
786<para>Equals VIDEO_SET_BLANK for this command.</para>
787</entry>
788 </row><row><entry
789 align="char">
790<para>boolean mode</para>
791</entry><entry
792 align="char">
793<para>TRUE: Blank screen when stop.</para>
794</entry>
795 </row><row><entry
796 align="char">
797</entry><entry
798 align="char">
799<para>FALSE: Show last decoded frame.</para>
800</entry>
801 </row></tbody></tgroup></informaltable>
802&return-value-dvb;
803
804</section><section id="VIDEO_GET_STATUS"
805role="subsection"><title>VIDEO_GET_STATUS</title>
806<para>DESCRIPTION
807</para>
808<informaltable><tgroup cols="1"><tbody><row><entry
809 align="char">
810<para>This ioctl call asks the Video Device to return the current status of the device.</para>
811</entry>
812 </row></tbody></tgroup></informaltable>
813<para>SYNOPSIS
814</para>
815<informaltable><tgroup cols="1"><tbody><row><entry
816 align="char">
817<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct
818 video_status &#x22C6;status);</para>
819</entry>
820 </row></tbody></tgroup></informaltable>
821<para>PARAMETERS
822</para>
823<informaltable><tgroup cols="2"><tbody><row><entry
824 align="char">
825<para>int fd</para>
826</entry><entry
827 align="char">
828<para>File descriptor returned by a previous call to open().</para>
829</entry>
830 </row><row><entry
831 align="char">
832<para>int request</para>
833</entry><entry
834 align="char">
835<para>Equals VIDEO_GET_STATUS for this command.</para>
836</entry>
837 </row><row><entry
838 align="char">
839<para>struct video_status
840 *status</para>
841</entry><entry
842 align="char">
843<para>Returns the current status of the Video Device.</para>
844</entry>
845 </row></tbody></tgroup></informaltable>
846&return-value-dvb;
847
848</section><section id="VIDEO_GET_EVENT"
849role="subsection"><title>VIDEO_GET_EVENT</title>
850<para>DESCRIPTION
851</para>
852<informaltable><tgroup cols="1"><tbody><row><entry
853 align="char">
854<para>This ioctl call returns an event of type video_event if available. If an event is
855 not available, the behavior depends on whether the device is in blocking or
856 non-blocking mode. In the latter case, the call fails immediately with errno
857 set to EWOULDBLOCK. In the former case, the call blocks until an event
858 becomes available. The standard Linux poll() and/or select() system calls can
859 be used with the device file descriptor to watch for new events. For select(),
860 the file descriptor should be included in the exceptfds argument, and for
861 poll(), POLLPRI should be specified as the wake-up condition. Read-only
862 permissions are sufficient for this ioctl call.</para>
863</entry>
864 </row></tbody></tgroup></informaltable>
865<para>SYNOPSIS
866</para>
867<informaltable><tgroup cols="1"><tbody><row><entry
868 align="char">
869<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct
870 video_event &#x22C6;ev);</para>
871</entry>
872 </row></tbody></tgroup></informaltable>
873<para>PARAMETERS
874</para>
875<informaltable><tgroup cols="2"><tbody><row><entry
876 align="char">
877<para>int fd</para>
878</entry><entry
879 align="char">
880<para>File descriptor returned by a previous call to open().</para>
881</entry>
882 </row><row><entry
883 align="char">
884<para>int request</para>
885</entry><entry
886 align="char">
887<para>Equals VIDEO_GET_EVENT for this command.</para>
888</entry>
889 </row><row><entry
890 align="char">
891<para>struct video_event
892 *ev</para>
893</entry><entry
894 align="char">
895<para>Points to the location where the event, if any, is to be
896 stored.</para>
897</entry>
898 </row></tbody></tgroup></informaltable>
899&return-value-dvb;
900<informaltable><tgroup cols="2"><tbody><row><entry
901 align="char">
902<para>EWOULDBLOCK</para>
903</entry><entry
904 align="char">
905<para>There is no event pending, and the device is in
906 non-blocking mode.</para>
907</entry>
908 </row><row><entry
909 align="char">
910<para>EOVERFLOW</para>
911</entry><entry
912 align="char">
913<para>Overflow in event queue - one or more events were lost.</para>
914</entry>
915 </row></tbody></tgroup></informaltable>
916
917</section><section id="VIDEO_SET_DISPLAY_FORMAT"
918role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title>
919<para>DESCRIPTION
920</para>
921<informaltable><tgroup cols="1"><tbody><row><entry
922 align="char">
923<para>This ioctl call asks the Video Device to select the video format to be applied
924 by the MPEG chip on the video.</para>
925</entry>
926 </row></tbody></tgroup></informaltable>
927<para>SYNOPSIS
928</para>
929<informaltable><tgroup cols="1"><tbody><row><entry
930 align="char">
931<para> int ioctl(fd, int request =
932 VIDEO_SET_DISPLAY_FORMAT, video_display_format_t
933 format);</para>
934</entry>
935 </row></tbody></tgroup></informaltable>
936<para>PARAMETERS
937</para>
938<informaltable><tgroup cols="2"><tbody><row><entry
939 align="char">
940<para>int fd</para>
941</entry><entry
942 align="char">
943<para>File descriptor returned by a previous call to open().</para>
944</entry>
945 </row><row><entry
946 align="char">
947<para>int request</para>
948</entry><entry
949 align="char">
950<para>Equals VIDEO_SET_DISPLAY_FORMAT for this
951 command.</para>
952</entry>
953 </row><row><entry
954 align="char">
955<para>video_display_format_t
956 format</para>
957</entry><entry
958 align="char">
959<para>Selects the video format to be used.</para>
960</entry>
961 </row></tbody></tgroup></informaltable>
962&return-value-dvb;
963
964</section><section id="VIDEO_STILLPICTURE"
965role="subsection"><title>VIDEO_STILLPICTURE</title>
966<para>DESCRIPTION
967</para>
968<informaltable><tgroup cols="1"><tbody><row><entry
969 align="char">
970<para>This ioctl call asks the Video Device to display a still picture (I-frame). The
971 input data shall contain an I-frame. If the pointer is NULL, then the current
972 displayed still picture is blanked.</para>
973</entry>
974 </row></tbody></tgroup></informaltable>
975<para>SYNOPSIS
976</para>
977<informaltable><tgroup cols="1"><tbody><row><entry
978 align="char">
979<para>int ioctl(fd, int request = VIDEO_STILLPICTURE,
980 struct video_still_picture &#x22C6;sp);</para>
981</entry>
982 </row></tbody></tgroup></informaltable>
983<para>PARAMETERS
984</para>
985<informaltable><tgroup cols="2"><tbody><row><entry
986 align="char">
987<para>int fd</para>
988</entry><entry
989 align="char">
990<para>File descriptor returned by a previous call to open().</para>
991</entry>
992 </row><row><entry
993 align="char">
994<para>int request</para>
995</entry><entry
996 align="char">
997<para>Equals VIDEO_STILLPICTURE for this command.</para>
998</entry>
999 </row><row><entry
1000 align="char">
1001<para>struct
1002 video_still_picture
1003 *sp</para>
1004</entry><entry
1005 align="char">
1006<para>Pointer to a location where an I-frame and size is stored.</para>
1007</entry>
1008 </row></tbody></tgroup></informaltable>
1009&return-value-dvb;
1010
1011</section><section id="VIDEO_FAST_FORWARD"
1012role="subsection"><title>VIDEO_FAST_FORWARD</title>
1013<para>DESCRIPTION
1014</para>
1015<informaltable><tgroup cols="1"><tbody><row><entry
1016 align="char">
1017<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames.
1018 This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1019</entry>
1020 </row></tbody></tgroup></informaltable>
1021<para>SYNOPSIS
1022</para>
1023<informaltable><tgroup cols="1"><tbody><row><entry
1024 align="char">
1025<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int
1026 nFrames);</para>
1027</entry>
1028 </row></tbody></tgroup></informaltable>
1029<para>PARAMETERS
1030</para>
1031<informaltable><tgroup cols="2"><tbody><row><entry
1032 align="char">
1033<para>int fd</para>
1034</entry><entry
1035 align="char">
1036<para>File descriptor returned by a previous call to open().</para>
1037</entry>
1038 </row><row><entry
1039 align="char">
1040<para>int request</para>
1041</entry><entry
1042 align="char">
1043<para>Equals VIDEO_FAST_FORWARD for this command.</para>
1044</entry>
1045 </row><row><entry
1046 align="char">
1047<para>int nFrames</para>
1048</entry><entry
1049 align="char">
1050<para>The number of frames to skip.</para>
1051</entry>
1052 </row></tbody></tgroup></informaltable>
1053&return-value-dvb;
1054<informaltable><tgroup cols="2"><tbody><row><entry
1055 align="char">
1056<para>EPERM</para>
1057</entry><entry
1058 align="char">
1059<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1060</entry>
1061 </row></tbody></tgroup></informaltable>
1062
1063</section><section id="VIDEO_SLOWMOTION"
1064role="subsection"><title>VIDEO_SLOWMOTION</title>
1065<para>DESCRIPTION
1066</para>
1067<informaltable><tgroup cols="1"><tbody><row><entry
1068 align="char">
1069<para>This ioctl call asks the video device to repeat decoding frames N number of
1070 times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1071</entry>
1072 </row></tbody></tgroup></informaltable>
1073<para>SYNOPSIS
1074</para>
1075<informaltable><tgroup cols="1"><tbody><row><entry
1076 align="char">
1077<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int
1078 nFrames);</para>
1079</entry>
1080 </row></tbody></tgroup></informaltable>
1081<para>PARAMETERS
1082</para>
1083<informaltable><tgroup cols="2"><tbody><row><entry
1084 align="char">
1085<para>int fd</para>
1086</entry><entry
1087 align="char">
1088<para>File descriptor returned by a previous call to open().</para>
1089</entry>
1090 </row><row><entry
1091 align="char">
1092<para>int request</para>
1093</entry><entry
1094 align="char">
1095<para>Equals VIDEO_SLOWMOTION for this command.</para>
1096</entry>
1097 </row><row><entry
1098 align="char">
1099<para>int nFrames</para>
1100</entry><entry
1101 align="char">
1102<para>The number of times to repeat each frame.</para>
1103</entry>
1104 </row></tbody></tgroup></informaltable>
1105&return-value-dvb;
1106<informaltable><tgroup cols="2"><tbody><row><entry
1107 align="char">
1108<para>EPERM</para>
1109</entry><entry
1110 align="char">
1111<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1112</entry>
1113 </row></tbody></tgroup></informaltable>
1114
1115</section><section id="VIDEO_GET_CAPABILITIES"
1116role="subsection"><title>VIDEO_GET_CAPABILITIES</title>
1117<para>DESCRIPTION
1118</para>
1119<informaltable><tgroup cols="1"><tbody><row><entry
1120 align="char">
1121<para>This ioctl call asks the video device about its decoding capabilities. On success
1122 it returns and integer which has bits set according to the defines in section ??.</para>
1123</entry>
1124 </row></tbody></tgroup></informaltable>
1125<para>SYNOPSIS
1126</para>
1127<informaltable><tgroup cols="1"><tbody><row><entry
1128 align="char">
1129<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES,
1130 unsigned int &#x22C6;cap);</para>
1131</entry>
1132 </row></tbody></tgroup></informaltable>
1133<para>PARAMETERS
1134</para>
1135<informaltable><tgroup cols="2"><tbody><row><entry
1136 align="char">
1137<para>int fd</para>
1138</entry><entry
1139 align="char">
1140<para>File descriptor returned by a previous call to open().</para>
1141</entry>
1142 </row><row><entry
1143 align="char">
1144<para>int request</para>
1145</entry><entry
1146 align="char">
1147<para>Equals VIDEO_GET_CAPABILITIES for this
1148 command.</para>
1149</entry>
1150 </row><row><entry
1151 align="char">
1152<para>unsigned int *cap</para>
1153</entry><entry
1154 align="char">
1155<para>Pointer to a location where to store the capability
1156 information.</para>
1157</entry>
1158 </row></tbody></tgroup></informaltable>
1159&return-value-dvb;
1160
1161</section><section id="VIDEO_SET_ID"
1162role="subsection"><title>VIDEO_SET_ID</title>
1163<para>DESCRIPTION
1164</para>
1165<informaltable><tgroup cols="1"><tbody><row><entry
1166 align="char">
1167<para>This ioctl selects which sub-stream is to be decoded if a program or system
1168 stream is sent to the video device.</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 ioctl(int fd, int request = VIDEO_SET_ID, int
1176 id);</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>int fd</para>
1184</entry><entry
1185 align="char">
1186<para>File descriptor returned by a previous call to open().</para>
1187</entry>
1188 </row><row><entry
1189 align="char">
1190<para>int request</para>
1191</entry><entry
1192 align="char">
1193<para>Equals VIDEO_SET_ID for this command.</para>
1194</entry>
1195 </row><row><entry
1196 align="char">
1197<para>int id</para>
1198</entry><entry
1199 align="char">
1200<para>video sub-stream id</para>
1201</entry>
1202 </row></tbody></tgroup></informaltable>
1203&return-value-dvb;
1204<informaltable><tgroup cols="2"><tbody><row><entry
1205 align="char">
1206<para>EINVAL</para>
1207</entry><entry
1208 align="char">
1209<para>Invalid sub-stream id.</para>
1210</entry>
1211 </row></tbody></tgroup></informaltable>
1212
1213</section><section id="VIDEO_CLEAR_BUFFER"
1214role="subsection"><title>VIDEO_CLEAR_BUFFER</title>
1215<para>DESCRIPTION
1216</para>
1217<informaltable><tgroup cols="1"><tbody><row><entry
1218 align="char">
1219<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para>
1220</entry>
1221 </row></tbody></tgroup></informaltable>
1222<para>SYNOPSIS
1223</para>
1224<informaltable><tgroup cols="1"><tbody><row><entry
1225 align="char">
1226<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para>
1227</entry>
1228 </row></tbody></tgroup></informaltable>
1229<para>PARAMETERS
1230</para>
1231<informaltable><tgroup cols="2"><tbody><row><entry
1232 align="char">
1233<para>int fd</para>
1234</entry><entry
1235 align="char">
1236<para>File descriptor returned by a previous call to open().</para>
1237</entry>
1238 </row><row><entry
1239 align="char">
1240<para>int request</para>
1241</entry><entry
1242 align="char">
1243<para>Equals VIDEO_CLEAR_BUFFER for this command.</para>
1244</entry>
1245 </row></tbody></tgroup></informaltable>
1246&return-value-dvb;
1247
1248</section><section id="VIDEO_SET_STREAMTYPE"
1249role="subsection"><title>VIDEO_SET_STREAMTYPE</title>
1250<para>DESCRIPTION
1251</para>
1252<informaltable><tgroup cols="1"><tbody><row><entry
1253 align="char">
1254<para>This ioctl tells the driver which kind of stream to expect being written to it. If
1255 this call is not used the default of video PES is used. Some drivers might not
1256 support this call and always expect PES.</para>
1257</entry>
1258 </row></tbody></tgroup></informaltable>
1259<para>SYNOPSIS
1260</para>
1261<informaltable><tgroup cols="1"><tbody><row><entry
1262 align="char">
1263<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE,
1264 int type);</para>
1265</entry>
1266 </row></tbody></tgroup></informaltable>
1267<para>PARAMETERS
1268</para>
1269<informaltable><tgroup cols="2"><tbody><row><entry
1270 align="char">
1271<para>int fd</para>
1272</entry><entry
1273 align="char">
1274<para>File descriptor returned by a previous call to open().</para>
1275</entry>
1276 </row><row><entry
1277 align="char">
1278<para>int request</para>
1279</entry><entry
1280 align="char">
1281<para>Equals VIDEO_SET_STREAMTYPE for this command.</para>
1282</entry>
1283 </row><row><entry
1284 align="char">
1285<para>int type</para>
1286</entry><entry
1287 align="char">
1288<para>stream type</para>
1289</entry>
1290 </row></tbody></tgroup></informaltable>
1291&return-value-dvb;
1292
1293</section><section id="VIDEO_SET_FORMAT"
1294role="subsection"><title>VIDEO_SET_FORMAT</title>
1295<para>DESCRIPTION
1296</para>
1297<informaltable><tgroup cols="1"><tbody><row><entry
1298 align="char">
1299<para>This ioctl sets the screen format (aspect ratio) of the connected output device
1300 (TV) so that the output of the decoder can be adjusted accordingly.</para>
1301</entry>
1302 </row></tbody></tgroup></informaltable>
1303<para>SYNOPSIS
1304</para>
1305<informaltable><tgroup cols="1"><tbody><row><entry
1306 align="char">
1307<para> int ioctl(fd, int request = VIDEO_SET_FORMAT,
1308 video_format_t format);</para>
1309</entry>
1310 </row></tbody></tgroup></informaltable>
1311<para>PARAMETERS
1312</para>
1313<informaltable><tgroup cols="2"><tbody><row><entry
1314 align="char">
1315<para>int fd</para>
1316</entry><entry
1317 align="char">
1318<para>File descriptor returned by a previous call to open().</para>
1319</entry>
1320 </row><row><entry
1321 align="char">
1322<para>int request</para>
1323</entry><entry
1324 align="char">
1325<para>Equals VIDEO_SET_FORMAT for this command.</para>
1326</entry>
1327 </row><row><entry
1328 align="char">
1329<para>video_format_t
1330 format</para>
1331</entry><entry
1332 align="char">
1333<para>video format of TV as defined in section ??.</para>
1334</entry>
1335 </row></tbody></tgroup></informaltable>
1336&return-value-dvb;
1337<informaltable><tgroup cols="2"><tbody><row><entry
1338 align="char">
1339<para>EINVAL</para>
1340</entry><entry
1341 align="char">
1342<para>format is not a valid video format.</para>
1343</entry>
1344 </row></tbody></tgroup></informaltable>
1345
1346</section><section id="VIDEO_SET_SYSTEM"
1347role="subsection"><title>VIDEO_SET_SYSTEM</title>
1348<para>DESCRIPTION
1349</para>
1350<informaltable><tgroup cols="1"><tbody><row><entry
1351 align="char">
1352<para>This ioctl sets the television output format. The format (see section ??) may
1353 vary from the color format of the displayed MPEG stream. If the hardware is
1354 not able to display the requested format the call will return an error.</para>
1355</entry>
1356 </row></tbody></tgroup></informaltable>
1357<para>SYNOPSIS
1358</para>
1359<informaltable><tgroup cols="1"><tbody><row><entry
1360 align="char">
1361<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM ,
1362 video_system_t system);</para>
1363</entry>
1364 </row></tbody></tgroup></informaltable>
1365<para>PARAMETERS
1366</para>
1367<informaltable><tgroup cols="2"><tbody><row><entry
1368 align="char">
1369<para>int fd</para>
1370</entry><entry
1371 align="char">
1372<para>File descriptor returned by a previous call to open().</para>
1373</entry>
1374 </row><row><entry
1375 align="char">
1376<para>int request</para>
1377</entry><entry
1378 align="char">
1379<para>Equals VIDEO_SET_FORMAT for this command.</para>
1380</entry>
1381 </row><row><entry
1382 align="char">
1383<para>video_system_t
1384 system</para>
1385</entry><entry
1386 align="char">
1387<para>video system of TV output.</para>
1388</entry>
1389 </row></tbody></tgroup></informaltable>
1390&return-value-dvb;
1391<informaltable><tgroup cols="2"><tbody><row><entry
1392 align="char">
1393<para>EINVAL</para>
1394</entry><entry
1395 align="char">
1396<para>system is not a valid or supported video system.</para>
1397</entry>
1398 </row></tbody></tgroup></informaltable>
1399
1400</section><section id="VIDEO_SET_HIGHLIGHT"
1401role="subsection"><title>VIDEO_SET_HIGHLIGHT</title>
1402<para>DESCRIPTION
1403</para>
1404<informaltable><tgroup cols="1"><tbody><row><entry
1405 align="char">
1406<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para>
1407</entry>
1408 </row></tbody></tgroup></informaltable>
1409<para>SYNOPSIS
1410</para>
1411<informaltable><tgroup cols="1"><tbody><row><entry
1412 align="char">
1413<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT
1414 ,video_highlight_t &#x22C6;vhilite)</para>
1415</entry>
1416 </row></tbody></tgroup></informaltable>
1417<para>PARAMETERS
1418</para>
1419<informaltable><tgroup cols="2"><tbody><row><entry
1420 align="char">
1421<para>int fd</para>
1422</entry><entry
1423 align="char">
1424<para>File descriptor returned by a previous call to open().</para>
1425</entry>
1426 </row><row><entry
1427 align="char">
1428<para>int request</para>
1429</entry><entry
1430 align="char">
1431<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para>
1432</entry>
1433 </row><row><entry
1434 align="char">
1435<para>video_highlight_t
1436 *vhilite</para>
1437</entry><entry
1438 align="char">
1439<para>SPU Highlight information according to section ??.</para>
1440</entry>
1441 </row></tbody></tgroup></informaltable>
1442&return-value-dvb;
1443
1444</section><section id="VIDEO_SET_SPU"
1445role="subsection"><title>VIDEO_SET_SPU</title>
1446<para>DESCRIPTION
1447</para>
1448<informaltable><tgroup cols="1"><tbody><row><entry
1449 align="char">
1450<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can
1451 only be used, if the driver is able to handle a DVD stream.</para>
1452</entry>
1453 </row></tbody></tgroup></informaltable>
1454<para>SYNOPSIS
1455</para>
1456<informaltable><tgroup cols="1"><tbody><row><entry
1457 align="char">
1458<para> int ioctl(fd, int request = VIDEO_SET_SPU ,
1459 video_spu_t &#x22C6;spu)</para>
1460</entry>
1461 </row></tbody></tgroup></informaltable>
1462<para>PARAMETERS
1463</para>
1464<informaltable><tgroup cols="2"><tbody><row><entry
1465 align="char">
1466<para>int fd</para>
1467</entry><entry
1468 align="char">
1469<para>File descriptor returned by a previous call to open().</para>
1470</entry>
1471 </row><row><entry
1472 align="char">
1473<para>int request</para>
1474</entry><entry
1475 align="char">
1476<para>Equals VIDEO_SET_SPU for this command.</para>
1477</entry>
1478 </row><row><entry
1479 align="char">
1480<para>video_spu_t *spu</para>
1481</entry><entry
1482 align="char">
1483<para>SPU decoding (de)activation and subid setting according
1484 to section ??.</para>
1485</entry>
1486 </row></tbody></tgroup></informaltable>
1487&return-value-dvb;
1488<informaltable><tgroup cols="2"><tbody><row><entry
1489 align="char">
1490<para>EINVAL</para>
1491</entry><entry
1492 align="char">
1493<para>input is not a valid spu setting or driver cannot handle
1494 SPU.</para>
1495</entry>
1496 </row></tbody></tgroup></informaltable>
1497
1498</section><section id="VIDEO_SET_SPU_PALETTE"
1499role="subsection"><title>VIDEO_SET_SPU_PALETTE</title>
1500<para>DESCRIPTION
1501</para>
1502<informaltable><tgroup cols="1"><tbody><row><entry
1503 align="char">
1504<para>This ioctl sets the SPU color palette.</para>
1505</entry>
1506 </row></tbody></tgroup></informaltable>
1507<para>SYNOPSIS
1508</para>
1509<informaltable><tgroup cols="1"><tbody><row><entry
1510 align="char">
1511<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
1512 ,video_spu_palette_t &#x22C6;palette )</para>
1513</entry>
1514 </row></tbody></tgroup></informaltable>
1515<para>PARAMETERS
1516</para>
1517<informaltable><tgroup cols="2"><tbody><row><entry
1518 align="char">
1519<para>int fd</para>
1520</entry><entry
1521 align="char">
1522<para>File descriptor returned by a previous call to open().</para>
1523</entry>
1524 </row><row><entry
1525 align="char">
1526<para>int request</para>
1527</entry><entry
1528 align="char">
1529<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para>
1530</entry>
1531 </row><row><entry
1532 align="char">
1533<para>video_spu_palette_t
1534 *palette</para>
1535</entry><entry
1536 align="char">
1537<para>SPU palette according to section ??.</para>
1538</entry>
1539 </row></tbody></tgroup></informaltable>
1540&return-value-dvb;
1541<informaltable><tgroup cols="2"><tbody><row><entry
1542 align="char">
1543<para>EINVAL</para>
1544</entry><entry
1545 align="char">
1546<para>input is not a valid palette or driver doesn&#8217;t handle SPU.</para>
1547</entry>
1548 </row></tbody></tgroup></informaltable>
1549
1550</section><section id="VIDEO_GET_NAVI"
1551role="subsection"><title>VIDEO_GET_NAVI</title>
1552<para>DESCRIPTION
1553</para>
1554<informaltable><tgroup cols="1"><tbody><row><entry
1555 align="char">
1556<para>This ioctl returns navigational information from the DVD stream. This is
1557 especially needed if an encoded stream has to be decoded by the hardware.</para>
1558</entry>
1559 </row></tbody></tgroup></informaltable>
1560<para>SYNOPSIS
1561</para>
1562<informaltable><tgroup cols="1"><tbody><row><entry
1563 align="char">
1564<para> int ioctl(fd, int request = VIDEO_GET_NAVI ,
1565 video_navi_pack_t &#x22C6;navipack)</para>
1566</entry>
1567 </row></tbody></tgroup></informaltable>
1568<para>PARAMETERS
1569</para>
1570<informaltable><tgroup cols="2"><tbody><row><entry
1571 align="char">
1572<para>int fd</para>
1573</entry><entry
1574 align="char">
1575<para>File descriptor returned by a previous call to open().</para>
1576</entry>
1577 </row><row><entry
1578 align="char">
1579<para>int request</para>
1580</entry><entry
1581 align="char">
1582<para>Equals VIDEO_GET_NAVI for this command.</para>
1583</entry>
1584 </row><row><entry
1585 align="char">
1586<para>video_navi_pack_t
1587 *navipack</para>
1588</entry><entry
1589 align="char">
1590<para>PCI or DSI pack (private stream 2) according to section
1591 ??.</para>
1592</entry>
1593 </row></tbody></tgroup></informaltable>
1594&return-value-dvb;
1595<informaltable><tgroup cols="2"><tbody><row><entry
1596 align="char">
1597<para>EFAULT</para>
1598</entry><entry
1599 align="char">
1600<para>driver is not able to return navigational information</para>
1601</entry>
1602 </row></tbody></tgroup></informaltable>
1603
1604</section><section id="VIDEO_SET_ATTRIBUTES"
1605role="subsection"><title>VIDEO_SET_ATTRIBUTES</title>
1606<para>DESCRIPTION
1607</para>
1608<informaltable><tgroup cols="1"><tbody><row><entry
1609 align="char">
1610<para>This ioctl is intended for DVD playback and allows you to set certain
1611 information about the stream. Some hardware may not need this information,
1612 but the call also tells the hardware to prepare for DVD playback.</para>
1613</entry>
1614 </row></tbody></tgroup></informaltable>
1615<para>SYNOPSIS
1616</para>
1617<informaltable><tgroup cols="1"><tbody><row><entry
1618 align="char">
1619<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE
1620 ,video_attributes_t vattr)</para>
1621</entry>
1622 </row></tbody></tgroup></informaltable>
1623<para>PARAMETERS
1624</para>
1625<informaltable><tgroup cols="2"><tbody><row><entry
1626 align="char">
1627<para>int fd</para>
1628</entry><entry
1629 align="char">
1630<para>File descriptor returned by a previous call to open().</para>
1631</entry>
1632 </row><row><entry
1633 align="char">
1634<para>int request</para>
1635</entry><entry
1636 align="char">
1637<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para>
1638</entry>
1639 </row><row><entry
1640 align="char">
1641<para>video_attributes_t
1642 vattr</para>
1643</entry><entry
1644 align="char">
1645<para>video attributes according to section ??.</para>
1646</entry>
1647 </row></tbody></tgroup></informaltable>
1648&return-value-dvb;
1649<informaltable><tgroup cols="2"><tbody><row><entry
1650 align="char">
1651<para>EINVAL</para>
1652</entry><entry
1653 align="char">
1654<para>input is not a valid attribute setting.</para>
1655</entry>
1656 </row></tbody></tgroup></informaltable>
1657 </section></section>
generated by cgit v1.2.2 (git 2.25.0) at 2025-01-21 11:24:08 -0500