projects / deliverable / linux.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
[media] DocBook: Add documentation about the demux API
[deliverable/linux.git] / Documentation / DocBook / media / dvb / kdapi.xml
CommitLineData
8e080c2e
MCC		 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
ec8f3386
MCC		 4DVB device driver writers. The header file for this API is named <constant>demux.h</constant> and located in
5<constant>">drivers/media/dvb-core</constant>.
8e080c2e
MCC		 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
8e080c2e
MCC		 14</section>
15<section id="ts_filter_types">
16<title>TS filter types</title>
17 <programlisting>
18 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
19 /&#x22C6; TS packet reception &#x22C6;/
20 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
21
22 /&#x22C6; TS filter type for set_type() &#x22C6;/
23
24 #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
25 #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
26 payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
27 #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
28</programlisting>
29
30</section>
31<section id="dmx_ts_pes_t">
32<title>dmx_ts_pes_t</title>
33<para>The structure
34</para>
35<programlisting>
36 typedef enum
37 {
38 DMX_TS_PES_AUDIO, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
39 DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
40 DMX_TS_PES_TELETEXT,
41 DMX_TS_PES_SUBTITLE,
42 DMX_TS_PES_PCR,
43 DMX_TS_PES_OTHER,
44 } dmx_ts_pes_t;
45</programlisting>
46<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
47should be kept identical) to the types in the demux device.
48</para>
49<programlisting>
50 struct dmx_ts_feed_s {
51 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
52 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
53 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
54 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
55 __u16 pid,
56 size_t callback_length,
57 size_t circular_buffer_size,
58 int descramble,
59 struct timespec timeout);
60 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
61 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
62 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
63 int type,
64 dmx_ts_pes_t pes_type);
65 };
66
67 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
68</programlisting>
69 <programlisting>
70 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
71 /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
72 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
73
74 typedef struct dmx_pes_filter_s {
75 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
76 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
77 } dmx_pes_filter_t;
78</programlisting>
79 <programlisting>
80 typedef struct dmx_pes_feed_s {
81 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
82 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
83 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
84 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
85 __u16 pid,
86 size_t circular_buffer_size,
87 int descramble,
88 struct timespec timeout);
89 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
90 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
91 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
92 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
93 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
94 dmx_pes_filter_t&#x22C6; filter);
95 } dmx_pes_feed_t;
96</programlisting>
97 <programlisting>
98 typedef struct {
99 __u8 filter_value [DMX_MAX_FILTER_SIZE];
100 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
101 struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
102 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
103 } dmx_section_filter_t;
104</programlisting>
105 <programlisting>
106 struct dmx_section_feed_s {
107 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
108 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
109 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
110 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
111 __u16 pid,
112 size_t circular_buffer_size,
113 int descramble,
114 int check_crc);
115 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
116 dmx_section_filter_t&#x22C6;&#x22C6; filter);
117 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
118 dmx_section_filter_t&#x22C6; filter);
119 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
120 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
121 };
122 typedef struct dmx_section_feed_s dmx_section_feed_t;
123
124 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
125 /&#x22C6; Callback functions &#x22C6;/
126 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
127
128 typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
129 size_t buffer1_length,
130 __u8 &#x22C6; buffer2,
131 size_t buffer2_length,
2f684b23 132 dmx_ts_feed_t&#x22C6; source)
8e080c2e
MCC		 133
134 typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
135 size_t buffer1_len,
136 __u8 &#x22C6; buffer2,
137 size_t buffer2_len,
2f684b23 138 dmx_section_filter_t &#x22C6; source);
8e080c2e
MCC		 139
140 typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
141 size_t buffer1_len,
142 __u8 &#x22C6; buffer2,
143 size_t buffer2_len,
2f684b23 144 dmx_pes_filter_t&#x22C6; source);
8e080c2e
MCC		 145
146 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
147 /&#x22C6; DVB Front-End &#x22C6;/
148 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
149
150 typedef enum {
0693bdf7
MCC		 151 DMX_MEMORY_FE,
152 DMX_FRONTEND_0,
153 } dmx_frontend_source;
8e080c2e
MCC		 154
155 typedef struct {
156 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
157 char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
158 char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
159 char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
160 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
161 be connected to a particular
162 demux &#x22C6;/
163 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
0693bdf7 164 dmx_frontend_source source;
8e080c2e
MCC		 165 } dmx_frontend_t;
166
167 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
168 /&#x22C6; MPEG-2 TS Demux &#x22C6;/
169 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
170
171 /&#x22C6;
172 &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
173 &#x22C6;/
174
175 #define DMX_TS_FILTERING 1
176 #define DMX_PES_FILTERING 2
177 #define DMX_SECTION_FILTERING 4
178 #define DMX_MEMORY_BASED_FILTERING 8 /&#x22C6; write() available &#x22C6;/
179 #define DMX_CRC_CHECKING 16
180 #define DMX_TS_DESCRAMBLING 32
181 #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
182 #define DMX_MAC_ADDRESS_DESCRAMBLING 128
183</programlisting>
184
185</section>
186<section id="demux_demux_t">
187<title>demux_demux_t</title>
188 <programlisting>
189 /&#x22C6;
190 &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
191 &#x22C6; front-ends from the generic type struct list_head
192 &#x22C6; to the type &#x22C6; dmx_frontend_t
193 &#x22C6;.
194 &#x22C6;/
8e080c2e
MCC		 195</programlisting>
196
197</section>
198<section id="demux_directory">
199<title>Demux directory</title>
200 <programlisting>
201 /&#x22C6;
202 &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
203 &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
204 &#x22C6;.
205 &#x22C6;/
206
207 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
208
209 int dmx_register_demux (dmx_demux_t&#x22C6; demux);
210 int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
211 struct list_head&#x22C6; dmx_get_demuxes (void);
212</programlisting>
213 </section></section>
214<section id="demux_directory_api">
215<title>Demux Directory API</title>
216<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
217MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
218is possible using this API.
219</para>
220<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
221</para>
222
223<section
224role="subsection"><title>dmx_register_demux()</title>
225<para>DESCRIPTION
226</para>
227<informaltable><tgroup cols="1"><tbody><row><entry
228 align="char">
229<para>This function makes a demux driver interface available to the Linux kernel. It is
230 usually called by the init_module() function of the kernel module that contains
231 the demux driver. The caller of this function is responsible for allocating
232 dynamic or static memory for the demux structure and for initializing its fields
233 before calling this function. The memory allocated for the demux structure
234 must not be freed before calling dmx_unregister_demux(),</para>
235</entry>
236 </row></tbody></tgroup></informaltable>
237<para>SYNOPSIS
238</para>
239<informaltable><tgroup cols="1"><tbody><row><entry
240 align="char">
241<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
242</entry>
243 </row></tbody></tgroup></informaltable>
244<para>PARAMETERS
245</para>
246<informaltable><tgroup cols="2"><tbody><row><entry
247 align="char">
248<para>dmx_demux_t*
249 demux</para>
250</entry><entry
251 align="char">
252<para>Pointer to the demux structure.</para>
253</entry>
254 </row></tbody></tgroup></informaltable>
255<para>RETURNS
256</para>
257<informaltable><tgroup cols="2"><tbody><row><entry
258 align="char">
259<para>0</para>
260</entry><entry
261 align="char">
262<para>The function was completed without errors.</para>
263</entry>
264 </row><row><entry
265 align="char">
266<para>-EEXIST</para>
267</entry><entry
268 align="char">
269<para>A demux with the same value of the id field already stored
270 in the directory.</para>
271</entry>
272 </row><row><entry
273 align="char">
274<para>-ENOSPC</para>
275</entry><entry
276 align="char">
277<para>No space left in the directory.</para>
278</entry>
279 </row></tbody></tgroup></informaltable>
280
281</section><section
282role="subsection"><title>dmx_unregister_demux()</title>
283<para>DESCRIPTION
284</para>
285<informaltable><tgroup cols="1"><tbody><row><entry
286 align="char">
287<para>This function is called to indicate that the given demux interface is no
288 longer available. The caller of this function is responsible for freeing the
289 memory of the demux structure, if it was dynamically allocated before calling
290 dmx_register_demux(). The cleanup_module() function of the kernel module
291 that contains the demux driver should call this function. Note that this function
292 fails if the demux is currently in use, i.e., release_demux() has not been called
293 for the interface.</para>
294</entry>
295 </row></tbody></tgroup></informaltable>
296<para>SYNOPSIS
297</para>
298<informaltable><tgroup cols="1"><tbody><row><entry
299 align="char">
300<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
301</entry>
302 </row></tbody></tgroup></informaltable>
303<para>PARAMETERS
304</para>
305<informaltable><tgroup cols="2"><tbody><row><entry
306 align="char">
307<para>dmx_demux_t*
308 demux</para>
309</entry><entry
310 align="char">
311<para>Pointer to the demux structure which is to be
312 unregistered.</para>
313</entry>
314 </row></tbody></tgroup></informaltable>
315<para>RETURNS
316</para>
317<informaltable><tgroup cols="2"><tbody><row><entry
318 align="char">
319<para>0</para>
320</entry><entry
321 align="char">
322<para>The function was completed without errors.</para>
323</entry>
324 </row><row><entry
325 align="char">
326<para>ENODEV</para>
327</entry><entry
328 align="char">
329<para>The specified demux is not registered in the demux
330 directory.</para>
331</entry>
332 </row><row><entry
333 align="char">
334<para>EBUSY</para>
335</entry><entry
336 align="char">
337<para>The specified demux is currently in use.</para>
338</entry>
339 </row></tbody></tgroup></informaltable>
340
341</section><section
342role="subsection"><title>dmx_get_demuxes()</title>
343<para>DESCRIPTION
344</para>
345<informaltable><tgroup cols="1"><tbody><row><entry
346 align="char">
347<para>Provides the caller with the list of registered demux interfaces, using the
348 standard list structure defined in the include file linux/list.h. The include file
349 demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
350 the generic type struct list_head* to the type dmx_demux_t*. The caller must
351 not free the memory of any of the elements obtained via this function call.</para>
352</entry>
353 </row></tbody></tgroup></informaltable>
354<para>SYNOPSIS
355</para>
356<informaltable><tgroup cols="1"><tbody><row><entry
357 align="char">
358<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
359</entry>
360 </row></tbody></tgroup></informaltable>
361<para>PARAMETERS
362</para>
363<informaltable><tgroup cols="2"><tbody><row><entry
364 align="char">
365<para>none</para>
366</entry>
367 </row></tbody></tgroup></informaltable>
368<para>RETURNS
369</para>
370<informaltable><tgroup cols="2"><tbody><row><entry
371 align="char">
372<para>struct list_head *</para>
373</entry><entry
374 align="char">
375<para>A list of demux interfaces, or NULL in the case of an
376 empty list.</para>
377</entry>
378 </row></tbody></tgroup></informaltable>
379 </section></section>
380<section id="demux_api">
381<title>Demux API</title>
382<para>The demux API should be implemented for each demux in the system. It is used to select
383the TS source of a demux and to manage the demux resources. When the demux
384client allocates a resource via the demux API, it receives a pointer to the API of that
385resource.
386</para>
387<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
388demux API. In a system with more than one front-end, the API can be used to select one of
389the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
390demux API only controls front-ends regarding their connections with demuxes; the APIs
391used to set the other front-end parameters, such as tuning, are not defined in this
392document.
393</para>
394<para>The functions that implement the abstract interface demux should be defined static or
395module private and registered to the Demux Directory for external access. It is not necessary
396to implement every function in the demux_t struct, however (for example, a demux interface
397might support Section filtering, but not TS or PES filtering). The API client is expected to
398check the value of any function pointer before calling the function: the value of NULL means
399&#8220;function not available&#8221;.
400</para>
401<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
402update and race condition problems should be addressed, e.g. by protecting parts of code with
403mutexes. This is especially important on multi-processor hosts.
404</para>
405<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
406kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
407swapping is needed. For example, the Linux kernel calls the functions of a network device
408interface from a bottom half context. Thus, if a demux API function is called from network
409device code, the function must not sleep.
410</para>
411
8e080c2e 412</section>
8e080c2e
MCC		 413<section id="demux_callback_api">
414<title>Demux Callback API</title>
415<para>This kernel-space API comprises the callback functions that deliver filtered data to the
416demux client. Unlike the other APIs, these API functions are provided by the client and called
417from the demux code.
418</para>
419<para>The function pointers of this abstract interface are not packed into a structure as in the
420other demux APIs, because the callback functions are registered and used independent
421of each other. As an example, it is possible for the API client to provide several
422callback functions for receiving TS packets and no callbacks for PES packets or
423sections.
424</para>
425<para>The functions that implement the callback API need not be re-entrant: when a demux
426driver calls one of these functions, the driver is not allowed to call the function again before
427the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
428to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
429function call directly from a hardware interrupt.
430</para>
431
432<section
433role="subsection"><title>dmx_ts_cb()</title>
434<para>DESCRIPTION
435</para>
436<informaltable><tgroup cols="1"><tbody><row><entry
437 align="char">
438<para>This function, provided by the client of the demux API, is called from the
439 demux code. The function is only called when filtering on this TS feed has
440 been enabled using the start_filtering() function.</para>
441</entry>
442 </row><row><entry
443 align="char">
444<para>Any TS packets that match the filter settings are copied to a circular buffer. The
445 filtered TS packets are delivered to the client using this callback function. The
446 size of the circular buffer is controlled by the circular_buffer_size parameter
447 of the set() function in the TS Feed API. It is expected that the buffer1 and
448 buffer2 callback parameters point to addresses within the circular buffer, but
449 other implementations are also possible. Note that the called party should not
450 try to free the memory the buffer1 and buffer2 parameters point to.</para>
451</entry>
452 </row><row><entry
453 align="char">
454<para>When this function is called, the buffer1 parameter typically points to the
455 start of the first undelivered TS packet within a circular buffer. The buffer2
456 buffer parameter is normally NULL, except when the received TS packets have
457 crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
458 of the buffer. In the latter case the buffer1 parameter would contain an address
459 within the circular buffer, while the buffer2 parameter would contain the first
460 address of the circular buffer.</para>
461</entry>
462 </row><row><entry
463 align="char">
464<para>The number of bytes delivered with this function (i.e. buffer1_length +
465 buffer2_length) is usually equal to the value of callback_length parameter
466 given in the set() function, with one exception: if a timeout occurs before
467 receiving callback_length bytes of TS data, any undelivered packets are
468 immediately delivered to the client by calling this function. The timeout
469 duration is controlled by the set() function in the TS Feed API.</para>
470</entry>
471 </row><row><entry
472 align="char">
473<para>If a TS packet is received with errors that could not be fixed by the TS-level
474 forward error correction (FEC), the Transport_error_indicator flag of the TS
475 packet header should be set. The TS packet should not be discarded, as
476 the error can possibly be corrected by a higher layer protocol. If the called
477 party is slow in processing the callback, it is possible that the circular buffer
478 eventually fills up. If this happens, the demux driver should discard any TS
479 packets received while the buffer is full. The error should be indicated to the
480 client on the next callback by setting the success parameter to the value of
481 DMX_OVERRUN_ERROR.</para>
482</entry>
483 </row><row><entry
484 align="char">
485<para>The type of data returned to the callback can be selected by the new
486 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
487 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
488 include file ost/demux.h) The type parameter decides if the raw TS packet
489 (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
490 should be returned. If additionally the TS_DECODER bit is set the stream
491 will also be sent to the hardware MPEG decoder. In this case, the second
492 flag decides as what kind of data the stream should be interpreted. The
493 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
494 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
495 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
496</entry>
497 </row></tbody></tgroup></informaltable>
498<para>SYNOPSIS
499</para>
500<informaltable><tgroup cols="1"><tbody><row><entry
501 align="char">
502<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
503 __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
2f684b23 504 source);</para>
8e080c2e
MCC		 505</entry>
506 </row></tbody></tgroup></informaltable>
507<para>PARAMETERS
508</para>
509<informaltable><tgroup cols="2"><tbody><row><entry
510 align="char">
511<para>__u8* buffer1</para>
512</entry><entry
513 align="char">
514<para>Pointer to the start of the filtered TS packets.</para>
515</entry>
516 </row><row><entry
517 align="char">
518<para>size_t buffer1_length</para>
519</entry><entry
520 align="char">
521<para>Length of the TS data in buffer1.</para>
522</entry>
523 </row><row><entry
524 align="char">
525<para>__u8* buffer2</para>
526</entry><entry
527 align="char">
528<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
529</entry>
530 </row><row><entry
531 align="char">
532<para>size_t buffer2_length</para>
533</entry><entry
534 align="char">
535<para>Length of the TS data in buffer2.</para>
536</entry>
537 </row><row><entry
538 align="char">
539<para>dmx_ts_feed_t*
540 source</para>
541</entry><entry
542 align="char">
543<para>Indicates which TS feed is the source of the callback.</para>
8e080c2e
MCC		 544</entry>
545 </row></tbody></tgroup></informaltable>
546<para>RETURNS
547</para>
548<informaltable><tgroup cols="2"><tbody><row><entry
549 align="char">
550<para>0</para>
551</entry><entry
552 align="char">
553<para>Continue filtering.</para>
554</entry>
555 </row><row><entry
556 align="char">
557<para>-1</para>
558</entry><entry
559 align="char">
560<para>Stop filtering - has the same effect as a call to
561 stop_filtering() on the TS Feed API.</para>
562</entry>
563 </row></tbody></tgroup></informaltable>
564
565</section><section
566role="subsection"><title>dmx_section_cb()</title>
567<para>DESCRIPTION
568</para>
569<informaltable><tgroup cols="1"><tbody><row><entry
570 align="char">
571<para>This function, provided by the client of the demux API, is called from the
572 demux code. The function is only called when filtering of sections has been
573 enabled using the function start_filtering() of the section feed API. When the
574 demux driver has received a complete section that matches at least one section
575 filter, the client is notified via this callback function. Normally this function is
576 called for each received section; however, it is also possible to deliver multiple
577 sections with one callback, for example when the system load is high. If an
578 error occurs while receiving a section, this function should be called with
579 the corresponding error type set in the success field, whether or not there is
580 data to deliver. The Section Feed implementation should maintain a circular
581 buffer for received sections. However, this is not necessary if the Section Feed
582 API is implemented as a client of the TS Feed API, because the TS Feed
583 implementation then buffers the received data. The size of the circular buffer
584 can be configured using the set() function in the Section Feed API. If there
585 is no room in the circular buffer when a new section is received, the section
586 must be discarded. If this happens, the value of the success parameter should
587 be DMX_OVERRUN_ERROR on the next callback.</para>
588</entry>
589 </row></tbody></tgroup></informaltable>
590<para>SYNOPSIS
591</para>
592<informaltable><tgroup cols="1"><tbody><row><entry
593 align="char">
594<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
595 buffer1_length, __u8&#x22C6; buffer2, size_t
2f684b23 596 buffer2_length, dmx_section_filter_t&#x22C6; source);</para>
8e080c2e
MCC		 597</entry>
598 </row></tbody></tgroup></informaltable>
599<para>PARAMETERS
600</para>
601<informaltable><tgroup cols="2"><tbody><row><entry
602 align="char">
603<para>__u8* buffer1</para>
604</entry><entry
605 align="char">
606<para>Pointer to the start of the filtered section, e.g. within the
607 circular buffer of the demux driver.</para>
608</entry>
609 </row><row><entry
610 align="char">
611<para>size_t buffer1_length</para>
612</entry><entry
613 align="char">
614<para>Length of the filtered section data in buffer1, including
615 headers and CRC.</para>
616</entry>
617 </row><row><entry
618 align="char">
619<para>__u8* buffer2</para>
620</entry><entry
621 align="char">
622<para>Pointer to the tail of the filtered section data, or NULL.
623 Useful to handle the wrapping of a circular buffer.</para>
624</entry>
625 </row><row><entry
626 align="char">
627<para>size_t buffer2_length</para>
628</entry><entry
629 align="char">
630<para>Length of the filtered section data in buffer2, including
631 headers and CRC.</para>
632</entry>
633 </row><row><entry
634 align="char">
635<para>dmx_section_filter_t*
636 filter</para>
637</entry><entry
638 align="char">
639<para>Indicates the filter that triggered the callback.</para>
8e080c2e
MCC		 640</entry>
641 </row></tbody></tgroup></informaltable>
642<para>RETURNS
643</para>
644<informaltable><tgroup cols="2"><tbody><row><entry
645 align="char">
646<para>0</para>
647</entry><entry
648 align="char">
649<para>Continue filtering.</para>
650</entry>
651 </row><row><entry
652 align="char">
653<para>-1</para>
654</entry><entry
655 align="char">
656<para>Stop filtering - has the same effect as a call to
657 stop_filtering() on the Section Feed API.</para>
658</entry>
659 </row></tbody></tgroup></informaltable>
660 </section></section>
661<section id="ts_feed_api">
662<title>TS Feed API</title>
663<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
664Using this API, the client can set the filtering properties to start/stop filtering TS
665packets on a particular TS feed. The API is defined as an abstract interface of the type
666dmx_ts_feed_t.
667</para>
668<para>The functions that implement the interface should be defined static or module private. The
669client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
670demux API.
671</para>
672
673<section
674role="subsection"><title>set()</title>
675<para>DESCRIPTION
676</para>
677<informaltable><tgroup cols="1"><tbody><row><entry
678 align="char">
679<para>This function sets the parameters of a TS feed. Any filtering in progress on the
680 TS feed must be stopped before calling this function.</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 set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
688 callback_length, size_t circular_buffer_size, int
689 descramble, struct timespec timeout);</para>
690</entry>
691 </row></tbody></tgroup></informaltable>
692<para>PARAMETERS
693</para>
694<informaltable><tgroup cols="2"><tbody><row><entry
695 align="char">
696<para>dmx_ts_feed_t* feed</para>
697</entry><entry
698 align="char">
699<para>Pointer to the TS feed API and instance data.</para>
700</entry>
701 </row><row><entry
702 align="char">
703<para>__u16 pid</para>
704</entry><entry
705 align="char">
706<para>PID value to filter. Only the TS packets carrying the
707 specified PID will be passed to the API client.</para>
708</entry>
709 </row><row><entry
710 align="char">
711<para>size_t
712 callback_length</para>
713</entry><entry
714 align="char">
715<para>Number of bytes to deliver with each call to the
716 dmx_ts_cb() callback function. The value of this
717 parameter should be a multiple of 188.</para>
718</entry>
719 </row><row><entry
720 align="char">
721<para>size_t
722 circular_buffer_size</para>
723</entry><entry
724 align="char">
725<para>Size of the circular buffer for the filtered TS packets.</para>
726</entry>
727 </row><row><entry
728 align="char">
729<para>int descramble</para>
730</entry><entry
731 align="char">
732<para>If non-zero, descramble the filtered TS packets.</para>
733</entry>
734 </row><row><entry
735 align="char">
736<para>struct timespec
737 timeout</para>
738</entry><entry
739 align="char">
740<para>Maximum time to wait before delivering received TS
741 packets to the client.</para>
742</entry>
743 </row></tbody></tgroup></informaltable>
744<para>RETURNS
745</para>
746<informaltable><tgroup cols="2"><tbody><row><entry
747 align="char">
748<para>0</para>
749</entry><entry
750 align="char">
751<para>The function was completed without errors.</para>
752</entry>
753 </row><row><entry
754 align="char">
755<para>-ENOMEM</para>
756</entry><entry
757 align="char">
758<para>Not enough memory for the requested buffer size.</para>
759</entry>
760 </row><row><entry
761 align="char">
762<para>-ENOSYS</para>
763</entry><entry
764 align="char">
765<para>No descrambling facility available for TS.</para>
766</entry>
767 </row><row><entry
768 align="char">
769<para>-EINVAL</para>
770</entry><entry
771 align="char">
772<para>Bad parameter.</para>
773</entry>
774 </row></tbody></tgroup></informaltable>
775
776</section><section
777role="subsection"><title>start_filtering()</title>
778<para>DESCRIPTION
779</para>
780<informaltable><tgroup cols="1"><tbody><row><entry
781 align="char">
782<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
783 value to filter can be set by the API client. All matching TS packets are
784 delivered asynchronously to the client, using the callback function registered
785 with allocate_ts_feed().</para>
786</entry>
787 </row></tbody></tgroup></informaltable>
788<para>SYNOPSIS
789</para>
790<informaltable><tgroup cols="1"><tbody><row><entry
791 align="char">
792<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
793</entry>
794 </row></tbody></tgroup></informaltable>
795<para>PARAMETERS
796</para>
797<informaltable><tgroup cols="2"><tbody><row><entry
798 align="char">
799<para>dmx_ts_feed_t* feed</para>
800</entry><entry
801 align="char">
802<para>Pointer to the TS feed API and instance data.</para>
803</entry>
804 </row></tbody></tgroup></informaltable>
805<para>RETURNS
806</para>
807<informaltable><tgroup cols="2"><tbody><row><entry
808 align="char">
809<para>0</para>
810</entry><entry
811 align="char">
812<para>The function was completed without errors.</para>
813</entry>
814 </row><row><entry
815 align="char">
816<para>-EINVAL</para>
817</entry><entry
818 align="char">
819<para>Bad parameter.</para>
820</entry>
821 </row></tbody></tgroup></informaltable>
822
823</section><section
824role="subsection"><title>stop_filtering()</title>
825<para>DESCRIPTION
826</para>
827<informaltable><tgroup cols="1"><tbody><row><entry
828 align="char">
829<para>Stops filtering TS packets on this TS feed.</para>
830</entry>
831 </row></tbody></tgroup></informaltable>
832<para>SYNOPSIS
833</para>
834<informaltable><tgroup cols="1"><tbody><row><entry
835 align="char">
836<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
837</entry>
838 </row></tbody></tgroup></informaltable>
839<para>PARAMETERS
840</para>
841<informaltable><tgroup cols="2"><tbody><row><entry
842 align="char">
843<para>dmx_ts_feed_t* feed</para>
844</entry><entry
845 align="char">
846<para>Pointer to the TS feed API and instance data.</para>
847</entry>
848 </row></tbody></tgroup></informaltable>
849<para>RETURNS
850</para>
851<informaltable><tgroup cols="2"><tbody><row><entry
852 align="char">
853<para>0</para>
854</entry><entry
855 align="char">
856<para>The function was completed without errors.</para>
857</entry>
858 </row><row><entry
859 align="char">
860<para>-EINVAL</para>
861</entry><entry
862 align="char">
863<para>Bad parameter.</para>
864</entry>
865 </row></tbody></tgroup></informaltable>
866 </section></section>
867<section id="section_feed_api">
868<title>Section Feed API</title>
869<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
870API, the client can set the properties of a section feed and to start/stop filtering. The API is
871defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
872the interface should be defined static or module private. The client can get the handle of
873a section feed API by calling the function allocate_section_feed() in the demux
874API.
875</para>
876<para>On demux platforms that provide section filtering in hardware, the Section Feed API
877implementation provides a software wrapper for the demux hardware. Other platforms may
878support only PID filtering in hardware, requiring that TS packets are converted to sections in
879software. In the latter case the Section Feed API implementation can be a client of the TS
880Feed API.
881</para>
882
883</section>
884<section id="kdapi_set">
885<title>set()</title>
886<para>DESCRIPTION
887</para>
888<informaltable><tgroup cols="1"><tbody><row><entry
889 align="char">
890<para>This function sets the parameters of a section feed. Any filtering in progress on
891 the section feed must be stopped before calling this function. If descrambling
892 is enabled, the payload_scrambling_control and address_scrambling_control
893 fields of received DVB datagram sections should be observed. If either one is
894 non-zero, the section should be descrambled either in hardware or using the
895 functions descramble_mac_address() and descramble_section_payload() of the
896 demux API. Note that according to the MPEG-2 Systems specification, only
897 the payloads of private sections can be scrambled while the rest of the section
898 data must be sent in the clear.</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 set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
906 circular_buffer_size, int descramble, int
907 check_crc);</para>
908</entry>
909 </row></tbody></tgroup></informaltable>
910<para>PARAMETERS
911</para>
912<informaltable><tgroup cols="2"><tbody><row><entry
913 align="char">
914<para>dmx_section_feed_t*
915 feed</para>
916</entry><entry
917 align="char">
918<para>Pointer to the section feed API and instance data.</para>
919</entry>
920 </row><row><entry
921 align="char">
922<para>__u16 pid</para>
923</entry><entry
924 align="char">
925<para>PID value to filter; only the TS packets carrying the
926 specified PID will be accepted.</para>
927</entry>
928 </row><row><entry
929 align="char">
930<para>size_t
931 circular_buffer_size</para>
932</entry><entry
933 align="char">
934<para>Size of the circular buffer for filtered sections.</para>
935</entry>
936 </row><row><entry
937 align="char">
938<para>int descramble</para>
939</entry><entry
940 align="char">
941<para>If non-zero, descramble any sections that are scrambled.</para>
942</entry>
943 </row><row><entry
944 align="char">
945<para>int check_crc</para>
946</entry><entry
947 align="char">
948<para>If non-zero, check the CRC values of filtered sections.</para>
949</entry>
950 </row></tbody></tgroup></informaltable>
951<para>RETURNS
952</para>
953<informaltable><tgroup cols="2"><tbody><row><entry
954 align="char">
955<para>0</para>
956</entry><entry
957 align="char">
958<para>The function was completed without errors.</para>
959</entry>
960 </row><row><entry
961 align="char">
962<para>-ENOMEM</para>
963</entry><entry
964 align="char">
965<para>Not enough memory for the requested buffer size.</para>
966</entry>
967 </row><row><entry
968 align="char">
969<para>-ENOSYS</para>
970</entry><entry
971 align="char">
972<para>No descrambling facility available for sections.</para>
973</entry>
974 </row><row><entry
975 align="char">
976<para>-EINVAL</para>
977</entry><entry
978 align="char">
979<para>Bad parameters.</para>
980</entry>
981 </row></tbody></tgroup></informaltable>
982
983</section><section
984role="subsection"><title>allocate_filter()</title>
985<para>DESCRIPTION
986</para>
987<informaltable><tgroup cols="1"><tbody><row><entry
988 align="char">
989<para>This function is used to allocate a section filter on the demux. It should only be
990 called when no filtering is in progress on this section feed. If a filter cannot be
991 allocated, the function fails with -ENOSPC. See in section ?? for the format of
992 the section filter.</para>
993</entry>
994 </row><row><entry
995 align="char">
996<para>The bitfields filter_mask and filter_value should only be modified when no
997 filtering is in progress on this section feed. filter_mask controls which bits of
998 filter_value are compared with the section headers/payload. On a binary value
999 of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
1000 sections that are equal to filter_value in all the tested bit positions. Any changes
1001 to the values of filter_mask and filter_value are guaranteed to take effect only
1002 when the start_filtering() function is called next time. The parent pointer in
1003 the struct is initialized by the API implementation to the value of the feed
1004 parameter. The priv pointer is not used by the API implementation, and can
1005 thus be freely utilized by the caller of this function. Any data pointed to by the
1006 priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
1007</entry>
1008 </row><row><entry
1009 align="char">
1010<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
1011 currently set at 16 bytes, hardware filters of that size are not available on all
1012 platforms. Therefore, section filtering will often take place first in hardware,
1013 followed by filtering in software for the header bytes that were not covered
1014 by a hardware filter. The filter_mask field can be checked to determine how
1015 many bytes of the section filter are actually used, and if the hardware filter will
1016 suffice. Additionally, software-only section filters can optionally be allocated
1017 to clients when all hardware section filters are in use. Note that on most demux
1018 hardware it is not possible to filter on the section_length field of the section
1019 header &#8211; thus this field is ignored, even though it is included in filter_value and
1020 filter_mask fields.</para>
1021</entry>
1022 </row></tbody></tgroup></informaltable>
1023<para>SYNOPSIS
1024</para>
1025<informaltable><tgroup cols="1"><tbody><row><entry
1026 align="char">
1027<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
1028 dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
1029</entry>
1030 </row></tbody></tgroup></informaltable>
1031<para>PARAMETERS
1032</para>
1033<informaltable><tgroup cols="2"><tbody><row><entry
1034 align="char">
1035<para>dmx_section_feed_t*
1036 feed</para>
1037</entry><entry
1038 align="char">
1039<para>Pointer to the section feed API and instance data.</para>
1040</entry>
1041 </row><row><entry
1042 align="char">
1043<para>dmx_section_filter_t**
1044 filter</para>
1045</entry><entry
1046 align="char">
1047<para>Pointer to the allocated filter.</para>
1048</entry>
1049 </row></tbody></tgroup></informaltable>
1050<para>RETURNS
1051</para>
1052<informaltable><tgroup cols="2"><tbody><row><entry
1053 align="char">
1054<para>0</para>
1055</entry><entry
1056 align="char">
1057<para>The function was completed without errors.</para>
1058</entry>
1059 </row><row><entry
1060 align="char">
1061<para>-ENOSPC</para>
1062</entry><entry
1063 align="char">
1064<para>No filters of given type and length available.</para>
1065</entry>
1066 </row><row><entry
1067 align="char">
1068<para>-EINVAL</para>
1069</entry><entry
1070 align="char">
1071<para>Bad parameters.</para>
1072</entry>
1073 </row></tbody></tgroup></informaltable>
1074
1075</section><section
1076role="subsection"><title>release_filter()</title>
1077<para>DESCRIPTION
1078</para>
1079<informaltable><tgroup cols="1"><tbody><row><entry
1080 align="char">
1081<para>This function releases all the resources of a previously allocated section filter.
1082 The function should not be called while filtering is in progress on this section
1083 feed. After calling this function, the caller should not try to dereference the
1084 filter pointer.</para>
1085</entry>
1086 </row></tbody></tgroup></informaltable>
1087<para>SYNOPSIS
1088</para>
1089<informaltable><tgroup cols="1"><tbody><row><entry
1090 align="char">
1091<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
1092 dmx_section_filter_t&#x22C6; filter);</para>
1093</entry>
1094 </row></tbody></tgroup></informaltable>
1095<para>PARAMETERS
1096</para>
1097<informaltable><tgroup cols="2"><tbody><row><entry
1098 align="char">
1099<para>dmx_section_feed_t*
1100 feed</para>
1101</entry><entry
1102 align="char">
1103<para>Pointer to the section feed API and instance data.</para>
1104</entry>
1105 </row><row><entry
1106 align="char">
1107<para>dmx_section_filter_t*
1108 filter</para>
1109</entry><entry
1110 align="char">
1111<para>I/O Pointer to the instance data of a section filter.</para>
1112</entry>
1113 </row></tbody></tgroup></informaltable>
1114<para>RETURNS
1115</para>
1116<informaltable><tgroup cols="2"><tbody><row><entry
1117 align="char">
1118<para>0</para>
1119</entry><entry
1120 align="char">
1121<para>The function was completed without errors.</para>
1122</entry>
1123 </row><row><entry
1124 align="char">
1125<para>-ENODEV</para>
1126</entry><entry
1127 align="char">
1128<para>No such filter allocated.</para>
1129</entry>
1130 </row><row><entry
1131 align="char">
1132<para>-EINVAL</para>
1133</entry><entry
1134 align="char">
1135<para>Bad parameter.</para>
1136</entry>
1137 </row></tbody></tgroup></informaltable>
1138
1139</section><section
1140role="subsection"><title>start_filtering()</title>
1141<para>DESCRIPTION
1142</para>
1143<informaltable><tgroup cols="1"><tbody><row><entry
1144 align="char">
1145<para>Starts filtering sections on this section feed, according to its settings. Sections
1146 are first filtered based on their PID and then matched with the section
1147 filters allocated for this feed. If the section matches the PID filter and
1148 at least one section filter, it is delivered to the API client. The section
1149 is delivered asynchronously using the callback function registered with
1150 allocate_section_feed().</para>
1151</entry>
1152 </row></tbody></tgroup></informaltable>
1153<para>SYNOPSIS
1154</para>
1155<informaltable><tgroup cols="1"><tbody><row><entry
1156 align="char">
1157<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
1158</entry>
1159 </row></tbody></tgroup></informaltable>
1160<para>PARAMETERS
1161</para>
1162<informaltable><tgroup cols="2"><tbody><row><entry
1163 align="char">
1164<para>dmx_section_feed_t*
1165 feed</para>
1166</entry><entry
1167 align="char">
1168<para>Pointer to the section feed API and instance data.</para>
1169</entry>
1170 </row></tbody></tgroup></informaltable>
1171<para>RETURNS
1172</para>
1173<informaltable><tgroup cols="2"><tbody><row><entry
1174 align="char">
1175<para>0</para>
1176</entry><entry
1177 align="char">
1178<para>The function was completed without errors.</para>
1179</entry>
1180 </row><row><entry
1181 align="char">
1182<para>-EINVAL</para>
1183</entry><entry
1184 align="char">
1185<para>Bad parameter.</para>
1186</entry>
1187 </row></tbody></tgroup></informaltable>
1188
1189</section><section
1190role="subsection"><title>stop_filtering()</title>
1191<para>DESCRIPTION
1192</para>
1193<informaltable><tgroup cols="1"><tbody><row><entry
1194 align="char">
1195<para>Stops filtering sections on this section feed. Note that any changes to the
1196 filtering parameters (filter_value, filter_mask, etc.) should only be made when
1197 filtering is stopped.</para>
1198</entry>
1199 </row></tbody></tgroup></informaltable>
1200<para>SYNOPSIS
1201</para>
1202<informaltable><tgroup cols="1"><tbody><row><entry
1203 align="char">
1204<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
1205</entry>
1206 </row></tbody></tgroup></informaltable>
1207<para>PARAMETERS
1208</para>
1209<informaltable><tgroup cols="2"><tbody><row><entry
1210 align="char">
1211<para>dmx_section_feed_t*
1212 feed</para>
1213</entry><entry
1214 align="char">
1215<para>Pointer to the section feed API and instance data.</para>
1216</entry>
1217 </row></tbody></tgroup></informaltable>
1218<para>RETURNS
1219</para>
1220<informaltable><tgroup cols="2"><tbody><row><entry
1221 align="char">
1222<para>0</para>
1223</entry><entry
1224 align="char">
1225<para>The function was completed without errors.</para>
1226</entry>
1227 </row><row><entry
1228 align="char">
1229<para>-EINVAL</para>
1230</entry><entry
1231 align="char">
1232<para>Bad parameter.</para>
1233</entry>
1234 </row></tbody></tgroup></informaltable>
1235
1236</section>
Linux kernel - Deliverables
This page took 0.355655 seconds and 5 git commands to generate.