In FreeBSD, usb_config structures are used to find and communicate with individual endpoints. struct usb_config is defined in the <dev/usb/usbdi.h> header as follows:
struct usb_config {
/* USB Module Private Data */
enum usb_hc_mode usb_mode;
/* Mandatory Fields */
uint8_t type;
uint8_t endpoint;
uint8_t direction;
usb_callback_t *callback;
usb_frlength_t bufsize;
/* Optional Fields */
usb_timeout_t timeout;
usb_timeout_t interval;
usb_frcount_t frames;
uint8_t ep_index;
uint8_t if_index;
/* USB Transfer Flags */
struct usb_xfer_flags flags;
};Many of the fields in struct usb_config must be initialized by a USB driver. These fields are described in the following sections.
The type field specifies the endpoint type. Valid values for this field are UE_CONTROL, UE_BULK, UE_INTERRUPT, and UE_ISOCHRONOUS.
The endpoint field specifies the endpoint number. A value of UE_ADDR_ANY suggests that the endpoint number is unimportant—the other fields are used to find the correct endpoint.
The direction field specifies the endpoint direction. Valid values for this field are shown in Table 15-1.
Table 15-1. USB Endpoint Direction Symbolic Constants
Constant | Description |
|---|---|
| Stipulates that the endpoint be an IN endpoint; that is, the endpoint transfers data to the host from the device |
| Stipulates that the endpoint be an OUT endpoint; that is, the endpoint transfers data to the device from the host |
| Stipulates that the endpoint support bidirectional transfers |
Note
The direction of an endpoint is from the host’s perspective.
The callback field denotes a mandatory callback function. This function is executed before and after the endpoint specified by type, endpoint, and direction transfers data. We’ll discuss this function further in USB Transfers (in FreeBSD) in USB Transfers (in FreeBSD).
The bufsize field denotes the buffer size for the endpoint specified by type, endpoint, and direction. As you would expect, bufsize is used for type transactions.
As this section’s heading implies, the preceding fields must be defined in every usb_config structure.
The timeout field sets the transaction timeout in milliseconds. If timeout is 0 or undefined and type is UE_ISOCHRONOUS, then a timeout of 250 ms will be used.
The interval field’s meaning is based on the value of type. Table 15-2 details interval’s purpose (based on type).
Table 15-2. interval’s Purpose (Based on Endpoint Type)
Endpoint Type | What interval Does |
|---|---|
|
|
|
|
|
|
|
|
The frames field denotes the maximum number of USB frames that the endpoint specified by type, endpoint, and direction supports. In FreeBSD, USB frames are simply “data packets” that travel to or from an endpoint. USB frames are composed of one or more USB packets, which actually contain the data.
The ep_index field demands a non-negative integer. If multiple endpoints are identified by type, endpoint, and direction—which can occur when endpoint is UE_ADDR_ANY—the value of ep_index will be used to select one.
The if_index field specifies the interface number (based on the ifaces argument passed to usbd_transfer_setup, which is described in USB Configuration Structure Management Routines in USB Configuration Structure Management Routines).
The flags field sets the transactional properties for the endpoint specified by type, endpoint, and direction. This field expects a usb_xfer_flags structure.
struct usb_xfer_flags is defined in the <dev/usb/usbdi.h> header as follows:
struct usb_xfer_flags {
uint8_t force_short_xfer : 1;
uint8_t short_xfer_ok : 1;
uint8_t short_frames_ok : 1;
uint8_t pipe_bof : 1;
uint8_t proxy_buffer : 1;
uint8_t ext_buffer : 1;
uint8_t manual_status : 1;
uint8_t no_pipe_ok : 1;
uint8_t stall_pipe : 1;
};All of the fields in struct usb_xfer_flags are optional. These fields are 1-bit and function as flags. They are detailed in Table 15-3.
Table 15-3. USB Transfer Flags
Description | |
|---|---|
| Causes a short transfer; short transfers basically dispatch a short USB packet, which tends to indicate “end of transaction;” this flag can be set anytime |
| Indicates that it is okay to receive short transfers; this flag can be set anytime |
| Indicates that it is okay to receive gobs of short USB frames; this flag can only affect |
| Causes any failed USB transactions to remain first in their queue; this guarantees that all transactions complete in FIFO order; this flag can be set anytime |
| Rounds |
| Indicates that an external DMA buffer will be used for all transactions; this flag cannot be set after driver initialization |
| Stops the handshake/status stage from occurring in control transactions; this flag can be set anytime |
| Causes |
| Causes the endpoint specified by |
Note
If you don’t understand some of these descriptions, don’t worry; I’ll expand on them later.