ChorusOS man pages section 9DDI: Device Driver Interfaces

mouse(9DDI)

NAME

mouse- Mouse Device Driver Interface

SYNOPSIS

#include <ddi/mouse/mouse.h>

FEATURES

DDI

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

The mouse device driver interface defines the upper interface for mouse device drivers.

EXTENDED DESCRIPTION

Generic Properties

MOUSE_PROP_DEFAULT_CONFIG
MOUSE_PROP_RESOLUTION
MOUSE_PROP_SCALING_FACTOR
MOUSE_PROP_REPORTING_RATE

The MOUSE_PROP_DEFAULT_CONFIG property is mandatory. The value associated is a pointer to a MouseConfig structure which includes default values for non tunable configuration parameters.

typedef struct {
  int reportingRate;
  MouseReportingMode reportingMode;
  int scale;
  int resolution;
  } MouseConfig;

reportingRate indicates the maximum number of interrupts per second.

reportingMode specifies how the report is performed. The reporting mode can be specified with one of three constants:

MOUSE_CFG_REPORT_CONTINUOUSLY: Report continuously, as soon as the state changes.
MOUSE_CFG_REPORT_PERIODICALLY: Report periodically, at the rate controlled by reportingRate.
MOUSE_CFG_REPORT_PROMPT: Report only when requested.

Note that the client of the mouse driver should only be notified when the mouse state has changed.

The scale specifies the scaling factors.

The resolution is expressed in millimeters.

The value associated with the MOUSE_PROP_RESOLUTION property is a pointer to the MousePropResolutionRange:

typedef struct {
int min;
int max;
} MousePropResolutionRange;

The unit for min and max parameters is the number of mickeys reported for a move of one centimeter.

The value associated with the MOUSE_PROP_SCALING_FACTOR property is a 32-bit unsigned integer which specifies the maximum scaling factor supported by the mouse.

The value associated with the MOUSE_PROP_REPORTING_RATE property is a pointer on a MousePropReportRate:

typedef struct {
int min;
int max;
} MousePropReportRate;

Service Routines

The mouse device driver service routines are declared by the MouseDevOps structure shown below. A pointer to the mouseOps structure is exported by the driver via the svDeviceRegister microkernel call. A driver client invokes the svDeviceLookup and svDeviceEntry microkernel calls in order to obtain a pointer to the device service routines table. Once a pointer is obtained, the driver client is able to invoke the driver service routines (via an indirect function call).

#define MOUSE_CLASS "mouse"#define MOUSE_CLASS "mouse"

typedef enum {
  MOUSE_VERSION_INITIAL = 0,
  } MouseVersion;

typedef struct {
  MouseVersion version;
  KnError
  
  (*open) (MouseId dev_id,
    MouseConfig* dev_cfg,
    MouseCallBack* cbops,
    void* cookie);
    void
  (*mask) (MouseId dev_id);
    void
  (*unmask) (MouseId dev_id);
    void
  (*read) (MouseId dev_id, MouseEvent* event);
    void
  (*close) (MouseId dev_id);
  } MouseDevOps;

typedef struct { 
  MouseEventId mouseState;
  int x;
  int y;
  int z;
  } MouseEvent;

Obtaining communication with the device

The open call takes the following arguments:

dev_id: An identifier assigned to the device by the device driver.
dev_cfg: An identifier assigned to the device by the mouse client.
cbops: A pointer to a MouseCallBack structure which contains the set of functions exported by the mouse client of the device.
cookie: An identifier assigned to the device by the mouse client.

The open function is only invoked by the mouse client to start communication over the underlying mouse device, designated by the first argument dev_id. The device driver must record the cookie and the clientOps arguments in the structure it associates to the device in order to make further upcalls to the mouse client. cookie is the first argument in every function exported by the mouse client to the device driver.

The open function is always invoked at base level. The mouse client ensures the device is not opened again before having closed it.

Return value: K_OK if successful; K_EFAIL otherwise.

Masking attached interrupts

The mask call uses the MouseId dev_id argument.

The mask function disables the device's notification routine. The notification routine will not be called until the unmask function is called. When mask is called, the client must disable preemption to prevent the current thread being preempted with masked device interrupts.

For more information on the mask function, see the unmask section below.

Unmasking attached interrupts

The unmask call uses the MouseId dev_id argument.

The unmask function enables all device interrupts (that is, input, output and special) . Typically, the mask/unmask pair would be used by the driver client to implement a critical section of code which is synchronized with the call-back handlers. The mask/unmask pair must not be called by the call-back handlers because the interrupts are already masked when a call-back handler is invoked. The mask/unmask pair must not be nested.

Obtaining device state

The read call takes the following arguments:

MouseId: dev_id
MouseEvent*: event

This function is used to read a mouse event. read initializes the structure MouseEvent with values describing the event and the state (the coordinates) of the mouse since reporting of the last event. This function can be used directly when the mouse does not work in interrupt mode (for example, in MOUSE_REPORT_PROMPT). In other cases, the read function must be invoked within a mask/unmask section.

The event of a MouseEvent can be:

MOUSE_LEFT_BUTTON_DOWN
MOUSE_RIGHT_BUTTON_DOWN
MOUSE_CENTER_BUTTON_DOWN
MOUSE_BUTTON4_DOWN
MOUSE_BUTTON5_DOWN
MOUSE_BUTTON6_DOWN
MOUSE_BUTTON7_DOWN
MOUSE_BUTTON8_DOWN

The state of the mouse, mouseState, is defined by:

x: The horizontal coordinate relative to the last report.
y: The vertical coordinate relative to the last report.
z: The depth coordinate relative to the last report.

Releasing the device

The close call takes the following argument:

device_id: The identifier assigned to the device by the device driver.

The close function tells the mouse driver that the device is no longer used by the client. The close function must stop the mouse device gracefully. In particular, it must disable all device interrupts. The close function must ensure that all functions exported by the mouse client will no longer be invoked after it returns to the client.

The close function is only invoked once after a successful invocation of open for the same device. The close function is always invoked at base level. The close function is invoked in mutual exclusion with all other functions exported by the device driver on the same device. The mouse driver client guarantees that all other functions exported by the device driver will never be invoked again (on the same device) after it has invoked close.

The set of functions exported by the mouse client is represented by the MouseCallBack structure. A pointer to this type of structure is provided to the mouse driver by the mouse client as an argument of the open function:

typedef struct MouseCallBack {
  void
  (*event_notify) (void* cookie,
  MouseEvent* event);
  } MouseCallBack;

eventnotify notifies the client of an event which has occurred, with the arguments:

cookie: the client cookie specified in open()
event: specifies an event.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving