[PATCH 2/2] Documentation: added etzkx driver documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



The etzkx driver's documentation contains some basic information about

 - accelerometer chip overview
 - driver interfaces
 - driver usage

Signed-off-by: Andi Shyti <andi@xxxxxxxxxxx>
Reviewed-by: Onur Atilla <oatilla@xxxxxxxxx>
---
 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 <andi@xxxxxxxxxxx>
+
+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 <linux/input.h>
+
+	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-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux