Skip to content

Commit 3586898

Browse files
benedekkupperbenedekkupper
committed
readme updates
1 parent c263b00 commit 3586898

7 files changed

Lines changed: 213 additions & 117 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,26 @@
1-
# Configurable Composite USB device library
1+
# Configurable Composite (c2) USB device library
22

3-
This is the 2nd generation of my composite USB device library,
4-
which is the most flexible and configurable open-source USB device stack so far.
3+
This is a 2nd generation USB device library,
4+
designed with an emphasis of maximum flexibility for configurability and composability.
55
The device framework is designed to scale well to designs of any complexity,
66
and to make the high level functionality as portable as possible.
77

8-
The core of the flexibility and portability is the manual high-level definition
9-
of each USB configuration, which consists of:
10-
1. Power configuration
11-
2. List of USB functions with their assigned endpoints
12-
13-
This manual definition allows for a device framework with multiple number of configurations
14-
for each bus speed (and even alternative configurations for MS Windows OS),
15-
that can be easily modified at runtime as well.
16-
17-
This codebase is written in C++20, as it allows better abstractions, encapsulation,
18-
type safety, etc as C. Implementing the same logic in C would have required
19-
a considerable amount of preprocessor macros,
20-
which would have made the library much harder to use correctly.
21-
Thanks to C++, there is also no need for a configuration header full of preprocessor defines.
22-
Note that the codebase has no dynamic memory allocations nor any other expensive C++
23-
standard library dependency. Its optimized build produces a code size on par with
24-
C libraries of similar functionality.
8+
The use of the C++(20) language is integral to the project's design.
9+
That doesn't mean dynamic allocation or use of exceptions, but instead
10+
accurate abstractions, encapsulation, type safety, polymorphism.
2511

2612
## Features
2713

28-
* USB 2.0(.1) specification compliant stack
14+
* USB 2.0(.1) specification compliant full and high-speed stack
2915
* self-describing objects -> no manual implementation of any USB descriptors
3016
* efficient RAM usage
3117

18+
### Platforms
19+
20+
The library integrates as a **west module** into the following platforms:
21+
* NXP MCUXpresso (see [mcux](mcux) directory)
22+
* Zephyr RTOS (see [zephyr](zephyr) directory)
23+
3224
### Device classes
3325

3426
#### HID - Human Interface Device Class
@@ -48,12 +40,6 @@ The Abstract Control Model of Communications Device Class is fully implemented.
4840
Notably the notification endpoint can be marked as unused, skipping any hardware resource allocation,
4941
but keeping compatibility with all hosts.
5042

51-
### Platforms
52-
53-
* NXP MCUs supported via `mcux_mac` (see [c2usb/port/nxp](c2usb/port/nxp))
54-
* Zephyr RTOS supported via `udc_mac` (see [c2usb/port/zephyr](c2usb/port/zephyr))
55-
* support the project to see more!
56-
5743
### Vendor extensions
5844

5945
#### Microsoft OS descriptors

‎c2usb/port/nxp/README.md‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

‎c2usb/port/zephyr/README.md‎

Lines changed: 0 additions & 62 deletions
This file was deleted.

