drivers/media/usb/dvb-usb-v2/dvb_usb.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * DVB USB framework
   4  *
   5  * Copyright (C) 2004-6 Patrick Boettcher <patrick.boettcher@posteo.de>
   6  * Copyright (C) 2012 Antti Palosaari <crope@iki.fi>
   7  */
   8
   9 #ifndef DVB_USB_H
  10 #define DVB_USB_H
  11
  12 #include <linux/usb/input.h>
  13 #include <linux/firmware.h>
  14 #include <media/rc-core.h>
  15 #include <media/media-device.h>
  16
  17 #include <media/dvb_frontend.h>
  18 #include <media/dvb_demux.h>
  19 #include <media/dvb_net.h>
  20 #include <media/dmxdev.h>
  21 #include <media/dvb-usb-ids.h>
  22
  23 /*
  24  * device file: /dev/dvb/adapter[0-1]/frontend[0-2]
  25  *
  26  * |-- device
  27  * |   |-- adapter0
  28  * |   |   |-- frontend0
  29  * |   |   |-- frontend1
  30  * |   |   `-- frontend2
  31  * |   `-- adapter1
  32  * |       |-- frontend0
  33  * |       |-- frontend1
  34  * |       `-- frontend2
  35  *
  36  *
  37  * Commonly used variable names:
  38  * d = pointer to device (struct dvb_usb_device *)
  39  * adap = pointer to adapter (struct dvb_usb_adapter *)
  40  * fe = pointer to frontend (struct dvb_frontend *)
  41  *
  42  * Use macros defined in that file to resolve needed pointers.
  43  */
  44
  45 /* helper macros for every DVB USB driver use */
  46 #define adap_to_d(adap) (container_of(adap, struct dvb_usb_device, \
  47                 adapter[adap->id]))
  48 #define adap_to_priv(adap) (adap_to_d(adap)->priv)
  49 #define fe_to_adap(fe) ((struct dvb_usb_adapter *) ((fe)->dvb->priv))
  50 #define fe_to_d(fe) (adap_to_d(fe_to_adap(fe)))
  51 #define fe_to_priv(fe) (fe_to_d(fe)->priv)
  52 #define d_to_priv(d) (d->priv)
  53
  54 #define dvb_usb_dbg_usb_control_msg(udev, r, t, v, i, b, l) { \
  55         char *direction; \
  56         if (t == (USB_TYPE_VENDOR | USB_DIR_OUT)) \
  57                 direction = ">>>"; \
  58         else \
  59                 direction = "<<<"; \
  60         dev_dbg(&udev->dev, "%s: %02x %02x %02x %02x %02x %02x %02x %02x " \
  61                         "%s %*ph\n",  __func__, t, r, v & 0xff, v >> 8, \
  62                         i & 0xff, i >> 8, l & 0xff, l >> 8, direction, l, b); \
  63 }
  64
  65 #define DVB_USB_STREAM_BULK(endpoint_, count_, size_) { \
  66         .type = USB_BULK, \
  67         .count = count_, \
  68         .endpoint = endpoint_, \
  69         .u = { \
  70                 .bulk = { \
  71                         .buffersize = size_, \
  72                 } \
  73         } \
  74 }
  75
  76 #define DVB_USB_STREAM_ISOC(endpoint_, count_, frames_, size_, interval_) { \
  77         .type = USB_ISOC, \
  78         .count = count_, \
  79         .endpoint = endpoint_, \
  80         .u = { \
  81                 .isoc = { \
  82                         .framesperurb = frames_, \
  83                         .framesize = size_,\
  84                         .interval = interval_, \
  85                 } \
  86         } \
  87 }
  88
  89 #define DVB_USB_DEVICE(vend, prod, props_, name_, rc) \
  90         .match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
  91         .idVendor = (vend), \
  92         .idProduct = (prod), \
  93         .driver_info = (kernel_ulong_t) &((const struct dvb_usb_driver_info) { \
  94                 .props = (props_), \
  95                 .name = (name_), \
  96                 .rc_map = (rc), \
  97         })
  98
  99 struct dvb_usb_device;
 100 struct dvb_usb_adapter;
 101
 102 /**
 103  * structure for carrying all needed data from the device driver to the general
 104  * dvb usb routines
 105  * @name: device name
 106  * @rc_map: name of rc codes table
 107  * @props: structure containing all device properties
 108  */
 109 struct dvb_usb_driver_info {
 110         const char *name;
 111         const char *rc_map;
 112         const struct dvb_usb_device_properties *props;
 113 };
 114
 115 /**
 116  * structure for remote controller configuration
 117  * @map_name: name of rc codes table
 118  * @allowed_protos: protocol(s) supported by the driver
 119  * @change_protocol: callback to change protocol
 120  * @query: called to query an event from the device
 121  * @interval: time in ms between two queries
 122  * @driver_type: used to point if a device supports raw mode
 123  * @bulk_mode: device supports bulk mode for rc (disable polling mode)
 124  */
 125 struct dvb_usb_rc {
 126         const char *map_name;
 127         u64 allowed_protos;
 128         int (*change_protocol)(struct rc_dev *dev, u64 *rc_proto);
 129         int (*query) (struct dvb_usb_device *d);
 130         unsigned int interval;
 131         enum rc_driver_type driver_type;
 132         bool bulk_mode;
 133 };
 134
 135 /**
 136  * usb streaming configuration for adapter
 137  * @type: urb type
 138  * @count: count of used urbs
 139  * @endpoint: stream usb endpoint number
 140  */
 141 struct usb_data_stream_properties {
 142 #define USB_BULK  1
 143 #define USB_ISOC  2
 144         u8 type;
 145         u8 count;
 146         u8 endpoint;
 147
 148         union {
 149                 struct {
 150                         unsigned int buffersize; /* per URB */
 151                 } bulk;
 152                 struct {
 153                         int framesperurb;
 154                         int framesize;
 155                         int interval;
 156                 } isoc;
 157         } u;
 158 };
 159
 160 /**
 161  * properties of dvb usb device adapter
 162  * @caps: adapter capabilities
 163  * @pid_filter_count: pid count of adapter pid-filter
 164  * @pid_filter_ctrl: called to enable/disable pid-filter
 165  * @pid_filter: called to set/unset pid for filtering
 166  * @stream: adapter usb stream configuration
 167  */
 168 #define MAX_NO_OF_FE_PER_ADAP 3
 169 struct dvb_usb_adapter_properties {
 170 #define DVB_USB_ADAP_HAS_PID_FILTER               0x01
 171 #define DVB_USB_ADAP_PID_FILTER_CAN_BE_TURNED_OFF 0x02
 172 #define DVB_USB_ADAP_NEED_PID_FILTERING           0x04
 173         u8 caps;
 174
 175         u8 pid_filter_count;
 176         int (*pid_filter_ctrl) (struct dvb_usb_adapter *, int);
 177         int (*pid_filter) (struct dvb_usb_adapter *, int, u16, int);
 178
 179         struct usb_data_stream_properties stream;
 180 };
 181
 182 /**
 183  * struct dvb_usb_device_properties - properties of a dvb-usb-device
 184  * @driver_name: name of the owning driver module
 185  * @owner: owner of the dvb_adapter
 186  * @adapter_nr: values from the DVB_DEFINE_MOD_OPT_ADAPTER_NR() macro
 187  * @bInterfaceNumber: usb interface number driver binds
 188  * @size_of_priv: bytes allocated for the driver private data
 189  * @generic_bulk_ctrl_endpoint: bulk control endpoint number for sent
 190  * @generic_bulk_ctrl_endpoint_response: bulk control endpoint number for
 191  *  receive
 192  * @generic_bulk_ctrl_delay: delay between bulk control sent and receive message
 193  * @probe: like probe on driver model
 194  * @disconnect: like disconnect on driver model
 195  * @identify_state: called to determine the firmware state (cold or warm) and
 196  *  return possible firmware file name to be loaded
 197  * @firmware: name of the firmware file to be loaded
 198  * @download_firmware: called to download the firmware
 199  * @i2c_algo: i2c_algorithm if the device has i2c-adapter
 200  * @num_adapters: dvb usb device adapter count
 201  * @get_adapter_count: called to resolve adapter count
 202  * @adapter: array of all adapter properties of device
 203  * @power_ctrl: called to enable/disable power of the device
 204  * @read_config: called to resolve device configuration
 205  * @read_mac_address: called to resolve adapter mac-address
 206  * @frontend_attach: called to attach the possible frontends
 207  * @frontend_detach: called to detach the possible frontends
 208  * @tuner_attach: called to attach the possible tuners
 209  * @frontend_ctrl: called to power on/off active frontend
 210  * @streaming_ctrl: called to start/stop the usb streaming of adapter
 211  * @init: called after adapters are created in order to finalize device
 212  *  configuration
 213  * @exit: called when driver is unloaded
 214  * @get_rc_config: called to resolve used remote controller configuration
 215  * @get_stream_config: called to resolve input and output stream configuration
 216  *  of the adapter just before streaming is started. input stream is transport
 217  *  stream from the demodulator and output stream is usb stream to host.
 218  */
 219 #define MAX_NO_OF_ADAPTER_PER_DEVICE 2
 220 struct dvb_usb_device_properties {
 221         const char *driver_name;
 222         struct module *owner;
 223         short *adapter_nr;
 224
 225         u8 bInterfaceNumber;
 226         unsigned int size_of_priv;
 227         u8 generic_bulk_ctrl_endpoint;
 228         u8 generic_bulk_ctrl_endpoint_response;
 229         unsigned int generic_bulk_ctrl_delay;
 230
 231         int (*probe)(struct dvb_usb_device *);
 232         void (*disconnect)(struct dvb_usb_device *);
 233 #define WARM                  0
 234 #define COLD                  1
 235         int (*identify_state) (struct dvb_usb_device *, const char **);
 236         const char *firmware;
 237 #define RECONNECTS_USB        1
 238         int (*download_firmware) (struct dvb_usb_device *,
 239                         const struct firmware *);
 240
 241         struct i2c_algorithm *i2c_algo;
 242
 243         unsigned int num_adapters;
 244         int (*get_adapter_count) (struct dvb_usb_device *);
 245         struct dvb_usb_adapter_properties adapter[MAX_NO_OF_ADAPTER_PER_DEVICE];
 246         int (*power_ctrl) (struct dvb_usb_device *, int);
 247         int (*read_config) (struct dvb_usb_device *d);
 248         int (*read_mac_address) (struct dvb_usb_adapter *, u8 []);
 249         int (*frontend_attach) (struct dvb_usb_adapter *);
 250         int (*frontend_detach)(struct dvb_usb_adapter *);
 251         int (*tuner_attach) (struct dvb_usb_adapter *);
 252         int (*tuner_detach)(struct dvb_usb_adapter *);
 253         int (*frontend_ctrl) (struct dvb_frontend *, int);
 254         int (*streaming_ctrl) (struct dvb_frontend *, int);
 255         int (*init) (struct dvb_usb_device *);
 256         void (*exit) (struct dvb_usb_device *);
 257         int (*get_rc_config) (struct dvb_usb_device *, struct dvb_usb_rc *);
 258 #define DVB_USB_FE_TS_TYPE_188        0
 259 #define DVB_USB_FE_TS_TYPE_204        1
 260 #define DVB_USB_FE_TS_TYPE_RAW        2
 261         int (*get_stream_config) (struct dvb_frontend *,  u8 *,
 262                         struct usb_data_stream_properties *);
 263 };
 264
 265 /**
 266  * generic object of an usb stream
 267  * @buf_num: number of buffer allocated
 268  * @buf_size: size of each buffer in buf_list
 269  * @buf_list: array containing all allocate buffers for streaming
 270  * @dma_addr: list of dma_addr_t for each buffer in buf_list
 271  *
 272  * @urbs_initialized: number of URBs initialized
 273  * @urbs_submitted: number of URBs submitted
 274  */
 275 #define MAX_NO_URBS_FOR_DATA_STREAM 10
 276 struct usb_data_stream {
 277         struct usb_device *udev;
 278         struct usb_data_stream_properties props;
 279
 280 #define USB_STATE_INIT    0x00
 281 #define USB_STATE_URB_BUF 0x01
 282         u8 state;
 283
 284         void (*complete) (struct usb_data_stream *, u8 *, size_t);
 285
 286         struct urb    *urb_list[MAX_NO_URBS_FOR_DATA_STREAM];
 287         int            buf_num;
 288         unsigned long  buf_size;
 289         u8            *buf_list[MAX_NO_URBS_FOR_DATA_STREAM];
 290         dma_addr_t     dma_addr[MAX_NO_URBS_FOR_DATA_STREAM];
 291
 292         int urbs_initialized;
 293         int urbs_submitted;
 294
 295         void *user_priv;
 296 };
 297
 298 /**
 299  * dvb adapter object on dvb usb device
 300  * @props: pointer to adapter properties
 301  * @stream: adapter the usb data stream
 302  * @id: index of this adapter (starting with 0)
 303  * @ts_type: transport stream, input stream, type
 304  * @suspend_resume_active: set when there is ongoing suspend / resume
 305  * @pid_filtering: is hardware pid_filtering used or not
 306  * @feed_count: current feed count
 307  * @max_feed_count: maimum feed count device can handle
 308  * @dvb_adap: adapter dvb_adapter
 309  * @dmxdev: adapter dmxdev
 310  * @demux: adapter software demuxer
 311  * @dvb_net: adapter dvb_net interfaces
 312  * @sync_mutex: mutex used to sync control and streaming of the adapter
 313  * @fe: adapter frontends
 314  * @fe_init: rerouted frontend-init function
 315  * @fe_sleep: rerouted frontend-sleep function
 316  */
 317 struct dvb_usb_adapter {
 318         const struct dvb_usb_adapter_properties *props;
 319         struct usb_data_stream stream;
 320         u8 id;
 321         u8 ts_type;
 322         bool suspend_resume_active;
 323         bool pid_filtering;
 324         u8 feed_count;
 325         u8 max_feed_count;
 326         s8 active_fe;
 327 #define ADAP_INIT                0
 328 #define ADAP_SLEEP               1
 329 #define ADAP_STREAMING           2
 330         unsigned long state_bits;
 331
 332         /* dvb */
 333         struct dvb_adapter   dvb_adap;
 334         struct dmxdev        dmxdev;
 335         struct dvb_demux     demux;
 336         struct dvb_net       dvb_net;
 337
 338         struct dvb_frontend *fe[MAX_NO_OF_FE_PER_ADAP];
 339         int (*fe_init[MAX_NO_OF_FE_PER_ADAP]) (struct dvb_frontend *);
 340         int (*fe_sleep[MAX_NO_OF_FE_PER_ADAP]) (struct dvb_frontend *);
 341 };
 342
 343 /**
 344  * dvb usb device object
 345  * @props: device properties
 346  * @name: device name
 347  * @rc_map: name of rc codes table
 348  * @rc_polling_active: set when RC polling is active
 349  * @intf: pointer to the device's struct usb_interface
 350  * @udev: pointer to the device's struct usb_device
 351  * @rc: remote controller configuration
 352  * @powered: indicated whether the device is power or not
 353  * @usb_mutex: mutex for usb control messages
 354  * @i2c_mutex: mutex for i2c-transfers
 355  * @i2c_adap: device's i2c-adapter
 356  * @rc_dev: rc device for the remote control
 357  * @rc_query_work: work for polling remote
 358  * @priv: private data of the actual driver (allocate by dvb usb, size defined
 359  *  in size_of_priv of dvb_usb_properties).
 360  */
 361 struct dvb_usb_device {
 362         const struct dvb_usb_device_properties *props;
 363         const char *name;
 364         const char *rc_map;
 365         bool rc_polling_active;
 366         struct usb_interface *intf;
 367         struct usb_device *udev;
 368         struct dvb_usb_rc rc;
 369         int powered;
 370
 371         /* locking */
 372         struct mutex usb_mutex;
 373
 374         /* i2c */
 375         struct mutex i2c_mutex;
 376         struct i2c_adapter i2c_adap;
 377
 378         struct dvb_usb_adapter adapter[MAX_NO_OF_ADAPTER_PER_DEVICE];
 379
 380         /* remote control */
 381         struct rc_dev *rc_dev;
 382         char rc_phys[64];
 383         struct delayed_work rc_query_work;
 384
 385         void *priv;
 386 };
 387
 388 extern int dvb_usbv2_probe(struct usb_interface *,
 389                 const struct usb_device_id *);
 390 extern void dvb_usbv2_disconnect(struct usb_interface *);
 391 extern int dvb_usbv2_suspend(struct usb_interface *, pm_message_t);
 392 extern int dvb_usbv2_resume(struct usb_interface *);
 393 extern int dvb_usbv2_reset_resume(struct usb_interface *);
 394
 395 /* the generic read/write method for device control */
 396 extern int dvb_usbv2_generic_rw(struct dvb_usb_device *, u8 *, u16, u8 *, u16);
 397 extern int dvb_usbv2_generic_write(struct dvb_usb_device *, u8 *, u16);
 398 /* caller must hold lock when locked versions are called */
 399 extern int dvb_usbv2_generic_rw_locked(struct dvb_usb_device *,
 400                 u8 *, u16, u8 *, u16);
 401 extern int dvb_usbv2_generic_write_locked(struct dvb_usb_device *, u8 *, u16);
 402
 403 #endif