This page describes the second version of the XenMou protocol. While the first version supported an absolute mouse pointer, this second version is designed to be more flexible, and support a variety of different types of input device, including a mulitouch tablet screen.
As before, XenMou is a PCI device which may be present at any BDF in the system. The Xen PCI Vendor ID 5853 and Device ID C110 will be assigned for this device. It will be an Input Device Class, Mouse Subclass (0x0902).
The device can generate an interrupt.
This PCI device contains 1 BAR: BAR0 is non prefetchable memory of 8k+ bytes (3+ pages) containing MMIO registers and mouse event data.
The pages in BAR0 contain a page for Global registers, one or more pages for event data, and a final page containing a device configuration space. These three sections are described in the three sections below.
Global Registers (Range 0x00000 - 0x00FFF)
The global registers control features of the xenmou adapter that reflect the entire device.
0x00000 - XMOU_MAGIC
Type: Read-Only
Magic number. This register always reads 0x584D4F55
0x00004 - XMOU_REV
Type: Read-Only
Revision number of the back end. This register reads 0x1 until XMOU_CLIENT_REV has been written too, after which it returns it true version (0x2 as of writing). This value should not be used as an indicator of compatibility, as newer versions may be backwards compatible. Please refer to XMOU_CLIENT_REV for use in version compatibility checking.
0x00100 - XMOU_CONTROL
Type: Read-Write
Control register to change backend settings.
Bit 0: XMOU_EN Set to enable the xenmou device. Bit 1: INT_EN Global bit to enable interrupts from the device. Bit 2: MOU_V2 This is no longer supported. It use to enable version 2 of the xenmou protocol. XMOU_CLIENT_REV should be used instead. Bits 3 - 31: Unused.
0x00104 - XMOU_EVENT_SIZE
Type: Read-Only
Size in bytes of the individual event data structures in the event register range.
0x00108 - XMOU_EVENT_NPAGES
Type: Read-Only
Number of pages that make up the the event register range.
0x0010C - XMOU_ACCELERATION:
Type: Write-Only
Not used.
0x000110 - XMOU_ISR:
Type: Read-Only
Interrupt status register. Write to dismiss interrupt.
Bit 0: INT Indicates if this device is currently generating an interrupt. Bits 1 - 31: Unused.
0x00114 - XMOU_CONF_SIZE
Type: Read-Only
This returns the size, in bytes of the XenMou device configuration record (described later under #Device_configuration_space). This value should be used when indexing the array of these records, in place of the size you expect the record to be. This is to allow for expansion, and failing to do so may result in compatibility issues.
0x00118 - XMOU_CLIENT_REV
Type: Read-Write
This should be set on start up, to the version of XenMou spec you expect to use. If not set, the xenmou back end will follow the xenmou version 1 spec. Once you have written the spec version number (0x2 as of writing), you should read this register back. If the value read is not that which was written, then this indicates a fail condition. Reading 0 indicates that the version was rejected, a newer version of the spec may need to be adhered to. Note that newer versions of the back end may still support older versions of the spec - but not necessarily all versions. This register may only be written to before XMOU_EN of the control register, has been enabled. Attempts to change the protocol version, while enabled, will be ignored.
Event Registers (Range 0x01000 - 0x0nFFF)
The event registers occupy XMOU_EVENT_NPAGES pages of 4096 bytes. There are (PAGE_SIZE/XMOU_EVENT_SIZE - 1) individual event data structures per page. The individual event data structures are each XMOU_EVENT_SIZE bits in size (XMOU_EVENT_SIZE is always 64 or greater bits). The first event data structure on the first page is unique in that it holds the read and write pointer indexing into the other event data structures.
0x01000 : XMOU_READ_PTR:
Type: Read-Write
Current read offset index to the next event data structures to read (in XMOU_EVENT_SIZE units).
0x01004 : XMOU_WRITE_PTR:
Type: Read-Only
Current write offset index to the event data structures one beyond the last one written to (in XMOU_EVENT_SIZE units).
0x01000 + (XMOU_EVENT_SIZE) : Event Record Queue
Type: Read-Only
The event registers data structures starting at (0x01000 + XMOU_EVENT_SIZE) form a logical ring spanning XMOU_EVENT_NPAGES pages. The offset pointers above are indices into the ring. If the write pointer is less than the read pointer then the ring has wrapped. When the read pointer is not equal to the write pointer, there are events to read. The pointers being equal always means there are no events to read, that is read == write never means that the ring is full with (PAGE_SIZE/XMOU_EVENT_SIZE - 1) events. A full ring will have a maximum of (PAGE_SIZE/XMOU_EVENT_SIZE - 2) events in it. The ring may wrap at this point, controlled by the underlying virtual HW. When events have been consumed, the xenmou driver software moves the read pointer forward up to the write pointer. Driver software never moves the write pointer. A interrupt is generated when events need the read from the buffer - this is when a SYN_REPORT event (described later) is added. The event record format is described in the next section.
Event Records
Each of the event records are formatted in the following manner:
uint16 type // Type of record, including KEY (key/button), REL (relative scalar), ABS (absolute scalar), SYN (Synchronization events.) or DEV (Device change events). uint16 code // This indicated which item (be it a key or axis) this record represents. uint32 value // This is the new value for the item indicated by two field above. For a button or key, this would be a Boolean.