[mirror_ubuntu-jammy-kernel.git] / Documentation / misc-devices / apds990x.rst

.. SPDX-License-Identifier: GPL-2.0

======================
Kernel driver apds990x
======================

Supported chips:
Avago APDS990X

Data sheet:
Not freely available

Author:
Samu Onkalo <samu.p.onkalo@nokia.com>

Description
-----------

APDS990x is a combined ambient light and proximity sensor. ALS and proximity
functionality are highly connected. ALS measurement path must be running
while the proximity functionality is enabled.

ALS produces raw measurement values for two channels: Clear channel
(infrared + visible light) and IR only. However, threshold comparisons happen
using clear channel only. Lux value and the threshold level on the HW
might vary quite much depending the spectrum of the light source.

Driver makes necessary conversions to both directions so that user handles
only lux values. Lux value is calculated using information from the both
channels. HW threshold level is calculated from the given lux value to match
with current type of the lightning. Sometimes inaccuracy of the estimations
lead to false interrupt, but that doesn't harm.

ALS contains 4 different gain steps. Driver automatically
selects suitable gain step. After each measurement, reliability of the results
is estimated and new measurement is triggered if necessary.

Platform data can provide tuned values to the conversion formulas if
values are known. Otherwise plain sensor default values are used.

Proximity side is little bit simpler. There is no need for complex conversions.
It produces directly usable values.

Driver controls chip operational state using pm_runtime framework.
Voltage regulators are controlled based on chip operational state.

SYSFS
-----


chip_id
	RO - shows detected chip type and version

power_state
	RW - enable / disable chip. Uses counting logic

	     1 enables the chip
	     0 disables the chip
lux0_input
	RO - measured lux value

	     sysfs_notify called when threshold interrupt occurs

lux0_sensor_range
	RO - lux0_input max value.

	     Actually never reaches since sensor tends
	     to saturate much before that. Real max value varies depending
	     on the light spectrum etc.

lux0_rate
	RW - measurement rate in Hz

lux0_rate_avail
	RO - supported measurement rates

lux0_calibscale
	RW - calibration value.

	     Set to neutral value by default.
	     Output results are multiplied with calibscale / calibscale_default
	     value.

lux0_calibscale_default
	RO - neutral calibration value

lux0_thresh_above_value
	RW - HI level threshold value.

	     All results above the value
	     trigs an interrupt. 65535 (i.e. sensor_range) disables the above
	     interrupt.

lux0_thresh_below_value
	RW - LO level threshold value.

	     All results below the value
	     trigs an interrupt. 0 disables the below interrupt.

prox0_raw
	RO - measured proximity value

	     sysfs_notify called when threshold interrupt occurs

prox0_sensor_range
	RO - prox0_raw max value (1023)

prox0_raw_en
	RW - enable / disable proximity - uses counting logic

	     - 1 enables the proximity
	     - 0 disables the proximity

prox0_reporting_mode
	RW - trigger / periodic.

	     In "trigger" mode the driver tells two possible
	     values: 0 or prox0_sensor_range value. 0 means no proximity,
	     1023 means proximity. This causes minimal number of interrupts.
	     In "periodic" mode the driver reports all values above
	     prox0_thresh_above. This causes more interrupts, but it can give
	     _rough_ estimate about the distance.

prox0_reporting_mode_avail
	RO - accepted values to prox0_reporting_mode (trigger, periodic)

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