From 91fe0451d933a10d2e49753459e1854032739ed2 Mon Sep 17 00:00:00 2001 From: Fangjia Shen Date: Tue, 10 Sep 2024 20:24:02 -0400 Subject: [PATCH] Better README --- README.md | 14 ++++++- TEMPLATE.README.md | 100 --------------------------------------------- 2 files changed, 13 insertions(+), 101 deletions(-) delete mode 100644 TEMPLATE.README.md diff --git a/README.md b/README.md index 61c0808..06099f9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,18 @@ -The code in this project was tested with verilator version 4.038 and sbt version 1.8 or mill version 0.10.12. + +# Documentation +The Ray Tracer Datapath is documented in our arXiv article: [A +Hardware Ray Tracer Datapath with Generalized +Features](https://arxiv.org/abs/2409.06000) where the following are discussed: +- Supported operations +- IO specification +- Configurable parameters +- Dataflow of pipeline stages +- Hardware assets +- Design choices +- Description of source files # Prerequisites +The code in this project was tested with verilator version 4.038 and sbt version 1.8 or mill version 0.10.12. - verilator (for running the testbenches) - sbt (optional) (for building the project with SBT) diff --git a/TEMPLATE.README.md b/TEMPLATE.README.md deleted file mode 100644 index a81de66..0000000 --- a/TEMPLATE.README.md +++ /dev/null @@ -1,100 +0,0 @@ -Chisel Project Template -======================= - -You've done the [Chisel Bootcamp](https://github.com/freechipsproject/chisel-bootcamp), and now you -are ready to start your own Chisel project. The following procedure should get you started -with a clean running [Chisel3](https://www.chisel-lang.org/) project. - -## Make your own Chisel3 project - -### Dependencies - -#### JDK 8 or newer - -We recommend LTS releases Java 8 and Java 11. You can install the JDK as recommended by your operating system, or use the prebuilt binaries from [AdoptOpenJDK](https://adoptopenjdk.net/). - -#### SBT or mill - -SBT is the most common built tool in the Scala community. You can download it [here](https://www.scala-sbt.org/download.html). -mill is another Scala/Java build tool without obscure DSL like SBT. You can download it [here](https://github.com/com-lihaoyi/mill/releases) - -### How to get started - -#### Create a repository from the template - -This repository is a Github template. You can create your own repository from it by clicking the green `Use this template` in the top right. -Please leave `Include all branches` **unchecked**; checking it will pollute the history of your new repository. -For more information, see ["Creating a repository from a template"](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). - -#### Wait for the template cleanup workflow to complete - -After using the template to create your own blank project, please wait a minute or two for the `Template cleanup` workflow to run which will removes some template-specific stuff from the repository (like the LICENSE). -Refresh the repository page in your browser until you see a 2nd commit by `actions-user` titled `Template cleanup`. - - -#### Clone your repository - -Once you have created a repository from this template and the `Template cleanup` workflow has completed, you can click the green button to get a link for cloning your repository. -Note that it is easiest to push to a repository if you set up SSH with Github, please see the [related documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh). SSH is required for pushing to a Github repository when using two-factor authentication. - -```sh -git clone git@github.com:FJShen/raytracer.git -cd raytracer -``` - -#### Set project organization and name in build.sbt - -The cleanup workflow will have attempted to provide sensible defaults for `ThisBuild / organization` and `name` in the `build.sbt`. -Feel free to use your text editor of choice to change them as you see fit. - -#### Clean up the README.md file - -Again, use you editor of choice to make the README specific to your project. - -#### Add a LICENSE file - -It is important to have a LICENSE for open source (or closed source) code. -This template repository has the Unlicense in order to allow users to add any license they want to derivative code. -The Unlicense is stripped when creating a repository from this template so that users do not accidentally unlicense their own work. - -For more information about a license, check out the [Github Docs](https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/adding-a-license-to-a-repository). - -#### Commit your changes -```sh -git commit -m 'Starting raytracer' -git push origin main -``` - -### Did it work? - -You should now have a working Chisel3 project. - -You can run the included test with: -```sh -sbt test -``` - -You should see a whole bunch of output that ends with something like the following lines -``` -[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 -[info] All tests passed. -[success] Total time: 5 s, completed Dec 16, 2020 12:18:44 PM -``` -If you see the above then... - -### It worked! - -You are ready to go. We have a few recommended practices and things to do. - -* Use packages and following conventions for [structure](https://www.scala-sbt.org/1.x/docs/Directories.html) and [naming](http://docs.scala-lang.org/style/naming-conventions.html) -* Package names should be clearly reflected in the testing hierarchy -* Build tests for all your work -* Read more about testing in SBT in the [SBT docs](https://www.scala-sbt.org/1.x/docs/Testing.html) -* This template includes a [test dependency](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Per-configuration+dependencies) on [chiseltest](https://github.com/ucb-bar/chisel-testers2), this is a reasonable starting point for most tests - * You can remove this dependency in the build.sbt file if you want to -* Change the name of your project in the build.sbt file -* Change your README.md - -## Problems? Questions? - -Check out the [Chisel Users Community](https://www.chisel-lang.org/community.html) page for links to get in contact!