diff options
Diffstat (limited to 'Documentation/driver-api/media')
18 files changed, 2921 insertions, 130 deletions
diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst new file mode 100644 index 000000000000..ffb0cad8137a --- /dev/null +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -0,0 +1,147 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Writing camera sensor drivers +============================= + +CSI-2 +----- + +Please see what is written on :ref:`MIPI_CSI_2`. + +Handling clocks +--------------- + +Camera sensors have an internal clock tree including a PLL and a number of +divisors. The clock tree is generally configured by the driver based on a few +input parameters that are specific to the hardware:: the external clock frequency +and the link frequency. The two parameters generally are obtained from system +firmware. No other frequencies should be used in any circumstances. + +The reason why the clock frequencies are so important is that the clock signals +come out of the SoC, and in many cases a specific frequency is designed to be +used in the system. Using another frequency may cause harmful effects +elsewhere. Therefore only the pre-determined frequencies are configurable by the +user. + +Frame size +---------- + +There are two distinct ways to configure the frame size produced by camera +sensors. + +Freely configurable camera sensor drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Freely configurable camera sensor drivers expose the device's internal +processing pipeline as one or more sub-devices with different cropping and +scaling configurations. The output size of the device is the result of a series +of cropping and scaling operations from the device's pixel array's size. + +An example of such a driver is the smiapp driver (see drivers/media/i2c/smiapp). + +Register list based drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register list based drivers generally, instead of able to configure the device +they control based on user requests, are limited to a number of preset +configurations that combine a number of different parameters that on hardware +level are independent. How a driver picks such configuration is based on the +format set on a source pad at the end of the device's internal pipeline. + +Most sensor drivers are implemented this way, see e.g. +drivers/media/i2c/imx319.c for an example. + +Frame interval configuration +---------------------------- + +There are two different methods for obtaining possibilities for different frame +intervals as well as configuring the frame interval. Which one to implement +depends on the type of the device. + +Raw camera sensors +~~~~~~~~~~~~~~~~~~ + +Instead of a high level parameter such as frame interval, the frame interval is +a result of the configuration of a number of camera sensor implementation +specific parameters. Luckily, these parameters tend to be the same for more or +less all modern raw camera sensors. + +The frame interval is calculated using the following equation:: + + frame interval = (analogue crop width + horizontal blanking) * + (analogue crop height + vertical blanking) / pixel rate + +The formula is bus independent and is applicable for raw timing parameters on +large variety of devices beyond camera sensors. Devices that have no analogue +crop, use the full source image size, i.e. pixel array size. + +Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and +``V4L2_CID_VBLANK``, respectively. The unit of these controls are lines. The +pixel rate is specified by ``V4L2_CID_PIXEL_RATE`` in the same sub-device. The +unit of that control is Hz. + +Register list based drivers need to implement read-only sub-device nodes for the +purpose. Devices that are not register list based need these to configure the +device's internal processing pipeline. + +The first entity in the linear pipeline is the pixel array. The pixel array may +be followed by other entities that are there to allow configuring binning, +skipping, scaling or digital crop :ref:`v4l2-subdev-selections`. + +USB cameras etc. devices +~~~~~~~~~~~~~~~~~~~~~~~~ + +USB video class hardware, as well as many cameras offering a similar higher +level interface natively, generally use the concept of frame interval (or frame +rate) on device level in firmware or hardware. This means lower level controls +implemented by raw cameras may not be used on uAPI (or even kAPI) to control the +frame interval on these devices. + +Power management +---------------- + +Always use runtime PM to manage the power states of your device. Camera sensor +drivers are in no way special in this respect: they are responsible for +controlling the power state of the device they otherwise control as well. In +general, the device must be powered on at least when its registers are being +accessed and when it is streaming. + +Existing camera sensor drivers may rely on the old +:c:type:`v4l2_subdev_core_ops`->s_power() callback for bridge or ISP drivers to +manage their power state. This is however **deprecated**. If you feel you need +to begin calling an s_power from an ISP or a bridge driver, instead please add +runtime PM support to the sensor driver you are using. Likewise, new drivers +should not use s_power. + +Please see examples in e.g. ``drivers/media/i2c/ov8856.c`` and +``drivers/media/i2c/smiapp/smiapp-core.c``. The two drivers work in both ACPI +and DT based systems. + +Control framework +~~~~~~~~~~~~~~~~~ + +``v4l2_ctrl_handler_setup()`` function may not be used in the device's runtime +PM ``runtime_resume`` callback, as it has no way to figure out the power state +of the device. This is because the power state of the device is only changed +after the power state transition has taken place. The ``s_ctrl`` callback can be +used to obtain device's power state after the power state transition: + +.. c:function:: + int pm_runtime_get_if_in_use(struct device *dev); + +The function returns a non-zero value if it succeeded getting the power count or +runtime PM was disabled, in either of which cases the driver may proceed to +access the device. + +Controls +-------- + +For camera sensors that are connected to a bus where transmitter and receiver +require common configuration set by drivers, such as CSI-2 or parallel (BT.601 +or BT.656) bus, the ``V4L2_CID_LINK_FREQ`` control is mandatory on transmitter +drivers. Receiver drivers can use the ``V4L2_CID_LINK_FREQ`` to query the +frequency used on the bus. + +The transmitter drivers should also implement ``V4L2_CID_PIXEL_RATE`` control in +order to tell the maximum pixel rate to the receiver. This is required on raw +camera sensors. diff --git a/Documentation/driver-api/media/cec-core.rst b/Documentation/driver-api/media/cec-core.rst index 3ce26b7c2b2b..a26dc87eee8f 100644 --- a/Documentation/driver-api/media/cec-core.rst +++ b/Documentation/driver-api/media/cec-core.rst @@ -36,8 +36,9 @@ The struct cec_adapter represents the CEC adapter hardware. It is created by calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): .. c:function:: - struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, void *priv, - const char *name, u32 caps, u8 available_las); + struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, \ + void *priv, const char *name, \ + u32 caps, u8 available_las); .. c:function:: void cec_delete_adapter(struct cec_adapter *adap); @@ -74,7 +75,8 @@ To register the /dev/cecX device node and the remote control device (if CEC_CAP_RC is set) you call: .. c:function:: - int cec_register_adapter(struct cec_adapter *adap, struct device *parent); + int cec_register_adapter(struct cec_adapter *adap, \ + struct device *parent); where parent is the parent device. @@ -96,7 +98,7 @@ Implementing the Low-Level CEC Adapter The following low-level adapter operations have to be implemented in your driver: -.. c:type:: struct cec_adap_ops +.. c:struct:: cec_adap_ops .. code-block:: none @@ -123,9 +125,8 @@ The seven low-level ops deal with various aspects of controlling the CEC adapter hardware: -To enable/disable the hardware: +To enable/disable the hardware:: -.. c:function:: int (*adap_enable)(struct cec_adapter *adap, bool enable); This callback enables or disables the CEC hardware. Enabling the CEC hardware @@ -137,22 +138,20 @@ state of the CEC adapter after calling cec_allocate_adapter() is disabled. Note that adap_enable must return 0 if enable is false. -To enable/disable the 'monitor all' mode: +To enable/disable the 'monitor all' mode:: -.. c:function:: int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); If enabled, then the adapter should be put in a mode to also monitor messages -that not for us. Not all hardware supports this and this function is only +that are not for us. Not all hardware supports this and this function is only called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional (some hardware may always be in 'monitor all' mode). Note that adap_monitor_all_enable must return 0 if enable is false. -To enable/disable the 'monitor pin' mode: +To enable/disable the 'monitor pin' mode:: -.. c:function:: int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); If enabled, then the adapter should be put in a mode to also monitor CEC pin @@ -163,9 +162,8 @@ the CEC_CAP_MONITOR_PIN capability is set. This callback is optional Note that adap_monitor_pin_enable must return 0 if enable is false. -To program a new logical address: +To program a new logical address:: -.. c:function:: int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses @@ -177,9 +175,8 @@ can receive directed messages to that address. Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. -To transmit a new message: +To transmit a new message:: -.. c:function:: int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, u32 signal_free_time, struct cec_msg *msg); @@ -196,17 +193,15 @@ The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to microseconds (one data bit period is 2.4 ms). -To log the current CEC hardware status: +To log the current CEC hardware status:: -.. c:function:: void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); This optional callback can be used to show the status of the CEC hardware. The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status -To free any resources when the adapter is deleted: +To free any resources when the adapter is deleted:: -.. c:function:: void (*adap_free)(struct cec_adapter *adap); This optional callback can be used to free any resources that might have been @@ -216,15 +211,14 @@ allocated by the driver. It's called from cec_delete_adapter. Your adapter driver will also have to react to events (typically interrupt driven) by calling into the framework in the following situations: -When a transmit finished (successfully or otherwise): +When a transmit finished (successfully or otherwise):: -.. c:function:: - void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, - u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); + void cec_transmit_done(struct cec_adapter *adap, u8 status, + u8 arb_lost_cnt, u8 nack_cnt, u8 low_drive_cnt, + u8 error_cnt); -or: +or:: -.. c:function:: void cec_transmit_attempt_done(struct cec_adapter *adap, u8 status); The status can be one of: @@ -341,17 +335,15 @@ So this must work: $ cat einj.txt >error-inj The first callback is called when this file is read and it should show the -the current error injection state: +current error injection state:: -.. c:function:: int (*error_inj_show)(struct cec_adapter *adap, struct seq_file *sf); It is recommended that it starts with a comment block with basic usage information. It returns 0 for success and an error otherwise. -The second callback will parse commands written to the ``error-inj`` file: +The second callback will parse commands written to the ``error-inj`` file:: -.. c:function:: bool (*error_inj_parse_line)(struct cec_adapter *adap, char *line); The ``line`` argument points to the start of the command. Any leading @@ -382,9 +374,8 @@ CEC protocol driven. The following high-level callbacks are available: }; The received() callback allows the driver to optionally handle a newly -received CEC message +received CEC message:: -.. c:function:: int (*received)(struct cec_adapter *adap, struct cec_msg *msg); If the driver wants to process a CEC message, then it can implement this @@ -399,15 +390,14 @@ CEC framework functions CEC Adapter drivers can call the following CEC framework functions: .. c:function:: - int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, - bool block); + int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, \ + bool block); Transmit a CEC message. If block is true, then wait until the message has been transmitted, otherwise just queue it and return. .. c:function:: - void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, - bool block); + void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); Change the physical address. This function will set adap->phys_addr and send an event if it has changed. If cec_s_log_addrs() has been called and @@ -422,15 +412,15 @@ to another valid physical address, then this function will first set the address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. .. c:function:: - void cec_s_phys_addr_from_edid(struct cec_adapter *adap, - const struct edid *edid); + void cec_s_phys_addr_from_edid(struct cec_adapter *adap, \ + const struct edid *edid); A helper function that extracts the physical address from the edid struct and calls cec_s_phys_addr() with that address, or CEC_PHYS_ADDR_INVALID if the EDID did not contain a physical address or edid was a NULL pointer. .. c:function:: - int cec_s_log_addrs(struct cec_adapter *adap, + int cec_s_log_addrs(struct cec_adapter *adap, \ struct cec_log_addrs *log_addrs, bool block); Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS diff --git a/Documentation/driver-api/media/csi2.rst b/Documentation/driver-api/media/csi2.rst index 17cad435f1a0..e3bbc6baf0f0 100644 --- a/Documentation/driver-api/media/csi2.rst +++ b/Documentation/driver-api/media/csi2.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _MIPI_CSI_2: + MIPI CSI-2 ========== @@ -26,10 +28,9 @@ interface elements must be present on the sub-device represents the CSI-2 transmitter. The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the -frequency (and not the symbol rate) of the link. The -V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel -rate the transmitter uses. The -:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an +frequency (and not the symbol rate) of the link. The V4L2_CID_PIXEL_RATE +control may be used by the receiver to obtain the pixel rate the transmitter +uses. The :c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an ability to start and stop the stream. The value of the V4L2_CID_PIXEL_RATE is calculated as follows:: diff --git a/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc new file mode 100644 index 000000000000..f2042acc8a45 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs-regs.asc @@ -0,0 +1,1041 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +# register rflags +# - f field LSB MSB rflags +# - e enum value # after a field +# - e enum value [LSB MSB] +# - b bool bit +# - l arg name min max elsize [discontig...] +# +# rflags +# 8, 16, 32 register bits (default is 8) +# v1.1 defined in version 1.1 +# f formula +# float_ireal iReal or IEEE 754; 32 bits +# ireal unsigned iReal + +# general status registers +module_model_id 0x0000 16 +module_revision_number_major 0x0002 8 +frame_count 0x0005 8 +pixel_order 0x0006 8 +- e GRBG 0 +- e RGGB 1 +- e BGGR 2 +- e GBRG 3 +MIPI_CCS_version 0x0007 8 +- e v1_0 0x10 +- e v1_1 0x11 +- f major 4 7 +- f minor 0 3 +data_pedestal 0x0008 16 +module_manufacturer_id 0x000e 16 +module_revision_number_minor 0x0010 8 +module_date_year 0x0012 8 +module_date_month 0x0013 8 +module_date_day 0x0014 8 +module_date_phase 0x0015 8 +- f 0 2 +- e ts 0 +- e es 1 +- e cs 2 +- e mp 3 +sensor_model_id 0x0016 16 +sensor_revision_number 0x0018 8 +sensor_firmware_version 0x001a 8 +serial_number 0x001c 32 +sensor_manufacturer_id 0x0020 16 +sensor_revision_number_16 0x0022 16 + +# frame format description registers +frame_format_model_type 0x0040 8 +- e 2-byte 1 +- e 4-byte 2 +frame_format_model_subtype 0x0041 8 +- f rows 0 3 +- f columns 4 7 +frame_format_descriptor(n) 0x0042 16 f +- l n 0 14 2 +- f pixels 0 11 +- f pcode 12 15 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 +frame_format_descriptor_4(n) 0x0060 32 f +- l n 0 7 4 +- f pixels 0 15 +- f pcode 28 31 +- e embedded 1 +- e dummy_pixel 2 +- e black_pixel 3 +- e dark_pixel 4 +- e visible_pixel 5 +- e manuf_specific_0 8 +- e manuf_specific_1 9 +- e manuf_specific_2 10 +- e manuf_specific_3 11 +- e manuf_specific_4 12 +- e manuf_specific_5 13 +- e manuf_specific_6 14 + +# analog gain description registers +analog_gain_capability 0x0080 16 +- e global 0 +- e alternate_global 2 +analog_gain_code_min 0x0084 16 +analog_gain_code_max 0x0086 16 +analog_gain_code_step 0x0088 16 +analog_gain_type 0x008a 16 +analog_gain_m0 0x008c 16 +analog_gain_c0 0x008e 16 +analog_gain_m1 0x0090 16 +analog_gain_c1 0x0092 16 +analog_linear_gain_min 0x0094 16 v1.1 +analog_linear_gain_max 0x0096 16 v1.1 +analog_linear_gain_step_size 0x0098 16 v1.1 +analog_exponential_gain_min 0x009a 16 v1.1 +analog_exponential_gain_max 0x009c 16 v1.1 +analog_exponential_gain_step_size 0x009e 16 v1.1 + +# data format description registers +data_format_model_type 0x00c0 8 +- e normal 1 +- e extended 2 +data_format_model_subtype 0x00c1 8 +- f rows 0 3 +- f columns 4 7 +data_format_descriptor(n) 0x00c2 16 f +- l n 0 15 2 +- f compressed 0 7 +- f uncompressed 8 15 + +# general set-up registers +mode_select 0x0100 8 +- e software_standby 0 +- e streaming 1 +image_orientation 0x0101 8 +- b horizontal_mirror 0 +- b vertical_flip 1 +software_reset 0x0103 8 +- e off 0 +- e on 1 +grouped_parameter_hold 0x0104 8 +mask_corrupted_frames 0x0105 8 +- e allow 0 +- e mask 1 +fast_standby_ctrl 0x0106 8 +- e complete_frames 0 +- e frame_truncation 1 +CCI_address_ctrl 0x0107 8 +2nd_CCI_if_ctrl 0x0108 8 +- b enable 0 +- b ack 1 +2nd_CCI_address_ctrl 0x0109 8 +CSI_channel_identifier 0x0110 8 +CSI_signaling_mode 0x0111 8 +- e csi_2_dphy 2 +- e csi_2_cphy 3 +CSI_data_format 0x0112 16 +CSI_lane_mode 0x0114 8 +DPCM_Frame_DT 0x011d 8 +Bottom_embedded_data_DT 0x011e 8 +Bottom_embedded_data_VC 0x011f 8 + +gain_mode 0x0120 8 +- e global 0 +- e alternate 1 +ADC_bit_depth 0x0121 8 +emb_data_ctrl 0x0122 v1.1 +- b raw8_packing_for_raw16 0 +- b raw10_packing_for_raw20 1 +- b raw12_packing_for_raw24 2 + +GPIO_TRIG_mode 0x0130 8 +extclk_frequency_mhz 0x0136 16 ireal +temp_sensor_ctrl 0x0138 8 +- b enable 0 +temp_sensor_mode 0x0139 8 +temp_sensor_output 0x013a 8 + +# integration time registers +fine_integration_time 0x0200 16 +coarse_integration_time 0x0202 16 + +# analog gain registers +analog_gain_code_global 0x0204 16 +analog_linear_gain_global 0x0206 16 v1.1 +analog_exponential_gain_global 0x0208 16 v1.1 + +# digital gain registers +digital_gain_global 0x020e 16 + +# hdr control registers +Short_analog_gain_global 0x0216 16 +Short_digital_gain_global 0x0218 16 + +HDR_mode 0x0220 8 +- b enabled 0 +- b separate_analog_gain 1 +- b upscaling 2 +- b reset_sync 3 +- b timing_mode 4 +- b exposure_ctrl_direct 5 +- b separate_digital_gain 6 +HDR_resolution_reduction 0x0221 8 +- f row 0 3 +- f column 4 7 +Exposure_ratio 0x0222 8 +HDR_internal_bit_depth 0x0223 8 +Direct_short_integration_time 0x0224 16 +Short_analog_linear_gain_global 0x0226 16 v1.1 +Short_analog_exponential_gain_global 0x0228 16 v1.1 + +# clock set-up registers +vt_pix_clk_div 0x0300 16 +vt_sys_clk_div 0x0302 16 +pre_pll_clk_div 0x0304 16 +#vt_pre_pll_clk_div 0x0304 16 +pll_multiplier 0x0306 16 +#vt_pll_multiplier 0x0306 16 +op_pix_clk_div 0x0308 16 +op_sys_clk_div 0x030a 16 +op_pre_pll_clk_div 0x030c 16 +op_pll_multiplier 0x031e 16 +pll_mode 0x0310 8 +- f 0 0 +- e single 0 +- e dual 1 +op_pix_clk_div_rev 0x0312 16 v1.1 +op_sys_clk_div_rev 0x0314 16 v1.1 + +# frame timing registers +frame_length_lines 0x0340 16 +line_length_pck 0x0342 16 + +# image size registers +x_addr_start 0x0344 16 +y_addr_start 0x0346 16 +x_addr_end 0x0348 16 +y_addr_end 0x034a 16 +x_output_size 0x034c 16 +y_output_size 0x034e 16 + +# timing mode registers +Frame_length_ctrl 0x0350 8 +- b automatic 0 +Timing_mode_ctrl 0x0352 8 +- b manual_readout 0 +- b delayed_exposure 1 +Start_readout_rs 0x0353 8 +- b manual_readout_start 0 +Frame_margin 0x0354 16 + +# sub-sampling registers +x_even_inc 0x0380 16 +x_odd_inc 0x0382 16 +y_even_inc 0x0384 16 +y_odd_inc 0x0386 16 + +# monochrome readout registers +monochrome_en 0x0390 v1.1 +- e enabled 0 + +# image scaling registers +Scaling_mode 0x0400 16 +- e no_scaling 0 +- e horizontal 1 +scale_m 0x0404 16 +scale_n 0x0406 16 +digital_crop_x_offset 0x0408 16 +digital_crop_y_offset 0x040a 16 +digital_crop_image_width 0x040c 16 +digital_crop_image_height 0x040e 16 + +# image compression registers +compression_mode 0x0500 16 +- e none 0 +- e dpcm_pcm_simple 1 + +# test pattern registers +test_pattern_mode 0x0600 16 +- e none 0 +- e solid_color 1 +- e color_bars 2 +- e fade_to_grey 3 +- e pn9 4 +- e color_tile 5 +test_data_red 0x0602 16 +test_data_greenR 0x0604 16 +test_data_blue 0x0606 16 +test_data_greenB 0x0608 16 +value_step_size_smooth 0x060a 8 +value_step_size_quantised 0x060b 8 + +# phy configuration registers +tclk_post 0x0800 8 +ths_prepare 0x0801 8 +ths_zero_min 0x0802 8 +ths_trail 0x0803 8 +tclk_trail_min 0x0804 8 +tclk_prepare 0x0805 8 +tclk_zero 0x0806 8 +tlpx 0x0807 8 +phy_ctrl 0x0808 8 +- e auto 0 +- e UI 1 +- e manual 2 +tclk_post_ex 0x080a 16 +ths_prepare_ex 0x080c 16 +ths_zero_min_ex 0x080e 16 +ths_trail_ex 0x0810 16 +tclk_trail_min_ex 0x0812 16 +tclk_prepare_ex 0x0814 16 +tclk_zero_ex 0x0816 16 +tlpx_ex 0x0818 16 + +# link rate register +requested_link_rate 0x0820 32 u16.16 + +# equalization control registers +DPHY_equalization_mode 0x0824 8 v1.1 +- b eq2 0 +PHY_equalization_ctrl 0x0825 8 v1.1 +- b enable 0 + +# d-phy preamble control registers +DPHY_preamble_ctrl 0x0826 8 v1.1 +- b enable 0 +DPHY_preamble_length 0x0826 8 v1.1 + +# d-phy spread spectrum control registers +PHY_SSC_ctrl 0x0828 8 v1.1 +- b enable 0 + +# manual lp control register +manual_LP_ctrl 0x0829 8 v1.1 +- b enable 0 + +# additional phy configuration registers +twakeup 0x082a v1.1 +tinit 0x082b v1.1 +ths_exit 0x082c v1.1 +ths_exit_ex 0x082e 16 v1.1 + +# phy calibration configuration registers +PHY_periodic_calibration_ctrl 0x0830 8 +- b frame_blanking 0 +PHY_periodic_calibration_interval 0x0831 8 +PHY_init_calibration_ctrl 0x0832 8 +- b stream_start 0 +DPHY_calibration_mode 0x0833 8 v1.1 +- b also_alternate 0 +CPHY_calibration_mode 0x0834 8 v1.1 +- e format_1 0 +- e format_2 1 +- e format_3 2 +t3_calpreamble_length 0x0835 8 v1.1 +t3_calpreamble_length_per 0x0836 8 v1.1 +t3_calaltseq_length 0x0837 8 v1.1 +t3_calaltseq_length_per 0x0838 8 v1.1 +FM2_init_seed 0x083a 16 v1.1 +t3_caludefseq_length 0x083c 16 v1.1 +t3_caludefseq_length_per 0x083e 16 v1.1 + +# c-phy manual control registers +TGR_Preamble_Length 0x0841 8 +- b preamable_prog_seq 7 +- f begin_preamble_length 0 5 +TGR_Post_Length 0x0842 8 +- f post_length 0 4 +TGR_Preamble_Prog_Sequence(n2) 0x0843 +- l n2 0 6 1 +- f symbol_n_1 3 5 +- f symbol_n 0 2 +t3_prepare 0x084e 16 +t3_lpx 0x0850 16 + +# alps control register +ALPS_ctrl 0x085a 8 +- b lvlp_dphy 0 +- b lvlp_cphy 1 +- b alp_cphy 2 + +# lrte control registers +TX_REG_CSI_EPD_EN_SSP_cphy 0x0860 16 +TX_REG_CSI_EPD_OP_SLP_cphy 0x0862 16 +TX_REG_CSI_EPD_EN_SSP_dphy 0x0864 16 +TX_REG_CSI_EPD_OP_SLP_dphy 0x0866 16 +TX_REG_CSI_EPD_MISC_OPTION_cphy 0x0868 v1.1 +TX_REG_CSI_EPD_MISC_OPTION_dphy 0x0869 v1.1 + +# scrambling control registers +Scrambling_ctrl 0x0870 +- b enabled 0 +- f 2 3 +- e 1_seed_cphy 0 +- e 4_seed_cphy 3 +lane_seed_value(seed, lane) 0x0872 16 +- l seed 0 3 0x10 +- l lane 0 7 0x2 + +# usl control registers +TX_USL_REV_ENTRY 0x08c0 16 v1.1 +TX_USL_REV_Clock_Counter 0x08c2 16 v1.1 +TX_USL_REV_LP_Counter 0x08c4 16 v1.1 +TX_USL_REV_Frame_Counter 0x08c6 16 v1.1 +TX_USL_REV_Chronological_Timer 0x08c8 16 v1.1 +TX_USL_FWD_ENTRY 0x08ca 16 v1.1 +TX_USL_GPIO 0x08cc 16 v1.1 +TX_USL_Operation 0x08ce 16 v1.1 +- b reset 0 +TX_USL_ALP_ctrl 0x08d0 16 v1.1 +- b clock_pause 0 +TX_USL_APP_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +TX_USL_SNS_BTA_ACK_TIMEOUT 0x08d2 16 v1.1 +USL_Clock_Mode_d_ctrl 0x08d2 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 + +# binning configuration registers +binning_mode 0x0900 8 +binning_type 0x0901 8 +binning_weighting 0x0902 8 + +# data transfer interface registers +data_transfer_if_1_ctrl 0x0a00 8 +- b enable 0 +- b write 1 +- b clear_error 2 +data_transfer_if_1_status 0x0a01 8 +- b read_if_ready 0 +- b write_if_ready 1 +- b data_corrupted 2 +- b improper_if_usage 3 +data_transfer_if_1_page_select 0x0a02 8 +data_transfer_if_1_data(p) 0x0a04 8 f +- l p 0 63 1 + +# image processing and sensor correction configuration registers +shading_correction_en 0x0b00 8 +- b enable 0 +luminance_correction_level 0x0b01 8 +green_imbalance_filter_en 0x0b02 8 +- b enable 0 +mapped_defect_correct_en 0x0b05 8 +- b enable 0 +single_defect_correct_en 0x0b06 8 +- b enable 0 +dynamic_couplet_correct_en 0x0b08 8 +- b enable 0 +combined_defect_correct_en 0x0b0a 8 +- b enable 0 +module_specific_correction_en 0x0b0c 8 +- b enable 0 +dynamic_triplet_defect_correct_en 0x0b13 8 +- b enable 0 +NF_ctrl 0x0b15 8 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black pixel readout registers +OB_readout_control 0x0b30 8 +- b enable 0 +- b interleaving 1 +OB_virtual_channel 0x0b31 8 +OB_DT 0x0b32 8 +OB_data_format 0x0b33 8 + +# color temperature feedback registers +color_temperature 0x0b8c 16 +absolute_gain_greenr 0x0b8e 16 +absolute_gain_red 0x0b90 16 +absolute_gain_blue 0x0b92 16 +absolute_gain_greenb 0x0b94 16 + +# cfa conversion registers +CFA_conversion_ctrl 0x0ba0 v1.1 +- b bayer_conversion_enable 0 + +# flash strobe and sa strobe control registers +flash_strobe_adjustment 0x0c12 8 +flash_strobe_start_point 0x0c14 16 +tflash_strobe_delay_rs_ctrl 0x0c16 16 +tflash_strobe_width_high_rs_ctrl 0x0c18 16 +flash_mode_rs 0x0c1a 8 +- b continuous 0 +- b truncate 1 +- b async 3 +flash_trigger_rs 0x0c1b 8 +flash_status 0x0c1c 8 +- b retimed 0 +sa_strobe_mode 0x0c1d 8 +- b continuous 0 +- b truncate 1 +- b async 3 +- b adjust_edge 4 +sa_strobe_start_point 0x0c1e 16 +tsa_strobe_delay_ctrl 0x0c20 16 +tsa_strobe_width_ctrl 0x0c22 16 +sa_strobe_trigger 0x0c24 8 +sa_strobe_status 0x0c25 8 +- b retimed 0 +tSA_strobe_re_delay_ctrl 0x0c30 16 +tSA_strobe_fe_delay_ctrl 0x0c32 16 + +# pdaf control registers +PDAF_ctrl 0x0d00 16 +- b enable 0 +- b processed 1 +- b interleaved 2 +- b visible_pdaf_correction 3 +PDAF_VC 0x0d02 8 +PDAF_DT 0x0d03 8 +pd_x_addr_start 0x0d04 16 +pd_y_addr_start 0x0d06 16 +pd_x_addr_end 0x0d08 16 +pd_y_addr_end 0x0d0a 16 + +# bracketing interface configuration registers +bracketing_LUT_ctrl 0x0e00 8 +bracketing_LUT_mode 0x0e01 8 +- b continue_streaming 0 +- b loop_mode 1 +bracketing_LUT_entry_ctrl 0x0e02 8 +bracketing_LUT_frame(n) 0x0e10 v1.1 f +- l n 0 0xef 1 + +# integration time and gain parameter limit registers +integration_time_capability 0x1000 16 +- b fine 0 +coarse_integration_time_min 0x1004 16 +coarse_integration_time_max_margin 0x1006 16 +fine_integration_time_min 0x1008 16 +fine_integration_time_max_margin 0x100a 16 + +# digital gain parameter limit registers +digital_gain_capability 0x1081 +- e none 0 +- e global 2 +digital_gain_min 0x1084 16 +digital_gain_max 0x1086 16 +digital_gain_step_size 0x1088 16 + +# data pedestal capability registers +Pedestal_capability 0x10e0 8 v1.1 + +# adc capability registers +ADC_capability 0x10f0 8 +- b bit_depth_ctrl 0 +ADC_bit_depth_capability 0x10f4 32 v1.1 + +# video timing parameter limit registers +min_ext_clk_freq_mhz 0x1100 32 float_ireal +max_ext_clk_freq_mhz 0x1104 32 float_ireal +min_pre_pll_clk_div 0x1108 16 +# min_vt_pre_pll_clk_div 0x1108 16 +max_pre_pll_clk_div 0x110a 16 +# max_vt_pre_pll_clk_div 0x110a 16 +min_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +# min_vt_pll_ip_clk_freq_mhz 0x110c 32 float_ireal +max_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +# max_vt_pll_ip_clk_freq_mhz 0x1110 32 float_ireal +min_pll_multiplier 0x1114 16 +# min_vt_pll_multiplier 0x1114 16 +max_pll_multiplier 0x1116 16 +# max_vt_pll_multiplier 0x1116 16 +min_pll_op_clk_freq_mhz 0x1118 32 float_ireal +max_pll_op_clk_freq_mhz 0x111c 32 float_ireal + +# video timing set-up capability registers +min_vt_sys_clk_div 0x1120 16 +max_vt_sys_clk_div 0x1122 16 +min_vt_sys_clk_freq_mhz 0x1124 32 float_ireal +max_vt_sys_clk_freq_mhz 0x1128 32 float_ireal +min_vt_pix_clk_freq_mhz 0x112c 32 float_ireal +max_vt_pix_clk_freq_mhz 0x1130 32 float_ireal +min_vt_pix_clk_div 0x1134 16 +max_vt_pix_clk_div 0x1136 16 +clock_calculation 0x1138 +- b lane_speed 0 +- b link_decoupled 1 +- b dual_pll_op_sys_ddr 2 +- b dual_pll_op_pix_ddr 3 +num_of_vt_lanes 0x1139 +num_of_op_lanes 0x113a +op_bits_per_lane 0x113b 8 v1.1 + +# frame timing parameter limits +min_frame_length_lines 0x1140 16 +max_frame_length_lines 0x1142 16 +min_line_length_pck 0x1144 16 +max_line_length_pck 0x1146 16 +min_line_blanking_pck 0x1148 16 +min_frame_blanking_lines 0x114a 16 +min_line_length_pck_step_size 0x114c +timing_mode_capability 0x114d +- b auto_frame_length 0 +- b rolling_shutter_manual_readout 2 +- b delayed_exposure_start 3 +- b manual_exposure_embedded_data 4 +frame_margin_max_value 0x114e 16 +frame_margin_min_value 0x1150 +gain_delay_type 0x1151 +- e fixed 0 +- e variable 1 + +# output clock set-up capability registers +min_op_sys_clk_div 0x1160 16 +max_op_sys_clk_div 0x1162 16 +min_op_sys_clk_freq_mhz 0x1164 32 float_ireal +max_op_sys_clk_freq_mhz 0x1168 32 float_ireal +min_op_pix_clk_div 0x116c 16 +max_op_pix_clk_div 0x116e 16 +min_op_pix_clk_freq_mhz 0x1170 32 float_ireal +max_op_pix_clk_freq_mhz 0x1174 32 float_ireal + +# image size parameter limit registers +x_addr_min 0x1180 16 +y_addr_min 0x1182 16 +x_addr_max 0x1184 16 +y_addr_max 0x1186 16 +min_x_output_size 0x1188 16 +min_y_output_size 0x118a 16 +max_x_output_size 0x118c 16 +max_y_output_size 0x118e 16 + +x_addr_start_div_constant 0x1190 v1.1 +y_addr_start_div_constant 0x1191 v1.1 +x_addr_end_div_constant 0x1192 v1.1 +y_addr_end_div_constant 0x1193 v1.1 +x_size_div 0x1194 v1.1 +y_size_div 0x1195 v1.1 +x_output_div 0x1196 v1.1 +y_output_div 0x1197 v1.1 +non_flexible_resolution_support 0x1198 v1.1 +- b new_pix_addr 0 +- b new_output_res 1 +- b output_crop_no_pad 2 +- b output_size_lane_dep 3 + +min_op_pre_pll_clk_div 0x11a0 16 +max_op_pre_pll_clk_div 0x11a2 16 +min_op_pll_ip_clk_freq_mhz 0x11a4 32 float_ireal +max_op_pll_ip_clk_freq_mhz 0x11a8 32 float_ireal +min_op_pll_multiplier 0x11ac 16 +max_op_pll_multiplier 0x11ae 16 +min_op_pll_op_clk_freq_mhz 0x11b0 32 float_ireal +max_op_pll_op_clk_freq_mhz 0x11b4 32 float_ireal +clock_tree_pll_capability 0x11b8 8 +- b dual_pll 0 +- b single_pll 1 +- b ext_divider 2 +- b flexible_op_pix_clk_div 3 +clock_capa_type_capability 0x11b9 v1.1 +- b ireal 0 + +# sub-sampling parameters limit registers +min_even_inc 0x11c0 16 +min_odd_inc 0x11c2 16 +max_even_inc 0x11c4 16 +max_odd_inc 0x11c6 16 +aux_subsamp_capability 0x11c8 v1.1 +- b factor_power_of_2 1 +aux_subsamp_mono_capability 0x11c9 v1.1 +- b factor_power_of_2 1 +monochrome_capability 0x11ca v1.1 +- e inc_odd 0 +- e inc_even 1 +pixel_readout_capability 0x11cb v1.1 +- e bayer 0 +- e monochrome 1 +- e bayer_and_mono 2 +min_even_inc_mono 0x11cc 16 v1.1 +max_even_inc_mono 0x11ce 16 v1.1 +min_odd_inc_mono 0x11d0 16 v1.1 +max_odd_inc_mono 0x11d2 16 v1.1 +min_even_inc_bc2 0x11d4 16 v1.1 +max_even_inc_bc2 0x11d6 16 v1.1 +min_odd_inc_bc2 0x11d8 16 v1.1 +max_odd_inc_bc2 0x11da 16 v1.1 +min_even_inc_mono_bc2 0x11dc 16 v1.1 +max_even_inc_mono_bc2 0x11de 16 v1.1 +min_odd_inc_mono_bc2 0x11f0 16 v1.1 +max_odd_inc_mono_bc2 0x11f2 16 v1.1 + +# image scaling limit parameters +scaling_capability 0x1200 16 +- e none 0 +- e horizontal 1 +- e reserved 2 +scaler_m_min 0x1204 16 +scaler_m_max 0x1206 16 +scaler_n_min 0x1208 16 +scaler_n_max 0x120a 16 +digital_crop_capability 0x120e +- e none 0 +- e input_crop 1 + +# hdr limit registers +hdr_capability_1 0x1210 +- b 2x2_binning 0 +- b combined_analog_gain 1 +- b separate_analog_gain 2 +- b upscaling 3 +- b reset_sync 4 +- b direct_short_exp_timing 5 +- b direct_short_exp_synthesis 6 +min_hdr_bit_depth 0x1211 +hdr_resolution_sub_types 0x1212 +hdr_resolution_sub_type(n) 0x1213 +- l n 0 1 1 +- f row 0 3 +- f column 4 7 +hdr_capability_2 0x121b +- b combined_digital_gain 0 +- b separate_digital_gain 1 +- b timing_mode 3 +- b synthesis_mode 4 +max_hdr_bit_depth 0x121c + +# usl capability register +usl_support_capability 0x1230 v1.1 +- b clock_tree 0 +- b rev_clock_tree 1 +- b rev_clock_calc 2 +usl_clock_mode_d_capability 0x1231 v1.1 +- b cont_clock_standby 0 +- b cont_clock_vblank 1 +- b cont_clock_hblank 2 +- b noncont_clock_standby 3 +- b noncont_clock_vblank 4 +- b noncont_clock_hblank 5 +min_op_sys_clk_div_rev 0x1234 v1.1 +max_op_sys_clk_div_rev 0x1236 v1.1 +min_op_pix_clk_div_rev 0x1238 v1.1 +max_op_pix_clk_div_rev 0x123a v1.1 +min_op_sys_clk_freq_rev_mhz 0x123c 32 v1.1 float_ireal +max_op_sys_clk_freq_rev_mhz 0x1240 32 v1.1 float_ireal +min_op_pix_clk_freq_rev_mhz 0x1244 32 v1.1 float_ireal +max_op_pix_clk_freq_rev_mhz 0x1248 32 v1.1 float_ireal +max_bitrate_rev_d_mode_mbps 0x124c 32 v1.1 ireal +max_symrate_rev_c_mode_msps 0x1250 32 v1.1 ireal + +# image compression capability registers +compression_capability 0x1300 +- b dpcm_pcm_simple 0 + +# test mode capability registers +test_mode_capability 0x1310 16 +- b solid_color 0 +- b color_bars 1 +- b fade_to_grey 2 +- b pn9 3 +- b color_tile 5 +pn9_data_format1 0x1312 +pn9_data_format2 0x1313 +pn9_data_format3 0x1314 +pn9_data_format4 0x1315 +pn9_misc_capability 0x1316 +- f num_pixels 0 2 +- b compression 3 +test_pattern_capability 0x1317 v1.1 +- b no_repeat 1 +pattern_size_div_m1 0x1318 v1.1 + +# fifo capability registers +fifo_support_capability 0x1502 +- e none 0 +- e derating 1 +- e derating_overrating 2 + +# csi-2 capability registers +phy_ctrl_capability 0x1600 +- b auto_phy_ctl 0 +- b ui_phy_ctl 1 +- b dphy_time_ui_reg_1_ctl 2 +- b dphy_time_ui_reg_2_ctl 3 +- b dphy_time_ctl 4 +- b dphy_ext_time_ui_reg_1_ctl 5 +- b dphy_ext_time_ui_reg_2_ctl 6 +- b dphy_ext_time_ctl 7 +csi_dphy_lane_mode_capability 0x1601 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +csi_signaling_mode_capability 0x1602 +- b csi_dphy 2 +- b csi_cphy 3 +fast_standby_capability 0x1603 +- e no_frame_truncation 0 +- e frame_truncation 1 +csi_address_control_capability 0x1604 +- b cci_addr_change 0 +- b 2nd_cci_addr 1 +- b sw_changeable_2nd_cci_addr 2 +data_type_capability 0x1605 +- b dpcm_programmable 0 +- b bottom_embedded_dt_programmable 1 +- b bottom_embedded_vc_programmable 2 +- b ext_vc_range 3 +csi_cphy_lane_mode_capability 0x1606 +- b 1_lane 0 +- b 2_lane 1 +- b 3_lane 2 +- b 4_lane 3 +- b 5_lane 4 +- b 6_lane 5 +- b 7_lane 6 +- b 8_lane 7 +emb_data_capability 0x1607 v1.1 +- b two_bytes_per_raw16 0 +- b two_bytes_per_raw20 1 +- b two_bytes_per_raw24 2 +- b no_one_byte_per_raw16 3 +- b no_one_byte_per_raw20 4 +- b no_one_byte_per_raw24 5 +max_per_lane_bitrate_lane_d_mode_mbps(n) 0x1608 32 ireal +- l n 0 7 4 4,0x32 +temp_sensor_capability 0x1618 +- b supported 0 +- b CCS_format 1 +- b reset_0x80 2 +max_per_lane_bitrate_lane_c_mode_mbps(n) 0x161a 32 ireal +- l n 0 7 4 4,0x30 +dphy_equalization_capability 0x162b +- b equalization_ctrl 0 +- b eq1 1 +- b eq2 2 +cphy_equalization_capability 0x162c +- b equalization_ctrl 0 +dphy_preamble_capability 0x162d +- b preamble_seq_ctrl 0 +dphy_ssc_capability 0x162e +- b supported 0 +cphy_calibration_capability 0x162f +- b manual 0 +- b manual_streaming 1 +- b format_1_ctrl 2 +- b format_2_ctrl 3 +- b format_3_ctrl 4 +dphy_calibration_capability 0x1630 +- b manual 0 +- b manual_streaming 1 +- b alternate_seq 2 +phy_ctrl_capability_2 0x1631 +- b tgr_length 0 +- b tgr_preamble_prog_seq 1 +- b extra_cphy_manual_timing 2 +- b clock_based_manual_cdphy 3 +- b clock_based_manual_dphy 4 +- b clock_based_manual_cphy 5 +- b manual_lp_dphy 6 +- b manual_lp_cphy 7 +lrte_cphy_capability 0x1632 +- b pdq_short 0 +- b spacer_short 1 +- b pdq_long 2 +- b spacer_long 3 +- b spacer_no_pdq 4 +lrte_dphy_capability 0x1633 +- b pdq_short_opt1 0 +- b spacer_short_opt1 1 +- b pdq_long_opt1 2 +- b spacer_long_opt1 3 +- b spacer_short_opt2 4 +- b spacer_long_opt2 5 +- b spacer_no_pdq_opt1 6 +- b spacer_variable_opt2 7 +alps_capability_dphy 0x1634 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +alps_capability_cphy 0x1635 +- e lvlp_not_supported 0 0x3 +- e lvlp_supported 1 0x3 +- e controllable_lvlp 2 0x3 +- e alp_not_supported 0xc 0xc +- e alp_supported 0xd 0xc +- e controllable_alp 0xe 0xc +scrambling_capability 0x1636 +- b scrambling_supported 0 +- f max_seeds_per_lane_c 1 2 +- e 1 0 +- e 4 3 +- f num_seed_regs 3 5 +- e 0 0 +- e 1 1 +- e 4 4 +- b num_seed_per_lane 6 +dphy_manual_constant 0x1637 +cphy_manual_constant 0x1638 +CSI2_interface_capability_misc 0x1639 v1.1 +- b eotp_short_pkt_opt2 0 +PHY_ctrl_capability_3 0x165c v1.1 +- b dphy_timing_not_multiple 0 +- b dphy_min_timing_value_1 1 +- b twakeup_supported 2 +- b tinit_supported 3 +- b ths_exit_supported 4 +- b cphy_timing_not_multiple 5 +- b cphy_min_timing_value_1 6 +dphy_sf 0x165d v1.1 +cphy_sf 0x165e v1.1 +- f twakeup 0 3 +- f tinit 4 7 +dphy_limits_1 0x165f v1.1 +- f ths_prepare 0 3 +- f ths_zero 4 7 +dphy_limits_2 0x1660 v1.1 +- f ths_trail 0 3 +- f tclk_trail_min 4 7 +dphy_limits_3 0x1661 v1.1 +- f tclk_prepare 0 3 +- f tclk_zero 4 7 +dphy_limits_4 0x1662 v1.1 +- f tclk_post 0 3 +- f tlpx 4 7 +dphy_limits_5 0x1663 v1.1 +- f ths_exit 0 3 +- f twakeup 4 7 +dphy_limits_6 0x1664 v1.1 +- f tinit 0 3 +cphy_limits_1 0x1665 v1.1 +- f t3_prepare_max 0 3 +- f t3_lpx_max 4 7 +cphy_limits_2 0x1666 v1.1 +- f ths_exit_max 0 3 +- f twakeup_max 4 7 +cphy_limits_3 0x1667 v1.1 +- f tinit_max 0 3 + +# binning capability registers +min_frame_length_lines_bin 0x1700 16 +max_frame_length_lines_bin 0x1702 16 +min_line_length_pck_bin 0x1704 16 +max_line_length_pck_bin 0x1706 16 +min_line_blanking_pck_bin 0x1708 16 +fine_integration_time_min_bin 0x170a 16 +fine_integration_time_max_margin_bin 0x170c 16 +binning_capability 0x1710 +- e unsupported 0 +- e binning_then_subsampling 1 +- e subsampling_then_binning 2 +binning_weighting_capability 0x1711 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types 0x1712 +binning_sub_type(n) 0x1713 +- l n 0 63 1 +- f row 0 3 +- f column 4 7 +binning_weighting_mono_capability 0x1771 v1.1 +- b averaged 0 +- b summed 1 +- b bayer_corrected 2 +- b module_specific_weight 3 +binning_sub_types_mono 0x1772 v1.1 +binning_sub_type_mono(n) 0x1773 v1.1 f +- l n 0 63 1 + +# data transfer interface capability registers +data_transfer_if_capability 0x1800 +- b supported 0 +- b polling 2 + +# sensor correction capability registers +shading_correction_capability 0x1900 +- b color_shading 0 +- b luminance_correction 1 +green_imbalance_capability 0x1901 +- b supported 0 +module_specific_correction_capability 0x1903 +defect_correction_capability 0x1904 16 +- b mapped_defect 0 +- b dynamic_couplet 2 +- b dynamic_single 5 +- b combined_dynamic 8 +defect_correction_capability_2 0x1906 16 +- b dynamic_triplet 3 +nf_capability 0x1908 +- b luma 0 +- b chroma 1 +- b combined 2 + +# optical black readout capability registers +ob_readout_capability 0x1980 +- b controllable_readout 0 +- b visible_pixel_readout 1 +- b different_vc_readout 2 +- b different_dt_readout 3 +- b prog_data_format 4 + +# color feedback capability registers +color_feedback_capability 0x1987 +- b kelvin 0 +- b awb_gain 1 + +# cfa pattern capability registers +CFA_pattern_capability 0x1990 v1.1 +- e bayer 0 +- e monochrome 1 +- e 4x4_quad_bayer 2 +- e vendor_specific 3 +CFA_pattern_conversion_capability 0x1991 v1.1 +- b bayer 0 + +# timer capability registers +flash_mode_capability 0x1a02 +- b single_strobe 0 +sa_strobe_mode_capability 0x1a03 +- b fixed_width 0 +- b edge_ctrl 1 + +# soft reset capability registers +reset_max_delay 0x1a10 v1.1 +reset_min_time 0x1a11 v1.1 + +# pdaf capability registers +pdaf_capability_1 0x1b80 +- b supported 0 +- b processed_bottom_embedded 1 +- b processed_interleaved 2 +- b raw_bottom_embedded 3 +- b raw_interleaved 4 +- b visible_pdaf_correction 5 +- b vc_interleaving 6 +- b dt_interleaving 7 +pdaf_capability_2 0x1b81 +- b ROI 0 +- b after_digital_crop 1 +- b ctrl_retimed 2 + +# bracketing interface capability registers +bracketing_lut_capability_1 0x1c00 +- b coarse_integration 0 +- b global_analog_gain 1 +- b flash 4 +- b global_digital_gain 5 +- b alternate_global_analog_gain 6 +bracketing_lut_capability_2 0x1c01 +- b single_bracketing_mode 0 +- b looped_bracketing_mode 1 +bracketing_lut_size 0x1c02 diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst new file mode 100644 index 000000000000..f49e971f2d92 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause + +.. include:: <isonum.txt> + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +<https://www.mipi.org/specifications/camera-command-set>`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) expses another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Register definition generator +----------------------------- + +The ccs-regs.asc file contains MIPI CCS register definitions that are used +to produce C source code files for definitions that can be better used by +programs written in C language. As there are many dependencies between the +produced files, please do not modify them manually as it's error-prone and +in vain, but instead change the script producing them. + +Usage +~~~~~ + +Conventionally the script is called this way to update the CCS driver +definitions: + +.. code-block:: none + + $ Documentation/driver-api/media/drivers/ccs/mk-ccs-regs -k \ + -e drivers/media/i2c/ccs/ccs-regs.h \ + -L drivers/media/i2c/ccs/ccs-limits.h \ + -l drivers/media/i2c/ccs/ccs-limits.c \ + -c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs new file mode 100755 index 000000000000..6668deaf2f19 --- /dev/null +++ b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs @@ -0,0 +1,433 @@ +#!/usr/bin/perl -w +# SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause +# Copyright (C) 2019--2020 Intel Corporation + +use Getopt::Long qw(:config no_ignore_case); +use File::Basename; + +my $ccsregs = "ccs-regs.asc"; +my $header; +my $regarray; +my $limitc; +my $limith; +my $kernel; +my $help; + +GetOptions("ccsregs|c=s" => \$ccsregs, + "header|e=s" => \$header, + "regarray|r=s" => \$regarray, + "limitc|l=s" => \$limitc, + "limith|L=s" => \$limith, + "kernel|k" => \$kernel, + "help|h" => \$help) or die "can't parse options"; + +$help = 1 if ! defined $header || ! defined $limitc || ! defined $limith; + +if (defined $help) { + print <<EOH +$0 - Create CCS register definitions for C + +usage: $0 -c ccs-regs.asc -e header -r regarray -l limit-c -L limit-header [-k] + + -c ccs register file + -e header file name + -r register description array file name + -l limit and capability array file name + -L limit and capability header file name + -k generate files for kernel space consumption +EOH + ; + exit 0; +} + +my $lh_hdr = ! defined $kernel + ? '#include "ccs-os.h"' . "\n" + : "#include <linux/bits.h>\n#include <linux/types.h>\n"; +my $uint32_t = ! defined $kernel ? 'uint32_t' : 'u32'; +my $uint16_t = ! defined $kernel ? 'uint16_t' : 'u16'; + +open(my $R, "< $ccsregs") or die "can't open $ccsregs"; + +open(my $H, "> $header") or die "can't open $header"; +my $A; +if (defined $regarray) { + open($A, "> $regarray") or die "can't open $regarray"; +} +open(my $LC, "> $limitc") or die "can't open $limitc"; +open(my $LH, "> $limith") or die "can't open $limith"; + +my %this; + +sub is_limit_reg($) { + my $addr = hex $_[0]; + + return 0 if $addr < 0x40; # weed out status registers + return 0 if $addr >= 0x100 && $addr < 0xfff; # weed out configuration registers + + return 1; +} + +my $uc_header = basename uc $header; +$uc_header =~ s/[^A-Z0-9]/_/g; + +my $copyright = "/* Copyright (C) 2019--2020 Intel Corporation */\n"; +my $license = "SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause"; + +for my $fh ($A, $LC) { + print $fh "// $license\n$copyright\n" if defined $fh; +} + +for my $fh ($H, $LH) { + print $fh "/* $license */\n$copyright\n"; +} + +sub bit_def($) { + my $bit = shift @_; + + return "BIT($bit)" if defined $kernel; + return "(1U << $bit)" if $bit =~ /^[a-zA-Z0-9_]+$/; + return "(1U << ($bit))"; +} + +print $H <<EOF +#ifndef __${uc_header}__ +#define __${uc_header}__ + +EOF + ; + +print $H "#include <linux/bits.h>\n\n" if defined $kernel; + +print $H <<EOF +#define CCS_FL_BASE 16 +EOF + ; + +print $H "#define CCS_FL_16BIT " . bit_def("CCS_FL_BASE") . "\n"; +print $H "#define CCS_FL_32BIT " . bit_def("CCS_FL_BASE + 1") . "\n"; +print $H "#define CCS_FL_FLOAT_IREAL " . bit_def("CCS_FL_BASE + 2") . "\n"; +print $H "#define CCS_FL_IREAL " . bit_def("CCS_FL_BASE + 3") . "\n"; + +print $H <<EOF +#define CCS_R_ADDR(r) ((r) & 0xffff) + +EOF + ; + +print $A <<EOF +#include <stdint.h> +#include <stdio.h> +#include "ccs-extra.h" +#include "ccs-regs.h" + +EOF + if defined $A; + +my $uc_limith = basename uc $limith; +$uc_limith =~ s/[^A-Z0-9]/_/g; + +print $LH <<EOF +#ifndef __${uc_limith}__ +#define __${uc_limith}__ + +$lh_hdr +struct ccs_limit { + $uint32_t reg; + $uint16_t size; + $uint16_t flags; + const char *name; +}; + +EOF + ; +print $LH "#define CCS_L_FL_SAME_REG " . bit_def(0) . "\n\n"; + +print $LH <<EOF +extern const struct ccs_limit ccs_limits[]; + +EOF + ; + +print $LC <<EOF +#include "ccs-limits.h" +#include "ccs-regs.h" + +const struct ccs_limit ccs_limits[] = { +EOF + ; + +my $limitcount = 0; +my $argdescs; +my $reglist = "const struct ccs_reg_desc ccs_reg_desc[] = {\n"; + +sub name_split($$) { + my ($name, $addr) = @_; + my $args; + + $name =~ /([^\(]+?)(\(.*)/; + ($name, $args) = ($1, $2); + $args = [split /,\s*/, $args]; + foreach my $t (@$args) { + $t =~ s/[\(\)]//g; + $t =~ s/\//\\\//g; + } + + return ($name, $addr, $args); +} + +sub tabconv($) { + $_ = shift; + + my @l = split "\n", $_; + + map { + s/ {8,8}/\t/g; + s/\t\K +//; + } @l; + + return (join "\n", @l) . "\n"; +} + +sub elem_size(@) { + my @flags = @_; + + return 2 if grep /^16$/, @flags; + return 4 if grep /^32$/, @flags; + return 1; +} + +sub arr_size($) { + my $this = $_[0]; + my $size = $this->{elsize}; + my $h = $this->{argparams}; + + foreach my $arg (@{$this->{args}}) { + my $apref = $h->{$arg}; + + $size *= $apref->{max} - $apref->{min} + 1; + } + + return $size; +} + +sub print_args($$$) { + my ($this, $postfix, $is_same_reg) = @_; + my ($args, $argparams, $name) = + ($this->{args}, $this->{argparams}, $this->{name}); + my $varname = "ccs_reg_arg_" . (lc $name) . $postfix; + my @mins; + my @sorted_args = @{$this->{sorted_args}}; + my $lim_arg; + my $size = arr_size($this); + + $argdescs .= "static const struct ccs_reg_arg " . $varname . "[] = {\n"; + + foreach my $sorted_arg (@sorted_args) { + push @mins, $argparams->{$sorted_arg}->{min}; + } + + foreach my $sorted_arg (@sorted_args) { + my $h = $argparams->{$sorted_arg}; + + $argdescs .= "\t{ \"$sorted_arg\", $h->{min}, $h->{max}, $h->{elsize} },\n"; + + $lim_arg .= defined $lim_arg ? ", $h->{min}" : "$h->{min}"; + } + + $argdescs .= "};\n\n"; + + $reglist .= "\t{ CCS_R_" . (uc $name) . "(" . (join ",", (@mins)) . + "), $size, sizeof($varname) / sizeof(*$varname)," . + " \"" . (lc $name) . "\", $varname },\n"; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . "($lim_arg), " . + $size . ", " . ($is_same_reg ? "CCS_L_FL_SAME_REG" : "0") . + ", \"$name" . (defined $this->{discontig} ? " $lim_arg" : "") . "\" },\n" + if is_limit_reg $this->{base_addr}; +} + +my $hdr_data; + +while (<$R>) { + chop; + s/^\s*//; + next if /^[#;]/ || /^$/; + if (s/^-\s*//) { + if (s/^b\s*//) { + my ($bit, $addr) = split /\t+/; + $bit = uc $bit; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) ."_$bit", bit_def($addr) . "\n"; + } elsif (s/^f\s*//) { + s/[,\.-]/_/g; + my @a = split /\s+/; + my ($msb, $lsb, $this_field) = reverse @a; + @a = ( { "name" => "SHIFT", "addr" => $lsb, "fmt" => "%uU", }, + { "name" => "MASK", "addr" => (1 << ($msb + 1)) - 1 - ((1 << $lsb) - 1), "fmt" => "0x%" . join(".", ($this{"elsize"} >> 2) x 2) . "x" } ); + $this{"field"} = $this_field; + foreach my $ar (@a) { + #print $ar->{fmt}."\n"; + $hdr_data .= sprintf "#define %-62s " . $ar->{"fmt"} . "\n", "CCS_" . (uc $this{"name"}) . (defined $this_field ? "_" . uc $this_field : "") . "_" . $ar->{"name"}, $ar->{"addr"} . "\n"; + } + } elsif (s/^e\s*//) { + s/[,\.-]/_/g; + my ($enum, $addr) = split /\s+/; + $enum = uc $enum; + $hdr_data .= sprintf "#define %-62s %s", "CCS_" . (uc ${this{name}}) . (defined $this{"field"} ? "_" . uc $this{"field"} : "") ."_$enum", $addr . ($addr =~ /0x/i ? "" : "U") . "\n"; + } elsif (s/^l\s*//) { + my ($arg, $min, $max, $elsize, @discontig) = split /\s+/; + my $size; + + foreach my $num ($min, $max) { + $num = hex $num if $num =~ /0x/i; + } + + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MIN_$arg"), $min . ($min =~ /0x/i ? "" : "U") . "\n"; + $hdr_data .= sprintf "#define %-62s %s", "CCS_LIM_" . (uc ${this{name}} . "_MAX_$arg"), $max . ($max =~ /0x/i ? "" : "U") . "\n"; + + my $h = $this{argparams}; + + $h->{$arg} = { "min" => $min, + "max" => $max, + "elsize" => $elsize =~ /^0x/ ? hex $elsize : $elsize, + "discontig" => \@discontig }; + + $this{discontig} = $arg if @discontig; + + next if $#{$this{args}} + 1 != scalar keys %{$this{argparams}}; + + my $reg_formula = "($this{addr}"; + my $lim_formula; + + foreach my $arg (@{$this{args}}) { + my $d = $h->{$arg}->{discontig}; + my $times = $h->{$arg}->{elsize} != 1 ? + " * " . $h->{$arg}->{elsize} : ""; + + if (@$d) { + my ($lim, $offset) = split /,/, $d->[0]; + + $reg_formula .= " + (($arg) < $lim ? ($arg)$times : $offset + (($arg) - $lim)$times)"; + } else { + $reg_formula .= " + ($arg)$times"; + } + + $lim_formula .= (defined $lim_formula ? " + " : "") . "($arg)$times"; + } + + $reg_formula .= ")\n"; + $lim_formula =~ s/^\(([a-z0-9]+)\)$/$1/i; + + print $H tabconv sprintf("#define %-62s %s", "CCS_R_" . (uc $this{name}) . + $this{arglist}, $reg_formula); + + print $H tabconv $hdr_data; + undef $hdr_data; + + # Sort arguments in descending order by size + @{$this{sorted_args}} = sort { + $h->{$a}->{elsize} <= $h->{$b}->{elsize} + } @{$this{args}}; + + if (defined $this{discontig}) { + my $da = $this{argparams}->{$this{discontig}}; + my ($first_discontig) = split /,/, $da->{discontig}->[0]; + my $max = $da->{max}; + + $da->{max} = $first_discontig - 1; + print_args(\%this, "", 0); + + $da->{min} = $da->{max} + 1; + $da->{max} = $max; + print_args(\%this, $first_discontig, 1); + } else { + print_args(\%this, "", 0); + } + + next unless is_limit_reg $this{base_addr}; + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}) . "_OFFSET(" . + (join ", ", @{$this{args}}) . ")", "($lim_formula)"; + } + + if (! @{$this{args}}) { + print $H tabconv($hdr_data); + undef $hdr_data; + } + + next; + } + + my ($name, $addr, @flags) = split /\t+/, $_; + my $args = []; + + my $sp; + + ($name, $addr, $args) = name_split($name, $addr) if /\(.*\)/; + + $name =~ s/[,\.-]/_/g; + + my $flagstring = ""; + my $size = elem_size(@flags); + $flagstring .= "| CCS_FL_16BIT " if $size eq "2"; + $flagstring .= "| CCS_FL_32BIT " if $size eq "4"; + $flagstring .= "| CCS_FL_FLOAT_IREAL " if grep /^float_ireal$/, @flags; + $flagstring .= "| CCS_FL_IREAL " if grep /^ireal$/, @flags; + $flagstring =~ s/^\| //; + $flagstring =~ s/ $//; + $flagstring = "($flagstring)" if $flagstring =~ /\|/; + my $base_addr = $addr; + $addr = "($addr | $flagstring)" if $flagstring ne ""; + + my $arglist = @$args ? "(" . (join ", ", @$args) . ")" : ""; + $hdr_data .= sprintf "#define %-62s %s\n", "CCS_R_" . (uc $name), $addr + if !@$args; + + $name =~ s/\(.*//; + + %this = ( name => $name, + addr => $addr, + base_addr => $base_addr, + argparams => {}, + args => $args, + arglist => $arglist, + elsize => $size, + ); + + if (!@$args) { + $reglist .= "\t{ CCS_R_" . (uc $name) . ", 1, 0, \"" . (lc $name) . "\", NULL },\n"; + print $H tabconv $hdr_data; + undef $hdr_data; + + print $LC tabconv sprintf "\t{ CCS_R_" . (uc $name) . ", " . + $this{elsize} . ", 0, \"$name\" },\n" + if is_limit_reg $this{base_addr}; + } + + print $LH tabconv sprintf "#define %-63s%s\n", + "CCS_L_" . (uc $this{name}), $limitcount++ + if is_limit_reg $this{base_addr}; +} + +if (defined $A) { + print $A $argdescs, $reglist; + + print $A "\t{ 0 }\n"; + + print $A "};\n"; +} + +print $H "\n#endif /* __${uc_header}__ */\n"; + +print $LH tabconv sprintf "#define %-63s%s\n", "CCS_L_LAST", $limitcount; + +print $LH "\n#endif /* __${uc_limith}__ */\n"; + +print $LC "\t{ 0 } /* Guardian */\n"; +print $LC "};\n"; + +close($R); +close($H); +close($A) if defined $A; +close($LC); +close($LH); diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index 0df85fc96605..426cda633bf0 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -25,6 +25,8 @@ Video4Linux (V4L) drivers sh_mobile_ceu_camera tuners vimc-devel + zoran + ccs/ccs Digital TV drivers @@ -35,4 +37,5 @@ Digital TV drivers dvb-usb frontends + vidtv contributors diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst new file mode 100644 index 000000000000..673bdff919ea --- /dev/null +++ b/Documentation/driver-api/media/drivers/vidtv.rst @@ -0,0 +1,513 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +vidtv: Virtual Digital TV driver +================================ + +Author: Daniel W. S. Almeida <dwlsalmeida@gmail.com>, June 2020. + +Background +---------- + +Vidtv is a virtual DVB driver that aims to serve as a reference for driver +writers by serving as a template. It also validates the existing media DVB +APIs, thus helping userspace application writers. + +Currently, it consists of: + +- A fake tuner driver, which will report a bad signal quality if the chosen + frequency is too far away from a table of valid frequencies for a + particular delivery system. + +- A fake demod driver, which will constantly poll the fake signal quality + returned by the tuner, simulating a device that can lose/reacquire a lock + on the signal depending on the CNR levels. + +- A fake bridge driver, which is the module responsible for modprobing the + fake tuner and demod modules and implementing the demux logic. This module + takes parameters at initialization that will dictate how the simulation + behaves. + +- Code reponsible for encoding a valid MPEG Transport Stream, which is then + passed to the bridge driver. This fake stream contains some hardcoded content. + For now, we have a single, audio-only channel containing a single MPEG + Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave. + Note that this particular encoder was chosen because it is the easiest + way to encode PCM audio data in a MPEG Transport Stream. + +Building vidtv +-------------- +vidtv is a test driver and thus is **not** enabled by default when +compiling the kernel. + +In order to enable compilation of vidtv: + +- Enable **DVB_TEST_DRIVERS**, then +- Enable **DVB_VIDTV** + +When compiled as a module, expect the following .ko files: + +- dvb_vidtv_tuner.ko + +- dvb_vidtv_demod.ko + +- dvb_vidtv_bridge.ko + +Running vidtv +------------- +When compiled as a module, run:: + + modprobe vidtv + +That's it! The bridge driver will initialize the tuner and demod drivers as +part of its own initialization. + +By default, it will accept the following frequencies: + + - 474 MHz for DVB-T/T2/C; + - 11,362 GHz for DVB-S/S2. + +For satellite systems, the driver simulates an universal extended +LNBf, with frequencies at Ku-Band, ranging from 10.7 GHz to 12.75 GHz. + +You can optionally define some command-line arguments to vidtv. + +Command-line arguments to vidtv +------------------------------- +Below is a list of all arguments that can be supplied to vidtv: + +drop_tslock_prob_on_low_snr + Probability of losing the TS lock if the signal quality is bad. + This probability be used by the fake demodulator driver to + eventually return a status of 0 when the signal quality is not + good. + +recover_tslock_prob_on_good_snr: + Probability recovering the TS lock when the signal improves. This + probability be used by the fake demodulator driver to eventually + return a status of 0x1f when/if the signal quality improves. + +mock_power_up_delay_msec + Simulate a power up delay. Default: 0. + +mock_tune_delay_msec + Simulate a tune delay. Default 0. + +vidtv_valid_dvb_t_freqs + Valid DVB-T frequencies to simulate, in Hz. + +vidtv_valid_dvb_c_freqs + Valid DVB-C frequencies to simulate, in Hz. + +vidtv_valid_dvb_s_freqs + Valid DVB-S/S2 frequencies to simulate at Ku-Band, in kHz. + +max_frequency_shift_hz, + Maximum shift in HZ allowed when tuning in a channel. + +si_period_msec + How often to send SI packets. Default: 40ms. + +pcr_period_msec + How often to send PCR packets. Default: 40ms. + +mux_rate_kbytes_sec + Attempt to maintain this bit rate by inserting TS null packets, if + necessary. Default: 4096. + +pcr_pid, + PCR PID for all channels. Default: 0x200. + +mux_buf_sz_pkts, + Size for the mux buffer in multiples of 188 bytes. + +vidtv internal structure +------------------------ +The kernel modules are split in the following way: + +vidtv_tuner.[ch] + Implements a fake tuner DVB driver. + +vidtv_demod.[ch] + Implements a fake demodulator DVB driver. + +vidtv_bridge.[ch] + Implements a bridge driver. + +The MPEG related code is split in the following way: + +vidtv_ts.[ch] + Code to work with MPEG TS packets, such as TS headers, adaptation + fields, PCR packets and NULL packets. + +vidtv_psi.[ch] + This is the PSI generator. PSI packets contain general information + about a MPEG Transport Stream. A PSI generator is needed so + userspace apps can retrieve information about the Transport Stream + and eventually tune into a (dummy) channel. + + Because the generator is implemented in a separate file, it can be + reused elsewhere in the media subsystem. + + Currently vidtv supports working with 5 PSI tables: PAT, PMT, + SDT, NIT and EIT. + + The specification for PAT and PMT can be found in *ISO 13818-1: + Systems*, while the specification for the SDT, NIT, EIT can be found in *ETSI + EN 300 468: Specification for Service Information (SI) in DVB + systems*. + + It isn't strictly necessary, but using a real TS file helps when + debugging PSI tables. Vidtv currently tries to replicate the PSI + structure found in this file: `TS1Globo.ts + <https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts>`_. + + A good way to visualize the structure of streams is by using + `DVBInspector <https://sourceforge.net/projects/dvbinspector/>`_. + +vidtv_pes.[ch] + Implements the PES logic to convert encoder data into MPEG TS + packets. These can then be fed into a TS multiplexer and eventually + into userspace. + +vidtv_encoder.h + An interface for vidtv encoders. New encoders can be added to this + driver by implementing the calls in this file. + +vidtv_s302m.[ch] + Implements a S302M encoder to make it possible to insert PCM audio + data in the generated MPEG Transport Stream. The relevant + specification is available online as *SMPTE 302M-2007: Television - + Mapping of AES3 Data into MPEG-2 Transport Stream*. + + + The resulting MPEG Elementary Stream is conveyed in a private + stream with a S302M registration descriptor attached. + + This shall enable passing an audio signal into userspace so it can + be decoded and played by media software. The corresponding decoder + in ffmpeg is located in 'libavcodec/s302m.c' and is experimental. + +vidtv_channel.[ch] + Implements a 'channel' abstraction. + + When vidtv boots, it will create some hardcoded channels: + + #. Their services will be concatenated to populate the SDT. + + #. Their programs will be concatenated to populate the PAT + + #. Their events will be concatenated to populate the EIT + + #. For each program in the PAT, a PMT section will be created + + #. The PMT section for a channel will be assigned its streams. + + #. Every stream will have its corresponding encoder polled in a + loop to produce TS packets. + These packets may be interleaved by the muxer and then delivered + to the bridge. + +vidtv_mux.[ch] + Implements a MPEG TS mux, loosely based on the ffmpeg + implementation in "libavcodec/mpegtsenc.c" + + The muxer runs a loop which is responsible for: + + #. Keeping track of the amount of time elapsed since the last + iteration. + + #. Polling encoders in order to fetch 'elapsed_time' worth of data. + + #. Inserting PSI and/or PCR packets, if needed. + + #. Padding the resulting stream with NULL packets if + necessary in order to maintain the chosen bit rate. + + #. Delivering the resulting TS packets to the bridge + driver so it can pass them to the demux. + +Testing vidtv with v4l-utils +---------------------------- + +Using the tools in v4l-utils is a great way to test and inspect the output of +vidtv. It is hosted here: `v4l-utils Documentation +<https://linuxtv.org/wiki/index.php/V4l-utils>`_. + +From its webpage:: + + The v4l-utils are a series of packages for handling media devices. + + It is hosted at http://git.linuxtv.org/v4l-utils.git, and packaged + on most distributions. + + It provides a series of libraries and utilities to be used to + control several aspect of the media boards. + + +Start by installing v4l-utils and then modprobing vidtv:: + + modprobe dvb_vidtv_bridge + +If the driver is OK, it should load and its probing code will run. This will +pull in the tuner and demod drivers. + +Using dvb-fe-tool +~~~~~~~~~~~~~~~~~ + +The first step to check whether the demod loaded successfully is to run:: + + $ dvb-fe-tool + Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities: + CAN_FEC_1_2 + CAN_FEC_2_3 + CAN_FEC_3_4 + CAN_FEC_4_5 + CAN_FEC_5_6 + CAN_FEC_6_7 + CAN_FEC_7_8 + CAN_FEC_8_9 + CAN_FEC_AUTO + CAN_GUARD_INTERVAL_AUTO + CAN_HIERARCHY_AUTO + CAN_INVERSION_AUTO + CAN_QAM_16 + CAN_QAM_32 + CAN_QAM_64 + CAN_QAM_128 + CAN_QAM_256 + CAN_QAM_AUTO + CAN_QPSK + CAN_TRANSMISSION_MODE_AUTO + DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A + Supported delivery systems: + DVBT + DVBT2 + [DVBC/ANNEX_A] + DVBS + DVBS2 + Frequency range for the current standard: + From: 51.0 MHz + To: 2.15 GHz + Step: 62.5 kHz + Tolerance: 29.5 MHz + Symbol rate ranges for the current standard: + From: 1.00 MBauds + To: 45.0 MBauds + +This should return what is currently set up at the demod struct, i.e.:: + + static const struct dvb_frontend_ops vidtv_demod_ops = { + .delsys = { + SYS_DVBT, + SYS_DVBT2, + SYS_DVBC_ANNEX_A, + SYS_DVBS, + SYS_DVBS2, + }, + + .info = { + .name = "Dummy demod for DVB-T/T2/C/S/S2", + .frequency_min_hz = 51 * MHz, + .frequency_max_hz = 2150 * MHz, + .frequency_stepsize_hz = 62500, + .frequency_tolerance_hz = 29500 * kHz, + .symbol_rate_min = 1000000, + .symbol_rate_max = 45000000, + + .caps = FE_CAN_FEC_1_2 | + FE_CAN_FEC_2_3 | + FE_CAN_FEC_3_4 | + FE_CAN_FEC_4_5 | + FE_CAN_FEC_5_6 | + FE_CAN_FEC_6_7 | + FE_CAN_FEC_7_8 | + FE_CAN_FEC_8_9 | + FE_CAN_QAM_16 | + FE_CAN_QAM_64 | + FE_CAN_QAM_32 | + FE_CAN_QAM_128 | + FE_CAN_QAM_256 | + FE_CAN_QAM_AUTO | + FE_CAN_QPSK | + FE_CAN_FEC_AUTO | + FE_CAN_INVERSION_AUTO | + FE_CAN_TRANSMISSION_MODE_AUTO | + FE_CAN_GUARD_INTERVAL_AUTO | + FE_CAN_HIERARCHY_AUTO, + } + + .... + +For more information on dvb-fe-tools check its online documentation here: +`dvb-fe-tool Documentation +<https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_. + +Using dvb-scan +~~~~~~~~~~~~~~ + +In order to tune into a channel and read the PSI tables, we can use dvb-scan. + +For this, one should provide a configuration file known as a 'scan file', +here's an example:: + + [Channel] + FREQUENCY = 474000000 + MODULATION = QAM/AUTO + SYMBOL_RATE = 6940000 + INNER_FEC = AUTO + DELIVERY_SYSTEM = DVBC/ANNEX_A + +.. note:: + The parameters depend on the video standard you're testing. + +.. note:: + Vidtv is a fake driver and does not validate much of the information + in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM' + should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you + should also provide 'SYMBOL_RATE'. + +You can browse scan tables online here: `dvb-scan-tables +<https://git.linuxtv.org/dtv-scan-tables.git>`_. + +Assuming this channel is named 'channel.conf', you can then run:: + + $ dvbv5-scan channel.conf + dvbv5-scan ~/vidtv.conf + ERROR command BANDWIDTH_HZ (5) not found during retrieve + Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet). + Scanning frequency #1 330000000 + (0x00) Signal= -68.00dBm + Scanning frequency #2 474000000 + Lock (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0 + Service Beethoven, provider LinuxTV.org: digital television + +For more information on dvb-scan, check its documentation online here: +`dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_. + +Using dvb-zap +~~~~~~~~~~~~~ + +dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The +typical use is to tune into a channel and put it into record mode. The example +below - which is taken from the documentation - illustrates that\ [1]_:: + + $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10 + using demux 'dvb0.demux0' + reading channels from file 'dvb_channel.conf' + tuning to 474000000 Hz + pass all PID's to TS + dvb_set_pesfilter 8192 + dvb_dev_set_bufsize: buffer set to 6160384 + Lock (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Lock (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0 + Record to file 'music.ts' started + received 24587768 bytes (2401 Kbytes/sec) + Lock (0x1f) Quality= Good Signal= -34.42dBm C/N= 33.89dB UCB= 0 postBER= 0 preBER= 2.44x10^-3 PER= 0 + +.. [1] In this example, it records 10 seconds with all program ID's stored + at the music.ts file. + + +The channel can be watched by playing the contents of the stream with some +player that recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``. + +By playing the contents of the stream one can visually inspect the workings of +vidtv, e.g., to play a recorded TS file with:: + + $ mplayer music.ts + +or, alternatively, running this command on one terminal:: + + $ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r & + +And, on a second terminal, playing the contents from DVR interface with:: + + $ mplayer /dev/dvb/adapter0/dvr0 + +For more information on dvb-zap check its online documentation here: +`dvb-zap Documentation +<https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_. +See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_. + + +What can still be improved in vidtv +----------------------------------- + +Add *debugfs* integration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although frontend drivers provide DVBv5 statistics via the .read_status +call, a nice addition would be to make additional statistics available to +userspace via debugfs, which is a simple-to-use, RAM-based filesystem +specifically designed for debug purposes. + +The logic for this would be implemented on a separate file so as not to +pollute the frontend driver. These statistics are driver-specific and can +be useful during tests. + +The Siano driver is one example of a driver using +debugfs to convey driver-specific statistics to userspace and it can be +used as a reference. + +This should be further enabled and disabled via a Kconfig +option for convenience. + +Add a way to test video +~~~~~~~~~~~~~~~~~~~~~~~ + +Currently, vidtv can only encode PCM audio. It would be great to implement +a barebones version of MPEG-2 video encoding so we can also test video. The +first place to look into is *ISO 13818-2: Information technology — Generic +coding of moving pictures and associated audio information — Part 2: Video*, +which covers the encoding of compressed video in MPEG Transport Streams. + +This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg, +which resides at:: + + drivers/media/common/v4l2-tpg/ + + +Add white noise simulation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The vidtv tuner already has code to identify whether the chosen frequency +is too far away from a table of valid frequencies. For now, this means that +the demodulator can eventually lose the lock on the signal, since the tuner will +report a bad signal quality. + +A nice addition is to simulate some noise when the signal quality is bad by: + +- Randomly dropping some TS packets. This will trigger a continuity error if the + continuity counter is updated but the packet is not passed on to the demux. + +- Updating the error statistics accordingly (e.g. BER, etc). + +- Simulating some noise in the encoded data. + +Functions and structs used within vidtv +--------------------------------------- + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c + +.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c diff --git a/Documentation/driver-api/media/drivers/zoran.rst b/Documentation/driver-api/media/drivers/zoran.rst new file mode 100644 index 000000000000..83cbae9cedef --- /dev/null +++ b/Documentation/driver-api/media/drivers/zoran.rst @@ -0,0 +1,575 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Zoran driver +================ + +unified zoran driver (zr360x7, zoran, buz, dc10(+), dc30(+), lml33) + +website: http://mjpeg.sourceforge.net/driver-zoran/ + + +Frequently Asked Questions +-------------------------- + +What cards are supported +------------------------ + +Iomega Buz, Linux Media Labs LML33/LML33R10, Pinnacle/Miro +DC10/DC10+/DC30/DC30+ and related boards (available under various names). + +Iomega Buz +~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36060 MJPEG codec +* Philips saa7111 TV decoder +* Philips saa7185 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, saa7111, saa7185, zr36060, zr36067 + +Inputs/outputs: Composite and S-video + +Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) + +Card number: 7 + +AverMedia 6 Eyes AVS6EYES +~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36060 MJPEG codec +* Samsung ks0127 TV decoder +* Conexant bt866 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, ks0127, bt866, zr36060, zr36067 + +Inputs/outputs: + Six physical inputs. 1-6 are composite, + 1-2, 3-4, 5-6 doubles as S-video, + 1-3 triples as component. + One composite output. + +Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) + +Card number: 8 + +.. note:: + + Not autodetected, card=8 is necessary. + +Linux Media Labs LML33 +~~~~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36060 MJPEG codec +* Brooktree bt819 TV decoder +* Brooktree bt856 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, bt819, bt856, zr36060, zr36067 + +Inputs/outputs: Composite and S-video + +Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) + +Card number: 5 + +Linux Media Labs LML33R10 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36060 MJPEG codec +* Philips saa7114 TV decoder +* Analog Devices adv7170 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, saa7114, adv7170, zr36060, zr36067 + +Inputs/outputs: Composite and S-video + +Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) + +Card number: 6 + +Pinnacle/Miro DC10(new) +~~~~~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36057 PCI controller +* Zoran zr36060 MJPEG codec +* Philips saa7110a TV decoder +* Analog Devices adv7176 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, saa7110, adv7175, zr36060, zr36067 + +Inputs/outputs: Composite, S-video and Internal + +Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) + +Card number: 1 + +Pinnacle/Miro DC10+ +~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36060 MJPEG codec +* Philips saa7110a TV decoder +* Analog Devices adv7176 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, saa7110, adv7175, zr36060, zr36067 + +Inputs/outputs: Composite, S-video and Internal + +Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) + +Card number: 2 + +Pinnacle/Miro DC10(old) +~~~~~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36057 PCI controller +* Zoran zr36050 MJPEG codec +* Zoran zr36016 Video Front End or Fuji md0211 Video Front End (clone?) +* Micronas vpx3220a TV decoder +* mse3000 TV encoder or Analog Devices adv7176 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, vpx3220, mse3000/adv7175, zr36050, zr36016, zr36067 + +Inputs/outputs: Composite, S-video and Internal + +Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) + +Card number: 0 + +Pinnacle/Miro DC30 +~~~~~~~~~~~~~~~~~~ + +* Zoran zr36057 PCI controller +* Zoran zr36050 MJPEG codec +* Zoran zr36016 Video Front End +* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder +* Analog Devices adv7176 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36016, zr36067 + +Inputs/outputs: Composite, S-video and Internal + +Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) + +Card number: 3 + +Pinnacle/Miro DC30+ +~~~~~~~~~~~~~~~~~~~ + +* Zoran zr36067 PCI controller +* Zoran zr36050 MJPEG codec +* Zoran zr36016 Video Front End +* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder +* Analog Devices adv7176 TV encoder + +Drivers to use: videodev, i2c-core, i2c-algo-bit, +videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36015, zr36067 + +Inputs/outputs: Composite, S-video and Internal + +Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) + +Card number: 4 + +.. note:: + + #) No module for the mse3000 is available yet + #) No module for the vpx3224 is available yet + +1.1 What the TV decoder can do an what not +------------------------------------------ + +The best know TV standards are NTSC/PAL/SECAM. but for decoding a frame that +information is not enough. There are several formats of the TV standards. +And not every TV decoder is able to handle every format. Also the every +combination is supported by the driver. There are currently 11 different +tv broadcast formats all aver the world. + +The CCIR defines parameters needed for broadcasting the signal. +The CCIR has defined different standards: A,B,D,E,F,G,D,H,I,K,K1,L,M,N,... +The CCIR says not much about the colorsystem used !!! +And talking about a colorsystem says not to much about how it is broadcast. + +The CCIR standards A,E,F are not used any more. + +When you speak about NTSC, you usually mean the standard: CCIR - M using +the NTSC colorsystem which is used in the USA, Japan, Mexico, Canada +and a few others. + +When you talk about PAL, you usually mean: CCIR - B/G using the PAL +colorsystem which is used in many Countries. + +When you talk about SECAM, you mean: CCIR - L using the SECAM Colorsystem +which is used in France, and a few others. + +There the other version of SECAM, CCIR - D/K is used in Bulgaria, China, +Slovakai, Hungary, Korea (Rep.), Poland, Rumania and a others. + +The CCIR - H uses the PAL colorsystem (sometimes SECAM) and is used in +Egypt, Libya, Sri Lanka, Syrain Arab. Rep. + +The CCIR - I uses the PAL colorsystem, and is used in Great Britain, Hong Kong, +Ireland, Nigeria, South Africa. + +The CCIR - N uses the PAL colorsystem and PAL frame size but the NTSC framerate, +and is used in Argentinia, Uruguay, an a few others + +We do not talk about how the audio is broadcast ! + +A rather good sites about the TV standards are: +http://www.sony.jp/support/ +http://info.electronicwerkstatt.de/bereiche/fernsehtechnik/frequenzen_und_normen/Fernsehnormen/ +and http://www.cabl.com/restaurant/channel.html + +Other weird things around: NTSC 4.43 is a modificated NTSC, which is mainly +used in PAL VCR's that are able to play back NTSC. PAL 60 seems to be the same +as NTSC 4.43 . The Datasheets also talk about NTSC 44, It seems as if it would +be the same as NTSC 4.43. +NTSC Combs seems to be a decoder mode where the decoder uses a comb filter +to split coma and luma instead of a Delay line. + +But I did not defiantly find out what NTSC Comb is. + +Philips saa7111 TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1997, is used in the BUZ and +- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC N, NTSC 4.43 and SECAM + +Philips saa7110a TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1995, is used in the Pinnacle/Miro DC10(new), DC10+ and +- can handle: PAL B/G, NTSC M and SECAM + +Philips saa7114 TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 2000, is used in the LML33R10 and +- can handle: PAL B/G/D/H/I/N, PAL N, PAL M, NTSC M, NTSC 4.43 and SECAM + +Brooktree bt819 TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1996, and is used in the LML33 and +- can handle: PAL B/D/G/H/I, NTSC M + +Micronas vpx3220a TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1996, is used in the DC30 and DC30+ and +- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC 44, PAL 60, SECAM,NTSC Comb + +Samsung ks0127 TV decoder +~~~~~~~~~~~~~~~~~~~~~~~~~ + +- is used in the AVS6EYES card and +- can handle: NTSC-M/N/44, PAL-M/N/B/G/H/I/D/K/L and SECAM + + +What the TV encoder can do an what not +-------------------------------------- + +The TV encoder is doing the "same" as the decoder, but in the other direction. +You feed them digital data and the generate a Composite or SVHS signal. +For information about the colorsystems and TV norm take a look in the +TV decoder section. + +Philips saa7185 TV Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1996, is used in the BUZ +- can generate: PAL B/G, NTSC M + +Brooktree bt856 TV Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1994, is used in the LML33 +- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL-N (Argentina) + +Analog Devices adv7170 TV Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 2000, is used in the LML300R10 +- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL 60 + +Analog Devices adv7175 TV Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1996, is used in the DC10, DC10+, DC10 old, DC30, DC30+ +- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M + +ITT mse3000 TV encoder +~~~~~~~~~~~~~~~~~~~~~~ + +- was introduced in 1991, is used in the DC10 old +- can generate: PAL , NTSC , SECAM + +Conexant bt866 TV encoder +~~~~~~~~~~~~~~~~~~~~~~~~~ + +- is used in AVS6EYES, and +- can generate: NTSC/PAL, PALM, PALN + +The adv717x, should be able to produce PAL N. But you find nothing PAL N +specific in the registers. Seem that you have to reuse a other standard +to generate PAL N, maybe it would work if you use the PAL M settings. + +How do I get this damn thing to work +------------------------------------ + +Load zr36067.o. If it can't autodetect your card, use the card=X insmod +option with X being the card number as given in the previous section. +To have more than one card, use card=X1[,X2[,X3,[X4[..]]]] + +To automate this, add the following to your /etc/modprobe.d/zoran.conf: + +options zr36067 card=X1[,X2[,X3[,X4[..]]]] +alias char-major-81-0 zr36067 + +One thing to keep in mind is that this doesn't load zr36067.o itself yet. It +just automates loading. If you start using xawtv, the device won't load on +some systems, since you're trying to load modules as a user, which is not +allowed ("permission denied"). A quick workaround is to add 'Load "v4l"' to +XF86Config-4 when you use X by default, or to run 'v4l-conf -c <device>' in +one of your startup scripts (normally rc.local) if you don't use X. Both +make sure that the modules are loaded on startup, under the root account. + +What mainboard should I use (or why doesn't my card work) +--------------------------------------------------------- + + +<insert lousy disclaimer here>. In short: good=SiS/Intel, bad=VIA. + +Experience tells us that people with a Buz, on average, have more problems +than users with a DC10+/LML33. Also, it tells us that people owning a VIA- +based mainboard (ktXXX, MVP3) have more problems than users with a mainboard +based on a different chipset. Here's some notes from Andrew Stevens: + +Here's my experience of using LML33 and Buz on various motherboards: + +- VIA MVP3 + - Forget it. Pointless. Doesn't work. +- Intel 430FX (Pentium 200) + - LML33 perfect, Buz tolerable (3 or 4 frames dropped per movie) +- Intel 440BX (early stepping) + - LML33 tolerable. Buz starting to get annoying (6-10 frames/hour) +- Intel 440BX (late stepping) + - Buz tolerable, LML3 almost perfect (occasional single frame drops) +- SiS735 + - LML33 perfect, Buz tolerable. +- VIA KT133(*) + - LML33 starting to get annoying, Buz poor enough that I have up. + +- Both 440BX boards were dual CPU versions. + +Bernhard Praschinger later added: + +- AMD 751 + - Buz perfect-tolerable +- AMD 760 + - Buz perfect-tolerable + +In general, people on the user mailinglist won't give you much of a chance +if you have a VIA-based motherboard. They may be cheap, but sometimes, you'd +rather want to spend some more money on better boards. In general, VIA +mainboard's IDE/PCI performance will also suck badly compared to others. +You'll noticed the DC10+/DC30+ aren't mentioned anywhere in the overview. +Basically, you can assume that if the Buz works, the LML33 will work too. If +the LML33 works, the DC10+/DC30+ will work too. They're most tolerant to +different mainboard chipsets from all of the supported cards. + +If you experience timeouts during capture, buy a better mainboard or lower +the quality/buffersize during capture (see 'Concerning buffer sizes, quality, +output size etc.'). If it hangs, there's little we can do as of now. Check +your IRQs and make sure the card has its own interrupts. + +Programming interface +--------------------- + +This driver conforms to video4linux2. Support for V4L1 and for the custom +zoran ioctls has been removed in kernel 2.6.38. + +For programming example, please, look at lavrec.c and lavplay.c code in +the MJPEG-tools (http://mjpeg.sf.net/). + +Additional notes for software developers: + + The driver returns maxwidth and maxheight parameters according to + the current TV standard (norm). Therefore, the software which + communicates with the driver and "asks" for these parameters should + first set the correct norm. Well, it seems logically correct: TV + standard is "more constant" for current country than geometry + settings of a variety of TV capture cards which may work in ITU or + square pixel format. + +Applications +------------ + +Applications known to work with this driver: + +TV viewing: + +* xawtv +* kwintv +* probably any TV application that supports video4linux or video4linux2. + +MJPEG capture/playback: + +* mjpegtools/lavtools (or Linux Video Studio) +* gstreamer +* mplayer + +General raw capture: + +* xawtv +* gstreamer +* probably any application that supports video4linux or video4linux2 + +Video editing: + +* Cinelerra +* MainActor +* mjpegtools (or Linux Video Studio) + + +Concerning buffer sizes, quality, output size etc. +-------------------------------------------------- + + +The zr36060 can do 1:2 JPEG compression. This is really the theoretical +maximum that the chipset can reach. The driver can, however, limit compression +to a maximum (size) of 1:4. The reason for this is that some cards (e.g. Buz) +can't handle 1:2 compression without stopping capture after only a few minutes. +With 1:4, it'll mostly work. If you have a Buz, use 'low_bitrate=1' to go into +1:4 max. compression mode. + +100% JPEG quality is thus 1:2 compression in practice. So for a full PAL frame +(size 720x576). The JPEG fields are stored in YUY2 format, so the size of the +fields are 720x288x16/2 bits/field (2 fields/frame) = 207360 bytes/field x 2 = +414720 bytes/frame (add some more bytes for headers and DHT (huffman)/DQT +(quantization) tables, and you'll get to something like 512kB per frame for +1:2 compression. For 1:4 compression, you'd have frames of half this size. + +Some additional explanation by Martin Samuelsson, which also explains the +importance of buffer sizes: +-- +> Hmm, I do not think it is really that way. With the current (downloaded +> at 18:00 Monday) driver I get that output sizes for 10 sec: +> -q 50 -b 128 : 24.283.332 Bytes +> -q 50 -b 256 : 48.442.368 +> -q 25 -b 128 : 24.655.992 +> -q 25 -b 256 : 25.859.820 + +I woke up, and can't go to sleep again. I'll kill some time explaining why +this doesn't look strange to me. + +Let's do some math using a width of 704 pixels. I'm not sure whether the Buz +actually use that number or not, but that's not too important right now. + +704x288 pixels, one field, is 202752 pixels. Divided by 64 pixels per block; +3168 blocks per field. Each pixel consist of two bytes; 128 bytes per block; +1024 bits per block. 100% in the new driver mean 1:2 compression; the maximum +output becomes 512 bits per block. Actually 510, but 512 is simpler to use +for calculations. + +Let's say that we specify d1q50. We thus want 256 bits per block; times 3168 +becomes 811008 bits; 101376 bytes per field. We're talking raw bits and bytes +here, so we don't need to do any fancy corrections for bits-per-pixel or such +things. 101376 bytes per field. + +d1 video contains two fields per frame. Those sum up to 202752 bytes per +frame, and one of those frames goes into each buffer. + +But wait a second! -b128 gives 128kB buffers! It's not possible to cram +202752 bytes of JPEG data into 128kB! + +This is what the driver notice and automatically compensate for in your +examples. Let's do some math using this information: + +128kB is 131072 bytes. In this buffer, we want to store two fields, which +leaves 65536 bytes for each field. Using 3168 blocks per field, we get +20.68686868... available bytes per block; 165 bits. We can't allow the +request for 256 bits per block when there's only 165 bits available! The -q50 +option is silently overridden, and the -b128 option takes precedence, leaving +us with the equivalence of -q32. + +This gives us a data rate of 165 bits per block, which, times 3168, sums up +to 65340 bytes per field, out of the allowed 65536. The current driver has +another level of rate limiting; it won't accept -q values that fill more than +6/8 of the specified buffers. (I'm not sure why. "Playing it safe" seem to be +a safe bet. Personally, I think I would have lowered requested-bits-per-block +by one, or something like that.) We can't use 165 bits per block, but have to +lower it again, to 6/8 of the available buffer space: We end up with 124 bits +per block, the equivalence of -q24. With 128kB buffers, you can't use greater +than -q24 at -d1. (And PAL, and 704 pixels width...) + +The third example is limited to -q24 through the same process. The second +example, using very similar calculations, is limited to -q48. The only +example that actually grab at the specified -q value is the last one, which +is clearly visible, looking at the file size. +-- + +Conclusion: the quality of the resulting movie depends on buffer size, quality, +whether or not you use 'low_bitrate=1' as insmod option for the zr36060.c +module to do 1:4 instead of 1:2 compression, etc. + +If you experience timeouts, lowering the quality/buffersize or using +'low_bitrate=1 as insmod option for zr36060.o might actually help, as is +proven by the Buz. + +It hangs/crashes/fails/whatevers! Help! +--------------------------------------- + +Make sure that the card has its own interrupts (see /proc/interrupts), check +the output of dmesg at high verbosity (load zr36067.o with debug=2, +load all other modules with debug=1). Check that your mainboard is favorable +(see question 2) and if not, test the card in another computer. Also see the +notes given in question 3 and try lowering quality/buffersize/capturesize +if recording fails after a period of time. + +If all this doesn't help, give a clear description of the problem including +detailed hardware information (memory+brand, mainboard+chipset+brand, which +MJPEG card, processor, other PCI cards that might be of interest), give the +system PnP information (/proc/interrupts, /proc/dma, /proc/devices), and give +the kernel version, driver version, glibc version, gcc version and any other +information that might possibly be of interest. Also provide the dmesg output +at high verbosity. See 'Contacting' on how to contact the developers. + +Maintainers/Contacting +---------------------- + +Previous maintainers/developers of this driver are +- Laurent Pinchart <laurent.pinchart@skynet.be> +- Ronald Bultje rbultje@ronald.bitfreak.net +- Serguei Miridonov <mirsev@cicese.mx> +- Wolfgang Scherr <scherr@net4you.net> +- Dave Perks <dperks@ibm.net> +- Rainer Johanni <Rainer@Johanni.de> + +Driver's License +---------------- + + This driver is distributed under the terms of the General Public License. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +See http://www.gnu.org/ for more information. diff --git a/Documentation/driver-api/media/dtv-frontend.rst b/Documentation/driver-api/media/dtv-frontend.rst index b362109bb131..ea43cdb5b0e4 100644 --- a/Documentation/driver-api/media/dtv-frontend.rst +++ b/Documentation/driver-api/media/dtv-frontend.rst @@ -125,7 +125,7 @@ responsible for tuning the device. It supports multiple algorithms to detect a channel, as defined at enum :c:func:`dvbfe_algo`. The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver -doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to +doesn't fill its field at struct dvb_frontend_ops, it will default to ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning, e. g. it will try first to use the specified center frequency ``f``, then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|, @@ -140,7 +140,7 @@ define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``. a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to define its own hardware-assisted algorithm. Very few hardware need to use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other - function callbacks at struct :c:type:`dvb_frontend_ops`. + function callbacks at struct dvb_frontend_ops. Attaching frontend driver to the bridge driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -244,7 +244,7 @@ Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) Having it available after inner FEC is more common. Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors after + - Those counters measure the number of bits and bit errors after the forward error correction (FEC) on the inner coding block (after Viterbi, LDPC or other inner code). @@ -253,7 +253,7 @@ Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POS see :c:type:`fe_status`). Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`) - - Those counters measure the number of bits and bit errors errors before + - Those counters measure the number of bits and bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). @@ -263,7 +263,7 @@ Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-T after ``FE_HAS_VITERBI``, see :c:type:`fe_status`). Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`) - - Those counters measure the number of blocks and block errors errors after + - Those counters measure the number of blocks and block errors after the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index 328350924853..c140692454b1 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -34,6 +34,7 @@ Please see: mc-core cec-core csi2 + camera-sensor drivers/index diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst index 05bba0b61748..57b5bbba944e 100644 --- a/Documentation/driver-api/media/mc-core.rst +++ b/Documentation/driver-api/media/mc-core.rst @@ -36,7 +36,7 @@ pad to a sink pad. Media device ^^^^^^^^^^^^ -A media device is represented by a struct :c:type:`media_device` +A media device is represented by a struct media_device instance, defined in ``include/media/media-device.h``. Allocation of the structure is handled by the media device driver, usually by embedding the :c:type:`media_device` instance in a larger driver-specific @@ -49,7 +49,7 @@ and unregistered by calling :c:func:`media_device_unregister()`. Entities ^^^^^^^^ -Entities are represented by a struct :c:type:`media_entity` +Entities are represented by a struct media_entity instance, defined in ``include/media/media-entity.h``. The structure is usually embedded into a higher-level structure, such as :c:type:`v4l2_subdev` or :c:type:`video_device` @@ -67,10 +67,10 @@ Interfaces ^^^^^^^^^^ Interfaces are represented by a -struct :c:type:`media_interface` instance, defined in +struct media_interface instance, defined in ``include/media/media-entity.h``. Currently, only one type of interface is defined: a device node. Such interfaces are represented by a -struct :c:type:`media_intf_devnode`. +struct media_intf_devnode. Drivers initialize and create device node interfaces by calling :c:func:`media_devnode_create()` @@ -79,7 +79,7 @@ and remove them by calling: Pads ^^^^ -Pads are represented by a struct :c:type:`media_pad` instance, +Pads are represented by a struct media_pad instance, defined in ``include/media/media-entity.h``. Each entity stores its pads in a pads array managed by the entity driver. Drivers usually embed the array in a driver-specific structure. @@ -87,8 +87,8 @@ a driver-specific structure. Pads are identified by their entity and their 0-based index in the pads array. -Both information are stored in the struct :c:type:`media_pad`, -making the struct :c:type:`media_pad` pointer the canonical way +Both information are stored in the struct media_pad, +making the struct media_pad pointer the canonical way to store and pass link references. Pads have flags that describe the pad capabilities and state. @@ -104,7 +104,7 @@ Pads have flags that describe the pad capabilities and state. Links ^^^^^ -Links are represented by a struct :c:type:`media_link` instance, +Links are represented by a struct media_link instance, defined in ``include/media/media-entity.h``. There are two types of links: **1. pad to pad links**: @@ -187,7 +187,7 @@ Use count and power handling Due to the wide differences between drivers regarding power management needs, the media controller does not implement power management. However, -the struct :c:type:`media_entity` includes a ``use_count`` +the struct media_entity includes a ``use_count`` field that media drivers can use to track the number of users of every entity for power management needs. @@ -213,11 +213,11 @@ prevent link states from being modified during streaming by calling The function will mark all entities connected to the given entity through enabled links, either directly or indirectly, as streaming. -The struct :c:type:`media_pipeline` instance pointed to by +The struct media_pipeline instance pointed to by the pipe argument will be stored in every entity in the pipeline. -Drivers should embed the struct :c:type:`media_pipeline` +Drivers should embed the struct media_pipeline in higher-level pipeline structures and can then access the -pipeline through the struct :c:type:`media_entity` +pipeline through the struct media_entity pipe field. Calls to :c:func:`media_pipeline_start()` can be nested. diff --git a/Documentation/driver-api/media/v4l2-controls.rst b/Documentation/driver-api/media/v4l2-controls.rst index 5129019afb49..b2e91804829b 100644 --- a/Documentation/driver-api/media/v4l2-controls.rst +++ b/Documentation/driver-api/media/v4l2-controls.rst @@ -27,7 +27,7 @@ V4L2 specification with respect to controls in a central place. And to make life as easy as possible for the driver developer. Note that the control framework relies on the presence of a struct -:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +:c:type:`v4l2_device` for V4L2 drivers and struct v4l2_subdev for sub-device drivers. @@ -335,7 +335,7 @@ current and new values: union v4l2_ctrl_ptr p_new; union v4l2_ctrl_ptr p_cur; -If the control has a simple s32 type type, then: +If the control has a simple s32 type, then: .. code-block:: c @@ -349,7 +349,7 @@ Within the control ops you can freely use these. The val and cur.val speak for themselves. The p_char pointers point to character buffers of length ctrl->maximum + 1, and are always 0-terminated. -Unless the control is marked volatile the p_cur field points to the the +Unless the control is marked volatile the p_cur field points to the current cached control value. When you create a new control this value is made identical to the default value. After calling v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally a good idea to call this diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst index 63c064837c00..99e3b5fa7444 100644 --- a/Documentation/driver-api/media/v4l2-dev.rst +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -67,7 +67,7 @@ You should also set these fields of :c:type:`video_device`: file operation is called this lock will be taken by the core and released afterwards. See the next section for more details. -- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue` +- :c:type:`video_device`->queue: a pointer to the struct vb2_queue associated with this device node. If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``, @@ -81,7 +81,7 @@ You should also set these fields of :c:type:`video_device`: - :c:type:`video_device`->prio: keeps track of the priorities. Used to implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. - If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state` + If left to ``NULL``, then it will use the struct v4l2_prio_state in :c:type:`v4l2_device`. If you want to have a separate priority state per (group of) device node(s), then you can point it to your own struct :c:type:`v4l2_prio_state`. @@ -95,7 +95,7 @@ You should also set these fields of :c:type:`video_device`: but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI devices at the same time it is setup without a parent device. But when the - struct :c:type:`video_device` is initialized you **do** know which parent + struct video_device is initialized you **do** know which parent PCI device to use and so you set ``dev_device`` to the correct PCI device. If you use :c:type:`v4l2_ioctl_ops`, then you should set @@ -138,7 +138,7 @@ ioctls and locking ------------------ The V4L core provides optional locking services. The main service is the -lock field in struct :c:type:`video_device`, which is a pointer to a mutex. +lock field in struct video_device, which is a pointer to a mutex. If you set this pointer, then that will be used by unlocked_ioctl to serialize all ioctls. @@ -212,7 +212,7 @@ types exist: ========================== ==================== ============================== The last argument gives you a certain amount of control over the device -device node number used (i.e. the X in ``videoX``). Normally you will pass -1 +node number used (i.e. the X in ``videoX``). Normally you will pass -1 to let the v4l2 framework pick the first free number. But sometimes users want to select a specific node number. It is common that drivers allow the user to select a specific device node number through a driver module diff --git a/Documentation/driver-api/media/v4l2-device.rst b/Documentation/driver-api/media/v4l2-device.rst index 5e25bf182c18..7bd9c45f551b 100644 --- a/Documentation/driver-api/media/v4l2-device.rst +++ b/Documentation/driver-api/media/v4l2-device.rst @@ -3,7 +3,7 @@ V4L2 device instance -------------------- -Each device instance is represented by a struct :c:type:`v4l2_device`. +Each device instance is represented by a struct v4l2_device. Very simple devices can just allocate this struct, but most of the time you would embed this struct inside a larger struct. @@ -18,9 +18,9 @@ dev->driver_data field is ``NULL``, it will be linked to Drivers that want integration with the media device framework need to set dev->driver_data manually to point to the driver-specific device structure -that embed the struct :c:type:`v4l2_device` instance. This is achieved by a +that embed the struct v4l2_device instance. This is achieved by a ``dev_set_drvdata()`` call before registering the V4L2 device instance. -They must also set the struct :c:type:`v4l2_device` mdev field to point to a +They must also set the struct v4l2_device mdev field to point to a properly initialized and registered :c:type:`media_device` instance. If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a diff --git a/Documentation/driver-api/media/v4l2-event.rst b/Documentation/driver-api/media/v4l2-event.rst index a4b7ae2b94d8..5b8254eba7da 100644 --- a/Documentation/driver-api/media/v4l2-event.rst +++ b/Documentation/driver-api/media/v4l2-event.rst @@ -44,18 +44,18 @@ such objects. So to summarize: -- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, +- struct v4l2_fh has two lists: one of the ``subscribed`` events, and one of the ``available`` events. -- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised +- struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of that particular type. -- If struct :c:type:`v4l2_subscribed_event` is associated with a specific +- If struct v4l2_subscribed_event is associated with a specific object, then that object will have an internal list of - struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an + struct v4l2_subscribed_event so it knows who subscribed an event to that object. -Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has +Furthermore, the internal struct v4l2_subscribed_event has ``merge()`` and ``replace()`` callbacks which drivers can set. These callbacks are called when a new event is raised and there is no more room. diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst index 4c62b19af744..3eeaa8da0c9e 100644 --- a/Documentation/driver-api/media/v4l2-fh.rst +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -3,11 +3,11 @@ V4L2 File handlers ------------------ -struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific +struct v4l2_fh provides a way to easily keep file handle specific data that is used by the V4L2 framework. .. attention:: - New drivers must use struct :c:type:`v4l2_fh` + New drivers must use struct v4l2_fh since it is also used to implement priority handling (:ref:`VIDIOC_G_PRIORITY`). @@ -16,11 +16,11 @@ whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. This bit is set whenever :c:func:`v4l2_fh_init` is called. -struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle +struct v4l2_fh is allocated as a part of the driver's own file handle structure and ``file->private_data`` is set to it in the driver's ``open()`` function by the driver. -In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger +In many cases the struct v4l2_fh will be embedded in a larger structure. In that case you should call: #) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()`` @@ -102,18 +102,18 @@ Below is a short description of the :c:type:`v4l2_fh` functions used: memory can be freed. -If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: +If struct v4l2_fh is not embedded, then you can use these helper functions: :c:func:`v4l2_fh_open <v4l2_fh_open>` (struct file \*filp) -- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to - the struct :c:type:`video_device` associated with the file struct. +- This allocates a struct v4l2_fh, initializes it and adds it to + the struct video_device associated with the file struct. :c:func:`v4l2_fh_release <v4l2_fh_release>` (struct file \*filp) -- This deletes it from the struct :c:type:`video_device` associated with the +- This deletes it from the struct video_device associated with the file struct, uninitialised the :c:type:`v4l2_fh` and frees it. These two functions can be plugged into the v4l2_file_operation's ``open()`` diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index bc7e1fc40a9d..bb5b1a7cdfd9 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -34,7 +34,7 @@ provides host private data for that purpose that can be accessed with From the bridge driver perspective, you load the sub-device module and somehow obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call ``i2c_get_clientdata()``. For other buses something similar needs to be done. -Helper functions exists for sub-devices on an I2C bus that do most of this +Helper functions exist for sub-devices on an I2C bus that do most of this tricky work for you. Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers @@ -110,7 +110,7 @@ pads: err = media_entity_pads_init(&sd->entity, npads, pads); The pads array must have been previously initialized. There is no need to -manually set the struct :c:type:`media_entity` function and name fields, but the +manually set the struct media_entity function and name fields, but the revision field must be initialized if needed. A reference to the entity will be automatically acquired/released when the @@ -138,6 +138,9 @@ ensures that width, height and the media bus pixel code are equal on both source and sink of the link. Subdev drivers are also free to use this function to perform the checks mentioned above in addition to their own checks. +Subdev registration +~~~~~~~~~~~~~~~~~~~ + There are currently two ways to register subdevices with the V4L2 core. The first (traditional) possibility is to have subdevices registered by bridge drivers. This can be done when the bridge driver has the complete information @@ -157,7 +160,7 @@ below. Using one or the other registration method only affects the probing process, the run-time bridge-subdevice interaction is in both cases the same. -In the synchronous case a device (bridge) driver needs to register the +In the **synchronous** case a device (bridge) driver needs to register the :c:type:`v4l2_subdev` with the v4l2_device: :c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` @@ -179,7 +182,51 @@ You can unregister a sub-device using: Afterwards the subdev module can be unloaded and :c:type:`sd <v4l2_subdev>`->dev == ``NULL``. -You can call an ops function either directly: +In the **asynchronous** case subdevice probing can be invoked independently of +the bridge driver availability. The subdevice driver then has to verify whether +all the requirements for a successful probing are satisfied. This can include a +check for a master clock availability. If any of the conditions aren't satisfied +the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing +attempts. Once all conditions are met the subdevice shall be registered using +the :c:func:`v4l2_async_register_subdev` function. Unregistration is +performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices +registered this way are stored in a global list of subdevices, ready to be +picked up by bridge drivers. + +Bridge drivers in turn have to register a notifier object. This is +performed using the :c:func:`v4l2_async_notifier_register` call. To +unregister the notifier the driver has to call +:c:func:`v4l2_async_notifier_unregister`. The former of the two functions +takes two arguments: a pointer to struct :c:type:`v4l2_device` and a +pointer to struct :c:type:`v4l2_async_notifier`. + +Before registering the notifier, bridge drivers must do two things: +first, the notifier must be initialized using the +:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then +begin to form a list of subdevice descriptors that the bridge device +needs for its operation. Subdevice descriptors are added to the notifier +using the :c:func:`v4l2_async_notifier_add_subdev` call. This function +takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`, +and a pointer to the subdevice descripter, which is of type struct +:c:type:`v4l2_async_subdev`. + +The V4L2 core will then use these descriptors to match asynchronously +registered subdevices to them. If a match is detected the ``.bound()`` +notifier callback is called. After all subdevices have been located the +.complete() callback is called. When a subdevice is removed from the +system the .unbind() method is called. All three callbacks are optional. + +Calling subdev operations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and +does not contain any knowledge about the underlying hardware. So a driver might +contain several subdevs that use an I2C bus, but also a subdev that is +controlled through GPIO pins. This distinction is only relevant when setting +up the device, but once the subdev is registered it is completely transparent. + +Once te subdev has been registered you can call an ops function either +directly: .. code-block:: c @@ -191,7 +238,7 @@ but it is better and easier to use this macro: err = v4l2_subdev_call(sd, core, g_std, &norm); -The macro will to the right ``NULL`` pointer checks and returns ``-ENODEV`` +The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV`` if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops. @@ -232,46 +279,6 @@ it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not. Otherwise the result of the ``notify()`` call is returned. -The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and -does not contain any knowledge about the underlying hardware. So a driver might -contain several subdevs that use an I2C bus, but also a subdev that is -controlled through GPIO pins. This distinction is only relevant when setting -up the device, but once the subdev is registered it is completely transparent. - -In the asynchronous case subdevice probing can be invoked independently of the -bridge driver availability. The subdevice driver then has to verify whether all -the requirements for a successful probing are satisfied. This can include a -check for a master clock availability. If any of the conditions aren't satisfied -the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing -attempts. Once all conditions are met the subdevice shall be registered using -the :c:func:`v4l2_async_register_subdev` function. Unregistration is -performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices -registered this way are stored in a global list of subdevices, ready to be -picked up by bridge drivers. - -Bridge drivers in turn have to register a notifier object. This is -performed using the :c:func:`v4l2_async_notifier_register` call. To -unregister the notifier the driver has to call -:c:func:`v4l2_async_notifier_unregister`. The former of the two functions -takes two arguments: a pointer to struct :c:type:`v4l2_device` and a -pointer to struct :c:type:`v4l2_async_notifier`. - -Before registering the notifier, bridge drivers must do two things: -first, the notifier must be initialized using the -:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then -begin to form a list of subdevice descriptors that the bridge device -needs for its operation. Subdevice descriptors are added to the notifier -using the :c:func:`v4l2_async_notifier_add_subdev` call. This function -takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`, -and a pointer to the subdevice descripter, which is of type struct -:c:type:`v4l2_async_subdev`. - -The V4L2 core will then use these descriptors to match asynchronously -registered subdevices to them. If a match is detected the ``.bound()`` -notifier callback is called. After all subdevices have been located the -.complete() callback is called. When a subdevice is removed from the -system the .unbind() method is called. All three callbacks are optional. - V4L2 sub-device userspace API ----------------------------- @@ -488,5 +495,3 @@ V4L2 sub-device functions and data structures --------------------------------------------- .. kernel-doc:: include/media/v4l2-subdev.h - -.. kernel-doc:: include/media/v4l2-async.h |