Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755580Ab3FPVj0 (ORCPT ); Sun, 16 Jun 2013 17:39:26 -0400 Received: from etezian.org ([198.101.225.253]:40803 "EHLO mail.etezian.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755521Ab3FPVjR (ORCPT ); Sun, 16 Jun 2013 17:39:17 -0400 From: Andi Shyti To: arnd@arndb.de, gregkh@linuxfoundation.org, rob@landley.net Cc: oatilla@gmail.com, szsolt@gmail.com, linux-kernel@vger.kernel.org, andi@etezian.org, linux-doc@vger.kernel.org Subject: [PATCH 2/2] Documentation: added etzkx driver documentation Date: Sun, 16 Jun 2013 23:40:28 +0200 Message-Id: X-Mailer: git-send-email 1.7.10.4 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 11234 Lines: 352 The etzkx driver's documentation contains some basic information about - accelerometer chip overview - driver interfaces - driver usage Signed-off-by: Andi Shyti Reviewed-by: Onur Atilla --- Documentation/misc-devices/etzkx.txt | 325 ++++++++++++++++++++++++++++++++++ 1 file changed, 325 insertions(+) create mode 100644 Documentation/misc-devices/etzkx.txt diff --git a/Documentation/misc-devices/etzkx.txt b/Documentation/misc-devices/etzkx.txt new file mode 100644 index 0000000..5d2017c --- /dev/null +++ b/Documentation/misc-devices/etzkx.txt @@ -0,0 +1,325 @@ + ETZKX - State Machine Interrupt Driven Accelerometer + ==================================================== + +Author: Andi Shyti + +The etzkx driver provides support for the programmable state machine interrupt +driven 3-axis accelerometer. +The chip is manifactured by: + + ROHM Semiconductor: kxcnl-1010 + +Device description +------------------ +The kxcnl-1010 accelerometer is an ultra low-power device based on a +differential capacitance arising from acceleration-induced motion of the sensor +element. The device has a dynamically user selectable sensitivity scale of ++-2/+-4/+-6/+-8g. Moreover the user has the possibility to select the sampling +frequency (odr) from 3.125Hz to 1.6kHz. + +The X, Y, Z coordinates are accessible by polling the device. Interrupt +generation on data ready is also possible if preferred. + +The device is capable of running two state machines for gesture recognition +such as orientation change, shake, tap, etc. Two sets of registers are used to +load the algorithms for the state machine. + +The communication with the CPU is done via I2C bus. Two interrupt lines allow +signalling the state machines behavior and possibly the presence of new +data. + +The device implements a hardware selftest functionality which allows testing of +the reliability of the device. + +The driver +---------- +The driver is located under + + driver/misc/etzkx.c + include/linux/i2c/etzkx.h + +and is placed in between the i2c driver and the userspace interfaces + + __________________________ + | | | | + | input | sysfs | char | + | device | | device | + |________|________|________| + | | + | etzkx | + |__________________________| + | | + | i2c smbus | + |__________________________| + | | + | i2c xfer | + | | + +==========================+ + | | + | kxcnl-1010 | + |__________________________| + + +In the menuconfig the driver is reachable + + Device Drivers ---> + [*] Misc devices ---> + <*> ETZKX kxcnl 3d digital accelerometer + +The interfaces +-------------- +The driver generates three types of interfaces: + + * sysfs: provides information related to the device and sets some basic + parameters like output data rate (odr) and range. + + * input event: provides the X, Y, Z coordinates. + + * character device: provides state machine related information. + +Sysfs interfaces +---------------- +Here is a list of all the sysfs interfaces generated by the driver + +hwid + RO - shows the chip installed on the board + +enable + RW - enables/disables the streaming of X, Y, Z coordinates which are + readable from the input event file + 1 enables the the streaming + 0 disables the streaming + +odr + RW - sets the output data rate of the chip, i.e. sets the frequency of + working of the chip. The available data rates are (in Hz) 3.125, + 6.25, 12.5, 25, 50, 100, 400, 1600. It is possible to write a + generic frequency and the driver will normalize it to the closest + available. When a state machine is running the user is prevented + form changing the odr. + +delay + RW - sets the driver polling rate in ms. Usually is + + 1 + delay = ----- + odr + + but depending of some state machine conditions, odr and delay + might not be synchronized. + +range + RW - sets the sensitivity measured in g. The available g range are + +-2g, +-4g, +-6g, +-8g. When a state machine is running, the user + is prevented from changing the range. + +self_test + RW - enables/disables the self-test functionality. When the self_test is + enabled the X, Y, Z axes are affected by an offset, that offset + allows to evaluate the liability of the device (refer to the + datasheets for the self test patterns) + 1 enables self test + 0 disables self test + +drv_version + RO - shows the driver version + +Input event interface +--------------------- +The input event is generated under /dev/input/eventX, where X is an incremental +number chosen by the input driver framework. + +To eventX file is associated the 'etzkx' name which is discoverable using an +ioctl function with EVIOCGNAME flag. + + DIR *dir; + struct dirent *de; + char *fname; + [...] + + dir = opendir("/dev/input"); + while ( (de = readdir(dir)) ) + { + fd = open(de->d_name, O_RDONLY)) + ioctl(fd, EVIOCGNAME(sizeof(fname) - 1), &fname) + + if (!strcmp(fname, "etzkx")) + /*** found it! ***/ + + close (fd); + } + +The driver streams the coordinates every "delay" ms (or "odr" Hz) through this +interface. The input driver sends a struct input_event to the interface buffer, +which has the following structure: + + #include + + struct input_event { + struct timeval time; + __u16 type; + __u16 code; + __s32 value; + }; + +where the type event is EV_ABS, the code of the event is ABS_X, ABS_Y, ABS_Z +corresponding to the X, Y, Z coordiantes and in the end the value field is the +specific coordinate value. The driver sends three different events for each +coordinate followed by a synchronization event which has type=0, code=0 and +value=0. + +A possible reading algorithm can be + + struct input_event ev; + + while (1) + { + do + { + read(fd, &ev, sizeof(struct input_event)); + + if (ev.type == EV_ABS) + switch (ev.code) + { + case ABS_X: + X = ev.value; + break; + case ABS_Y: + Y = ev.value; + break; + case ABS_Z: + Z = ev.value; + break; + } + } while (ev.type != EV_SYN); + } + +Character device +---------------- +The character device is used to report to the userspace the running state +machine's outcome. The interface is capable of polling so that it is possible to +use select() or poll() on it. The character interface is generated as + + /dev/etzkx_stm + +The driver communicates with userspace by writing 64 bit structure on the +interface + + +-----+--------------------------+ + | 32 | algorithm id | + +-----+--------------------------+ + | 32 | specific algorithm data | + +-----+--------------------------+ + +Currently, three algorithms are implemented: + + - algorithm id + ETZKX_STM_ID_TIMING: timing algorithm used for testing. It sends an interrupt + every 16 odr. + + ETZKX_STM_ID_ORIENTATION: sends an interrupt every orientation change + (portrait or landscape) + + ETZKX_STM_ID_DOUBLE_TAP: sends an interrupt every time that a double tap + is detected + + - specific algorithm data + timing (bit order) + 32 bit: not relevant, uninitialized + + orientation (bit order) + 16 bit: 1 if portrait, 0 otherwise + 16 bit: 1 if landscape, 0 otherwise + + double tap (bit order) + 8 bit: 1 if +x, 2 if -x, 0 otherwise + 8 bit: 1 if +y, 2 if -y, 0 otherwise + 8 bit: 1 if +z, 2 if -z, 0 otherwise + 8 bit: double tap peak + +The /dev/etzkx_stm file is capable of ioctl with the following flags + + ETZKXIO_ENABLE_TIMING: enables timing algorithm + ETZKXIO_DISABLE_TIMING: disable timing algorithm + ETZKXIO_ENABLE_ORIENTATION: enables orientation algorithm + ETZKXIO_DISABLE_ORIENTATION: disables orientation algorithm + ETZKXIO_ENABLE_DOUBLE_TAP: enables double tap algorithm + ETZKXIO_DISABLE_DOUBLE_TAP: disables double tap algorithm + + ETZKXIO_WHICH_ORIENTATION: asks to the driver the actual orientation + status. The driver provides via ioctl an algorithm structure like + this: + + 32 bit: ETZKX_STM_ID_ORIENTATION + 16 bit: 1 if portrait, 0 otherwise + 16 bit: 1 if landscape, 0 otherwise + + ETZKXIO_INSTANT_ORIENTATION: like ETZKXIO_WHICH_ORIENTATION, with the + difference that the calculation of the orientation is calculated by + comparing the X and Y coordinates. + + ETZKXIO_RUNNING_ALGO: reports to the userspace the two running + algorithms for each state machine slot: + + 32 bit: running algorithm id on slot 1 + 32 bit: running algorithm id on slot 2 + + if no state machine is loaded, the id is equal to ETZKX_STM_ID_NO_STM + +Driver usage +------------ +The driver follows a state machine way of working and at any time it tracks the +state which the driver is in. + + __STRM --- STRM + STM1 + / \/ \ + / /\ \ + STBY --- ACTIVE --- STM1 STRM + STM2 --- STRM + STM1 + STM2 + \ \/ / + \__ /\ / + STM2 --- STM1 + STM2 + +To reach each driver state, userspace applications have to enable/disable the +available features using the related interfaces. + +Enable/disable streaming (STRM state): + echo 1 > /sys/.../enable + echo 0 > /sys/.../enable + +Enable/disable state machine (STM1/STM2 state): + ioctl (fd, ETZKXIO_ENABLE_ORIENTATION, 0); + ioctl (fd, ETZKXIO_ENABLE_DOUBLE_TAP, 0); + ioctl (fd, ETZKXIO_DISABLE_ORIENTATION, 0); + ioctl (fd, ETZKXIO_DISABLE_DOUBLE_TAP, 0); + +Self test +--------- +The self test checks the electromechanical functionality of the sensor. The +driver sets the self test state as a specific branch of the driver state +machine: + + _ + / ST + / ^ + STDBY <---> ACTIVE | + \ | + \_ v + STRM + +To enable/disable the self test + + echo 1 > /sys/.../self_test + echo 0 > /sys/.../self_test + +This applies an extra capacitance to every axes which adds an offset to the X, +Y, Z output, it can be different for each coordinate. + +The suppliers provides the minimum Dx, Dy, Dz offset in order to consider the +device reliable. The evaluation should be done like follows: + + |Xst - X| > Dx + |Yst - Y| > Dy + |Zst - Z| > Dz + +where Xst, Yst and Zst are the coordinates measured after applying the self test +on the accelerometer. -- 1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/