Re: [PATCHv3 5/5] Documentation: Short descriptions for bh1770glc and apds990x drivers

Jonathan Cameron
2010-10-11T13:50:33Z

On 10/11/10 12:06, Samu Onkalo wrote:
> Add short documentation for two ALS / proximity chip drivers.

Couple of nitpicks. All in category of things to fix if you are
respinning the patch for some other reason.
>
> Signed-off-by: Samu Onkalo <samu.p.onkalo-xNZwKgViW5gAvxtiuMwx3w@public.gmane.org>
Acked-by: Jonathan Cameron <jic23-KWPb1pKIrIJaa/9Udqfwiw@public.gmane.org>
> ---
> Documentation/misc-devices/apds990x.txt | 113 ++++++++++++++++++++++++++++
> Documentation/misc-devices/bh1770glc.txt | 118 ++++++++++++++++++++++++++++++
> 2 files changed, 231 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/misc-devices/apds990x.txt
> create mode 100644 Documentation/misc-devices/bh1770glc.txt
>
> diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.txt
> new file mode 100644
> index 0000000..36b9e40
> --- /dev/null
> +++ b/Documentation/misc-devices/apds990x.txt
> @@ -0,0 +1,113 @@
> +Kernel driver apds990x
> +======================
> +
> +Supported chips:
> +Avago APDS990X
> +
> +Data sheet:
> +Not freely available
> +
> +Author:
> +Samu Onkalo <samu.p.onkalo-xNZwKgViW5gAvxtiuMwx3w@public.gmane.org>
> +
> +Description
> +-----------
> +
> +APDS990x is a combined ambient light and proximity sensor. ALS and proximity
> +functionality are highly connected. ALS measurement path must be running
> +while the proximity functionality is enabled.
> +
> +ALS produces raw measurement values for two channels: Clear channel
> +(infrared + visible light) and IR only. However, threshold comparisons happen
> +using clear channel only. LUX value and the threshold level on the HW
> +might vary quite much depending the spectrum of the light source.
> +
> +Driver makes necessary conversions to both directions so that user handles
> +only LUX values. LUX value is calculated using information from the both
> +channels. HW threshold level is calculated from the given LUX value to match
> +with current type of the lightning. Sometimes inaccuracy of the estimations
> +lead to false interrupt, but that doesn't harm.
> +
> +ALS contains 4 different gain steps. Driver automatically
> +selects suitable gain step. After each measurement, reliability of the results
> +is estimated and new measurement is trigged if necessary.
> +
> +Platform data can provide tuned values to the conversion formulas if
> +values are known. Otherwise plain sensor default values are used.
> +
> +Proximity side is little bit simpler. There is no need for complex conversions.
> +It produces directly usable values.
> +
> +Driver controls chip operational state using pm_runtime framework.
> +Voltage regulators are controlled based on chip operational state.
> +
> +SYSFS
> +-----
> +
> +
> +chip_id
> + RO - shows detected chip type and version
> +
> +power_state
> + RW - enable / disable chip. Uses counting logic
> + 1 enables the chip
> + 0 disables the chip
> +lux0_input
> + RO - measured LUX value
> + sysfs_notify called when threshold interrupt occurs
> +
> +lux0_sensor_range
> + RO - lux0_input max value. Actually never reaches since sensor tends
> + to saturate much before that. Real max value varies depending
> + on the light spectrum etc.
> +
bonus blank line?
> +
> +lux0_rate
> + RW - measurement rate in Hz
> +
> +lux0_rate_avail
> + RO - supported measurement rates
> +
> +lux0_calibscale
> + RW - calibration value. Set to neutral value by default.
> + Output results are multiplied with calibscale / calibscale_default
> + value.
> +
> +lux0_calibscale_default
> + RO - neutral calibration value
> +
> +lux0_thresh_above_value
> + RW - HI level threshold value. All results above the value
> + trigs an interrupt. 65535 (i.e. sensor_range) disables the above
> + interrupt.
> +
> +lux0_thresh_below_value
> + RW - LO level threshold value. All results below the value
> + trigs an interrupt. 0 disables the below interrupt.
> +
> +prox0_raw
> + RO - measured proximity value
> + sysfs_notify called when threshold interrupt occurs
> +
> +prox0_sensor_range
> + RO - prox0_raw max value (1023)
> +
> +prox0_raw_en
> + RW - enable / disable proximity - uses counting logic
> + 1 enables the proximity
> + 0 disables the proximity
> +
> +prox0_reporting_mode
> + RW - trigger / periodic. In "trigger" mode the driver tells two possible
> + values: 0 or prox0_sensor_range value. 0 means no proximity,
> + 1023 means proximity. This causes minimal number of interrupts.
> + In "periodic" mode the driver reports all values above
> + prox0_thresh_above. This causes more interrupts, but it can give
> + _rough_ estimate about the distance.
> +
> +prox0_reporting_mode_avail
> + RO - accepted values to prox0_reporting_mode (trigger, periodic)
> +
> +prox0_thresh_above_value
> + RW - threshold level which trigs proximity events.
> +
> diff --git a/Documentation/misc-devices/bh1770glc.txt b/Documentation/misc-devices/bh1770glc.txt
> new file mode 100644
> index 0000000..e98e756
> --- /dev/null
> +++ b/Documentation/misc-devices/bh1770glc.txt
> @@ -0,0 +1,118 @@
> +Kernel driver bh1770glc
> +=======================
> +
> +Supported chips:
> +ROHM BH1770GLC
> +OSRAM SFH7770
> +
> +Data sheet:
> +Not freely available
> +
> +Author:
> +Samu Onkalo <samu.p.onkalo-xNZwKgViW5gAvxtiuMwx3w@public.gmane.org>
> +
> +Description
> +-----------
> +BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
> +ALS and proximity parts operates on their own, but they shares common I2C
> +interface and interrupt logic. In principle they can run on their own,
> +but ALS side results are used to estimate reliability of the proximity sensor.
> +
> +ALS produces 16 bit LUX values. The chip contains interrupt logic to produce
> +low and high threshold interrupts.
> +
> +Proximity part contains IR-led driver up to 3 IR leds. The chip measures
> +amount of reflected IR light and produces proximity result. Resolution is
> +8 bit. Driver supports only one channel. Driver uses ALS results to estimate
> +reliability of the proximity results. Thus ALS is always running while
> +proximity detection is needed.
> +
> +Driver uses threshold interrupts to avoid need for polling the values.
> +Proximity low interrupt doesn't exists in the chip. This is simulated
> +by using a delayed work. As long as there is proximity threshold above
> +interrupts the delayed work is pushed forward. So, when proximity level goes
> +below the threshold value, there is no interrupt and the delayed work will
> +finally run. This is handled as no proximity indication.
> +
> +Chip state is controlled via runtime pm framework when enabled in config.
> +
> +Calibscale factor is used to hide differences between the chips. By default
> +value set to neutral state meaning factor of 1.00. To get proper values,
> +calibrated source of light is needed as a reference. Calibscale factor is set
> +so that measurement produces about the expected lux value.
I'm not sure why LUX is in capitals everywhere else, but if there is a reason
then I think this one should be as well?
> +
> +SYSFS
> +-----
> +
> +chip_id
> + RO - shows detected chip type and version
> +
> +power_state
> + RW - enable / disable chip. Uses counting logic
> + 1 enables the chip
> + 0 disables the chip
> +
> +lux0_input
> + RO - measured LUX value
> + sysfs_notify called when threshold interrupt occurs
> +
> +lux0_sensor_range
> + RO - lux0_input max value
> +
> +lux0_rate
> + RW - measurement rate in Hz
> +
> +lux0_rate_avail
> + RO - supported measurement rates
> +
> +lux0_thresh_above_value
> + RW - HI level threshold value. All results above the value
> + trigs an interrupt. 65535 (i.e. sensor_range) disables the above
> + interrupt.
> +
> +lux0_thresh_below_value
> + RW - LO level threshold value. All results below the value
> + trigs an interrupt. 0 disables the below interrupt.
> +
> +lux0_calibscale
> + RW - calibration value. Set to neutral value by default.
> + Output results are multiplied with calibscale / calibscale_default
> + value.
> +
> +lux0_calibscale_default
> + RO - neutral calibration value
> +
> +prox0_raw
> + RO - measured proximity value
> + sysfs_notify called when threshold interrupt occurs
> +
> +prox0_sensor_range
> + RO - prox0_raw max value
> +
> +prox0_raw_en
> + RW - enable / disable proximity - uses counting logic
> + 1 enables the proximity
> + 0 disables the proximity
> +
> +prox0_thresh_above_count
> + RW - number of proximity interrupts needed before triggering the event
> +
> +prox0_rate_above
> + RW - Measurement rate (in Hz) when the level is above threshold
> + i.e. when proximity on has been reported.
> +
> +prox0_rate_below
> + RW - Measurement rate (in Hz) when the level is below threshold
> + i.e. when proximity off has been reported.
> +
> +prox0_rate_avail
> + RO - Supported proximity measurement rates in Hz
Nitpick, bonus white line?
> +
> +
> +prox0_thresh_above0_value
> + RW - threshold level which trigs proximity events.
> + Filtered by persistence filter (prox0_thresh_above_count)
> +
> +prox0_thresh_above1_value
> + RW - threshold level which trigs event immediately
> +