Uniform Input Device Interface for MicroWindows
Version 0.01 - Feb 29, 2000

Purpose

This document defines a simple interface for input devices such as Mouse, Touch Screen, Kbd and Timers to be used by MicroWindows.

It is meant to be used on embedded systems and RTOS where a device driver model, may or not exist, and/or for performance reasons, it mighr be needed to have the ISRs posting messages directly to the queue used by this interface.

Also, using a generic interface, such this one, one would avoid writing any new MicroWindows drivers, as long as the kernel ( RTOS ) used would provide the functions defined by this interface.

Let's list a few good reasons to have a simple interface such this one:

Architecture

The architecture of the interface is very simple, and it uses a global queue ( FIFO ) as a concentrator of messages from several sources ( devices ). The unique contract between MicroWindows driver interface and the physical devices, it is the message used to describe each event ocurred. The message format will be discussed later in this document.

Whenever a device needs to post one new message to MicroWindows, such as a keystroke or a mouse move, it should write a message to the global queue. Yes, it is that simple.

The figure below shows how it works.





Input Queue



It is responsibility of MicroWindows to establish( create ) the global queue and somehow indicate to the devices to start posting messages to it.

Message Format

The messages between the devices and the application ( MicroWindows ), it is pretty standard, and it has a type to indicate the source of the message and a body with the content of the message.

/*
 * Message generated by input devices controlled by MicroWindows. 
 */
struct MW_UID_MESSAGE
{
  enum MW_INPUT_DEVICE_TYPE type;  /* device type */
  union
  {
     /* fired when keyboard events are raised */
     struct kbd_t {
        unsigned short keycode;     /* code represeting the key   */
        unsigned short modifiers;   /* modifiers for the keys     */
    } kbd;

    /* fired when position events are raised, mouse, touch screen, etc */
    struct pos_t {
        unsigned short btns; /* indicates which buttons are pressed */
        short x;             /* x location */
        short y;             /* y location */
        short z;             /* z location, 0 for 2D */
    } pos;

    /* fired by a timer device periodically */
    struct timer_t {
        unsigned long  frt;   /* free running timer */
        unsigned long  seq;   /* sequence number */
    } tmr;

  } m;
};

The devices supported are:

API Wrapper - Specification


/*
API for creating/closing/accessing the message queue used by the micro
input device interface. All functions of this interface returns a 
zero ( 0 ) on success. One exception for that is the "read" routine
that returns the number of bytes read. 
Negative numbers indicate errors on reads.

The implementation of the message queue for RTEMS uses a POSIX message
queue. It should be very portable among systems with POSIX support.
*/

/* creates the message queue that holds events from the input devices */
extern int uid_open_queue( const char *q_name, int flags, size_t max_msgs );

/* closes message queue */
extern int uid_close_queue( void );

/* 
 * reads a message from the queue. It waits up to the specified 
 * timeout in mili-seconds.
 */
extern int uid_read_message( struct MW_UID_MESSAGE *m, unsigned long timeout );

/* write a message to the queue */
extern int uid_write_message( struct MW_UID_MESSAGE *m );


/* register device to insert data to the queue */
extern int uid_register_device( int fd, const char *q_name );

/* unregister device to stop adding messages to the queue */
extern int uid_unregister_device( int fd );

MicroWindows Drivers -- Kbd and Mouse

This section provides a reference implementation. This code was used as a first implementation for RTEMS. A simple driver is provided along with a GsSelect() function to match the MicroWindows driver model.

TODO

Contributors