wstablet API proposal

["Jason Beaudoin" <jasonbeaudoin%gmail.com@localhost>]

hello there!

I've attached my design proposal for the wstablet API, and would love
to hear your thoughts and suggestions regarding it's development. In
the document I have outlined the wstablet API design and proposed a
set of changes to wscons that are needed to support the API.

Additionally, the section "Items in Question" (marked with an XXX)
details an area of the API that would benefit from community
discussion and input.

Feel free to browse through my CVS repository at:
 http://netbsd-soc.cvs.sourceforge.net/netbsd-soc/wscons/

Much of what is discussed here is in the works there, though not all lines match
up yet  :)


Magnificent thanks to my mentors:
 - S.P.Zeidler    | spz%serpens.de@localhost
 - Michael Lorenz | macallan%netbsd.org@localhost


Regards,
~Jason
-- 
401.837.8417
JasonBeaudoin%gmail.com@localhost

                                Abstract:

wstablet provides a known framework for (real) tablet hardware device drivers.
This allows users of the device to expect given data structures and
organization, as well as simplifying the nuances between different types of
hardware; it is easier to modify hardware drivers according to the available
capabilities, as opposed to requiring user programs to include support for
specific hardware. In other words, like the rest of wscons, wstablet will work
with device drivers, acting as the middleman between the parent device driver
and all users.

This document outlines the wstablet API design, and proposes a set of changes to
wscons that are needed to support the API. Additionally, the section "Items in
Question" (marked with an XXX) details an area of the API that would benefit
from community discussion and input.

Feel free to browse through my CVS repository at:
 http://netbsd-soc.cvs.sourceforge.net/netbsd-soc/wscons/

Much of what is discussed here is in the works there, though not all lines match
up yet  :)


Regards,
~Jason


Magnificent thanks to my mentors: 
 - S.P.Zeidler    | spz%serpens.de@localhost
 - Michael Lorenz | macallan%netbsd.org@localhost


--------------------------------------------------------------------------------


Current Tablet Capabilities:
(what do we need to support)

 . X/Y location
 . pen/mouse tilt, twist (rotation), and tip pressure
 . multiple styli and mice
 . stylus/mouse device ID
 . absolute and relative coordinate modes (implemented in software.. this allows
    for better tablet use as a mouse)


NOTE the context when using the term "device" (we've got the tablet device, as a
whole, but styli, mice, and other tablet instruments are also known as devices).


--------------------------------------------------------------------------------

                                Theory of Operation:

Similarities with wsmouse:

 . A wstablet device becomes a child device of the hardware driver that called
    it.

 . wstablet takes input from its parent hardware device, and builds an event
    queue that is then processed by wsevent and the rest of wscons. 

 . The basic aspects of device setup (initialization, attach/detachment, device
    printing, mux, etc) will be reused from wsmouse.

 . Following along with wscons, wstablet itself will be contained within two
    new files: wstablet.c and wstabletvar.h. Support for wstablet will then
    be added to the necessary wscons systems.

 . Buttons are numbered uniquely from 0-N (and there might be quite a few...)

 . wstablet will employ similar ioctls for reading the device type, as well as
   reading/writing factors for scaling, resolution, and calibration.


Differences with wsmouse:

 . wsmouse_input() takes a rather long argument list (xywz values as separate
    ints), wstablet will require a structure containing the values for
    wstablet_input() to fill the wscons_event array with. (There are many more
    values to be passed to wstablet..)

 . Switching between relative and absolute modes is now in the user's hands,
    through the wscons control interface (wsconsctl). Details regarding this
    work has not yet been explored, and will be examined in greater depth once
    the basic framework is in place.

 . There are now only two input event types, location and button events 
    (wsmouse has delta/absolute for x/y, etc). This difference is a result of
    the differences in processing device values from the hardware driver. These
    input event types will be defined in wstabletvar.h and used by the hardware
    device driver as part of passing input data to wstablet_input().

 . wstablet implements no button repeating

 . Buttons not associated with a device (stylus/mouse) are given the device ID
    of 0. This takes care of buttons on the actual tablet itself.


