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