A library to use Digilent Arty A7 Boards with Hardcaml.
This library has been tested with Arty A7 35 and Arty A7 100.
This library provides a wrapper for the following features in Arty A7 boards:
- A 166.66667MHz clock and its corresponding synchronous active low clear.
- A 200MHz clock and its corresponding synchronous active low clear.
- Control bits (on/off) for the board's LEDs.
- Control bits (on/off for r, g, and b) for the board's RGB LEDs.
- UART receive and transmit data streams.
- Ethernet receive and transmit data streams.
This section describes what you'll need to add to an existing Hardcaml design in order to turn it into a bitstream that can run on an Arty A7 board.
See examples/blinker for an example, reference files to copy into your own project, and instructions on how to:
- Install some necessary programs/utilities.
- Generate the bitstream.
- Load it onto your board.
boards folder from examples/blinker into the top-level directory of your project.
This tells Vivado which board to use when compiling your design, provides some configuration for said board, and sets human-readable names for the board's pins that will be used later on in the constraint files.
ips folder from examples/blinker into the top-level directory of your project.
This library makes use of several Xilinx IPs:
- The clocking wizard, used for generating aforementioned clock/clear signals from the board's system clock (Manual).
- The Tri-Mode Ethernet MAC, used for supporting Ethernet communication (Manual).
Please note that while the clocking wizard is provided alongside Vivado software installation, the ethernet MAC requires a special license. See the examples/blinker README for more information.
RTL Generation Executable
Essentially, this library works by taking a Hardcaml subcircuit that contains your design, and wrapping to abstract away some messy infrastructure / IP interaction so you can work with a clean, simple API.
This means you will need to give it a subcircuit that implements the
User_application.O Hardcaml interfaces. Once you have that, you can use this library's
Rtl_generator.generate function to generate Arty A7-compatible Verilog output.
We recommmend creating an
arty.ml file (with the corresponding
dune config to make it an executable) in the top-level directory of your project that defines a
create function which wraps your design to input/output the aforementioned
User_application interfaces, then define a main function:
let () = Hardcaml_arty.Rtl_generator.generate create (To_channel Stdio.stdout) ;;
Makefile files from [examples/blinker) into the top-level directory of your project.
These files instruct Vivado to generate the bitstream for your design:
synth.tclsynthesizes your design into a netlist, including the aforementioned IPs.
place.tclbinds the input and output ports used by this library's wrapper module to pins on the board, and runs implementation.
route.tclgenerates the bitstream.
Makefile links these build steps together. You'll need to adjust it slightly for the RTL generation executable you made in the previous step (e.g. replacing "blinker" with "arty").
Makefile requires a
BOARD env variable parameter which can be either
How to Run
Now, all that's left is to actually generate a bitstream and load it onto your board! Follow the instructions at examples/blinker, adapting to your project's directory structure.
Board Tools Reference
This section is a summary of the tools offered by this library to interact with some of the less trivial Arty A7 components, notably UART and Ethernet.
UART input/output data streams are encoded as a Hardcaml With_valid record, which has
value is an 8-bit wire that represents the last 8 received UART data bits, with the MSB corresponding to the most recently received bit.
1 when every 8th UART bit is received; that is, when every byte has been completely received.
The UART uses the 166.66667MHz clock signal and corresponding clear, and processes one bit every
166_667_000 / 115_200 = 1446 cycles.