CoCalc -- kdapi.xml

GitHub Repository: awilliam/linux-vfio
Path: blob/master/Documentation/DocBook/dvb/kdapi.xml
¹⁰⁸²³ views
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/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>
2310

2311
Product

Resources

Company
