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