Hardware Driver Requirements:
 (what we want from our parent)

 . It is the responsibility of the hardware driver to workout any needed 
     conversions to provide meaningful values for wstablet.

 . When passing data to wstablet_input(), the tablet's current values for the
     *given device* will all be contained within the specified data structure. 
     (currently known as wstablet_tabdata, but I don't like this name, and it
     will be changed when I find something more pleasing).

 . Only one set of (current) values is allowed per device; event values must be
     from the originating stylus. This means that if multiple stylus devices 
are 
     being used simultaneously, the current event values passed to 
     wstablet_input() may only be grouped together by device, and separate
     devices will have separate calls to wstablet_input().

 . The event type must be specified when passing event data to wstablet_input().

 . If the hardware driver would like to support device IDs for separate styli,
     these values should be passed along with the current event values. ID 0 is
     reserved for unknown/unspecified/unsupported, or on the tablet. ID 1-N is
     then resolved by the hardware driver.

 . Normal set of attachment arguments and both access and callback functions.


--------------------------------------------------------------------------------


                        *XXX*  Items in Question:  *XXX*

 . The wscons_event structure (defined in wsconsio.h) currently has fields for
     the event's type, value, and time occured. To implement the full API spec,
     an additional field is required to support wstablet providing the ID of the
     device where the event originated (this field is currently named "dev_id"
     As this name might be a bit confusing, it might change). 

     Adding a field to wscons_event will break any code using the structure, and
     require a rebuild (including the Xserver and various packages that utilize
     wscons_event).

     Several known options to resolve this issue:
      . add the new field, break compatibility, require rebuilding
      . abusively hack the current fields we have
      . version the event structure, allowing for backwards compatibility


   ***  So what are your thoughts? ***

   Here are mine:
      . From my (inexperienced) perspective, adding the new field, rebuilding,
        and cleaning up any breakage, appears to be the cleanest and (arguably)
        more correct option. That said, I'm not sure how much breakage we'd be
        faced with - looks like a fair number of sizeof()'s - nor have I fully
        thought through how to deal with a system update (how can we avoid
        breakage when rebooting that new kernel?).

      . I'm not a huge fan of the hackery we might employ to use the existing
        fields of wscons_event, though I am not about to underestimate your
        clever abilities.

      . Versioning wscons_event doesn't seem like too bad of an idea, but it
        still seems a wee bit less straightforward than cleanly adding the new
        field explicitly.

      . We're adding new functionality here, new functionality sometimes breaks
        old code.. I don't see a problem as long as we fix and update that old
        code. The next logical question is then: is that possible?



--------------------------------------------------------------------------------

                                Other Details:


Event/Device types, and ioctl Definitions:
 (found in wsconsio.h)

** event types **

WSCONS_EVENT_TABLET_UP                  # button states
WSCONS_EVENT_TABLET_DOWN

WSCONS_EVENT_TABLET_MODE_REL            # which mode are we in?
WSCONS_EVENT_TABLET_MODE_ABS

WSCONS_EVENT_TABLET_X                   # x/y coordinates
WSCONS_EVENT_TABLET_Y

WSCONS_EVENT_TABLET_P                   # pressure and twist (rotate)
WSCONS_EVENT_TABLET_T

WSCONS_EVENT_TABLET_TILT_X              # x/y tilt
WSCONS_EVENT_TABLET_TILT_Y


** tablet types **

WSTABLET_GTYPE                          # ioctl to get tablet type
WSTABLET_TYPE_*                         # type definitions of different tablets


** wsmux **

WSMUX_TABLET


Other additions and modifications to wscons:

 . add support for WSMUX_TABLET to wsmux.c
 . add support for dev_id to the wscons event system
 . add wstablet support into files.wscons
 . sys/arch/files needs to know about wstablet
 . scaling and resolution (possibly calibration too) has not yet been resolved