Merge pull request #95 from Udit8348/develop-documentation

Documentation for Testing and Contributing

docs/continuous_integration.md

@@ -0,0 +1,36 @@
+# Continuous Integration
+- Each time you push to the repo, the Continuous Integration pipeline will run
+- This pipeline consists of creating the correct development environment, building your code, and running all tests
+- This is an extensive pipeline so it might take some time to complete
+
+
+## Protecting Master Branch
+Navigate to your Repository:
+Open your repository on GitHub.
+
+Click on "Settings":
+In the upper-right corner of your repository page, click on the "Settings" tab.
+
+Select "Branches" in the left sidebar:
+On the left sidebar, look for the "Branches" option and click on it.
+
+Choose the Branch:
+Under "Branch protection rules," select the branch you want to protect. In this case, choose the main branch.
+
+Enable Branch Protection:``
+Check the box that says "Protect this branch."
+
+Configure Protection Settings:
+You can configure various protection settings. Some common settings include:
+
+Require pull request reviews before merging: This ensures that changes are reviewed before being merged.
+Require status checks to pass before merging: This ensures that automated tests and checks are passing.
+Require signed commits: This enforces that commits are signed with a verified signature.
+Restrict Who Can Push:
+You can further restrict who can push directly to the branch. You might want to limit this privilege to specific people or teams.
+
+Save Changes:
+Once you've configured the protection settings, scroll down and click on the "Save changes" button.
+
+Now, your main branch is protected, and certain criteria must be met before changes can be pushed directly to it. Contributors will need to create pull requests, have their changes reviewed, and meet other specified criteria before the changes can be merged into the main branch.
+

docs/contributing.md

@@ -0,0 +1,18 @@
+# Contributing to Vortex on Github
+
+## Github Details
+- There are two main repos, `vortex` (public, this one) and `vortex-dev` (private)
+- todo: Most current development is on `vortex`
+- If you have a legacy version of `vortex`, you can use the releases branch or tags to access the repo at that point in time
+
+## Contribution Process
+- 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
+see `testing.md`

docs/environment_setup.md

