Commit | Line | Data |
---|---|---|
9b5db89e | 1 | ======================= |
455fbdd3 | 2 | Kernel driver lis3lv02d |
2b872903 | 3 | ======================= |
455fbdd3 PM |
4 | |
5 | Supported chips: | |
6 | ||
bc62c147 | 7 | * STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision) |
0bf5a8be AC |
8 | * STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and |
9 | LIS331DLH (16 bits) | |
455fbdd3 | 10 | |
2b872903 | 11 | Authors: |
9b5db89e MCC |
12 | - Yan Burman <burman.yan@gmail.com> |
13 | - Eric Piel <eric.piel@tremplin-utc.net> | |
455fbdd3 PM |
14 | |
15 | ||
16 | Description | |
17 | ----------- | |
18 | ||
bc62c147 ÉP |
19 | This driver provides support for the accelerometer found in various HP laptops |
20 | sporting the feature officially called "HP Mobile Data Protection System 3D" or | |
21 | "HP 3D DriveGuard". It detects automatically laptops with this sensor. Known | |
efcfed9b JD |
22 | models (full list can be found in drivers/platform/x86/hp_accel.c) will have |
23 | their axis automatically oriented on standard way (eg: you can directly play | |
bc62c147 | 24 | neverball). The accelerometer data is readable via |
e956e6b7 SO |
25 | /sys/devices/platform/lis3lv02d. Reported values are scaled |
26 | to mg values (1/1000th of earth gravity). | |
455fbdd3 PM |
27 | |
28 | Sysfs attributes under /sys/devices/platform/lis3lv02d/: | |
9b5db89e MCC |
29 | |
30 | position | |
31 | - 3D position that the accelerometer reports. Format: "(x,y,z)" | |
32 | rate | |
33 | - read reports the sampling rate of the accelerometer device in HZ. | |
e956e6b7 SO |
34 | write changes sampling rate of the accelerometer device. |
35 | Only values which are supported by HW are accepted. | |
9b5db89e MCC |
36 | selftest |
37 | - performs selftest for the chip as specified by chip manufacturer. | |
455fbdd3 PM |
38 | |
39 | This driver also provides an absolute input class device, allowing | |
e956e6b7 SO |
40 | the laptop to act as a pinball machine-esque joystick. Joystick device can be |
41 | calibrated. Joystick device can be in two different modes. | |
42 | By default output values are scaled between -32768 .. 32767. In joystick raw | |
43 | mode, joystick and sysfs position entry have the same scale. There can be | |
44 | small difference due to input system fuzziness feature. | |
45 | Events are also available as input event device. | |
46 | ||
47 | Selftest is meant only for hardware diagnostic purposes. It is not meant to be | |
48 | used during normal operations. Position data is not corrupted during selftest | |
49 | but interrupt behaviour is not guaranteed to work reliably. In test mode, the | |
50 | sensing element is internally moved little bit. Selftest measures difference | |
51 | between normal mode and test mode. Chip specifications tell the acceptance | |
52 | limit for each type of the chip. Limits are provided via platform data | |
53 | to allow adjustment of the limits without a change to the actual driver. | |
54 | Seltest returns either "OK x y z" or "FAIL x y z" where x, y and z are | |
55 | measured difference between modes. Axes are not remapped in selftest mode. | |
56 | Measurement values are provided to help HW diagnostic applications to make | |
57 | final decision. | |
455fbdd3 | 58 | |
bc62c147 ÉP |
59 | On HP laptops, if the led infrastructure is activated, support for a led |
60 | indicating disk protection will be provided as /sys/class/leds/hp::hddprotect. | |
61 | ||
ef2cfc79 PM |
62 | Another feature of the driver is misc device called "freefall" that |
63 | acts similar to /dev/rtc and reacts on free-fall interrupts received | |
64 | from the device. It supports blocking operations, poll/select and | |
65 | fasync operation modes. You must read 1 bytes from the device. The | |
66 | result is number of free-fall interrupts since the last successful | |
0024d6e9 | 67 | read (or 255 if number of interrupts would not fit). See the freefall.c |
bc62c147 | 68 | file for an example on using the device. |
ef2cfc79 PM |
69 | |
70 | ||
455fbdd3 PM |
71 | Axes orientation |
72 | ---------------- | |
73 | ||
74 | For better compatibility between the various laptops. The values reported by | |
75 | the accelerometer are converted into a "standard" organisation of the axes | |
76 | (aka "can play neverball out of the box"): | |
9b5db89e | 77 | |
455fbdd3 | 78 | * When the laptop is horizontal the position reported is about 0 for X and Y |
9b5db89e | 79 | and a positive value for Z |
455fbdd3 | 80 | * If the left side is elevated, X increases (becomes positive) |
219beb29 | 81 | * If the front side (where the touchpad is) is elevated, Y decreases |
9b5db89e | 82 | (becomes negative) |
455fbdd3 PM |
83 | * If the laptop is put upside-down, Z becomes negative |
84 | ||
219beb29 | 85 | If your laptop model is not recognized (cf "dmesg"), you can send an |
bc62c147 | 86 | email to the maintainer to add it to the database. When reporting a new |
219beb29 PM |
87 | laptop, please include the output of "dmidecode" plus the value of |
88 | /sys/devices/platform/lis3lv02d/position in these four cases. | |
455fbdd3 | 89 | |
2b872903 PM |
90 | Q&A |
91 | --- | |
92 | ||
93 | Q: How do I safely simulate freefall? I have an HP "portable | |
94 | workstation" which has about 3.5kg and a plastic case, so letting it | |
95 | fall to the ground is out of question... | |
96 | ||
97 | A: The sensor is pretty sensitive, so your hands can do it. Lift it | |
98 | into free space, follow the fall with your hands for like 10 | |
99 | centimeters. That should be enough to trigger the detection. |