‎c2usb/usb/df/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# USB Device Framework (usb::df)
2+
3+
`usb::df` is a high-level USB device framework that separates:
4+
5+
1. Device policy and configuration modeling
6+
2. USB class/function logic (HID, CDC-ACM, vendor functions)
7+
3. Hardware/RTOS USB controller integration (MAC implementations)
8+
9+
The key design idea is that a USB configuration is defined manually at a high level
10+
as a static composition of:
11+
12+
1. Power properties
13+
2. Interfaces bound to function objects
14+
3. Endpoints bound to those interfaces
15+
16+
The framework then uses those definitions to build descriptors and route control/data
17+
transfers without requiring descriptor blobs handwritten by the application.
18+
This manual definition allows for a device framework with multiple number of configurations
19+
for each bus speed (and even alternative configurations for MS Windows OS),
20+
that can be easily modified at runtime as well.
21+
22+
## Design goals
23+
24+
- Portable high-level USB function logic across platforms
25+
- Explicit, static configuration composition (no hidden dynamic behavior)
26+
- No dynamic memory requirement in the framework core
27+
- Runtime selection of configuration sets (including per-speed lists)
28+
- Support for vendor/device extensions without forking core device logic
29+
30+
## Core concepts
31+
32+
### 1) Function objects
33+
34+
A `usb::df::function` is the base class for USB functions. Subclasses implement class
35+
behavior and descriptor contribution.
36+
37+
Responsibilities of a function:
38+
39+
- Contribute to configuration descriptor via `describe_config(...)`
40+
- Handle control requests routed to its interfaces/endpoints
41+
- Manage its assigned endpoints while it is active
42+
- Optionally own string descriptor indices
43+
44+
Examples in-tree:
45+
46+
- `usb::df::hid::function`
47+
- `usb::df::cdc::acm::function`
48+
- `usb::df::microsoft::xfunction`
49+
50+
### 2) Configuration model
51+
52+
The `usb::df::config` configuration model is built around fixed-size elements:
53+
54+
- `power`: bus/self/shared power + remote wakeup + max current
55+
- `header`: configuration metadata (`power` + optional name + computed size)
56+
- `interface`: binds one interface entry to a function object
57+
- `endpoint`: endpoint descriptor plus internal flags
58+
59+
The tests in `test/usb/df/config.test.cpp` demonstrate intended behavior,
60+
including reverse iteration, endpoint lookup, interface endpoint views,
61+
active-vs-unused endpoint filtering, and list handling.
62+
63+
### 3) Device controller
64+
65+
`usb::df::device` handles standard device-level control flow:
66+
67+
- standard requests (`GET_DESCRIPTOR`, `SET_CONFIGURATION`, etc.)
68+
- interface and endpoint recipient request routing
69+
- active configuration transitions
70+
- string descriptor ownership and dispatch
71+
- BOS descriptor assembly
72+
- power/state event signaling to application
73+
74+
`usb::df::device_instance<SPEEDS, MAX_CONFIG_LIST_SIZE>` stores and serves
75+
configuration lists per speed and provides convenience APIs for single-config devices.
76+
77+
### 4) MAC abstraction
78+
79+
`usb::df::mac` is the hardware/driver abstraction used by `device` and `function` objects.
80+
It provides:
81+
82+
- bus attach/detach and reset integration
83+
- control transfer staging
84+
- endpoint open/close/send/receive/stall operations
85+
- active endpoint mapping helpers
86+
87+
Platform ports implement concrete behavior (for example Zephyr UDC and NXP MCUX).
88+
89+
### 5) Extension mechanism
90+
91+
`usb::df::device::extension` extensions can hook device behavior without modifying core classes:
92+
93+
- bus reset reaction
94+
- extra string ownership
95+
- descriptor/control request augmentation
96+
- speed-specific config override
97+
- BOS capability contribution
98+
99+
Microsoft OS 2.0 support is implemented through this extension model.
100+
101+
## Architecture at a glance
102+
103+
Typical flow:
104+
105+
1. Application creates function objects
106+
2. Application builds one or more `config::view` definitions
107+
3. Application registers configs in `device_instance`
108+
4. Application opens device (`device.open()`)
109+
5. Host enumerates; `device` builds descriptors by asking each function
110+
6. Host selects configuration; functions are initialized and endpoints opened
111+
7. Class/data traffic is routed between `device`, `function`, and `mac`
112+
113+
Layering:
114+
115+
- Application: owns function instances and selected configuration sets
116+
- `usb::df` core: descriptor generation, control routing, lifecycle orchestration
117+
- Port MAC: interacts with USB controller driver/RTOS
118+
119+
## Practical extension points
120+
121+
For new class/vendor development:
122+
123+
1. Derive from `usb::df::function` or `usb::df::named_function`
124+
2. Implement `describe_config(...)`
125+
3. Implement control request handlers as needed
126+
4. Implement enable/disable and transfer callbacks
127+
5. Provide a `config(...)` helper to simplify integration
128+
129+
For device-wide customization:
130+
131+
1. Derive from `usb::df::device::extension`
132+
2. Override only the hooks needed
133+
3. Inject extension instance into `device_instance` constructor

