Documentation/misc-devices/apds990x.txt

   1 Kernel driver apds990x
   2 ======================
   3
   4 Supported chips:
   5 Avago APDS990X
   6
   7 Data sheet:
   8 Not freely available
   9
  10 Author:
  11 Samu Onkalo <samu.p.onkalo@nokia.com>
  12
  13 Description
  14 -----------
  15
  16 APDS990x is a combined ambient light and proximity sensor. ALS and proximity
  17 functionality are highly connected. ALS measurement path must be running
  18 while the proximity functionality is enabled.
  19
  20 ALS produces raw measurement values for two channels: Clear channel
  21 (infrared + visible light) and IR only. However, threshold comparisons happen
  22 using clear channel only. Lux value and the threshold level on the HW
  23 might vary quite much depending the spectrum of the light source.
  24
  25 Driver makes necessary conversions to both directions so that user handles
  26 only lux values. Lux value is calculated using information from the both
  27 channels. HW threshold level is calculated from the given lux value to match
  28 with current type of the lightning. Sometimes inaccuracy of the estimations
  29 lead to false interrupt, but that doesn't harm.
  30
  31 ALS contains 4 different gain steps. Driver automatically
  32 selects suitable gain step. After each measurement, reliability of the results
  33 is estimated and new measurement is trigged if necessary.
  34
  35 Platform data can provide tuned values to the conversion formulas if
  36 values are known. Otherwise plain sensor default values are used.
  37
  38 Proximity side is little bit simpler. There is no need for complex conversions.
  39 It produces directly usable values.
  40
  41 Driver controls chip operational state using pm_runtime framework.
  42 Voltage regulators are controlled based on chip operational state.
  43
  44 SYSFS
  45 -----
  46
  47
  48 chip_id
  49         RO - shows detected chip type and version
  50
  51 power_state
  52         RW - enable / disable chip. Uses counting logic
  53              1 enables the chip
  54              0 disables the chip
  55 lux0_input
  56         RO - measured lux value
  57              sysfs_notify called when threshold interrupt occurs
  58
  59 lux0_sensor_range
  60         RO - lux0_input max value. Actually never reaches since sensor tends
  61              to saturate much before that. Real max value varies depending
  62              on the light spectrum etc.
  63
  64 lux0_rate
  65         RW - measurement rate in Hz
  66
  67 lux0_rate_avail
  68         RO - supported measurement rates
  69
  70 lux0_calibscale
  71         RW - calibration value. Set to neutral value by default.
  72              Output results are multiplied with calibscale / calibscale_default
  73              value.
  74
  75 lux0_calibscale_default
  76         RO - neutral calibration value
  77
  78 lux0_thresh_above_value
  79         RW - HI level threshold value. All results above the value
  80              trigs an interrupt. 65535 (i.e. sensor_range) disables the above
  81              interrupt.
  82
  83 lux0_thresh_below_value
  84         RW - LO level threshold value. All results below the value
  85              trigs an interrupt. 0 disables the below interrupt.
  86
  87 prox0_raw
  88         RO - measured proximity value
  89              sysfs_notify called when threshold interrupt occurs
  90
  91 prox0_sensor_range
  92         RO - prox0_raw max value (1023)
  93
  94 prox0_raw_en
  95         RW - enable / disable proximity - uses counting logic
  96              1 enables the proximity
  97              0 disables the proximity
  98
  99 prox0_reporting_mode
 100         RW - trigger / periodic. In "trigger" mode the driver tells two possible
 101              values: 0 or prox0_sensor_range value. 0 means no proximity,
 102              1023 means proximity. This causes minimal number of interrupts.
 103              In "periodic" mode the driver reports all values above
 104              prox0_thresh_above. This causes more interrupts, but it can give
 105              _rough_ estimate about the distance.
 106
 107 prox0_reporting_mode_avail
 108         RO - accepted values to prox0_reporting_mode (trigger, periodic)
 109
 110 prox0_thresh_above_value
 111         RW - threshold level which trigs proximity events.