Hi,
I attach my first cut of a generic touch screen driver specification as promised
from my earlier email.
This specification is based around my experience with the Compaq iPAQ H3600 touch
screen driver, however I have tried to make it as generic as possible for all
Linux platforms.
If nothing else I hope it will at least start the ball rolling in the quest to
gain consensus on what a generic touch screen driver will eventually look like.
I will also put this spec in html format on the www.handhelds.org web site.
Since there has also been some interest in the [EMAIL PROTECTED] mailing
list I will post it in both lists for now with a view to maybe moving the
discussion to one (which one?) of the lists.
Regards
--Charlie
+++++++++++++++++++++++++++
MAJOR NUMBER
--------------------
(TBD)
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.
DEVICE NODES and MINOR NUMBERS
----------------------------------------------
/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.
TOUCH SCREEN EVENT STRUCTURE (TS_EVENT)
-----------------------------------------------------------
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 touch screen 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 */
/* any more ? */
} TS_EVENT;
USER LEVEL FILE OPERATIONS
--------------------------------------
In addition to open(), close() and ioctl() functions, blocking and non-blocking
reads and asynchronous notification (SIGIO) should be supported at the user
level. The select/poll mechanism will be used for non-blocking reads.
See the EXAMPLES section for pointers to example code on the above functions.
KERNEL LEVEL FILE OPERATIONS
------------------------------------------
The following file operations pertain to device /dev/ts.
_read()
Blocking reads will block until a complete TS_EVENT structure (see below) can be
returned.
_fasync()
Will send a 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 from the driver, 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 (if adopted in user space) will have it�s own ioctls
(see CALIBRATION section).
The ioctl command numbers should be �mangled� using the _IO,_IOW,_IOR,_IOWR
macros as defined in <linux/ioctl.h>
A �magic number� of �?� should be used (see CALIBRATION section)
TOUCH SCREEN EXAMPLE CODE
------------------------------------------
The following example code can be found in the ../apps/h3600_test directory in
the 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 specification is called h3650_ts.c and
can be found in the ../drivers/char directory in the handhelds.org CVS tree.
CALIBRATION
------------------
(This section assumes the calibration mechanism will be an application)
The (H3600) 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 = mxXraw + Cx
Ycal = myYraw + Cy
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).
typedef struct {
int xscale;
int xtrans;
int yscale;
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);
TOUCH SCREEN CALIBRATION APPLICATION EXAMPLE CODE
-----------------------------------------------------------------------------
The H3600 calibration application can be found in ../apps/ts_calibrate.c in the
handhelds.org CVS tree. 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 superceded by the
TS_SET_RAW_ON/OFF ioctls.
Notes
1. Some systems return pressure as a value between 0 and xxxx which is used to
determine the pen status (UP or DOWN). The Compaq iPAQ H3600 just returns
pressure=0 (UP) or pressure=1 (DOWN). If UP then X and Y coordinates are set to
�1. Should this member variable be called something else?
2. The Compaq H3600 driver does not use this mechanism at present.
+++++++++++++++++++++++++++
Charlie Flynn wrote:
> Hello,
>
> My name is Charlie Flynn and I have just completed V1.0 of a touch
> screen driver for the Compaq iPAQ H3600 running Linux 2.4.0-test1.
>
> I was thinking it would be a good idea if we had a generic interface to
> the touch screen drivers of all Linux SA11x0 platforms.
>
> This would allow clients ( such as the X windows device dependent layer
> ) to work, without modification, with all Linux SA11x0 touch screen
> drivers.
>
> I know it's a bit late to ask this ;-) but is there already a document
> describing a generic TSD interface for these platforms?
>
> Assuming there isn't such a document and also assuming people think it's
> worth pursuing I can start the ball rolling by posting a draft spec to
> the linux-arm-kernel mailing list which I assume would be the most
> appropriate place to discuss this issue.
>
> Regards
> --Charlie
>
> unsubscribe: body of `unsubscribe linux-arm' to [EMAIL PROTECTED]
> ++ Please use [EMAIL PROTECTED] for ++
> ++ kernel-related discussions. ++
unsubscribe: body of `unsubscribe linux-arm' to [EMAIL PROTECTED]
++ Please use [EMAIL PROTECTED] for ++
++ kernel-related discussions. ++
