Kernel Driver BH1770GLC | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

bh1770glc.rst:1-135

ALS와 proximity는 독립 block이지만 I2C·interrupt를 공유하며 proximity reliability 판단에 ALS 값을 사용합니다. 따라서 proximity detection 동안 ALS도 계속 동작합니다.

Proximity-off 판정

Above-threshold interruptDelayed work 연기Proximity on 유지

Interrupt 중단Delayed work 실행No proximity 보고

Chip에 low interrupt가 없어 above-threshold interrupt가 멈춘 시간을 delayed work로 판정합니다.

Proximity threshold

AttributeFilterEvent

prox0_thresh_above0_valuePersistence countFiltered event

prox0_thresh_above1_value없음Immediate event

Persistence를 거치는 threshold와 즉시 event threshold를 구분합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

3 =======================

4 Kernel driver bh1770glc

5 =======================

7 Supported chips:

9 - ROHM BH1770GLC

10 - OSRAM SFH7770

12 Data sheet:

13 Not freely available

15 Author:

16 Samu Onkalo <[email protected]>

18 Description

19 -----------

20 BH1770GLC and SFH7770 are combined ambient light and proximity sensors.

21 ALS and proximity parts operates on their own, but they shares common I2C

22 interface and interrupt logic. In principle they can run on their own,

23 but ALS side results are used to estimate reliability of the proximity sensor.

25 ALS produces 16 bit lux values. The chip contains interrupt logic to produce

26 low and high threshold interrupts.

28 Proximity part contains IR-led driver up to 3 IR leds. The chip measures

29 amount of reflected IR light and produces proximity result. Resolution is

30 8 bit. Driver supports only one channel. Driver uses ALS results to estimate

31 reliability of the proximity results. Thus ALS is always running while

32 proximity detection is needed.

34 Driver uses threshold interrupts to avoid need for polling the values.

35 Proximity low interrupt doesn't exists in the chip. This is simulated

36 by using a delayed work. As long as there is proximity threshold above

37 interrupts the delayed work is pushed forward. So, when proximity level goes

38 below the threshold value, there is no interrupt and the delayed work will

39 finally run. This is handled as no proximity indication.

41 Chip state is controlled via runtime pm framework when enabled in config.

43 Calibscale factor is used to hide differences between the chips. By default

44 value set to neutral state meaning factor of 1.00. To get proper values,

45 calibrated source of light is needed as a reference. Calibscale factor is set

46 so that measurement produces about the expected lux value.

48 SYSFS

49 -----

51 chip_id

52 RO - shows detected chip type and version

54 power_state

55 RW - enable / disable chip

57 Uses counting logic

59 - 1 enables the chip

60 - 0 disables the chip

62 lux0_input

63 RO - measured lux value

65 sysfs_notify called when threshold interrupt occurs

67 lux0_sensor_range

68 RO - lux0_input max value

70 lux0_rate

71 RW - measurement rate in Hz

73 lux0_rate_avail

74 RO - supported measurement rates

76 lux0_thresh_above_value

77 RW - HI level threshold value

79 All results above the value

80 trigs an interrupt. 65535 (i.e. sensor_range) disables the above

81 interrupt.

83 lux0_thresh_below_value

84 RW - LO level threshold value

86 All results below the value

87 trigs an interrupt. 0 disables the below interrupt.

89 lux0_calibscale

90 RW - calibration value

92 Set to neutral value by default.

93 Output results are multiplied with calibscale / calibscale_default

94 value.

96 lux0_calibscale_default

97 RO - neutral calibration value

99 prox0_raw

100 RO - measured proximity value

101

102 sysfs_notify called when threshold interrupt occurs

103

104 prox0_sensor_range

105 RO - prox0_raw max value

106

107 prox0_raw_en

108 RW - enable / disable proximity

109

110 Uses counting logic

111

112 - 1 enables the proximity

113 - 0 disables the proximity

114

115 prox0_thresh_above_count

116 RW - number of proximity interrupts needed before triggering the event

117

118 prox0_rate_above

119 RW - Measurement rate (in Hz) when the level is above threshold

120 i.e. when proximity on has been reported.

121

122 prox0_rate_below

123 RW - Measurement rate (in Hz) when the level is below threshold

124 i.e. when proximity off has been reported.

125

126 prox0_rate_avail

127 RO - Supported proximity measurement rates in Hz

128

129 prox0_thresh_above0_value

130 RW - threshold level which trigs proximity events.

131

132 Filtered by persistence filter (prox0_thresh_above_count)

133

134 prox0_thresh_above1_value

135 RW - threshold level which trigs event immediately

136

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

지원 chip

1-17

이 driver는 ROHM BH1770GLC와 OSRAM SFH7770을 지원합니다. Datasheet는 자유롭게 제공되지 않으며 저자는 Samu Onkalo <[email protected]>입니다.

.. SPDX-License-Identifier: GPL-2.0

=======================
Kernel driver bh1770glc
=======================

Supported chips:

- ROHM BH1770GLC
- OSRAM SFH7770

Data sheet:
Not freely available

Author:
Samu Onkalo <[email protected]>

Sensor 동작

18-47

