| 1 | =======================
|
| 2 | Kernel driver lis3lv02d
|
| 3 | =======================
|
| 4 |
|
| 5 | Supported chips:
|
| 6 |
|
| 7 | * STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision)
|
| 8 | * STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and
|
| 9 | LIS331DLH (16 bits)
|
| 10 |
|
| 11 | Authors:
|
| 12 | - Yan Burman <[email protected]>
|
| 13 | - Eric Piel <[email protected]>
|
| 14 |
|
| 15 |
|
| 16 | Description
|
| 17 | -----------
|
| 18 |
|
| 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
|
| 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
|
| 24 | neverball). The accelerometer data is readable via
|
| 25 | /sys/devices/faux/lis3lv02d. Reported values are scaled
|
| 26 | to mg values (1/1000th of earth gravity).
|
| 27 |
|
| 28 | Sysfs attributes under /sys/devices/faux/lis3lv02d/:
|
| 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.
|
| 34 | write changes sampling rate of the accelerometer device.
|
| 35 | Only values which are supported by HW are accepted.
|
| 36 | selftest
|
| 37 | - performs selftest for the chip as specified by chip manufacturer.
|
| 38 |
|
| 39 | This driver also provides an absolute input class device, allowing
|
| 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.
|
| 58 |
|
| 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 |
|
| 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
|
| 67 | read (or 255 if number of interrupts would not fit). See the freefall.c
|
| 68 | file for an example on using the device.
|
| 69 |
|
| 70 |
|
| 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"):
|
| 77 |
|
| 78 | * When the laptop is horizontal the position reported is about 0 for X and Y
|
| 79 | and a positive value for Z
|
| 80 | * If the left side is elevated, X increases (becomes positive)
|
| 81 | * If the front side (where the touchpad is) is elevated, Y decreases
|
| 82 | (becomes negative)
|
| 83 | * If the laptop is put upside-down, Z becomes negative
|
| 84 |
|
| 85 | If your laptop model is not recognized (cf "dmesg"), you can send an
|
| 86 | email to the maintainer to add it to the database. When reporting a new
|
| 87 | laptop, please include the output of "dmidecode" plus the value of
|
| 88 | /sys/devices/faux/lis3lv02d/position in these four cases.
|
| 89 |
|
| 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.
|