Three files are required to build a system with CoRAM:

1. The core logic source code file, commonly Verilog, that describes the hardware performing computation
2. The control thread source code, written in C, that coordinates data transfers and synchronization
3. The system specification file, a configuration file that describes how the system will be built, and is often standard to the output platform

In addition to these files, there may also be a memory image file containing input data.

This file contains HDL descriptions of the hardware components that implement computation. It is generally written in Verilog, but can also be written in Bluespec System Verilog (if the Bluespec compiler is available) and compiled to Verilog.

It looks like any other Verilog file, with the addition of CoRAM specific components that it instantiates. The three CoRAM specific components are CoRAM modules, Channel FIFO modules, and Channel Registers.

1. CoRAM modules are memories that interact with the hardware components as single ported block memories with a 1 cycle delay on read. These modules are used to hold data brought from or sent to DRAM (or communicated off chip)
2. Channel FIFO modules provide two way queues for communication with control threads. Each queue is 64 entries deep and 64 bits wide.
3. Channel Registers provide a single register that can be used to communicate with control threads. Each register is 64 bits wide.

The compute components may link to other modules defined in external tools. These modules can be any modules supported by the toolset used for simulation and synthesis, and may even be created by high level synthesis tools such as ROCCC, Xilinx Vivado High Level Synthesis, or Altera C2H, and linking the block memory connections from the cores created by these tools to CoRAM modules.

Primitive declarations

detailed_coram_hardware_instantiation

CoRAM Control Threads coordinate data transfers between CoRAM modules and DRAM (or to off chip entities). In addition to memory operations, they can communicate with hardware modules via Channel FIFOs and Channel Registers, which allows them to perform synchronization tasks, and can perform I/O at the board level through memory mapped serial or PCI Express interfaces. Control threads support a subset of the C programming languages, including loops and other control flow and “printf”-like test formatting in simulation. Important parts of the Control Thread API are:

1. cpi_register_thread - Must be called at the beginning of every CoRAM control thread to ensure that the framework processes it correctly
2. cpi_get_ram - get a handle to a CoRAM
3. cpi_get_channel get a handle to a Channel FIFO or Channel Register
4. cpi_write_ram - Blocking write from DRAM to a CoRAM
5. cpi_read_ram - Blocking read from CoRAM to DRAM
6. cpi_nb_write_ram - Nonlocking write from DRAM to a CoRAM (returns a tag)
7. cpi_read_ram - Non-blocking read from CoRAM to DRAM (returns a tag)
8. cpi_wait - wait for a Non-blocking access (using a tag)
9. cpi_write_channel - write to a Channel FIFO or Channel Register.
10. cpi_read_cannel - read from a Channel FIFO or Channel Register - blocks if a FIFO is empty
11. cpi_printf - [SIMULATION ONLY] print formatted text

Actual header file

detailed_coram_control_thread

The system specification file can be used for advanced tuning, to provide more control over how the system is built. In general, it does not have to be modified, as a default file for each supported platform is often sufficient. Important parameters are:

1. platform - Determines general built type. Use “ml605” for hardware (either the Xilinx ML605 or Terasic/Altera DE4), “ml605sim” for simulation with icarus, or “vsim” for simulation with isim. Simulation targets model dram accesses as having a fixed delay (specified in cycles)
2. num_mc - Determines the number of memory controllers (and caches) to use. This should be 1 for the ML605, can be 1 or 2 for the DE4, and can be any number for simulation
3. topology - Network topology to use. Can be “xbar” for a crossbar, or “ring” for a unidirectional ring
4. ports_per_mc - Network ports connected to the memory controller. Must be 4 to reach maximum bandwidth, but may be reduced to create smaller designs.
5. dram_delay_cycles - Fixed DRAM delay for simulations