From 138cb1909f7ff60c938781eb3414315f001cefc4 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Thu, 16 Jul 2020 11:21:55 +0200 Subject: [PATCH] add USB diagrams --- .../src/control-transfers.md | 6 +- .../src/device-descriptor.md | 4 + .../src/get-descriptor-config.md | 20 +- .../src/usb-all-endpoints.svg | 285 ++++++++++++++++++ .../src/usb-configuration.svg | 285 ++++++++++++++++++ embedded-workshop-book/src/usb-control.svg | 285 ++++++++++++++++++ embedded-workshop-book/src/usb-device.svg | 285 ++++++++++++++++++ embedded-workshop-book/src/usb-endpoint.svg | 285 ++++++++++++++++++ embedded-workshop-book/src/usb-endpoints.md | 10 +- embedded-workshop-book/src/usb-interface.svg | 285 ++++++++++++++++++ embedded-workshop-book/src/usb.svg | 285 ++++++++++++++++++ 11 files changed, 2031 insertions(+), 4 deletions(-) create mode 100644 embedded-workshop-book/src/usb-all-endpoints.svg create mode 100644 embedded-workshop-book/src/usb-configuration.svg create mode 100644 embedded-workshop-book/src/usb-control.svg create mode 100644 embedded-workshop-book/src/usb-device.svg create mode 100644 embedded-workshop-book/src/usb-endpoint.svg create mode 100644 embedded-workshop-book/src/usb-interface.svg create mode 100644 embedded-workshop-book/src/usb.svg diff --git a/embedded-workshop-book/src/control-transfers.md b/embedded-workshop-book/src/control-transfers.md index e2b358d..4278470 100644 --- a/embedded-workshop-book/src/control-transfers.md +++ b/embedded-workshop-book/src/control-transfers.md @@ -1,9 +1,13 @@ # Control Transfers +

+ TODO +

+ Before we continue we need to discuss how data transfers work under the USB protocol. The control pipe handles *control transfers*, a special kind of data transfer used by the host to issue *requests*. A control transfer is a data transfer that occurs in three stages: a SETUP stage, an optional DATA stage and a STATUS stage. During the SETUP stage the host sends 8 bytes of data that identify the control request. Depending on the issued request there may be a DATA stage or not; during the DATA stage data is transferred either from the device to the host or the other way around. During the STATUS stage the device acknowledges, or not, the whole control request. -For detailed information about control transfers check section 5.5, Control Transfers, of the [USB 2.0 specification][usb20]. \ No newline at end of file +For detailed information about control transfers check section 5.5, Control Transfers, of the [USB 2.0 specification][usb20]. diff --git a/embedded-workshop-book/src/device-descriptor.md b/embedded-workshop-book/src/device-descriptor.md index f995d1c..220796b 100644 --- a/embedded-workshop-book/src/device-descriptor.md +++ b/embedded-workshop-book/src/device-descriptor.md @@ -1,5 +1,9 @@ # Device Descriptor +

+ TODO +

+ After receiving a GET_DESCRIPTOR request during the SETUP stage the device needs to respond with a *descriptor* during the DATA stage. A descriptor is a binary encoded data structure sent by the device to the host. The device descriptor, in particular, contains information about the device, like its product and vendor identifiers and how many *configurations* it has. The format of the device descriptor is specified in section 9.6.1, Device, of the USB specification. diff --git a/embedded-workshop-book/src/get-descriptor-config.md b/embedded-workshop-book/src/get-descriptor-config.md index 6b8b1c5..28a5801 100644 --- a/embedded-workshop-book/src/get-descriptor-config.md +++ b/embedded-workshop-book/src/get-descriptor-config.md @@ -8,6 +8,10 @@ We have covered configurations and endpoints but what is an *interface*? ## Interface +

+ TODO +

+ An interface is closest to a USB device's function. For example, a USB mouse may expose a single HID (Human Interface Device) interface to report user input to the host. USB devices can expose multiple interfaces within a configuration. For example, the nRF52840 Dongle could expose both a CDC ACM interface (AKA virtual serial port) *and* a HID interface; the first interface could be used for (`log::info!`-style) logs; and the second one could provide a RPC (Remote Procedure Call) interface to the host for controlling the nRF52840's radio. An interface is made up of one or more *endpoints*. To give an example, a HID interface can use two (interrupt) endpoints, one IN and one OUT, for bidirectional communication with the host. A single endpoint cannot be used by more than one interface with the exception of the special "endpoint 0", which can be (and usually is) shared by all interfaces. @@ -16,6 +20,10 @@ For detailed information about interfaces check section 9.6.5, Interface, of the ## Configuration descriptor +

+ TODO +

+ The configuration descriptor describes one of the device configurations to the host. The descriptor contains the following information about a particular configuration: - the total length of the configuration: this is the number of bytes required to transfer this configuration descriptor and the interface and endpoint descriptors associated to it @@ -29,6 +37,10 @@ The configuration descriptor describes one of the device configurations to the h ## Interface descriptor +

