A URB is passed to a transaction either as the source or destination for transfered data depending on the pipe direction and type of transaction requested.
A URB may only be used by one outstanding transaction at a time. However, a URB may be reused in another transaction once any outstanding transaction is completed. Hence, a URB may be claimed once at the beginning of a series of transactions and freed once they are all complete.
A driver may vary the amount of data transfered, in each transaction of a series, by changing the used size field to indicate the amount of data to receive or transmit before starting the next transaction.
The used size field indicates the number of bytes to transfer in transactions from host to device transfers. Used size is used to limit the amount of data to be transfered from a device to host, note that the transaction may complete having transfered fewer bytes than this value and the actual_position field should be used to find the actual number of bytes transfered.
See Chapter 7, Transactions for more details on transactions and their interaction with URBs.
Example 5.1. Use of URBs with a control transaction
This example shows
The allocation of two URBs
Data manipulation in a URB (zeroing space for reception of data)
URB use with a control transaction
URB freeing
Please note this example performs no error checking, real code would of course need to check the return and error codes from each call.
int result;
extern waiting* msgwait;
usb_io_buffer* msgbuf;
usb_io_buffer* databuf;
/* allocate a URB for a control message */
msgbuf = usb_buffer_malloc(control_pipe,/* pipe reference */
USB_STRUCT_SETUP_BUFFER_SIZE,/* buffer length */
0,/* no external storage */
&result); /* result pointer */
/* allocate a 64byte data URB */
databuf = usb_buffer_malloc(control_pipe, 64, 0, &result);
/* clear data buffer within URB */
memset(databuf->pointer_to_data, 0, len);
databuf->size = len;
/* code would change URB data buffer if data was to be transfered from host to device*/
/* sends a control messgage */
msgwait = usblib_ctrl_msg(control_pipe,
databuf,
msgbuf,
&wait,
requtype,
req,
val,
index);
/* code would examine URB data buffer if data was transfered from device to host */
/* free URB */
usb_buffer_free(databuf);
usb_buffer_free(msgbuf);
|