kdapi.tex

linux TV 源码

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