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@xxxxxxxxx> Acked-by: Jonathan Cameron <jic23@xxxxxxxxx> > --- > 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@xxxxxxxxx> > + > +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@xxxxxxxxx> > + > +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 > + -- To unsubscribe from this list: send the line "unsubscribe linux-i2c" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
