Culsans - tightly-coupled cache coherence unit using the ACE protocol

Introduction

Aim of this project is the development of a tightly-coupled cache coherence unit for a multicore processor based on CVA6. Like the ancient god ¹, its responsibilities are to maintain order (and data consistency) among the memory accesses performed by the 2~4 CPUs which are part of the system.

Getting started

git clone https://github.com/planvtech/culsans.git --recursive

Synthesis on FPGA (Genesys2)

make fpga

The top level file for FPGA synthesis is rtl/src/culsans_xilinx.sv

SD image generation

Make sure all dependencies specified in cva6-sdk are fulfilled.

make sdk

Then follow the instruction in cva6-sdk to copy the generated image to the SD.

RTL tests

Sanity check

make sanity-tests

Regression tests

make test

Verification

Culsans Integration Test Suite (CITS)

The CITS is a test platform that tests the integration of components of Culsans.

There are two layers to the tests.

There is c code self testing. This is achieved by c code within the test testing what it expects it has effected in the memory. If it fails, it exits early with a code indicative of the core and cacheline that incurred the problem.

The second (optional) layer is that where an external parser inspects the logs generated by the tests and compares them to an expected sequence. This layer is not further described here.

Running tests

Tests are run in the tests/integration directory. All commands below are executed in this directory.

To run a test in the CITS, type

make -C testlist/<test_name> all

To run a test in the CITS in a GUI, type

make GUI=1 -C testlist/<test_name> all

Adding tests

A CITS test consists of a batch of files within the folder testlist/<test_name>. The folder should contain the following files:

File	Description
<test_name>.c/h	This file is the the actual test. See similar files in the CITS for an example of how to write one.
main.c	This file co-ordinates the core execution and calls the test_name() function. See the main.c files in the CITS for an example on how to write one.
Makefile	Symlink to ../../test_automation/Makefile
sim.tcl	Symlink to ../../test_automation/sim.tcl

The test function defined in <test_name>.c should be self-checking and call exit(arg) with arg > 0 if the test fails, otherwise return 0.

Footnotes

1. Culsans – the Etruscan version of Janus, the two-faced and also four-faced god, god of the first and last of the year, of the beginning and the end, of the cardinal points and thus of order in general. ↩