kdapi.tex

linux TV 源码

\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,