drivers/media/dvb-core/demux.h

   1 /*
   2  * demux.h
   3  *
   4  * Copyright (c) 2002 Convergence GmbH
   5  *
   6  * based on code:
   7  * Copyright (c) 2000 Nokia Research Center
   8  *                    Tampere, FINLAND
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23  *
  24  */
  25
  26 #ifndef __DEMUX_H
  27 #define __DEMUX_H
  28
  29 #include <linux/types.h>
  30 #include <linux/errno.h>
  31 #include <linux/list.h>
  32 #include <linux/time.h>
  33 #include <linux/dvb/dmx.h>
  34
  35 /*--------------------------------------------------------------------------*/
  36 /* Common definitions */
  37 /*--------------------------------------------------------------------------*/
  38
  39 /*
  40  * DMX_MAX_FILTER_SIZE: Maximum length (in bytes) of a section/PES filter.
  41  */
  42
  43 #ifndef DMX_MAX_FILTER_SIZE
  44 #define DMX_MAX_FILTER_SIZE 18
  45 #endif
  46
  47 /*
  48  * DMX_MAX_SECFEED_SIZE: Maximum length (in bytes) of a private section feed filter.
  49  */
  50
  51 #ifndef DMX_MAX_SECTION_SIZE
  52 #define DMX_MAX_SECTION_SIZE 4096
  53 #endif
  54 #ifndef DMX_MAX_SECFEED_SIZE
  55 #define DMX_MAX_SECFEED_SIZE (DMX_MAX_SECTION_SIZE + 188)
  56 #endif
  57
  58 /*--------------------------------------------------------------------------*/
  59 /* TS packet reception */
  60 /*--------------------------------------------------------------------------*/
  61
  62 /* TS filter type for set() */
  63
  64 #define TS_PACKET       1   /* send TS packets (188 bytes) to callback (default) */
  65 #define TS_PAYLOAD_ONLY 2   /* in case TS_PACKET is set, only send the TS
  66                                payload (<=184 bytes per packet) to callback */
  67 #define TS_DECODER      4   /* send stream to built-in decoder (if present) */
  68 #define TS_DEMUX        8   /* in case TS_PACKET is set, send the TS to
  69                                the demux device, not to the dvr device */
  70
  71 /**
  72  * struct dmx_ts_feed - Structure that contains a TS feed filter
  73  *
  74  * @is_filtering:       Set to non-zero when filtering in progress
  75  * @parent:             pointer to struct dmx_demux
  76  * @priv:               pointer to private data of the API client
  77  * @set:                sets the TS filter
  78  * @start_filtering:    starts TS filtering
  79  * @stop_filtering:     stops TS filtering
  80  *
  81  * A TS feed is typically mapped to a hardware PID filter on the demux chip.
  82  * Using this API, the client can set the filtering properties to start/stop
  83  * filtering TS packets on a particular TS feed.
  84  */
  85 struct dmx_ts_feed {
  86         int is_filtering;
  87         struct dmx_demux *parent;
  88         void *priv;
  89         int (*set) (struct dmx_ts_feed *feed,
  90                     u16 pid,
  91                     int type,
  92                     enum dmx_ts_pes pes_type,
  93                     size_t circular_buffer_size,
  94                     struct timespec timeout);
  95         int (*start_filtering) (struct dmx_ts_feed* feed);
  96         int (*stop_filtering) (struct dmx_ts_feed* feed);
  97 };
  98
  99 /*--------------------------------------------------------------------------*/
 100 /* Section reception */
 101 /*--------------------------------------------------------------------------*/
 102
 103 /**
 104  * struct dmx_section_filter - Structure that describes a section filter
 105  *
 106  * @filter_value: Contains up to 16 bytes (128 bits) of the TS section header
 107  *                that will be matched by the section filter
 108  * @filter_mask:  Contains a 16 bytes (128 bits) filter mask with the bits
 109  *                specified by @filter_value that will be used on the filter
 110  *                match logic.
 111  * @filter_mode:  Contains a 16 bytes (128 bits) filter mode.
 112  * @parent:       Pointer to struct dmx_section_feed.
 113  * @priv:         Pointer to private data of the API client.
 114  *
 115  *
 116  * The @filter_mask controls which bits of @filter_value are compared with
 117  * the section headers/payload. On a binary value of 1 in filter_mask, the
 118  * corresponding bits are compared. The filter only accepts sections that are
 119  * equal to filter_value in all the tested bit positions.
 120  */
 121 struct dmx_section_filter {
 122         u8 filter_value [DMX_MAX_FILTER_SIZE];
 123         u8 filter_mask [DMX_MAX_FILTER_SIZE];
 124         u8 filter_mode [DMX_MAX_FILTER_SIZE];
 125         struct dmx_section_feed* parent; /* Back-pointer */
 126         void* priv; /* Pointer to private data of the API client */
 127 };
 128
 129 /**
 130  * struct dmx_section_feed - Structure that contains a section feed filter
 131  *
 132  * @is_filtering:       Set to non-zero when filtering in progress
 133  * @parent:             pointer to struct dmx_demux
 134  * @priv:               pointer to private data of the API client
 135  * @check_crc:          If non-zero, check the CRC values of filtered sections.
 136  * @set:                sets the section filter
 137  * @allocate_filter:    This function is used to allocate a section filter on
 138  *                      the demux. It should only be called when no filtering
 139  *                      is in progress on this section feed. If a filter cannot
 140  *                      be allocated, the function fails with -ENOSPC.
 141  * @release_filter:     This function releases all the resources of a
 142  *                      previously allocated section filter. The function
 143  *                      should not be called while filtering is in progress
 144  *                      on this section feed. After calling this function,
 145  *                      the caller should not try to dereference the filter
 146  *                      pointer.
 147  * @start_filtering:    starts section filtering
 148  * @stop_filtering:     stops section filtering
 149  *
 150  * A TS feed is typically mapped to a hardware PID filter on the demux chip.
 151  * Using this API, the client can set the filtering properties to start/stop
 152  * filtering TS packets on a particular TS feed.
 153  */
 154 struct dmx_section_feed {
 155         int is_filtering;
 156         struct dmx_demux* parent;
 157         void* priv;
 158
 159         int check_crc;
 160
 161         /* private: Used internally at dvb_demux.c */
 162         u32 crc_val;
 163
 164         u8 *secbuf;
 165         u8 secbuf_base[DMX_MAX_SECFEED_SIZE];
 166         u16 secbufp, seclen, tsfeedp;
 167
 168         /* public: */
 169         int (*set) (struct dmx_section_feed* feed,
 170                     u16 pid,
 171                     size_t circular_buffer_size,
 172                     int check_crc);
 173         int (*allocate_filter) (struct dmx_section_feed* feed,
 174                                 struct dmx_section_filter** filter);
 175         int (*release_filter) (struct dmx_section_feed* feed,
 176                                struct dmx_section_filter* filter);
 177         int (*start_filtering) (struct dmx_section_feed* feed);
 178         int (*stop_filtering) (struct dmx_section_feed* feed);
 179 };
 180
 181 /*--------------------------------------------------------------------------*/
 182 /* Callback functions */
 183 /*--------------------------------------------------------------------------*/
 184
 185 typedef int (*dmx_ts_cb) ( const u8 * buffer1,
 186                            size_t buffer1_length,
 187                            const u8 * buffer2,
 188                            size_t buffer2_length,
 189                            struct dmx_ts_feed* source);
 190
 191 typedef int (*dmx_section_cb) ( const u8 * buffer1,
 192                                 size_t buffer1_len,
 193                                 const u8 * buffer2,
 194                                 size_t buffer2_len,
 195                                 struct dmx_section_filter * source);
 196
 197 /*--------------------------------------------------------------------------*/
 198 /* DVB Front-End */
 199 /*--------------------------------------------------------------------------*/
 200
 201 /**
 202  * enum dmx_frontend_source - Used to identify the type of frontend
 203  *
 204  * @DMX_MEMORY_FE:      The source of the demux is memory. It means that
 205  *                      the MPEG-TS to be filtered comes from userspace,
 206  *                      via write() syscall.
 207  *
 208  * @DMX_FRONTEND_0:     The source of the demux is a frontend connected
 209  *                      to the demux.
 210  */
 211 enum dmx_frontend_source {
 212         DMX_MEMORY_FE,
 213         DMX_FRONTEND_0,
 214 };
 215
 216 /**
 217  * struct dmx_frontend - Structure that lists the frontends associated with
 218  *                       a demux
 219  *
 220  * @connectivity_list:  List of front-ends that can be connected to a
 221  *                      particular demux;
 222  * @source:             Type of the frontend.
 223  *
 224  * FIXME: this structure should likely be replaced soon by some
 225  *      media-controller based logic.
 226  */
 227 struct dmx_frontend {
 228         struct list_head connectivity_list;
 229         enum dmx_frontend_source source;
 230 };
 231
 232 /*--------------------------------------------------------------------------*/
 233 /* MPEG-2 TS Demux */
 234 /*--------------------------------------------------------------------------*/
 235
 236 /*
 237  * Flags OR'ed in the capabilities field of struct dmx_demux.
 238  */
 239
 240 #define DMX_TS_FILTERING                        1
 241 #define DMX_PES_FILTERING                       2
 242 #define DMX_SECTION_FILTERING                   4
 243 #define DMX_MEMORY_BASED_FILTERING              8    /* write() available */
 244 #define DMX_CRC_CHECKING                        16
 245 #define DMX_TS_DESCRAMBLING                     32
 246
 247 /*
 248  * Demux resource type identifier.
 249 */
 250
 251 /*
 252  * DMX_FE_ENTRY(): Casts elements in the list of registered
 253  * front-ends from the generic type struct list_head
 254  * to the type * struct dmx_frontend
 255  *.
 256 */
 257
 258 #define DMX_FE_ENTRY(list) list_entry(list, struct dmx_frontend, connectivity_list)
 259
 260 /**
 261  * struct dmx_demux - Structure that contains the demux capabilities and
 262  *                    callbacks.
 263  *
 264  * @capabilities: Bitfield of capability flags
 265  *
 266  * @frontend: Front-end connected to the demux
 267  *
 268  * @priv: Pointer to private data of the API client
 269  *
 270  * @open: This function reserves the demux for use by the caller and, if
 271  *      necessary, initializes the demux. When the demux is no longer needed,
 272  *      the function @close should be called. It should be possible for
 273  *      multiple clients to access the demux at the same time. Thus, the
 274  *      function implementation should increment the demux usage count when
 275  *      @open is called and decrement it when @close is called.
 276  *      The @demux function parameter contains a pointer to the demux API and
 277  *      instance data.
 278  *      It returns
 279  *              0 on success;
 280  *              -EUSERS, if maximum usage count was reached;
 281  *              -EINVAL, on bad parameter.
 282  *
 283  * @close: This function reserves the demux for use by the caller and, if
 284  *      necessary, initializes the demux. When the demux is no longer needed,
 285  *      the function @close should be called. It should be possible for
 286  *      multiple clients to access the demux at the same time. Thus, the
 287  *      function implementation should increment the demux usage count when
 288  *      @open is called and decrement it when @close is called.
 289  *      The @demux function parameter contains a pointer to the demux API and
 290  *      instance data.
 291  *      It returns
 292  *              0 on success;
 293  *              -ENODEV, if demux was not in use (e. g. no users);
 294  *              -EINVAL, on bad parameter.
 295  *
 296  * @write: This function provides the demux driver with a memory buffer
 297  *      containing TS packets. Instead of receiving TS packets from the DVB
 298  *      front-end, the demux driver software will read packets from memory.
 299  *      Any clients of this demux with active TS, PES or Section filters will
 300  *      receive filtered data via the Demux callback API (see 0). The function
 301  *      returns when all the data in the buffer has been consumed by the demux.
 302  *      Demux hardware typically cannot read TS from memory. If this is the
 303  *      case, memory-based filtering has to be implemented entirely in software.
 304  *      The @demux function parameter contains a pointer to the demux API and
 305  *      instance data.
 306  *      The @buf function parameter contains a pointer to the TS data in
 307  *      kernel-space memory.
 308  *      The @count function parameter contains the length of the TS data.
 309  *      It returns
 310  *              0 on success;
 311  *              -ERESTARTSYS, if mutex lock was interrupted;
 312  *              -EINTR, if a signal handling is pending;
 313  *              -ENODEV, if demux was removed;
 314  *              -EINVAL, on bad parameter.
 315  *
 316  * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS
 317  *      packets carrying a certain PID. The TS feed normally corresponds to a
 318  *      hardware PID filter on the demux chip.
 319  *      The @demux function parameter contains a pointer to the demux API and
 320  *      instance data.
 321  *      The @feed function parameter contains a pointer to the TS feed API and
 322  *      instance data.
 323  *      The @callback function parameter contains a pointer to the callback
 324  *      function for passing received TS packet.
 325  *      It returns
 326  *              0 on success;
 327  *              -ERESTARTSYS, if mutex lock was interrupted;
 328  *              -EBUSY, if no more TS feeds is available;
 329  *              -EINVAL, on bad parameter.
 330  *
 331  * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed.
 332  *      Any filtering in progress on the TS feed should be stopped before
 333  *      calling this function.
 334  *      The @demux function parameter contains a pointer to the demux API and
 335  *      instance data.
 336  *      The @feed function parameter contains a pointer to the TS feed API and
 337  *      instance data.
 338  *      It returns
 339  *              0 on success;
 340  *              -EINVAL on bad parameter.
 341  *
 342  * @allocate_section_feed: Allocates a new section feed, i.e. a demux resource
 343  *      for filtering and receiving sections. On platforms with hardware
 344  *      support for section filtering, a section feed is directly mapped to
 345  *      the demux HW. On other platforms, TS packets are first PID filtered in
 346  *      hardware and a hardware section filter then emulated in software. The
 347  *      caller obtains an API pointer of type dmx_section_feed_t as an out
 348  *      parameter. Using this API the caller can set filtering parameters and
 349  *      start receiving sections.
 350  *      The @demux function parameter contains a pointer to the demux API and
 351  *      instance data.
 352  *      The @feed function parameter contains a pointer to the TS feed API and
 353  *      instance data.
 354  *      The @callback function parameter contains a pointer to the callback
 355  *      function for passing received TS packet.
 356  *      It returns
 357  *              0 on success;
 358  *              -EBUSY, if no more TS feeds is available;
 359  *              -EINVAL, on bad parameter.
 360  *
 361  * @release_section_feed: Releases the resources allocated with
 362  *      @allocate_section_feed, including allocated filters. Any filtering in
 363  *      progress on the section feed should be stopped before calling this
 364  *      function.
 365  *      The @demux function parameter contains a pointer to the demux API and
 366  *      instance data.
 367  *      The @feed function parameter contains a pointer to the TS feed API and
 368  *      instance data.
 369  *      It returns
 370  *              0 on success;
 371  *              -EINVAL, on bad parameter.
 372  *
 373  * @add_frontend: Registers a connectivity between a demux and a front-end,
 374  *      i.e., indicates that the demux can be connected via a call to
 375  *      @connect_frontend to use the given front-end as a TS source. The
 376  *      client of this function has to allocate dynamic or static memory for
 377  *      the frontend structure and initialize its fields before calling this
 378  *      function. This function is normally called during the driver
 379  *      initialization. The caller must not free the memory of the frontend
 380  *      struct before successfully calling @remove_frontend.
 381  *      The @demux function parameter contains a pointer to the demux API and
 382  *      instance data.
 383  *      The @frontend function parameter contains a pointer to the front-end
 384  *      instance data.
 385  *      It returns
 386  *              0 on success;
 387  *              -EINVAL, on bad parameter.
 388  *
 389  * @remove_frontend: Indicates that the given front-end, registered by a call
 390  *      to @add_frontend, can no longer be connected as a TS source by this
 391  *      demux. The function should be called when a front-end driver or a demux
 392  *      driver is removed from the system. If the front-end is in use, the
 393  *      function fails with the return value of -EBUSY. After successfully
 394  *      calling this function, the caller can free the memory of the frontend
 395  *      struct if it was dynamically allocated before the @add_frontend
 396  *      operation.
 397  *      The @demux function parameter contains a pointer to the demux API and
 398  *      instance data.
 399  *      The @frontend function parameter contains a pointer to the front-end
 400  *      instance data.
 401  *      It returns
 402  *              0 on success;
 403  *              -ENODEV, if the front-end was not found,
 404  *              -EINVAL, on bad parameter.
 405  *
 406  * @get_frontends: Provides the APIs of the front-ends that have been
 407  *      registered for this demux. Any of the front-ends obtained with this
 408  *      call can be used as a parameter for @connect_frontend. The include
 409  *      file demux.h contains the macro DMX_FE_ENTRY() for converting an
 410  *      element of the generic type struct &list_head * to the type
 411  *      struct &dmx_frontend *. The caller must not free the memory of any of
 412  *      the elements obtained via this function call.
 413  *      The @demux function parameter contains a pointer to the demux API and
 414  *      instance data.
 415  *      It returns a struct list_head pointer to the list of front-end
 416  *      interfaces, or NULL in the case of an empty list.
 417  *
 418  * @connect_frontend: Connects the TS output of the front-end to the input of
 419  *      the demux. A demux can only be connected to a front-end registered to
 420  *      the demux with the function @add_frontend. It may or may not be
 421  *      possible to connect multiple demuxes to the same front-end, depending
 422  *      on the capabilities of the HW platform. When not used, the front-end
 423  *      should be released by calling @disconnect_frontend.
 424  *      The @demux function parameter contains a pointer to the demux API and
 425  *      instance data.
 426  *      The @frontend function parameter contains a pointer to the front-end
 427  *      instance data.
 428  *      It returns
 429  *              0 on success;
 430  *              -EINVAL, on bad parameter.
 431  *
 432  * @disconnect_frontend: Disconnects the demux and a front-end previously
 433  *      connected by a @connect_frontend call.
 434  *      The @demux function parameter contains a pointer to the demux API and
 435  *      instance data.
 436  *      It returns
 437  *              0 on success;
 438  *              -EINVAL on bad parameter.
 439  *
 440  * @get_pes_pids: Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0,
 441  *      DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0.
 442  *      The @demux function parameter contains a pointer to the demux API and
 443  *      instance data.
 444  *      The @pids function parameter contains an array with five u16 elements
 445  *      where the PIDs will be stored.
 446  *      It returns
 447  *              0 on success;
 448  *              -EINVAL on bad parameter.
 449  */
 450
 451 struct dmx_demux {
 452         u32 capabilities;
 453         struct dmx_frontend* frontend;
 454         void* priv;
 455         int (*open) (struct dmx_demux* demux);
 456         int (*close) (struct dmx_demux* demux);
 457         int (*write) (struct dmx_demux* demux, const char __user *buf, size_t count);
 458         int (*allocate_ts_feed) (struct dmx_demux* demux,
 459                                  struct dmx_ts_feed** feed,
 460                                  dmx_ts_cb callback);
 461         int (*release_ts_feed) (struct dmx_demux* demux,
 462                                 struct dmx_ts_feed* feed);
 463         int (*allocate_section_feed) (struct dmx_demux* demux,
 464                                       struct dmx_section_feed** feed,
 465                                       dmx_section_cb callback);
 466         int (*release_section_feed) (struct dmx_demux* demux,
 467                                      struct dmx_section_feed* feed);
 468         int (*add_frontend) (struct dmx_demux* demux,
 469                              struct dmx_frontend* frontend);
 470         int (*remove_frontend) (struct dmx_demux* demux,
 471                                 struct dmx_frontend* frontend);
 472         struct list_head* (*get_frontends) (struct dmx_demux* demux);
 473         int (*connect_frontend) (struct dmx_demux* demux,
 474                                  struct dmx_frontend* frontend);
 475         int (*disconnect_frontend) (struct dmx_demux* demux);
 476
 477         int (*get_pes_pids) (struct dmx_demux* demux, u16 *pids);
 478
 479         /* private: Not used upstream and never documented */
 480 #if 0
 481         int (*get_caps) (struct dmx_demux* demux, struct dmx_caps *caps);
 482         int (*set_source) (struct dmx_demux* demux, const dmx_source_t *src);
 483 #endif
 484         /*
 485          * private: Only used at av7110, to read some data from firmware.
 486          *      As this was never documented, we have no clue about what's
 487          *      there, and its usage on other drivers aren't encouraged.
 488          */
 489         int (*get_stc) (struct dmx_demux* demux, unsigned int num,
 490                         u64 *stc, unsigned int *base);
 491 };
 492
 493 #endif /* #ifndef __DEMUX_H */