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