Documentation/DocBook/dvb/kdapi.xml

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