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 enable_monitor if different than zero put the routine into
175 * monitor mode
176 * @param user_priv pointer to user private data
177 *
178 * This routine can be called on two modes: normal or monitor mode
179 *
180 * In normal mode, it will seek for the local Digital TV devices, store them
181 * at the struct dvb_device and return.
182 *
183 * In monitor mode, it will not only enumerate all devices, but it will also
184 * keep waiting for device changes. The device seek loop will only be
185 * interrupted after calling dvb_dev_stop_monitor().
186 *
187 * Please notice that, in such mode, the function will wait forever. So, it
188 * is up to the application to put start a separate thread to handle it in
189 * monitor mode, and add the needed mutexes to make it thread safe.
190 *
191 * @return returns 0 on success, a negative value otherwise.
192 */
193 int dvb_dev_find(struct dvb_device *dvb, dvb_dev_change_t handler,
194 void *user_priv);
195
196 /**
197 * @brief Find a device that matches the search criteria given by this
198 * functions's parameters.
199 *
200 * @param dvb pointer to struct dvb_device to be used
201 * @param adapter Adapter number, as defined internally at the Kernel.
202 * Always start with 0;
203 * @param num Digital TV device number (e. g. frontend0, net0, etc);
204 * @param type Type of the device, as given by enum dvb_dev_type;
205 *
206 * @return returns a pointer to a struct dvb_dev_list object or NULL if the
207 * desired device was not found.
208 */
209 struct dvb_dev_list *dvb_dev_seek_by_adapter(struct dvb_device *dvb,
210 unsigned int adapter,
211 unsigned int num,
212 enum dvb_dev_type type);
213
214 /**
215 * @brief Return data about a device from its sysname
216 *
217 * @param dvb pointer to struct dvb_device to be used
218 * @param sysname Kernel's name of the device to be opened, as obtained
219 * via dvb_dev_seek_by_adapter() or via dvb_dev_find().
220 *
221 * @return returns a pointer to a struct dvb_dev_list object or NULL if the
222 * desired device was not found.
223 */
224 struct dvb_dev_list *dvb_get_dev_info(struct dvb_device *dvb,
225 const char *sysname);
226
227 /**
228 * @brief Stop the dvb_dev_find loop
229 * @ingroup dvb_device
230 *
231 * @param dvb pointer to struct dvb_device to be used
232 *
233 * This function stops dvb_dev_find() if it is running in monitor
234 * mode. It does nothing on other modes. Can be called even if the
235 * monitor mode was already stopped.
236 */
237 void dvb_dev_stop_monitor(struct dvb_device *dvb);
238
239 /**
240 * @brief Sets the DVB verbosity and log function with context private data
241 * @ingroup dvb_device
242 *
243 * @param dvb pointer to struct dvb_device to be used
244 * @param verbose Verbosity level of the messages that will be printed
245 * @param logfunc Callback function to be called when a log event
246 * happens. Can either store the event into a file or
247 * to print it at the TUI/GUI. Can be null.
248 * @param logpriv Private data for log function
249 *
250 * @details Sets the function to report log errors and to set the verbosity
251 * level of debug report messages. If not called, or if logfunc is
252 * NULL, the libdvbv5 will report error and debug messages via stderr,
253 * and will use colors for the debug messages.
254 *
255 */
256 void dvb_dev_set_logpriv(struct dvb_device *dvb,
257 unsigned verbose,
258 dvb_logfunc_priv logfunc, void *logpriv);
259
260 /**
261 * @brief Sets the DVB verbosity and log function
262 * @ingroup dvb_device
263 *
264 * @param dvb pointer to struct dvb_device to be used
265 * @param verbose Verbosity level of the messages that will be printed
266 * @param logfunc Callback function to be called when a log event
267 * happens. Can either store the event into a file or
268 * to print it at the TUI/GUI. Can be null.
269 *
270 * @details Sets the function to report log errors and to set the verbosity
271 * level of debug report messages. If not called, or if logfunc is
272 * NULL, the libdvbv5 will report error and debug messages via stderr,
273 * and will use colors for the debug messages.
274 *
275 */
276 void dvb_dev_set_log(struct dvb_device *dvb,
277 unsigned verbose,
278 dvb_logfunc logfunc);
279
280 /**
281 * @brief Opens a dvb device
282 * @ingroup dvb_device
283 *
284 * @param dvb pointer to struct dvb_device to be used
285 * @param sysname Kernel's name of the device to be opened, as obtained
286 * via dvb_dev_seek_by_adapter() or via dvb_dev_find().
287 * @param flags Flags to be passed to open: O_RDONLY, O_RDWR and/or
288 * O_NONBLOCK
289 *
290 *
291 * @note Please notice that O_NONBLOCK is not supported for frontend devices,
292 * and will be silently ignored.
293 *
294 * @note the sysname will only work if a previous call to dvb_dev_find()
295 * is issued.
296 *
297 * @details This function is equivalent to open(2) system call: it opens a
298 * Digital TV given by the dev parameter, using the flags.
299 *
300 * @return returns a pointer to the dvb_open_descriptor that should be used
301 * on further calls if sucess. NULL otherwise.
302 */
303 struct dvb_open_descriptor *dvb_dev_open(struct dvb_device *dvb,
304 const char *sysname, int flags);
305
306 /**
307 * @brief Closes a dvb device
308 * @ingroup dvb_device
309 *
310 * @param open_dev Points to the struct dvb_open_descriptor to be
311 * closed.
312 */
313 void dvb_dev_close(struct dvb_open_descriptor *open_dev);
314
315 /**
316 * @brief returns fd from a local device
317 * This will not work for remote devices.
318 * @ingroup dvb_device
319 *
320 * @param open_dev Points to the struct dvb_open_descriptor
321 *
322 * @return On success, returns the fd.
323 * Returns -1 on error.
324 */
325 int dvb_dev_get_fd(struct dvb_open_descriptor *open_dev);
326
327 /**
328 * @brief read from a dvb demux or dvr file
329 * @ingroup dvb_device
330 *
331 * @param open_dev Points to the struct dvb_open_descriptor to be
332 * closed.
333 * @param buf Buffer to store the data
334 * @param count number of bytes to read
335 *
336 * @return On success, returns the number of bytes read. Returns -1 on
337 * error.
338 */
339 ssize_t dvb_dev_read(struct dvb_open_descriptor *open_dev,
340 void *buf, size_t count);
341
342 /**
343 * @brief Stops the demux filter for a given file descriptor
344 * @ingroup dvb_device
345 *
346 * @param open_dev Points to the struct dvb_open_descriptor
347 *
348 * This is a wrapper function for DMX_STOP ioctl.
349 *
350 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
351 * for more details.
352 *
353 * @note valid only for DVB_DEVICE_DEMUX.
354 */
355 void dvb_dev_dmx_stop(struct dvb_open_descriptor *open_dev);
356
357 /**
358 * @brief Start a demux or dvr buffer size
359 * @ingroup dvb_device
360 *
361 * @param open_dev Points to the struct dvb_open_descriptor
362 * @param buffersize Size of the buffer to be allocated to store the filtered data.
363 *
364 * This is a wrapper function for DMX_SET_BUFFER_SIZE ioctl.
365 *
366 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
367 * for more details.
368 *
369 * @return Retuns zero on success, -1 otherwise.
370 *
371 * @note valid only for DVB_DEVICE_DEMUX or DVB_DEVICE_DVR.
372 */
373 int dvb_dev_set_bufsize(struct dvb_open_descriptor *open_dev,
374 int buffersize);
375
376 /**
377 * @brief Start a filter for a MPEG-TS Packetized Elementary
378 * Stream (PES)
379 * @ingroup dvb_device
380 *
381 * @param open_dev Points to the struct dvb_open_descriptor
382 * @param pid Program ID to filter. Use 0x2000 to select all PIDs
383 * @param type type of the PID (DMX_PES_VIDEO, DMX_PES_AUDIO,
384 * DMX_PES_OTHER, etc).
385 * @param output Where the data will be output (DMX_OUT_TS_TAP,
386 * DMX_OUT_DECODER, etc).
387 * @param buffersize Size of the buffer to be allocated to store the filtered data.
388 *
389 * This is a wrapper function for DMX_SET_PES_FILTER and DMX_SET_BUFFER_SIZE
390 * ioctls.
391 *
392 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
393 * for more details.
394 *
395 * @return Retuns zero on success, -1 otherwise.
396 *
397 * @note valid only for DVB_DEVICE_DEMUX.
398 */
399 int dvb_dev_dmx_set_pesfilter(struct dvb_open_descriptor *open_dev,
400 int pid, dmx_pes_type_t type,
401 dmx_output_t output, int buffersize);
402
403 /**
404 * @brief Sets a MPEG-TS section filter
405 * @ingroup dvb_device
406 *
407 * @param open_dev Points to the struct dvb_open_descriptor
408 * @param pid Program ID to filter. Use 0x2000 to select all PIDs
409 * @param filtsize Size of the filter (up to 18 btyes)
410 * @param filter data to filter. Can be NULL or should have filtsize length
411 * @param mask filter mask. Can be NULL or should have filtsize length
412 * @param mode mode mask. Can be NULL or should have filtsize length
413 * @param flags flags for set filter (DMX_CHECK_CRC,DMX_ONESHOT,
414 * DMX_IMMEDIATE_START).
415 *
416 * This is a wrapper function for DMX_SET_FILTER ioctl.
417 *
418 * See http://linuxtv.org/downloads/v4l-dvb-apis/dvb_demux.html
419 * for more details.
420 *
421 * @return Retuns zero on success, -1 otherwise.
422 *
423 * @note valid only for DVB_DEVICE_DEMUX.
424 */
425 int dvb_dev_dmx_set_section_filter(struct dvb_open_descriptor *open_dev,
426 int pid, unsigned filtsize,
427 unsigned char *filter,
428 unsigned char *mask,
429 unsigned char *mode,
430 unsigned int flags);
431
432 /**
433 * @brief read the contents of the MPEG-TS PAT table, seeking for
434 * an specific service ID
435 * @ingroup dvb_device
436 *
437 * @param open_dev Points to the struct dvb_open_descriptor
438 * @param sid Session ID to seeking
439 *
440 * @return At return, it returns a negative value if error or the PID
441 * associated with the desired Session ID.
442 *
443 * @warning This function currently assumes that the PAT fits into one session.
444 *
445 * @note valid only for DVB_DEVICE_DEMUX.
446 */
447 int dvb_dev_dmx_get_pmt_pid(struct dvb_open_descriptor *open_dev, int sid);
448
449 /**
450 * @brief Scans a DVB dvb_add_scaned_transponder
451 * @ingroup frontend_scan
452 *
453 * @param entry DVB file entry that corresponds to a transponder to be
454 * tuned
455 * @param open_dev Points to the struct dvb_open_descriptor
456 * @param check_frontend a pointer to a function that will show the frontend
457 * status while tuning into a transponder
458 * @param args a pointer, opaque to libdvbv5, that will be used when
459 * calling check_frontend. It should contain any parameters
460 * that could be needed by check_frontend.
461 * @param other_nit Use alternate table IDs for NIT and other tables
462 * @param timeout_multiply Improves the timeout for each table reception, by
463 *
464 * This is the function that applications should use when doing a transponders
465 * scan. It does everything needed to fill the entries with DVB programs
466 * (virtual channels) and detect the PIDs associated with them.
467 *
468 * This is the dvb_device variant of dvb_scan_transponder().
469 */
470 struct dvb_v5_descriptors *dvb_dev_scan(struct dvb_open_descriptor *open_dev,
471 struct dvb_entry *entry,
472 check_frontend_t *check_frontend,
473 void *args,
474 unsigned other_nit,
475 unsigned timeout_multiply);
476
477 /* From dvb-dev-remote.c */
478
479 #ifdef HAVE_DVBV5_REMOTE
480
481 #define REMOTE_BUF_SIZE (87 * 188) /* 16356 bytes */
482
483
484 /**
485 * @brief initialize the dvb-dev to use a remote device running the
486 * dvbv5-daemon.
487 *
488 * @param dvb pointer to struct dvb_device to be used
489 * @param server server hostname or address
490 * @param port server port
491 *
492 * @note The protocol between the dvbv5-daemon and the dvb_dev library is
493 * highly experimental and is subject to changes in a near future. So,
494 * while this is not stable enough, you will only work if both the client
495 * and the server are running the same version of the v4l-utils library.
496 */
497 int dvb_dev_remote_init(struct dvb_device *d, char *server, int port);
498
499 #else
500
dvb_dev_remote_init(struct dvb_device * d,char * server,int port)501 static inline int dvb_dev_remote_init(struct dvb_device *d, char *server,
502 int port)
503 {
504 return -1;
505 };
506
507 #endif
508
509
510 #endif
511