‎mcux/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# NXP MCUXpresso SDK support
2+
3+
This library integrates into MCUXpresso SDK builds as a west module.
4+
The contents of this directory tree are for supporting this SDK.
5+
6+
## Examples
7+
8+
You need a basic understanding of the [platform][mcuxpresso], and usage of the [`west`][west] tool.
9+
For developing within this project using **MCUXpresso for VS Code**,
10+
open [mcux.code-workspace](mcux.code-workspace) with `vscode`.
11+
This allows building and running the examples available in [examples](examples).
12+
The [arm-gcc](../.github/workflows/arm-gcc.yml) github action illustrates the command line build flow.
13+
14+
The first step is to initialize the workspace folder (``c2usb-workspace``) where
15+
this repository and all Zephyr modules will be cloned. Run the following
16+
command:
17+
18+
```shell
19+
west init -m https://github.com/IntergatedCircuits/c2usb c2usb-workspace -mf west4mcuxsdk.yml
20+
cd c2usb-workspace
21+
# fetch all required dependencies and apply any patches (always run these in a chain)
22+
west update && west patch
23+
```
24+
25+
### usb-keyboard
26+
27+
A straightforward USB HID keyboard to illustrate a minimal project integration.
28+
Use the button on the board to trigger a caps lock press, and observe as the host changes the caps lock state on the board's LED.
29+
30+
[mcuxpresso]: https://mcuxpresso.nxp.com/mcuxsdk/latest/html/index.html
31+
[west]: https://docs.zephyrproject.org/latest/develop/west/index.html

‎mcux/import_mcuxsdk.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,5 @@ manifest:
2020
- mcuxsdk-tool-data
2121
- mcux-soc-svd
2222
- mcux-devices-kinetis
23+
# TODO: allow more device lines
2324
- usb

‎zephyr/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Zephyr-RTOS support
2+
3+
This library integrates into zephyr builds as a west module.
4+
The contents of this directory tree are for supporting SDKs based on the zephyr framework.
5+
6+
## Examples
7+
8+
You need a basic understanding of the [framework][zephyr], and usage of the [`west`][west] tool.
9+
For developing within this project using **nRF Connect**,
10+
open [zephyr.code-workspace](zephyr.code-workspace) with `vscode`.
11+
This allows building and running the examples available in [examples](examples).
12+
The [zephyr](../.github/workflows/zephyr.yml) github action illustrates the command line build flow.
13+
14+
The first step is to initialize the workspace folder (``c2usb-workspace``) where
15+
this repository and all Zephyr modules will be cloned. Run the following
16+
command:
17+
18+
```shell
19+
west init -m https://github.com/IntergatedCircuits/c2usb c2usb-workspace -mf west4nrfsdk.yml
20+
cd c2usb-workspace
21+
# fetch all required dependencies and apply any patches (always run these in a chain)
22+
west update && west patch
23+
```
24+
25+
### usb-keyboard
26+
27+
A straightforward USB HID keyboard to illustrate a minimal project integration.
28+
Use the button on the board to trigger a caps lock press, and observe as the host changes the caps lock state on the board's LED.
29+
30+
### usb-shell
31+
32+
Demonstrating USB serial port functionality with shell access to the zephyr OS.
33+
34+
[zephyr]: https://docs.zephyrproject.org/latest/index.html
35+
[west]: https://docs.zephyrproject.org/latest/develop/west/index.html

0 commit comments

Comments
 (0)