Appendix A. Constants
Prev | RISC OS USB Device Drivers | Next

## Appendix A. Constants

The USB system has numerous constant values, these are represented here in various tables, grouped by their general use. These tables are referenced from elsewhere in the document and are also represented in the C API headers.

## A.1. Error Codes

Table A.1. Error codes used by the USB system

Error code | Error | Description
--- | --- | ---
0 | USB_RESULT_OK | All OK. Operation performed successfully
&819B00 | USB_RESULT_ALIAS_FILE_NOT_FOUND | Alias File could not be opened
&819B01 | USB_RESULT_STRUCTUR_DROPPED | Operation could not be executed because it tried to use a structure which has been dropped. Don't use the structure any longer and release every references to it.
&819B02 | USB_RESULT_INVALID_PARAMETER | Wrong parameter passed to function
&819B03 | USB_RESULT_CONTROLLER_ALREADY_EXISTS | Can occur at usb_controller_register if a controller gets the same name by translation process of the alias file as a controller which has been already registered. Will be the case if you plug in two controllers into your system and did not assign names to them inside alias file.
&819B04 | USB_RESULT_BUS_INVALID_INTERNAL_2 | Should never occur. Internal invalid state was detected by USB-Module. Please inform developer about this.
&819B05 | USB_RESULT_ILLEGAL_SPEED | Either USB Host Controller is not supporting this speed or the speed is illegal in conjunction with the selected USB-Transfer type
&819B06 | USB_RESULT_ALL_DEVICES_USED | All device addresses are in use however.
&819B07 | USB_RESULT_DEVICE_ADDRESS_USED | A device address should used for new device which is already in use.
&819B08 | USB_RESULT_ENDPOINT_ADDRESS_USED | An endpoint address is already in use. May be used as a standalone and shall be used in both direction or may be in both directions and shall be used in a single direction.
&819B09 | USB_RESULT_INVALID_PIPE_STATE | Occurs if an operation shall be done on a pipe and this pipe does not have the correct state (E.G. not open but a request shall be started)
&819B0A | USB_RESULT_NO_TRANSACTION_PENDING | Only used by usb_transaction_get_pending function to inform the USB Host controller driver that no transactions are pending.
&819B0B | USB_RESULT_ERROR_GENERATED | Used by usb_transaction_result to inform the USB Host controller driver that the transaction result has been changed internally by the USB-Module into an Error.
&819B0C | USB_RESULT_NO_OBJECT_FOUND | Used by usb_find_object to inform the caller that the requested object could not be found.
&819B0D | USB_RESULT_BUS_CAPACITY_TO_SMALL | Not enough USB capacity at opening a pipe.
&819B0E | USB_RESULT_BUS_INVALID_PAYLOAD_SIZE | Maximal data payload size for an endpoint must be one value of 2^x and 0<=x<=10. If not this error will be generated by usb_endpoint_register.
&819B0F | USB_RESULT_BUS_INVALID_TRANSFER_TYPE | Shows illegal transfer type at usb_endpoint_register. That means that you either selected an invalid transfer type or that the actual host controller is not supporting this type. In all other situations it shows an heavy internal error. Please inform developer about this.
&819B10 | USB_RESULT_BUS_INVALID_INTERNAL_1 | This error should never occur. Please contact Simtec Electronics for further assistance.
&819B11 | USB_RESULT_NOT_ENOUGH_MEMORY | Unable to claim a piece of memory

## A.2. Transaction constants

Table A.2. Transaction behaviour flags