BH1770GLC와 SFH7770은 ambient-light와 proximity를 결합한 sensor입니다. ALS와 proximity 부분은 독립적으로 동작하지만 I2C interface와 interrupt logic을 공유합니다. 원칙적으로 각각 실행할 수 있으나 proximity 결과의 reliability를 추정할 때 ALS 결과를 사용합니다.

ALS는 16-bit lux 값을 만들며 chip은 low·high threshold interrupt logic을 포함합니다.

Proximity 부분에는 최대 3개 IR LED용 driver가 있습니다. 반사된 IR light의 양을 측정해 8-bit proximity 결과를 만들며 이 driver는 channel 하나만 지원합니다. Proximity detection이 필요한 동안 reliability 판단을 위해 ALS도 항상 실행합니다.

Driver는 polling을 피하려고 threshold interrupt를 사용합니다. Chip에 proximity low interrupt가 없으므로 delayed work로 이를 흉내 냅니다. Above-threshold interrupt가 계속 발생하는 동안 delayed work를 뒤로 미루고, level이 threshold 아래로 내려가 interrupt가 멈추면 마침내 delayed work가 실행되어 no-proximity로 처리합니다.

Config에서 enable하면 runtime PM framework가 chip state를 제어합니다. `calibscale`은 chip 간 차이를 숨기며 기본값 1.00이 neutral입니다. 정확한 값을 얻으려면 calibration된 light source를 기준으로 measurement가 예상 lux를 내도록 factor를 설정합니다.

Description
-----------
BH1770GLC and SFH7770 are combined ambient light and proximity sensors.
ALS and proximity parts operates on their own, but they shares common I2C
interface and interrupt logic. In principle they can run on their own,
but ALS side results are used to estimate reliability of the proximity sensor.

ALS produces 16 bit lux values. The chip contains interrupt logic to produce
low and high threshold interrupts.

Proximity part contains IR-led driver up to 3 IR leds. The chip measures
amount of reflected IR light and produces proximity result. Resolution is
8 bit. Driver supports only one channel. Driver uses ALS results to estimate
reliability of the proximity results. Thus ALS is always running while
proximity detection is needed.

Driver uses threshold interrupts to avoid need for polling the values.
Proximity low interrupt doesn't exists in the chip. This is simulated
by using a delayed work. As long as there is proximity threshold above
interrupts the delayed work is pushed forward. So, when proximity level goes
below the threshold value, there is no interrupt and the delayed work will
finally run. This is handled as no proximity indication.

Chip state is controlled via runtime pm framework when enabled in config.

Calibscale factor is used to hide differences between the chips. By default
value set to neutral state meaning factor of 1.00. To get proper values,
calibrated source of light is needed as a reference. Calibscale factor is set
so that measurement produces about the expected lux value.

ALS sysfs

48-98

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의 최댓값입니다.
lux0_rate	RW	Hz 단위 measurement rate입니다.
lux0_rate_avail	RO	지원하는 measurement rate입니다.
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합니다.
lux0_calibscale	RW	Calibration 값입니다. 기본은 neutral이며 출력에 calibscale / calibscale_default를 곱합니다.
lux0_calibscale_default	RO	Neutral calibration 값입니다.

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

lux0_rate
        RW - measurement rate in Hz

lux0_rate_avail
        RO - supported measurement rates

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.

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

Proximity sysfs

99-135

Attribute	Access	의미
prox0_raw	RO	측정한 proximity 값이며 threshold interrupt 때 sysfs_notify를 호출합니다.
prox0_sensor_range	RO	prox0_raw의 최댓값입니다.
prox0_raw_en	RW	Counting logic으로 proximity를 enable/disable합니다. 1은 enable, 0은 disable입니다.
prox0_thresh_above_count	RW	Event를 trigger하기 전에 필요한 proximity interrupt 수입니다.
prox0_rate_above	RW	Level이 threshold 위여서 proximity-on이 보고된 때의 Hz 단위 measurement rate입니다.
prox0_rate_below	RW	Level이 threshold 아래여서 proximity-off가 보고된 때의 Hz 단위 measurement rate입니다.
prox0_rate_avail	RO	지원하는 proximity measurement rate를 Hz로 표시합니다.
prox0_thresh_above0_value	RW	Persistence filter(prox0_thresh_above_count)를 거쳐 proximity event를 발생시키는 threshold입니다.
prox0_thresh_above1_value	RW	즉시 event를 발생시키는 threshold입니다.

prox0_raw
        RO - measured proximity value

             sysfs_notify called when threshold interrupt occurs

prox0_sensor_range
        RO - prox0_raw max value

prox0_raw_en
        RW - enable / disable proximity

             Uses counting logic

             - 1 enables the proximity
             - 0 disables the proximity

prox0_thresh_above_count
        RW - number of proximity interrupts needed before triggering the event

prox0_rate_above
        RW - Measurement rate (in Hz) when the level is above threshold
        i.e. when proximity on has been reported.

prox0_rate_below
        RW - Measurement rate (in Hz) when the level is below threshold
        i.e. when proximity off has been reported.

prox0_rate_avail
        RO - Supported proximity measurement rates in Hz

prox0_thresh_above0_value
        RW - threshold level which trigs proximity events.

             Filtered by persistence filter (prox0_thresh_above_count)

prox0_thresh_above1_value
        RW - threshold level which trigs event immediately