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