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