Skip to content

IO Core

Overview

Registers are a fundamental building block of digital hardware, and the IO core provides a simple way of interacting with them from the host machine. It allows you to define a set of inputs and outputs of arbitrary width, and then set values to the outputs and read values from the inputs.

This is a very, very simple task - and while configuration is straightforward, there are a few caveats. More on both topics below:

Configuration

Just like the rest of the cores, the IO core is configured via an entry in a project's configuration file. This is easiest to show by example:

---
my_io_core:
  type: io

  inputs:
    kermit: 3
    piggy: 1
    animal: 38
    scooter:
      width: 4
      initial_value: 13

  outputs:
    fozzy: 1
    gonzo: 3

  user_clock: True
Inside this configuration, the following parameters may be configured:

  • 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 technically 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 below. This parameter is optional, and defaults to False.

Name things carefully!

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 class in src/manta/io_core/__init__.py, and it may be controlled with the two functions:

Manta.IOCore.set_probe(name, data)

  • [string] name: The probe to write to. Must not be an output port, and must match the name provided in the config file.
  • [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

This method is blocking. When called it will dispatch a request to the FPGA, and halt execution until the request has been sent.

Manta.IOCore.get_probe(name)

  • [string] name: The probe to read from. May be either an input or an output port, and must match the name provided in the config file.
  • 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.

This method is blocking. When called it will dispatch a request to the FPGA, and halt execution until the request has been sent and a response has been received.

Example

A small example is shown below, using the example configuration above. More extensive examples can also be found in the repository's examples/ folder.

>>> import Manta
>>> m = Manta
>>> m.my_io_core.set_probe("fozzy", True)
>>> m.my_io_core.get_probe("fozzy")
True
>>> m.my_io_core.set_probe("gonzo", 4)
>>> m.my_io_core.get_probe("scooter")
5

Limitations

While the IO core performs a very, very simple task, it carries a few caveats.

  • First, it's not instantaneous. Manta has designed to be as fast as possible, but setting and querying registers relies on passing messages between the host and FPGA, which is slow relative to FPGA clock speeds! If you're trying to set values in your design with cycle-accurate timing, this will not do that for you. However, the Logic Analyzer's playback feature might be helpful.

  • Second, the API methods are blocking, and will wait for a response from the FPGA before resuming program execution. Depending on your application, you might want to run your IO Core operations in a separate thread, but you can also decrease the execution time by using a faster interface between the host and FPGA. This means using a higher UART baudrate, or using Ethernet.