A generic Touch Screen major number to be registered according to the procedure documented in ../linux/Documentation/devices.txt.
A major number 10 seems the most likely candidate (TBD).
/dev/ts This is the device used to read calibrated touch screen events
A generic Touch Screen device name (/dev/ts) and minor number (TBD) to be registered according to the procedure documented in ../linux/Documentation/devices.txt.
This is the structure contains the X and Y pixel coordinates of a single touch screen event. It is passed from the driver to the user by the read() function.
typedef
struct {
short pressure; /* used to determine if the pen is up or down (Note 1) */
short
x; /*
If pen is down then this is the pixel X
coordinate */
short y; /* If pen is down then this is the pixel Y coordinate */
}
TS_EVENT;
In addition to open(), close() and ioctl() functions, blocking and non-blocking read() and asynchronous notification (SIGIO) should be supported at the user level. The select/poll mechanism will also be supported.
The following file operations pertain to device /dev/ts.
_read()
Blocking reads will block until a TS_EVENT structure (see below) can be returned.
_fasync()
SIGIO to user when there is an event to report. An event is defined as reception of a complete TS_EVENT structure.
_poll()
If there are 1 or more TS_EVENT structures to be read then this function will return the (POLLIN | POLLRDNORM) flags otherwise a zero will be returned.
_ioctl()
The list of ioctls will depend on the hardware used to implement the touch screen (example UCB1200). Initialisation ioctls will be called by the driver’s init_module() or equivalent. The calibration application will have it’s own ioctls (see CALIBRATION section).
In general the ioctl command
numbers should be ‘mangled’ using the _IO,_IOW,_IOR,_IOWR
macros as defined in <linux/ioctl.h>
A ‘magic number’ of ‘t’ should be used (see CALIBRATION section)
#define
IOC_MAGIC ‘t’
The following example code can be found in the ../apps/h3600_test directory on the http://www.handhelds.org/ CVS tree.
ts_poll.c
example of a non-blocking read using the poll/select mechanism.
ts_read.c
example of a blocking read.
fasynctst.c
example of how asynchronous notifications are handled in user space.
The driver which implements most of this spec is called h3650_ts.c and can be found in the ../drivers/char directory in the http://www.handhelds.org/ CVS tree.
The calibration parameters are calculated by a separate calibration application. It uses the Itsy calibration paradigm. The touch screen sensor is assumed linear conforming to the equations of a straight line:
Xcal
= (xscale * Xraw) + xtrans
Ycal
= (yscale * Yraw) + ytrans
For increased accuracy xscale and yscale are multiplied by 256 and stored in the TS_CAL structure in the driver.
Xscale = xscale << 8
Yscale = yscale << 8
During conversion from raw to calibrated the reverse transformation is required.
Xcal
= ( (Xscale * Xraw) >> 8 ) + xtrans
Ycal
= ( (Yscale * Yraw) >> 8 ) + ytrans
Calibration information is held in the TS_CAL structure and is passed to and from the driver using the TS_GET_CALIBRATE and TS_SET_CALIBRATE ioctls.
#define
TS_SET_CALIBRATE _IOW(IOC_MAGIC,2,TS_CAL);
#define
TS_GET_CALIBRATE _IOW(IOC_MAGIC,3,TS_CAL);
The TS_CAL structure is used to convert raw touch screen coordinates (Xraw and Yraw) to calibrated touch screen coordinates (Xcal and Ycal) suitable for use with the X windows client.
typedef
struct {
int
Xscale; /*
Xscale = xscale << 8 */
int
xtrans;
int
Yscale;
/* Yscale = yscale << 8 */
int
ytrans;
int
xyswap;
}
TS_CAL;
The TS_SET_RAW_ON/OFF ioctl pair will switch between raw and calibrated data. The calibration application will instruct the driver to return only raw events using the TS_SET_RAW_ON ioctl and when calibrated the calibration application will switch the driver back to returning calibrated events using the TS_SET_RAW_OFF (Note 2)
#define TS_SET_RAW_ON _IO(IOC_MAGIC,0);
#define TS_SET_RAW_OFF _IO(IOC_MAGIC,1);
The H3600 calibration application can be found in ../apps/calibrate.c. This code is extensively commented and will explain how the Itsy calibration application works. Note is uses a device called /dev/h3600_tsraw to get raw data. This device may be replaced by the TS_SET_RAW_ON/OFF ioctls.