xref: /linux/Documentation/misc-devices/apds990x.rst (revision 4b4193256c8d3bc3a5397b5cd9494c2ad386317d)
1*9f70e48eSMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0
2*9f70e48eSMauro Carvalho Chehab
3*9f70e48eSMauro Carvalho Chehab======================
43f0f4a3fSSamu OnkaloKernel driver apds990x
53f0f4a3fSSamu Onkalo======================
63f0f4a3fSSamu Onkalo
73f0f4a3fSSamu OnkaloSupported chips:
83f0f4a3fSSamu OnkaloAvago APDS990X
93f0f4a3fSSamu Onkalo
103f0f4a3fSSamu OnkaloData sheet:
113f0f4a3fSSamu OnkaloNot freely available
123f0f4a3fSSamu Onkalo
133f0f4a3fSSamu OnkaloAuthor:
143f0f4a3fSSamu OnkaloSamu Onkalo <samu.p.onkalo@nokia.com>
153f0f4a3fSSamu Onkalo
163f0f4a3fSSamu OnkaloDescription
173f0f4a3fSSamu Onkalo-----------
183f0f4a3fSSamu Onkalo
193f0f4a3fSSamu OnkaloAPDS990x is a combined ambient light and proximity sensor. ALS and proximity
203f0f4a3fSSamu Onkalofunctionality are highly connected. ALS measurement path must be running
213f0f4a3fSSamu Onkalowhile the proximity functionality is enabled.
223f0f4a3fSSamu Onkalo
233f0f4a3fSSamu OnkaloALS produces raw measurement values for two channels: Clear channel
243f0f4a3fSSamu Onkalo(infrared + visible light) and IR only. However, threshold comparisons happen
253f0f4a3fSSamu Onkalousing clear channel only. Lux value and the threshold level on the HW
263f0f4a3fSSamu Onkalomight vary quite much depending the spectrum of the light source.
273f0f4a3fSSamu Onkalo
283f0f4a3fSSamu OnkaloDriver makes necessary conversions to both directions so that user handles
293f0f4a3fSSamu Onkaloonly lux values. Lux value is calculated using information from the both
303f0f4a3fSSamu Onkalochannels. HW threshold level is calculated from the given lux value to match
313f0f4a3fSSamu Onkalowith current type of the lightning. Sometimes inaccuracy of the estimations
323f0f4a3fSSamu Onkalolead to false interrupt, but that doesn't harm.
333f0f4a3fSSamu Onkalo
343f0f4a3fSSamu OnkaloALS contains 4 different gain steps. Driver automatically
353f0f4a3fSSamu Onkaloselects suitable gain step. After each measurement, reliability of the results
3696d8d5ffSMasanari Iidais estimated and new measurement is triggered if necessary.
373f0f4a3fSSamu Onkalo
383f0f4a3fSSamu OnkaloPlatform data can provide tuned values to the conversion formulas if
393f0f4a3fSSamu Onkalovalues are known. Otherwise plain sensor default values are used.
403f0f4a3fSSamu Onkalo
413f0f4a3fSSamu OnkaloProximity side is little bit simpler. There is no need for complex conversions.
423f0f4a3fSSamu OnkaloIt produces directly usable values.
433f0f4a3fSSamu Onkalo
443f0f4a3fSSamu OnkaloDriver controls chip operational state using pm_runtime framework.
453f0f4a3fSSamu OnkaloVoltage regulators are controlled based on chip operational state.
463f0f4a3fSSamu Onkalo
473f0f4a3fSSamu OnkaloSYSFS
483f0f4a3fSSamu Onkalo-----
493f0f4a3fSSamu Onkalo
503f0f4a3fSSamu Onkalo
513f0f4a3fSSamu Onkalochip_id
523f0f4a3fSSamu Onkalo	RO - shows detected chip type and version
533f0f4a3fSSamu Onkalo
543f0f4a3fSSamu Onkalopower_state
553f0f4a3fSSamu Onkalo	RW - enable / disable chip. Uses counting logic
56*9f70e48eSMauro Carvalho Chehab
573f0f4a3fSSamu Onkalo	     1 enables the chip
583f0f4a3fSSamu Onkalo	     0 disables the chip
593f0f4a3fSSamu Onkalolux0_input
603f0f4a3fSSamu Onkalo	RO - measured lux value
61*9f70e48eSMauro Carvalho Chehab
623f0f4a3fSSamu Onkalo	     sysfs_notify called when threshold interrupt occurs
633f0f4a3fSSamu Onkalo
643f0f4a3fSSamu Onkalolux0_sensor_range
65*9f70e48eSMauro Carvalho Chehab	RO - lux0_input max value.
66*9f70e48eSMauro Carvalho Chehab
67*9f70e48eSMauro Carvalho Chehab	     Actually never reaches since sensor tends
683f0f4a3fSSamu Onkalo	     to saturate much before that. Real max value varies depending
693f0f4a3fSSamu Onkalo	     on the light spectrum etc.
703f0f4a3fSSamu Onkalo
713f0f4a3fSSamu Onkalolux0_rate
723f0f4a3fSSamu Onkalo	RW - measurement rate in Hz
733f0f4a3fSSamu Onkalo
743f0f4a3fSSamu Onkalolux0_rate_avail
753f0f4a3fSSamu Onkalo	RO - supported measurement rates
763f0f4a3fSSamu Onkalo
773f0f4a3fSSamu Onkalolux0_calibscale
78*9f70e48eSMauro Carvalho Chehab	RW - calibration value.
79*9f70e48eSMauro Carvalho Chehab
80*9f70e48eSMauro Carvalho Chehab	     Set to neutral value by default.
813f0f4a3fSSamu Onkalo	     Output results are multiplied with calibscale / calibscale_default
823f0f4a3fSSamu Onkalo	     value.
833f0f4a3fSSamu Onkalo
843f0f4a3fSSamu Onkalolux0_calibscale_default
853f0f4a3fSSamu Onkalo	RO - neutral calibration value
863f0f4a3fSSamu Onkalo
873f0f4a3fSSamu Onkalolux0_thresh_above_value
88*9f70e48eSMauro Carvalho Chehab	RW - HI level threshold value.
89*9f70e48eSMauro Carvalho Chehab
90*9f70e48eSMauro Carvalho Chehab	     All results above the value
913f0f4a3fSSamu Onkalo	     trigs an interrupt. 65535 (i.e. sensor_range) disables the above
923f0f4a3fSSamu Onkalo	     interrupt.
933f0f4a3fSSamu Onkalo
943f0f4a3fSSamu Onkalolux0_thresh_below_value
95*9f70e48eSMauro Carvalho Chehab	RW - LO level threshold value.
96*9f70e48eSMauro Carvalho Chehab
97*9f70e48eSMauro Carvalho Chehab	     All results below the value
983f0f4a3fSSamu Onkalo	     trigs an interrupt. 0 disables the below interrupt.
993f0f4a3fSSamu Onkalo
1003f0f4a3fSSamu Onkaloprox0_raw
1013f0f4a3fSSamu Onkalo	RO - measured proximity value
102*9f70e48eSMauro Carvalho Chehab
1033f0f4a3fSSamu Onkalo	     sysfs_notify called when threshold interrupt occurs
1043f0f4a3fSSamu Onkalo
1053f0f4a3fSSamu Onkaloprox0_sensor_range
1063f0f4a3fSSamu Onkalo	RO - prox0_raw max value (1023)
1073f0f4a3fSSamu Onkalo
1083f0f4a3fSSamu Onkaloprox0_raw_en
1093f0f4a3fSSamu Onkalo	RW - enable / disable proximity - uses counting logic
110*9f70e48eSMauro Carvalho Chehab
111*9f70e48eSMauro Carvalho Chehab	     - 1 enables the proximity
112*9f70e48eSMauro Carvalho Chehab	     - 0 disables the proximity
1133f0f4a3fSSamu Onkalo
1143f0f4a3fSSamu Onkaloprox0_reporting_mode
115*9f70e48eSMauro Carvalho Chehab	RW - trigger / periodic.
116*9f70e48eSMauro Carvalho Chehab
117*9f70e48eSMauro Carvalho Chehab	     In "trigger" mode the driver tells two possible
1183f0f4a3fSSamu Onkalo	     values: 0 or prox0_sensor_range value. 0 means no proximity,
1193f0f4a3fSSamu Onkalo	     1023 means proximity. This causes minimal number of interrupts.
1203f0f4a3fSSamu Onkalo	     In "periodic" mode the driver reports all values above
1213f0f4a3fSSamu Onkalo	     prox0_thresh_above. This causes more interrupts, but it can give
1223f0f4a3fSSamu Onkalo	     _rough_ estimate about the distance.
1233f0f4a3fSSamu Onkalo
1243f0f4a3fSSamu Onkaloprox0_reporting_mode_avail
1253f0f4a3fSSamu Onkalo	RO - accepted values to prox0_reporting_mode (trigger, periodic)
1263f0f4a3fSSamu Onkalo
1273f0f4a3fSSamu Onkaloprox0_thresh_above_value
1283f0f4a3fSSamu Onkalo	RW - threshold level which trigs proximity events.
129