About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / dvb / kdapi.xml




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:38 EST.

1	<title>Kernel Demux API</title>
2	<para>The kernel demux API defines a driver-internal interface for registering low-level,
3	hardware specific driver to a hardware independent demux layer. It is only of interest for
4	DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in
5	<emphasis role="tt">drivers/media/dvb-core</emphasis>.
6	</para>
7	<para>Maintainer note: This section must be reviewed. It is probably out of date.
8	</para>
9	
10	<section id="kernel_demux_data_types">
11	<title>Kernel Demux Data Types</title>
12	
13	
14	<section id="dmx_success_t">
15	<title>dmx_success_t</title>
16	 <programlisting>
17	 typedef enum {
18	   DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
19	   DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
20	   DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
21	   DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
22	   DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
23	   DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
24	   DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
25	 } dmx_success_t;
26	</programlisting>
27	
28	</section>
29	<section id="ts_filter_types">
30	<title>TS filter types</title>
31	 <programlisting>
32	 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
33	 /&#x22C6; TS packet reception &#x22C6;/
34	 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
35	
36	 /&#x22C6; TS filter type for set_type() &#x22C6;/
37	
38	 #define TS_PACKET       1   /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
39	 #define TS_PAYLOAD_ONLY 2   /&#x22C6; in case TS_PACKET is set, only send the TS
40					payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
41	 #define TS_DECODER      4   /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
42	</programlisting>
43	
44	</section>
45	<section id="dmx_ts_pes_t">
46	<title>dmx_ts_pes_t</title>
47	<para>The structure
48	</para>
49	<programlisting>
50	 typedef enum
51	 {
52		 DMX_TS_PES_AUDIO,   /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
53		 DMX_TS_PES_VIDEO,   /&#x22C6; ... &#x22C6;/
54		 DMX_TS_PES_TELETEXT,
55		 DMX_TS_PES_SUBTITLE,
56		 DMX_TS_PES_PCR,
57		 DMX_TS_PES_OTHER,
58	 } dmx_ts_pes_t;
59	</programlisting>
60	<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
61	should 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
295	MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
296	is 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
302	role="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
360	role="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
420	role="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
461	the TS source of a demux and to manage the demux resources. When the demux
462	client allocates a resource via the demux API, it receives a pointer to the API of that
463	resource.
464	</para>
465	<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
466	demux API. In a system with more than one front-end, the API can be used to select one of
467	the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
468	demux API only controls front-ends regarding their connections with demuxes; the APIs
469	used to set the other front-end parameters, such as tuning, are not defined in this
470	document.
471	</para>
472	<para>The functions that implement the abstract interface demux should be defined static or
473	module private and registered to the Demux Directory for external access. It is not necessary
474	to implement every function in the demux_t struct, however (for example, a demux interface
475	might support Section filtering, but not TS or PES filtering). The API client is expected to
476	check 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
480	update and race condition problems should be addressed, e.g. by protecting parts of code with
481	mutexes. 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
484	kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
485	swapping is needed. For example, the Linux kernel calls the functions of a network device
486	interface from a bottom half context. Thus, if a demux API function is called from network
487	device 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
679	role="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
756	role="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
809	role="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
891	role="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
946	role="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
1044	role="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
1157	role="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
1239	role="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
1307	role="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
1355	role="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
1424	role="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
1472	demux client. Unlike the other APIs, these API functions are provided by the client and called
1473	from the demux code.
1474	</para>
1475	<para>The function pointers of this abstract interface are not packed into a structure as in the
1476	other demux APIs, because the callback functions are registered and used independent
1477	of each other. As an example, it is possible for the API client to provide several
1478	callback functions for receiving TS packets and no callbacks for PES packets or
1479	sections.
1480	</para>
1481	<para>The functions that implement the callback API need not be re-entrant: when a demux
1482	driver calls one of these functions, the driver is not allowed to call the function again before
1483	the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
1484	to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
1485	function call directly from a hardware interrupt.
1486	</para>
1487	
1488	<section
1489	role="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
1630	role="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.
1737	Using this API, the client can set the filtering properties to start/stop filtering TS
1738	packets on a particular TS feed. The API is defined as an abstract interface of the type
1739	dmx_ts_feed_t.
1740	</para>
1741	<para>The functions that implement the interface should be defined static or module private. The
1742	client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
1743	demux API.
1744	</para>
1745	
1746	<section
1747	role="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
1850	role="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
1897	role="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
1943	API, the client can set the properties of a section feed and to start/stop filtering. The API is
1944	defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
1945	the interface should be defined static or module private. The client can get the handle of
1946	a section feed API by calling the function allocate_section_feed() in the demux
1947	API.
1948	</para>
1949	<para>On demux platforms that provide section filtering in hardware, the Section Feed API
1950	implementation provides a software wrapper for the demux hardware. Other platforms may
1951	support only PID filtering in hardware, requiring that TS packets are converted to sections in
1952	software. In the latter case the Section Feed API implementation can be a client of the TS
1953	Feed 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
2057	role="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
2149	role="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
2213	role="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
2263	role="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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.