+ TODO +

+ The interface descriptor describes one of the device interfaces to the host. The descriptor contains the following information about a particular interface: - its interface number -- this is a zero-based index @@ -41,16 +53,20 @@ The number of endpoints can be zero and endpoint zero must not be accounted when ## Endpoint descriptor +

+ TODO +

+ We will not need to deal with endpoint descriptors in this workshop but they are specified in section 9.6.6, Endpoint, of the USB specification. ## Response So how should we respond to the host? As our only goal is to be enumerated we'll respond with the minimum amount of information possible. -**First, check the request:** +**First, check the request:** Configuration descriptors are requested by *index*, not by their configuration value. Since we reported a single configuration in our device descriptor the index in the request must be zero. Any other value should be rejected by stalling the endpoint (see section [Dealing with unknown requests: Stalling the endpoint](./unknown-requests.md#dealing-with-unknown-requests-stalling-the-endpoint) for more information). -**Next, create and send a response:** +**Next, create and send a response:** The response should consist of the configuration descriptor, followed by interface descriptors and then by (optional) endpoint descriptors. We'll include a minimal single interface descriptor in the response. Since endpoints are optional we will include none. diff --git a/embedded-workshop-book/src/usb-all-endpoints.svg b/embedded-workshop-book/src/usb-all-endpoints.svg new file mode 100644 index 0000000..80ab1eb --- /dev/null +++ b/embedded-workshop-book/src/usb-all-endpoints.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb-configuration.svg b/embedded-workshop-book/src/usb-configuration.svg new file mode 100644 index 0000000..b4b761f --- /dev/null +++ b/embedded-workshop-book/src/usb-configuration.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb-control.svg b/embedded-workshop-book/src/usb-control.svg new file mode 100644 index 0000000..d1daa14 --- /dev/null +++ b/embedded-workshop-book/src/usb-control.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb-device.svg b/embedded-workshop-book/src/usb-device.svg new file mode 100644 index 0000000..5044057 --- /dev/null +++ b/embedded-workshop-book/src/usb-device.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb-endpoint.svg b/embedded-workshop-book/src/usb-endpoint.svg new file mode 100644 index 0000000..6c6256a --- /dev/null +++ b/embedded-workshop-book/src/usb-endpoint.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb-endpoints.md b/embedded-workshop-book/src/usb-endpoints.md index 2e54496..69819d2 100644 --- a/embedded-workshop-book/src/usb-endpoints.md +++ b/embedded-workshop-book/src/usb-endpoints.md @@ -1,13 +1,21 @@ # USB Endpoints +

+ TODO +

+ Under the USB protocol data transfers occur over *endpoints*. Endpoints are similar to UDP or TCP ports in that they allow logical multiplexing of data over a single physical USB bus. USB endpoints, however, have directions: an endpoint can either be an IN endpoint or an OUT endpoint. The direction is always from the perspective of the host so at an IN endpoint data travels from the device to the host and at an OUT endpoint data travels from the host to the device. Endpoints are identified by their address, a zero-based index, and direction. There are four types of endpoints: control endpoints, bulk endpoints, interrupt endpoints and isochronous endpoints. Each endpoint type has different properties: reliability, latency, etc. In this workshop we'll only need to deal with control endpoints. +

+ TODO +

+ All USB devices must use "endpoint 0" as the default control endpoint. "Endpoint 0" actually refers to two endpoints: endpoint 0 IN and endpoint 0 OUT. This endpoint pair is used to establish a *control pipe*, a bidirectional communication channel between the host and device where data is exchanged using a predefined format. The default control pipe over endpoint 0 is mandatory: it must always be present and must always be active. For detailed information about endpoints check section 5.3.1, Device Endpoints, of the [USB 2.0 specification][usb20]. -[usb20]: https://www.usb.org/document-library/usb-20-specification \ No newline at end of file +[usb20]: https://www.usb.org/document-library/usb-20-specification diff --git a/embedded-workshop-book/src/usb-interface.svg b/embedded-workshop-book/src/usb-interface.svg new file mode 100644 index 0000000..4cd2b2e --- /dev/null +++ b/embedded-workshop-book/src/usb-interface.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + + diff --git a/embedded-workshop-book/src/usb.svg b/embedded-workshop-book/src/usb.svg new file mode 100644 index 0000000..2ede1f4 --- /dev/null +++ b/embedded-workshop-book/src/usb.svg @@ -0,0 +1,285 @@ + + + + + + + + image/svg+xml + + + + + + + + + configuration 1 + device + + interface 0 + + control endpoint + + + bNumConfigurations=1 + + + bNumInterfaces=1 + bNumEndpoints=3 + + endpoint 0 IN + + endpoint 0 OUT + + endpoint 1 IN + + endpoint 2 OUT + + endpoint 2 IN + +