# USB Subsystem Overview

The subsystem is a framework for implementing applications where the board will act as a USB device, USB host or both.

The following diagram is a high-level overview of the USB subsystem architecture. The left side of the "USB Library" box is the USB Device framework, while the right side is the USB Host framework. An application may choose to use both or just one of the frameworks. The "OTG / transceiver" part is optional, but usually present when using a dual-role controller.

For more information, please see one of the following pages:

- The USB core library
- The USB Device Framework

## The USB core library

The USB core library provides helper functions which can be used by both device- and host-side USB components. To initialize the USB core library, the following function must be called before any drivers are initialized.

- usb_init(): Initialize the USB core subsystem.

### USB request management

A USB request contains a list of buffers, each representing a contiguous region of memory used for holding data to be sent or received in a USB transfer. See the documentation of struct usb_request for details.

Each request may have a callback associated with it, which is called when all the buffers have been transferred or cancelled. The submitter may use usb_request::context to hold arbitrary data associated with the request.

Before a USB request can be (re)used, it must be initialized by calling usb_req_init().

USB requests can also be allocated dynamically from the USB request pool using the following functions. These functions will automatically initialize the request, so there's no need to call usb_req_init() on a freshly allocated request.

- usb_req_alloc(): Allocate and initialize a USB request structure.
- usb_req_alloc_single_tx(): Allocate a USB request and initialize with a single buffer for transmission.
- usb_req_alloc_single_rx(): Allocate a USB request and initialize with a single buffer for reception.
- usb_req_free(): Free a USB request structure.
- usb_req_free_all(): Free a USB request and all associated buffers.

Finally, the following function can be used to associate another buffer with a request.

- usb_req_add_buffer(): Add a buffer to a USB request.