rockbox/docs/usb-api.md

Handling USB control requests

API overview

enum usb_control_response {
    USB_CONTROL_ACK,
    USB_CONTROL_STALL,
    USB_CONTROL_RECEIVE,
};

void usb_core_control_request(struct usb_ctrlrequest* req, void* reqdata);
void usb_core_control_complete(int status);
void usb_drv_control_response(enum usb_control_response resp,
                              void* data, int length);

The two usb_core functions are common to all targets with a USB stack and are implemented in usb_core.c. The USB driver calls them to inform the core when a control request arrives or is completed.

Each USB driver implements usb_drv_control_response(). The core calls this to let the driver know how to respond to each control request.

Legacy API

void usb_core_legacy_control_request(struct usb_ctrlrequest* req);

The old control request API is available through this function. Drivers which don't yet implement the new API can use the legacy API instead. To support legacy drivers, the USB core implements all functions in the new API and emulates the old control request handling behavior, bugs included.

This is intended as a stopgap measure so that old drivers keep working as-is. The core can start using the new API right away, and drivers can be ported one-by-one as time allows. Once all drivers are ported to the new API, all legacy driver support can be removed.

Request handling process

The driver submits control requests to the USB core one at a time. Once a request is submitted, it must be completed before the next request can be submitted. This mirrors normal USB operation.

When the USB driver receives a setup packet from the host, it submits it to the core to begin handling the control transfer. The driver calls usb_core_control_request(req, NULL), passing the setup packet in req. The second argument, reqdata, is not used at this time and is passed as NULL.

The core processes the setup packet and calls usb_drv_control_response() when it's done. The allowed responses depend on the type of control transfer being processed.

Non-data transfers

• USB_CONTROL_ACK, to indicate the request was processed successfully.
• USB_CONTROL_STALL, if the request is unsupported or cannot be processed.

Control read transfers

• USB_CONTROL_ACK, to indicate the request was processed successfully. The core must provide a valid data buffer with length not exceeding the wLength field in the setup packet; otherwise, driver behavior is undefined. The driver will transfer this data to the host during the data phase of the control transfer, and then acknowledge the host's OUT packet to complete the transfer successfully.
• USB_CONTROL_STALL, if the request is unsupported or cannot be processed.

Control write transfers

The driver calls usb_core_control_request() twice to handle control writes. The first call allows the core to handle the setup packet, and if the core decides to accept the data phase, the second call is made when the data has been received without error.

Setup phase

The first call is made at the end of the setup phase, after receiving the setup packet. The driver passes reqdata = NULL to indicate this.

The core can decide whether it wants to receive the data phase:

• USB_CONTROL_RECEIVE, if the core wishes to continue to the data phase. The core must provide a valid data buffer with length greater than or equal to the wLength specified in the setup packet; otherwise, driver behavior is undefined. The driver will proceed to the data phase and store received data into the provided buffer.
• USB_CONTROL_STALL, if the request is unsupported or cannot be processed.

If the core accepts the data phase, the driver will re-submit the request when the data phase is completed correctly. If any error occurs during the data phase, the driver will not re-submit the request; instead, it will call usb_core_control_complete() with a non-zero status code.

Status phase

The second call to usb_core_control_request() is made at the end of the data phase. The reqdata passed by the driver is the same one that the core passed in its USB_CONTROL_RECEIVE response.

The core's allowed responses are:

• USB_CONTROL_ACK, to indicate the request was processed successfully.
• USB_CONTROL_STALL, if the request is unsupported or cannot be processed.

Request completion

The driver will notify the core when a request has completed by calling usb_core_control_complete(). A status code of zero means the request was completed successfully; a non-zero code means it failed. Note that failure can occur even if the request was successful from the core's perspective.

If the core response is USB_CONTROL_STALL at any point, the request is considered complete. In this case, the driver won't deliver a completion notification because it would be redundant.

The driver may only complete a request after the core has provided a response to any pending usb_core_control_request() call. Specifically, if the core has not yet responded to a request, the driver needs to defer the completion notification until it sees the core's response. If the core's response is a stall, then the notification should be silently dropped.

Notes

• Driver behavior is undefined if the core makes an inappropriate response to a request, for example, responding with USB_CONTROL_ACK in the setup phase of a control write or USB_CONTROL_RECEIVE to a non-data request. The only permissible responses are the documented ones.

• If a response requires a buffer, then data must be non-NULL unless the length is also zero. If a buffer is not required, the core must pass data = NULL and length = 0. Otherwise, driver behavior is undefined. There are two responses which require a buffer:

  • USB_CONTROL_ACK to a control read
  • USB_CONTROL_RECEIVE to the setup phase of a control write

• Drivers must be prepared to accept a setup packet at any time, including in the middle of a control request. In such a case, devices are required to abort the ongoing request and start handling the new request. (This is intended as an error recovery mechanism and should not be abused by hosts in normal operation.) The driver must take care to notify the core of the current request's failure, and then submit the new request.