diff --git a/README.md b/README.md index ec8d10bd5..553939b50 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Vortex GPGPU -Vortex is a full-stack open-source RISC-V GPGPU. +Vortex is a full-stack open-source RISC-V GPGPU. Vortex supports multiple *backend drivers*, including our C++ simulator (simx), an RTL simulator, and physical Xilinx and Altera FPGAs-- all controlled by a single driver script. The chosen driver determines the corresponding code invoked to run Vortex. Generally, developers will prototype their intended design in simx, before completing going forward with an RTL implementation. Alternatively, you can get up and running by selecting a driver of your choice and running a demo program. ## Specifications @@ -29,12 +29,14 @@ Vortex is a full-stack open-source RISC-V GPGPU. - `ci`: Continuous integration scripts. - `miscs`: Miscellaneous resources. -## Build Instructions -More detailed build instructions can be found [here](docs/install_vortex.md). +## Quick Start +The following steps demonstrate how to run Vortex with the default driver: simx. If you are interested in a different backend, look [here](docs/simulation.md). + ### Supported OS Platforms - Ubuntu 18.04, 20.04 - Centos 7 ### Toolchain Dependencies +The following dependencies will be fetched prebuilt by `toolchain_install.sh`. - [POCL](http://portablecl.org/) - [LLVM](https://llvm.org/) - [RISCV-GNU-TOOLCHAIN](https://github.com/riscv-collab/riscv-gnu-toolchain) @@ -107,4 +109,4 @@ echo "source /ci/toolchain_env.sh" >> ~/.bashrc ```sh ./ci/blackbox.sh --app=demo --debug=3 ``` -- For additional information, check out the /docs. +- For additional information, check out the [documentation](docs/index.md) diff --git a/docs/contributing.md b/docs/contributing.md index e87158272..f10f4017b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -22,7 +22,7 @@ However, contributions are strongly encouraged and keep the project moving forwa 6. Otherwise, you can go to your fork on Github online and manually create a PR (todo) (todo): how to name and format your PR, what information you should add to the PR, does not need to be too strict if you are attending the weekly meetings* 7. Github uses the following semantics: `base repository` gets the changes from your `head repository` -8. Therefore, you should set the `base repository` to `vortexgpgpu/vortex` and the `base` branch to `develop` since active development should only be added to this branch +8. Therefore, you should set the `base repository` to `vortexgpgpu/vortex` and the `base` branch to `master` since the master branch is protected by reviewed PRs. 9. And you should assign the `head repository` to `/vortex` (which represents your fork of vortex) and the `base` branch to the one created in step 2 10. Now that your intended PR has been specified, you should review the status. Check for merge conflicts, if all your commits are present, and all the modified files make sense 11. You can still make a PR if there are issues in step 10, just make sure the structure is correct according to steps 7-9 @@ -31,14 +31,7 @@ However, contributions are strongly encouraged and keep the project moving forwa 14. As long as the `head repository`'s `base` branch is the one you edited, the PR will automatically get the most recent changes 15. When all merge conflicts are resolved, changes are made, and tests pass you can have an admin merge your PR - -- You should create a new branch from develop that is clearly named with the feature that you want to add -- Avoid pushing directly to the `master` branch instead you will need to make a Pull Request (PR) -- There should be protections in place that prevent pushing directly to the main branch, but don't rely on it -- When you make a PR it will be tested against the continuous integration (ci) pipeline (see `continuous_integration.md`) -- It is not sufficient to just write some tests, they need to be incorporated into the ci pipeline to make sure they are run -- During a PR, you might receive feedback regarding your changes and you might need to make further commits to your branch - - -## Creating and Adding Tests -The CI pipeline the vortex tests. If you are contributing code changes, then review `testing.md` to learn how to integrate your own tests \ No newline at end of file +## What Makes a Good Contribution? +- If you are contributing code changes, then review `testing.md` to ensure your tests are integrated into the CI pipeline +- During a PR, you should consider the advice you are provided by your reviewers. Remember you keep adding commits to an open PR! +- If your change aims to fix an issue opened on Github, please tag that issue in the PR itself \ No newline at end of file diff --git a/docs/fpga_setup.md b/docs/fpga_setup.md index 2a673f8fc..78ed63e25 100644 --- a/docs/fpga_setup.md +++ b/docs/fpga_setup.md @@ -1,7 +1,7 @@ # FPGA Startup and Configuration Guide ## Gaining Access to FPGA's with CRNCH -If you are associated with Georgia Tech and need remote access to the FPGA's, you can utilize CRNCH's server. +If you are associated with Georgia Tech (or related workshops) you can use CRNCH's server to gain remote access to FPGA's. Otherwise, you can skip to the Xilinx or Intel (Altera) synthesis steps below. ## What is CRNCH? @@ -37,11 +37,10 @@ CRNCH resources do not require any VPN access for GT members so you can head to Alternatively, you can `ssh` into rg with: `ssh @rg-login.crnch.gatech.edu` -(`ssh usubramanya3@rg-login.crnch.gatech.edu`) +(`ssh gburdell3@rg-login.crnch.gatech.edu`) -Once you’ve logged in, you can use Slurm to request other nodes within the testbed. See more information on Slurm at [this page](https://gt-crnch-rg.readthedocs.io/en/main/general/using-slurm.html). - -Note that you can also use VSCode to log into the Rogues Gallery via its terminal functionality. See [this page for more details](https://gt-crnch-rg.readthedocs.io/en/main/general/visual-studio-code.html). +## Synthesis for Xilinx Boards +First, you need to get access to the server with the Xilinx FPGAs. ## **What Machines are Available in the Rogues Gallery?** @@ -49,7 +48,7 @@ Complete list of machines can be found [here](https://gt-crnch-rg.readthedocs.io ## Which Machine do we Need from RG? -There are three primary nodes you might use. The table below summarizes: +There are three primary nodes you might use for Xilinx FPGAs. The table below summarizes: | Name | Device | Description | | --- | --- | --- | @@ -62,59 +61,43 @@ There are three primary nodes you might use. The table below summarizes: ## How to Access flubber for Synthesis? -Now that you have the files prepared and available on the FPGA node, you can start the synthesis. To run on hardware we need a rg-xilinx-fpga-hw cluster which includes **flubber[1,4-5]**. First `ssh` into the rouges gallery: +Now that you have the files prepared and available on the FPGA node, you can start the synthesis. To run on hardware we need a rg-xilinx-fpga-hw cluster which includes **flubber[1,4-5]**. First `ssh` into the rouges gallery, if you have not already. ```bash ssh [@rg-login.crnch.gatech.edu](mailto:usubramanya3@rg-login.crnch.gatech.edu) ``` -Then, to access the hardware node you need to `ssh` into flubber: +Once you’ve logged in, you can use Slurm to request an interactive job. First, view the available Slurm Partitions here [here](https://gt-crnch-rg.readthedocs.io/en/main/general/using-slurm.html). Then, the example requests can be found [here](https://gt-crnch-rg.readthedocs.io/en/main/general/using-slurm-examples.html). +In our case we might run: ```bash -ssh flubber1 +salloc -p rg-fpga --nodes=1 --ntasks-per-node=1 --nodelist flubber1 --time=01:00:00 ``` -## Synthesis for Xillinx Boards - -XRT Environment Setup ----------------------- - - $ source /opt/xilinx/Vitis/2023.1/settings64.sh - $ source /opt/xilinx/xrt/setup.sh - +## Environment Setup +Once you are logged in, you will need to complete some first time configurations. -Check Installed FPGA Platforms ------------------------------- +### Clone Repo - $ platforminfo -l +### Source Configuration Scripts +``` +$ source /opt/xilinx/xrt/setup.sh +$ source /opt/xilinx/Vitis/2023.1/settings64.sh +``` +### Check Installed FPGA Platforms +`platforminfo -l` -Build FPGA image ----------------- +### Build FPGA image +The directory `hw/syn/xilinx/xrt` contains the makefile used to synthesize Vortex. +``` $ cd hw/syn/xilinx/xrt - $ PREFIX=test1 PLATFORM=xilinx_u50_gen3x16_xdma_5_202210_1 TARGET=hw NUM_CORES=4 make - + $ PREFIX=test1 PLATFORM=xilinx_u50_gen3x16_xdma_5_202210_1 TARGET=hw NUM_CORES=4 make build_u50_hw_4c.log 2>&1 & +``` Will run the synthesis under new build directory: BUILD_DIR := "\\_\\_\" - The generated bitstream will be located under /bin/vortex_afu.xclbin -Sample FPGA Run Test --------------------- - -Ensure you have the correct opae runtime for the FPGA target - - $ make -C runtime/xrt clean - $ TARGET=hw make -C runtime/xrt - -Run the following from your Vortex build directory - - $ TARGET=hw FPGA_BIN_DIR=/bin ./ci/blackbox.sh --driver=xrt --app=sgemm --args="-n128" - ---- - -The directory `hw/syn/xilinx/xrt` contains the makefile used to synthesize Vortex. - For long-running jobs, invocation of this makefile can be made of the following form: `[CONFIGS=] [PREFIX=] [NUM_CORES=<#>] TARGET=hw|hw_emu PLATFORM= nohup make > 2>&1 &` @@ -127,7 +110,7 @@ CONFIGS="-DL2_ENABLE -DDCACHE_SIZE=8192" PREFIX=build_4c_u280 NUM_CORES=4 TARGET The build is complete when the bitstream file `vortex_afu.xclbin` exists in `hw|hw_emu/bin`. -## Running a Program on FPGA +### Running a Program on Xilinx FPGA The blackbox.sh script in `ci` can be used to run a test with Vortex’s xrt driver using the following command: @@ -135,9 +118,9 @@ The blackbox.sh script in `ci` can be used to run a test with Vortex’s xrt d For example: -`FPGA_BIN_DIR=`realpath hw/syn/xilinx/xrt/build_4c_u280_xilinx_u280_gen3x16_xdma_1_202211_1_hw/bin` TARGET=hw PLATFORM=xilinx_u280_gen3x16_xdma_1_202211_1 ./ci/blackbox.sh --driver=xrt --app=demo` +```FPGA_BIN_DIR= hw/syn/xilinx/xrt/build_4c_u280_xilinx_u280_gen3x16_xdma_1_202211_1_hw/bin TARGET=hw PLATFORM=xilinx_u280_gen3x16_xdma_1_202211_1 ./ci/blackbox.sh --driver=xrt --app=demo``` -## Synthesis for Intel (Altera) Boards +### Synthesis for Intel (Altera) Boards To set up the environment, source the XRT setup.sh and other Xilinx scripts. For example: diff --git a/docs/index.md b/docs/index.md index 14a45f335..a53a2fd15 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,29 +5,6 @@ - [Codebase Layout](codebase.md) - [Microarchitecture](microarchitecture.md) - [Cache Subsystem](cache_subsystem.md) -- [Software](software.md) - [Simulation](simulation.md) -- [Altera FPGA Setup Guide](altera_fpga_guide.md) -- [Xilinx FPGA Setup Guide](xilinx_fpga_guide.md) +- [Contributing](contributing.md) - [Debugging](debugging.md) -- [Useful Links](references.md) - -## Installation - -- For the different environments Vortex supports, [read this document](environment_setup.md). -- To install on your own system, [follow this document](install_vortex.md). - -## Quick Start Scenarios - -Running Vortex simulators with different configurations: -- Run basic driver test with rtlsim driver and Vortex config of 2 clusters, 2 cores, 2 warps, 4 threads - - $ ./ci/blackbox.sh --driver=rtlsim --clusters=2 --cores=2 --warps=2 --threads=4 --app=basic - -- Run demo driver test with opae driver and Vortex config of 1 clusters, 4 cores, 4 warps, 2 threads - - $ ./ci/blackbox.sh --driver=opae --clusters=1 --cores=4 --warps=4 --threads=2 --app=demo - -- Run dogfood driver test with simx driver and Vortex config of 4 cluster, 4 cores, 8 warps, 6 threads - - $ ./ci/blackbox.sh --driver=simx --clusters=4 --cores=4 --warps=8 --threads=6 --app=dogfood diff --git a/docs/simulation.md b/docs/simulation.md index e1c578034..d55b3cd94 100644 --- a/docs/simulation.md +++ b/docs/simulation.md @@ -6,11 +6,14 @@ ### Cycle-Approximate Simulation -SimX is a C++ cycle-level in-house simulator developed for Vortex. The relevant files are located in the `simX` folder. +SimX is a C++ cycle-level in-house simulator developed for Vortex. The relevant files are located in the `simx` folder. The [readme](README.md) has the most detailed instructions for building and running simX. + +- To install on your own system, [follow this document](install_vortex.md). +- For the different Georgia Tech environments Vortex supports, [read this document](environment_setup.md). ### FGPA Simulation -The guide to build the fpga with specific configurations is located [here.](fpga_setup.md) You can find instructions for both Xilinx and Intel (Altera) based FPGAs. +The guide to build the fpga with specific configurations is located [here.](fpga_setup.md) You can find instructions for both Xilinx and Altera based FPGAs. ### How to Test @@ -47,4 +50,19 @@ PERF: core1: instrs=90693, cycles=53108, IPC=1.707709 PERF: core2: instrs=90849, cycles=53107, IPC=1.710678 PERF: core3: instrs=90836, cycles=50347, IPC=1.804199 PERF: instrs=363180, cycles=53108, IPC=6.838518 -``` \ No newline at end of file +``` + +## Additional Quick Start Scenarios + +Running Vortex simulators with different configurations: +- Run basic driver test with rtlsim driver and Vortex config of 2 clusters, 2 cores, 2 warps, 4 threads + + $ ./ci/blackbox.sh --driver=rtlsim --clusters=2 --cores=2 --warps=2 --threads=4 --app=basic + +- Run demo driver test with opae driver and Vortex config of 1 clusters, 4 cores, 4 warps, 2 threads + + $ ./ci/blackbox.sh --driver=opae --clusters=1 --cores=4 --warps=4 --threads=2 --app=demo + +- Run dogfood driver test with simx driver and Vortex config of 4 cluster, 4 cores, 8 warps, 6 threads + + $ ./ci/blackbox.sh --driver=simx --clusters=4 --cores=4 --warps=8 --threads=6 --app=dogfood \ No newline at end of file