1*9f70e48eSMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2*9f70e48eSMauro Carvalho Chehab 3*9f70e48eSMauro Carvalho Chehab====================== 4*9f70e48eSMauro Carvalho ChehabKernel driver apds990x 5*9f70e48eSMauro Carvalho Chehab====================== 6*9f70e48eSMauro Carvalho Chehab 7*9f70e48eSMauro Carvalho ChehabSupported chips: 8*9f70e48eSMauro Carvalho ChehabAvago APDS990X 9*9f70e48eSMauro Carvalho Chehab 10*9f70e48eSMauro Carvalho ChehabData sheet: 11*9f70e48eSMauro Carvalho ChehabNot freely available 12*9f70e48eSMauro Carvalho Chehab 13*9f70e48eSMauro Carvalho ChehabAuthor: 14*9f70e48eSMauro Carvalho ChehabSamu Onkalo <samu.p.onkalo@nokia.com> 15*9f70e48eSMauro Carvalho Chehab 16*9f70e48eSMauro Carvalho ChehabDescription 17*9f70e48eSMauro Carvalho Chehab----------- 18*9f70e48eSMauro Carvalho Chehab 19*9f70e48eSMauro Carvalho ChehabAPDS990x is a combined ambient light and proximity sensor. ALS and proximity 20*9f70e48eSMauro Carvalho Chehabfunctionality are highly connected. ALS measurement path must be running 21*9f70e48eSMauro Carvalho Chehabwhile the proximity functionality is enabled. 22*9f70e48eSMauro Carvalho Chehab 23*9f70e48eSMauro Carvalho ChehabALS produces raw measurement values for two channels: Clear channel 24*9f70e48eSMauro Carvalho Chehab(infrared + visible light) and IR only. However, threshold comparisons happen 25*9f70e48eSMauro Carvalho Chehabusing clear channel only. Lux value and the threshold level on the HW 26*9f70e48eSMauro Carvalho Chehabmight vary quite much depending the spectrum of the light source. 27*9f70e48eSMauro Carvalho Chehab 28*9f70e48eSMauro Carvalho ChehabDriver makes necessary conversions to both directions so that user handles 29*9f70e48eSMauro Carvalho Chehabonly lux values. Lux value is calculated using information from the both 30*9f70e48eSMauro Carvalho Chehabchannels. HW threshold level is calculated from the given lux value to match 31*9f70e48eSMauro Carvalho Chehabwith current type of the lightning. Sometimes inaccuracy of the estimations 32*9f70e48eSMauro Carvalho Chehablead to false interrupt, but that doesn't harm. 33*9f70e48eSMauro Carvalho Chehab 34*9f70e48eSMauro Carvalho ChehabALS contains 4 different gain steps. Driver automatically 35*9f70e48eSMauro Carvalho Chehabselects suitable gain step. After each measurement, reliability of the results 36*9f70e48eSMauro Carvalho Chehabis estimated and new measurement is triggered if necessary. 37*9f70e48eSMauro Carvalho Chehab 38*9f70e48eSMauro Carvalho ChehabPlatform data can provide tuned values to the conversion formulas if 39*9f70e48eSMauro Carvalho Chehabvalues are known. Otherwise plain sensor default values are used. 40*9f70e48eSMauro Carvalho Chehab 41*9f70e48eSMauro Carvalho ChehabProximity side is little bit simpler. There is no need for complex conversions. 42*9f70e48eSMauro Carvalho ChehabIt produces directly usable values. 43*9f70e48eSMauro Carvalho Chehab 44*9f70e48eSMauro Carvalho ChehabDriver controls chip operational state using pm_runtime framework. 45*9f70e48eSMauro Carvalho ChehabVoltage regulators are controlled based on chip operational state. 46*9f70e48eSMauro Carvalho Chehab 47*9f70e48eSMauro Carvalho ChehabSYSFS 48*9f70e48eSMauro Carvalho Chehab----- 49*9f70e48eSMauro Carvalho Chehab 50*9f70e48eSMauro Carvalho Chehab 51*9f70e48eSMauro Carvalho Chehabchip_id 52*9f70e48eSMauro Carvalho Chehab RO - shows detected chip type and version 53*9f70e48eSMauro Carvalho Chehab 54*9f70e48eSMauro Carvalho Chehabpower_state 55*9f70e48eSMauro Carvalho Chehab RW - enable / disable chip. Uses counting logic 56*9f70e48eSMauro Carvalho Chehab 57*9f70e48eSMauro Carvalho Chehab 1 enables the chip 58*9f70e48eSMauro Carvalho Chehab 0 disables the chip 59*9f70e48eSMauro Carvalho Chehablux0_input 60*9f70e48eSMauro Carvalho Chehab RO - measured lux value 61*9f70e48eSMauro Carvalho Chehab 62*9f70e48eSMauro Carvalho Chehab sysfs_notify called when threshold interrupt occurs 63*9f70e48eSMauro Carvalho Chehab 64*9f70e48eSMauro Carvalho Chehablux0_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 68*9f70e48eSMauro Carvalho Chehab to saturate much before that. Real max value varies depending 69*9f70e48eSMauro Carvalho Chehab on the light spectrum etc. 70*9f70e48eSMauro Carvalho Chehab 71*9f70e48eSMauro Carvalho Chehablux0_rate 72*9f70e48eSMauro Carvalho Chehab RW - measurement rate in Hz 73*9f70e48eSMauro Carvalho Chehab 74*9f70e48eSMauro Carvalho Chehablux0_rate_avail 75*9f70e48eSMauro Carvalho Chehab RO - supported measurement rates 76*9f70e48eSMauro Carvalho Chehab 77*9f70e48eSMauro Carvalho Chehablux0_calibscale 78*9f70e48eSMauro Carvalho Chehab RW - calibration value. 79*9f70e48eSMauro Carvalho Chehab 80*9f70e48eSMauro Carvalho Chehab Set to neutral value by default. 81*9f70e48eSMauro Carvalho Chehab Output results are multiplied with calibscale / calibscale_default 82*9f70e48eSMauro Carvalho Chehab value. 83*9f70e48eSMauro Carvalho Chehab 84*9f70e48eSMauro Carvalho Chehablux0_calibscale_default 85*9f70e48eSMauro Carvalho Chehab RO - neutral calibration value 86*9f70e48eSMauro Carvalho Chehab 87*9f70e48eSMauro Carvalho Chehablux0_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 91*9f70e48eSMauro Carvalho Chehab trigs an interrupt. 65535 (i.e. sensor_range) disables the above 92*9f70e48eSMauro Carvalho Chehab interrupt. 93*9f70e48eSMauro Carvalho Chehab 94*9f70e48eSMauro Carvalho Chehablux0_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 98*9f70e48eSMauro Carvalho Chehab trigs an interrupt. 0 disables the below interrupt. 99*9f70e48eSMauro Carvalho Chehab 100*9f70e48eSMauro Carvalho Chehabprox0_raw 101*9f70e48eSMauro Carvalho Chehab RO - measured proximity value 102*9f70e48eSMauro Carvalho Chehab 103*9f70e48eSMauro Carvalho Chehab sysfs_notify called when threshold interrupt occurs 104*9f70e48eSMauro Carvalho Chehab 105*9f70e48eSMauro Carvalho Chehabprox0_sensor_range 106*9f70e48eSMauro Carvalho Chehab RO - prox0_raw max value (1023) 107*9f70e48eSMauro Carvalho Chehab 108*9f70e48eSMauro Carvalho Chehabprox0_raw_en 109*9f70e48eSMauro Carvalho Chehab 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 113*9f70e48eSMauro Carvalho Chehab 114*9f70e48eSMauro Carvalho Chehabprox0_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 118*9f70e48eSMauro Carvalho Chehab values: 0 or prox0_sensor_range value. 0 means no proximity, 119*9f70e48eSMauro Carvalho Chehab 1023 means proximity. This causes minimal number of interrupts. 120*9f70e48eSMauro Carvalho Chehab In "periodic" mode the driver reports all values above 121*9f70e48eSMauro Carvalho Chehab prox0_thresh_above. This causes more interrupts, but it can give 122*9f70e48eSMauro Carvalho Chehab _rough_ estimate about the distance. 123*9f70e48eSMauro Carvalho Chehab 124*9f70e48eSMauro Carvalho Chehabprox0_reporting_mode_avail 125*9f70e48eSMauro Carvalho Chehab RO - accepted values to prox0_reporting_mode (trigger, periodic) 126*9f70e48eSMauro Carvalho Chehab 127*9f70e48eSMauro Carvalho Chehabprox0_thresh_above_value 128*9f70e48eSMauro Carvalho Chehab RW - threshold level which trigs proximity events. 129