1 /*
2 * Copyright (c) 2016 - Mauro Carvalho Chehab
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation version 2.1 of the License.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 * Or, point your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
17 */
18
19 #ifndef _DVB_DEV_H
20 #define _DVB_DEV_H
21
22 #include "dvb-fe.h"
23 #include "dvb-scan.h"
24
25 #include <linux/dvb/dmx.h>
26
27 /**
28 * @file dvb-dev.h
29 * @ingroup dvb_device
30 * @brief Provides interfaces to handle Digital TV devices.
31 * @copyright GNU Lesser General Public License version 2.1 (LGPLv2.1)
32 * @author Mauro Carvalho Chehab
33 *
34 * Digital TV device node file names depend on udev configuration. For
35 * example, while frontends are typically found at/dev/dvb/adapter?/frontend?,
36 * the actual file name can vary from system to system, depending on the
37 * udev ruleset.
38 *
39 * The libdvbv5 provides a set of functions to allow detecting and getting
40 * the device paths in a sane way, via libudev.
41 *
42 * @par Bug Report
43 * Please submit bug reports and patches to linux-media@vger.kernel.org
44 */
45
46 /**
47 * @enum dvb_dev_type
48 * @brief Type of a device entry to search
49 * @ingroup dvb_device
50 *
51 * @param DVB_DEVICE_FRONTEND Digital TV frontend
52 * @param DVB_DEVICE_DEMUX Digital TV demux
53 * @param DVB_DEVICE_DVR Digital TV Digital Video Record
54 * @param DVB_DEVICE_NET Digital TV network interface control
55 * @param DVB_DEVICE_CA Digital TV Conditional Access
56 * @param DVB_DEVICE_CA_SEC Digital TV Conditional Access serial
57 */
58 enum dvb_dev_type {
59 DVB_DEVICE_FRONTEND,
60 DVB_DEVICE_DEMUX,
61 DVB_DEVICE_DVR,
62 DVB_DEVICE_NET,
63 DVB_DEVICE_CA,
64 DVB_DEVICE_CA_SEC,
65 DVB_DEVICE_VIDEO,
66 DVB_DEVICE_AUDIO,
67 };
68
69 /**
70 * @struct dvb_dev_list
71 * @brief Digital TV device node properties
72 * @ingroup dvb_device
73 *
74 * @param path path for the /dev file handler
75 * @param sysname Kernel's system name for the device (dvb?.frontend?,
76 * for example)
77 * @param dvb_type type of the DVB device, as defined by enum dvb_dev_type
78 * @param bus_addr address of the device at the bus. For USB devices,
79 * it will be like: usb:3-1.1.4; for PCI devices:
80 * pci:0000:01:00.0)
81 * @param bus_id Id of the device at the bus (optional, PCI ID or USB ID)
82 * @param manufacturer Device's manufacturer name (optional, only on USB)
83 * @param product Device's product name (optional, only on USB)
84 * @param serial Device's serial name (optional, only on USB)
85 */
86 struct dvb_dev_list {
87 char *syspath;
88 char *path;
89 char *sysname;
90 enum dvb_dev_type dvb_type;
91 char *bus_addr;
92 char *bus_id;
93 char *manufacturer;
94 char *product;
95 char *serial;
96 };
97
98 /**
99 * @enum dvb_dev_change_type
100 * @brief Describes the type of change to be notifier_delay
101 *
102 * @param DVB_DEV_ADD New device detected
103 * @param DVB_DEV_CHANGE Device has changed something
104 * @param DVB_DEV_REMOVE A hot-pluggable device was removed
105 */
106 enum dvb_dev_change_type {
107 DVB_DEV_ADD,
108 DVB_DEV_CHANGE,
109 DVB_DEV_REMOVE,
110 };
111
112 /**
113 * @brief Describes a callback for dvb_dev_find()
114 *
115 * sysname: Kernel's system name for the device (dvb?.frontend?,
116 * for example)
117 * type: type of change, as defined by enum dvb_dev_change_type
118 *
119 * @note: the returned string should be freed with free().
120 */
121 typedef int (*dvb_dev_change_t)(char *sysname,
122 enum dvb_dev_change_type type, void *priv);
123
124 /**
125 * @struct dvb_open_descriptor
126 *
127 * Opaque struct with a DVB open file descriptor
128 */
129 struct dvb_open_descriptor;
130
131 /**
132 * @struct dvb_device
133 * @brief Digital TV list of devices
134 * @ingroup dvb_device
135 *
136 * @param devices Array with a dvb_dev_list of devices. Each device
137 * node is a different entry at the list.
138 * @param num_devices number of elements at the devices array.
139 */
140 struct dvb_device {
141 /* Digital TV device lists */
142 struct dvb_dev_list *devices;
143 int num_devices;
144
145 /* Digital TV frontend access */
146 struct dvb_v5_fe_parms *fe_parms;
147 };
148
149 /**
150 * @brief Allocate a struct dvb_device
151 * @ingroup dvb_device
152 *
153 * @note Before using the dvb device function calls, the struct dvb_device should
154 * be allocated via this function call.
155 *
156 * @return on success, returns a pointer to the allocated struct dvb_device or
157 * NULL if not enough memory to allocate the struct.
158 */
159 struct dvb_device *dvb_dev_alloc(void);
160
161 /**
162 * @brief free a struct dvb_device
163 * @ingroup dvb_device
164 *
165 * @param dvb pointer to struct dvb_device to be freed
166 */
167 void dvb_dev_free(struct dvb_device *dvb);
168
169 /**
170 * @brief finds all DVB devices on the local machine
171 * @ingroup dvb_device
172 *
173 * @param dvb pointer to struct dvb_device to be filled
174 * @param handler if not NULL, then this is called whenever
175 * something changed
176 * monitor mode
177 * @param user_priv pointer to user private data
178 *
179 * This routine can be called on two modes: normal or monitor mode
180 *
181 * In normal mode, it will seek for the local Digital TV devices, store them
182 * at the struct dvb_device and return.
183 *
184 * In monitor mode, it will not only enumerate all devices, but it will also
185 * keep waiting for device changes. The handler callback is called for the
186 * changed device.
187 *
188 * @return returns 0 on success, a negative value otherwise.
189 */
190 int dvb_dev_find(struct dvb_device *dvb, dvb_dev_change_t handler,
191 void *user_priv);
192
193 /**
194 * @brief Find a device that matches the search criteria given by this
195 * functions's parameters.
196 *
197 * @param dvb pointer to struct dvb_device to be used
198 * @param adapter Adapter number, as defined internally at the Kernel.
199 * Always start with 0;
200 * @param num Digital TV device number (e. g. frontend0, net0, etc);
201 * @param type Type of the device, as given by enum dvb_dev_type;
202 *
203 * @return returns a pointer to a struct dvb_dev_list object or NULL if the
204 * desired device was not found.
205 */
206 struct dvb_dev_list *dvb_dev_seek_by_adapter(struct dvb_device *dvb,
207 unsigned int adapter,
208 unsigned int num,
209 enum dvb_dev_type type);
210
211 /**
212 * @brief Return data about a device from its sysname
213 *
214 * @param dvb pointer to struct dvb_device to be used
215 * @param sysname Kernel's name of the device to be opened, as obtained
216 * via dvb_dev_seek_by_adapter() or via dvb_dev_find().
217 *
218 * @return returns a pointer to a struct dvb_dev_list object or NULL if the
219 * desired device was not found.
220 */
221 struct dvb_dev_list *dvb_get_dev_info(struct dvb_device *dvb,
222 const char *sysname);
223
224 /**
225 * @brief Stop the dvb_dev_find loop
226 * @ingroup dvb_device
227 *
228 * @param dvb pointer to struct dvb_device to be used
229 *
230 * This function stops dvb_dev_find() if it is running in monitor
231 * mode. It does nothing on other modes. Can be called even if the
232 * monitor mode was already stopped.
233 */
234 void dvb_dev_stop_monitor(struct dvb_device *dvb);
235
236 /**
237 * @brief Sets the DVB verbosity and log function with context private data
238 * @ingroup dvb_device
239 *
240 * @param dvb pointer to struct dvb_device to be used
241 * @param verbose Verbosity level of the messages that will be printed
242 * @param logfunc Callback function to be called when a log event
243 * happens. Can either store the event into a file or
244 * to print it at the TUI/GUI. Can be null.
245 * @param logpriv Private data for log function
246 *
247 * @details Sets the function to report log errors and to set the verbosity
248 * level of debug report messages. If not called, or if logfunc is
249 * NULL, the libdvbv5 will report error and debug messages via stderr,
250 * and will use colors for the debug messages.
251 *
252 */
253 void dvb_dev_set_logpriv(struct dvb_device *dvb,
254 unsigned verbose,
255 dvb_logfunc_priv logfunc, void *logpriv);
256
257 /**
258 * @brief Sets the DVB verbosity and log function
259 * @ingroup dvb_device
260 *
261 * @param dvb pointer to struct dvb_device to be used
262 * @param verbose Verbosity level of the messages that will be printed
263 * @param logfunc Callback function to be called when a log event
264 * happens. Can either store the event into a file or
265 * to print it at the TUI/GUI. Can be null.
266 *
267 * @details Sets the function to report log errors and to set the verbosity
268 * level of debug report messages. If not called, or if logfunc is
269 * NULL, the libdvbv5 will report error and debug messages via stderr,
270 * and will use colors for the debug messages.
271 *
272 */
273 void dvb_dev_set_log(struct dvb_device *dvb,
274 unsigned verbose,
275 dvb_logfunc logfunc);
276
277 /**
278 * @brief Opens a dvb device
279 * @ingroup dvb_device
280 *
281 * @param dvb pointer to struct dvb_device to be used
282 * @param sysname Kernel's name of the device to be opened, as obtained
283 * via dvb_dev_seek_by_adapter() or via dvb_dev_find().
284 * @param flags Flags to be passed to open: O_RDONLY, O_RDWR and/or
285 * O_NONBLOCK
286 *
287 *
288 * @note Please notice that O_NONBLOCK is not supported for frontend devices,
289 * and will be silently ignored.
290 *
291 * @note the sysname will only work if a previous call to dvb_dev_find()
292 * is issued.
293 *
294 * @details This function is equivalent to open(2) system call: it opens a
295 * Digital TV given by the dev parameter, using the flags.
296 *
297 * @return returns a pointer to the dvb_open_descriptor that should be used
298 * on further calls if sucess. NULL otherwise.
299 */
300 struct dvb_open_descriptor *dvb_dev_open(struct dvb_device *dvb,
301 const char *sysname, int flags);
302
303 /**
304 * @brief Closes a dvb device
305 * @ingroup dvb_device
306 *
307 * @param open_dev Points to the struct dvb_open_descriptor to be
308 * closed.
309 */
310 void dvb_dev_close(struct dvb_open_descriptor *open_dev);
311
312 /**
313 * @brief returns fd from a local device
314 * This will not work for remote devices.
315 * @ingroup dvb_device
316 *
317 * @param open_dev Points to the struct dvb_open_descriptor
318 *
319 * @return On success, returns the fd.
320 * Returns -1 on error.
321 */
322 int dvb_dev_get_fd(struct dvb_open_descriptor *open_dev);
323
324 /**
325 * @brief read from a dvb demux or dvr file
326 * @ingroup dvb_device
327 *
328 * @param open_dev Points to the struct dvb_open_descriptor to be
329 * closed.
330 * @param buf Buffer to store the data
331 * @param count number of bytes to read
332 *
333 * @return On success, returns the number of bytes read. Returns -1 on
334 * error.
335 */
336 ssize_t dvb_dev_read(struct dvb_open_descriptor *open_dev,
337 void *buf, size_t count);
338
339 /**
340 * @brief Stops the demux filter for a given file descriptor
341 * @ingroup dvb_device
342 *
343 * @param open_dev Points to the struct dvb_open_descriptor
344 *
345 * This is a wrapper function for DMX_STOP ioctl.
346 *
347 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
348 * for more details.
349 *
350 * @note valid only for DVB_DEVICE_DEMUX.
351 */
352 void dvb_dev_dmx_stop(struct dvb_open_descriptor *open_dev);
353
354 /**
355 * @brief Start a demux or dvr buffer size
356 * @ingroup dvb_device
357 *
358 * @param open_dev Points to the struct dvb_open_descriptor
359 * @param buffersize Size of the buffer to be allocated to store the filtered data.
360 *
361 * This is a wrapper function for DMX_SET_BUFFER_SIZE ioctl.
362 *
363 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
364 * for more details.
365 *
366 * @return Retuns zero on success, -1 otherwise.
367 *
368 * @note valid only for DVB_DEVICE_DEMUX or DVB_DEVICE_DVR.
369 */
370 int dvb_dev_set_bufsize(struct dvb_open_descriptor *open_dev,
371 int buffersize);
372
373 /**
374 * @brief Start a filter for a MPEG-TS Packetized Elementary
375 * Stream (PES)
376 * @ingroup dvb_device
377 *
378 * @param open_dev Points to the struct dvb_open_descriptor
379 * @param pid Program ID to filter. Use 0x2000 to select all PIDs
380 * @param type type of the PID (DMX_PES_VIDEO, DMX_PES_AUDIO,
381 * DMX_PES_OTHER, etc).
382 * @param output Where the data will be output (DMX_OUT_TS_TAP,
383 * DMX_OUT_DECODER, etc).
384 * @param buffersize Size of the buffer to be allocated to store the filtered data.
385 *
386 * This is a wrapper function for DMX_SET_PES_FILTER and DMX_SET_BUFFER_SIZE
387 * ioctls.
388 *
389 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
390 * for more details.
391 *
392 * @return Retuns zero on success, -1 otherwise.
393 *
394 * @note valid only for DVB_DEVICE_DEMUX.
395 */
396 int dvb_dev_dmx_set_pesfilter(struct dvb_open_descriptor *open_dev,
397 int pid, dmx_pes_type_t type,
398 dmx_output_t output, int buffersize);
399
400 /**
401 * @brief Sets a MPEG-TS section filter
402 * @ingroup dvb_device
403 *
404 * @param open_dev Points to the struct dvb_open_descriptor
405 * @param pid Program ID to filter. Use 0x2000 to select all PIDs
406 * @param filtsize Size of the filter (up to 18 btyes)
407 * @param filter data to filter. Can be NULL or should have filtsize length
408 * @param mask filter mask. Can be NULL or should have filtsize length
409 * @param mode mode mask. Can be NULL or should have filtsize length
410 * @param flags flags for set filter (DMX_CHECK_CRC,DMX_ONESHOT,
411 * DMX_IMMEDIATE_START).
412 *
413 * This is a wrapper function for DMX_SET_FILTER ioctl.
414 *
415 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
416 * for more details.
417 *
418 * @return Retuns zero on success, -1 otherwise.
419 *
420 * @note valid only for DVB_DEVICE_DEMUX.
421 */
422 int dvb_dev_dmx_set_section_filter(struct dvb_open_descriptor *open_dev,
423 int pid, unsigned filtsize,
424 unsigned char *filter,
425 unsigned char *mask,
426 unsigned char *mode,
427 unsigned int flags);
428
429 /**
430 * @brief read the contents of the MPEG-TS PAT table, seeking for
431 * an specific service ID
432 * @ingroup dvb_device
433 *
434 * @param open_dev Points to the struct dvb_open_descriptor
435 * @param sid Session ID to seeking
436 *
437 * @return At return, it returns a negative value if error or the PID
438 * associated with the desired Session ID.
439 *
440 * @warning This function currently assumes that the PAT fits into one session.
441 *
442 * @note valid only for DVB_DEVICE_DEMUX.
443 */
444 int dvb_dev_dmx_get_pmt_pid(struct dvb_open_descriptor *open_dev, int sid);
445
446 /**
447 * @brief Scans a DVB dvb_add_scaned_transponder
448 * @ingroup frontend_scan
449 *
450 * @param entry DVB file entry that corresponds to a transponder to be
451 * tuned
452 * @param open_dev Points to the struct dvb_open_descriptor
453 * @param check_frontend a pointer to a function that will show the frontend
454 * status while tuning into a transponder
455 * @param args a pointer, opaque to libdvbv5, that will be used when
456 * calling check_frontend. It should contain any parameters
457 * that could be needed by check_frontend.
458 * @param other_nit Use alternate table IDs for NIT and other tables
459 * @param timeout_multiply Improves the timeout for each table reception, by
460 *
461 * This is the function that applications should use when doing a transponders
462 * scan. It does everything needed to fill the entries with DVB programs
463 * (virtual channels) and detect the PIDs associated with them.
464 *
465 * This is the dvb_device variant of dvb_scan_transponder().
466 */
467 struct dvb_v5_descriptors *dvb_dev_scan(struct dvb_open_descriptor *open_dev,
468 struct dvb_entry *entry,
469 check_frontend_t *check_frontend,
470 void *args,
471 unsigned other_nit,
472 unsigned timeout_multiply);
473
474 /* From dvb-dev-remote.c */
475
476 #ifdef HAVE_DVBV5_REMOTE
477
478 #define REMOTE_BUF_SIZE (87 * 188) /* 16356 bytes */
479
480
481 /**
482 * @brief initialize the dvb-dev to use a remote device running the
483 * dvbv5-daemon.
484 *
485 * @param dvb pointer to struct dvb_device to be used
486 * @param server server hostname or address
487 * @param port server port
488 *
489 * @note The protocol between the dvbv5-daemon and the dvb_dev library is
490 * highly experimental and is subject to changes in a near future. So,
491 * while this is not stable enough, you will only work if both the client
492 * and the server are running the same version of the v4l-utils library.
493 */
494 int dvb_dev_remote_init(struct dvb_device *d, char *server, int port);
495
496 #else
497
dvb_dev_remote_init(struct dvb_device * d,char * server,int port)498 static inline int dvb_dev_remote_init(struct dvb_device *d, char *server,
499 int port)
500 {
501 return -1;
502 };
503
504 #endif
505
506
507 #endif
508