include/media/dvbdev.h

0001 /*
0002  * dvbdev.h
0003  *
0004  * Copyright (C) 2000 Ralph Metzler & Marcus Metzler
0005  *                    for convergence integrated media GmbH
0006  *
0007  * This program is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU General Lesser Public License
0009  * as published by the Free Software Foundation; either version 2.1
0010  * of the License, or (at your option) any later version.
0011  *
0012  * This program is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0015  * GNU General Public License for more details.
0016  *
0017  */
0018
0019 #ifndef _DVBDEV_H_
0020 #define _DVBDEV_H_
0021
0022 #include <linux/types.h>
0023 #include <linux/poll.h>
0024 #include <linux/fs.h>
0025 #include <linux/list.h>
0026 #include <media/media-device.h>
0027
0028 #define DVB_MAJOR 212
0029
0030 #if defined(CONFIG_DVB_MAX_ADAPTERS) && CONFIG_DVB_MAX_ADAPTERS > 0
0031   #define DVB_MAX_ADAPTERS CONFIG_DVB_MAX_ADAPTERS
0032 #else
0033   #define DVB_MAX_ADAPTERS 16
0034 #endif
0035
0036 #define DVB_UNSET (-1)
0037
0038 /* List of DVB device types */
0039
0040 /**
0041  * enum dvb_device_type - type of the Digital TV device
0042  *
0043  * @DVB_DEVICE_SEC:     Digital TV standalone Common Interface (CI)
0044  * @DVB_DEVICE_FRONTEND:    Digital TV frontend.
0045  * @DVB_DEVICE_DEMUX:       Digital TV demux.
0046  * @DVB_DEVICE_DVR:     Digital TV digital video record (DVR).
0047  * @DVB_DEVICE_CA:      Digital TV Conditional Access (CA).
0048  * @DVB_DEVICE_NET:     Digital TV network.
0049  *
0050  * @DVB_DEVICE_VIDEO:       Digital TV video decoder.
0051  *              Deprecated. Used only on av7110-av.
0052  * @DVB_DEVICE_AUDIO:       Digital TV audio decoder.
0053  *              Deprecated. Used only on av7110-av.
0054  * @DVB_DEVICE_OSD:     Digital TV On Screen Display (OSD).
0055  *              Deprecated. Used only on av7110.
0056  */
0057 enum dvb_device_type {
0058     DVB_DEVICE_SEC,
0059     DVB_DEVICE_FRONTEND,
0060     DVB_DEVICE_DEMUX,
0061     DVB_DEVICE_DVR,
0062     DVB_DEVICE_CA,
0063     DVB_DEVICE_NET,
0064
0065     DVB_DEVICE_VIDEO,
0066     DVB_DEVICE_AUDIO,
0067     DVB_DEVICE_OSD,
0068 };
0069
0070 #define DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nr) \
0071     static short adapter_nr[] = \
0072         {[0 ... (DVB_MAX_ADAPTERS - 1)] = DVB_UNSET }; \
0073     module_param_array(adapter_nr, short, NULL, 0444); \
0074     MODULE_PARM_DESC(adapter_nr, "DVB adapter numbers")
0075
0076 struct dvb_frontend;
0077
0078 /**
0079  * struct dvb_adapter - represents a Digital TV adapter using Linux DVB API
0080  *
0081  * @num:        Number of the adapter
0082  * @list_head:      List with the DVB adapters
0083  * @device_list:    List with the DVB devices
0084  * @name:       Name of the adapter
0085  * @proposed_mac:   proposed MAC address for the adapter
0086  * @priv:       private data
0087  * @device:     pointer to struct device
0088  * @module:     pointer to struct module
0089  * @mfe_shared:     indicates mutually exclusive frontends.
0090  *          Use of this flag is currently deprecated.
0091  * @mfe_dvbdev:     Frontend device in use, in the case of MFE
0092  * @mfe_lock:       Lock to prevent using the other frontends when MFE is
0093  *          used.
0094  * @mdev_lock:          Protect access to the mdev pointer.
0095  * @mdev:       pointer to struct media_device, used when the media
0096  *          controller is used.
0097  * @conn:       RF connector. Used only if the device has no separate
0098  *          tuner.
0099  * @conn_pads:      pointer to struct media_pad associated with @conn;
0100  */
0101 struct dvb_adapter {
0102     int num;
0103     struct list_head list_head;
0104     struct list_head device_list;
0105     const char *name;
0106     u8 proposed_mac [6];
0107     void* priv;
0108
0109     struct device *device;
0110
0111     struct module *module;
0112
0113     int mfe_shared;         /* indicates mutually exclusive frontends */
0114     struct dvb_device *mfe_dvbdev;  /* frontend device in use */
0115     struct mutex mfe_lock;      /* access lock for thread creation */
0116
0117 #if defined(CONFIG_MEDIA_CONTROLLER_DVB)
0118     struct mutex mdev_lock;
0119     struct media_device *mdev;
0120     struct media_entity *conn;
0121     struct media_pad *conn_pads;
0122 #endif
0123 };
0124
0125 /**
0126  * struct dvb_device - represents a DVB device node
0127  *
0128  * @list_head:  List head with all DVB devices
0129  * @fops:   pointer to struct file_operations
0130  * @adapter:    pointer to the adapter that holds this device node
0131  * @type:   type of the device, as defined by &enum dvb_device_type.
0132  * @minor:  devnode minor number. Major number is always DVB_MAJOR.
0133  * @id:     device ID number, inside the adapter
0134  * @readers:    Initialized by the caller. Each call to open() in Read Only mode
0135  *      decreases this counter by one.
0136  * @writers:    Initialized by the caller. Each call to open() in Read/Write
0137  *      mode decreases this counter by one.
0138  * @users:  Initialized by the caller. Each call to open() in any mode
0139  *      decreases this counter by one.
0140  * @wait_queue: wait queue, used to wait for certain events inside one of
0141  *      the DVB API callers
0142  * @kernel_ioctl: callback function used to handle ioctl calls from userspace.
0143  * @name:   Name to be used for the device at the Media Controller
0144  * @entity: pointer to struct media_entity associated with the device node
0145  * @pads:   pointer to struct media_pad associated with @entity;
0146  * @priv:   private data
0147  * @intf_devnode: Pointer to media_intf_devnode. Used by the dvbdev core to
0148  *      store the MC device node interface
0149  * @tsout_num_entities: Number of Transport Stream output entities
0150  * @tsout_entity: array with MC entities associated to each TS output node
0151  * @tsout_pads: array with the source pads for each @tsout_entity
0152  *
0153  * This structure is used by the DVB core (frontend, CA, net, demux) in
0154  * order to create the device nodes. Usually, driver should not initialize
0155  * this struct diretly.
0156  */
0157 struct dvb_device {
0158     struct list_head list_head;
0159     const struct file_operations *fops;
0160     struct dvb_adapter *adapter;
0161     enum dvb_device_type type;
0162     int minor;
0163     u32 id;
0164
0165     /* in theory, 'users' can vanish now,
0166        but I don't want to change too much now... */
0167     int readers;
0168     int writers;
0169     int users;
0170
0171     wait_queue_head_t     wait_queue;
0172     /* don't really need those !? -- FIXME: use video_usercopy  */
0173     int (*kernel_ioctl)(struct file *file, unsigned int cmd, void *arg);
0174
0175     /* Needed for media controller register/unregister */
0176 #if defined(CONFIG_MEDIA_CONTROLLER_DVB)
0177     const char *name;
0178
0179     /* Allocated and filled inside dvbdev.c */
0180     struct media_intf_devnode *intf_devnode;
0181
0182     unsigned tsout_num_entities;
0183     struct media_entity *entity, *tsout_entity;
0184     struct media_pad *pads, *tsout_pads;
0185 #endif
0186
0187     void *priv;
0188 };
0189
0190 /**
0191  * dvb_register_adapter - Registers a new DVB adapter
0192  *
0193  * @adap:   pointer to struct dvb_adapter
0194  * @name:   Adapter's name
0195  * @module: initialized with THIS_MODULE at the caller
0196  * @device: pointer to struct device that corresponds to the device driver
0197  * @adapter_nums: Array with a list of the numbers for @dvb_register_adapter;
0198  *      to select among them. Typically, initialized with:
0199  *      DVB_DEFINE_MOD_OPT_ADAPTER_NR(adapter_nums)
0200  */
0201 int dvb_register_adapter(struct dvb_adapter *adap, const char *name,
0202              struct module *module, struct device *device,
0203              short *adapter_nums);
0204
0205 /**
0206  * dvb_unregister_adapter - Unregisters a DVB adapter
0207  *
0208  * @adap:   pointer to struct dvb_adapter
0209  */
0210 int dvb_unregister_adapter(struct dvb_adapter *adap);
0211
0212 /**
0213  * dvb_register_device - Registers a new DVB device
0214  *
0215  * @adap:   pointer to struct dvb_adapter
0216  * @pdvbdev:    pointer to the place where the new struct dvb_device will be
0217  *      stored
0218  * @template:   Template used to create &pdvbdev;
0219  * @priv:   private data
0220  * @type:   type of the device, as defined by &enum dvb_device_type.
0221  * @demux_sink_pads: Number of demux outputs, to be used to create the TS
0222  *      outputs via the Media Controller.
0223  */
0224 int dvb_register_device(struct dvb_adapter *adap,
0225             struct dvb_device **pdvbdev,
0226             const struct dvb_device *template,
0227             void *priv,
0228             enum dvb_device_type type,
0229             int demux_sink_pads);
0230
0231 /**
0232  * dvb_remove_device - Remove a registered DVB device
0233  *
0234  * This does not free memory.  To do that, call dvb_free_device().
0235  *
0236  * @dvbdev: pointer to struct dvb_device
0237  */
0238 void dvb_remove_device(struct dvb_device *dvbdev);
0239
0240 /**
0241  * dvb_free_device - Free memory occupied by a DVB device.
0242  *
0243  * Call dvb_unregister_device() before calling this function.
0244  *
0245  * @dvbdev: pointer to struct dvb_device
0246  */
0247 void dvb_free_device(struct dvb_device *dvbdev);
0248
0249 /**
0250  * dvb_unregister_device - Unregisters a DVB device
0251  *
0252  * This is a combination of dvb_remove_device() and dvb_free_device().
0253  * Using this function is usually a mistake, and is often an indicator
0254  * for a use-after-free bug (when a userspace process keeps a file
0255  * handle to a detached device).
0256  *
0257  * @dvbdev: pointer to struct dvb_device
0258  */
0259 void dvb_unregister_device(struct dvb_device *dvbdev);
0260
0261 #ifdef CONFIG_MEDIA_CONTROLLER_DVB
0262 /**
0263  * dvb_create_media_graph - Creates media graph for the Digital TV part of the
0264  *              device.
0265  *
0266  * @adap:           pointer to &struct dvb_adapter
0267  * @create_rf_connector:    if true, it creates the RF connector too
0268  *
0269  * This function checks all DVB-related functions at the media controller
0270  * entities and creates the needed links for the media graph. It is
0271  * capable of working with multiple tuners or multiple frontends, but it
0272  * won't create links if the device has multiple tuners and multiple frontends
0273  * or if the device has multiple muxes. In such case, the caller driver should
0274  * manually create the remaining links.
0275  */
0276 __must_check int dvb_create_media_graph(struct dvb_adapter *adap,
0277                     bool create_rf_connector);
0278
0279 /**
0280  * dvb_register_media_controller - registers a media controller at DVB adapter
0281  *
0282  * @adap:           pointer to &struct dvb_adapter
0283  * @mdev:           pointer to &struct media_device
0284  */
0285 static inline void dvb_register_media_controller(struct dvb_adapter *adap,
0286                          struct media_device *mdev)
0287 {
0288     adap->mdev = mdev;
0289 }
0290
0291 /**
0292  * dvb_get_media_controller - gets the associated media controller
0293  *
0294  * @adap:           pointer to &struct dvb_adapter
0295  */
0296 static inline struct media_device *
0297 dvb_get_media_controller(struct dvb_adapter *adap)
0298 {
0299     return adap->mdev;
0300 }
0301 #else
0302 static inline
0303 int dvb_create_media_graph(struct dvb_adapter *adap,
0304                bool create_rf_connector)
0305 {
0306     return 0;
0307 };
0308 #define dvb_register_media_controller(a, b) {}
0309 #define dvb_get_media_controller(a) NULL
0310 #endif
0311
0312 /**
0313  * dvb_generic_open - Digital TV open function, used by DVB devices
0314  *
0315  * @inode: pointer to &struct inode.
0316  * @file: pointer to &struct file.
0317  *
0318  * Checks if a DVB devnode is still valid, and if the permissions are
0319  * OK and increment negative use count.
0320  */
0321 int dvb_generic_open(struct inode *inode, struct file *file);
0322
0323 /**
0324  * dvb_generic_release - Digital TV close function, used by DVB devices
0325  *
0326  * @inode: pointer to &struct inode.
0327  * @file: pointer to &struct file.
0328  *
0329  * Checks if a DVB devnode is still valid, and if the permissions are
0330  * OK and decrement negative use count.
0331  */
0332 int dvb_generic_release(struct inode *inode, struct file *file);
0333
0334 /**
0335  * dvb_generic_ioctl - Digital TV close function, used by DVB devices
0336  *
0337  * @file: pointer to &struct file.
0338  * @cmd: Ioctl name.
0339  * @arg: Ioctl argument.
0340  *
0341  * Checks if a DVB devnode and struct dvbdev.kernel_ioctl is still valid.
0342  * If so, calls dvb_usercopy().
0343  */
0344 long dvb_generic_ioctl(struct file *file,
0345                unsigned int cmd, unsigned long arg);
0346
0347 /**
0348  * dvb_usercopy - copies data from/to userspace memory when an ioctl is
0349  *      issued.
0350  *
0351  * @file: Pointer to struct &file.
0352  * @cmd: Ioctl name.
0353  * @arg: Ioctl argument.
0354  * @func: function that will actually handle the ioctl
0355  *
0356  * Ancillary function that uses ioctl direction and size to copy from
0357  * userspace. Then, it calls @func, and, if needed, data is copied back
0358  * to userspace.
0359  */
0360 int dvb_usercopy(struct file *file, unsigned int cmd, unsigned long arg,
0361          int (*func)(struct file *file, unsigned int cmd, void *arg));
0362
0363 #if IS_ENABLED(CONFIG_I2C)
0364
0365 struct i2c_adapter;
0366 struct i2c_client;
0367 /**
0368  * dvb_module_probe - helper routine to probe an I2C module
0369  *
0370  * @module_name:
0371  *  Name of the I2C module to be probed
0372  * @name:
0373  *  Optional name for the I2C module. Used for debug purposes.
0374  *  If %NULL, defaults to @module_name.
0375  * @adap:
0376  *  pointer to &struct i2c_adapter that describes the I2C adapter where
0377  *  the module will be bound.
0378  * @addr:
0379  *  I2C address of the adapter, in 7-bit notation.
0380  * @platform_data:
0381  *  Platform data to be passed to the I2C module probed.
0382  *
0383  * This function binds an I2C device into the DVB core. Should be used by
0384  * all drivers that use I2C bus to control the hardware. A module bound
0385  * with dvb_module_probe() should use dvb_module_release() to unbind.
0386  *
0387  * Return:
0388  *  On success, return an &struct i2c_client, pointing to the bound
0389  *  I2C device. %NULL otherwise.
0390  *
0391  * .. note::
0392  *
0393  *    In the past, DVB modules (mainly, frontends) were bound via dvb_attach()
0394  *    macro, with does an ugly hack, using I2C low level functions. Such
0395  *    usage is deprecated and will be removed soon. Instead, use this routine.
0396  */
0397 struct i2c_client *dvb_module_probe(const char *module_name,
0398                     const char *name,
0399                     struct i2c_adapter *adap,
0400                     unsigned char addr,
0401                     void *platform_data);
0402
0403 /**
0404  * dvb_module_release - releases an I2C device allocated with
0405  *   dvb_module_probe().
0406  *
0407  * @client: pointer to &struct i2c_client with the I2C client to be released.
0408  *      can be %NULL.
0409  *
0410  * This function should be used to free all resources reserved by
0411  * dvb_module_probe() and unbinding the I2C hardware.
0412  */
0413 void dvb_module_release(struct i2c_client *client);
0414
0415 #endif /* CONFIG_I2C */
0416
0417 /* Legacy generic DVB attach function. */
0418 #ifdef CONFIG_MEDIA_ATTACH
0419
0420 /**
0421  * dvb_attach - attaches a DVB frontend into the DVB core.
0422  *
0423  * @FUNCTION:   function on a frontend module to be called.
0424  * @ARGS:   @FUNCTION arguments.
0425  *
0426  * This ancillary function loads a frontend module in runtime and runs
0427  * the @FUNCTION function there, with @ARGS.
0428  * As it increments symbol usage cont, at unregister, dvb_detach()
0429  * should be called.
0430  *
0431  * .. note::
0432  *
0433  *    In the past, DVB modules (mainly, frontends) were bound via dvb_attach()
0434  *    macro, with does an ugly hack, using I2C low level functions. Such
0435  *    usage is deprecated and will be removed soon. Instead, you should use
0436  *    dvb_module_probe().
0437  */
0438 #define dvb_attach(FUNCTION, ARGS...) ({ \
0439     void *__r = NULL; \
0440     typeof(&FUNCTION) __a = symbol_request(FUNCTION); \
0441     if (__a) { \
0442         __r = (void *) __a(ARGS); \
0443         if (__r == NULL) \
0444             symbol_put(FUNCTION); \
0445     } else { \
0446         printk(KERN_ERR "DVB: Unable to find symbol "#FUNCTION"()\n"); \
0447     } \
0448     __r; \
0449 })
0450
0451 /**
0452  * dvb_detach - detaches a DVB frontend loaded via dvb_attach()
0453  *
0454  * @FUNC:   attach function
0455  *
0456  * Decrements usage count for a function previously called via dvb_attach().
0457  */
0458
0459 #define dvb_detach(FUNC)    symbol_put_addr(FUNC)
0460
0461 #else
0462 #define dvb_attach(FUNCTION, ARGS...) ({ \
0463     FUNCTION(ARGS); \
0464 })
0465
0466 #define dvb_detach(FUNC)    {}
0467
0468 #endif  /* CONFIG_MEDIA_ATTACH */
0469
0470 #endif /* #ifndef _DVBDEV_H_ */