Chapter 5. USB Message System
Prev | RISC OS USB Device Drivers | Next

## Chapter 5. USB Message System

## 5.1. Introduction

The messaging system replaces the reliance on service-calls to propagate most of the change information around the system.

A driver may send messages using USB_MsgSend (SWI&55398), this is available to any driver. A module driver may also choose to register a message handler with the USB core to receive messages.

All messages have a class (Table D.1), which indicates what data the message contains and the data payload. The handlers can indicate which types of message they are interested in, so that they are not called for irrelevant information.

Current message classes are listed in Appendix D. Drivers should be prepared to silently ignore all messages they do not understand, as the class codes may be extended at a later date.

## 5.2. Sending Messages

To send a message call USB_MsgSend (SWI&55398) with the message. Messages are defined in Appendix D. The usbmsg_send can be used from the C API. The returned value will be 0 if the message was unclaimed or a value returned by the claiming handler.

## 5.3. Receiving Messages

Any driver wishing to receive messages using the USB messaging system must provide and register at least one message handler. This is a routine which will be executed by the USB system to deliver messages to the application. It should be noted that the routine is executed in the context of the USB system and a crash in this routine will most likely render the whole USB system unusable. Hence, this routine should be robust and not block execution for an extended period of time.

The routine is called with a pointer to a message and the private word that it was registered with. The handler will be called once for each message to be delivered. The handler may either return 0 to allow the message to propagate to another application or a value which will stop further processing of the message and return the value to the caller of USB_MsgSend (SWI&55398).

Registering a handler is done by calling the USB_MsgOp (SWI&55399) with the USB_MSGOP_REGISTER reason code, the address of the message handler and a value to be passed to the handler on each call. This may also be achieved by using the usbmsg_register_handler C API call.

De-registering a handler is done by calling the USB_MsgOp (SWI&55399) with the USB_MSGOP_DEREGISTER reason code and the values of message handler and private word passed to the register call. This may also be achieved by using the usbmsg_deregister_handler C API call.

Setting a filter based on message class is done by calling USB_MsgOp (SWI&55399) with the USB_MSGOP_FILTER reason code, the values of message handler and private word used to register the handler, the message class and a flag to indicate either the setting or clearing of the filter. This may also be achieved using the usbmsg_filter C API call.

A special case filter can be applied which prevents the reception of all messages. This is useful for either temporary suspension of message reception or filtering of all but one or two message classes. This is achieved by calling USB_MsgOp (SWI&55399) with the USB_MSGOP_FILTERALL reason code, the values of message handler and private word used to register the handler. This may also be achieved by using the usbmsg_filterall C API call.

## 5.4. Service Calls Replaced

Some service calls have been superseded by the messaging system.

SERVICE_USB_HUB_EVENT has been replaced with Section D.1.

SERVICE_USB_POWER_CAP has been replace with Section D.2

## 5.5. Message Memory Layout

The messages memory layout is dependent on their class. The class is stored in the first word of the passed message block and the class dependent data after that.

Prev | Up | Next
Chapter 4. Endpoints and Pipes | Home | Chapter 6. Data Buffers