USB_FindObject (SWI&55387) — Find the address of an object.
| 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, “Object reference types” | |||||||||
| R3 |
| |||||||||
| 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
behaviour flag set. The reference to the master structure is deregistered automatically if USB_FIND_KEEP_REFERENCE in the behaviour control has not been selected. |
| R0 | Pointer to controller, device or endpoint structure or zero if an error occurred. |
| R1 | Error code Table A.1, “Error codes used by the USB system” |
| R2, R3, R4 | Preserved |
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.