docs/concepts/usb/request-lifecycle.md - fuchsia - Git at Google

 <!--
     (C) Copyright 2019 The Fuchsia Authors. All rights reserved.
     Use of this source code is governed by a BSD-style license that can be
     found in the LICENSE file.
 -->

 # Lifecycle of a USB request

 ## Glossary

 *   HCI -- Host Controller Interface: A host controller interface driver is
     responsible for queueing USB requests to hardware, and managing the state
     of connected devices while operating as a USB host.
 *   DCI -- Device controller interface: A device controller interface is
     responsible for queueing USB requests to a USB host that the device is
     connected to.

 ## Allocation

 The first step in a USB request's lifecycle is allocation. USB requests contain
 data from all of the drivers in the request stack in a single allocation. Each
 driver that is upstream of a USB device driver should provide a
 [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) method --
 which returns the size it needs to contain its local request context. When a
 USB device driver allocates a request, it should invoke this method to
 determine the size of the parent's request context.

 Note: It is important to ensure that the lifetime of a request does not exceed
 the lifetime of your driver. If your driver is released with outstanding
 requests, you will encounter a use-after-free scenario when the parent tries to
 send the request back to you by invoking your callback. Drivers should not
 reply to unbind until all outstanding requests have been returned.

 ### C example {#c-example}

 ```c
 size_t parent_req_size = usb_get_request_size(&usb);
 usb_request_t* request;
 usb_request_alloc(&request, transfer_length, endpoint_addr,
 parent_req_size+sizeof(your_context_struct_t));
 usb_request_complete_t complete = {
       .callback = usb_request_complete,
       .ctx = your_context_pointer,
 };
 your_context_pointer.completion = complete;
 usb_request_queue(&usb, request, &complete);
 ...

 void usb_request_complete(void* cookie, usb_request_t* request) {
     your_context_struct_t data;
     // memcpy is needed to ensure alignment
     memcpy(&data, cookie, sizeof(data));
     // Do something here to process the response
     // ...

     // Requeue the request
     usb_request_queue(&data.usb, request, &data.completion);
 }
 ```

 ### C++ example

 ```c++
 parent_req_size = usb.GetRequestSize();
 std::optional<usb::Request<void>> req;
 status = usb::Request<void>::Alloc(&req, transfer_length,
 endpoint_addr, parent_req_size);
 usb_request_complete_t complete = {
       .callback =
           [](void* ctx, usb_request_t* request) {
             static_cast<YourDeviceClass*>(ctx)->YourHandlerFunction(request);
           },
       .ctx = this,
   };
 usb.RequestQueue(req->take(), &complete);
 ```

 ### C++ example (with lambdas)

 ```c++
 size_t parent_size = usb_.GetRequestSize();
 using Request = usb::CallbackRequest<sizeof(std::max_align_t) * 4>;
 std::optional<Request> request;
 Request::Alloc(&request, max_packet_size, endpoint_address,
 parent_size, [=](Request request) {
     // Do some processing here.
     // ...
     // Re-queue the request
     Request::Queue(std::move(request), usb_client_);
 });
 ```

 ## Submission

 You can submit requests using the
 [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22) method,
 or -- in the case of CallbackRequests (as seen [here](#c-example)), using
 `Request::Queue` or simply `request.Queue(client)`. In all cases, ownership of
 the USB request is transferred to the parent driver (usually `usb-device`).

 The typical lifecycle of a USB request (from a device driver to either a host
 controller or device controller is as follows):

 *   The USB device driver queues the request
 *   The `usb-device` core driver receives the request, and now owns the request
     object.
 *   The `usb-device` core driver injects its own callback (if the direct flag
     is not set), or passes through the request (if the direct flag is set) to
     the HCI or DCI driver.
 *   The HCI or DCI driver now owns the request. The HCI or DCI driver submits
     this request to hardware.
 *   The request completes. When this happens, if the direct flag was set, the
     callback in the device driver is invoked, and the device driver now owns
     the request. If the direct flag is not set, the usb-device (core) driver
     now owns the request.
 *   If the core driver owns the request; it is added to a queue for dispatch by
     another thread.
 *   The core driver eventually invokes the callback, and the request is now
     owned by the device driver. The device driver can now re-submit the
     request.

 ## Cancellation

 Requests may be cancelled by invoking
 [CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89). When
 [CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89) completes, all
 requests are owned by the caller. Drivers implementing a
 [CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89) function (such
 as the usb-device core driver and any HCI/DCI drivers) are responsible for
 transferring ownership to their children with a `ZX_ERR_CANCELLED` status code.

 ## Implementation notes for writers of HCI, DCI, or filter drivers

 ### Implementing [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96)

 The value returned by
 [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) should
 equal the value of your parent's
 [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) + the size
 of your request context, including any padding that would be necessary to
 ensure proper alignment of your data structures (if applicable). If you are
 implementing an HCI or DCI driver, you must include `sizeof(usb_request_t)` in
 your size calculation in addition to any other data structures that you are
 storing. `usb_request_t` has no special alignment requirements, so it is not
 necessary to add padding for that structure.

 ### Implementing [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22)

 Implementors of
 [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22) temporarily
 assumes ownership of the USB request from its client driver. As an implementor
 of [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22), you are
 allowed to access all fields of the `usb_request_t`, as well as any private
 data that you have appended to the `usb_request_t` structure (by requesting
 additional space through
 [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96)), but you
 are not allowed to modify any data outside of your private area, which starts
 at `parent_req_size` bytes (past the end of `usb_request_t`).

 ## Example USB request stack (HCI)

 xHCI (host controller) -> `usb-bus` -> `usb-device` (core USB device driver) ->
 `usb-mass-storage`

 ## Example USB request stack (DCI)

 `dwc2` (device-side controller) -> `usb-peripheral` (peripheral core driver) ->
 `usb-function` (core function driver) -> `cdc-eth-function` (ethernet
 peripheral mode driver)
	<!--
	(C) Copyright 2019 The Fuchsia Authors. All rights reserved.
	Use of this source code is governed by a BSD-style license that can be
	found in the LICENSE file.
	-->

	# Lifecycle of a USB request

	## Glossary

	* HCI -- Host Controller Interface: A host controller interface driver is
	responsible for queueing USB requests to hardware, and managing the state
	of connected devices while operating as a USB host.
	* DCI -- Device controller interface: A device controller interface is
	responsible for queueing USB requests to a USB host that the device is
	connected to.

	## Allocation

	The first step in a USB request's lifecycle is allocation. USB requests contain
	data from all of the drivers in the request stack in a single allocation. Each
	driver that is upstream of a USB device driver should provide a
	[GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) method --
	which returns the size it needs to contain its local request context. When a
	USB device driver allocates a request, it should invoke this method to
	determine the size of the parent's request context.

	Note: It is important to ensure that the lifetime of a request does not exceed
	the lifetime of your driver. If your driver is released with outstanding
	requests, you will encounter a use-after-free scenario when the parent tries to
	send the request back to you by invoking your callback. Drivers should not
	reply to unbind until all outstanding requests have been returned.

	### C example {#c-example}

	```c
	size_t parent_req_size = usb_get_request_size(&usb);
	usb_request_t* request;
	usb_request_alloc(&request, transfer_length, endpoint_addr,
	parent_req_size+sizeof(your_context_struct_t));
	usb_request_complete_t complete = {
	.callback = usb_request_complete,
	.ctx = your_context_pointer,
	};
	your_context_pointer.completion = complete;
	usb_request_queue(&usb, request, &complete);
	...

	void usb_request_complete(void* cookie, usb_request_t* request) {
	your_context_struct_t data;
	// memcpy is needed to ensure alignment
	memcpy(&data, cookie, sizeof(data));
	// Do something here to process the response
	// ...

	// Requeue the request
	usb_request_queue(&data.usb, request, &data.completion);
	}
	```

	### C++ example

	```c++
	parent_req_size = usb.GetRequestSize();
	std::optional<usb::Request<void>> req;
	status = usb::Request<void>::Alloc(&req, transfer_length,
	endpoint_addr, parent_req_size);
	usb_request_complete_t complete = {
	.callback =
	[](void* ctx, usb_request_t* request) {
	static_cast<YourDeviceClass*>(ctx)->YourHandlerFunction(request);
	},
	.ctx = this,
	};
	usb.RequestQueue(req->take(), &complete);
	```

	### C++ example (with lambdas)

	```c++
	size_t parent_size = usb_.GetRequestSize();
	using Request = usb::CallbackRequest<sizeof(std::max_align_t) * 4>;
	std::optional<Request> request;
	Request::Alloc(&request, max_packet_size, endpoint_address,
	parent_size, [=](Request request) {
	// Do some processing here.
	// ...
	// Re-queue the request
	Request::Queue(std::move(request), usb_client_);
	});
	```

	## Submission

	You can submit requests using the
	[RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22) method,
	or -- in the case of CallbackRequests (as seen [here](#c-example)), using
	`Request::Queue` or simply `request.Queue(client)`. In all cases, ownership of
	the USB request is transferred to the parent driver (usually `usb-device`).

	The typical lifecycle of a USB request (from a device driver to either a host
	controller or device controller is as follows):

	* The USB device driver queues the request
	* The `usb-device` core driver receives the request, and now owns the request
	object.
	* The `usb-device` core driver injects its own callback (if the direct flag
	is not set), or passes through the request (if the direct flag is set) to
	the HCI or DCI driver.
	* The HCI or DCI driver now owns the request. The HCI or DCI driver submits
	this request to hardware.
	* The request completes. When this happens, if the direct flag was set, the
	callback in the device driver is invoked, and the device driver now owns
	the request. If the direct flag is not set, the usb-device (core) driver
	now owns the request.
	* If the core driver owns the request; it is added to a queue for dispatch by
	another thread.
	* The core driver eventually invokes the callback, and the request is now
	owned by the device driver. The device driver can now re-submit the
	request.

	## Cancellation

	Requests may be cancelled by invoking
	[CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89). When
	[CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89) completes, all
	requests are owned by the caller. Drivers implementing a
	[CancelAll](/sdk/banjo/ddk.protocol.usb/usb.banjo#89) function (such
	as the usb-device core driver and any HCI/DCI drivers) are responsible for
	transferring ownership to their children with a `ZX_ERR_CANCELLED` status code.

	## Implementation notes for writers of HCI, DCI, or filter drivers

	### Implementing [GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96)

	The value returned by
	[GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) should
	equal the value of your parent's
	[GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96) + the size
	of your request context, including any padding that would be necessary to
	ensure proper alignment of your data structures (if applicable). If you are
	implementing an HCI or DCI driver, you must include `sizeof(usb_request_t)` in
	your size calculation in addition to any other data structures that you are
	storing. `usb_request_t` has no special alignment requirements, so it is not
	necessary to add padding for that structure.

	### Implementing [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22)

	Implementors of
	[RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22) temporarily
	assumes ownership of the USB request from its client driver. As an implementor
	of [RequestQueue](/sdk/banjo/ddk.protocol.usb/usb.banjo#22), you are
	allowed to access all fields of the `usb_request_t`, as well as any private
	data that you have appended to the `usb_request_t` structure (by requesting
	additional space through
	[GetRequestSize](/sdk/banjo/ddk.protocol.usb/usb.banjo#96)), but you
	are not allowed to modify any data outside of your private area, which starts
	at `parent_req_size` bytes (past the end of `usb_request_t`).

	## Example USB request stack (HCI)

	xHCI (host controller) -> `usb-bus` -> `usb-device` (core USB device driver) ->
	`usb-mass-storage`

	## Example USB request stack (DCI)

	`dwc2` (device-side controller) -> `usb-peripheral` (peripheral core driver) ->
	`usb-function` (core function driver) -> `cdc-eth-function` (ethernet
	peripheral mode driver)