Chapter 3. Library SWI Calls

Table of Contents

3.1. Introduction
3.2. Notes on reference counts
3.3. Reference management SWIs
3.4. Waiting Support SWIs
3.5. Transaction SWIs
3.6. Device management SWIs
3.7. Library SWIs
3.8. URB SWIs

3.1. Introduction

This Module provides support calls for the USB system. Every call here can be implemented using discrete calls from the "core" module and structure manipulation.

The SWIs here adhere to the standard RISC OS error reporting mechanism. A Call returning with the V flag set indicates that the data pointed to by R0 on exit is an error block and the call has failed

The SWIs provided here break down into three general categories

Interfacing to functionality similar to the C API
Creation of standard structures E.G. waiting structures
Manipulation of standard structures

Where appropriate links will be provided to their equivalents in the RISC OS USB C API.

3.2. Notes on reference counts

All HostController, Endpoint and Device references have an associated reference count. This count is incremented by the associated find calls for them, and needs to be decremented when they are no-longer of use to the driver. A reference can be de-registered by USBLib_ReferenceDeregister (SWI &56340) which will take one off the reference count. When the reference count reaches zero, the reference will finally be deleted from the system, freeing up any associated resources.

If the reference counts are not suitably de-registered, then you will leave references and their resources in the system, and will therefore leave less room for new resources.

The reference count of of endpoints created when the device is first obtained by the driver may well not be zero, drivers should not assume this behaviour and should balance claims and releases accordingly.

3.3. Reference management SWIs

Table of Contents

USBLib_FindDeviceRef (SWI &56340) - Obtains a device reference
USBLib_FindDevice (SWI &56340) - Obtains a device and controller reference
USBLib_DeviceInfo (SWI &56340) - Gets device information
USBLib_HCInfo (SWI &56340) - Gets host controller information
USBLib_ReferenceDeregister (SWI &56340) - Deregisters a reference
USBLib_PipeInfo (SWI &56340) - Obtain information on a pipe
USBLib_GetReferenceCount (SWI &56340) - Obtain reference count of a reference
USBLib_FindEndpoint (SWI &56340) - Obtain an endpoint reference

3.4. Waiting Support SWIs

Table of Contents

USBLib_CreateLoopWaiting (SWI &56340) - Creates a loop waiting structure
USBLib_CreateReturnWaiting (SWI &56340) - Creates a return waiting structure
USBLib_CloneWaiting (SWI &56340) - Clones a waiting structure
USBLib_FreeWaiting (SWI &56340) - Frees a waiting structure.
USBLib_CreateWimpMsgWaiting (SWI &56340) - Creates a wimp message waiting structure.
USBLib_CreateAPCSWaiting (SWI &56340) - Creates an APCS waiting structure
USBLib_CreatePollWaiting (SWI &56340) - Creates a Wimp poll waiting structure
USBLib_CreateSWIWaiting (SWI &56340) - Creates a SWI call waiting structure
USBLib_CreateCallbackWaiting (SWI &56340) - Creates a callback waiting structure
USBLib_WaitingResult (SWI &56340) - examines the state of a waiting structure

3.5. Transaction SWIs

Table of Contents

USBLib_CtrlMsg (SWI &56340) - Starts a transaction using a formatted control message.
USBLib_DecodeTransactionResult (SWI &56340) - Decodes a transaction result into a human readable string
USBLib_GetDefaultPipe (SWI &56340) - Obtains a devices default pipe
USBLib_SelectInterface (SWI &56340) - Selects an alternate interface on a device.
USBLib_DecodeAddress (SWI &56340) - Decodes a packed device address
USBLib_EndpointInfo (SWI &56340) - Information on an endpoint
USBLib_WaitingInfo (SWI &56340) - Gets the information about a waiting structure
USBLib_PipeOpen (SWI &56340) - Opens a pipe on an endpoint
USBLib_PipeClose (SWI &56340) - Closes an open pipe
USBLib_PipeClear (SWI &56340) - Clears all pending transactions from a pipe
USBLib_RequestStart (SWI &56340) - Starts a request on a pipe
USBLib_RequestStart2 (SWI &56340) - Starts a transaction with a timeout
USBLib_RequestResult (SWI &56340) - Gets a transactions result
USBLib_FindController (SWI &56340) - Obtains a reference to a controller

3.6. Device management SWIs

Table of Contents

USBLib_DevMgrDrop (SWI &56340) - Removes a specified device from the unclaimed device pool.
USBLib_DevMgrRelease (SWI &56340) - Releases a claim on a device.
USBLib_DevMgrClaim (SWI &56340) - Claims a device from the unclaimed device pool.
USBLib_DevMgrFindFree (SWI &56340) - Finds devices matching criteria in unclaimed device pool.
USBLib_FindFreeDev (SWI &56340) - Finds a device in the unclaimed device pool
USBLib_ParseCmdLine (SWI &56340) - Parse a command line
USBLib_NewDevMsgInfo (SWI &56340) - Extract information from a new device message
USBLib_DevMgrSetFilter (SWI &56340) - Sets up a filter block

3.7. Library SWIs

Table of Contents

USBLib_Version (SWI &56340) - Obtain the version of the loaded library module
USBLib_Info (SWI &56340) - Obtain statistics on library usage
USBLib_Register (SWI &56340) - Register a client with the library
USBLib_Deregister (SWI &56340) - Deregisters a client from the library
USBLib_CInit (SWI &56340) - Initialises a jump table for use with C library
USBLib_Free (SWI &56340) - Frees library allocated resources
USBLib_TranslateError (SWI &56340) - Translates an error code into a human readable string

3.8. URB SWIs

Table of Contents

USBLib_AllocURB (SWI &56340) - Creates a URB
USBLib_FreeURB (SWI &56340) - frees a URB
USBLib_URBInfo (SWI &56340) - Gets parameters from a URB
USBLib_SetURB (SWI &56340) - Sets values in a URB