Based on kernel version 4.3. Page generated on 2015-11-02 12:48 EST.
1 <title>Kernel Demux API</title> 2 <para>The kernel demux API defines a driver-internal interface for registering low-level, 3 hardware specific driver to a hardware independent demux layer. It is only of interest for 4 DVB device driver writers. The header file for this API is named <constant>demux.h</constant> and located in 5 <constant>">drivers/media/dvb-core</constant>. 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, /⋆ Received Ok ⋆/ 19 DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ 20 DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ 21 DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ 22 DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ 23 DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ 24 DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ 25 } dmx_success_t; 26 </programlisting> 27 28 </section> 29 <section id="ts_filter_types"> 30 <title>TS filter types</title> 31 <programlisting> 32 /⋆--------------------------------------------------------------------------⋆/ 33 /⋆ TS packet reception ⋆/ 34 /⋆--------------------------------------------------------------------------⋆/ 35 36 /⋆ TS filter type for set_type() ⋆/ 37 38 #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ 39 #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS 40 payload (<=184 bytes per packet) to callback ⋆/ 41 #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ 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, /⋆ also send packets to audio decoder (if it exists) ⋆/ 53 DMX_TS_PES_VIDEO, /⋆ ... ⋆/ 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; /⋆ Set to non-zero when filtering in progress ⋆/ 66 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ 67 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 68 int (⋆set) (struct dmx_ts_feed_s⋆ feed, 69 __u16 pid, 70 size_t callback_length, 71 size_t circular_buffer_size, 72 int descramble, 73 struct timespec timeout); 74 int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); 75 int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); 76 int (⋆set_type) (struct dmx_ts_feed_s⋆ 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 /⋆--------------------------------------------------------------------------⋆/ 85 /⋆ PES packet reception (not supported yet) ⋆/ 86 /⋆--------------------------------------------------------------------------⋆/ 87 88 typedef struct dmx_pes_filter_s { 89 struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ 90 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 91 } dmx_pes_filter_t; 92 </programlisting> 93 <programlisting> 94 typedef struct dmx_pes_feed_s { 95 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ 96 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ 97 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 98 int (⋆set) (struct dmx_pes_feed_s⋆ feed, 99 __u16 pid, 100 size_t circular_buffer_size, 101 int descramble, 102 struct timespec timeout); 103 int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); 104 int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); 105 int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, 106 dmx_pes_filter_t⋆⋆ filter); 107 int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, 108 dmx_pes_filter_t⋆ 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⋆ parent; /⋆ Back-pointer ⋆/ 116 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 117 } dmx_section_filter_t; 118 </programlisting> 119 <programlisting> 120 struct dmx_section_feed_s { 121 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ 122 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ 123 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 124 int (⋆set) (struct dmx_section_feed_s⋆ feed, 125 __u16 pid, 126 size_t circular_buffer_size, 127 int descramble, 128 int check_crc); 129 int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, 130 dmx_section_filter_t⋆⋆ filter); 131 int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, 132 dmx_section_filter_t⋆ filter); 133 int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); 134 int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); 135 }; 136 typedef struct dmx_section_feed_s dmx_section_feed_t; 137 138 /⋆--------------------------------------------------------------------------⋆/ 139 /⋆ Callback functions ⋆/ 140 /⋆--------------------------------------------------------------------------⋆/ 141 142 typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, 143 size_t buffer1_length, 144 __u8 ⋆ buffer2, 145 size_t buffer2_length, 146 dmx_ts_feed_t⋆ source, 147 dmx_success_t success); 148 149 typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, 150 size_t buffer1_len, 151 __u8 ⋆ buffer2, 152 size_t buffer2_len, 153 dmx_section_filter_t ⋆ source, 154 dmx_success_t success); 155 156 typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, 157 size_t buffer1_len, 158 __u8 ⋆ buffer2, 159 size_t buffer2_len, 160 dmx_pes_filter_t⋆ source, 161 dmx_success_t success); 162 163 /⋆--------------------------------------------------------------------------⋆/ 164 /⋆ DVB Front-End ⋆/ 165 /⋆--------------------------------------------------------------------------⋆/ 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, /⋆ DVB-ASI interface ⋆/ 174 DMX_MEMORY_FE 175 } dmx_frontend_source_t; 176 177 typedef struct { 178 /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ 179 char⋆ id; /⋆ Unique front-end identifier ⋆/ 180 char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ 181 char⋆ model; /⋆ Name of the front-end model ⋆/ 182 struct list_head connectivity_list; /⋆ List of front-ends that can 183 be connected to a particular 184 demux ⋆/ 185 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 186 dmx_frontend_source_t source; 187 } dmx_frontend_t; 188 189 /⋆--------------------------------------------------------------------------⋆/ 190 /⋆ MPEG-2 TS Demux ⋆/ 191 /⋆--------------------------------------------------------------------------⋆/ 192 193 /⋆ 194 ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. 195 ⋆/ 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 /⋆ write() available ⋆/ 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 /⋆ 212 ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered 213 ⋆ front-ends from the generic type struct list_head 214 ⋆ to the type ⋆ dmx_frontend_t 215 ⋆. 216 ⋆/ 217 218 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) 219 220 struct dmx_demux_s { 221 /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ 222 char⋆ id; /⋆ Unique demux identifier ⋆/ 223 char⋆ vendor; /⋆ Name of the demux vendor ⋆/ 224 char⋆ model; /⋆ Name of the demux model ⋆/ 225 __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ 226 dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ 227 struct list_head reg_list; /⋆ List of registered demuxes ⋆/ 228 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ 229 int users; /⋆ Number of users ⋆/ 230 int (⋆open) (struct dmx_demux_s⋆ demux); 231 int (⋆close) (struct dmx_demux_s⋆ demux); 232 int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); 233 int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, 234 dmx_ts_feed_t⋆⋆ feed, 235 dmx_ts_cb callback); 236 int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, 237 dmx_ts_feed_t⋆ feed); 238 int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, 239 dmx_pes_feed_t⋆⋆ feed, 240 dmx_pes_cb callback); 241 int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, 242 dmx_pes_feed_t⋆ feed); 243 int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, 244 dmx_section_feed_t⋆⋆ feed, 245 dmx_section_cb callback); 246 int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, 247 dmx_section_feed_t⋆ feed); 248 int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, 249 __u8⋆ buffer1, 250 size_t buffer1_length, 251 __u8⋆ buffer2, 252 size_t buffer2_length, 253 __u16 pid); 254 int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, 255 __u8⋆ buffer1, 256 size_t buffer1_length, 257 __u8⋆ buffer2, size_t buffer2_length, 258 __u16 pid); 259 int (⋆add_frontend) (struct dmx_demux_s⋆ demux, 260 dmx_frontend_t⋆ frontend); 261 int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, 262 dmx_frontend_t⋆ frontend); 263 struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); 264 int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, 265 dmx_frontend_t⋆ frontend); 266 int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); 267 268 269 /⋆ added because js cannot keep track of these himself ⋆/ 270 int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆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 /⋆ 280 ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered 281 ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t 282 ⋆. 283 ⋆/ 284 285 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) 286 287 int dmx_register_demux (dmx_demux_t⋆ demux); 288 int dmx_unregister_demux (dmx_demux_t⋆ demux); 289 struct list_head⋆ 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 ⋆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 ⋆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 ⋆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 “function not available”. 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⋆ 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⋆ 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⋆ demux, const char⋆ 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⋆ demux, 694 dmx_ts_feed_t⋆⋆ 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⋆ demux, 770 dmx_ts_feed_t⋆ 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⋆ demux, 828 dmx_section_feed_t ⋆⋆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⋆ demux, 906 dmx_section_feed_t ⋆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⋆ demux, __u8 962 ⋆buffer1, size_t buffer1_length, __u8 ⋆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 “plug-in” 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⋆ demux, 1075 __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆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 ⋆demux, dmx_frontend_t 1176 ⋆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⋆ demux, 1258 dmx_frontend_t⋆ 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⋆ get_frontends(dmx_demux_t⋆ 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⋆ demux, 1376 dmx_frontend_t⋆ 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⋆ 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 “bottom half” 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 ”wrapped” 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—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⋆ buffer1, size_t buffer1_length, 1559 __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ 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⋆ buffer1, size_t 1659 buffer1_length, __u8⋆ buffer2, size_t 1660 buffer2_length, dmx_section_filter_t⋆ 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⋆ 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⋆ 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⋆ 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⋆ 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 – 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⋆ feed, 2101 dmx_section_filter_t⋆⋆ 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⋆ feed, 2165 dmx_section_filter_t⋆ 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⋆ 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⋆ 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>