diff options
Diffstat (limited to 'dvb-spec/dvbapi/kdapi.tex')
| -rw-r--r-- | dvb-spec/dvbapi/kdapi.tex | 1014 |
1 files changed, 0 insertions, 1014 deletions
diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex deleted file mode 100644 index f7fc69353..000000000 --- a/dvb-spec/dvbapi/kdapi.tex +++ /dev/null @@ -1,1014 +0,0 @@ -\devsec{Kernel Demux API} - -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 \texttt{demux.h} and located in -\texttt{drivers/media/dvb/dvb-core}. - -Maintainer note: This section must be reviewed. It is probably out of date. - -\devsubsec{Kernel Demux Data Types} - -\devsubsubsec{dmx\_success\_t} -\label{dmxsuccesst} - -\begin{verbatim} -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; -\end{verbatim} - - -\devsubsubsec{TS filter types} -\label{tsfiltertypes} - -\begin{verbatim} -/*--------------------------------------------------------------------------*/ -/* 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) */ -\end{verbatim} - - -\devsubsubsec{dmx\_ts\_pes\_t} -\label{dmxtspest} - -The structure -\begin{verbatim} -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; -\end{verbatim} -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. - -\begin{verbatim} -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; -\end{verbatim} - -\begin{verbatim} -/*--------------------------------------------------------------------------*/ -/* 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; -\end{verbatim} - -\begin{verbatim} -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; -\end{verbatim} - - -\label{sectionfilter} -\begin{verbatim} -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; -\end{verbatim} - -\begin{verbatim} -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 -\end{verbatim} - -\devsubsubsec{demux\_demux\_t} -\label{demuxdemuxt} - -\begin{verbatim} -/* - * 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; -\end{verbatim} - - -\devsubsubsec{Demux directory} -\label{demuxdir} - -\begin{verbatim} -/* - * 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); -\end{verbatim} - -\clearpage - -\devsubsec{Demux Directory API} - -The demux directory is a Linux kernel-wide facility for registering and -accessing the MPEG-2 TS demuxes in the system. Run-time registering and -unregistering of demux drivers is possible using this API. - -All demux drivers in the directory implement the abstract interface dmx\_demux\_t. - -\kifunction{dmx\_register\_demux()}{ - int dmx\_register\_demux ( dmx\_demux\_t *demux ) - }{ - This function makes a demux driver interface available to the Linux kernel. - It is usually called by the init\_module() function of the kernel module that - contains the demux driver. The caller of this function is responsible for - allocating dynamic or static memory for the demux structure and for initializing - its fields before calling this function. - The memory allocated for the demux structure must not be freed before calling - dmx\_unregister\_demux(), - }{ - dmx\_demux\_t* demux & Pointer to the demux structure. - }{ - 0 & The function was completed without errors.\\ - -EEXIST & A demux with the same value of the id field - already stored in the directory.\\ - -ENOSPC & No space left in the directory. -} - -\kifunction{dmx\_unregister\_demux()}{ - int dmx\_unregister\_demux ( dmx\_demux\_t *demux ) - }{ - This function is called to indicate that the given demux interface is no longer - available. The caller of this function is responsible for freeing the memory of - the demux structure, if it was dynamically allocated before calling - dmx\_register\_demux(). - The cleanup\_module() function of the kernel module that contains the demux - driver should call this function. Note that this function fails if the demux - is currently in use, i.e., release\_demux() has not been called for the - interface. - }{ - dmx\_demux\_t* demux & Pointer to the demux structure which is to be unregistered. - }{ - 0 & The function was completed without errors.\\ - ENODEV & The specified demux is not registered in the demux directory.\\ - EBUSY & The specified demux is currently in use. -} - -\kifunction{dmx\_get\_demuxes()}{ - struct list\_head *dmx\_get\_demuxes () - }{ - Provides the caller with the list of registered demux interfaces, using the - standard list structure defined in the include file linux/list.h. - The include file demux.h defines the macro DMX\_DIR\_ENTRY() for converting an - element of the generic type struct list\_head* to the type dmx\_demux\_t*. - The caller must not free the memory of any of the elements obtained via this - function call. - }{ - none - }{ - struct list\_head * & - A list of demux interfaces, or NULL in the case of an empty list. -} - -\clearpage - -\devsubsec{Demux API} - -The demux API should be implemented for each demux in the system. It is used to -select the TS source of a demux and to manage the demux resources. When the -demux client allocates a resource via the demux API, it receives a pointer -to the API of that resource. - -Each demux receives its TS input from a DVB front-end or from memory, as -set via the demux API. In a system with more than one front-end, the API can -be used to select one of the DVB front-ends as a TS source for a demux, unless -this is fixed in the HW platform. The demux API only controls front-ends -regarding their connections with demuxes; the APIs used to set the other -front-end parameters, such as tuning, are not defined in this document. - -The functions that implement the abstract interface demux should be defined -static or module private and registered to the Demux Directory for external -access. It is not necessary to implement every function in the demux\_t struct, -however (for example, a demux interface might support Section filtering, but -not TS or PES filtering). The API client is expected to check the value of any -function pointer before calling the function: the value of NULL means ``function -not available''. - -Whenever the functions of the demux API modify shared data, the possibilities -of lost update and race condition problems should be addressed, e.g. by -protecting parts of code with mutexes. This is especially important on -multi-processor hosts. - -Note that functions called from a bottom half context must not sleep, at least -in the 2.2.x kernels. Even a simple memory allocation can result in a kernel -thread being put to sleep if swapping is needed. For example, the Linux kernel -calls the functions of a network device interface from a bottom half context. -Thus, if a demux API function is called from network device code, the function -must not sleep. - -\kfunction{open()}{ - int open ( demux\_t* demux ); - }{ - This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. - It should be possible for multiple clients to access the demux at the same time. - Thus, the function implementation should increment the demux usage count when - open() is called and decrement it when close() is called. - }{ - demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EUSERS & Maximum usage count reached.\\ - -EINVAL & Bad parameter. -} - -\kfunction{close()}{ - int close(demux\_t* demux); - }{ - This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. - It should be possible for multiple clients to access the demux at the same time. - Thus, the function implementation should increment the demux usage count when - open() is called and decrement it when close() is called. - }{ - demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -ENODEV & The demux was not in use.\\ - -EINVAL & Bad parameter. -} - -\kfunction{write()}{ - int write(demux\_t* demux, const char* buf, size\_t count); - }{ - This function provides the demux driver with a memory buffer containing TS - packets. Instead of receiving TS packets from the DVB front-end, the demux - driver software will read packets from memory. Any clients of this demux - with active TS, PES or Section filters will receive filtered data via the Demux - callback API (see 0). The function returns when all the data in the buffer has - been consumed by the demux. - Demux hardware typically cannot read TS from memory. If this is the case, - memory-based filtering has to be implemented entirely in software. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - const char* buf & Pointer to the TS data in kernel-space memory.\\ - size\_t length & Length of the TS data. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - -\kifunction{allocate\_ts\_feed()}{ - int allocate\_ts\_feed(dmx\_demux\_t* demux, - dmx\_ts\_feed\_t** feed, dmx\_ts\_cb callback); - }{ - Allocates a new TS feed, which is used to filter the TS packets carrying a - certain PID. - The TS feed normally corresponds to a hardware PID filter on the demux chip. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_ts\_feed\_t** feed & Pointer to the TS feed API and instance data.\\ - dmx\_ts\_cb callback & Pointer to the callback function for - passing received TS packet - }{ - 0 & The function was completed without errors.\\ - -EBUSY & No more TS feeds available.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - -\kifunction{release\_ts\_feed()}{ - int release\_ts\_feed(dmx\_demux\_t* demux, dmx\_ts\_feed\_t* feed); - }{ - Releases the resources allocated with allocate\_ts\_feed(). Any filtering in progress - on the TS feed should be stopped before calling this function. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{allocate\_section\_feed()}{ - int allocate\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t **feed, - dmx\_section\_cb callback); - }{ - Allocates a new section feed, i.e. a demux resource for filtering and - receiving sections. - On platforms with hardware support for section filtering, a section feed is directly - mapped to the demux HW. On other platforms, TS packets are first PID filtered in - hardware and a hardware section filter then emulated in software. - The caller obtains an API pointer of type dmx\_section\_feed\_t as an out parameter. - Using this API the caller can set filtering parameters and start receiving sections. - }{ - demux\_t *demux & Pointer to the demux API and instance data.\\ - dmx\_section\_feed\_t **feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_cb callback & Pointer to the callback function for - passing received sections. - }{ - 0 & The function was completed without errors.\\ - -EBUSY & No more section feeds available.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - - -\kifunction{release\_section\_feed()}{ - int release\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t *feed); - }{ - Releases the resources allocated with allocate\_section\_feed(), including allocated - filters. - Any filtering in progress on the section feed should be stopped before calling - this function. - }{ - demux\_t *demux & Pointer to the demux API and instance data.\\ - dmx\_section\_feed\_t *feed & Pointer to the section feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{descramble\_mac\_address()}{ - int descramble\_mac\_address(dmx\_demux\_t* demux, - \_\_u8 *buffer1, size\_t buffer1\_length, - \_\_u8 *buffer2, size\_t buffer2\_length, \_\_u16 pid); - }{ - This function runs a descrambling algorithm on the destination MAC address field of a - DVB Datagram Section, replacing the original address with its un-encrypted version. - Otherwise, the description on the function descramble\_section\_payload() applies - also to this function. - }{ - dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ - \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ - size\_t buffer1\_length & Length of the section data, including headers and CRC, - in buffer1.\\ - \_\_u8* buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a - non-NULL value if the section wraps - past the end of a circular buffer.\\ - size\_t buffer2\_length & Length of the section data, - including headers and CRC, in buffer2.\\ - \_\_u16 pid & The PID on which the section was received. Useful for obtaining the - descrambling key, e.g. from a DVB Common Access facility. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & No descrambling facility available.\\ - -EINVAL & Bad parameter. -} - -\kifunction{descramble\_section\_payload()}{ - int descramble\_section\_payload(dmx\_demux\_t* demux, - \_\_u8 *buffer1, size\_t buffer1\_length, \_\_u8 *buffer2, size\_t - buffer2\_length, \_\_u16 pid); - }{ - This function runs a descrambling algorithm on the payload of a DVB Datagram - Section, replacing the original payload with its un-encrypted version. - The function will - be called from the demux API implementation; the API client need - not call this function directly. - Section-level scrambling algorithms are currently standardized only for DVB-RCC - (return channel over 2-directional cable TV network) systems. For all other DVB - networks, encryption schemes are likely to be proprietary to each data broadcaster. - Thus, it is expected that this function pointer will have the value of NULL - (i.e., function not available) in most demux API implementations. - Nevertheless, it should be possible - to use the function pointer as a hook for dynamically adding a ``plug-in'' - descrambling facility to a demux driver.\\ - While this function is not needed with hardware-based section descrambling, the - descramble\_section\_payload function pointer can be used to override the default - hardware-based descrambling algorithm: if the function pointer has a non-NULL value, - the corresponding function should be used instead of any descrambling hardware. - }{ - dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ - \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ - size\_t buffer1\_length & Length of the section data, including headers and CRC, in - buffer1.\\ - \_\_u8 *buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a - non-NULL value if the section wraps - past the end of a circular buffer.\\ - size\_t buffer2\_length & Length of the section data, including headers and CRC, in - buffer2.\\ - \_\_u16 pid & The PID on which the section was received. Useful for obtaining the - descrambling key, e.g. from a DVB Common Access facility. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & No descrambling facility available.\\ - -EINVAL & Bad parameter. -} - -\kifunction{add\_frontend()}{ - int add\_frontend(dmx\_demux\_t *demux, dmx\_frontend\_t *frontend); - }{ - Registers a connectivity between a demux and a front-end, i.e., indicates that the - demux can be connected via a call to connect\_frontend() to use the given front-end - as a TS source. The client of this function has to allocate dynamic or static - memory for - the frontend structure and initialize its fields before calling this function. - This function is normally called during the driver initialization. - The caller must not free - the memory of the frontend struct before successfully calling remove\_frontend(). - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -EEXIST & A front-end with the same value of the id field already registered.\\ - -EINUSE & The demux is in use.\\ - -ENOMEM & No more front-ends can be added.\\ - -EINVAL & Bad parameter. -} - -\kifunction{remove\_frontend()}{ - int remove\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); - }{ - Indicates that the given front-end, registered by a call to add\_frontend(), can no - longer be connected as a TS source by this demux. The function should be called - when a front-end driver or a demux driver is removed from the system. If the front-end - is in use, the function fails with the return value of -EBUSY. - After successfully calling this function, the caller can free the memory of - the frontend struct if it was dynamically allocated before the add\_frontend() - operation. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter.\\ - -EBUSY & The front-end is in use, i.e. a call to - connect\_frontend() has not been followed by - a call to disconnect\_frontend(). -} - -\kifunction{get\_frontends()}{ - struct list\_head* get\_frontends(dmx\_demux\_t* demux); - }{ - Provides the APIs of the front-ends that have been registered for this demux. Any of - the front-ends obtained with this call can be used as a parameter for - connect\_frontend().\\ - The include file demux.h contains the macro DMX\_FE\_ENTRY() for converting an - element of the generic type struct list\_head* to the type dmx\_frontend\_t*. - The caller must not free the memory of any of the elements obtained via this function - call. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data. - }{ - dmx\_demux\_t* & A list of front-end interfaces, or NULL in the case of an empty list. -} - - -\kifunction{connect\_frontend()}{ - int connect\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); - }{ - Connects the TS output of the front-end to the input of the demux. A demux can only - be connected to a front-end registered to the demux with the function - add\_frontend().\\ - It may or may not be possible to connect multiple demuxes to the same front-end, - depending on the capabilities of the HW platform. When not used, the front-end should - be released by calling disconnect\_frontend(). - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter.\\ - -EBUSY & The front-end is in use. -} - -\kifunction{disconnect\_frontend()}{ - int disconnect\_frontend(dmx\_demux\_t* demux); - }{ - Disconnects the demux and a front-end previously connected by a - connect\_frontend() call. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\clearpage - -\devsubsec{Demux Callback API} - -This kernel-space API comprises the callback functions that deliver filtered data to the -demux client. Unlike the other APIs, these API functions are provided by the client and -called from the demux code. - -The function pointers of this abstract interface are not packed into a structure -as in the -other demux APIs, because the callback functions are registered and used -independent of each other. As an example, it is possible for the API client to provide -several callback functions for receiving TS packets and no callbacks for PES packets -or sections. - -The functions that implement the callback API need not be re-entrant: when a demux -driver calls one of these functions, the driver is not allowed to call the -function again before the original call returns. -If a callback is triggered by a hardware interrupt, it is -recommended to use the Linux ``bottom half'' mechanism or start a tasklet instead of -making the callback function call directly from a hardware interrupt. - -\kifunction{dmx\_ts\_cb()}{ - 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); - }{ - This function, provided by the client of the demux API, is called from the - demux code. The function is only called when filtering on this TS feed has - been enabled using the start\_filtering() function. \\ - Any TS packets that match the filter settings are copied to a circular buffer. - The filtered TS packets are delivered to the client using this callback - function. The size of the circular buffer is controlled by the - circular\_buffer\_size parameter of the set() function in the TS Feed API. It is - expected that the buffer1 and buffer2 callback parameters point to addresses - within the circular buffer, but other implementations are also - possible. Note that the called party should not try to free the memory the - buffer1 and buffer2 parameters point to.\\ - When this function is called, the buffer1 parameter typically points to the - start of the first undelivered TS packet within a circular buffer. The buffer2 - buffer parameter is normally NULL, except when the received TS packets have - crossed the last address of the circular buffer and "wrapped" to the beginning - of the buffer. In the latter case the buffer1 parameter would contain an - address within the circular buffer, while the buffer2 parameter would contain - the first address of the circular buffer.\\ - The number of bytes delivered with this function (i.e. buffer1\_length + - buffer2\_length) is usually equal to the value of callback\_length parameter given - in the set() function, with one exception: if a timeout occurs before receiving - callback\_length bytes of TS data, any undelivered packets are immediately - delivered to the client by calling this function. The timeout duration is - controlled by the set() function in the TS Feed API.\\ - If a TS packet is received with errors that could not be fixed by the TS-level - forward error correction (FEC), the Transport\_error\_indicator flag of the TS - packet header should be set. The TS packet should not be discarded, as the - error can possibly be corrected by a higher layer protocol. - If the called party is slow in processing the callback, it is possible that - the circular buffer eventually fills up. If this happens, the demux driver - should discard any TS packets received while the buffer is full. The error - should be indicated to the client on the next callback by setting the success - parameter to the value of DMX\_OVERRUN\_ERROR.\\ - The type of data returned to the callback can be selected by the - new function int (*set\_type) (struct dmx\_ts\_feed\_s* feed, int type, - dmx\_ts\_pes\_t pes\_type) which is part of the dmx\_ts\_feed\_s struct - (also cf. to the include file ost/demux.h) - The type parameter decides if the raw TS packet (TS\_PACKET) or just the - payload (TS\_PACKET|TS\_PAYLOAD\_ONLY) should be returned. - If additionally the TS\_DECODER bit is set the stream will also be sent - to the hardware MPEG decoder. In this case, the second flag decides - as what kind of data the stream should be interpreted. - The possible choices are one of DMX\_TS\_PES\_AUDIO, DMX\_TS\_PES\_VIDEO, - DMX\_TS\_PES\_TELETEXT, DMX\_TS\_PES\_SUBTITLE, DMX\_TS\_PES\_PCR, or - DMX\_TS\_PES\_OTHER. - }{ - \_\_u8* buffer1 & Pointer to the start of the filtered TS packets.\\ - size\_t buffer1\_length & Length of the TS data in buffer1.\\ - \_\_u8* buffer2 & Pointer to the tail of the filtered TS packets, or NULL.\\ - size\_t buffer2\_length & Length of the TS data in buffer2.\\ - dmx\_ts\_feed\_t* source & Indicates which TS feed is the source of the callback.\\ - dmx\_success\_t success & Indicates if there was an error in TS reception. - }{ - 0 & Continue filtering.\\ - -1& Stop filtering - has the same effect as a call - to stop\_filtering() on the TS Feed API. -} - -\kifunction{dmx\_section\_cb()}{ - int dmx\_section\_cb(\_\_u8* buffer1, size\_t buffer1\_length, \_\_u8* buffer2, - size\_t buffer2\_length, dmx\_section\_filter\_t* source, - dmx\_success\_t success); - }{ - This function, provided by the client of the demux API, is called from the demux code. - The function is only called when filtering of sections has been enabled using the - function start\_filtering() of the section feed API. - When the demux driver has received a complete section that matches at least one - section filter, the client is notified via this callback function. Normally this function is - called for each received section; however, it is also possible to deliver multiple sections - with one callback, for example when the system load is high. - If an error occurs while receiving a section, this function should be called with the - corresponding error type set in the success field, whether or not there is data to - deliver. - The Section Feed implementation should maintain a circular buffer for received sections. - However, this is not necessary if the Section Feed API is implemented as a client of - the TS Feed API, because the TS Feed implementation then buffers the - received data. - The size of the circular buffer can be configured using the set() function in the - Section Feed API. If there is no room in the circular buffer when a new section is - received, the section must be discarded. If this happens, the value of the success - parameter should be DMX\_OVERRUN\_ERROR on the next callback. - }{ - \_\_u8* buffer1 & Pointer to the start of the filtered section, e.g. - within the circular buffer of the demux driver.\\ - size\_t buffer1\_length & Length of the filtered section data in buffer1, - including headers and CRC.\\ - \_\_u8* buffer2 & Pointer to the tail of the filtered section data, or - NULL. Useful to handle the wrapping of a circular - buffer.\\ - size\_t buffer2\_length & Length of the filtered section data in buffer2, - including headers and CRC.\\ - dmx\_section\_filter\_t* filter & Indicates the filter that triggered the callback.\\ - dmx\_success\_t success & Indicates if there was an error in section reception. - }{ - 0 & Continue filtering.\\ - -1& Stop filtering - has the same effect as a call - to stop\_filtering() on the Section Feed API. -} - -\clearpage - -\devsubsec{TS Feed API} - -A TS feed is typically mapped to a hardware PID filter on the demux chip. Using this -API, the client can set the filtering properties to start/stop filtering TS packets on a -particular TS feed. The API is defined as an abstract interface of the type -dmx\_ts\_feed\_t. - -The functions that implement the interface should be defined static or module -private. The client can get the handle of a TS feed API by calling the function -allocate\_ts\_feed() in the demux API. - -\kifunction{set()}{ - int set ( dmx\_ts\_feed\_t* feed, \_\_u16 pid, size\_t callback\_length, - size\_t circular\_buffer\_size, int descramble, struct timespec timeout); - }{ - This function sets the parameters of a TS feed. - Any filtering in progress on the TS feed - must be stopped before calling this function. - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data.\\ - \_\_u16 pid & PID value to filter. Only the TS packets carrying the specified PID will - be passed to the API client.\\ - size\_t callback\_length & Number of bytes to deliver with each - call to the dmx\_ts\_cb() callback - function. The value of this - parameter should be a multiple of 188.\\ - size\_t circular\_buffer\_size & Size of the circular buffer for the filtered TS packets.\\ - int descramble & If non-zero, descramble the filtered TS packets.\\ - struct timespec timeout & Maximum time to wait before - delivering received TS packets to the client. - }{ - 0 & The function was completed without errors.\\ - -ENOMEM & Not enough memory for the requested buffer size.\\ - -ENOSYS & No descrambling facility available for TS.\\ - -EINVAL & Bad parameter. -} - - -\kifunction{start\_filtering()}{ - int start\_filtering(dmx\_ts\_feed\_t* feed); - }{ - Starts filtering TS packets on this TS feed, according to its settings. - The PID value to filter can be set by the API client. - All matching TS packets are delivered asynchronously to the client, - using the callback function registered with allocate\_ts\_feed(). - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{stop\_filtering()}{ - int stop\_filtering(dmx\_ts\_feed\_t* feed); - }{ - Stops filtering TS packets on this TS feed. - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\clearpage - -\devsubsec{Section Feed API} - -A section feed is a resource consisting of a PID filter and a set of section filters. -Using this API, the client can set the properties of a section feed and to -start/stop filtering. -The API is defined as an abstract interface of the type dmx\_section\_feed\_t. -The functions that implement the interface should be defined static or module -private. The client can get the handle of a section feed API by calling the function -allocate\_section\_feed() in the demux API. - -On demux platforms that provide section filtering in hardware, the Section Feed API -implementation provides a software wrapper for the demux hardware. Other platforms -may support only PID filtering in hardware, requiring that TS packets are converted to -sections in software. In the latter case the Section Feed API implementation can be a -client of the TS Feed API. - - -\kifunction{set()}{ - int set(dmx\_section\_feed\_t* feed, \_\_u16 pid, size\_t circular\_buffer\_size, - int descramble, int check\_crc); - }{ - This function sets the parameters of a section feed. Any filtering in progress on the - section feed must be stopped before calling this function. - If descrambling is enabled, the payload\_scrambling\_control and - address\_scrambling\_control fields of received DVB datagram sections should be - observed. If either one is non-zero, the section should be descrambled either in - hardware or using the functions descramble\_mac\_address() and - descramble\_section\_payload() of the demux API. Note that according to the - MPEG-2 Systems specification, only the payloads of private sections can be - scrambled while the rest of the section data must be sent in the clear. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - \_\_u16 pid & PID value to filter; only the TS packets - carrying the specified PID will be accepted.\\ - size\_t circular\_buffer\_size & Size of the circular buffer for filtered sections.\\ - int descramble & If non-zero, descramble any sections that are scrambled.\\ - int check\_crc & If non-zero, check the CRC values of filtered sections. - }{ - 0 & The function was completed without errors.\\ - -ENOMEM & Not enough memory for the requested buffer size.\\ - -ENOSYS & No descrambling facility available for sections.\\ - -EINVAL & Bad parameters. -} - -\kifunction{allocate\_filter()}{ - int allocate\_filter(dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t** filter); - }{ - This function is used to allocate a section filter on the demux. - It should only be called when no filtering is in progress on this section feed. - If a filter cannot be allocated, the function fails with -ENOSPC. - See in section \ref{sectionfilter} for the format of the section filter. \\ - The bitfields filter\_mask and filter\_value should only be modified when no - filtering is in progress on this section feed. filter\_mask controls which bits of - filter\_value are compared with the section headers/payload. On a binary value of 1 - in filter\_mask, the corresponding bits are compared. The filter only accepts sections - that are equal to filter\_value in all the tested bit positions. Any changes to the - values of filter\_mask and filter\_value are guaranteed to take effect only when - the start\_filtering() function is called next time. The parent pointer in the struct - is initialized by the API implementation to the value of the feed parameter. The priv - pointer is not used by the API implementation, and can thus be freely utilized by the - caller of this function. Any data pointed to by the priv pointer is available to the - recipient of the dmx\_section\_cb() function call.\\ - While the maximum section filter length (DMX\_MAX\_FILTER\_SIZE) - is currently set at 16 bytes, hardware filters of that size are not - available on all platforms. Therefore, section filtering will often - take place first in hardware, followed by filtering in software for the - header bytes that were not covered by a hardware filter. - The filter\_mask field can be checked to determine how many bytes of - the section filter are actually used, and if the - hardware filter will suffice. Additionally, software-only section filters - can optionally be - allocated to clients when all hardware section filters are in use. - Note that on most demux hardware it is not possible to filter on the - section\_length field - of the section header -- thus this field is ignored, even though it is included in - filter\_value and filter\_mask fields. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_filter\_t** filter & Pointer to the allocated filter. - }{ - 0 & The function was completed without errors.\\ - -ENOSPC & No filters of given type and length available.\\ - -EINVAL & Bad parameters. -} - -\kifunction{release\_filter()}{ - int release\_filter ( dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t* filter); - }{ - This function releases all the resources of a previously allocated section filter. - The function should not be called while filtering is in progress on this section feed. - After calling this function, the caller should not try to dereference the - filter pointer. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_filter\_t* filter & I/O Pointer to the instance data of a section filter. - }{ - 0 & The function was completed without errors.\\ - -ENODEV & No such filter allocated.\\ - -EINVAL & Bad parameter. -} - -\kifunction{start\_filtering()}{ - int start\_filtering ( dmx\_section\_feed\_t* feed ); - }{ - Starts filtering sections on this section feed, according to its settings. - Sections are first filtered based on their PID and then matched with the - section filters allocated for this feed. - If the section matches the PID filter and at least one section filter, it is delivered - to the API client. The section is delivered asynchronously using the callback function - registered with allocate\_section\_feed(). - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{stop\_filtering()}{ - int stop\_filtering ( dmx\_section\_feed\_t* feed ); - }{ - Stops filtering sections on this section feed. Note that any changes to the - filtering parameters (filter\_value, filter\_mask, etc.) should only be made - when filtering is stopped. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - - - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: |