update docs with new IO core options
This commit is contained in:
Fischer Moseley
parent
b4fb79bc8e
commit
3ce8594247
|
|
@ -10,7 +10,7 @@ Just like the rest of the cores, the IO core is configured via an entry in a pro
|
|||
|
||||
```yaml
|
||||
---
|
||||
the_muppets:
|
||||
my_io_core:
|
||||
type: io
|
||||
|
||||
inputs:
|
||||
|
|
@ -18,41 +18,33 @@ the_muppets:
|
|||
piggy: 1
|
||||
animal: 38
|
||||
scooter: 4
|
||||
initial: 13
|
||||
|
||||
outputs:
|
||||
fozzy: 1
|
||||
gonzo: 3
|
||||
|
||||
user_clock: True
|
||||
```
|
||||
This configuration specifies four parameters:
|
||||
Inside this configuration, the following parameters may be configured:
|
||||
|
||||
- `name`: The name of the IO core. This name is used to reference the core when working with the API, and can be whatever you'd like.
|
||||
- `type`: This denotes that this is an IO core. All cores contain a `type` field, which must be set to `io` to be recognized as an IO core.
|
||||
- `inputs`: This lists all inputs from from the FPGA fabric to the host machine. Signals in this list may be read by the host, but ___cannot___ be written to.
|
||||
- `outputs`: This lists all outputs from the host machine to the FPGA fabric. Signals in this list may be written by the host, but ___can___ also be read from, and doing so returns the value last written to the register.
|
||||
- `name` _(required)_: The name of the IO core. This name is used to reference the core when working with the API, and can be whatever you'd like.
|
||||
- `type` _(required)_: This denotes that this is an IO core. All cores contain a `type` field, which must be set to `io` to be recognized as an IO core.
|
||||
- `inputs` _(optional)_: This lists all inputs from from the FPGA fabric to the host machine. Signals in this list may be read by the host, but ___cannot___ be written to. Technically specifying input probes is totally optional - it's perfectly fine to have an IO core with only output probes.
|
||||
- `outputs` _(optional)_: This lists all outputs from the host machine to the FPGA fabric. Signals in this list are usually written to by the host, but they can also be read from. Doing so returns the value last written to the register. Just like the `inputs` parameter, this list is techically optional, and it's perfectly valid to have an IO core with input probes only.
|
||||
- `initial_value` _(optional)_: This sets an initial value for an output probe to take after the FPGA powers on. This is done with an `initial` statement in Manta's Verilog, and is independent of the input clock or resets elsewhere in the FPGA. This parameter is optional, and if it isn't provided the probe will initialize to zero.
|
||||
- `user_clock` _(optional)_: If set to True, an extra input port will be added to the `manta` module for an clock input to run the IO core on. This lets the IO Core handle clock domain crossing through its internal buffers. If set to False, Manta will run the IO core from its internal clock (the one provided through `manta`'s `clk` port). More information on this is available in the [diagram](#how-it-works) below. This parameter is optional, and defaults to False.
|
||||
|
||||
Lastly, the name of the core and the names of the probes are referenced in the autogenerated Verilog. This means that while the names can be arbitrary, they must be unique within your project and not contain any characters that your synthesis engine won't appreciate. As an example, here's an instance of what the autogenerated module would look like for the configuration above:
|
||||
!!! warning "Name things carefully!"
|
||||
|
||||
```verilog
|
||||
manta manta_inst (
|
||||
.clk(clk),
|
||||
|
||||
.rx(rx),
|
||||
.tx(tx),
|
||||
|
||||
.kermit(kermit),
|
||||
.piggy(piggy),
|
||||
.animal(animal),
|
||||
.scooter(scooter),
|
||||
.fozzy(fozzy),
|
||||
.gonzo(gonzo));
|
||||
```
|
||||
The names of the core and its probes are referenced in the autogenerated Verilog. This means that while the names can be arbitrary, they must be unique within your project and not contain any characters that your synthesis engine won't appreciate.
|
||||
|
||||
|
||||
## Python API
|
||||
|
||||
The IO core functionality is stored in the `Manta.IOCore` and `Manta.IOCoreProbe` classes in [src/manta/io_core/\_\_init\_\_.py](https://github.com/fischermoseley/manta/blob/main/src/manta/io_core/__init__.py), and it may be controlled with the two functions:
|
||||
The IO core functionality is stored in the `Manta.IOCore`, `Manta.InputProbe`, and `Manta.OutputProbe` classes in [src/manta/io_core/\_\_init\_\_.py](https://github.com/fischermoseley/manta/blob/main/src/manta/io_core/__init__.py), and it may be controlled with the two functions:
|
||||
|
||||
`Manta.IOCoreProbe.set(int, bool data)`
|
||||
`Manta.IOCoreProbe.set(data)`
|
||||
|
||||
- [`int`, `bool`] _data_: The value to write to an output probe. May be signed or unsigned, but will raise an exception if the value is too large for the width of the port.
|
||||
- _returns_: None
|
||||
|
|
@ -61,7 +53,7 @@ This method is blocking. When called it will dispatch a request to the FPGA, and
|
|||
|
||||
---
|
||||
|
||||
`Manta.IOCoreProbe.set()`
|
||||
`Manta.IOCoreProbe.get()`
|
||||
|
||||
- _returns_: The value of an input or output probe. In the case of an output probe, the value returned will be the last value written to the probe.
|
||||
|
||||
|
|
@ -101,4 +93,4 @@ This is done with the architecture shown below:
|
|||
|
||||
Each of the probes is mapped to a register of Manta's internal memory. Since Manta's internal registers are 16 bits wide, probes less than 16 bits are mapped to a single register, but probes wider than 16 bits require multiple.
|
||||
|
||||
Whatever the number of registers required, these are read from and written to by the host machine - but the connection to the user's logic isn't direct. The value of each probe is buffered, and only once the `strobe` register has been set to one will the buffers update. When this happens, output probes provide new values to user logic, and new values for input probes are read from user logic. This provides a convenient place to perform clock domain crossing, and also mitigates the possibility of an inconsistent system state. More details on this can be found in Chapter 3.6 of the [original thesis](thesis.pdf).
|
||||
Whatever the number of registers required, these are read from and written to by the host machine - but the connection to the user's logic isn't direct. The value of each probe is buffered, and only once the `strobe` register has been set to one will the buffers update. When this happens, output probes provide new values to user logic, and new values for input probes are read from user logic. This provides a convenient place to perform clock domain crossing, and also mitigates the possibility of an inconsistent system state. This is explained in more detail in Chapter 3.6 of the [original thesis](thesis.pdf).
|
||||
Loading…
Reference in New Issue