ChorusOS man pages section 9DDI: Device Driver Interfaces

keyboard(9DDI)

NAME

keyboard- Keyboard Device Driver Interface

SYNOPSIS

#include <ddi/keyboard/keyboard.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 keyboard device driver interface (asynchronous mode) defines the upper interface for keyboard device drivers.

EXTENDED DESCRIPTION

Generic Property

KEYBOARD_PROP_CONFIG

The KEYBOARD_PROP_CONFIG property is mandatory and it is a pointer to a Keyboard-Config structure:

typedef struct {
  int initialRepeatDelay;
  int repeatDelay;
  } KeyboardConfig;

initialRepeatDelay: When character repeating is supported by the hardware, this parameter specifies how long a key must remain pushed before the keyboard starts to send a continuous stream of characters. The unit is a millisecond.
repeatDelay: This parameter sets the delay between two characters when the keyboard operates in repeat mode. The unit is a millisecond.

Generic Type

typedef enum {
  KEYBOARD_VERSION_INITIAL = 0
  } KeyboardVersion;

#define KEYBOARD_CLASS "keyboard"

typedef uint32_f ScanCode;

The ScanCode is defined to support up to 32 bit scancodes. Note that the content of ScanCode is keyboard dependent, so the client of the driver must know the kind of keyboard device serviced by the driver.

Generic Callback

typedef struct KeyboardCallBack {
void
(*scan_code_receive) (void* cookie);
} KeyboardCallBack;

scan_code_receive notifies the client that a scancode is available for reading.

This call takes the following arguments:

cookie: The client cookie specified in open.
event: Specifies an event.

The scan_code_receive up-call is invoked with masked device interrupts. Typically, the scan_code_receive up-call is issued from the interrupt level. This function is invoked by the keyboard driver for each scancode sent by the keyboard.

Service Routines

typedef struct KeyboardDevOps {
KeyboardVersion version;
KnError
(*open) (KeyboardId dev_id,
KeyboardConfig* dev_cfg,
KeyboardCallBack* cbops,
void* cookie);
void
(*mask) (KeyboardId dev_id);
void
(*unmask) (KeyboardId dev_id);
Bool
(*scan_code_get) (KeyboardId dev_id, ScanCode* scanCode);
void
(*code_send) (KeyboardId dev_id, uint32_f command);
void
(*close) (KeyboardId dev_id);
} KeyboardDevOps;

Obtaining communication with the device

The open call takes the following arguments:

dev_id: Device identifier.
dev_cfg: Structure specifying the keyboard configuration.
cookie: Passed back to the client when a client call back handler is invoked.
cbops: Client call back handlers.

The open call returns the following:

K_OK: Specifies that the line is successfully initialized.
K_EFAIL: Specifies that the line cannot be initialized with the given configuration (that is, the specified repeat rate is not supported).

open must be the first call to the device driver. When K_OK is returned, open puts the device into an interrupts-masked state. In order to start the device (enable interrupts), the unmask down-call must be invoked.

Note that the driver is supposed to be single-client; the client must not try to open the device again before calling close.

Masking attached interrupts

The mask call takes the following argument:

dev_id: Device identifier.

The mask function disables ScanCode notification from the device. 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 takes the following argument:

dev_id: Device identifier.

The unmask function enables the scanCode notification (scan_code_receive() call back). Typically, the mask/unmask pair would be used by the driver's 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.

Receiving from the device

The scan_code_get call takes the following arguments:

dev_id: Device identifier.
scanCode: Points to a scancode.

If one scancode has been received, the function returns 1 and initializes the data pointed to by the scanCode with the received scanCode. Otherwise it returns 0 and does not initialize the data pointed to by scanCode parameter. Note that scan_code_get must be invoked while interrupts are masked.

Sending to the device

The code_send call takes the following arguments:

dev_id: Device identifier.
command: Keyboard command parameter.

This method is used to send commands to the keyboard. The command is keyboard dependent. The code supported by a given keyboard must be specified by the client of the driver. For instance, this method can be used to switch LEDs on and off.

Releasing the device

The close call takes the following argument:

dev_id: Device identifier.

The close down-call releases the keyboard device. The close function must be called in the masked state. In other words, the mask down-call must be issued before the close down-call.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving