mirror of
https://github.com/ferrous-systems/embedded-trainings-2020.git
synced 2024-05-14 22:43:05 +00:00
last batch of didactic changes
This commit is contained in:
parent
d71095251d
commit
0ea86f204e
|
@ -2,17 +2,24 @@
|
||||||
|
|
||||||
## String descriptors
|
## String descriptors
|
||||||
|
|
||||||
If you'd like to continue working on your workshop project, we recommend adding String Descriptors support to the USB firmware.
|
If you'd like to continue working on your workshop project, we recommend adding String Descriptors support to the USB firmware. To do this, follow these steps:
|
||||||
|
|
||||||
- First, you'll want to read through section 9.6.7 of the USB spec, which covers string descriptors.
|
✅ Read through section 9.6.7 of the USB spec, which covers string descriptors.
|
||||||
- Next, we suggest you change your *configuration* descriptor to use string descriptors. You'll want to change the `iConfiguration` field to a non-zero value. Note that this change will likely break enumeration.
|
|
||||||
- Now, re-run the program to see what new control requests you get from the host.
|
|
||||||
- You'll need to update the `usb` parser to handle the new requests.
|
|
||||||
- Then you can extend the logic of `ep0setup` to handle these new requests.
|
|
||||||
- Eventually, you'll need to send a string descriptor to the host. Note here that Rust string literals are UTF-8 encoded but the USB protocol uses UTF-**16** strings. You'll need to convert between these formats.
|
|
||||||
- After you have `iConfiguration` working you can start adding strings to other descriptors like the device descriptor e.g. its `iProduct` field.
|
|
||||||
|
|
||||||
To verify that string descriptors are working in a cross-platform way you can extend the `print-descs` program to also print the device's string descriptors. See the [`read_string_descriptor`] method but note that this must be called on a "device handle", which is what the commented out `open` operation does.
|
|
||||||
|
✅ Change your *configuration* descriptor to use string descriptors. You'll want to change the `iConfiguration` field to a non-zero value. Note that this change will likely break enumeration.
|
||||||
|
|
||||||
|
✅ Re-run the program to see what new control requests you get from the host.
|
||||||
|
|
||||||
|
✅ Update the `usb` parser to handle the new requests.
|
||||||
|
|
||||||
|
✅ Extend the logic of `ep0setup` to handle these new requests.
|
||||||
|
|
||||||
|
Eventually, you'll need to send a string descriptor to the host. Note here that Rust string literals are UTF-8 encoded but the USB protocol uses UTF-**16** strings. You'll need to convert between these formats.
|
||||||
|
|
||||||
|
✅ If this works, add strings to other descriptors like the device descriptor e.g. its `iProduct` field.
|
||||||
|
|
||||||
|
✅ To verify that string descriptors are working in a cross-platform way, extend the `print-descs` program to also print the device's string descriptors. See the [`read_string_descriptor`] method but note that this must be called on a "device handle", which is what the commented out `open` operation does.
|
||||||
|
|
||||||
[`read_string_descriptor`]: https://docs.rs/rusb/0.6.2/rusb/struct.DeviceHandle.html#method.read_string_descriptor
|
[`read_string_descriptor`]: https://docs.rs/rusb/0.6.2/rusb/struct.DeviceHandle.html#method.read_string_descriptor
|
||||||
|
|
||||||
|
|
|
@ -23,7 +23,7 @@ The SET_CONFIGURATION request is sent by the host to configure the device. Its c
|
||||||
- `wValue` contains the requested configuration value
|
- `wValue` contains the requested configuration value
|
||||||
- `wIndex` and `wLength` are 0, there is no `wData`
|
- `wIndex` and `wLength` are 0, there is no `wData`
|
||||||
|
|
||||||
To handle a SET_CONFIGURATION, do the following:
|
✅ To handle a SET_CONFIGURATION, do the following:
|
||||||
|
|
||||||
- If the device is in the `Default` state, you should stall the endpoint because the operation is not permitted in that state.
|
- If the device is in the `Default` state, you should stall the endpoint because the operation is not permitted in that state.
|
||||||
|
|
||||||
|
@ -38,12 +38,15 @@ To handle a SET_CONFIGURATION, do the following:
|
||||||
- if `wValue` is not valid then stall the endpoint
|
- if `wValue` is not valid then stall the endpoint
|
||||||
|
|
||||||
In all the cases where you did not stall the endpoint (by returning `Err`) you'll need to acknowledge the request by starting a STATUS stage.
|
In all the cases where you did not stall the endpoint (by returning `Err`) you'll need to acknowledge the request by starting a STATUS stage.
|
||||||
This is done by writing 1 to the TASKS_EP0STATUS register.
|
|
||||||
|
✅ This is done by writing 1 to the TASKS_EP0STATUS register.
|
||||||
|
|
||||||
NOTE: On Windows, you may get a `GET_STATUS` request *before* the `SET_CONFIGURATION` request and although you *should* respond to it, stalling the `GET_STATUS` request seems sufficient to get the device to the `Configured` state.
|
NOTE: On Windows, you may get a `GET_STATUS` request *before* the `SET_CONFIGURATION` request and although you *should* respond to it, stalling the `GET_STATUS` request seems sufficient to get the device to the `Configured` state.
|
||||||
|
|
||||||
## Expected output
|
## Expected output
|
||||||
|
|
||||||
|
✅ Run the progam and check the log output.
|
||||||
|
|
||||||
Once you are correctly handling the `SET_CONFIGURATION` request you should get logs like these:
|
Once you are correctly handling the `SET_CONFIGURATION` request you should get logs like these:
|
||||||
|
|
||||||
``` console
|
``` console
|
||||||
|
|
|
@ -1,9 +1,13 @@
|
||||||
# Inspecting the Descriptors
|
# Inspecting the Descriptors
|
||||||
|
|
||||||
There's a tool in the `advanced/host/` folder called `print-descs`. You can run this tool to print all the descriptors reported by your application.
|
There's a tool in the `advanced/host/` folder called `print-descs`, it prints all the descriptors reported by your application.
|
||||||
|
|
||||||
|
✅ Run this tool.
|
||||||
|
|
||||||
|
Your output should look like this:
|
||||||
|
|
||||||
``` console
|
``` console
|
||||||
$ print-descs
|
$ cargo run
|
||||||
DeviceDescriptor {
|
DeviceDescriptor {
|
||||||
bLength: 18,
|
bLength: 18,
|
||||||
bDescriptorType: 1,
|
bDescriptorType: 1,
|
||||||
|
|
Loading…
Reference in a new issue