USB_FindObject (SWI&55387)
Prev | Chapter 2. Core SWI Calls | Next

## Name

USB_FindObject (SWI&55387) — Find the address of an object.

## On Entry

R0 | Pointer to the master object structure which should be searched for the object or zero if searching for an USB host controller.
R1 | Pointer to controller name at controller searching or device or endpoint number
R2 | Object type Table A.8
R3 |
Value | Definition | Description
--- | --- | ---
1 | USB_FIND_KEEP_REFERENCE | The reference to the master object is not automatically released but kept.
2 | USB_FIND_NEXT_OBJECT | Does not find the USB Host controller, device or endpoint which Number or Name has been given inside R1 but the one which name or number is the next bigger one than the value given in R1. This allows enumerating of USB Host controllers, devices and endpoints.
R4 | Pointer to a 4 Byte word. May be set to zero if not scanning a list. The value returned inside this word if given depends on the kind of search value passed in R1. If this is an integer it will contain an integer else it will contain a pointer to 0 terminated string. This value can be used to scan list of host controllers, devices and endpoints if it is used for the next USB_FindObject call with USB_FIND_NEXT_OBJECT behavior flag set. The reference to the master structure is deregistered automatically if USB_FIND_KEEP_REFERENCE in the behavior control has not been selected.

## On Exit

R0 | Pointer to controller, device or endpoint structure or zero if an error occurred.
R1 | Error code Table A.1
R2, R3, R4 | Preserved

## Use

Value of the word to which R4 is pointing will be changed as described above.

A reference to the structure found is registered automatically if call is successful. Don't forgot to release this reference at enumerating!

If successful a pointer to the object structure will be returned. If the call is not successful a NULL pointer and an according error code will be returned.

This SWI is used to translate human readable value like device address numbers and name of host controllers into an address which can be used at parameters of other SWI of the USB module. It can be also used to scan a list of host controllers, devices or endpoints. For example:

An application wants to generate its own endpoint for a device on a USB host controller.

Firstly USB_FindObject (SWI&55387) is called to get the address of the USB host controller(Note because Host controllers have no parent object R0 must be set to zero for this call). The result in R0 is used for the next call.
Secondly USB_FindObject (SWI&55387) is called again, this time the device number is searched for. After finding the device the endpoint can be generated by using USB_EndpointRegister, this will automatically de-reference the found objects structure and return a pointer to an endpoint. This endpoint can be used for opening a pipe but this will not automaticly de-register the endpoint as it is required throughout the life of the pipe. Use USB_EndpointDeregister (SWI&55381) to dereference the endpoint after the pipe is closed.

To scan a list you will need a trick especially at the device numbers. The problem is to find the first element. If it is equal to the lowest possible value you won't find it if using USB_FIND_NEXT_OBJECT. Therefore do a normal USB_FindObject call first searching for the lowest possible value. If successful this will be the first element inside your list. Else you now have to call USB_FindObject again with the lowest possible value but this time with USB_FIND_NEXT_OBJECT set. To get the next element of the list copy the value returned of the word pointed to by R4 into R1. Drop the reference returned to you by the previous call by using USB_ReferenceDeregister if you are not longer using it. Always set USB_FIND_KEEP_REFERENCE.

## Related SWI's

USB_ReferenceDeregister (SWI&55386)

Prev | Up | Next
USB_ReferenceDeregister (SWI&55386) | Home | USB_ManageDeviceAddresses (SWI&55388)