blob: 6d3b95b8939db2bf07eab47ea1aef197d2d86379 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/*
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>
Andreas Oberritterc0510052005-09-09 13:02:21 -070033#include <linux/dvb/dmx.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -070034
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020035/**
Mauro Carvalho Chehab6747b392015-11-04 12:07:02 -020036 * DOC: Digital TV Demux
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020037 *
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020038 * 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
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020042 * drivers/media/dvb-core.
43 *
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020044 * The demux kABI should be implemented for each demux in the system. It is
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020045 * used to select the TS source of a demux and to manage the demux resources.
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020046 * When the demux client allocates a resource via the demux kABI, it receives
47 * a pointer to the kABI of that resource.
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020048 *
49 * Each demux receives its TS input from a DVB front-end or from memory, as
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020050 * set via this demux kABI. In a system with more than one front-end, the kABI
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020051 * 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 *
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020054 * 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.
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020057 *
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,
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020062 * but not PES filtering. The kABI client is expected to check the value of any
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020063 * 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
Mauro Carvalho Chehab03946b22015-11-10 11:14:52 -020074 * bottom half context. Thus, if a demux kABI function is called from network
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -020075 * device code, the function must not sleep.
76 */
77
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -030078/*
79 * Common definitions
80 */
Linus Torvalds1da177e2005-04-16 15:20:36 -070081
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/*
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -030091 * DMX_MAX_SECFEED_SIZE: Maximum length (in bytes) of a private section feed
92 * filter.
Linus Torvalds1da177e2005-04-16 15:20:36 -070093 */
94
Mark Adamsb3967d62005-11-08 21:35:50 -080095#ifndef DMX_MAX_SECTION_SIZE
96#define DMX_MAX_SECTION_SIZE 4096
97#endif
Linus Torvalds1da177e2005-04-16 15:20:36 -070098#ifndef DMX_MAX_SECFEED_SIZE
Mark Adamsb3967d62005-11-08 21:35:50 -080099#define DMX_MAX_SECFEED_SIZE (DMX_MAX_SECTION_SIZE + 188)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100#endif
101
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300102/*
103 * TS packet reception
104 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700105
Mauro Carvalho Chehab0e6f2d12015-10-08 17:21:48 -0300106/**
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 */
116enum ts_filter_type {
117 TS_PACKET = 1,
118 TS_PAYLOAD_ONLY = 2,
119 TS_DECODER = 4,
120 TS_DEMUX = 8,
121};
Linus Torvalds1da177e2005-04-16 15:20:36 -0700122
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300123/**
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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700137struct dmx_ts_feed {
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300138 int is_filtering;
139 struct dmx_demux *parent;
140 void *priv;
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300141 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);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149};
150
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300151/*
152 * Section reception
153 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700154
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300155/**
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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700173struct dmx_section_filter {
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300174 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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700179};
180
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300181/**
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
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300194 * previously allocated section filter. The function
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300195 * 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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700206struct dmx_section_feed {
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300207 int is_filtering;
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300208 struct dmx_demux *parent;
209 void *priv;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700210
Mauro Carvalho Chehabafd1a0c2005-12-12 00:37:27 -0800211 int check_crc;
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300212
213 /* private: Used internally at dvb_demux.c */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700214 u32 crc_val;
215
Mauro Carvalho Chehabafd1a0c2005-12-12 00:37:27 -0800216 u8 *secbuf;
217 u8 secbuf_base[DMX_MAX_SECFEED_SIZE];
218 u16 secbufp, seclen, tsfeedp;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700219
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300220 /* public: */
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300221 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);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700231};
232
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -0200233/**
Mauro Carvalho Chehab6747b392015-11-04 12:07:02 -0200234 * DOC: Demux Callback
Mauro Carvalho Chehab7b6e55b2015-11-04 11:07:09 -0200235 *
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.
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300255 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700256
Mauro Carvalho Chehab0cf35e82015-10-08 17:05:11 -0300257/**
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 */
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300312typedef 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);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700317
Mauro Carvalho Chehab4be45fb2015-10-10 10:22:20 -0300318/**
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 */
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300353typedef int (*dmx_section_cb)(const u8 *buffer1,
354 size_t buffer1_len,
355 const u8 *buffer2,
356 size_t buffer2_len,
Mauro Carvalho Chehab4be45fb2015-10-10 10:22:20 -0300357 struct dmx_section_filter *source);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700358
359/*--------------------------------------------------------------------------*/
360/* DVB Front-End */
361/*--------------------------------------------------------------------------*/
362
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300363/**
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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700373enum dmx_frontend_source {
374 DMX_MEMORY_FE,
375 DMX_FRONTEND_0,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700376};
377
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300378/**
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 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700389struct dmx_frontend {
Mauro Carvalho Chehab548e5ae2015-10-07 16:11:03 -0300390 struct list_head connectivity_list;
Mauro Carvalho Chehabafd1a0c2005-12-12 00:37:27 -0800391 enum dmx_frontend_source source;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700392};
393
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300394/*
395 * MPEG-2 TS Demux
396 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700397
Mauro Carvalho Chehab9be91db2015-10-08 17:33:47 -0300398/**
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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700406 */
Mauro Carvalho Chehab9be91db2015-10-08 17:33:47 -0300407enum dmx_demux_caps {
408 DMX_TS_FILTERING = 1,
409 DMX_SECTION_FILTERING = 4,
410 DMX_MEMORY_BASED_FILTERING = 8,
411};
Linus Torvalds1da177e2005-04-16 15:20:36 -0700412
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
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300424#define DMX_FE_ENTRY(list) \
425 list_entry(list, struct dmx_frontend, connectivity_list)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700426
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300427/**
428 * struct dmx_demux - Structure that contains the demux capabilities and
429 * callbacks.
430 *
Mauro Carvalho Chehab9be91db2015-10-08 17:33:47 -0300431 * @capabilities: Bitfield of capability flags.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300432 *
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,
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300439 * the function @close should be called. It should be possible for
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300440 * multiple clients to access the demux at the same time. Thus, the
441 * function implementation should increment the demux usage count when
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300442 * @open is called and decrement it when @close is called.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300443 * The @demux function parameter contains a pointer to the demux API and
444 * instance data.
445 * It returns
446 * 0 on success;
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300447 * -EUSERS, if maximum usage count was reached;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300448 * -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,
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300452 * the function @close should be called. It should be possible for
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300453 * multiple clients to access the demux at the same time. Thus, the
454 * function implementation should increment the demux usage count when
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300455 * @open is called and decrement it when @close is called.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300456 * The @demux function parameter contains a pointer to the demux API and
457 * instance data.
458 * It returns
459 * 0 on success;
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300460 * -ENODEV, if demux was not in use (e. g. no users);
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300461 * -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;
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300478 * -ERESTARTSYS, if mutex lock was interrupted;
479 * -EINTR, if a signal handling is pending;
480 * -ENODEV, if demux was removed;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300481 * -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;
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300494 * -ERESTARTSYS, if mutex lock was interrupted;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300495 * -EBUSY, if no more TS feeds is available;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300496 * -EINVAL, on bad parameter.
497 *
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300498 * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300499 * 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;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300526 * -EINVAL, on bad parameter.
527 *
528 * @release_section_feed: Releases the resources allocated with
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300529 * @allocate_section_feed, including allocated filters. Any filtering in
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300530 * 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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300542 * @connect_frontend to use the given front-end as a TS source. The
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300543 * 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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300547 * struct before successfully calling @remove_frontend.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300548 * 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;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300554 * -EINVAL, on bad parameter.
555 *
556 * @remove_frontend: Indicates that the given front-end, registered by a call
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300557 * to @add_frontend, can no longer be connected as a TS source by this
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300558 * 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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300562 * struct if it was dynamically allocated before the @add_frontend
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300563 * 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;
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300570 * -ENODEV, if the front-end was not found,
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300571 * -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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300575 * call can be used as a parameter for @connect_frontend. The include
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300576 * file demux.h contains the macro DMX_FE_ENTRY() for converting an
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300577 * element of the generic type struct &list_head * to the type
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300578 * struct &dmx_frontend *. The caller must not free the memory of any of
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300579 * the elements obtained via this function call.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300580 * 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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300587 * the demux with the function @add_frontend. It may or may not be
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300588 * 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
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300590 * should be released by calling @disconnect_frontend.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300591 * 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;
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300597 * -EINVAL, on bad parameter.
598 *
599 * @disconnect_frontend: Disconnects the demux and a front-end previously
Mauro Carvalho Chehab28cff822015-10-06 15:30:46 -0300600 * connected by a @connect_frontend call.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300601 * 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.
Mauro Carvalho Chehab4bc645d2015-10-06 18:39:40 -0300606 *
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.
Mauro Carvalho Chehab95abfdb2015-10-05 15:10:55 -0300616 */
617
Linus Torvalds1da177e2005-04-16 15:20:36 -0700618struct dmx_demux {
Mauro Carvalho Chehab9be91db2015-10-08 17:33:47 -0300619 enum dmx_demux_caps capabilities;
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300620 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);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700644
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300645 int (*get_pes_pids)(struct dmx_demux *demux, u16 *pids);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700646
Mauro Carvalho Chehab1e92bbe2015-10-06 18:36:20 -0300647 /* private: Not used upstream and never documented */
648#if 0
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300649 int (*get_caps)(struct dmx_demux *demux, struct dmx_caps *caps);
650 int (*set_source)(struct dmx_demux *demux, const dmx_source_t *src);
Mauro Carvalho Chehab1e92bbe2015-10-06 18:36:20 -0300651#endif
Mauro Carvalho Chehab4bc645d2015-10-06 18:39:40 -0300652 /*
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
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300655 * there, and its usage on other drivers aren't encouraged.
Mauro Carvalho Chehab4bc645d2015-10-06 18:39:40 -0300656 */
Mauro Carvalho Chehababfc97f2015-10-07 16:27:24 -0300657 int (*get_stc)(struct dmx_demux *demux, unsigned int num,
658 u64 *stc, unsigned int *base);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700659};
660
Linus Torvalds1da177e2005-04-16 15:20:36 -0700661#endif /* #ifndef __DEMUX_H */