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 <constant>demux.h</constant> and located in
5 <constant>">drivers/media/dvb-core</constant>.
7 <para>Maintainer note: This section must be reviewed. It is probably out of date.
10 <section id="kernel_demux_data_types">
11 <title>Kernel Demux Data Types</title>
15 <section id="ts_filter_types">
16 <title>TS filter types</title>
18 /⋆--------------------------------------------------------------------------⋆/
19 /⋆ TS packet reception ⋆/
20 /⋆--------------------------------------------------------------------------⋆/
22 /⋆ TS filter type for set_type() ⋆/
24 #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/
25 #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS
26 payload (<=184 bytes per packet) to callback ⋆/
27 #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/
31 <section id="dmx_ts_pes_t">
32 <title>dmx_ts_pes_t</title>
38 DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/
39 DMX_TS_PES_VIDEO, /⋆ ... ⋆/
46 <para>describes the PES type for filters which write to a built-in decoder. The correspond (and
47 should be kept identical) to the types in the demux device.
50 struct dmx_ts_feed_s {
51 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
52 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
53 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
54 int (⋆set) (struct dmx_ts_feed_s⋆ feed,
56 size_t callback_length,
57 size_t circular_buffer_size,
59 struct timespec timeout);
60 int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed);
61 int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed);
62 int (⋆set_type) (struct dmx_ts_feed_s⋆ feed,
64 dmx_ts_pes_t pes_type);
67 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
70 /⋆--------------------------------------------------------------------------⋆/
71 /⋆ PES packet reception (not supported yet) ⋆/
72 /⋆--------------------------------------------------------------------------⋆/
74 typedef struct dmx_pes_filter_s {
75 struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/
76 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
80 typedef struct dmx_pes_feed_s {
81 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
82 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
83 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
84 int (⋆set) (struct dmx_pes_feed_s⋆ feed,
86 size_t circular_buffer_size,
88 struct timespec timeout);
89 int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed);
90 int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed);
91 int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed,
92 dmx_pes_filter_t⋆⋆ filter);
93 int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed,
94 dmx_pes_filter_t⋆ filter);
99 __u8 filter_value [DMX_MAX_FILTER_SIZE];
100 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
101 struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/
102 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
103 } dmx_section_filter_t;
106 struct dmx_section_feed_s {
107 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
108 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
109 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
110 int (⋆set) (struct dmx_section_feed_s⋆ feed,
112 size_t circular_buffer_size,
115 int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed,
116 dmx_section_filter_t⋆⋆ filter);
117 int (⋆release_filter) (struct dmx_section_feed_s⋆ feed,
118 dmx_section_filter_t⋆ filter);
119 int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed);
120 int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed);
122 typedef struct dmx_section_feed_s dmx_section_feed_t;
124 /⋆--------------------------------------------------------------------------⋆/
125 /⋆ Callback functions ⋆/
126 /⋆--------------------------------------------------------------------------⋆/
128 typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1,
129 size_t buffer1_length,
130 __u8 ⋆ buffer2,
131 size_t buffer2_length,
132 dmx_ts_feed_t⋆ source)
134 typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1,
136 __u8 ⋆ buffer2,
138 dmx_section_filter_t ⋆ source);
140 typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1,
142 __u8 ⋆ buffer2,
144 dmx_pes_filter_t⋆ source);
146 /⋆--------------------------------------------------------------------------⋆/
147 /⋆ DVB Front-End ⋆/
148 /⋆--------------------------------------------------------------------------⋆/
153 } dmx_frontend_source;
156 /⋆ The following char⋆ fields point to NULL terminated strings ⋆/
157 char⋆ id; /⋆ Unique front-end identifier ⋆/
158 char⋆ vendor; /⋆ Name of the front-end vendor ⋆/
159 char⋆ model; /⋆ Name of the front-end model ⋆/
160 struct list_head connectivity_list; /⋆ List of front-ends that can
161 be connected to a particular
163 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
164 dmx_frontend_source source;
167 /⋆--------------------------------------------------------------------------⋆/
168 /⋆ MPEG-2 TS Demux ⋆/
169 /⋆--------------------------------------------------------------------------⋆/
172 ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s.
175 #define DMX_TS_FILTERING 1
176 #define DMX_PES_FILTERING 2
177 #define DMX_SECTION_FILTERING 4
178 #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/
179 #define DMX_CRC_CHECKING 16
180 #define DMX_TS_DESCRAMBLING 32
181 #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
182 #define DMX_MAC_ADDRESS_DESCRAMBLING 128
186 <section id="demux_demux_t">
187 <title>demux_demux_t</title>
190 ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered
191 ⋆ front-ends from the generic type struct list_head
192 ⋆ to the type ⋆ dmx_frontend_t
198 <section id="demux_directory">
199 <title>Demux directory</title>
202 ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered
203 ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t
207 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
209 int dmx_register_demux (dmx_demux_t⋆ demux);
210 int dmx_unregister_demux (dmx_demux_t⋆ demux);
211 struct list_head⋆ dmx_get_demuxes (void);
214 <section id="demux_directory_api">
215 <title>Demux Directory API</title>
216 <para>The demux directory is a Linux kernel-wide facility for registering and accessing the
217 MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
218 is possible using this API.
220 <para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
224 role="subsection"><title>dmx_register_demux()</title>
227 <informaltable><tgroup cols="1"><tbody><row><entry
229 <para>This function makes a demux driver interface available to the Linux kernel. It is
230 usually called by the init_module() function of the kernel module that contains
231 the demux driver. The caller of this function is responsible for allocating
232 dynamic or static memory for the demux structure and for initializing its fields
233 before calling this function. The memory allocated for the demux structure
234 must not be freed before calling dmx_unregister_demux(),</para>
236 </row></tbody></tgroup></informaltable>
239 <informaltable><tgroup cols="1"><tbody><row><entry
241 <para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para>
243 </row></tbody></tgroup></informaltable>
246 <informaltable><tgroup cols="2"><tbody><row><entry
252 <para>Pointer to the demux structure.</para>
254 </row></tbody></tgroup></informaltable>
257 <informaltable><tgroup cols="2"><tbody><row><entry
262 <para>The function was completed without errors.</para>
269 <para>A demux with the same value of the id field already stored
270 in the directory.</para>
277 <para>No space left in the directory.</para>
279 </row></tbody></tgroup></informaltable>
282 role="subsection"><title>dmx_unregister_demux()</title>
285 <informaltable><tgroup cols="1"><tbody><row><entry
287 <para>This function is called to indicate that the given demux interface is no
288 longer available. The caller of this function is responsible for freeing the
289 memory of the demux structure, if it was dynamically allocated before calling
290 dmx_register_demux(). The cleanup_module() function of the kernel module
291 that contains the demux driver should call this function. Note that this function
292 fails if the demux is currently in use, i.e., release_demux() has not been called
293 for the interface.</para>
295 </row></tbody></tgroup></informaltable>
298 <informaltable><tgroup cols="1"><tbody><row><entry
300 <para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para>
302 </row></tbody></tgroup></informaltable>
305 <informaltable><tgroup cols="2"><tbody><row><entry
311 <para>Pointer to the demux structure which is to be
314 </row></tbody></tgroup></informaltable>
317 <informaltable><tgroup cols="2"><tbody><row><entry
322 <para>The function was completed without errors.</para>
329 <para>The specified demux is not registered in the demux
337 <para>The specified demux is currently in use.</para>
339 </row></tbody></tgroup></informaltable>
342 role="subsection"><title>dmx_get_demuxes()</title>
345 <informaltable><tgroup cols="1"><tbody><row><entry
347 <para>Provides the caller with the list of registered demux interfaces, using the
348 standard list structure defined in the include file linux/list.h. The include file
349 demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
350 the generic type struct list_head* to the type dmx_demux_t*. The caller must
351 not free the memory of any of the elements obtained via this function call.</para>
353 </row></tbody></tgroup></informaltable>
356 <informaltable><tgroup cols="1"><tbody><row><entry
358 <para>struct list_head ⋆dmx_get_demuxes ()</para>
360 </row></tbody></tgroup></informaltable>
363 <informaltable><tgroup cols="2"><tbody><row><entry
367 </row></tbody></tgroup></informaltable>
370 <informaltable><tgroup cols="2"><tbody><row><entry
372 <para>struct list_head *</para>
375 <para>A list of demux interfaces, or NULL in the case of an
378 </row></tbody></tgroup></informaltable>
380 <section id="demux_api">
381 <title>Demux API</title>
382 <para>The demux API should be implemented for each demux in the system. It is used to select
383 the TS source of a demux and to manage the demux resources. When the demux
384 client allocates a resource via the demux API, it receives a pointer to the API of that
387 <para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
388 demux API. In a system with more than one front-end, the API can be used to select one of
389 the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
390 demux API only controls front-ends regarding their connections with demuxes; the APIs
391 used to set the other front-end parameters, such as tuning, are not defined in this
394 <para>The functions that implement the abstract interface demux should be defined static or
395 module private and registered to the Demux Directory for external access. It is not necessary
396 to implement every function in the demux_t struct, however (for example, a demux interface
397 might support Section filtering, but not TS or PES filtering). The API client is expected to
398 check the value of any function pointer before calling the function: the value of NULL means
399 “function not available”.
401 <para>Whenever the functions of the demux API modify shared data, the possibilities of lost
402 update and race condition problems should be addressed, e.g. by protecting parts of code with
403 mutexes. This is especially important on multi-processor hosts.
405 <para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
406 kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
407 swapping is needed. For example, the Linux kernel calls the functions of a network device
408 interface from a bottom half context. Thus, if a demux API function is called from network
409 device code, the function must not sleep.
413 <section id="demux_callback_api">
414 <title>Demux Callback API</title>
415 <para>This kernel-space API comprises the callback functions that deliver filtered data to the
416 demux client. Unlike the other APIs, these API functions are provided by the client and called
419 <para>The function pointers of this abstract interface are not packed into a structure as in the
420 other demux APIs, because the callback functions are registered and used independent
421 of each other. As an example, it is possible for the API client to provide several
422 callback functions for receiving TS packets and no callbacks for PES packets or
425 <para>The functions that implement the callback API need not be re-entrant: when a demux
426 driver calls one of these functions, the driver is not allowed to call the function again before
427 the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
428 to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback
429 function call directly from a hardware interrupt.
433 role="subsection"><title>dmx_ts_cb()</title>
436 <informaltable><tgroup cols="1"><tbody><row><entry
438 <para>This function, provided by the client of the demux API, is called from the
439 demux code. The function is only called when filtering on this TS feed has
440 been enabled using the start_filtering() function.</para>
444 <para>Any TS packets that match the filter settings are copied to a circular buffer. The
445 filtered TS packets are delivered to the client using this callback function. The
446 size of the circular buffer is controlled by the circular_buffer_size parameter
447 of the set() function in the TS Feed API. It is expected that the buffer1 and
448 buffer2 callback parameters point to addresses within the circular buffer, but
449 other implementations are also possible. Note that the called party should not
450 try to free the memory the buffer1 and buffer2 parameters point to.</para>
454 <para>When this function is called, the buffer1 parameter typically points to the
455 start of the first undelivered TS packet within a circular buffer. The buffer2
456 buffer parameter is normally NULL, except when the received TS packets have
457 crossed the last address of the circular buffer and ”wrapped” to the beginning
458 of the buffer. In the latter case the buffer1 parameter would contain an address
459 within the circular buffer, while the buffer2 parameter would contain the first
460 address of the circular buffer.</para>
464 <para>The number of bytes delivered with this function (i.e. buffer1_length +
465 buffer2_length) is usually equal to the value of callback_length parameter
466 given in the set() function, with one exception: if a timeout occurs before
467 receiving callback_length bytes of TS data, any undelivered packets are
468 immediately delivered to the client by calling this function. The timeout
469 duration is controlled by the set() function in the TS Feed API.</para>
473 <para>If a TS packet is received with errors that could not be fixed by the TS-level
474 forward error correction (FEC), the Transport_error_indicator flag of the TS
475 packet header should be set. The TS packet should not be discarded, as
476 the error can possibly be corrected by a higher layer protocol. If the called
477 party is slow in processing the callback, it is possible that the circular buffer
478 eventually fills up. If this happens, the demux driver should discard any TS
479 packets received while the buffer is full. The error should be indicated to the
480 client on the next callback by setting the success parameter to the value of
481 DMX_OVERRUN_ERROR.</para>
485 <para>The type of data returned to the callback can be selected by the new
486 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
487 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
488 include file ost/demux.h) The type parameter decides if the raw TS packet
489 (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY)
490 should be returned. If additionally the TS_DECODER bit is set the stream
491 will also be sent to the hardware MPEG decoder. In this case, the second
492 flag decides as what kind of data the stream should be interpreted. The
493 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
494 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
495 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
497 </row></tbody></tgroup></informaltable>
500 <informaltable><tgroup cols="1"><tbody><row><entry
502 <para>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length,
503 __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆
506 </row></tbody></tgroup></informaltable>
509 <informaltable><tgroup cols="2"><tbody><row><entry
511 <para>__u8* buffer1</para>
514 <para>Pointer to the start of the filtered TS packets.</para>
518 <para>size_t buffer1_length</para>
521 <para>Length of the TS data in buffer1.</para>
525 <para>__u8* buffer2</para>
528 <para>Pointer to the tail of the filtered TS packets, or NULL.</para>
532 <para>size_t buffer2_length</para>
535 <para>Length of the TS data in buffer2.</para>
543 <para>Indicates which TS feed is the source of the callback.</para>
545 </row></tbody></tgroup></informaltable>
548 <informaltable><tgroup cols="2"><tbody><row><entry
553 <para>Continue filtering.</para>
560 <para>Stop filtering - has the same effect as a call to
561 stop_filtering() on the TS Feed API.</para>
563 </row></tbody></tgroup></informaltable>
566 role="subsection"><title>dmx_section_cb()</title>
569 <informaltable><tgroup cols="1"><tbody><row><entry
571 <para>This function, provided by the client of the demux API, is called from the
572 demux code. The function is only called when filtering of sections has been
573 enabled using the function start_filtering() of the section feed API. When the
574 demux driver has received a complete section that matches at least one section
575 filter, the client is notified via this callback function. Normally this function is
576 called for each received section; however, it is also possible to deliver multiple
577 sections with one callback, for example when the system load is high. If an
578 error occurs while receiving a section, this function should be called with
579 the corresponding error type set in the success field, whether or not there is
580 data to deliver. The Section Feed implementation should maintain a circular
581 buffer for received sections. However, this is not necessary if the Section Feed
582 API is implemented as a client of the TS Feed API, because the TS Feed
583 implementation then buffers the received data. The size of the circular buffer
584 can be configured using the set() function in the Section Feed API. If there
585 is no room in the circular buffer when a new section is received, the section
586 must be discarded. If this happens, the value of the success parameter should
587 be DMX_OVERRUN_ERROR on the next callback.</para>
589 </row></tbody></tgroup></informaltable>
592 <informaltable><tgroup cols="1"><tbody><row><entry
594 <para>int dmx_section_cb(__u8⋆ buffer1, size_t
595 buffer1_length, __u8⋆ buffer2, size_t
596 buffer2_length, dmx_section_filter_t⋆ source);</para>
598 </row></tbody></tgroup></informaltable>
601 <informaltable><tgroup cols="2"><tbody><row><entry
603 <para>__u8* buffer1</para>
606 <para>Pointer to the start of the filtered section, e.g. within the
607 circular buffer of the demux driver.</para>
611 <para>size_t buffer1_length</para>
614 <para>Length of the filtered section data in buffer1, including
615 headers and CRC.</para>
619 <para>__u8* buffer2</para>
622 <para>Pointer to the tail of the filtered section data, or NULL.
623 Useful to handle the wrapping of a circular buffer.</para>
627 <para>size_t buffer2_length</para>
630 <para>Length of the filtered section data in buffer2, including
631 headers and CRC.</para>
635 <para>dmx_section_filter_t*
639 <para>Indicates the filter that triggered the callback.</para>
641 </row></tbody></tgroup></informaltable>
644 <informaltable><tgroup cols="2"><tbody><row><entry
649 <para>Continue filtering.</para>
656 <para>Stop filtering - has the same effect as a call to
657 stop_filtering() on the Section Feed API.</para>
659 </row></tbody></tgroup></informaltable>
661 <section id="ts_feed_api">
662 <title>TS Feed API</title>
663 <para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
664 Using this API, the client can set the filtering properties to start/stop filtering TS
665 packets on a particular TS feed. The API is defined as an abstract interface of the type
668 <para>The functions that implement the interface should be defined static or module private. The
669 client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
674 role="subsection"><title>set()</title>
677 <informaltable><tgroup cols="1"><tbody><row><entry
679 <para>This function sets the parameters of a TS feed. Any filtering in progress on the
680 TS feed must be stopped before calling this function.</para>
682 </row></tbody></tgroup></informaltable>
685 <informaltable><tgroup cols="1"><tbody><row><entry
687 <para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t
688 callback_length, size_t circular_buffer_size, int
689 descramble, struct timespec timeout);</para>
691 </row></tbody></tgroup></informaltable>
694 <informaltable><tgroup cols="2"><tbody><row><entry
696 <para>dmx_ts_feed_t* feed</para>
699 <para>Pointer to the TS feed API and instance data.</para>
703 <para>__u16 pid</para>
706 <para>PID value to filter. Only the TS packets carrying the
707 specified PID will be passed to the API client.</para>
712 callback_length</para>
715 <para>Number of bytes to deliver with each call to the
716 dmx_ts_cb() callback function. The value of this
717 parameter should be a multiple of 188.</para>
722 circular_buffer_size</para>
725 <para>Size of the circular buffer for the filtered TS packets.</para>
729 <para>int descramble</para>
732 <para>If non-zero, descramble the filtered TS packets.</para>
736 <para>struct timespec
740 <para>Maximum time to wait before delivering received TS
741 packets to the client.</para>
743 </row></tbody></tgroup></informaltable>
746 <informaltable><tgroup cols="2"><tbody><row><entry
751 <para>The function was completed without errors.</para>
758 <para>Not enough memory for the requested buffer size.</para>
765 <para>No descrambling facility available for TS.</para>
772 <para>Bad parameter.</para>
774 </row></tbody></tgroup></informaltable>
777 role="subsection"><title>start_filtering()</title>
780 <informaltable><tgroup cols="1"><tbody><row><entry
782 <para>Starts filtering TS packets on this TS feed, according to its settings. The PID
783 value to filter can be set by the API client. All matching TS packets are
784 delivered asynchronously to the client, using the callback function registered
785 with allocate_ts_feed().</para>
787 </row></tbody></tgroup></informaltable>
790 <informaltable><tgroup cols="1"><tbody><row><entry
792 <para>int start_filtering(dmx_ts_feed_t⋆ feed);</para>
794 </row></tbody></tgroup></informaltable>
797 <informaltable><tgroup cols="2"><tbody><row><entry
799 <para>dmx_ts_feed_t* feed</para>
802 <para>Pointer to the TS feed API and instance data.</para>
804 </row></tbody></tgroup></informaltable>
807 <informaltable><tgroup cols="2"><tbody><row><entry
812 <para>The function was completed without errors.</para>
819 <para>Bad parameter.</para>
821 </row></tbody></tgroup></informaltable>
824 role="subsection"><title>stop_filtering()</title>
827 <informaltable><tgroup cols="1"><tbody><row><entry
829 <para>Stops filtering TS packets on this TS feed.</para>
831 </row></tbody></tgroup></informaltable>
834 <informaltable><tgroup cols="1"><tbody><row><entry
836 <para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para>
838 </row></tbody></tgroup></informaltable>
841 <informaltable><tgroup cols="2"><tbody><row><entry
843 <para>dmx_ts_feed_t* feed</para>
846 <para>Pointer to the TS feed API and instance data.</para>
848 </row></tbody></tgroup></informaltable>
851 <informaltable><tgroup cols="2"><tbody><row><entry
856 <para>The function was completed without errors.</para>
863 <para>Bad parameter.</para>
865 </row></tbody></tgroup></informaltable>
867 <section id="section_feed_api">
868 <title>Section Feed API</title>
869 <para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
870 API, the client can set the properties of a section feed and to start/stop filtering. The API is
871 defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
872 the interface should be defined static or module private. The client can get the handle of
873 a section feed API by calling the function allocate_section_feed() in the demux
876 <para>On demux platforms that provide section filtering in hardware, the Section Feed API
877 implementation provides a software wrapper for the demux hardware. Other platforms may
878 support only PID filtering in hardware, requiring that TS packets are converted to sections in
879 software. In the latter case the Section Feed API implementation can be a client of the TS
884 <section id="kdapi_set">
888 <informaltable><tgroup cols="1"><tbody><row><entry
890 <para>This function sets the parameters of a section feed. Any filtering in progress on
891 the section feed must be stopped before calling this function. If descrambling
892 is enabled, the payload_scrambling_control and address_scrambling_control
893 fields of received DVB datagram sections should be observed. If either one is
894 non-zero, the section should be descrambled either in hardware or using the
895 functions descramble_mac_address() and descramble_section_payload() of the
896 demux API. Note that according to the MPEG-2 Systems specification, only
897 the payloads of private sections can be scrambled while the rest of the section
898 data must be sent in the clear.</para>
900 </row></tbody></tgroup></informaltable>
903 <informaltable><tgroup cols="1"><tbody><row><entry
905 <para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t
906 circular_buffer_size, int descramble, int
909 </row></tbody></tgroup></informaltable>
912 <informaltable><tgroup cols="2"><tbody><row><entry
914 <para>dmx_section_feed_t*
918 <para>Pointer to the section feed API and instance data.</para>
922 <para>__u16 pid</para>
925 <para>PID value to filter; only the TS packets carrying the
926 specified PID will be accepted.</para>
931 circular_buffer_size</para>
934 <para>Size of the circular buffer for filtered sections.</para>
938 <para>int descramble</para>
941 <para>If non-zero, descramble any sections that are scrambled.</para>
945 <para>int check_crc</para>
948 <para>If non-zero, check the CRC values of filtered sections.</para>
950 </row></tbody></tgroup></informaltable>
953 <informaltable><tgroup cols="2"><tbody><row><entry
958 <para>The function was completed without errors.</para>
965 <para>Not enough memory for the requested buffer size.</para>
972 <para>No descrambling facility available for sections.</para>
979 <para>Bad parameters.</para>
981 </row></tbody></tgroup></informaltable>
984 role="subsection"><title>allocate_filter()</title>
987 <informaltable><tgroup cols="1"><tbody><row><entry
989 <para>This function is used to allocate a section filter on the demux. It should only be
990 called when no filtering is in progress on this section feed. If a filter cannot be
991 allocated, the function fails with -ENOSPC. See in section ?? for the format of
992 the section filter.</para>
996 <para>The bitfields filter_mask and filter_value should only be modified when no
997 filtering is in progress on this section feed. filter_mask controls which bits of
998 filter_value are compared with the section headers/payload. On a binary value
999 of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
1000 sections that are equal to filter_value in all the tested bit positions. Any changes
1001 to the values of filter_mask and filter_value are guaranteed to take effect only
1002 when the start_filtering() function is called next time. The parent pointer in
1003 the struct is initialized by the API implementation to the value of the feed
1004 parameter. The priv pointer is not used by the API implementation, and can
1005 thus be freely utilized by the caller of this function. Any data pointed to by the
1006 priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
1010 <para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
1011 currently set at 16 bytes, hardware filters of that size are not available on all
1012 platforms. Therefore, section filtering will often take place first in hardware,
1013 followed by filtering in software for the header bytes that were not covered
1014 by a hardware filter. The filter_mask field can be checked to determine how
1015 many bytes of the section filter are actually used, and if the hardware filter will
1016 suffice. Additionally, software-only section filters can optionally be allocated
1017 to clients when all hardware section filters are in use. Note that on most demux
1018 hardware it is not possible to filter on the section_length field of the section
1019 header – thus this field is ignored, even though it is included in filter_value and
1020 filter_mask fields.</para>
1022 </row></tbody></tgroup></informaltable>
1025 <informaltable><tgroup cols="1"><tbody><row><entry
1027 <para>int allocate_filter(dmx_section_feed_t⋆ feed,
1028 dmx_section_filter_t⋆⋆ filter);</para>
1030 </row></tbody></tgroup></informaltable>
1033 <informaltable><tgroup cols="2"><tbody><row><entry
1035 <para>dmx_section_feed_t*
1039 <para>Pointer to the section feed API and instance data.</para>
1043 <para>dmx_section_filter_t**
1047 <para>Pointer to the allocated filter.</para>
1049 </row></tbody></tgroup></informaltable>
1052 <informaltable><tgroup cols="2"><tbody><row><entry
1057 <para>The function was completed without errors.</para>
1061 <para>-ENOSPC</para>
1064 <para>No filters of given type and length available.</para>
1068 <para>-EINVAL</para>
1071 <para>Bad parameters.</para>
1073 </row></tbody></tgroup></informaltable>
1076 role="subsection"><title>release_filter()</title>
1079 <informaltable><tgroup cols="1"><tbody><row><entry
1081 <para>This function releases all the resources of a previously allocated section filter.
1082 The function should not be called while filtering is in progress on this section
1083 feed. After calling this function, the caller should not try to dereference the
1084 filter pointer.</para>
1086 </row></tbody></tgroup></informaltable>
1089 <informaltable><tgroup cols="1"><tbody><row><entry
1091 <para>int release_filter ( dmx_section_feed_t⋆ feed,
1092 dmx_section_filter_t⋆ filter);</para>
1094 </row></tbody></tgroup></informaltable>
1097 <informaltable><tgroup cols="2"><tbody><row><entry
1099 <para>dmx_section_feed_t*
1103 <para>Pointer to the section feed API and instance data.</para>
1107 <para>dmx_section_filter_t*
1111 <para>I/O Pointer to the instance data of a section filter.</para>
1113 </row></tbody></tgroup></informaltable>
1116 <informaltable><tgroup cols="2"><tbody><row><entry
1121 <para>The function was completed without errors.</para>
1125 <para>-ENODEV</para>
1128 <para>No such filter allocated.</para>
1132 <para>-EINVAL</para>
1135 <para>Bad parameter.</para>
1137 </row></tbody></tgroup></informaltable>
1140 role="subsection"><title>start_filtering()</title>
1143 <informaltable><tgroup cols="1"><tbody><row><entry
1145 <para>Starts filtering sections on this section feed, according to its settings. Sections
1146 are first filtered based on their PID and then matched with the section
1147 filters allocated for this feed. If the section matches the PID filter and
1148 at least one section filter, it is delivered to the API client. The section
1149 is delivered asynchronously using the callback function registered with
1150 allocate_section_feed().</para>
1152 </row></tbody></tgroup></informaltable>
1155 <informaltable><tgroup cols="1"><tbody><row><entry
1157 <para>int start_filtering ( dmx_section_feed_t⋆ feed );</para>
1159 </row></tbody></tgroup></informaltable>
1162 <informaltable><tgroup cols="2"><tbody><row><entry
1164 <para>dmx_section_feed_t*
1168 <para>Pointer to the section feed API and instance data.</para>
1170 </row></tbody></tgroup></informaltable>
1173 <informaltable><tgroup cols="2"><tbody><row><entry
1178 <para>The function was completed without errors.</para>
1182 <para>-EINVAL</para>
1185 <para>Bad parameter.</para>
1187 </row></tbody></tgroup></informaltable>
1190 role="subsection"><title>stop_filtering()</title>
1193 <informaltable><tgroup cols="1"><tbody><row><entry
1195 <para>Stops filtering sections on this section feed. Note that any changes to the
1196 filtering parameters (filter_value, filter_mask, etc.) should only be made when
1197 filtering is stopped.</para>
1199 </row></tbody></tgroup></informaltable>
1202 <informaltable><tgroup cols="1"><tbody><row><entry
1204 <para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para>
1206 </row></tbody></tgroup></informaltable>
1209 <informaltable><tgroup cols="2"><tbody><row><entry
1211 <para>dmx_section_feed_t*
1215 <para>Pointer to the section feed API and instance data.</para>
1217 </row></tbody></tgroup></informaltable>
1220 <informaltable><tgroup cols="2"><tbody><row><entry
1225 <para>The function was completed without errors.</para>
1229 <para>-EINVAL</para>
1232 <para>Bad parameter.</para>
1234 </row></tbody></tgroup></informaltable>
projects / karo-tx-linux.git / blob