요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
======================
4
Kernel driver apds990x
5
======================
7
Supported chips:
8
Avago APDS990X
10
Data sheet:
11
Not freely available
13
Author:
14
Samu Onkalo <samu.p.onkalo@nokia.com>
16
Description
17
-----------
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.
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.
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.
34
ALS contains 4 different gain steps. Driver automatically
35
selects suitable gain step. After each measurement, reliability of the results
36
is estimated and new measurement is triggered if necessary.
38
Platform data can provide tuned values to the conversion formulas if
39
values are known. Otherwise plain sensor default values are used.
41
Proximity side is little bit simpler. There is no need for complex conversions.
42
It produces directly usable values.
44
Driver controls chip operational state using pm_runtime framework.
45
Voltage regulators are controlled based on chip operational state.
47
SYSFS
48
-----
51
chip_id
52
RO - shows detected chip type and version
54
power_state
55
RW - enable / disable chip. Uses counting logic
57
1 enables the chip
58
0 disables the chip
59
lux0_input
60
RO - measured lux value
62
sysfs_notify called when threshold interrupt occurs
64
lux0_sensor_range
65
RO - lux0_input max value.
67
Actually never reaches since sensor tends
68
to saturate much before that. Real max value varies depending
69
on the light spectrum etc.
71
lux0_rate
72
RW - measurement rate in Hz
74
lux0_rate_avail
75
RO - supported measurement rates
77
lux0_calibscale
78
RW - calibration value.
80
Set to neutral value by default.
81
Output results are multiplied with calibscale / calibscale_default
82
value.
84
lux0_calibscale_default
85
RO - neutral calibration value
87
lux0_thresh_above_value
88
RW - HI level threshold value.
90
All results above the value
91
trigs an interrupt. 65535 (i.e. sensor_range) disables the above
92
interrupt.
94
lux0_thresh_below_value
95
RW - LO level threshold value.
97
All results below the value
98
trigs an interrupt. 0 disables the below interrupt.
100
prox0_raw
101
RO - measured proximity value
103
sysfs_notify called when threshold interrupt occurs
105
prox0_sensor_range
106
RO - prox0_raw max value (1023)
108
prox0_raw_en
109
RW - enable / disable proximity - uses counting logic
111
- 1 enables the proximity
112
- 0 disables the proximity
114
prox0_reporting_mode
115
RW - trigger / periodic.
117
In "trigger" mode the driver tells two possible
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.
124
prox0_reporting_mode_avail
125
RO - accepted values to prox0_reporting_mode (trigger, periodic)
127
prox0_thresh_above_value
128
RW - threshold level which trigs proximity events.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
지원 device
1-15이 문서는 Avago APDS990X를 지원하는 `apds990x` kernel driver를 설명합니다. Datasheet는 자유롭게 제공되지 않으며 저자는 Samu Onkalo <samu.p.onkalo@nokia.com>입니다.
.. 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>
동작과 변환
16-46APDS990x는 ambient light와 proximity를 결합한 sensor입니다. ALS와 proximity 기능은 긴밀히 연결되어 있어 proximity 기능이 enable된 동안 ALS measurement path도 실행되어야 합니다.
ALS는 clear channel(infrared + visible light)과 IR-only channel의 raw measurement를 만듭니다. Threshold 비교는 clear channel만 사용합니다. Lux 값과 hardware threshold level은 light-source spectrum에 따라 크게 달라질 수 있습니다.
Driver가 양방향 변환을 담당하므로 사용자는 lux 값만 다룹니다. 두 channel의 정보로 lux를 계산하고, 현재 조명 유형에 맞도록 입력 lux 값에서 hardware threshold level을 계산합니다. 추정 오차가 false interrupt를 만들 수 있지만 해롭지는 않습니다.
ALS에는 네 gain step이 있으며 driver가 적절한 step을 자동 선택합니다. 각 measurement 뒤 결과의 reliability를 추정하고 필요하면 새 measurement를 시작합니다.
Platform data가 알려진 tuning 값을 conversion formula에 제공할 수 있습니다. 값이 없으면 sensor 기본값을 사용합니다. Proximity 쪽은 복잡한 변환 없이 바로 사용할 수 있는 값을 냅니다.
Driver는 `pm_runtime` framework로 chip operational state를 제어하며 voltage regulator도 이 state에 맞춰 제어합니다.
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.
ALS sysfs attribute
47-99| Attribute | Access | 의미 |
|---|---|---|
| chip_id | RO | 감지한 chip type과 version을 표시합니다. |
| power_state | RW | Counting logic으로 chip을 enable/disable합니다. 1은 enable, 0은 disable입니다. |
| lux0_input | RO | 측정한 lux 값입니다. Threshold interrupt가 발생하면 sysfs_notify를 호출합니다. |
| lux0_sensor_range | RO | lux0_input의 최댓값입니다. 실제로는 먼저 saturate하며 실제 최댓값은 light spectrum 등에 따라 달라집니다. |
| lux0_rate | RW | Hz 단위 measurement rate입니다. |
| lux0_rate_avail | RO | 지원하는 measurement rate입니다. |
| lux0_calibscale | RW | Calibration 값입니다. 기본은 neutral이며 출력에 calibscale / calibscale_default를 곱합니다. |
| lux0_calibscale_default | RO | Neutral calibration 값입니다. |
| lux0_thresh_above_value | RW | HI threshold입니다. 이보다 큰 결과가 interrupt를 발생시키며 65535(sensor_range)는 above interrupt를 disable합니다. |
| lux0_thresh_below_value | RW | LO threshold입니다. 이보다 작은 결과가 interrupt를 발생시키며 0은 below interrupt를 disable합니다. |
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.
Proximity sysfs attribute
100-128| Attribute | Access | 의미 |
|---|---|---|
| prox0_raw | RO | 측정한 proximity 값입니다. Threshold interrupt가 발생하면 sysfs_notify를 호출합니다. |
| prox0_sensor_range | RO | prox0_raw의 최댓값인 1023입니다. |
| prox0_raw_en | RW | Counting logic으로 proximity를 enable/disable합니다. 1은 enable, 0은 disable입니다. |
| prox0_reporting_mode | RW | trigger 또는 periodic입니다. trigger mode는 0(no proximity) 또는 1023(proximity)만 보고해 interrupt를 최소화합니다. periodic mode는 prox0_thresh_above보다 큰 값을 모두 보고해 interrupt가 늘지만 거리를 대략 추정할 수 있습니다. |
| prox0_reporting_mode_avail | RO | 허용되는 값인 trigger와 periodic을 표시합니다. |
| prox0_thresh_above_value | RW | Proximity event를 발생시키는 threshold level입니다. |
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.
요약·해설
apds990x.rst:1-128Driver는 clear·IR channel에서 lux를 계산하고 현재 spectrum에 맞춰 hardware threshold를 역산합니다. Gain과 재측정을 자동 관리하며 proximity가 켜진 동안 ALS path도 유지합니다.
두 optical channel이 lux 변환에 참여하고 clear channel은 threshold 비교에도 사용됩니다.
Interrupt 빈도와 거리 정보의 정밀도 사이에서 mode를 선택합니다.