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