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