요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=======================
Kernel driver lis3lv02d
=======================
Supported chips:
* STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision)
* STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and
LIS331DLH (16 bits)
Authors:
- Yan Burman <burman.yan@gmail.com>
- Eric Piel <eric.piel@tremplin-utc.net>
Description
-----------
This driver provides support for the accelerometer found in various HP laptops
sporting the feature officially called "HP Mobile Data Protection System 3D" or
"HP 3D DriveGuard". It detects automatically laptops with this sensor. Known
models (full list can be found in drivers/platform/x86/hp_accel.c) will have
their axis automatically oriented on standard way (eg: you can directly play
neverball). The accelerometer data is readable via
/sys/devices/faux/lis3lv02d. Reported values are scaled
to mg values (1/1000th of earth gravity).
Sysfs attributes under /sys/devices/faux/lis3lv02d/:
position
- 3D position that the accelerometer reports. Format: "(x,y,z)"
rate
- read reports the sampling rate of the accelerometer device in HZ.
write changes sampling rate of the accelerometer device.
Only values which are supported by HW are accepted.
selftest
- performs selftest for the chip as specified by chip manufacturer.
This driver also provides an absolute input class device, allowing
the laptop to act as a pinball machine-esque joystick. Joystick device can be
calibrated. Joystick device can be in two different modes.
By default output values are scaled between -32768 .. 32767. In joystick raw
mode, joystick and sysfs position entry have the same scale. There can be
small difference due to input system fuzziness feature.
Events are also available as input event device.
Selftest is meant only for hardware diagnostic purposes. It is not meant to be
used during normal operations. Position data is not corrupted during selftest
but interrupt behaviour is not guaranteed to work reliably. In test mode, the
sensing element is internally moved little bit. Selftest measures difference
between normal mode and test mode. Chip specifications tell the acceptance
limit for each type of the chip. Limits are provided via platform data
to allow adjustment of the limits without a change to the actual driver.
Seltest returns either "OK x y z" or "FAIL x y z" where x, y and z are
measured difference between modes. Axes are not remapped in selftest mode.
Measurement values are provided to help HW diagnostic applications to make
final decision.
On HP laptops, if the led infrastructure is activated, support for a led
indicating disk protection will be provided as /sys/class/leds/hp::hddprotect.
Another feature of the driver is misc device called "freefall" that
acts similar to /dev/rtc and reacts on free-fall interrupts received
from the device. It supports blocking operations, poll/select and
fasync operation modes. You must read 1 bytes from the device. The
result is number of free-fall interrupts since the last successful
read (or 255 if number of interrupts would not fit). See the freefall.c
file for an example on using the device.
Axes orientation
----------------
For better compatibility between the various laptops. The values reported by
the accelerometer are converted into a "standard" organisation of the axes
(aka "can play neverball out of the box"):
* When the laptop is horizontal the position reported is about 0 for X and Y
and a positive value for Z
* If the left side is elevated, X increases (becomes positive)
* If the front side (where the touchpad is) is elevated, Y decreases
(becomes negative)
* If the laptop is put upside-down, Z becomes negative
If your laptop model is not recognized (cf "dmesg"), you can send an
email to the maintainer to add it to the database. When reporting a new
laptop, please include the output of "dmidecode" plus the value of
/sys/devices/faux/lis3lv02d/position in these four cases.
Q&A
---
Q: How do I safely simulate freefall? I have an HP "portable
workstation" which has about 3.5kg and a plastic case, so letting it
fall to the ground is out of question...
A: The sensor is pretty sensitive, so your hands can do it. Lift it
into free space, follow the fall with your hands for like 10
centimeters. That should be enough to trigger the detection.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
지원 chip과 저자
1-14이 driver는 12-bit 정밀도의 STMicroelectronics LIS3LV02DL·LIS3LV02DQ, 8-bit LIS302DL·LIS3L02DQ·LIS331DL, 16-bit LIS331DLH를 지원합니다. 저자는 Yan Burman <burman.yan@gmail.com>과 Eric Piel <eric.piel@tremplin-utc.net>입니다.
=======================
Kernel driver lis3lv02d
=======================
Supported chips:
* STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision)
* STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and
LIS331DLH (16 bits)
Authors:
- Yan Burman <burman.yan@gmail.com>
- Eric Piel <eric.piel@tremplin-utc.net>
HP 가속도계 지원
15-27이 driver는 공식 명칭이 `HP Mobile Data Protection System 3D` 또는 `HP 3D DriveGuard`인 기능을 탑재한 여러 HP laptop의 accelerometer를 지원하며 해당 sensor가 있는 laptop을 자동 감지합니다.
알려진 model의 전체 목록은 `drivers/platform/x86/hp_accel.c`에 있습니다. 이 model들은 axis가 표준 방향으로 자동 정렬되므로 Neverball 같은 application을 바로 사용할 수 있습니다. Accelerometer data는 `/sys/devices/faux/lis3lv02d`에서 읽으며 값은 지구 중력의 1/1000인 mg 단위로 환산됩니다.
Description
-----------
This driver provides support for the accelerometer found in various HP laptops
sporting the feature officially called "HP Mobile Data Protection System 3D" or
"HP 3D DriveGuard". It detects automatically laptops with this sensor. Known
models (full list can be found in drivers/platform/x86/hp_accel.c) will have
their axis automatically oriented on standard way (eg: you can directly play
neverball). The accelerometer data is readable via
/sys/devices/faux/lis3lv02d. Reported values are scaled
to mg values (1/1000th of earth gravity).
Sysfs와 input device
28-45| Attribute | 동작 |
|---|---|
| position | Accelerometer의 3D 위치를 `(x,y,z)` 형식으로 보고합니다. |
| rate | 읽으면 HZ 단위 sampling rate를 보고하고, 쓰면 hardware가 지원하는 값으로 sampling rate를 변경합니다. |
| selftest | Chip 제조사가 규정한 self-test를 수행합니다. |
Driver는 absolute input class device도 제공하므로 laptop을 pinball machine과 비슷한 joystick으로 사용할 수 있습니다. Joystick은 calibration할 수 있고 두 mode를 지원합니다.
기본 mode의 output은 -32768부터 32767까지로 scaling됩니다. Joystick raw mode에서는 joystick과 sysfs `position`이 같은 scale을 사용하지만 input system의 fuzziness 기능 때문에 작은 차이가 생길 수 있습니다. Event는 input event device로도 제공됩니다.
Sysfs attributes under /sys/devices/faux/lis3lv02d/:
position
- 3D position that the accelerometer reports. Format: "(x,y,z)"
rate
- read reports the sampling rate of the accelerometer device in HZ.
write changes sampling rate of the accelerometer device.
Only values which are supported by HW are accepted.
selftest
- performs selftest for the chip as specified by chip manufacturer.
This driver also provides an absolute input class device, allowing
the laptop to act as a pinball machine-esque joystick. Joystick device can be
calibrated. Joystick device can be in two different modes.
By default output values are scaled between -32768 .. 32767. In joystick raw
mode, joystick and sysfs position entry have the same scale. There can be
small difference due to input system fuzziness feature.
Events are also available as input event device.Self-test와 disk-protection LED
46-60Self-test는 hardware 진단 전용이며 정상 동작 중 사용하기 위한 기능이 아닙니다. Self-test 중 position data는 손상되지 않지만 interrupt 동작의 신뢰성은 보장되지 않습니다.
Test mode에서는 sensing element를 내부적으로 조금 움직이고 normal mode와 test mode의 차이를 측정합니다. Chip specification이 chip type별 허용 한계를 정하며, 실제 driver를 바꾸지 않고 한계를 조정할 수 있도록 platform data로 limit를 제공합니다.
Self-test는 `OK x y z` 또는 `FAIL x y z`를 반환합니다. x, y, z는 두 mode 사이에서 측정한 차이이고 self-test mode에서는 axis를 remap하지 않습니다. Measurement 값은 hardware diagnostic application이 최종 판정을 내리는 데 쓰입니다.
HP laptop에서 LED infrastructure가 활성화되어 있으면 disk protection 표시 LED를 `/sys/class/leds/hp::hddprotect`로 제공합니다.
Selftest is meant only for hardware diagnostic purposes. It is not meant to be
used during normal operations. Position data is not corrupted during selftest
but interrupt behaviour is not guaranteed to work reliably. In test mode, the
sensing element is internally moved little bit. Selftest measures difference
between normal mode and test mode. Chip specifications tell the acceptance
limit for each type of the chip. Limits are provided via platform data
to allow adjustment of the limits without a change to the actual driver.
Seltest returns either "OK x y z" or "FAIL x y z" where x, y and z are
measured difference between modes. Axes are not remapped in selftest mode.
Measurement values are provided to help HW diagnostic applications to make
final decision.
On HP laptops, if the led infrastructure is activated, support for a led
indicating disk protection will be provided as /sys/class/leds/hp::hddprotect.Free-fall misc device
61-68Driver는 `freefall`이라는 misc device도 제공합니다. `/dev/rtc`와 비슷하게 device에서 받은 free-fall interrupt에 반응하며 blocking operation, `poll`/`select`, `fasync` mode를 지원합니다.
Device에서는 반드시 1 byte를 읽어야 합니다. 결과는 마지막 successful read 이후 발생한 free-fall interrupt 수이며, 그 수가 한 byte에 들어가지 않으면 255입니다. 사용 예제는 `freefall.c`에 있습니다.
Another feature of the driver is misc device called "freefall" that
acts similar to /dev/rtc and reacts on free-fall interrupts received
from the device. It supports blocking operations, poll/select and
fasync operation modes. You must read 1 bytes from the device. The
result is number of free-fall interrupts since the last successful
read (or 255 if number of interrupts would not fit). See the freefall.c
file for an example on using the device.Axis 표준 방향
69-88서로 다른 laptop 간 호환성을 높이기 위해 accelerometer 값을 표준 axis 구성으로 변환합니다. 이 규칙 덕분에 별도 설정 없이 Neverball 같은 application을 사용할 수 있습니다.
- Laptop이 수평이면 X와 Y는 약 0이고 Z는 양수입니다.
- 왼쪽을 들어 올리면 X가 증가해 양수가 됩니다.
- Touchpad가 있는 앞쪽을 들어 올리면 Y가 감소해 음수가 됩니다.
- Laptop을 뒤집으면 Z가 음수가 됩니다.
Laptop model이 `dmesg`에서 인식되지 않으면 maintainer에게 database 추가를 요청할 수 있습니다. 새 laptop을 보고할 때는 `dmidecode` 출력과 위 네 자세 각각에서 측정한 `/sys/devices/faux/lis3lv02d/position` 값을 포함해야 합니다.
Axes orientation
----------------
For better compatibility between the various laptops. The values reported by
the accelerometer are converted into a "standard" organisation of the axes
(aka "can play neverball out of the box"):
* When the laptop is horizontal the position reported is about 0 for X and Y
and a positive value for Z
* If the left side is elevated, X increases (becomes positive)
* If the front side (where the touchpad is) is elevated, Y decreases
(becomes negative)
* If the laptop is put upside-down, Z becomes negative
If your laptop model is not recognized (cf "dmesg"), you can send an
email to the maintainer to add it to the database. When reporting a new
laptop, please include the output of "dmidecode" plus the value of
/sys/devices/faux/lis3lv02d/position in these four cases.안전한 free-fall 모의
89-99질문은 약 3.5kg의 plastic case를 사용한 HP portable workstation을 실제로 떨어뜨리지 않고 어떻게 안전하게 free-fall을 모의하는지 묻습니다.
Sensor는 매우 민감하므로 손으로도 충분합니다. Laptop을 빈 공간으로 들어 올린 다음 손으로 약 10cm 동안 낙하 움직임을 따라가면 detection을 trigger할 수 있습니다.
Q&A
---
Q: How do I safely simulate freefall? I have an HP "portable
workstation" which has about 3.5kg and a plastic case, so letting it
fall to the ground is out of question...
A: The sensor is pretty sensitive, so your hands can do it. Lift it
into free space, follow the fall with your hands for like 10
centimeters. That should be enough to trigger the detection.
요약·해설
lis3lv02d.rst:1-99Driver는 HP laptop의 LIS3 accelerometer를 표준 axis로 remap하고 mg 단위 position, configurable sample rate, input event, 진단 self-test, disk-protection LED와 free-fall notification을 제공합니다.
Accelerometer interrupt는 freefall misc device를 통해 1-byte count로 userspace에 전달됩니다.
Laptop 자세에 따라 기대되는 X·Y·Z 부호를 보여줍니다.