@@ -0,0 +1,71 @@
+# Environment Setup# Vortex Dev Environment Setup
+These instructions apply to the development vortex repo using the *updated toolchain*. The updated toolchain is considered to be any commit of `master` pulled from *July 2, 2023* onwards. The toolchain update in question can be viewed in this [commit](https://github.com/vortexgpgpu/vortex-dev/commit/0048496ba28d7b9a209a0e569d52d60f2b68fc04). Therefore, if you are unsure whether you are using the new toolchain or not, then you should check the `ci` folder for the existence of the `toolchain_prebuilt.sh` script. Furthermore, you should notice that the `toolchain_install.sh` script has the legacy `llvm()` split into `llvm-vortex()` and `llvm-pocl()`.
+
+> Note: As it stands right now, there a few test suites which are not working due to this toolchain migration. We are working to determine an exact list of which ones are working and which ones are not. For now, if the repo builds at a minimum, then you can consider all these steps to have worked successfully.
+
+## Choosing an Development Environment
+There are three primary environments you can use. Each has its own pros and cons. Refer to this section to help you determine which environment best suits your needs.
+1. Volvo
+2. Docker
+3. Local
+
+### Volvo
+Volvo is a server provided by Georgia Tech. As such, it provides high performance compute, but you need valid credentials to access it. If you don't already have credentials, you can get in contact with your mentor to ask about setting your account up.
+
+Pros:
+
+1. Native x86_64 architecture, AMD EPYC 7702P 64-Core Processor (*fast*)
+2. Packages and difficult configurations are already done for you
+3. Consistent environment as others, allowing for easier troubleshooting
+4. Just need to SSH into Volvo, minimal impact on local computer resources
+5. VScode remote development tools are phenomenal over SSH
+
+Cons:
+1. Volvo is accessed via gatech vpn, external contributors might encounter issues with it -- especially from other university networks
+2. Account creation is not immediate and is subject to processing time
+3. Volvo might have outtages (*pretty uncommon*)
+5. SSH development requires internet and other remote development tools (*vscode works!*)
+
+### Docker
+
+Docker allows for isolated pre-built environments to be created, shared and used. They are much more resource efficient than a Virtual Machine, and have great tooling and support available. The main motivation for Docker is bringing a consistent development environment to your local computer, across all platforms.
+
+Pros:
+
+1. If you are native to x86_64, the container will also run natively, yielding better performance. However, if you have aarch64 (arm) processor, you can still run the Docker container without configuration changes.
+2. Consistent environment as others, allowing for easier troubleshooting
+3. Works out of the box, just have a working installation of Docker
+4. Vortex uses a build system, so once you build the repo once, only new code changes need to be recompiled
+5. Docker offers helpful tools and extensions to monitor the performance of your container
+
+Cons:
+
+1. If you are using an arm processor, the container will be run in emulation mode, so it will inherently run slower, as it needs to translate all the x86_64 instructions. It's still usable on Apple Silicon, however.
+2. Limited to your computer's performance, and Vortex is a large repo to build
+3. Will utilize a few gigabytes of storage on your computer for saving binaries to run the container
+
+
+### Local
+You can reverse engineer the Dockerfile and scripts above to get a working environment setup locally. This option is for experienced users, who have already considered the pros and cons of Volvo and Docker.
+
+## Setup on Volvo
+1. Clone Repo Recursively: `git clone --recursive https://github.com/vortexgpgpu/vortex-dev.git`
+2. Source `/opt/set_vortex_env_dev.sh` to initialize pre-installed toolchain
+3. `make -s` in `vortex-dev` root directory
+4. Run a test program: `./ci/blackbox.sh --cores=2 --app=dogfood`
+
+## Setup with Docker
+Currently the Dockerfile is not included with the official vortex-dev repository, however you can quickly add it to repo and get started.
+1. Clone repo recursively onto your local machine: `git clone --recursive https://github.com/vortexgpgpu/vortex-dev.git`
+2. Download a copy of `Dockerfile.dev` and place it in the root of the repo.
+3. Build the Dockerfile into an image: `docker build --platform=linux/amd64 -t vortex-dev -f Dockerfile.dev .`
+4. Run a container based on the image: `docker run --rm -v ./:/root/vortex-dev/ -it --name vtx-dev --privileged=true --platform=linux/amd64 vortex-dev`
+5. Install the toolchain `./ci/toolchain_install.sh --all` (once per container)
+6. `make -s` in `vortex-dev` root directory
+7. Run a test program: `./ci/blackbox.sh --cores=2 --app=dogfood`
+
+
+### Additional Docker Commands
+- Exit from a container (does not stop or remove it)
+- Resume a container you have exited or start a second terminal session `docker exec -it <container-name> bash`
+

docs/testing.md

@@ -2,18 +2,18 @@
 
 ## Running a Vortex application
 
-The framework provides a utility script: blakcbox.sh under the /ci/ folder for executing applications in the tests tree.
+The framework provides a utility script: blackbox.sh under the /ci/ folder for executing applications in the tests tree.
 You can query the commandline options of the tool using:
 
-    $ ./ci/blakcbox.sh --help
+    $ ./ci/blackbox.sh --help
 
 To execute sgemm test program on the simx driver and passing "-n10" as argument to sgemm:
 
-    $ ./ci/blakcbox.sh --driver=simx --app=sgemm --args="-n10"
+    $ ./ci/blackbox.sh --driver=simx --app=sgemm --args="-n10"
 
 You can execute the same application of a GPU architecture with 2 cores:
 
-    $ ./ci/blakcbox.sh --core=2 --driver=simx --app=sgemm --args="-n10"
+    $ ./ci/blackbox.sh --core=2 --driver=simx --app=sgemm --args="-n10"
 
 When excuting, Blackbox needs to recompile the driver if the desired architecture changes. 
 It tracks the latest configuration in a file under the current directory blackbox.<driver>.cache.
@@ -30,4 +30,18 @@ You can execute the default regression suite by running the following commands a
 You can execute the default opncl suite by running the following commands at the root folder.
 
     $ make -C tests/opencl run-simx 
-    $ make -C tests/opencl run-rtlsim
+    $ make -C tests/opencl run-rtlsim
+
+## Creating Your Own Regression Tests
+- Inside `test/` you will find a series of folders which are named based on what they test
+- You can view the tests to see which ones have tests similar to what you are trying to create new tests for
+- once you have found a similar baseline, you can copy the folder and rename it to what you are planning to test
+- `testcases.h` contains each of the test case templates
+- `main.cpp` contains the implementation of each of the test cases and builds a test suite of all the tests cases you want
+
+Compile the test case: `make -C tests/regression/<testcase-name>/ clean-all && make -C tests/regression/<testcase-name>/`
+
+Run the test case: `./ci/blackbox.sh --driver=simx --cores=4 --app=<testcase-name> --debug`
+
+## Adding Your Tests to the CI Pipeline
+see `continuous_integration.md`