[media] dvb_usb_v2: update header dvb_usb.h comments (f93c8028) · Commits · e / devices / android_kernel_fairphone_FP4

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

+114 −111

Original line number	Original line	Diff line number	Diff line
	@@ -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
	* @powered: indicated whether the device is power or not.		* @intf: pointer to the device's usb interface
	* Powered is in/decremented for each call to modify the state.		* @rc: remote controller configuration
	* @udev: pointer to the device's struct usb_device.		* @probe_work: work to defer .probe()
	*		* @powered: indicated whether the device is power or not
	* @usb_mutex: semaphore of USB control messages (reading needs two messages)		* @usb_mutex: mutex for usb control messages
	* @i2c_mutex: semaphore for i2c-transfers		* @i2c_mutex: mutex for i2c-transfers
	*		* @i2c_adap: device's i2c-adapter
	* @i2c_adap: device's i2c_adapter if it uses I2CoverUSB
	*		*
	* @rc_dev: rc device for the remote control (rc-core mode)		* @rc_dev: rc device for the remote control
	* @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 {