Chapter 14. Kernel Demux API

Table of Contents

Kernel Demux Data Types
dmx_success_t
TS filter types
dmx_ts_pes_t
demux_demux_t
Demux directory
Demux Directory API
dmx_register_demux()
dmx_unregister_demux()
dmx_get_demuxes()
Demux API
open()
close()
write()
allocate_ts_feed()
release_ts_feed()
allocate_section_feed()
release_section_feed()
descramble_mac_address()
descramble_section_payload()
add_frontend()
remove_frontend()
get_frontends()
connect_frontend()
disconnect_frontend()
Demux Callback API
dmx_ts_cb()
dmx_section_cb()
TS Feed API
set()
start_filtering()
stop_filtering()
Section Feed API
set()
allocate_filter()
release_filter()
start_filtering()
stop_filtering()

The kernel demux API defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent demux layer. It is only of interest for DVB device driver writers. The header file for this API is named demux.h and located in ">drivers/media/dvb-core.

Maintainer note: This section must be reviewed. It is probably out of date.

Kernel Demux Data Types

dmx_success_t

 typedef enum {
   DMX_OK = 0, /⋆ Received Ok ⋆/
   DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/
   DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/
   DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/
   DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/
   DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/
   DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/
 } dmx_success_t;

TS filter types

 /⋆--------------------------------------------------------------------------⋆/
 /⋆ TS packet reception ⋆/
 /⋆--------------------------------------------------------------------------⋆/

 /⋆ TS filter type for set_type() ⋆/

 #define TS_PACKET       1   /⋆ send TS packets (188 bytes) to callback (default) ⋆/
 #define TS_PAYLOAD_ONLY 2   /⋆ in case TS_PACKET is set, only send the TS
				payload (<=184 bytes per packet) to callback ⋆/
 #define TS_DECODER      4   /⋆ send stream to built-in decoder (if present) ⋆/

dmx_ts_pes_t

The structure

 typedef enum
 {
	 DMX_TS_PES_AUDIO,   /⋆ also send packets to audio decoder (if it exists) ⋆/
	 DMX_TS_PES_VIDEO,   /⋆ ... ⋆/
	 DMX_TS_PES_TELETEXT,
	 DMX_TS_PES_SUBTITLE,
	 DMX_TS_PES_PCR,
	 DMX_TS_PES_OTHER,
 } dmx_ts_pes_t;

describes the PES type for filters which write to a built-in decoder. The correspond (and should be kept identical) to the types in the demux device.

 struct dmx_ts_feed_s {
	 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
	 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
	 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
	 int (⋆set) (struct dmx_ts_feed_s⋆ feed,
		     __u16 pid,
		     size_t callback_length,
		     size_t circular_buffer_size,
		     int descramble,
		     struct timespec timeout);
	 int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed);
	 int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed);
	 int (⋆set_type) (struct dmx_ts_feed_s⋆ feed,
			  int type,
			  dmx_ts_pes_t pes_type);
 };

 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
 /⋆--------------------------------------------------------------------------⋆/
 /⋆ PES packet reception (not supported yet) ⋆/
 /⋆--------------------------------------------------------------------------⋆/

 typedef struct dmx_pes_filter_s {
	 struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/
	 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
 } dmx_pes_filter_t;
 typedef struct dmx_pes_feed_s {
	 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
	 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
	 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
	 int (⋆set) (struct dmx_pes_feed_s⋆ feed,
		     __u16 pid,
		     size_t circular_buffer_size,
		     int descramble,
		     struct timespec timeout);
	 int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed);
	 int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed);
	 int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed,
				 dmx_pes_filter_t⋆⋆ filter);
	 int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed,
				dmx_pes_filter_t⋆ filter);
 } dmx_pes_feed_t;
 typedef struct {
	 __u8 filter_value [DMX_MAX_FILTER_SIZE];
	 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
	 struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/
	 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
 } dmx_section_filter_t;
 struct dmx_section_feed_s {
	 int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/
	 struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/
	 void⋆ priv; /⋆ Pointer to private data of the API client ⋆/
	 int (⋆set) (struct dmx_section_feed_s⋆ feed,
		     __u16 pid,
		     size_t circular_buffer_size,
		     int descramble,
		     int check_crc);
	 int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed,
				 dmx_section_filter_t⋆⋆ filter);
	 int (⋆release_filter) (struct dmx_section_feed_s⋆ feed,
				dmx_section_filter_t⋆ filter);
	 int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed);
	 int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed);
 };
 typedef struct dmx_section_feed_s dmx_section_feed_t;

 /⋆--------------------------------------------------------------------------⋆/
 /⋆ Callback functions ⋆/
 /⋆--------------------------------------------------------------------------⋆/

 typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1,
			    size_t buffer1_length,
			    __u8 ⋆ buffer2,
			    size_t buffer2_length,
			    dmx_ts_feed_t⋆ source,
			    dmx_success_t success);

 typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1,
				 size_t buffer1_len,
				 __u8 ⋆ buffer2,
				 size_t buffer2_len,
				 dmx_section_filter_t ⋆ source,
				 dmx_success_t success);

 typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1,
			     size_t buffer1_len,
			     __u8 ⋆ buffer2,
			     size_t buffer2_len,
			     dmx_pes_filter_t⋆ source,
			     dmx_success_t success);

 /⋆--------------------------------------------------------------------------⋆/
 /⋆ DVB Front-End ⋆/
 /⋆--------------------------------------------------------------------------⋆/

 typedef enum {
	 DMX_OTHER_FE = 0,
	 DMX_SATELLITE_FE,
	 DMX_CABLE_FE,
	 DMX_TERRESTRIAL_FE,
	 DMX_LVDS_FE,
	 DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/
	 DMX_MEMORY_FE
 } dmx_frontend_source_t;

 typedef struct {
	 /⋆ The following char⋆ fields point to NULL terminated strings ⋆/
	 char⋆ id;                    /⋆ Unique front-end identifier ⋆/
	 char⋆ vendor;                /⋆ Name of the front-end vendor ⋆/
	 char⋆ model;                 /⋆ Name of the front-end model ⋆/
	 struct list_head connectivity_list; /⋆ List of front-ends that can
						be connected to a particular
						demux ⋆/
	 void⋆ priv;     /⋆ Pointer to private data of the API client ⋆/
	 dmx_frontend_source_t source;
 } dmx_frontend_t;

 /⋆--------------------------------------------------------------------------⋆/
 /⋆ MPEG-2 TS Demux ⋆/
 /⋆--------------------------------------------------------------------------⋆/

 /⋆
  ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s.
  ⋆/

 #define DMX_TS_FILTERING                        1
 #define DMX_PES_FILTERING                       2
 #define DMX_SECTION_FILTERING                   4
 #define DMX_MEMORY_BASED_FILTERING              8    /⋆ write() available ⋆/
 #define DMX_CRC_CHECKING                        16
 #define DMX_TS_DESCRAMBLING                     32
 #define DMX_SECTION_PAYLOAD_DESCRAMBLING        64
 #define DMX_MAC_ADDRESS_DESCRAMBLING            128

