diff --git a/README.md b/README.md index a187598617e3b0c5135aa43c8c760353ebf5a2c1..e47567cf9a7cf9da01553026d6f3541e12d7dc2d 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,27 @@ -# AES-128 Example Accelerator System Project +# Accelerator System Project -This repo is the top-level repository which contains an example accelerator based on the secworks AES engine integrated in SoC Labs provided nanosoc chip design IP in forms of git subrepositories. +This repo is the top-level repository which contains all the relavant IP for integrating your custom hardware accelerator with the SoC Labs provided nanosoc chip design IP in forms of git subrepositories. + +### Fork this repository + +In order to use this repository for your own project, we recommend that you fork a version of this repository first. In your forked version of the project you can add you accelerator as a subrepo if you are already using repositories, or alternatively add the source for you accelerator directly to your forked repository. ### 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/aes-128-project.git` +`git clone --recurse https://git.soton.ac.uk/soclabs/accelerator-project.git` + +At this stage you can also add your submodule with: +`git submodule add` + +After doing this you should update the projbranch file to include your repository name (as it appears in .gitmodules) and the branch. This will allow the set_env.sh script to pull in your repository when updates are made + +At this point you may also like to edit the /env/dependency_env.sh to include your accelerator directory for example: + +`export ACCELERATOR_DIR="$SOCLABS_PROJECT_DIR/accelerator"` + ## Setting up the Project Environment --- @@ -41,6 +55,13 @@ The core of the SoC is NanoSoC. This is an example, configurable system that is 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. +There is an example file in `/system/src/accelerator_subsystem.v`. You will need to add an instantiation of your top level to this file. The connections at this level are an AHB subordinate, DMA data requist signals, and CPU interupt signals. + +### Using the makefiles and FLISTS + +Simulation, FPGA implementation, and ASIC synthesis can all be performed from the main makefile in the nanosoc_tech repository. In order for these to work correctly you must make sure the flist files include your accelerator source code. +You can add these to `/flist/project/accelerator`. It is recommended here to use environment variables, the top level of your project will be `$SOCLABS_PROJECT_DIR`. You can include files directly, or include other flists with the `-f` command at the start of the line. + ### htmlgen design visualisation --- @@ -73,4 +94,34 @@ To run the simulation the 'socsim' command executes the makefile in the 'nanosoc This runs the integration test program on the Arm Cortex-M0 processor using the 'system_aes128.sh' script provided in the simulate/socsim directory and the logs are produced in the simulate/sim/system_aes128/logs directory. +## Adding testcodes + +To add your own testcodes to be run from the Arm Cortex-M0 processor, it is recommnded these are added in the `/system/testcodes/$TESTNAME` directory. +To enable the makefiles to find your testcode, you should also add the name of your test to the `/system/testcodes/software_list.txt` file. + +It is recommended that you copy and edit one of the makefiles for compiling your software into .hex files. (for example in `/system/testcodes/adp_v4_cmd_tests/makefile`) You will have to edit the TESTNAME (line 46) and may also need to change some of the compiler options depending on your code. +You can then either simulate using the `socim test_accelerator TESTNAME=x` or alternatively from the `/nanosoc_tech` directory you can run `make run_%SIM% TESTNAME=x ACCELERATOR=yes` + +The currently supported simulators are VCS, Excelium and Questa Sim. Currently we mostly use Quest Sim (run_mti) + +You can also run `sim_%SIMULATOR%` and this will run the simulation from the GUI. + +When using the makefile, you must include the `ACCELERATOR=yes` directive to include your accelerator + +## FPGA Builds + +We currently have build files for the ARM MPS3, PYNQ ZCU104, PYNQ Z2, KRIA KR260 and KRIA KV260. To build the bitfiles you can run the `make build_fpga FPGA=%target% ACCELERATOR=yes` from the `/nanosoc_tech/` directory. +The acceptable targets are defined in the `/nanosoc_tech/fpga/makefile.targets` and are `mps3, zcu104, z2, kr260, kv260` + +This script will run the vivado build scripts. The output from this will be in the `/imp/FPGA` directory. + +## ASIC Synthesis + +To run the ASIC synthesis you will first need to define a `$PHYS_IP` environment variable. This should point to the uncompressed Arm bundles for the TSMC 65nm LP node. + +For a Cadence synthesis flow use: +1. Run `make gen_memories` this will generate the bootrom, and SRAMS using the artisan memory compilers +2. Run `make flist_genus_nanosoc ACCELERATOR=yes ASIC=yes` which will generate the top flist for the genus synthesiser tool +3. Run `make syn_genus ACCELERATOR=yes ASIC=yes` which will run the synthesis +The output from the synthesis will be in the `/imp/ASIC` directory.