Bit | Definition | Value | Description
--- | --- | --- | ---
0 | USB_TRANSACTION_EXACT_SIZE | 0 | Reading: You can receive an arbitrary number of bytes up to the value of the URB used_size field. Writing: Zero length transactions will not be issued.
1 | The Term "exact buffer size" is used here with a different semantic to that of the USB specification. Device to Host: An error is generated if the device attempts to transfer a different number of bytes to that required in the URB. Host to Device: For setup transactions this will generate a zero length transfer at the end of the transaction if the length of the data URB is zero or a multiple of the packet size.
1 | USB_TRANSACTION_FRAME_START | 0 | Transaction will commence as soon as possible.
1 | Frame start number is given and the transaction will commence processing on or after the specified frame.
2 | USB_TRANSACTION_SETUP_EVAL (Currently Unsupported) | 0 | Setup buffer is not evaluated by the USB system. (currently only valid value).
1 | Setup buffer is evaluated by the USB system. This is intended for future support so the USB system may track changes to the device configuration and setup. It is currently the drivers responsibility to ensure that any changes modify the relevant system state.
3 | USB_TRANSACTION_STATUS_STAGE | 0 | Normal transaction behaviour.
1 | This flag must be set for control transactions to enable the use of the second URB. This also enables the second "data" phase of control transactions. This also implicitly sets USB_TRANSACTION_EXACT_SIZE to ensure the correct sequence of transfers occur.
4 | USB_TRANSACTION_TIMEOUT | 0 | Normal transaction behaviour.
1 | When set this allows the driver to specify the maximum number of centiseconds it is prepared to wait for a transaction, this is not affected by waiting mode. The transaction will be terminated with a USB_TRANSACTION_RESULT_TIMEOUT.
5 - 29 | Reserved | 0 | Reserved must be zero.
30 | USB_TRANSACTION_REQUEST_FIRST (Internal use only - Must be zero) | 0 | Transaction is not the first in a request. This blocks any other transaction at this endpoint to be notified as pending until it is removed from the pending queue by using a special function.
1 | Transaction is the first one in a request.
31 | USB_TRANSACTION_CANCELLED (Internal use only - Must be zero) | 0 | All informations inside transaction are valid.
1 | Transaction has been cancelled. Stop the processing of the transaction and its following transactions belonging to the same request immediately. Note that some information inside the transaction may be invalid. However the validity of the most pointer references is granted by reference chains.

Table A.3. Request States

Definition | Value | Description
--- | --- | ---
USB_TRANSACTION_RESULT_OK | 0 | Request finished without errors.
USB_TRANSACTION_RESULT_HALTED | -1 | Request finished with error. Pipe has been halted.
USB_TRANSACTION_RESULT_ABORTED | -2 | Request finished with error. Pipe has been cleared.
USB_TRANSACTION_RESULT_TRANSMISSION_FAILED | -3 | Request failed, an unrecoverable transmission error occurred. Pipe has been halted.
USB_TRANSACTION_RESULT_INVALID_SIZE | -4 | Request failed, transfered data was not of the requested size. Pipe has been halted.
USB_TRANSACTION_RESULT_WORKING | -5 | Request is still ongoing.
USB_TRANSACTION_RESULT_BUSPROTO_ERR | -6 | The data was corrupted on the bus, for example CRC or data format errors
USB_TRANSACTION_RESULT_NORESPONSE | -8 | Request was not acknowledged by the device.
USB_TRANSACTION_RESULT_HC_BUFF_ERR | -9 | The host controller either ran out of buffer space during the transaction, or could not buffer the data fast enough
USB_TRANSACTION_RESULT_BUS_DATASZ | -10 | The host controller got more data than expected from the transaction.
USB_TRANSACTION_RESULT_INTERNAL | -11 | the system had an internal failure and could not complete the transaction
USB_TRANSACTION_RESULT_TIMEOUT | -12 | The transaction did not complete within the specified timeout, and has been aborted. The system does no more clearing up after aborting the transaction and it is up to the initiator of the request to sort out any problems that a partial transaction may have caused.

Table A.4. Setup transaction request type

Bit | Description
--- | ---
0-4 | Recipient
0 - Device
1 - Interface
2 - Endpoint
3 - Other
4-32 - Reserved
6-5 | Type
0 - Standard
1 - Class
2 - Vendor
3 - Reserved
7 | Data transfer direction
0 - Host to device
1 - Device to host

Table A.5. Constants used for type of USB transfer

Definition | Value | Description
--- | --- | ---
USB_PIPE_TYPE_CONTROL | 0 | Control Transfer
USB_PIPE_TYPE_ISOCHRONUS | 1 | Isochronous Transfer
USB_PIPE_TYPE_BULK | 2 | Bulk Transfer
USB_PIPE_TYPE_INTERRUPT | 3 | Interrupt Transfer
USB_PIPE_TYPE_MAX | 4 | Number of supported transfer types is 4 (USB 1.1)

## A.3. Devices

Table A.6. Constants used for device speed

