kdapi.tex

linux TV 源码

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