demux_demux_t

 /⋆
  ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered
  ⋆ front-ends from the generic type struct list_head
  ⋆ to the type ⋆ dmx_frontend_t
  ⋆.
 ⋆/

 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)

 struct dmx_demux_s {
	 /⋆ The following char⋆ fields point to NULL terminated strings ⋆/
	 char⋆ id;                    /⋆ Unique demux identifier ⋆/
	 char⋆ vendor;                /⋆ Name of the demux vendor ⋆/
	 char⋆ model;                 /⋆ Name of the demux model ⋆/
	 __u32 capabilities;          /⋆ Bitfield of capability flags ⋆/
	 dmx_frontend_t⋆ frontend;    /⋆ Front-end connected to the demux ⋆/
	 struct list_head reg_list;   /⋆ List of registered demuxes ⋆/
	 void⋆ priv;                  /⋆ Pointer to private data of the API client ⋆/
	 int users;                   /⋆ Number of users ⋆/
	 int (⋆open) (struct dmx_demux_s⋆ demux);
	 int (⋆close) (struct dmx_demux_s⋆ demux);
	 int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count);
	 int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux,
				  dmx_ts_feed_t⋆⋆ feed,
				  dmx_ts_cb callback);
	 int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux,
				 dmx_ts_feed_t⋆ feed);
	 int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux,
				   dmx_pes_feed_t⋆⋆ feed,
				   dmx_pes_cb callback);
	 int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux,
				  dmx_pes_feed_t⋆ feed);
	 int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux,
				       dmx_section_feed_t⋆⋆ feed,
				       dmx_section_cb callback);
	 int (⋆release_section_feed) (struct dmx_demux_s⋆ demux,
				      dmx_section_feed_t⋆ feed);
	 int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux,
					__u8⋆ buffer1,
					size_t buffer1_length,
					__u8⋆ buffer2,
					size_t buffer2_length,
					__u16 pid);
	 int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux,
					    __u8⋆ buffer1,
					    size_t buffer1_length,
					    __u8⋆ buffer2, size_t buffer2_length,
					    __u16 pid);
	 int (⋆add_frontend) (struct dmx_demux_s⋆ demux,
			      dmx_frontend_t⋆ frontend);
	 int (⋆remove_frontend) (struct dmx_demux_s⋆ demux,
				 dmx_frontend_t⋆ frontend);
	 struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux);
	 int (⋆connect_frontend) (struct dmx_demux_s⋆ demux,
				  dmx_frontend_t⋆ frontend);
	 int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux);


	 /⋆ added because js cannot keep track of these himself ⋆/
	 int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids);
 };
 typedef struct dmx_demux_s dmx_demux_t;

Demux directory

 /⋆
  ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered
  ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t
  ⋆.
  ⋆/

 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)

 int dmx_register_demux (dmx_demux_t⋆ demux);
 int dmx_unregister_demux (dmx_demux_t⋆ demux);
 struct list_head⋆ dmx_get_demuxes (void);