=09As this was sent to the generic 'handhelds' rather than the
=09specific 'handhelds-linux' lists, I though it might be of some
=09interest - maybe even towards trying to have a similar interface
=09for NetBSD...

=09=09David/absolute
=09=09=09=09       -- www.netbsd.org: No hype required --

---------- Forwarded message ----------
Date: Mon, 10 Jul 2000 22:43:55 +1000
From: Charlie Flynn <flynn@ozy.dec.com>
Reply-To: handhelds@handhelds.org
To: linux-arm@vger.rutgers.edu, handhelds@handhelds.org
Subject: [Handhelds] Re: Touch Screen Driver Generic Interface for all
    Linux SA11x0 platforms.

Hi,

I attach my first cut of a generic touch screen driver specification as pro=
mised
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 a=
ll
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 l=
ike.

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 handhelds@handhelds.org mail=
ing
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 proce=
dure
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
=2E./linux/Documentation/devices.txt.

TOUCH SCREEN EVENT STRUCTURE (TS_EVENT)
-----------------------------------------------------------

This is the structure contains the X and Y pixel coordinates of a single to=
uch
screen event. It is passed from the driver to the user by the read() functi=
on.

typedef struct {
    short pressure;    /* used to determine if the touch screen pen is UP o=
r
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-bloc=
king
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 function=
s.

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) c=
an be
returned.

_fasync()
Will send a SIGIO to user when there is an event to report. An event is def=
ined
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=92s init_module() or equ=
ivalent.

The calibration application (if adopted in user space) will have it=92s own=
 ioctls
(see CALIBRATION section).

The ioctl command numbers should be =91mangled=92 using the _IO,_IOW,_IOR,_=
IOWR
macros as defined in  <linux/ioctl.h>
A =91magic number=92 of =91?=92 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=
=2E
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=
=2E

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 =3D mxXraw + Cx
Ycal =3D myYraw + Cy

Calibration information is held in the TS_CAL structure and is passed to an=
d 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 dat=
a. 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 wil=
l
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=3D0 (UP) or pressure=3D1 (DOWN). If UP then X and Y coordinates ar=
e set to
=961. 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 majordomo@vger.rutgers.ed=
u
> ++        Please use linux-arm-kernel@lists.arm.linux.org.uk for         =
  ++
> ++                        kernel-related discussions.                    =
  ++

_______________________________________________
Handhelds mailing list
Handhelds@handhelds.org
http://handhelds.org/mailman/listinfo/handhelds