Kyle Swenson | 8d8f654 | 2021-03-15 11:02:55 -0600 | [diff] [blame] | 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 triggered 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. |