Search this site


Metadata

Articles

Projects

Presentations

new moused modules guide - Developer guide to writing modules for new moused

Abstract

Mouse modules are simply userland drivers that translate raw data from hardware devices. Modules are standalone, and require little more than knowledge of how to understand the mouse to write.

Includes

First thing, you'll need to include a few header files:
#include <sys/types.h>
#include <sys/mouse.h> /* May not be needed */
#include <moused.h>

/* If you need to use the ps2 library: */
#include <ps2.h>
Those should get you started.

The rodent_t Structure

The rodent_t structure has many members of interest to you:
char *device
The path of the mouse device
int mfd
The file descriptor of the mouse device
char *packet
Buffer for storing packets. Dynamically allocated based on rodent_t.mode.packetsize
int (*update)(struct mouse_info *t)
Function to call when pushing movement updates

Function Overview

For every MOUSE_*_FUNC functin, you can expect to be passed a rodent_t pointer.

The following functions exist:
MOUSED_INIT_FUNC
Used to initialize your mouse module. Perform any necessary configuration and other setup here. Do NOT probe mice.
MOUSED_PROBE_FUNC
Probe the given mouse for functionality. This function should be used to test if the mouse we have opened is somethin we can handle.
MOUSED_HANDLER_INIT_FUNC
Initialization function called before the main loop of moused is entered. Do NOT probe mice. This function should be used to prepare data structures before the main loop is run.
MOUSED_HANDLER_FUNC
This is called every time a packet is available for reading from the mouse. It is up to you to read data from the mouse.

Initialization

The init function is declared like this:
MOUSED_INIT_FUNC {
	/* Initialization code here */
}

Probe

This function should test the mouse for features. That is, you should test the mouse device (however necessary) to check if it is the kind of mouse your module supports.

For instance, the synaptics module tests the ps/2 mouse by attemptig an extended status request. If this fails or otherwise indicates that no synaptics device is present, then it is clearly not a synaptics mouse, and we should fail.

The following return values are expected:
MODULE_PROBE_FAIL
Indicates that mouse type tests failed, and to not use this module
MOUSE_PROBE_SUCCESS
Indicate successful mouse probe. This mouse can be handled by this module

Handler Initialization

Last-minute changes to any data needed before the moused main loop is entered. This includes things such as setting expected packet size (In ps/2 drivers), enabling magic features such as Absolute mode (for synaptics).

PS/2 drivers should set the following at this point:
  • sync mask
  • packet size (don't forget to update rodent->mode.packetsize)
  • ps2_enable_stream(), if necessary

Handler Function

The handler function is expected to read one "packet" of data per function call. That is, only process one piece of mouse activity per call.

A typical order of operations is:
  • Read a packet
  • Check for proper byte length (if necessary)
  • Parse the packet for mouse data
  • Set values in a mouse_info_t variable
  • Call rodent->update(&(mouse_info_t variable))

Summary

Modules are meant to be simple to write. All you need to care about is understanding the raw mouse data and push movement deltas up through moused with the update function..