class RequestBase

Usage notes:

usb::Request is a c++ wrapper around the usb_request_t object. It provides

capabilities to interact with a usb_req buffer which is used to traverse the

usb stack. On deletion, it will automatically free itself.

usb::BorrowedRequest provides an unowned variant of usb::Request. It adds

functionality to store and call a complete callback which isn't present in

usb::Request. In addition, it will call the completion on destruction if it

wasn't already triggered.

usb::RequestPool provides pooling functionality for usb::Request reuse.

usb::RequestQueue provides a queue interface for tracking usb::Request and

usb::BorrowedRequest objects.

usb::RequestList provides a list interface for tracking usb::Request and

usb::BorrowedRequest objects.

A Request or BorrowedRequest cannot be stored simultaneously in both a

usb::RequestQueue and usb::RequestList in the same driver layer.

A CallbackRequest is a Request which maintains ownership of a request,

and contains a callback which will be invoked upon completion.

Since the parent request size is often not known at compile-time,

it is necessary for the device driver to implement its own wrapper

and call the Invoke function on the callback when a completion

is received. Invoke will then invoke the associated lambda function.

Available methods for both Request and BorrowedRequest include:

usb_request_t* request(); // accessor for inner type.

// Takes ownership of inner type. Should only be used when transferring

// ownership to another driver.

usb_request_t* take();

All methods implemented in RequestBase (scroll below for additional info).

Available to Request and BorrowedRequest if they templatize of Storage:

Storage* private_storage(); // accessor for private storage.

Available to Request:

void Release(); // Frees the inner type.

Available to BorrowedRequest:

void Complete(zx_status_t); // Completes the Request.

////////////////////////////////////////////////////////////////////////////

Example: Basic allocation with a pool:

usb::RequestPool

<

> pool;

const size_t op_size = usb::Request

<

>::RequestSize(parent_req_size);

for (int i = 0; i

<

kNumRequest; i++) {

std::optional

<usb

::Request> request;

request = usb::Request::Alloc(op_size, DATA_SIZE, EP_ADDRESS, parent_req_size);

if (!request) return ZX_ERR_NO_MEMORY;

pool.add(*std::move(request));

}

////////////////////////////////////////////////////////////////////////////

Example: Enqueue incoming requests into a usb::RequestQueue:

class Driver {

public:

<

...>

private:

usb::BorrowedRequestQueue

<

> request_;

const size_t parent_req_size_;

};

void Driver::UsbRequestQueue(usb_request_t* req, const usb_request_callback_t* completion_cb) {

request_.push(usb::BorrowedRequest

<

>(op, cb, parent_req_size_));

}

////////////////////////////////////////////////////////////////////////////

Example: Add incoming requests into a usb::RequestList:

class Driver {

public:

<

...>

private:

usb::BorrowedRequestList

<

> request_;

const size_t parent_req_size_;

};

void Driver::UsbRequestQueue(usb_request_t* req, const usb_request_callback_t* completion_cb) {

auto opt_unowned = usb::BorrowedRequest

<

>(op, cb, parent_req_size);

auto unowned = *std::move(opt_unowned);

request_.push_back(

&unowned

);

// Pass unowned_.take() to next layer.

}

////////////////////////////////////////////////////////////////////////////

Example: Using private context only visible to your driver:

struct PrivateStorage {

bool valid;

size_t count_metric;

}

using UsbRequest = usb::BorrowedRequest

<PrivateStorage

>;

void Driver::UsbRequestQueue(usb_request_t* req, const usb_request_t* completion_cb) {

UsbRequest usb_req(op, cb, parent_req_size_));

ZX_DEBUG_ASSERT(usb_req.request()->command == USB_ERASE);

usb_req.private_storage()->valid = true;

usb_req.private_storage()->count_metric += 1;

<

...>

}

////////////////////////////////////////////////////////////////////////////

Example: Using CallbackRequest

using UsbRequest = CallbackRequest

<

32>;

...

UsbRequest::Queue(std::move(request), [=](UsbRequest request) {...});