Skip to content

Commit f3c4861

Browse files
smunautsmunaut
committed
Update READMEs
Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
1 parent efa854d commit f3c4861

File tree

3 files changed

+163
-27
lines changed

3 files changed

+163
-27
lines changed

‎README-bin.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Nitro μACM prebuilt
2+
===================
3+
4+
This is a pre-built distribution of the Nitro μACM core.
5+
6+
7+
Nitro μACM core:
8+
----------------
9+
10+
For details about the core itself and its interface, please
11+
refer to the top level `README.md`.
12+
13+
If you're using the binary distribution package, then
14+
this should be available here as `README-core.md`.
15+
16+
17+
License
18+
-------
19+
20+
This pre-built μACM core is a mix between CERN-OHL-P-2.0 and ISC (the
21+
latter being for the included SERV core). It also contains a firmware
22+
licensed under MIT.
23+
24+
All the details can be found in the Nitro μACM git repository
25+
( https://github.com/no2fpga/no2muacm ) but from a practical user stand
26+
point, the only thing required when using this core is attribution to :
27+
28+
- Nitro FPGA project ( Sylvain Munaut - https://github.com/no2fpga/ )
29+
- SERV ( Olof Kindgren - https://github.com/olofk/serv )

‎README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,127 @@
11
Nitro μACM
22
==========
33

4+
The Nitro μACM core is a small implementation of a USB CDC ACM device
5+
entirely in FPGA fabric using only FPGA IOs (and an external 1.5kohm
6+
resistor from the `usb_pu` to the USB DP line).
7+
8+
Features:
9+
10+
- Entirely synchronous design, running in a single clock domain at 48 MHz
11+
- For convenience, a lightweight clock-domain crossing helper is provided
12+
in the `examples/` directory if your user logic needs to run at a
13+
different rate.
14+
15+
- Simple data interface similar to AXI-stream (`data`/`last`/`valid`/`ready`)
16+
17+
- Flexible packet flushing (on-demand, immediate, after-timeout) depending
18+
on your application requirements.
19+
20+
- Exposes a DFU-Runtime interface to integrate nicely if you're using a DFU
21+
bootloader to configure your FPGA.
22+
- This allows the host to programmatically request the reset of the fpga
23+
to its bootloader mode.
24+
- Includes all the requires `WinUSB` descriptors to work out-of-the-box
25+
under Win10+ without any user intervention configuring drivers.
26+
27+
- Customizable descriptors (PID/VID/Strings/...)
28+
29+
- Designed for easy "drop-in" integration
30+
- It generates a single source file you can use as a black box component
31+
- You can either build it yourself from this repo, or use the
32+
`no2muacm-bin` repository or one of the tagged release tarball.
33+
34+
35+
Example:
36+
--------
37+
38+
Refer to the `example/` directory to see how to use the core on some real boards.
39+
40+
41+
Building:
42+
---------
43+
44+
Currently the core is only setup for `iCE40` builds. Other FPGA targets will be
45+
coming soon. Feel free to open an issue if you have a particular need.
46+
47+
To build the core you will need the corresponding OSS toolchain for your target
48+
and a RISC-V compiler (default is using `riscv-none-embed-` prefix. Change with
49+
`CROSS` environment variable).
50+
51+
```bash
52+
$ cd gateware
53+
$ make
54+
```
55+
56+
This will create a `build/` directory with both a `muacm.v` and `muacm.ilang`
57+
(select whichever you prefer) that you can integrate as a single source file
58+
in your own project.
59+
60+
To integrate the core in your own project you can either:
61+
62+
- Just add this pre-built source as-is in your project for minimum hassle.
63+
64+
- Add this repository as a submodule and call the `make` step from your own
65+
build system.
66+
67+
- Add the `no2muacm-bin` repository as a submodule which should always contain
68+
pre-built version of the latest release of this core.
69+
70+
71+
Customization:
72+
--------------
73+
74+
You can customize several aspects of this core. Some of them can even be
75+
changed after synthesis in the pre-built core directly (useful if you plan
76+
to use `no2muacm-bin` releases.
77+
78+
To customize prior to building, the most relevant file is `firmware/usb_desc.c`
79+
which contains all the USB descriptors that will be included and should be
80+
self-explanatory.
81+
82+
To customize the pre-built netlist, a special python tool called
83+
`muacm_customize.py` is provided in `utils/`. Refer to the `--help` to see
84+
how to use it. This will allow direct patching of VID/PID/Strings inside
85+
the netlist. Note that strings are limited to 16 chars in this case (since
86+
space is pre-reserved during build).
87+
88+
89+
Clocking:
90+
---------
91+
92+
As mentionned in the "Features" above, the core runs entirely at 48 MHz.
93+
94+
The requirements on the clock are pretty wide, the USB specification only requires
95+
it to be within 2500 ppm. And the clock-recovery mechanism used here is capable
96+
of decoding packets with much wider clock range. For instance, this core has been
97+
used sucessfully with the _iCE40_ `SB_HFOSC` which is 48 MHz +- 10%. YMMV though.
98+
99+
100+
Data interface:
101+
---------------
102+
103+
The data interface is synchronous to the clock of the μACM module
104+
and is essentially a pair of AXI Streaming interfaces, one for
105+
RX and one for TX.
106+
107+
- `data` is the 8 bit data to/from the host
108+
109+
- `last` is the packet delineation marker. For `out` (i.e. from host to
110+
FPGA) it indicates the USB packets boundary as received from the host.
111+
For `in`, it can be used to force sending short packets.
112+
113+
- `valid` and `ready` are the handshake signals. Data transfer happens
114+
when both signals are high on the same cycle.
115+
116+
The `in` interface also has two additional control signals that are
117+
independent from the streaming interface :
118+
119+
- `in_flush_now`: Indicates that whatever pending data is still in buffers
120+
should be sent to the host ASAP.
121+
122+
- `in_flush_time`: Indicates that any pending data can be sent to the host
123+
after some reasonable timeout (to avoid data staying in buffer waiting to
124+
fill a full USB packet).
4125

5126

6127
License

‎example/README.md‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,22 @@ domain boundary from the USB domain into any other clock domain
2525
as required by the user application.
2626

2727

28+
Nitro μACM core:
29+
----------------
30+
31+
For details about the core itself and its interface, please
32+
refer to the top level `README.md`.
33+
34+
If you're using the example binary distribution package, then
35+
this should be available here as `README-core.md`.
36+
37+
2838
Clocking Infos:
2939
---------------
3040

31-
As mentionned above, the μACM core itself is required to run
32-
at 48 MHz to operate properly (USB is 12 MBits and we use 4x
33-
oversampling for clock recovery).
41+
The μACM core itself is required to run at 48 MHz to operate
42+
properly (USB is 12 MBits and we use 4x oversampling for clock
43+
recovery).
3444

3545
In this project the 48 MHz clock can come from 2 sources depending
3646
on the `HFOSC` define at the top of `top.v`:
@@ -87,30 +97,6 @@ at the beginning of `top.v` or by changing some `localparam` :
8797
to trigger a reboot to `foboot`.
8898

8999

90-
Data interface:
91-
---------------
92-
93-
The data interface is synchronous to the clock of the μACM module
94-
and is essentially a pair of AXI Streaming interfaces, one for
95-
RX and one for TX.
96-
97-
- `data` is the 8 bit data to/from the host
98-
- `last` is the packet delineation marker. For `out` (i.e. from host to
99-
FPGA) it indicates the USB packets boundary as received from the host.
100-
For `in`, it can be used to force sending short packets.
101-
- `valid` and `ready` are the handshake signals. Data transfer happens
102-
when both signals are high on the same cycle.
103-
104-
The `in` interface also has two additional control signals that are
105-
independent from the streaming interface :
106-
107-
- `in_flush_now`: Indicates that whatever pending data is still in buffers
108-
should be sent to the host ASAP.
109-
- `in_flush_time`: Indicates that any pending data can be sent to the host
110-
after some reasonable timeout (to avoid data staying in buffer waiting to
111-
fill a full USB packet).
112-
113-
114100
Build:
115101
------
116102

0 commit comments

Comments
 (0)