Appendix A. Constants

Table of Contents

A.1. Error Codes
A.2. Transaction constants
A.3. Devices
A.4. Object References
A.5. Waiting
A.6. URBs

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 codeErrorDescription
0USB_RESULT_OKAll OK. Operation performed successfully
&819B00USB_RESULT_ALIAS_FILE_NOT_FOUNDAlias File could not be opened
&819B01USB_RESULT_STRUCTUR_DROPPEDOperation 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.
&819B02USB_RESULT_INVALID_PARAMETERWrong parameter passed to function
&819B03USB_RESULT_CONTROLLER_ALREADY_EXISTSCan 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.
&819B04USB_RESULT_BUS_INVALID_INTERNAL_2Should never occur. Internal invalid state was detected by USB-Module. Please inform developer about this.
&819B05USB_RESULT_ILLEGAL_SPEEDEither USB Host Controller is not supporting this speed or the speed is illegal in conjunction with the selected USB-Transfer type
&819B06USB_RESULT_ALL_DEVICES_USEDAll device addresses are in use however.
&819B07USB_RESULT_DEVICE_ADDRESS_USEDA device address should used for new device which is already in use.
&819B08USB_RESULT_ENDPOINT_ADDRESS_USEDAn 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.
&819B09USB_RESULT_INVALID_PIPE_STATEOccurs 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)
&819B0AUSB_RESULT_NO_TRANSACTION_PENDINGOnly used by usb_transaction_get_pending function to inform the USB Host controller driver that no transactions are pending.
&819B0BUSB_RESULT_ERROR_GENERATEDUsed 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.
&819B0CUSB_RESULT_NO_OBJECT_FOUNDUsed by usb_find_object to inform the caller that the requested object could not be found.
&819B0DUSB_RESULT_BUS_CAPACITY_TO_SMALLNot enough USB capacity at opening a pipe.
&819B0EUSB_RESULT_BUS_INVALID_PAYLOAD_SIZEMaximal 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.
&819B0FUSB_RESULT_BUS_INVALID_TRANSFER_TYPEShows 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.
&819B10USB_RESULT_BUS_INVALID_INTERNAL_1This error should never occur. Please contact Simtec Electronics for further assistance.
&819B11USB_RESULT_NOT_ENOUGH_MEMORYUnable to claim a piece of memory

A.2. Transaction constants

Table A.2. Transaction behaviour flags

BitDefinitionValueDescription
0USB_TRANSACTION_EXACT_SIZE0
  • 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.

1USB_TRANSACTION_FRAME_START0Transaction will commence as soon as possible.
1Frame start number is given and the transaction will commence processing on or after the specified frame.
2USB_TRANSACTION_SETUP_EVAL (Currently Unsupported)0Setup 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.

3USB_TRANSACTION_STATUS_STAGE0Normal transaction behaviour.
1This 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.
4USB_TRANSACTION_TIMEOUT0Normal transaction behaviour.
1When 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 - 29Reserved0Reserved must be zero.
30USB_TRANSACTION_REQUEST_FIRST (Internal use only - Must be zero)0Transaction 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.
1Transaction is the first one in a request.
31USB_TRANSACTION_CANCELLED (Internal use only - Must be zero)0All 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

DefinitionValueDescription
USB_TRANSACTION_RESULT_OK0Request finished without errors.
USB_TRANSACTION_RESULT_HALTED-1Request finished with error. Pipe has been halted.
USB_TRANSACTION_RESULT_ABORTED-2Request finished with error. Pipe has been cleared.
USB_TRANSACTION_RESULT_TRANSMISSION_FAILED-3Request failed, an unrecoverable transmission error occurred. Pipe has been halted.
USB_TRANSACTION_RESULT_INVALID_SIZE-4Request failed, transfered data was not of the requested size. Pipe has been halted.
USB_TRANSACTION_RESULT_WORKING-5Request is still ongoing.
USB_TRANSACTION_RESULT_BUSPROTO_ERR-6The data was corrupted on the bus, for example CRC or data format errors
USB_TRANSACTION_RESULT_NORESPONSE-8Request was not acknowledged by the device.
USB_TRANSACTION_RESULT_HC_BUFF_ERR-9The host controller either ran out of buffer space during the transaction, or could not buffer the data fast enough
USB_TRANSACTION_RESULT_BUS_DATASZ-10The host controller got more data than expected from the transaction.
USB_TRANSACTION_RESULT_INTERNAL-11the system had an internal failure and could not complete the transaction
USB_TRANSACTION_RESULT_TIMEOUT-12The 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

BitDescription
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

DefinitionValueDescription
USB_PIPE_TYPE_CONTROL0Control Transfer
USB_PIPE_TYPE_ISOCHRONUS1Isochronous Transfer
USB_PIPE_TYPE_BULK2Bulk Transfer
USB_PIPE_TYPE_INTERRUPT3Interrupt Transfer
USB_PIPE_TYPE_MAX4Number of supported transfer types is 4 (USB 1.1)

A.3. Devices

Table A.6. Constants used for device speed

DefinitionValueDescription
USB_DEVICE_SPEED_SLOW0x00Device speed is 1.5Mbit/s.
USB_DEVICE_SPEED_NORMAL0x01Device speed is 12Mbit/s.
USB_DEVICE_SPEED_MAX0x01Maximal device speed (USB 1.1)

Table A.7. Constants used for device states

DefinitionValueDescription
USB_DEVICE_STATE_UNPLUGGED0x00Device has been registered at USB module.
USB_DEVICE_STATE_ATTACHED0x01Device is attached to the USB but not powered.
USB_DEVICE_STATE_POWERED0x02Device 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_DEFAULT0x03Device 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_ADDRESS0x04Device 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_CONFIGURED0x05Device 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_SUSPENDED0x40This 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

DefinitionValueDescription
USB_REFERENCE_ENDPOINT0Selects an endpoint at USB_ReferenceDeregister or USB_FindObject
USB_REFERENCE_DEVICE1Selects a device at USB_ReferenceDeregister or USB_FindObject
USB_REFERENCE_CONTROLLER2Selects a host controller at USB_ReferenceDeregister or USB_FindObject

A.5. Waiting

Table A.9. Constants used for USB waiting modes

DefinitionValueDescription
WAITING_TYPE_RETURN0Returns immediately. Program must check the state of the request periodically by calling USB_RequestGetState
WAITING_TYPE_LOOP1Loops internally until the request has been finished.
WAITING_TYPE_POLL2Waits 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_MESSAGE3Returns 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_SWI4Returns 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_APCS5Returns 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

PositionData typeDescription
0x00void*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.
0x04unsigned longAllocated data buffer size in Bytes. If the offset is added to this value you are getting the whole size of the buffer structure.
0x08unsigned longNumber of Bytes in the buffer which are really used for data in the moment.
0x0Cunsigned longActual position of data transfer.