hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[media] dvb_usb_v2: update header dvb_usb.h comments 

Comment briefly all used structures and variables.

Signed-off-by: Antti Palosaari <crope@iki.fi>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Antti Palosaari 2012-06-20 22:22:14 -03:00 committed by Mauro Carvalho Chehab
parent 1162c7b383
commit f93c802887
1 changed files with 114 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
drivers/media/dvb/dvb-usb/dvb_usb.h
View File

@ -4,8 +4,6 @@
* see dvb-usb-init.c for copyright information. * see dvb-usb-init.c for copyright information.
* *
* the headerfile, all dvb-usb-drivers have to include. * the headerfile, all dvb-usb-drivers have to include.
*
* TODO: clean-up the structures for unused fields and update the comments
*/ */
#ifndef DVB_USB_H #ifndef DVB_USB_H
#define DVB_USB_H #define DVB_USB_H
@ -20,6 +18,28 @@
#include "dmxdev.h" #include "dmxdev.h"
#include "dvb-usb-ids.h" #include "dvb-usb-ids.h"
/*
* device file: /dev/dvb/adapter[0-1]/frontend[0-2]
*
* |-- device
* | |-- adapter0
* | | |-- frontend0
* | | |-- frontend1
* | | `-- frontend2
* | `-- adapter1
* | |-- frontend0
* | |-- frontend1
* | `-- frontend2
*
*
* Commonly used variable names:
* d = pointer to device (struct dvb_usb_device *)
* adap = pointer to adapter (struct dvb_usb_adapter *)
* fe = pointer to frontend (struct dvb_frontend *)
*
* Use macros defined in that file to resolve needed pointers.
*/
/* helper macros for every DVB USB driver use */ /* helper macros for every DVB USB driver use */
#define adap_to_d(adap) (container_of(adap, struct dvb_usb_device, \ #define adap_to_d(adap) (container_of(adap, struct dvb_usb_device, \
adapter[adap->id])) adapter[adap->id]))
@ -66,6 +86,13 @@
struct dvb_usb_device; struct dvb_usb_device;
struct dvb_usb_adapter; struct dvb_usb_adapter;
/**
* structure for carrying all needed data from the device driver to the general
* dvb usb routines
* @name: device name
* @rc_map: name of rc codes table
* @props: structure containing all device properties
*/
struct dvb_usb_driver_info { struct dvb_usb_driver_info {
const char *name; const char *name;
const char *rc_map; const char *rc_map;
@ -73,15 +100,14 @@ struct dvb_usb_driver_info {
}; };
/** /**
* struct dvb_rc properties of remote controller, using rc-core * structure for remote controller configuration
* @rc_codes: name of rc codes table * @map_name: name of rc codes table
* @protocol: type of protocol(s) currently used by the driver
* @allowed_protos: protocol(s) supported by the driver * @allowed_protos: protocol(s) supported by the driver
* @driver_type: Used to point if a device supports raw mode
* @change_protocol: callback to change protocol * @change_protocol: callback to change protocol
* @rc_query: called to query an event event. * @query: called to query an event from the device
* @rc_interval: time in ms between two queries. * @interval: time in ms between two queries
* @bulk_mode: device supports bulk mode for RC (disable polling mode) * @driver_type: used to point if a device supports raw mode
* @bulk_mode: device supports bulk mode for rc (disable polling mode)
*/ */
struct dvb_usb_rc { struct dvb_usb_rc {
char *map_name; char *map_name;
@ -94,9 +120,10 @@ struct dvb_usb_rc {
}; };
/** /**
* Properties of USB streaming - TODO this structure should be somewhere else * usb streaming configration for adapter
* describes the kind of USB transfer used for data-streaming. * @type: urb type
* (BULK or ISOC) * @count: count of used urbs
* @endpoint: stream usb endpoint number
*/ */
struct usb_data_stream_properties { struct usb_data_stream_properties {
#define USB_BULK 1 #define USB_BULK 1
@ -118,25 +145,13 @@ struct usb_data_stream_properties {
}; };
/** /**
* struct dvb_usb_adapter_properties - properties of a dvb-usb-adapter. * properties of dvb usb device adapter
* A DVB-USB-Adapter is basically a dvb_adapter which is present on a * @caps: adapter capabilities
* USB-device. * @pid_filter_count: pid count of adapter pid-filter
* @caps: capabilities of the DVB USB device. * @pid_filter_ctrl: called to enable/disable pid-filter
* @pid_filter_count: number of PID filter position in the optional hardware * @pid_filter: called to set/unset pid for filtering
* PID-filter. * @stream: adapter usb stream configuration
* @num_frontends: number of frontends of the DVB USB adapter.
* @frontend_ctrl: called to power on/off active frontend.
* @streaming_ctrl: called to start and stop the MPEG2-TS streaming of the
* device (not URB submitting/killing).
* @pid_filter_ctrl: called to en/disable the PID filter, if any.
* @pid_filter: called to set/unset a PID for filtering.
* @frontend_attach: called to attach the possible frontends (fill fe-field
* of struct dvb_usb_device).
* @tuner_attach: called to attach the correct tuner and to fill pll_addr,
* pll_desc and pll_init_buf of struct dvb_usb_device).
* @stream: configuration of the USB streaming
*/ */
#define MAX_NO_OF_FE_PER_ADAP 3 #define MAX_NO_OF_FE_PER_ADAP 3
struct dvb_usb_adapter_properties { struct dvb_usb_adapter_properties {
#define DVB_USB_ADAP_HAS_PID_FILTER 0x01 #define DVB_USB_ADAP_HAS_PID_FILTER 0x01
@ -153,39 +168,38 @@ struct dvb_usb_adapter_properties {
/** /**
* struct dvb_usb_device_properties - properties of a dvb-usb-device * struct dvb_usb_device_properties - properties of a dvb-usb-device
* @driver_name: name of the owning driver module
* @owner: owner of the dvb_adapter * @owner: owner of the dvb_adapter
* @usb_ctrl: which USB device-side controller is in use. Needed for firmware * @adapter_nr: values from the DVB_DEFINE_MOD_OPT_ADAPTER_NR() macro
* download. * @bInterfaceNumber: usb interface number driver binds
* @firmware: name of the firmware file. * @size_of_priv: bytes allocated for the driver private data
* @download_firmware: called to download the firmware when the usb_ctrl is * @generic_bulk_ctrl_endpoint: bulk control endpoint number for sent
* DEVICE_SPECIFIC. * @generic_bulk_ctrl_endpoint_response: bulk control endpoint number for
* @no_reconnect: device doesn't do a reconnect after downloading the firmware, * receive
* so do the warm initialization right after it * @generic_bulk_ctrl_delay: delay between bulk control sent and receive message
* * @identify_state: called to determine the firmware state (cold or warm) and
* @size_of_priv: how many bytes shall be allocated for the private field * return possible firmware file name to be loaded
* of struct dvb_usb_device. * @firmware: name of the firmware file to be loaded
* * @download_firmware: called to download the firmware
* @power_ctrl: called to enable/disable power of the device. * @i2c_algo: i2c_algorithm if the device has i2c-adapter
* @read_mac_address: called to read the MAC address of the device. * @num_adapters: dvb usb device adapter count
* @identify_state: called to determine the state (cold or warm), when it * @get_adapter_count: called to resolve adapter count
* is not distinguishable by the USB IDs. * @adapter: array of all adapter properties of device
* @power_ctrl: called to enable/disable power of the device
* @read_config: called to resolve device configuration
* @read_mac_address: called to resolve adapter mac-address
* @frontend_attach: called to attach the possible frontends
* @tuner_attach: called to attach the possible tuners
* @frontend_ctrl: called to power on/off active frontend
* @streaming_ctrl: called to start/stop the usb streaming of adapter
* @fe_ioctl_override: frontend ioctl override. avoid using that is possible
* @init: called after adapters are created in order to finalize device * @init: called after adapters are created in order to finalize device
* configuration. * configuration
* * @exit: called when driver is unloaded
* @rc: remote controller properties * @get_rc_config: called to resolve used remote controller configuration
* * @get_stream_config: called to resolve input and output stream configuration
* @i2c_algo: i2c_algorithm if the device has I2CoverUSB. * of the adapter just before streaming is started. input stream is transport
* * stream from the demodulator and output stream is usb stream to host.
* @generic_bulk_ctrl_endpoint: most of the DVB USB devices have a generic
* endpoint which received control messages with bulk transfers. When this
* is non-zero, one can use dvb_usb_generic_rw and dvb_usb_generic_write-
* helper functions.
*
* @generic_bulk_ctrl_endpoint_response: some DVB USB devices use a separate
* endpoint for responses to control messages sent with bulk transfers via
* the generic_bulk_ctrl_endpoint. When this is non-zero, this will be used
* instead of the generic_bulk_ctrl_endpoint when reading usb responses in
* the dvb_usb_generic_rw helper function.
*/ */
#define MAX_NO_OF_ADAPTER_PER_DEVICE 2 #define MAX_NO_OF_ADAPTER_PER_DEVICE 2
struct dvb_usb_device_properties { struct dvb_usb_device_properties {
@ -210,8 +224,8 @@ struct dvb_usb_device_properties {
struct i2c_algorithm *i2c_algo; struct i2c_algorithm *i2c_algo;
unsigned int num_adapters; unsigned int num_adapters;
struct dvb_usb_adapter_properties adapter[MAX_NO_OF_ADAPTER_PER_DEVICE];
int (*get_adapter_count) (struct dvb_usb_device *); int (*get_adapter_count) (struct dvb_usb_device *);
struct dvb_usb_adapter_properties adapter[MAX_NO_OF_ADAPTER_PER_DEVICE];
int (*power_ctrl) (struct dvb_usb_device *, int); int (*power_ctrl) (struct dvb_usb_device *, int);
int (*read_config) (struct dvb_usb_device *d); int (*read_config) (struct dvb_usb_device *d);
int (*read_mac_address) (struct dvb_usb_adapter *, u8 []); int (*read_mac_address) (struct dvb_usb_adapter *, u8 []);
@ -232,14 +246,14 @@ struct dvb_usb_device_properties {
}; };
/** /**
* struct usb_data_stream - generic object of an USB stream * generic object of an usb stream
* @buf_num: number of buffer allocated. * @buf_num: number of buffer allocated
* @buf_size: size of each buffer in buf_list. * @buf_size: size of each buffer in buf_list
* @buf_list: array containing all allocate buffers for streaming. * @buf_list: array containing all allocate buffers for streaming
* @dma_addr: list of dma_addr_t for each buffer in buf_list. * @dma_addr: list of dma_addr_t for each buffer in buf_list
* *
* @urbs_initialized: number of URBs initialized. * @urbs_initialized: number of URBs initialized
* @urbs_submitted: number of URBs submitted. * @urbs_submitted: number of URBs submitted
*/ */
#define MAX_NO_URBS_FOR_DATA_STREAM 10 #define MAX_NO_URBS_FOR_DATA_STREAM 10
struct usb_data_stream { struct usb_data_stream {
@ -265,30 +279,22 @@ struct usb_data_stream {
}; };
/** /**
* struct dvb_usb_adapter - a DVB adapter on a USB device * dvb adapter object on dvb usb device
* @id: index of this adapter (starting with 0). * @props: pointer to adapter properties
* * @stream: adapter the usb data stream
* @feedcount: number of reqested feeds (used for streaming-activation) * @id: index of this adapter (starting with 0)
* @pid_filtering: is hardware pid_filtering used or not. * @ts_type: transport stream, input stream, type
* * @pid_filtering: is hardware pid_filtering used or not
* @pll_addr: I2C address of the tuner for programming * @feed_count: current feed count
* @pll_init: array containing the initialization buffer * @max_feed_count: maimum feed count device can handle
* @pll_desc: pointer to the appropriate struct dvb_pll_desc * @dvb_adap: adapter dvb_adapter
* @tuner_pass_ctrl: called to (de)activate tuner passthru of the demod or * @dmxdev: adapter dmxdev
* the board * @demux: adapter software demuxer
* * @dvb_net: adapter dvb_net interfaces
* @dvb_adap: device's dvb_adapter. * @sync_mutex: mutex used to sync control and streaming of the adapter
* @dmxdev: device's dmxdev. * @fe: adapter frontends
* @demux: device's software demuxer. * @fe_init: rerouted frontend-init function
* @dvb_net: device's dvb_net interfaces. * @fe_sleep: rerouted frontend-sleep function
* @dvb_frontend: device's frontend.
* @max_feed_count: how many feeds can be handled simultaneously by this
* device
*
* @fe_init: rerouted frontend-init (wakeup) function.
* @fe_sleep: rerouted frontend-sleep function.
*
* @stream: the usb data stream.
*/ */
struct dvb_usb_adapter { struct dvb_usb_adapter {
const struct dvb_usb_adapter_properties *props; const struct dvb_usb_adapter_properties *props;
@ -313,26 +319,23 @@ struct dvb_usb_adapter {
}; };
/** /**
* struct dvb_usb_device - object of a DVB USB device * dvb usb device object
* @props: copy of the struct dvb_usb_properties this device belongs to. * @props: device properties
* @desc: pointer to the device's struct dvb_usb_device_description. * @name: device name
* @state: initialization and runtime state of the device. * @rc_map: name of rc codes table
* @udev: pointer to the device's struct usb_device
* @intf: pointer to the device's usb interface
* @rc: remote controller configuration
* @probe_work: work to defer .probe()
* @powered: indicated whether the device is power or not
* @usb_mutex: mutex for usb control messages
* @i2c_mutex: mutex for i2c-transfers
* @i2c_adap: device's i2c-adapter
* *
* @powered: indicated whether the device is power or not. * @rc_dev: rc device for the remote control
* Powered is in/decremented for each call to modify the state.
* @udev: pointer to the device's struct usb_device.
*
* @usb_mutex: semaphore of USB control messages (reading needs two messages)
* @i2c_mutex: semaphore for i2c-transfers
*
* @i2c_adap: device's i2c_adapter if it uses I2CoverUSB
*
* @rc_dev: rc device for the remote control (rc-core mode)
* @input_dev: input device for the remote control (legacy mode) * @input_dev: input device for the remote control (legacy mode)
* @rc_query_work: struct work_struct frequent rc queries * @rc_query_work: work for polling remote
* @last_event: last triggered event * @priv: private data of the actual driver (allocate by dvb usb, size defined
* @last_state: last state (no, pressed, repeat)
* @priv: private data of the actual driver (allocate by dvb-usb, size defined
* in size_of_priv of dvb_usb_properties). * in size_of_priv of dvb_usb_properties).
*/ */
struct dvb_usb_device { struct dvb_usb_device {