Definition | Value | Description
--- | --- | ---
USB_DEVICE_SPEED_SLOW | 0x00 | Device speed is 1.5Mbit/s.
USB_DEVICE_SPEED_NORMAL | 0x01 | Device speed is 12Mbit/s.
USB_DEVICE_SPEED_MAX | 0x01 | Maximal device speed (USB 1.1)

Table A.7. Constants used for device states

Definition | Value | Description
--- | --- | ---
USB_DEVICE_STATE_UNPLUGGED | 0x00 | Device has been registered at USB module.
USB_DEVICE_STATE_ATTACHED | 0x01 | Device is attached to the USB but not powered.
USB_DEVICE_STATE_POWERED | 0x02 | Device is attached and powered but has not been reset. The USB Hub module will detect that a new device has been connected. Of course there may be the case that more than one device connected at the same time. In this case the Hub module is responsible to switch exactly one device to the bus per time by configuring the according hub.
USB_DEVICE_STATE_DEFAULT | 0x03 | Device is attached and powered and has been reset. It is responding at the default address. To set this address you must send a SET_ADDRESS standard device request to the device at the default address on the default pipe.
USB_DEVICE_STATE_ADDRESS | 0x04 | Device is attached and powered, has been reset and has got its own unique number. But device has not been configured. This can be done sending configuration on the default pipe.
USB_DEVICE_STATE_CONFIGURED | 0x05 | Device is attached and powered, has been reset, has got its own unique number and has been configured. The host program's can now use the device.
USB_DEVICE_STATE_SUSPENDED | 0x40 | This overlays actual device state. Device must be powered. The device enters this state if it hasn't seen an idle USB (that means also frame token are not sent!) for 3ms.

## A.4. Object References

Table A.8. Object reference types

Definition | Value | Description
--- | --- | ---
USB_REFERENCE_ENDPOINT | 0 | Selects an endpoint at USB_ReferenceDeregister or USB_FindObject
USB_REFERENCE_DEVICE | 1 | Selects a device at USB_ReferenceDeregister or USB_FindObject
USB_REFERENCE_CONTROLLER | 2 | Selects a host controller at USB_ReferenceDeregister or USB_FindObject

## A.5. Waiting

Table A.9. Constants used for USB waiting modes

Definition | Value | Description
--- | --- | ---
WAITING_TYPE_RETURN | 0 | Returns immediately. Program must check the state of the request periodically by calling USB_RequestGetState
WAITING_TYPE_LOOP | 1 | Loops internally until the request has been finished.
WAITING_TYPE_POLL | 2 | Waits until the request has been finished. WIMP is polled so other none interrupt driven tasks can use the CPU. This is only implemented for usage together with task windows.
WAITING_TYPE_MESSAGE | 3 | Returns immediately. If request is finished a message using the values inside the waiting structure is sent. This will be done by calling Wimp_SendMessage. A user message without a reply will be generated. Destination task and icon handle will be taken from waiting structure. The message block will be also taken from the location stored inside the waiting parameters. This means that a program will have to fill this block located inside a part of common address space before launching an operation which will make usage of the waiting structure. The program must fill the message block in according with general WIMP restriction to such blocks.
WAITING_TYPE_SWI | 4 | Returns immediately. If request is finished the SWI declared inside the waiting structure is launched. This is done by using the C-Function _kernel_swi. The SWI number is taken from the waiting structure. Also registers 0 to 9 are passed to this function. However results of the function call are dropped.
WAITING_TYPE_APCS | 5 | Returns immediately. If request is finished a function which has been declared inside the waiting structure is called. The function must be located elsewhere in common address space. It must accord to ARM Procedure Call Standard (APCS). In fact call is done by calling a C-Function of the type int function(int, int, int, int). The 4 parameters are filled from the waiting structure. The result of the function is dropped. At Assembler side registers 0-3 will be filled according APCS.

## A.6. URBs

Table A.10. URB driver fields

Position | Data type | Description
--- | --- | ---
0x00 | void* | Pointer to begin of buffer data. If data is included in this structure it will point behind the waiting structure else it must point to the piece of memory which is used as data buffer.
0x04 | unsigned long | Allocated data buffer size in Bytes. If the offset is added to this value you are getting the whole size of the buffer structure.
0x08 | unsigned long | Number of Bytes in the buffer which are really used for data in the moment.
0x0C | unsigned long | Actual position of data transfer.

Prev | Up | Next
Chapter 9. Old Documentation | Home | Appendix B. Service Calls