Accelerator System Top-Level

This repo is the top-level project repository which is used as a base for other projects to be built from.

Please Fork this repository in order to build your own custom project. This can be done through the git.soton.ac.uk/soclabs/accelerator-project website and create your own custom project folder which you can then customise to suit your needs.

Cloning this repository

This Repository contains multiple sub-repositories. In order to clone them with this repository, please use the following command:

git clone --recurse https://git.soton.ac.uk/soclabs/accelerator-project.git

This will clone this base repository. Change the url in the command above to clone your fork instead of the base repository.

Setting up the Project Environment

In order to checkout all the sub-repositories in your project to their branches and set up your local environment variables, from the top-level of this project run:

source set_env.sh

Adding a Custom Accelerator Repository

Custom accelerator repsitories can be added to your forked project using the following commands:

cd $SOCLABS_PROJECT_DIR; git submodule add youracceleratorurl.git

Once this has been done, you should see a folder at the top-level of your project containing your accelerator repository. This will be on a hash and not on a branch.

To get this repository to checkout to a branch, modify the top-level projbranch file to add your repository name (this should be the name of the directory it is in), followed by a colon and the name of the branch you wish it to check out to.

Then re-run the set environment script and force it to checkout all subrepositories:

source set_env.sh -f

The last thing you will wish to do it to modify the env/dependency_env.sh file. In here you can set an environment variable for your repsotry so it can be used in scripts and commands. Once this has been added, again run set environment command:

source set_env.sh

Setting up your environment

Every time you wish to run commands in this project, you will need to make sure the set environment script has been run for your current terminal session. This is done by moving to the top-level of the project and running:

source set_env.sh

This sets the environment variables related to this project and creates visability to the scripts in the flow directory.

Updating Subrepositories

Once you have run a source set_env.sh in your current terminal, you are then able to update all your repositories to their latest version by running:

socpull

This runs a git pull on all repositories in your project.

Project Structure

The core of the SoC is NanoSoC. This is an example, configurable system that is the main framework. It has many different memory-mapped regions, one of which is designed for the connection of accelerator subsystems called the expansion region.

The expansion region is able to instantiate an accelerator_subsystem by default. This means that anyone using NanoSoC as a platform for accelerator experimentation will need to build an accelerator_subsystem rtl module.

Accelerator Subsystem

accelerator_subsystem can either directly contain an accelerator (or multiple) or can instantiate accelerator wrappers which in turn instantiate accelerators.

This module is expected to be found in system/src/accelerator_subsystem.v.

Accelerator Wrapper

Accelerator wrappers are located in wrapper/src. These should instantiate accelerators and can use wrapper components within the accelerator_wrapper_tech repository to allow a conversion of valid//ready interfaces to a memory-mapped AHB interface.

Running the simulation

socsim is a tool that SoC Labs have developed that allows for running of shell scripts anywhere within your project environment. The idea is these scripts can be customised to run scripts for different simulators.

These scripts are located in simulate/socsim. There are some example scripts in there and can be run using the following command, where hello is the testcase to be run:

socsim system_nanosoc TESTNAME=hello

To run the simulation the 'socsim' command executes the makefile in the 'nanosoc_tech' microcontroller framework. (Edit the simulator target in nanosoc_tech/nanosoc/makefile for the simulator EDA tool used).

This runs the integration test program on the Arm Cortex-M0 processor using the 'system_nanosoc.sh' script provided in the simulate/socsim directory and the logs are produced in the simulate/sim/system_nanosoc/logs directory.