From 8e4bff4cab0ddac6060645b0715210484d02ff40 Mon Sep 17 00:00:00 2001
From: Yuval Adam <_@yuv.al>
Date: Wed, 30 Aug 2017 08:25:59 +0000
Subject: Initial file dump from open source release
---
Documentation/DocBook/media/dvb/kdapi.xml | 2309 +++++++++++++++++++++++++++++
1 file changed, 2309 insertions(+)
create mode 100644 Documentation/DocBook/media/dvb/kdapi.xml
(limited to 'Documentation/DocBook/media/dvb/kdapi.xml')
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
new file mode 100644
index 00000000..6c11ec52
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -0,0 +1,2309 @@
+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 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);
+
+
+
+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.
+
+
+dmx_register_demux()
+DESCRIPTION
+
+
+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(),
+
+
+SYNOPSIS
+
+
+int dmx_register_demux ( dmx_demux_t ⋆demux )
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux structure.
+
+
+RETURNS
+
+
+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.
+
+
+
+dmx_unregister_demux()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int dmx_unregister_demux ( dmx_demux_t ⋆demux )
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux structure which is to be
+ unregistered.
+
+
+RETURNS
+
+
+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.
+
+
+
+dmx_get_demuxes()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+struct list_head ⋆dmx_get_demuxes ()
+
+
+PARAMETERS
+
+
+none
+
+
+RETURNS
+
+
+struct list_head *
+
+A list of demux interfaces, or NULL in the case of an
+ empty list.
+
+
+
+
+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.
+
+
+
+
+open()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int open ( demux_t⋆ demux );
+
+
+PARAMETERS
+
+
+demux_t* demux
+
+Pointer to the demux API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EUSERS
+
+Maximum usage count reached.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+
+
+close()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int close(demux_t⋆ demux);
+
+
+PARAMETERS
+
+
+demux_t* demux
+
+Pointer to the demux API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENODEV
+
+The demux was not in use.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+
+
+write()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int write(demux_t⋆ demux, const char⋆ buf, size_t
+ count);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENOSYS
+
+The command is not implemented.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+allocate_ts_feed()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int allocate_ts_feed(dmx_demux_t⋆ demux,
+ dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);
+
+
+PARAMETERS
+
+
+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
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EBUSY
+
+No more TS feeds available.
+
+
+-ENOSYS
+
+The command is not implemented.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+release_ts_feed()
+DESCRIPTION
+
+
+Releases the resources allocated with allocate_ts_feed(). Any filtering in
+ progress on the TS feed should be stopped before calling this function.
+
+
+SYNOPSIS
+
+
+int release_ts_feed(dmx_demux_t⋆ demux,
+ dmx_ts_feed_t⋆ feed);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+allocate_section_feed()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int allocate_section_feed(dmx_demux_t⋆ demux,
+ dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EBUSY
+
+No more section feeds available.
+
+
+-ENOSYS
+
+The command is not implemented.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+release_section_feed()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int release_section_feed(dmx_demux_t⋆ demux,
+ dmx_section_feed_t ⋆feed);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+descramble_mac_address()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int descramble_mac_address(dmx_demux_t⋆ demux, __u8
+ ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2,
+ size_t buffer2_length, __u16 pid);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENOSYS
+
+No descrambling facility available.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+descramble_section_payload()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int descramble_section_payload(dmx_demux_t⋆ demux,
+ __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2,
+ size_t buffer2_length, __u16 pid);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENOSYS
+
+No descrambling facility available.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+add_frontend()
+DESCRIPTION
+
+
+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().
+
+
+SYNOPSIS
+
+
+int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t
+ ⋆frontend);
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux API and instance data.
+
+
+dmx_frontend_t*
+ frontend
+
+Pointer to the front-end instance data.
+
+
+RETURNS
+
+
+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.
+
+
+
+remove_frontend()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int remove_frontend(dmx_demux_t⋆ demux,
+ dmx_frontend_t⋆ frontend);
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux API and instance data.
+
+
+dmx_frontend_t*
+ frontend
+
+Pointer to the front-end instance data.
+
+
+RETURNS
+
+
+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().
+
+
+
+get_frontends()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux API and instance data.
+
+
+RETURNS
+
+
+dmx_demux_t*
+
+A list of front-end interfaces, or NULL in the case of an
+ empty list.
+
+
+
+connect_frontend()
+DESCRIPTION
+
+
+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().
+
+
+SYNOPSIS
+
+
+int connect_frontend(dmx_demux_t⋆ demux,
+ dmx_frontend_t⋆ frontend);
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux API and instance data.
+
+
+dmx_frontend_t*
+ frontend
+
+Pointer to the front-end instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+-EBUSY
+
+The front-end is in use.
+
+
+
+disconnect_frontend()
+DESCRIPTION
+
+
+Disconnects the demux and a front-end previously connected by a
+ connect_frontend() call.
+
+
+SYNOPSIS
+
+
+int disconnect_frontend(dmx_demux_t⋆ demux);
+
+
+PARAMETERS
+
+
+dmx_demux_t*
+ demux
+
+Pointer to the demux API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+
+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.
+
+
+dmx_ts_cb()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+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);
+
+
+PARAMETERS
+
+
+__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.
+
+
+RETURNS
+
+
+0
+
+Continue filtering.
+
+
+-1
+
+Stop filtering - has the same effect as a call to
+ stop_filtering() on the TS Feed API.
+
+
+
+dmx_section_cb()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+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);
+
+
+PARAMETERS
+
+
+__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.
+
+
+RETURNS
+
+
+0
+
+Continue filtering.
+
+
+-1
+
+Stop filtering - has the same effect as a call to
+ stop_filtering() on the Section Feed API.
+
+
+
+
+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.
+
+
+set()
+DESCRIPTION
+
+
+This function sets the parameters of a TS feed. Any filtering in progress on the
+ TS feed must be stopped before calling this function.
+
+
+SYNOPSIS
+
+
+int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t
+ callback_length, size_t circular_buffer_size, int
+ descramble, struct timespec timeout);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+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.
+
+
+
+start_filtering()
+DESCRIPTION
+
+
+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().
+
+
+SYNOPSIS
+
+
+int start_filtering(dmx_ts_feed_t⋆ feed);
+
+
+PARAMETERS
+
+
+dmx_ts_feed_t* feed
+
+Pointer to the TS feed API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+stop_filtering()
+DESCRIPTION
+
+
+Stops filtering TS packets on this TS feed.
+
+
+SYNOPSIS
+
+
+int stop_filtering(dmx_ts_feed_t⋆ feed);
+
+
+PARAMETERS
+
+
+dmx_ts_feed_t* feed
+
+Pointer to the TS feed API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+
+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.
+
+
+
+
+set()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t
+ circular_buffer_size, int descramble, int
+ check_crc);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+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.
+
+
+
+allocate_filter()
+DESCRIPTION
+
+
+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 ?? 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.
+
+
+SYNOPSIS
+
+
+int allocate_filter(dmx_section_feed_t⋆ feed,
+ dmx_section_filter_t⋆⋆ filter);
+
+
+PARAMETERS
+
+
+dmx_section_feed_t*
+ feed
+
+Pointer to the section feed API and instance data.
+
+
+dmx_section_filter_t**
+ filter
+
+Pointer to the allocated filter.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENOSPC
+
+No filters of given type and length available.
+
+
+-EINVAL
+
+Bad parameters.
+
+
+
+release_filter()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int release_filter ( dmx_section_feed_t⋆ feed,
+ dmx_section_filter_t⋆ filter);
+
+
+PARAMETERS
+
+
+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.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-ENODEV
+
+No such filter allocated.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+start_filtering()
+DESCRIPTION
+
+
+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().
+
+
+SYNOPSIS
+
+
+int start_filtering ( dmx_section_feed_t⋆ feed );
+
+
+PARAMETERS
+
+
+dmx_section_feed_t*
+ feed
+
+Pointer to the section feed API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+stop_filtering()
+DESCRIPTION
+
+
+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.
+
+
+SYNOPSIS
+
+
+int stop_filtering ( dmx_section_feed_t⋆ feed );
+
+
+PARAMETERS
+
+
+dmx_section_feed_t*
+ feed
+
+Pointer to the section feed API and instance data.
+
+
+RETURNS
+
+
+0
+
+The function was completed without errors.
+
+
+-EINVAL
+
+Bad parameter.
+
+
+
+
--
cgit v1.3.1