Chapter 7. Waiting
Prev | RISC OS USB Device Drivers | Next

## Chapter 7. Waiting

## 7.1. Introduction

When processing a transaction the USB system allows for several methods of informing the driver of its completion. This allows either synchronous or asynchronous transaction processing. Hence a driver does not need to block waiting for a transaction to complete and other processing may be done.

The USB system provides several different waiting modes in order that a each driver writer does not need to implement them itself.

## 7.2. Usage

The driver creates a waiting structure filling in the required mode value and associated data fields for that mode. This structure may be statically allocated and reused as required in any number of transactions. The USB system will inform the driver when the transaction has completed and the driver must then check the transactions completion status using USB_RequestGetState (SWI&55390) or the C A.P.I. function usb_request_get_state see Chapter 8 for more details on this.

There are six waiting modes each taking parameters as appropriate for the completion action (see Table A.9 for constants).

Any mode that specifies an action will have that action executed in either user or call-back context and should be prepared to adhere to the restrictions imposed by RISC OS.

## 7.3. Waiting Modes

### 7.3.1. Return

This mode is used for non-blocking style transactions where the driver will check for the transaction completion using USB_RequestGetState (SWI&55390). It is the responsibility of the driver in this mode to find the completion state of a transaction as the USB system will provide no other notification.

This mode is selected by placing WAITING_TYPE_RETURN in the mode field of the waiting structure. It takes no further parameters.

### 7.3.2. Blocking

This mode is used for blocking until a transaction completes. Execution will not return to the driver until the transaction request is complete.

This mode is selected by placing WAITING_TYPE_LOOP in the mode field of the waiting structure. It takes no further parameters.

### 7.3.3. Wimp Poll

This mode will not return execution to the driver until the transaction is complete but will ensure other WIMP applications still run. This mode is intended for use with application drivers running in task windows.

This mode is selected by placing WAITING_TYPE_POLL in the mode field of the waiting structure. It takes no further parameters.

### 7.3.4. Wimp Message

This mode returns execution to the driver and will send a specified WIMP message upon transaction completion. This is intended for use with WIMP based application drivers.

This mode is selected by placing WAITING_TYPE_MESSAGE in the mode field of the waiting structure. The waiting structure must have three additional parameters set. A pointer to a standard WIMP user message which must be in memory accessible from any context i.e. RMA or a dynamic area. A destination specified with a WIMP task and icon handle.

### 7.3.5. SWI

This mode will return execution to the driver and will call a specified SWI with a supplied set of registers upon transaction completion. The SWI used is called in a call-back context and hence only SWIs valid in such a context should be used i.e. not change processor mode. Any results from the SWI will be discarded and therefore the SWI may corrupt R0 to R9.

This mode is selected by placing WAITING_TYPE_SWI in the mode field of the waiting structure. The waiting structure must have two additional parameters set. The number of the SWI to call and an array of 10 values to be used as R0-R9 when calling the SWI.

### 7.3.6. APCS

This mode will return execution to the driver and call the supplied APCS function upon transaction completion. The function will be called with the specified register contents for R0 to R3, R14 will be the return address and R13 will contain a valid full descending stack.

This mode is selected by placing WAITING_TYPE_SWI in the mode field of the waiting structure. The waiting structure must have two additional parameters set. The address of the function to call. The array of four values to be used as R0-R3 then calling the function.

The function will be called in a call-back context and should ensure it adheres to the limitations of this context. It is allowed to corrupt R0-R3 on exit and must preserve all other registers. See ARM Procedure Call Standard(APCS) for more details.

Prev | Up | Next
Chapter 6. Data Buffers | Home | Chapter 8. Transactions