aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/dvb/kdapi.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/dvb/kdapi.xml')
-rw-r--r--Documentation/DocBook/dvb/kdapi.xml2309
1 files changed, 2309 insertions, 0 deletions
diff --git a/Documentation/DocBook/dvb/kdapi.xml b/Documentation/DocBook/dvb/kdapi.xml
new file mode 100644
index 000000000000..6c67481eaa4b
--- /dev/null
+++ b/Documentation/DocBook/dvb/kdapi.xml
@@ -0,0 +1,2309 @@
1<title>Kernel Demux API</title>
2<para>The kernel demux API defines a driver-internal interface for registering low-level,
3hardware specific driver to a hardware independent demux layer. It is only of interest for
4DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in
5<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>.
6</para>
7<para>Maintainer note: This section must be reviewed. It is probably out of date.
8</para>
9
10<section id="kernel_demux_data_types">
11<title>Kernel Demux Data Types</title>
12
13
14<section id="dmx_success_t">
15<title>dmx_success_t</title>
16 <programlisting>
17 typedef enum {
18 DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
19 DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
20 DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
21 DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
22 DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
23 DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
24 DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
25 } dmx_success_t;
26</programlisting>
27
28</section>
29<section id="ts_filter_types">
30<title>TS filter types</title>
31 <programlisting>
32 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
33 /&#x22C6; TS packet reception &#x22C6;/
34 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
35
36 /&#x22C6; TS filter type for set_type() &#x22C6;/
37
38 #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
39 #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
40 payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
41 #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
42</programlisting>
43
44</section>
45<section id="dmx_ts_pes_t">
46<title>dmx_ts_pes_t</title>
47<para>The structure
48</para>
49<programlisting>
50 typedef enum
51 {
52 DMX_TS_PES_AUDIO, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
53 DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
54 DMX_TS_PES_TELETEXT,
55 DMX_TS_PES_SUBTITLE,
56 DMX_TS_PES_PCR,
57 DMX_TS_PES_OTHER,
58 } dmx_ts_pes_t;
59</programlisting>
60<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
61should be kept identical) to the types in the demux device.
62</para>
63<programlisting>
64 struct dmx_ts_feed_s {
65 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
66 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
67 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
68 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
69 __u16 pid,
70 size_t callback_length,
71 size_t circular_buffer_size,
72 int descramble,
73 struct timespec timeout);
74 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
75 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
76 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
77 int type,
78 dmx_ts_pes_t pes_type);
79 };
80
81 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
82</programlisting>
83 <programlisting>
84 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
85 /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
86 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
87
88 typedef struct dmx_pes_filter_s {
89 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
90 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
91 } dmx_pes_filter_t;
92</programlisting>
93 <programlisting>
94 typedef struct dmx_pes_feed_s {
95 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
96 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
97 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
98 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
99 __u16 pid,
100 size_t circular_buffer_size,
101 int descramble,
102 struct timespec timeout);
103 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
104 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
105 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
106 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
107 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
108 dmx_pes_filter_t&#x22C6; filter);
109 } dmx_pes_feed_t;
110</programlisting>
111 <programlisting>
112 typedef struct {
113 __u8 filter_value [DMX_MAX_FILTER_SIZE];
114 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
115 struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
116 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
117 } dmx_section_filter_t;
118</programlisting>
119 <programlisting>
120 struct dmx_section_feed_s {
121 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
122 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
123 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
124 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
125 __u16 pid,
126 size_t circular_buffer_size,
127 int descramble,
128 int check_crc);
129 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
130 dmx_section_filter_t&#x22C6;&#x22C6; filter);
131 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
132 dmx_section_filter_t&#x22C6; filter);
133 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
134 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
135 };
136 typedef struct dmx_section_feed_s dmx_section_feed_t;
137
138 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
139 /&#x22C6; Callback functions &#x22C6;/
140 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
141
142 typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
143 size_t buffer1_length,
144 __u8 &#x22C6; buffer2,
145 size_t buffer2_length,
146 dmx_ts_feed_t&#x22C6; source,
147 dmx_success_t success);
148
149 typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
150 size_t buffer1_len,
151 __u8 &#x22C6; buffer2,
152 size_t buffer2_len,
153 dmx_section_filter_t &#x22C6; source,
154 dmx_success_t success);
155
156 typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
157 size_t buffer1_len,
158 __u8 &#x22C6; buffer2,
159 size_t buffer2_len,
160 dmx_pes_filter_t&#x22C6; source,
161 dmx_success_t success);
162
163 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
164 /&#x22C6; DVB Front-End &#x22C6;/
165 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
166
167 typedef enum {
168 DMX_OTHER_FE = 0,
169 DMX_SATELLITE_FE,
170 DMX_CABLE_FE,
171 DMX_TERRESTRIAL_FE,
172 DMX_LVDS_FE,
173 DMX_ASI_FE, /&#x22C6; DVB-ASI interface &#x22C6;/
174 DMX_MEMORY_FE
175 } dmx_frontend_source_t;
176
177 typedef struct {
178 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
179 char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
180 char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
181 char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
182 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
183 be connected to a particular
184 demux &#x22C6;/
185 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
186 dmx_frontend_source_t source;
187 } dmx_frontend_t;
188
189 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
190 /&#x22C6; MPEG-2 TS Demux &#x22C6;/
191 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
192
193 /&#x22C6;
194 &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
195 &#x22C6;/
196
197 #define DMX_TS_FILTERING 1
198 #define DMX_PES_FILTERING 2
199 #define DMX_SECTION_FILTERING 4
200 #define DMX_MEMORY_BASED_FILTERING 8 /&#x22C6; write() available &#x22C6;/
201 #define DMX_CRC_CHECKING 16
202 #define DMX_TS_DESCRAMBLING 32
203 #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
204 #define DMX_MAC_ADDRESS_DESCRAMBLING 128
205</programlisting>
206
207</section>
208<section id="demux_demux_t">
209<title>demux_demux_t</title>
210 <programlisting>
211 /&#x22C6;
212 &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
213 &#x22C6; front-ends from the generic type struct list_head
214 &#x22C6; to the type &#x22C6; dmx_frontend_t
215 &#x22C6;.
216 &#x22C6;/
217
218 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
219
220 struct dmx_demux_s {
221 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
222 char&#x22C6; id; /&#x22C6; Unique demux identifier &#x22C6;/
223 char&#x22C6; vendor; /&#x22C6; Name of the demux vendor &#x22C6;/
224 char&#x22C6; model; /&#x22C6; Name of the demux model &#x22C6;/
225 __u32 capabilities; /&#x22C6; Bitfield of capability flags &#x22C6;/
226 dmx_frontend_t&#x22C6; frontend; /&#x22C6; Front-end connected to the demux &#x22C6;/
227 struct list_head reg_list; /&#x22C6; List of registered demuxes &#x22C6;/
228 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
229 int users; /&#x22C6; Number of users &#x22C6;/
230 int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
231 int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
232 int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
233 int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
234 dmx_ts_feed_t&#x22C6;&#x22C6; feed,
235 dmx_ts_cb callback);
236 int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
237 dmx_ts_feed_t&#x22C6; feed);
238 int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
239 dmx_pes_feed_t&#x22C6;&#x22C6; feed,
240 dmx_pes_cb callback);
241 int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
242 dmx_pes_feed_t&#x22C6; feed);
243 int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
244 dmx_section_feed_t&#x22C6;&#x22C6; feed,
245 dmx_section_cb callback);
246 int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
247 dmx_section_feed_t&#x22C6; feed);
248 int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
249 __u8&#x22C6; buffer1,
250 size_t buffer1_length,
251 __u8&#x22C6; buffer2,
252 size_t buffer2_length,
253 __u16 pid);
254 int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
255 __u8&#x22C6; buffer1,
256 size_t buffer1_length,
257 __u8&#x22C6; buffer2, size_t buffer2_length,
258 __u16 pid);
259 int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
260 dmx_frontend_t&#x22C6; frontend);
261 int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
262 dmx_frontend_t&#x22C6; frontend);
263 struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
264 int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
265 dmx_frontend_t&#x22C6; frontend);
266 int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
267
268
269 /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
270 int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;pids);
271 };
272 typedef struct dmx_demux_s dmx_demux_t;
273</programlisting>
274
275</section>
276<section id="demux_directory">
277<title>Demux directory</title>
278 <programlisting>
279 /&#x22C6;
280 &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
281 &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
282 &#x22C6;.
283 &#x22C6;/
284
285 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
286
287 int dmx_register_demux (dmx_demux_t&#x22C6; demux);
288 int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
289 struct list_head&#x22C6; dmx_get_demuxes (void);
290</programlisting>
291 </section></section>
292<section id="demux_directory_api">
293<title>Demux Directory API</title>
294<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
295MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
296is possible using this API.
297</para>
298<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
299</para>
300
301<section
302role="subsection"><title>dmx_register_demux()</title>
303<para>DESCRIPTION
304</para>
305<informaltable><tgroup cols="1"><tbody><row><entry
306 align="char">
307<para>This function makes a demux driver interface available to the Linux kernel. It is
308 usually called by the init_module() function of the kernel module that contains
309 the demux driver. The caller of this function is responsible for allocating
310 dynamic or static memory for the demux structure and for initializing its fields
311 before calling this function. The memory allocated for the demux structure
312 must not be freed before calling dmx_unregister_demux(),</para>
313</entry>
314 </row></tbody></tgroup></informaltable>
315<para>SYNOPSIS
316</para>
317<informaltable><tgroup cols="1"><tbody><row><entry
318 align="char">
319<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
320</entry>
321 </row></tbody></tgroup></informaltable>
322<para>PARAMETERS
323</para>
324<informaltable><tgroup cols="2"><tbody><row><entry
325 align="char">
326<para>dmx_demux_t*
327 demux</para>
328</entry><entry
329 align="char">
330<para>Pointer to the demux structure.</para>
331</entry>
332 </row></tbody></tgroup></informaltable>
333<para>RETURNS
334</para>
335<informaltable><tgroup cols="2"><tbody><row><entry
336 align="char">
337<para>0</para>
338</entry><entry
339 align="char">
340<para>The function was completed without errors.</para>
341</entry>
342 </row><row><entry
343 align="char">
344<para>-EEXIST</para>
345</entry><entry
346 align="char">
347<para>A demux with the same value of the id field already stored
348 in the directory.</para>
349</entry>
350 </row><row><entry
351 align="char">
352<para>-ENOSPC</para>
353</entry><entry
354 align="char">
355<para>No space left in the directory.</para>
356</entry>
357 </row></tbody></tgroup></informaltable>
358
359</section><section
360role="subsection"><title>dmx_unregister_demux()</title>
361<para>DESCRIPTION
362</para>
363<informaltable><tgroup cols="1"><tbody><row><entry
364 align="char">
365<para>This function is called to indicate that the given demux interface is no
366 longer available. The caller of this function is responsible for freeing the
367 memory of the demux structure, if it was dynamically allocated before calling
368 dmx_register_demux(). The cleanup_module() function of the kernel module
369 that contains the demux driver should call this function. Note that this function
370 fails if the demux is currently in use, i.e., release_demux() has not been called
371 for the interface.</para>
372</entry>
373 </row></tbody></tgroup></informaltable>
374<para>SYNOPSIS
375</para>
376<informaltable><tgroup cols="1"><tbody><row><entry
377 align="char">
378<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
379</entry>
380 </row></tbody></tgroup></informaltable>
381<para>PARAMETERS
382</para>
383<informaltable><tgroup cols="2"><tbody><row><entry
384 align="char">
385<para>dmx_demux_t*
386 demux</para>
387</entry><entry
388 align="char">
389<para>Pointer to the demux structure which is to be
390 unregistered.</para>
391</entry>
392 </row></tbody></tgroup></informaltable>
393<para>RETURNS
394</para>
395<informaltable><tgroup cols="2"><tbody><row><entry
396 align="char">
397<para>0</para>
398</entry><entry
399 align="char">
400<para>The function was completed without errors.</para>
401</entry>
402 </row><row><entry
403 align="char">
404<para>ENODEV</para>
405</entry><entry
406 align="char">
407<para>The specified demux is not registered in the demux
408 directory.</para>
409</entry>
410 </row><row><entry
411 align="char">
412<para>EBUSY</para>
413</entry><entry
414 align="char">
415<para>The specified demux is currently in use.</para>
416</entry>
417 </row></tbody></tgroup></informaltable>
418
419</section><section
420role="subsection"><title>dmx_get_demuxes()</title>
421<para>DESCRIPTION
422</para>
423<informaltable><tgroup cols="1"><tbody><row><entry
424 align="char">
425<para>Provides the caller with the list of registered demux interfaces, using the
426 standard list structure defined in the include file linux/list.h. The include file
427 demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
428 the generic type struct list_head* to the type dmx_demux_t*. The caller must
429 not free the memory of any of the elements obtained via this function call.</para>
430</entry>
431 </row></tbody></tgroup></informaltable>
432<para>SYNOPSIS
433</para>
434<informaltable><tgroup cols="1"><tbody><row><entry
435 align="char">
436<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
437</entry>
438 </row></tbody></tgroup></informaltable>
439<para>PARAMETERS
440</para>
441<informaltable><tgroup cols="2"><tbody><row><entry
442 align="char">
443<para>none</para>
444</entry>
445 </row></tbody></tgroup></informaltable>
446<para>RETURNS
447</para>
448<informaltable><tgroup cols="2"><tbody><row><entry
449 align="char">
450<para>struct list_head *</para>
451</entry><entry
452 align="char">
453<para>A list of demux interfaces, or NULL in the case of an
454 empty list.</para>
455</entry>
456 </row></tbody></tgroup></informaltable>
457 </section></section>
458<section id="demux_api">
459<title>Demux API</title>
460<para>The demux API should be implemented for each demux in the system. It is used to select
461the TS source of a demux and to manage the demux resources. When the demux
462client allocates a resource via the demux API, it receives a pointer to the API of that
463resource.
464</para>
465<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
466demux API. In a system with more than one front-end, the API can be used to select one of
467the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
468demux API only controls front-ends regarding their connections with demuxes; the APIs
469used to set the other front-end parameters, such as tuning, are not defined in this
470document.
471</para>
472<para>The functions that implement the abstract interface demux should be defined static or
473module private and registered to the Demux Directory for external access. It is not necessary
474to implement every function in the demux_t struct, however (for example, a demux interface
475might support Section filtering, but not TS or PES filtering). The API client is expected to
476check the value of any function pointer before calling the function: the value of NULL means
477&#8220;function not available&#8221;.
478</para>
479<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
480update and race condition problems should be addressed, e.g. by protecting parts of code with
481mutexes. This is especially important on multi-processor hosts.
482</para>
483<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
484kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
485swapping is needed. For example, the Linux kernel calls the functions of a network device
486interface from a bottom half context. Thus, if a demux API function is called from network
487device code, the function must not sleep.
488</para>
489
490
491<section id="kdapi_fopen">
492<title>open()</title>
493<para>DESCRIPTION
494</para>
495<informaltable><tgroup cols="1"><tbody><row><entry
496 align="char">
497<para>This function reserves the demux for use by the caller and, if necessary,
498 initializes the demux. When the demux is no longer needed, the function close()
499 should be called. It should be possible for multiple clients to access the demux
500 at the same time. Thus, the function implementation should increment the
501 demux usage count when open() is called and decrement it when close() is
502 called.</para>
503</entry>
504 </row></tbody></tgroup></informaltable>
505<para>SYNOPSIS
506</para>
507<informaltable><tgroup cols="1"><tbody><row><entry
508 align="char">
509<para>int open ( demux_t&#x22C6; demux );</para>
510</entry>
511 </row></tbody></tgroup></informaltable>
512<para>PARAMETERS
513</para>
514<informaltable><tgroup cols="2"><tbody><row><entry
515 align="char">
516<para>demux_t* demux</para>
517</entry><entry
518 align="char">
519<para>Pointer to the demux API and instance data.</para>
520</entry>
521 </row></tbody></tgroup></informaltable>
522<para>RETURNS
523</para>
524<informaltable><tgroup cols="2"><tbody><row><entry
525 align="char">
526<para>0</para>
527</entry><entry
528 align="char">
529<para>The function was completed without errors.</para>
530</entry>
531 </row><row><entry
532 align="char">
533<para>-EUSERS</para>
534</entry><entry
535 align="char">
536<para>Maximum usage count reached.</para>
537</entry>
538 </row><row><entry
539 align="char">
540<para>-EINVAL</para>
541</entry><entry
542 align="char">
543<para>Bad parameter.</para>
544</entry>
545 </row></tbody></tgroup></informaltable>
546
547</section>
548<section id="kdapi_fclose">
549<title>close()</title>
550<para>DESCRIPTION
551</para>
552<informaltable><tgroup cols="1"><tbody><row><entry
553 align="char">
554<para>This function reserves the demux for use by the caller and, if necessary,
555 initializes the demux. When the demux is no longer needed, the function close()
556 should be called. It should be possible for multiple clients to access the demux
557 at the same time. Thus, the function implementation should increment the
558 demux usage count when open() is called and decrement it when close() is
559 called.</para>
560</entry>
561 </row></tbody></tgroup></informaltable>
562<para>SYNOPSIS
563</para>
564<informaltable><tgroup cols="1"><tbody><row><entry
565 align="char">
566<para>int close(demux_t&#x22C6; demux);</para>
567</entry>
568 </row></tbody></tgroup></informaltable>
569<para>PARAMETERS
570</para>
571<informaltable><tgroup cols="2"><tbody><row><entry
572 align="char">
573<para>demux_t* demux</para>
574</entry><entry
575 align="char">
576<para>Pointer to the demux API and instance data.</para>
577</entry>
578 </row></tbody></tgroup></informaltable>
579<para>RETURNS
580</para>
581<informaltable><tgroup cols="2"><tbody><row><entry
582 align="char">
583<para>0</para>
584</entry><entry
585 align="char">
586<para>The function was completed without errors.</para>
587</entry>
588 </row><row><entry
589 align="char">
590<para>-ENODEV</para>
591</entry><entry
592 align="char">
593<para>The demux was not in use.</para>
594</entry>
595 </row><row><entry
596 align="char">
597<para>-EINVAL</para>
598</entry><entry
599 align="char">
600<para>Bad parameter.</para>
601</entry>
602 </row></tbody></tgroup></informaltable>
603
604</section>
605<section id="kdapi_fwrite">
606<title>write()</title>
607<para>DESCRIPTION
608</para>
609<informaltable><tgroup cols="1"><tbody><row><entry
610 align="char">
611<para>This function provides the demux driver with a memory buffer containing TS
612 packets. Instead of receiving TS packets from the DVB front-end, the demux
613 driver software will read packets from memory. Any clients of this demux
614 with active TS, PES or Section filters will receive filtered data via the Demux
615 callback API (see 0). The function returns when all the data in the buffer has
616 been consumed by the demux. Demux hardware typically cannot read TS from
617 memory. If this is the case, memory-based filtering has to be implemented
618 entirely in software.</para>
619</entry>
620 </row></tbody></tgroup></informaltable>
621<para>SYNOPSIS
622</para>
623<informaltable><tgroup cols="1"><tbody><row><entry
624 align="char">
625<para>int write(demux_t&#x22C6; demux, const char&#x22C6; buf, size_t
626 count);</para>
627</entry>
628 </row></tbody></tgroup></informaltable>
629<para>PARAMETERS
630</para>
631<informaltable><tgroup cols="2"><tbody><row><entry
632 align="char">
633<para>demux_t* demux</para>
634</entry><entry
635 align="char">
636<para>Pointer to the demux API and instance data.</para>
637</entry>
638 </row><row><entry
639 align="char">
640<para>const char* buf</para>
641</entry><entry
642 align="char">
643<para>Pointer to the TS data in kernel-space memory.</para>
644</entry>
645 </row><row><entry
646 align="char">
647<para>size_t length</para>
648</entry><entry
649 align="char">
650<para>Length of the TS data.</para>
651</entry>
652 </row></tbody></tgroup></informaltable>
653<para>RETURNS
654</para>
655<informaltable><tgroup cols="2"><tbody><row><entry
656 align="char">
657<para>0</para>
658</entry><entry
659 align="char">
660<para>The function was completed without errors.</para>
661</entry>
662 </row><row><entry
663 align="char">
664<para>-ENOSYS</para>
665</entry><entry
666 align="char">
667<para>The command is not implemented.</para>
668</entry>
669 </row><row><entry
670 align="char">
671<para>-EINVAL</para>
672</entry><entry
673 align="char">
674<para>Bad parameter.</para>
675</entry>
676 </row></tbody></tgroup></informaltable>
677
678</section><section
679role="subsection"><title>allocate_ts_feed()</title>
680<para>DESCRIPTION
681</para>
682<informaltable><tgroup cols="1"><tbody><row><entry
683 align="char">
684<para>Allocates a new TS feed, which is used to filter the TS packets carrying a
685 certain PID. The TS feed normally corresponds to a hardware PID filter on the
686 demux chip.</para>
687</entry>
688 </row></tbody></tgroup></informaltable>
689<para>SYNOPSIS
690</para>
691<informaltable><tgroup cols="1"><tbody><row><entry
692 align="char">
693<para>int allocate_ts_feed(dmx_demux_t&#x22C6; demux,
694 dmx_ts_feed_t&#x22C6;&#x22C6; feed, dmx_ts_cb callback);</para>
695</entry>
696 </row></tbody></tgroup></informaltable>
697<para>PARAMETERS
698</para>
699<informaltable><tgroup cols="2"><tbody><row><entry
700 align="char">
701<para>demux_t* demux</para>
702</entry><entry
703 align="char">
704<para>Pointer to the demux API and instance data.</para>
705</entry>
706 </row><row><entry
707 align="char">
708<para>dmx_ts_feed_t**
709 feed</para>
710</entry><entry
711 align="char">
712<para>Pointer to the TS feed API and instance data.</para>
713</entry>
714 </row><row><entry
715 align="char">
716<para>dmx_ts_cb callback</para>
717</entry><entry
718 align="char">
719<para>Pointer to the callback function for passing received TS
720 packet</para>
721</entry>
722 </row></tbody></tgroup></informaltable>
723<para>RETURNS
724</para>
725<informaltable><tgroup cols="2"><tbody><row><entry
726 align="char">
727<para>0</para>
728</entry><entry
729 align="char">
730<para>The function was completed without errors.</para>
731</entry>
732 </row><row><entry
733 align="char">
734<para>-EBUSY</para>
735</entry><entry
736 align="char">
737<para>No more TS feeds available.</para>
738</entry>
739 </row><row><entry
740 align="char">
741<para>-ENOSYS</para>
742</entry><entry
743 align="char">
744<para>The command is not implemented.</para>
745</entry>
746 </row><row><entry
747 align="char">
748<para>-EINVAL</para>
749</entry><entry
750 align="char">
751<para>Bad parameter.</para>
752</entry>
753 </row></tbody></tgroup></informaltable>
754
755</section><section
756role="subsection"><title>release_ts_feed()</title>
757<para>DESCRIPTION
758</para>
759<informaltable><tgroup cols="1"><tbody><row><entry
760 align="char">
761<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in
762 progress on the TS feed should be stopped before calling this function.</para>
763</entry>
764 </row></tbody></tgroup></informaltable>
765<para>SYNOPSIS
766</para>
767<informaltable><tgroup cols="1"><tbody><row><entry
768 align="char">
769<para>int release_ts_feed(dmx_demux_t&#x22C6; demux,
770 dmx_ts_feed_t&#x22C6; feed);</para>
771</entry>
772 </row></tbody></tgroup></informaltable>
773<para>PARAMETERS
774</para>
775<informaltable><tgroup cols="2"><tbody><row><entry
776 align="char">
777<para>demux_t* demux</para>
778</entry><entry
779 align="char">
780<para>Pointer to the demux API and instance data.</para>
781</entry>
782 </row><row><entry
783 align="char">
784<para>dmx_ts_feed_t* feed</para>
785</entry><entry
786 align="char">
787<para>Pointer to the TS feed API and instance data.</para>
788</entry>
789 </row></tbody></tgroup></informaltable>
790<para>RETURNS
791</para>
792<informaltable><tgroup cols="2"><tbody><row><entry
793 align="char">
794<para>0</para>
795</entry><entry
796 align="char">
797<para>The function was completed without errors.</para>
798</entry>
799 </row><row><entry
800 align="char">
801<para>-EINVAL</para>
802</entry><entry
803 align="char">
804<para>Bad parameter.</para>
805</entry>
806 </row></tbody></tgroup></informaltable>
807
808</section><section
809role="subsection"><title>allocate_section_feed()</title>
810<para>DESCRIPTION
811</para>
812<informaltable><tgroup cols="1"><tbody><row><entry
813 align="char">
814<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving
815 sections. On platforms with hardware support for section filtering, a section
816 feed is directly mapped to the demux HW. On other platforms, TS packets are
817 first PID filtered in hardware and a hardware section filter then emulated in
818 software. The caller obtains an API pointer of type dmx_section_feed_t as an
819 out parameter. Using this API the caller can set filtering parameters and start
820 receiving sections.</para>
821</entry>
822 </row></tbody></tgroup></informaltable>
823<para>SYNOPSIS
824</para>
825<informaltable><tgroup cols="1"><tbody><row><entry
826 align="char">
827<para>int allocate_section_feed(dmx_demux_t&#x22C6; demux,
828 dmx_section_feed_t &#x22C6;&#x22C6;feed, dmx_section_cb callback);</para>
829</entry>
830 </row></tbody></tgroup></informaltable>
831<para>PARAMETERS
832</para>
833<informaltable><tgroup cols="2"><tbody><row><entry
834 align="char">
835<para>demux_t *demux</para>
836</entry><entry
837 align="char">
838<para>Pointer to the demux API and instance data.</para>
839</entry>
840 </row><row><entry
841 align="char">
842<para>dmx_section_feed_t
843 **feed</para>
844</entry><entry
845 align="char">
846<para>Pointer to the section feed API and instance data.</para>
847</entry>
848 </row><row><entry
849 align="char">
850<para>dmx_section_cb
851 callback</para>
852</entry><entry
853 align="char">
854<para>Pointer to the callback function for passing received
855 sections.</para>
856</entry>
857 </row></tbody></tgroup></informaltable>
858<para>RETURNS
859</para>
860<informaltable><tgroup cols="2"><tbody><row><entry
861 align="char">
862<para>0</para>
863</entry><entry
864 align="char">
865<para>The function was completed without errors.</para>
866</entry>
867 </row><row><entry
868 align="char">
869<para>-EBUSY</para>
870</entry><entry
871 align="char">
872<para>No more section feeds available.</para>
873</entry>
874 </row><row><entry
875 align="char">
876<para>-ENOSYS</para>
877</entry><entry
878 align="char">
879<para>The command is not implemented.</para>
880</entry>
881 </row><row><entry
882 align="char">
883<para>-EINVAL</para>
884</entry><entry
885 align="char">
886<para>Bad parameter.</para>
887</entry>
888 </row></tbody></tgroup></informaltable>
889
890</section><section
891role="subsection"><title>release_section_feed()</title>
892<para>DESCRIPTION
893</para>
894<informaltable><tgroup cols="1"><tbody><row><entry
895 align="char">
896<para>Releases the resources allocated with allocate_section_feed(), including
897 allocated filters. Any filtering in progress on the section feed should be stopped
898 before calling this function.</para>
899</entry>
900 </row></tbody></tgroup></informaltable>
901<para>SYNOPSIS
902</para>
903<informaltable><tgroup cols="1"><tbody><row><entry
904 align="char">
905<para>int release_section_feed(dmx_demux_t&#x22C6; demux,
906 dmx_section_feed_t &#x22C6;feed);</para>
907</entry>
908 </row></tbody></tgroup></informaltable>
909<para>PARAMETERS
910</para>
911<informaltable><tgroup cols="2"><tbody><row><entry
912 align="char">
913<para>demux_t *demux</para>
914</entry><entry
915 align="char">
916<para>Pointer to the demux API and instance data.</para>
917</entry>
918 </row><row><entry
919 align="char">
920<para>dmx_section_feed_t
921 *feed</para>
922</entry><entry
923 align="char">
924<para>Pointer to the section feed API and instance data.</para>
925</entry>
926 </row></tbody></tgroup></informaltable>
927<para>RETURNS
928</para>
929<informaltable><tgroup cols="2"><tbody><row><entry
930 align="char">
931<para>0</para>
932</entry><entry
933 align="char">
934<para>The function was completed without errors.</para>
935</entry>
936 </row><row><entry
937 align="char">
938<para>-EINVAL</para>
939</entry><entry
940 align="char">
941<para>Bad parameter.</para>
942</entry>
943 </row></tbody></tgroup></informaltable>
944
945</section><section
946role="subsection"><title>descramble_mac_address()</title>
947<para>DESCRIPTION
948</para>
949<informaltable><tgroup cols="1"><tbody><row><entry
950 align="char">
951<para>This function runs a descrambling algorithm on the destination MAC
952 address field of a DVB Datagram Section, replacing the original address
953 with its un-encrypted version. Otherwise, the description on the function
954 descramble_section_payload() applies also to this function.</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957<para>SYNOPSIS
958</para>
959<informaltable><tgroup cols="1"><tbody><row><entry
960 align="char">
961<para>int descramble_mac_address(dmx_demux_t&#x22C6; demux, __u8
962 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
963 size_t buffer2_length, __u16 pid);</para>
964</entry>
965 </row></tbody></tgroup></informaltable>
966<para>PARAMETERS
967</para>
968<informaltable><tgroup cols="2"><tbody><row><entry
969 align="char">
970<para>dmx_demux_t
971 *demux</para>
972</entry><entry
973 align="char">
974<para>Pointer to the demux API and instance data.</para>
975</entry>
976 </row><row><entry
977 align="char">
978<para>__u8 *buffer1</para>
979</entry><entry
980 align="char">
981<para>Pointer to the first byte of the section.</para>
982</entry>
983 </row><row><entry
984 align="char">
985<para>size_t buffer1_length</para>
986</entry><entry
987 align="char">
988<para>Length of the section data, including headers and CRC,
989 in buffer1.</para>
990</entry>
991 </row><row><entry
992 align="char">
993<para>__u8* buffer2</para>
994</entry><entry
995 align="char">
996<para>Pointer to the tail of the section data, or NULL. The
997 pointer has a non-NULL value if the section wraps past
998 the end of a circular buffer.</para>
999</entry>
1000 </row><row><entry
1001 align="char">
1002<para>size_t buffer2_length</para>
1003</entry><entry
1004 align="char">
1005<para>Length of the section data, including headers and CRC,
1006 in buffer2.</para>
1007</entry>
1008 </row><row><entry
1009 align="char">
1010<para>__u16 pid</para>
1011</entry><entry
1012 align="char">
1013<para>The PID on which the section was received. Useful
1014 for obtaining the descrambling key, e.g. from a DVB
1015 Common Access facility.</para>
1016</entry>
1017 </row></tbody></tgroup></informaltable>
1018<para>RETURNS
1019</para>
1020<informaltable><tgroup cols="2"><tbody><row><entry
1021 align="char">
1022<para>0</para>
1023</entry><entry
1024 align="char">
1025<para>The function was completed without errors.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>-ENOSYS</para>
1030</entry><entry
1031 align="char">
1032<para>No descrambling facility available.</para>
1033</entry>
1034 </row><row><entry
1035 align="char">
1036<para>-EINVAL</para>
1037</entry><entry
1038 align="char">
1039<para>Bad parameter.</para>
1040</entry>
1041 </row></tbody></tgroup></informaltable>
1042
1043</section><section
1044role="subsection"><title>descramble_section_payload()</title>
1045<para>DESCRIPTION
1046</para>
1047<informaltable><tgroup cols="1"><tbody><row><entry
1048 align="char">
1049<para>This function runs a descrambling algorithm on the payload of a DVB
1050 Datagram Section, replacing the original payload with its un-encrypted
1051 version. The function will be called from the demux API implementation;
1052 the API client need not call this function directly. Section-level scrambling
1053 algorithms are currently standardized only for DVB-RCC (return channel
1054 over 2-directional cable TV network) systems. For all other DVB networks,
1055 encryption schemes are likely to be proprietary to each data broadcaster. Thus,
1056 it is expected that this function pointer will have the value of NULL (i.e.,
1057 function not available) in most demux API implementations. Nevertheless, it
1058 should be possible to use the function pointer as a hook for dynamically adding
1059 a &#8220;plug-in&#8221; descrambling facility to a demux driver.</para>
1060</entry>
1061 </row><row><entry
1062 align="char">
1063<para>While this function is not needed with hardware-based section descrambling,
1064 the descramble_section_payload function pointer can be used to override the
1065 default hardware-based descrambling algorithm: if the function pointer has a
1066 non-NULL value, the corresponding function should be used instead of any
1067 descrambling hardware.</para>
1068</entry>
1069 </row></tbody></tgroup></informaltable>
1070<para>SYNOPSIS
1071</para>
1072<informaltable><tgroup cols="1"><tbody><row><entry
1073 align="char">
1074<para>int descramble_section_payload(dmx_demux_t&#x22C6; demux,
1075 __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
1076 size_t buffer2_length, __u16 pid);</para>
1077</entry>
1078 </row></tbody></tgroup></informaltable>
1079<para>PARAMETERS
1080</para>
1081<informaltable><tgroup cols="2"><tbody><row><entry
1082 align="char">
1083<para>dmx_demux_t
1084 *demux</para>
1085</entry><entry
1086 align="char">
1087<para>Pointer to the demux API and instance data.</para>
1088</entry>
1089 </row><row><entry
1090 align="char">
1091<para>__u8 *buffer1</para>
1092</entry><entry
1093 align="char">
1094<para>Pointer to the first byte of the section.</para>
1095</entry>
1096 </row><row><entry
1097 align="char">
1098<para>size_t buffer1_length</para>
1099</entry><entry
1100 align="char">
1101<para>Length of the section data, including headers and CRC,
1102 in buffer1.</para>
1103</entry>
1104 </row><row><entry
1105 align="char">
1106<para>__u8 *buffer2</para>
1107</entry><entry
1108 align="char">
1109<para>Pointer to the tail of the section data, or NULL. The
1110 pointer has a non-NULL value if the section wraps past
1111 the end of a circular buffer.</para>
1112</entry>
1113 </row><row><entry
1114 align="char">
1115<para>size_t buffer2_length</para>
1116</entry><entry
1117 align="char">
1118<para>Length of the section data, including headers and CRC,
1119 in buffer2.</para>
1120</entry>
1121 </row><row><entry
1122 align="char">
1123<para>__u16 pid</para>
1124</entry><entry
1125 align="char">
1126<para>The PID on which the section was received. Useful
1127 for obtaining the descrambling key, e.g. from a DVB
1128 Common Access facility.</para>
1129</entry>
1130 </row></tbody></tgroup></informaltable>
1131<para>RETURNS
1132</para>
1133<informaltable><tgroup cols="2"><tbody><row><entry
1134 align="char">
1135<para>0</para>
1136</entry><entry
1137 align="char">
1138<para>The function was completed without errors.</para>
1139</entry>
1140 </row><row><entry
1141 align="char">
1142<para>-ENOSYS</para>
1143</entry><entry
1144 align="char">
1145<para>No descrambling facility available.</para>
1146</entry>
1147 </row><row><entry
1148 align="char">
1149<para>-EINVAL</para>
1150</entry><entry
1151 align="char">
1152<para>Bad parameter.</para>
1153</entry>
1154 </row></tbody></tgroup></informaltable>
1155
1156</section><section
1157role="subsection"><title>add_frontend()</title>
1158<para>DESCRIPTION
1159</para>
1160<informaltable><tgroup cols="1"><tbody><row><entry
1161 align="char">
1162<para>Registers a connectivity between a demux and a front-end, i.e., indicates that
1163 the demux can be connected via a call to connect_frontend() to use the given
1164 front-end as a TS source. The client of this function has to allocate dynamic or
1165 static memory for the frontend structure and initialize its fields before calling
1166 this function. This function is normally called during the driver initialization.
1167 The caller must not free the memory of the frontend struct before successfully
1168 calling remove_frontend().</para>
1169</entry>
1170 </row></tbody></tgroup></informaltable>
1171<para>SYNOPSIS
1172</para>
1173<informaltable><tgroup cols="1"><tbody><row><entry
1174 align="char">
1175<para>int add_frontend(dmx_demux_t &#x22C6;demux, dmx_frontend_t
1176 &#x22C6;frontend);</para>
1177</entry>
1178 </row></tbody></tgroup></informaltable>
1179<para>PARAMETERS
1180</para>
1181<informaltable><tgroup cols="2"><tbody><row><entry
1182 align="char">
1183<para>dmx_demux_t*
1184 demux</para>
1185</entry><entry
1186 align="char">
1187<para>Pointer to the demux API and instance data.</para>
1188</entry>
1189 </row><row><entry
1190 align="char">
1191<para>dmx_frontend_t*
1192 frontend</para>
1193</entry><entry
1194 align="char">
1195<para>Pointer to the front-end instance data.</para>
1196</entry>
1197 </row></tbody></tgroup></informaltable>
1198<para>RETURNS
1199</para>
1200<informaltable><tgroup cols="2"><tbody><row><entry
1201 align="char">
1202<para>0</para>
1203</entry><entry
1204 align="char">
1205<para>The function was completed without errors.</para>
1206</entry>
1207 </row><row><entry
1208 align="char">
1209<para>-EEXIST</para>
1210</entry><entry
1211 align="char">
1212<para>A front-end with the same value of the id field already
1213 registered.</para>
1214</entry>
1215 </row><row><entry
1216 align="char">
1217<para>-EINUSE</para>
1218</entry><entry
1219 align="char">
1220<para>The demux is in use.</para>
1221</entry>
1222 </row><row><entry
1223 align="char">
1224<para>-ENOMEM</para>
1225</entry><entry
1226 align="char">
1227<para>No more front-ends can be added.</para>
1228</entry>
1229 </row><row><entry
1230 align="char">
1231<para>-EINVAL</para>
1232</entry><entry
1233 align="char">
1234<para>Bad parameter.</para>
1235</entry>
1236 </row></tbody></tgroup></informaltable>
1237
1238</section><section
1239role="subsection"><title>remove_frontend()</title>
1240<para>DESCRIPTION
1241</para>
1242<informaltable><tgroup cols="1"><tbody><row><entry
1243 align="char">
1244<para>Indicates that the given front-end, registered by a call to add_frontend(), can
1245 no longer be connected as a TS source by this demux. The function should be
1246 called when a front-end driver or a demux driver is removed from the system.
1247 If the front-end is in use, the function fails with the return value of -EBUSY.
1248 After successfully calling this function, the caller can free the memory of
1249 the frontend struct if it was dynamically allocated before the add_frontend()
1250 operation.</para>
1251</entry>
1252 </row></tbody></tgroup></informaltable>
1253<para>SYNOPSIS
1254</para>
1255<informaltable><tgroup cols="1"><tbody><row><entry
1256 align="char">
1257<para>int remove_frontend(dmx_demux_t&#x22C6; demux,
1258 dmx_frontend_t&#x22C6; frontend);</para>
1259</entry>
1260 </row></tbody></tgroup></informaltable>
1261<para>PARAMETERS
1262</para>
1263<informaltable><tgroup cols="2"><tbody><row><entry
1264 align="char">
1265<para>dmx_demux_t*
1266 demux</para>
1267</entry><entry
1268 align="char">
1269<para>Pointer to the demux API and instance data.</para>
1270</entry>
1271 </row><row><entry
1272 align="char">
1273<para>dmx_frontend_t*
1274 frontend</para>
1275</entry><entry
1276 align="char">
1277<para>Pointer to the front-end instance data.</para>
1278</entry>
1279 </row></tbody></tgroup></informaltable>
1280<para>RETURNS
1281</para>
1282<informaltable><tgroup cols="2"><tbody><row><entry
1283 align="char">
1284<para>0</para>
1285</entry><entry
1286 align="char">
1287<para>The function was completed without errors.</para>
1288</entry>
1289 </row><row><entry
1290 align="char">
1291<para>-EINVAL</para>
1292</entry><entry
1293 align="char">
1294<para>Bad parameter.</para>
1295</entry>
1296 </row><row><entry
1297 align="char">
1298<para>-EBUSY</para>
1299</entry><entry
1300 align="char">
1301<para>The front-end is in use, i.e. a call to connect_frontend()
1302 has not been followed by a call to disconnect_frontend().</para>
1303</entry>
1304 </row></tbody></tgroup></informaltable>
1305
1306</section><section
1307role="subsection"><title>get_frontends()</title>
1308<para>DESCRIPTION
1309</para>
1310<informaltable><tgroup cols="1"><tbody><row><entry
1311 align="char">
1312<para>Provides the APIs of the front-ends that have been registered for this demux.
1313 Any of the front-ends obtained with this call can be used as a parameter for
1314 connect_frontend().</para>
1315</entry>
1316 </row><row><entry
1317 align="char">
1318<para>The include file demux.h contains the macro DMX_FE_ENTRY() for
1319 converting an element of the generic type struct list_head* to the type
1320 dmx_frontend_t*. The caller must not free the memory of any of the elements
1321 obtained via this function call.</para>
1322</entry>
1323 </row></tbody></tgroup></informaltable>
1324<para>SYNOPSIS
1325</para>
1326<informaltable><tgroup cols="1"><tbody><row><entry
1327 align="char">
1328<para>struct list_head&#x22C6; get_frontends(dmx_demux_t&#x22C6; demux);</para>
1329</entry>
1330 </row></tbody></tgroup></informaltable>
1331<para>PARAMETERS
1332</para>
1333<informaltable><tgroup cols="2"><tbody><row><entry
1334 align="char">
1335<para>dmx_demux_t*
1336 demux</para>
1337</entry><entry
1338 align="char">
1339<para>Pointer to the demux API and instance data.</para>
1340</entry>
1341 </row></tbody></tgroup></informaltable>
1342<para>RETURNS
1343</para>
1344<informaltable><tgroup cols="2"><tbody><row><entry
1345 align="char">
1346<para>dmx_demux_t*</para>
1347</entry><entry
1348 align="char">
1349<para>A list of front-end interfaces, or NULL in the case of an
1350 empty list.</para>
1351</entry>
1352 </row></tbody></tgroup></informaltable>
1353
1354</section><section
1355role="subsection"><title>connect_frontend()</title>
1356<para>DESCRIPTION
1357</para>
1358<informaltable><tgroup cols="1"><tbody><row><entry
1359 align="char">
1360<para>Connects the TS output of the front-end to the input of the demux. A demux
1361 can only be connected to a front-end registered to the demux with the function
1362 add_frontend().</para>
1363</entry>
1364 </row><row><entry
1365 align="char">
1366<para>It may or may not be possible to connect multiple demuxes to the same
1367 front-end, depending on the capabilities of the HW platform. When not used,
1368 the front-end should be released by calling disconnect_frontend().</para>
1369</entry>
1370 </row></tbody></tgroup></informaltable>
1371<para>SYNOPSIS
1372</para>
1373<informaltable><tgroup cols="1"><tbody><row><entry
1374 align="char">
1375<para>int connect_frontend(dmx_demux_t&#x22C6; demux,
1376 dmx_frontend_t&#x22C6; frontend);</para>
1377</entry>
1378 </row></tbody></tgroup></informaltable>
1379<para>PARAMETERS
1380</para>
1381<informaltable><tgroup cols="2"><tbody><row><entry
1382 align="char">
1383<para>dmx_demux_t*
1384 demux</para>
1385</entry><entry
1386 align="char">
1387<para>Pointer to the demux API and instance data.</para>
1388</entry>
1389 </row><row><entry
1390 align="char">
1391<para>dmx_frontend_t*
1392 frontend</para>
1393</entry><entry
1394 align="char">
1395<para>Pointer to the front-end instance data.</para>
1396</entry>
1397 </row></tbody></tgroup></informaltable>
1398<para>RETURNS
1399</para>
1400<informaltable><tgroup cols="2"><tbody><row><entry
1401 align="char">
1402<para>0</para>
1403</entry><entry
1404 align="char">
1405<para>The function was completed without errors.</para>
1406</entry>
1407 </row><row><entry
1408 align="char">
1409<para>-EINVAL</para>
1410</entry><entry
1411 align="char">
1412<para>Bad parameter.</para>
1413</entry>
1414 </row><row><entry
1415 align="char">
1416<para>-EBUSY</para>
1417</entry><entry
1418 align="char">
1419<para>The front-end is in use.</para>
1420</entry>
1421 </row></tbody></tgroup></informaltable>
1422
1423</section><section
1424role="subsection"><title>disconnect_frontend()</title>
1425<para>DESCRIPTION
1426</para>
1427<informaltable><tgroup cols="1"><tbody><row><entry
1428 align="char">
1429<para>Disconnects the demux and a front-end previously connected by a
1430 connect_frontend() call.</para>
1431</entry>
1432 </row></tbody></tgroup></informaltable>
1433<para>SYNOPSIS
1434</para>
1435<informaltable><tgroup cols="1"><tbody><row><entry
1436 align="char">
1437<para>int disconnect_frontend(dmx_demux_t&#x22C6; demux);</para>
1438</entry>
1439 </row></tbody></tgroup></informaltable>
1440<para>PARAMETERS
1441</para>
1442<informaltable><tgroup cols="2"><tbody><row><entry
1443 align="char">
1444<para>dmx_demux_t*
1445 demux</para>
1446</entry><entry
1447 align="char">
1448<para>Pointer to the demux API and instance data.</para>
1449</entry>
1450 </row></tbody></tgroup></informaltable>
1451<para>RETURNS
1452</para>
1453<informaltable><tgroup cols="2"><tbody><row><entry
1454 align="char">
1455<para>0</para>
1456</entry><entry
1457 align="char">
1458<para>The function was completed without errors.</para>
1459</entry>
1460 </row><row><entry
1461 align="char">
1462<para>-EINVAL</para>
1463</entry><entry
1464 align="char">
1465<para>Bad parameter.</para>
1466</entry>
1467 </row></tbody></tgroup></informaltable>
1468 </section></section>
1469<section id="demux_callback_api">
1470<title>Demux Callback API</title>
1471<para>This kernel-space API comprises the callback functions that deliver filtered data to the
1472demux client. Unlike the other APIs, these API functions are provided by the client and called
1473from the demux code.
1474</para>
1475<para>The function pointers of this abstract interface are not packed into a structure as in the
1476other demux APIs, because the callback functions are registered and used independent
1477of each other. As an example, it is possible for the API client to provide several
1478callback functions for receiving TS packets and no callbacks for PES packets or
1479sections.
1480</para>
1481<para>The functions that implement the callback API need not be re-entrant: when a demux
1482driver calls one of these functions, the driver is not allowed to call the function again before
1483the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
1484to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
1485function call directly from a hardware interrupt.
1486</para>
1487
1488<section
1489role="subsection"><title>dmx_ts_cb()</title>
1490<para>DESCRIPTION
1491</para>
1492<informaltable><tgroup cols="1"><tbody><row><entry
1493 align="char">
1494<para>This function, provided by the client of the demux API, is called from the
1495 demux code. The function is only called when filtering on this TS feed has
1496 been enabled using the start_filtering() function.</para>
1497</entry>
1498 </row><row><entry
1499 align="char">
1500<para>Any TS packets that match the filter settings are copied to a circular buffer. The
1501 filtered TS packets are delivered to the client using this callback function. The
1502 size of the circular buffer is controlled by the circular_buffer_size parameter
1503 of the set() function in the TS Feed API. It is expected that the buffer1 and
1504 buffer2 callback parameters point to addresses within the circular buffer, but
1505 other implementations are also possible. Note that the called party should not
1506 try to free the memory the buffer1 and buffer2 parameters point to.</para>
1507</entry>
1508 </row><row><entry
1509 align="char">
1510<para>When this function is called, the buffer1 parameter typically points to the
1511 start of the first undelivered TS packet within a circular buffer. The buffer2
1512 buffer parameter is normally NULL, except when the received TS packets have
1513 crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
1514 of the buffer. In the latter case the buffer1 parameter would contain an address
1515 within the circular buffer, while the buffer2 parameter would contain the first
1516 address of the circular buffer.</para>
1517</entry>
1518 </row><row><entry
1519 align="char">
1520<para>The number of bytes delivered with this function (i.e. buffer1_length +
1521 buffer2_length) is usually equal to the value of callback_length parameter
1522 given in the set() function, with one exception: if a timeout occurs before
1523 receiving callback_length bytes of TS data, any undelivered packets are
1524 immediately delivered to the client by calling this function. The timeout
1525 duration is controlled by the set() function in the TS Feed API.</para>
1526</entry>
1527 </row><row><entry
1528 align="char">
1529<para>If a TS packet is received with errors that could not be fixed by the TS-level
1530 forward error correction (FEC), the Transport_error_indicator flag of the TS
1531 packet header should be set. The TS packet should not be discarded, as
1532 the error can possibly be corrected by a higher layer protocol. If the called
1533 party is slow in processing the callback, it is possible that the circular buffer
1534 eventually fills up. If this happens, the demux driver should discard any TS
1535 packets received while the buffer is full. The error should be indicated to the
1536 client on the next callback by setting the success parameter to the value of
1537 DMX_OVERRUN_ERROR.</para>
1538</entry>
1539 </row><row><entry
1540 align="char">
1541<para>The type of data returned to the callback can be selected by the new
1542 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
1543 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
1544 include file ost/demux.h) The type parameter decides if the raw TS packet
1545 (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
1546 should be returned. If additionally the TS_DECODER bit is set the stream
1547 will also be sent to the hardware MPEG decoder. In this case, the second
1548 flag decides as what kind of data the stream should be interpreted. The
1549 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
1550 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
1551 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
1552</entry>
1553 </row></tbody></tgroup></informaltable>
1554<para>SYNOPSIS
1555</para>
1556<informaltable><tgroup cols="1"><tbody><row><entry
1557 align="char">
1558<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
1559 __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
1560 source, dmx_success_t success);</para>
1561</entry>
1562 </row></tbody></tgroup></informaltable>
1563<para>PARAMETERS
1564</para>
1565<informaltable><tgroup cols="2"><tbody><row><entry
1566 align="char">
1567<para>__u8* buffer1</para>
1568</entry><entry
1569 align="char">
1570<para>Pointer to the start of the filtered TS packets.</para>
1571</entry>
1572 </row><row><entry
1573 align="char">
1574<para>size_t buffer1_length</para>
1575</entry><entry
1576 align="char">
1577<para>Length of the TS data in buffer1.</para>
1578</entry>
1579 </row><row><entry
1580 align="char">
1581<para>__u8* buffer2</para>
1582</entry><entry
1583 align="char">
1584<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
1585</entry>
1586 </row><row><entry
1587 align="char">
1588<para>size_t buffer2_length</para>
1589</entry><entry
1590 align="char">
1591<para>Length of the TS data in buffer2.</para>
1592</entry>
1593 </row><row><entry
1594 align="char">
1595<para>dmx_ts_feed_t*
1596 source</para>
1597</entry><entry
1598 align="char">
1599<para>Indicates which TS feed is the source of the callback.</para>
1600</entry>
1601 </row><row><entry
1602 align="char">
1603<para>dmx_success_t
1604 success</para>
1605</entry><entry
1606 align="char">
1607<para>Indicates if there was an error in TS reception.</para>
1608</entry>
1609 </row></tbody></tgroup></informaltable>
1610<para>RETURNS
1611</para>
1612<informaltable><tgroup cols="2"><tbody><row><entry
1613 align="char">
1614<para>0</para>
1615</entry><entry
1616 align="char">
1617<para>Continue filtering.</para>
1618</entry>
1619 </row><row><entry
1620 align="char">
1621<para>-1</para>
1622</entry><entry
1623 align="char">
1624<para>Stop filtering - has the same effect as a call to
1625 stop_filtering() on the TS Feed API.</para>
1626</entry>
1627 </row></tbody></tgroup></informaltable>
1628
1629</section><section
1630role="subsection"><title>dmx_section_cb()</title>
1631<para>DESCRIPTION
1632</para>
1633<informaltable><tgroup cols="1"><tbody><row><entry
1634 align="char">
1635<para>This function, provided by the client of the demux API, is called from the
1636 demux code. The function is only called when filtering of sections has been
1637 enabled using the function start_filtering() of the section feed API. When the
1638 demux driver has received a complete section that matches at least one section
1639 filter, the client is notified via this callback function. Normally this function is
1640 called for each received section; however, it is also possible to deliver multiple
1641 sections with one callback, for example when the system load is high. If an
1642 error occurs while receiving a section, this function should be called with
1643 the corresponding error type set in the success field, whether or not there is
1644 data to deliver. The Section Feed implementation should maintain a circular
1645 buffer for received sections. However, this is not necessary if the Section Feed
1646 API is implemented as a client of the TS Feed API, because the TS Feed
1647 implementation then buffers the received data. The size of the circular buffer
1648 can be configured using the set() function in the Section Feed API. If there
1649 is no room in the circular buffer when a new section is received, the section
1650 must be discarded. If this happens, the value of the success parameter should
1651 be DMX_OVERRUN_ERROR on the next callback.</para>
1652</entry>
1653 </row></tbody></tgroup></informaltable>
1654<para>SYNOPSIS
1655</para>
1656<informaltable><tgroup cols="1"><tbody><row><entry
1657 align="char">
1658<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
1659 buffer1_length, __u8&#x22C6; buffer2, size_t
1660 buffer2_length, dmx_section_filter_t&#x22C6; source,
1661 dmx_success_t success);</para>
1662</entry>
1663 </row></tbody></tgroup></informaltable>
1664<para>PARAMETERS
1665</para>
1666<informaltable><tgroup cols="2"><tbody><row><entry
1667 align="char">
1668<para>__u8* buffer1</para>
1669</entry><entry
1670 align="char">
1671<para>Pointer to the start of the filtered section, e.g. within the
1672 circular buffer of the demux driver.</para>
1673</entry>
1674 </row><row><entry
1675 align="char">
1676<para>size_t buffer1_length</para>
1677</entry><entry
1678 align="char">
1679<para>Length of the filtered section data in buffer1, including
1680 headers and CRC.</para>
1681</entry>
1682 </row><row><entry
1683 align="char">
1684<para>__u8* buffer2</para>
1685</entry><entry
1686 align="char">
1687<para>Pointer to the tail of the filtered section data, or NULL.
1688 Useful to handle the wrapping of a circular buffer.</para>
1689</entry>
1690 </row><row><entry
1691 align="char">
1692<para>size_t buffer2_length</para>
1693</entry><entry
1694 align="char">
1695<para>Length of the filtered section data in buffer2, including
1696 headers and CRC.</para>
1697</entry>
1698 </row><row><entry
1699 align="char">
1700<para>dmx_section_filter_t*
1701 filter</para>
1702</entry><entry
1703 align="char">
1704<para>Indicates the filter that triggered the callback.</para>
1705</entry>
1706 </row><row><entry
1707 align="char">
1708<para>dmx_success_t
1709 success</para>
1710</entry><entry
1711 align="char">
1712<para>Indicates if there was an error in section reception.</para>
1713</entry>
1714 </row></tbody></tgroup></informaltable>
1715<para>RETURNS
1716</para>
1717<informaltable><tgroup cols="2"><tbody><row><entry
1718 align="char">
1719<para>0</para>
1720</entry><entry
1721 align="char">
1722<para>Continue filtering.</para>
1723</entry>
1724 </row><row><entry
1725 align="char">
1726<para>-1</para>
1727</entry><entry
1728 align="char">
1729<para>Stop filtering - has the same effect as a call to
1730 stop_filtering() on the Section Feed API.</para>
1731</entry>
1732 </row></tbody></tgroup></informaltable>
1733 </section></section>
1734<section id="ts_feed_api">
1735<title>TS Feed API</title>
1736<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
1737Using this API, the client can set the filtering properties to start/stop filtering TS
1738packets on a particular TS feed. The API is defined as an abstract interface of the type
1739dmx_ts_feed_t.
1740</para>
1741<para>The functions that implement the interface should be defined static or module private. The
1742client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
1743demux API.
1744</para>
1745
1746<section
1747role="subsection"><title>set()</title>
1748<para>DESCRIPTION
1749</para>
1750<informaltable><tgroup cols="1"><tbody><row><entry
1751 align="char">
1752<para>This function sets the parameters of a TS feed. Any filtering in progress on the
1753 TS feed must be stopped before calling this function.</para>
1754</entry>
1755 </row></tbody></tgroup></informaltable>
1756<para>SYNOPSIS
1757</para>
1758<informaltable><tgroup cols="1"><tbody><row><entry
1759 align="char">
1760<para>int set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
1761 callback_length, size_t circular_buffer_size, int
1762 descramble, struct timespec timeout);</para>
1763</entry>
1764 </row></tbody></tgroup></informaltable>
1765<para>PARAMETERS
1766</para>
1767<informaltable><tgroup cols="2"><tbody><row><entry
1768 align="char">
1769<para>dmx_ts_feed_t* feed</para>
1770</entry><entry
1771 align="char">
1772<para>Pointer to the TS feed API and instance data.</para>
1773</entry>
1774 </row><row><entry
1775 align="char">
1776<para>__u16 pid</para>
1777</entry><entry
1778 align="char">
1779<para>PID value to filter. Only the TS packets carrying the
1780 specified PID will be passed to the API client.</para>
1781</entry>
1782 </row><row><entry
1783 align="char">
1784<para>size_t
1785 callback_length</para>
1786</entry><entry
1787 align="char">
1788<para>Number of bytes to deliver with each call to the
1789 dmx_ts_cb() callback function. The value of this
1790 parameter should be a multiple of 188.</para>
1791</entry>
1792 </row><row><entry
1793 align="char">
1794<para>size_t
1795 circular_buffer_size</para>
1796</entry><entry
1797 align="char">
1798<para>Size of the circular buffer for the filtered TS packets.</para>
1799</entry>
1800 </row><row><entry
1801 align="char">
1802<para>int descramble</para>
1803</entry><entry
1804 align="char">
1805<para>If non-zero, descramble the filtered TS packets.</para>
1806</entry>
1807 </row><row><entry
1808 align="char">
1809<para>struct timespec
1810 timeout</para>
1811</entry><entry
1812 align="char">
1813<para>Maximum time to wait before delivering received TS
1814 packets to the client.</para>
1815</entry>
1816 </row></tbody></tgroup></informaltable>
1817<para>RETURNS
1818</para>
1819<informaltable><tgroup cols="2"><tbody><row><entry
1820 align="char">
1821<para>0</para>
1822</entry><entry
1823 align="char">
1824<para>The function was completed without errors.</para>
1825</entry>
1826 </row><row><entry
1827 align="char">
1828<para>-ENOMEM</para>
1829</entry><entry
1830 align="char">
1831<para>Not enough memory for the requested buffer size.</para>
1832</entry>
1833 </row><row><entry
1834 align="char">
1835<para>-ENOSYS</para>
1836</entry><entry
1837 align="char">
1838<para>No descrambling facility available for TS.</para>
1839</entry>
1840 </row><row><entry
1841 align="char">
1842<para>-EINVAL</para>
1843</entry><entry
1844 align="char">
1845<para>Bad parameter.</para>
1846</entry>
1847 </row></tbody></tgroup></informaltable>
1848
1849</section><section
1850role="subsection"><title>start_filtering()</title>
1851<para>DESCRIPTION
1852</para>
1853<informaltable><tgroup cols="1"><tbody><row><entry
1854 align="char">
1855<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
1856 value to filter can be set by the API client. All matching TS packets are
1857 delivered asynchronously to the client, using the callback function registered
1858 with allocate_ts_feed().</para>
1859</entry>
1860 </row></tbody></tgroup></informaltable>
1861<para>SYNOPSIS
1862</para>
1863<informaltable><tgroup cols="1"><tbody><row><entry
1864 align="char">
1865<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1866</entry>
1867 </row></tbody></tgroup></informaltable>
1868<para>PARAMETERS
1869</para>
1870<informaltable><tgroup cols="2"><tbody><row><entry
1871 align="char">
1872<para>dmx_ts_feed_t* feed</para>
1873</entry><entry
1874 align="char">
1875<para>Pointer to the TS feed API and instance data.</para>
1876</entry>
1877 </row></tbody></tgroup></informaltable>
1878<para>RETURNS
1879</para>
1880<informaltable><tgroup cols="2"><tbody><row><entry
1881 align="char">
1882<para>0</para>
1883</entry><entry
1884 align="char">
1885<para>The function was completed without errors.</para>
1886</entry>
1887 </row><row><entry
1888 align="char">
1889<para>-EINVAL</para>
1890</entry><entry
1891 align="char">
1892<para>Bad parameter.</para>
1893</entry>
1894 </row></tbody></tgroup></informaltable>
1895
1896</section><section
1897role="subsection"><title>stop_filtering()</title>
1898<para>DESCRIPTION
1899</para>
1900<informaltable><tgroup cols="1"><tbody><row><entry
1901 align="char">
1902<para>Stops filtering TS packets on this TS feed.</para>
1903</entry>
1904 </row></tbody></tgroup></informaltable>
1905<para>SYNOPSIS
1906</para>
1907<informaltable><tgroup cols="1"><tbody><row><entry
1908 align="char">
1909<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1910</entry>
1911 </row></tbody></tgroup></informaltable>
1912<para>PARAMETERS
1913</para>
1914<informaltable><tgroup cols="2"><tbody><row><entry
1915 align="char">
1916<para>dmx_ts_feed_t* feed</para>
1917</entry><entry
1918 align="char">
1919<para>Pointer to the TS feed API and instance data.</para>
1920</entry>
1921 </row></tbody></tgroup></informaltable>
1922<para>RETURNS
1923</para>
1924<informaltable><tgroup cols="2"><tbody><row><entry
1925 align="char">
1926<para>0</para>
1927</entry><entry
1928 align="char">
1929<para>The function was completed without errors.</para>
1930</entry>
1931 </row><row><entry
1932 align="char">
1933<para>-EINVAL</para>
1934</entry><entry
1935 align="char">
1936<para>Bad parameter.</para>
1937</entry>
1938 </row></tbody></tgroup></informaltable>
1939 </section></section>
1940<section id="section_feed_api">
1941<title>Section Feed API</title>
1942<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
1943API, the client can set the properties of a section feed and to start/stop filtering. The API is
1944defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
1945the interface should be defined static or module private. The client can get the handle of
1946a section feed API by calling the function allocate_section_feed() in the demux
1947API.
1948</para>
1949<para>On demux platforms that provide section filtering in hardware, the Section Feed API
1950implementation provides a software wrapper for the demux hardware. Other platforms may
1951support only PID filtering in hardware, requiring that TS packets are converted to sections in
1952software. In the latter case the Section Feed API implementation can be a client of the TS
1953Feed API.
1954</para>
1955
1956</section>
1957<section id="kdapi_set">
1958<title>set()</title>
1959<para>DESCRIPTION
1960</para>
1961<informaltable><tgroup cols="1"><tbody><row><entry
1962 align="char">
1963<para>This function sets the parameters of a section feed. Any filtering in progress on
1964 the section feed must be stopped before calling this function. If descrambling
1965 is enabled, the payload_scrambling_control and address_scrambling_control
1966 fields of received DVB datagram sections should be observed. If either one is
1967 non-zero, the section should be descrambled either in hardware or using the
1968 functions descramble_mac_address() and descramble_section_payload() of the
1969 demux API. Note that according to the MPEG-2 Systems specification, only
1970 the payloads of private sections can be scrambled while the rest of the section
1971 data must be sent in the clear.</para>
1972</entry>
1973 </row></tbody></tgroup></informaltable>
1974<para>SYNOPSIS
1975</para>
1976<informaltable><tgroup cols="1"><tbody><row><entry
1977 align="char">
1978<para>int set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
1979 circular_buffer_size, int descramble, int
1980 check_crc);</para>
1981</entry>
1982 </row></tbody></tgroup></informaltable>
1983<para>PARAMETERS
1984</para>
1985<informaltable><tgroup cols="2"><tbody><row><entry
1986 align="char">
1987<para>dmx_section_feed_t*
1988 feed</para>
1989</entry><entry
1990 align="char">
1991<para>Pointer to the section feed API and instance data.</para>
1992</entry>
1993 </row><row><entry
1994 align="char">
1995<para>__u16 pid</para>
1996</entry><entry
1997 align="char">
1998<para>PID value to filter; only the TS packets carrying the
1999 specified PID will be accepted.</para>
2000</entry>
2001 </row><row><entry
2002 align="char">
2003<para>size_t
2004 circular_buffer_size</para>
2005</entry><entry
2006 align="char">
2007<para>Size of the circular buffer for filtered sections.</para>
2008</entry>
2009 </row><row><entry
2010 align="char">
2011<para>int descramble</para>
2012</entry><entry
2013 align="char">
2014<para>If non-zero, descramble any sections that are scrambled.</para>
2015</entry>
2016 </row><row><entry
2017 align="char">
2018<para>int check_crc</para>
2019</entry><entry
2020 align="char">
2021<para>If non-zero, check the CRC values of filtered sections.</para>
2022</entry>
2023 </row></tbody></tgroup></informaltable>
2024<para>RETURNS
2025</para>
2026<informaltable><tgroup cols="2"><tbody><row><entry
2027 align="char">
2028<para>0</para>
2029</entry><entry
2030 align="char">
2031<para>The function was completed without errors.</para>
2032</entry>
2033 </row><row><entry
2034 align="char">
2035<para>-ENOMEM</para>
2036</entry><entry
2037 align="char">
2038<para>Not enough memory for the requested buffer size.</para>
2039</entry>
2040 </row><row><entry
2041 align="char">
2042<para>-ENOSYS</para>
2043</entry><entry
2044 align="char">
2045<para>No descrambling facility available for sections.</para>
2046</entry>
2047 </row><row><entry
2048 align="char">
2049<para>-EINVAL</para>
2050</entry><entry
2051 align="char">
2052<para>Bad parameters.</para>
2053</entry>
2054 </row></tbody></tgroup></informaltable>
2055
2056</section><section
2057role="subsection"><title>allocate_filter()</title>
2058<para>DESCRIPTION
2059</para>
2060<informaltable><tgroup cols="1"><tbody><row><entry
2061 align="char">
2062<para>This function is used to allocate a section filter on the demux. It should only be
2063 called when no filtering is in progress on this section feed. If a filter cannot be
2064 allocated, the function fails with -ENOSPC. See in section ?? for the format of
2065 the section filter.</para>
2066</entry>
2067 </row><row><entry
2068 align="char">
2069<para>The bitfields filter_mask and filter_value should only be modified when no
2070 filtering is in progress on this section feed. filter_mask controls which bits of
2071 filter_value are compared with the section headers/payload. On a binary value
2072 of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
2073 sections that are equal to filter_value in all the tested bit positions. Any changes
2074 to the values of filter_mask and filter_value are guaranteed to take effect only
2075 when the start_filtering() function is called next time. The parent pointer in
2076 the struct is initialized by the API implementation to the value of the feed
2077 parameter. The priv pointer is not used by the API implementation, and can
2078 thus be freely utilized by the caller of this function. Any data pointed to by the
2079 priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
2080</entry>
2081 </row><row><entry
2082 align="char">
2083<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
2084 currently set at 16 bytes, hardware filters of that size are not available on all
2085 platforms. Therefore, section filtering will often take place first in hardware,
2086 followed by filtering in software for the header bytes that were not covered
2087 by a hardware filter. The filter_mask field can be checked to determine how
2088 many bytes of the section filter are actually used, and if the hardware filter will
2089 suffice. Additionally, software-only section filters can optionally be allocated
2090 to clients when all hardware section filters are in use. Note that on most demux
2091 hardware it is not possible to filter on the section_length field of the section
2092 header &#8211; thus this field is ignored, even though it is included in filter_value and
2093 filter_mask fields.</para>
2094</entry>
2095 </row></tbody></tgroup></informaltable>
2096<para>SYNOPSIS
2097</para>
2098<informaltable><tgroup cols="1"><tbody><row><entry
2099 align="char">
2100<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
2101 dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
2102</entry>
2103 </row></tbody></tgroup></informaltable>
2104<para>PARAMETERS
2105</para>
2106<informaltable><tgroup cols="2"><tbody><row><entry
2107 align="char">
2108<para>dmx_section_feed_t*
2109 feed</para>
2110</entry><entry
2111 align="char">
2112<para>Pointer to the section feed API and instance data.</para>
2113</entry>
2114 </row><row><entry
2115 align="char">
2116<para>dmx_section_filter_t**
2117 filter</para>
2118</entry><entry
2119 align="char">
2120<para>Pointer to the allocated filter.</para>
2121</entry>
2122 </row></tbody></tgroup></informaltable>
2123<para>RETURNS
2124</para>
2125<informaltable><tgroup cols="2"><tbody><row><entry
2126 align="char">
2127<para>0</para>
2128</entry><entry
2129 align="char">
2130<para>The function was completed without errors.</para>
2131</entry>
2132 </row><row><entry
2133 align="char">
2134<para>-ENOSPC</para>
2135</entry><entry
2136 align="char">
2137<para>No filters of given type and length available.</para>
2138</entry>
2139 </row><row><entry
2140 align="char">
2141<para>-EINVAL</para>
2142</entry><entry
2143 align="char">
2144<para>Bad parameters.</para>
2145</entry>
2146 </row></tbody></tgroup></informaltable>
2147
2148</section><section
2149role="subsection"><title>release_filter()</title>
2150<para>DESCRIPTION
2151</para>
2152<informaltable><tgroup cols="1"><tbody><row><entry
2153 align="char">
2154<para>This function releases all the resources of a previously allocated section filter.
2155 The function should not be called while filtering is in progress on this section
2156 feed. After calling this function, the caller should not try to dereference the
2157 filter pointer.</para>
2158</entry>
2159 </row></tbody></tgroup></informaltable>
2160<para>SYNOPSIS
2161</para>
2162<informaltable><tgroup cols="1"><tbody><row><entry
2163 align="char">
2164<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
2165 dmx_section_filter_t&#x22C6; filter);</para>
2166</entry>
2167 </row></tbody></tgroup></informaltable>
2168<para>PARAMETERS
2169</para>
2170<informaltable><tgroup cols="2"><tbody><row><entry
2171 align="char">
2172<para>dmx_section_feed_t*
2173 feed</para>
2174</entry><entry
2175 align="char">
2176<para>Pointer to the section feed API and instance data.</para>
2177</entry>
2178 </row><row><entry
2179 align="char">
2180<para>dmx_section_filter_t*
2181 filter</para>
2182</entry><entry
2183 align="char">
2184<para>I/O Pointer to the instance data of a section filter.</para>
2185</entry>
2186 </row></tbody></tgroup></informaltable>
2187<para>RETURNS
2188</para>
2189<informaltable><tgroup cols="2"><tbody><row><entry
2190 align="char">
2191<para>0</para>
2192</entry><entry
2193 align="char">
2194<para>The function was completed without errors.</para>
2195</entry>
2196 </row><row><entry
2197 align="char">
2198<para>-ENODEV</para>
2199</entry><entry
2200 align="char">
2201<para>No such filter allocated.</para>
2202</entry>
2203 </row><row><entry
2204 align="char">
2205<para>-EINVAL</para>
2206</entry><entry
2207 align="char">
2208<para>Bad parameter.</para>
2209</entry>
2210 </row></tbody></tgroup></informaltable>
2211
2212</section><section
2213role="subsection"><title>start_filtering()</title>
2214<para>DESCRIPTION
2215</para>
2216<informaltable><tgroup cols="1"><tbody><row><entry
2217 align="char">
2218<para>Starts filtering sections on this section feed, according to its settings. Sections
2219 are first filtered based on their PID and then matched with the section
2220 filters allocated for this feed. If the section matches the PID filter and
2221 at least one section filter, it is delivered to the API client. The section
2222 is delivered asynchronously using the callback function registered with
2223 allocate_section_feed().</para>
2224</entry>
2225 </row></tbody></tgroup></informaltable>
2226<para>SYNOPSIS
2227</para>
2228<informaltable><tgroup cols="1"><tbody><row><entry
2229 align="char">
2230<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2231</entry>
2232 </row></tbody></tgroup></informaltable>
2233<para>PARAMETERS
2234</para>
2235<informaltable><tgroup cols="2"><tbody><row><entry
2236 align="char">
2237<para>dmx_section_feed_t*
2238 feed</para>
2239</entry><entry
2240 align="char">
2241<para>Pointer to the section feed API and instance data.</para>
2242</entry>
2243 </row></tbody></tgroup></informaltable>
2244<para>RETURNS
2245</para>
2246<informaltable><tgroup cols="2"><tbody><row><entry
2247 align="char">
2248<para>0</para>
2249</entry><entry
2250 align="char">
2251<para>The function was completed without errors.</para>
2252</entry>
2253 </row><row><entry
2254 align="char">
2255<para>-EINVAL</para>
2256</entry><entry
2257 align="char">
2258<para>Bad parameter.</para>
2259</entry>
2260 </row></tbody></tgroup></informaltable>
2261
2262</section><section
2263role="subsection"><title>stop_filtering()</title>
2264<para>DESCRIPTION
2265</para>
2266<informaltable><tgroup cols="1"><tbody><row><entry
2267 align="char">
2268<para>Stops filtering sections on this section feed. Note that any changes to the
2269 filtering parameters (filter_value, filter_mask, etc.) should only be made when
2270 filtering is stopped.</para>
2271</entry>
2272 </row></tbody></tgroup></informaltable>
2273<para>SYNOPSIS
2274</para>
2275<informaltable><tgroup cols="1"><tbody><row><entry
2276 align="char">
2277<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2278</entry>
2279 </row></tbody></tgroup></informaltable>
2280<para>PARAMETERS
2281</para>
2282<informaltable><tgroup cols="2"><tbody><row><entry
2283 align="char">
2284<para>dmx_section_feed_t*
2285 feed</para>
2286</entry><entry
2287 align="char">
2288<para>Pointer to the section feed API and instance data.</para>
2289</entry>
2290 </row></tbody></tgroup></informaltable>
2291<para>RETURNS
2292</para>
2293<informaltable><tgroup cols="2"><tbody><row><entry
2294 align="char">
2295<para>0</para>
2296</entry><entry
2297 align="char">
2298<para>The function was completed without errors.</para>
2299</entry>
2300 </row><row><entry
2301 align="char">
2302<para>-EINVAL</para>
2303</entry><entry
2304 align="char">
2305<para>Bad parameter.</para>
2306</entry>
2307 </row></tbody></tgroup></informaltable>
2308
2309</section>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-19 09:42:21 -0500