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