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 49 * filter. 50 */ 51 52#ifndef DMX_MAX_SECTION_SIZE 53#define DMX_MAX_SECTION_SIZE 4096 54#endif 55#ifndef DMX_MAX_SECFEED_SIZE 56#define DMX_MAX_SECFEED_SIZE (DMX_MAX_SECTION_SIZE + 188) 57#endif 58 59/* 60 * TS packet reception 61 */ 62 63/** 64 * enum ts_filter_type - filter type bitmap for dmx_ts_feed.set() 65 * 66 * @TS_PACKET: Send TS packets (188 bytes) to callback (default). 67 * @TS_PAYLOAD_ONLY: In case TS_PACKET is set, only send the TS payload 68 * (<=184 bytes per packet) to callback 69 * @TS_DECODER: Send stream to built-in decoder (if present). 70 * @TS_DEMUX: In case TS_PACKET is set, send the TS to the demux 71 * device, not to the dvr device 72 */ 73enum ts_filter_type { 74 TS_PACKET = 1, 75 TS_PAYLOAD_ONLY = 2, 76 TS_DECODER = 4, 77 TS_DEMUX = 8, 78}; 79 80/** 81 * struct dmx_ts_feed - Structure that contains a TS feed filter 82 * 83 * @is_filtering: Set to non-zero when filtering in progress 84 * @parent: pointer to struct dmx_demux 85 * @priv: pointer to private data of the API client 86 * @set: sets the TS filter 87 * @start_filtering: starts TS filtering 88 * @stop_filtering: stops TS filtering 89 * 90 * A TS feed is typically mapped to a hardware PID filter on the demux chip. 91 * Using this API, the client can set the filtering properties to start/stop 92 * filtering TS packets on a particular TS feed. 93 */ 94struct dmx_ts_feed { 95 int is_filtering; 96 struct dmx_demux *parent; 97 void *priv; 98 int (*set)(struct dmx_ts_feed *feed, 99 u16 pid, 100 int type, 101 enum dmx_ts_pes pes_type, 102 size_t circular_buffer_size, 103 struct timespec timeout); 104 int (*start_filtering)(struct dmx_ts_feed *feed); 105 int (*stop_filtering)(struct dmx_ts_feed *feed); 106}; 107 108/* 109 * Section reception 110 */ 111 112/** 113 * struct dmx_section_filter - Structure that describes a section filter 114 * 115 * @filter_value: Contains up to 16 bytes (128 bits) of the TS section header 116 * that will be matched by the section filter 117 * @filter_mask: Contains a 16 bytes (128 bits) filter mask with the bits 118 * specified by @filter_value that will be used on the filter 119 * match logic. 120 * @filter_mode: Contains a 16 bytes (128 bits) filter mode. 121 * @parent: Pointer to struct dmx_section_feed. 122 * @priv: Pointer to private data of the API client. 123 * 124 * 125 * The @filter_mask controls which bits of @filter_value are compared with 126 * the section headers/payload. On a binary value of 1 in filter_mask, the 127 * corresponding bits are compared. The filter only accepts sections that are 128 * equal to filter_value in all the tested bit positions. 129 */ 130struct dmx_section_filter { 131 u8 filter_value[DMX_MAX_FILTER_SIZE]; 132 u8 filter_mask[DMX_MAX_FILTER_SIZE]; 133 u8 filter_mode[DMX_MAX_FILTER_SIZE]; 134 struct dmx_section_feed *parent; /* Back-pointer */ 135 void *priv; /* Pointer to private data of the API client */ 136}; 137 138/** 139 * struct dmx_section_feed - Structure that contains a section feed filter 140 * 141 * @is_filtering: Set to non-zero when filtering in progress 142 * @parent: pointer to struct dmx_demux 143 * @priv: pointer to private data of the API client 144 * @check_crc: If non-zero, check the CRC values of filtered sections. 145 * @set: sets the section filter 146 * @allocate_filter: This function is used to allocate a section filter on 147 * the demux. It should only be called when no filtering 148 * is in progress on this section feed. If a filter cannot 149 * be allocated, the function fails with -ENOSPC. 150 * @release_filter: This function releases all the resources of a 151 * previously allocated section filter. The function 152 * should not be called while filtering is in progress 153 * on this section feed. After calling this function, 154 * the caller should not try to dereference the filter 155 * pointer. 156 * @start_filtering: starts section filtering 157 * @stop_filtering: stops section filtering 158 * 159 * A TS feed is typically mapped to a hardware PID filter on the demux chip. 160 * Using this API, the client can set the filtering properties to start/stop 161 * filtering TS packets on a particular TS feed. 162 */ 163struct dmx_section_feed { 164 int is_filtering; 165 struct dmx_demux *parent; 166 void *priv; 167 168 int check_crc; 169 170 /* private: Used internally at dvb_demux.c */ 171 u32 crc_val; 172 173 u8 *secbuf; 174 u8 secbuf_base[DMX_MAX_SECFEED_SIZE]; 175 u16 secbufp, seclen, tsfeedp; 176 177 /* public: */ 178 int (*set)(struct dmx_section_feed *feed, 179 u16 pid, 180 size_t circular_buffer_size, 181 int check_crc); 182 int (*allocate_filter)(struct dmx_section_feed *feed, 183 struct dmx_section_filter **filter); 184 int (*release_filter)(struct dmx_section_feed *feed, 185 struct dmx_section_filter *filter); 186 int (*start_filtering)(struct dmx_section_feed *feed); 187 int (*stop_filtering)(struct dmx_section_feed *feed); 188}; 189 190/* 191 * Callback functions 192 */ 193 194/** 195 * typedef dmx_ts_cb - DVB demux TS filter callback function prototype 196 * 197 * @buffer1: Pointer to the start of the filtered TS packets. 198 * @buffer1_length: Length of the TS data in buffer1. 199 * @buffer2: Pointer to the tail of the filtered TS packets, or NULL. 200 * @buffer2_length: Length of the TS data in buffer2. 201 * @source: Indicates which TS feed is the source of the callback. 202 * 203 * This function callback prototype, provided by the client of the demux API, 204 * is called from the demux code. The function is only called when filtering 205 * on ae TS feed has been enabled using the start_filtering() function at 206 * the &dmx_demux. 207 * Any TS packets that match the filter settings are copied to a circular 208 * buffer. The filtered TS packets are delivered to the client using this 209 * callback function. The size of the circular buffer is controlled by the 210 * circular_buffer_size parameter of the &dmx_ts_feed.@set function. 211 * It is expected that the @buffer1 and @buffer2 callback parameters point to 212 * addresses within the circular buffer, but other implementations are also 213 * possible. Note that the called party should not try to free the memory 214 * the @buffer1 and @buffer2 parameters point to. 215 * 216 * When this function is called, the @buffer1 parameter typically points to 217 * the start of the first undelivered TS packet within a circular buffer. 218 * The @buffer2 buffer parameter is normally NULL, except when the received 219 * TS packets have crossed the last address of the circular buffer and 220 * ”wrapped” to the beginning of the buffer. In the latter case the @buffer1 221 * parameter would contain an address within the circular buffer, while the 222 * @buffer2 parameter would contain the first address of the circular buffer. 223 * The number of bytes delivered with this function (i.e. @buffer1_length + 224 * @buffer2_length) is usually equal to the value of callback_length parameter 225 * given in the set() function, with one exception: if a timeout occurs before 226 * receiving callback_length bytes of TS data, any undelivered packets are 227 * immediately delivered to the client by calling this function. The timeout 228 * duration is controlled by the set() function in the TS Feed API. 229 * 230 * If a TS packet is received with errors that could not be fixed by the 231 * TS-level forward error correction (FEC), the Transport_error_indicator 232 * flag of the TS packet header should be set. The TS packet should not be 233 * discarded, as the error can possibly be corrected by a higher layer 234 * protocol. If the called party is slow in processing the callback, it 235 * is possible that the circular buffer eventually fills up. If this happens, 236 * the demux driver should discard any TS packets received while the buffer 237 * is full and return -EOVERFLOW. 238 * 239 * The type of data returned to the callback can be selected by the 240 * &dmx_ts_feed.@set function. The type parameter decides if the raw 241 * TS packet (TS_PACKET) or just the payload (TS_PACKET|TS_PAYLOAD_ONLY) 242 * should be returned. If additionally the TS_DECODER bit is set the stream 243 * will also be sent to the hardware MPEG decoder. 244 * 245 * Return: 246 * 0, on success; 247 * -EOVERFLOW, on buffer overflow. 248 */ 249typedef int (*dmx_ts_cb)(const u8 *buffer1, 250 size_t buffer1_length, 251 const u8 *buffer2, 252 size_t buffer2_length, 253 struct dmx_ts_feed *source); 254 255/** 256 * typedef dmx_section_cb - DVB demux TS filter callback function prototype 257 * 258 * @buffer1: Pointer to the start of the filtered section, e.g. 259 * within the circular buffer of the demux driver. 260 * @buffer1_len: Length of the filtered section data in @buffer1, 261 * including headers and CRC. 262 * @buffer2: Pointer to the tail of the filtered section data, 263 * or NULL. Useful to handle the wrapping of a 264 * circular buffer. 265 * @buffer2_len: Length of the filtered section data in @buffer2, 266 * including headers and CRC. 267 * @source: Indicates which section feed is the source of the 268 * callback. 269 * 270 * This function callback prototype, provided by the client of the demux API, 271 * is called from the demux code. The function is only called when 272 * filtering of sections has been enabled using the function 273 * &dmx_ts_feed.@start_filtering. When the demux driver has received a 274 * complete section that matches at least one section filter, the client 275 * is notified via this callback function. Normally this function is called 276 * for each received section; however, it is also possible to deliver 277 * multiple sections with one callback, for example when the system load 278 * is high. If an error occurs while receiving a section, this 279 * function should be called with the corresponding error type set in the 280 * success field, whether or not there is data to deliver. The Section Feed 281 * implementation should maintain a circular buffer for received sections. 282 * However, this is not necessary if the Section Feed API is implemented as 283 * a client of the TS Feed API, because the TS Feed implementation then 284 * buffers the received data. The size of the circular buffer can be 285 * configured using the &dmx_ts_feed.@set function in the Section Feed API. 286 * If there is no room in the circular buffer when a new section is received, 287 * the section must be discarded. If this happens, the value of the success 288 * parameter should be DMX_OVERRUN_ERROR on the next callback. 289 */ 290typedef int (*dmx_section_cb)(const u8 *buffer1, 291 size_t buffer1_len, 292 const u8 *buffer2, 293 size_t buffer2_len, 294 struct dmx_section_filter *source); 295 296/*--------------------------------------------------------------------------*/ 297/* DVB Front-End */ 298/*--------------------------------------------------------------------------*/ 299 300/** 301 * enum dmx_frontend_source - Used to identify the type of frontend 302 * 303 * @DMX_MEMORY_FE: The source of the demux is memory. It means that 304 * the MPEG-TS to be filtered comes from userspace, 305 * via write() syscall. 306 * 307 * @DMX_FRONTEND_0: The source of the demux is a frontend connected 308 * to the demux. 309 */ 310enum dmx_frontend_source { 311 DMX_MEMORY_FE, 312 DMX_FRONTEND_0, 313}; 314 315/** 316 * struct dmx_frontend - Structure that lists the frontends associated with 317 * a demux 318 * 319 * @connectivity_list: List of front-ends that can be connected to a 320 * particular demux; 321 * @source: Type of the frontend. 322 * 323 * FIXME: this structure should likely be replaced soon by some 324 * media-controller based logic. 325 */ 326struct dmx_frontend { 327 struct list_head connectivity_list; 328 enum dmx_frontend_source source; 329}; 330 331/* 332 * MPEG-2 TS Demux 333 */ 334 335/** 336 * enum dmx_demux_caps - MPEG-2 TS Demux capabilities bitmap 337 * 338 * @DMX_TS_FILTERING: set if TS filtering is supported; 339 * @DMX_SECTION_FILTERING: set if section filtering is supported; 340 * @DMX_MEMORY_BASED_FILTERING: set if write() available. 341 * 342 * Those flags are OR'ed in the &dmx_demux.&capabilities field 343 */ 344enum dmx_demux_caps { 345 DMX_TS_FILTERING = 1, 346 DMX_SECTION_FILTERING = 4, 347 DMX_MEMORY_BASED_FILTERING = 8, 348}; 349 350/* 351 * Demux resource type identifier. 352*/ 353 354/* 355 * DMX_FE_ENTRY(): Casts elements in the list of registered 356 * front-ends from the generic type struct list_head 357 * to the type * struct dmx_frontend 358 *. 359*/ 360 361#define DMX_FE_ENTRY(list) \ 362 list_entry(list, struct dmx_frontend, connectivity_list) 363 364/** 365 * struct dmx_demux - Structure that contains the demux capabilities and 366 * callbacks. 367 * 368 * @capabilities: Bitfield of capability flags. 369 * 370 * @frontend: Front-end connected to the demux 371 * 372 * @priv: Pointer to private data of the API client 373 * 374 * @open: This function reserves the demux for use by the caller and, if 375 * necessary, initializes the demux. When the demux is no longer needed, 376 * the function @close should be called. It should be possible for 377 * multiple clients to access the demux at the same time. Thus, the 378 * function implementation should increment the demux usage count when 379 * @open is called and decrement it when @close is called. 380 * The @demux function parameter contains a pointer to the demux API and 381 * instance data. 382 * It returns 383 * 0 on success; 384 * -EUSERS, if maximum usage count was reached; 385 * -EINVAL, on bad parameter. 386 * 387 * @close: This function reserves the demux for use by the caller and, if 388 * necessary, initializes the demux. When the demux is no longer needed, 389 * the function @close should be called. It should be possible for 390 * multiple clients to access the demux at the same time. Thus, the 391 * function implementation should increment the demux usage count when 392 * @open is called and decrement it when @close is called. 393 * The @demux function parameter contains a pointer to the demux API and 394 * instance data. 395 * It returns 396 * 0 on success; 397 * -ENODEV, if demux was not in use (e. g. no users); 398 * -EINVAL, on bad parameter. 399 * 400 * @write: This function provides the demux driver with a memory buffer 401 * containing TS packets. Instead of receiving TS packets from the DVB 402 * front-end, the demux driver software will read packets from memory. 403 * Any clients of this demux with active TS, PES or Section filters will 404 * receive filtered data via the Demux callback API (see 0). The function 405 * returns when all the data in the buffer has been consumed by the demux. 406 * Demux hardware typically cannot read TS from memory. If this is the 407 * case, memory-based filtering has to be implemented entirely in software. 408 * The @demux function parameter contains a pointer to the demux API and 409 * instance data. 410 * The @buf function parameter contains a pointer to the TS data in 411 * kernel-space memory. 412 * The @count function parameter contains the length of the TS data. 413 * It returns 414 * 0 on success; 415 * -ERESTARTSYS, if mutex lock was interrupted; 416 * -EINTR, if a signal handling is pending; 417 * -ENODEV, if demux was removed; 418 * -EINVAL, on bad parameter. 419 * 420 * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS 421 * packets carrying a certain PID. The TS feed normally corresponds to a 422 * hardware PID filter on the demux chip. 423 * The @demux function parameter contains a pointer to the demux API and 424 * instance data. 425 * The @feed function parameter contains a pointer to the TS feed API and 426 * instance data. 427 * The @callback function parameter contains a pointer to the callback 428 * function for passing received TS packet. 429 * It returns 430 * 0 on success; 431 * -ERESTARTSYS, if mutex lock was interrupted; 432 * -EBUSY, if no more TS feeds is available; 433 * -EINVAL, on bad parameter. 434 * 435 * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed. 436 * Any filtering in progress on the TS feed should be stopped before 437 * calling this function. 438 * The @demux function parameter contains a pointer to the demux API and 439 * instance data. 440 * The @feed function parameter contains a pointer to the TS feed API and 441 * instance data. 442 * It returns 443 * 0 on success; 444 * -EINVAL on bad parameter. 445 * 446 * @allocate_section_feed: Allocates a new section feed, i.e. a demux resource 447 * for filtering and receiving sections. On platforms with hardware 448 * support for section filtering, a section feed is directly mapped to 449 * the demux HW. On other platforms, TS packets are first PID filtered in 450 * hardware and a hardware section filter then emulated in software. The 451 * caller obtains an API pointer of type dmx_section_feed_t as an out 452 * parameter. Using this API the caller can set filtering parameters and 453 * start receiving sections. 454 * The @demux function parameter contains a pointer to the demux API and 455 * instance data. 456 * The @feed function parameter contains a pointer to the TS feed API and 457 * instance data. 458 * The @callback function parameter contains a pointer to the callback 459 * function for passing received TS packet. 460 * It returns 461 * 0 on success; 462 * -EBUSY, if no more TS feeds is available; 463 * -EINVAL, on bad parameter. 464 * 465 * @release_section_feed: Releases the resources allocated with 466 * @allocate_section_feed, including allocated filters. Any filtering in 467 * progress on the section feed should be stopped before calling this 468 * function. 469 * The @demux function parameter contains a pointer to the demux API and 470 * instance data. 471 * The @feed function parameter contains a pointer to the TS feed API and 472 * instance data. 473 * It returns 474 * 0 on success; 475 * -EINVAL, on bad parameter. 476 * 477 * @add_frontend: Registers a connectivity between a demux and a front-end, 478 * i.e., indicates that the demux can be connected via a call to 479 * @connect_frontend to use the given front-end as a TS source. The 480 * client of this function has to allocate dynamic or static memory for 481 * the frontend structure and initialize its fields before calling this 482 * function. This function is normally called during the driver 483 * initialization. The caller must not free the memory of the frontend 484 * struct before successfully calling @remove_frontend. 485 * The @demux function parameter contains a pointer to the demux API and 486 * instance data. 487 * The @frontend function parameter contains a pointer to the front-end 488 * instance data. 489 * It returns 490 * 0 on success; 491 * -EINVAL, on bad parameter. 492 * 493 * @remove_frontend: Indicates that the given front-end, registered by a call 494 * to @add_frontend, can no longer be connected as a TS source by this 495 * demux. The function should be called when a front-end driver or a demux 496 * driver is removed from the system. If the front-end is in use, the 497 * function fails with the return value of -EBUSY. After successfully 498 * calling this function, the caller can free the memory of the frontend 499 * struct if it was dynamically allocated before the @add_frontend 500 * operation. 501 * The @demux function parameter contains a pointer to the demux API and 502 * instance data. 503 * The @frontend function parameter contains a pointer to the front-end 504 * instance data. 505 * It returns 506 * 0 on success; 507 * -ENODEV, if the front-end was not found, 508 * -EINVAL, on bad parameter. 509 * 510 * @get_frontends: Provides the APIs of the front-ends that have been 511 * registered for this demux. Any of the front-ends obtained with this 512 * call can be used as a parameter for @connect_frontend. The include 513 * file demux.h contains the macro DMX_FE_ENTRY() for converting an 514 * element of the generic type struct &list_head * to the type 515 * struct &dmx_frontend *. The caller must not free the memory of any of 516 * the elements obtained via this function call. 517 * The @demux function parameter contains a pointer to the demux API and 518 * instance data. 519 * It returns a struct list_head pointer to the list of front-end 520 * interfaces, or NULL in the case of an empty list. 521 * 522 * @connect_frontend: Connects the TS output of the front-end to the input of 523 * the demux. A demux can only be connected to a front-end registered to 524 * the demux with the function @add_frontend. It may or may not be 525 * possible to connect multiple demuxes to the same front-end, depending 526 * on the capabilities of the HW platform. When not used, the front-end 527 * should be released by calling @disconnect_frontend. 528 * The @demux function parameter contains a pointer to the demux API and 529 * instance data. 530 * The @frontend function parameter contains a pointer to the front-end 531 * instance data. 532 * It returns 533 * 0 on success; 534 * -EINVAL, on bad parameter. 535 * 536 * @disconnect_frontend: Disconnects the demux and a front-end previously 537 * connected by a @connect_frontend call. 538 * The @demux function parameter contains a pointer to the demux API and 539 * instance data. 540 * It returns 541 * 0 on success; 542 * -EINVAL on bad parameter. 543 * 544 * @get_pes_pids: Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0, 545 * DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0. 546 * The @demux function parameter contains a pointer to the demux API and 547 * instance data. 548 * The @pids function parameter contains an array with five u16 elements 549 * where the PIDs will be stored. 550 * It returns 551 * 0 on success; 552 * -EINVAL on bad parameter. 553 */ 554 555struct dmx_demux { 556 enum dmx_demux_caps capabilities; 557 struct dmx_frontend *frontend; 558 void *priv; 559 int (*open)(struct dmx_demux *demux); 560 int (*close)(struct dmx_demux *demux); 561 int (*write)(struct dmx_demux *demux, const char __user *buf, 562 size_t count); 563 int (*allocate_ts_feed)(struct dmx_demux *demux, 564 struct dmx_ts_feed **feed, 565 dmx_ts_cb callback); 566 int (*release_ts_feed)(struct dmx_demux *demux, 567 struct dmx_ts_feed *feed); 568 int (*allocate_section_feed)(struct dmx_demux *demux, 569 struct dmx_section_feed **feed, 570 dmx_section_cb callback); 571 int (*release_section_feed)(struct dmx_demux *demux, 572 struct dmx_section_feed *feed); 573 int (*add_frontend)(struct dmx_demux *demux, 574 struct dmx_frontend *frontend); 575 int (*remove_frontend)(struct dmx_demux *demux, 576 struct dmx_frontend *frontend); 577 struct list_head *(*get_frontends)(struct dmx_demux *demux); 578 int (*connect_frontend)(struct dmx_demux *demux, 579 struct dmx_frontend *frontend); 580 int (*disconnect_frontend)(struct dmx_demux *demux); 581 582 int (*get_pes_pids)(struct dmx_demux *demux, u16 *pids); 583 584 /* private: Not used upstream and never documented */ 585#if 0 586 int (*get_caps)(struct dmx_demux *demux, struct dmx_caps *caps); 587 int (*set_source)(struct dmx_demux *demux, const dmx_source_t *src); 588#endif 589 /* 590 * private: Only used at av7110, to read some data from firmware. 591 * As this was never documented, we have no clue about what's 592 * there, and its usage on other drivers aren't encouraged. 593 */ 594 int (*get_stc)(struct dmx_demux *demux, unsigned int num, 595 u64 *stc, unsigned int *base); 596}; 597 598#endif /* #ifndef __DEMUX_H */ 599