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 - Michael Lorenz | macallan@netbsd.org -------------------------------------------------------------------------------- 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