| * Goals * | |
| The goal of the project is to build an | |
| open-source equivalent of the Standard | |
| Template Library (in C++) for hardware design. | |
| This way, instead of rewriting and redebugging the | |
| same code over and over, we can reuse a bunch of | |
| well-designed hardware components. Because of this, | |
| good, clean style is important. You should focus on | |
| mimicking the style currently in use | |
| (naming, spacing, etc), and should try never | |
| to write the same code twice -- factor similar | |
| code into modules with clean, easy-to-explain | |
| interfaces and reuse them. | |
| * Repo structure * | |
| The basic structure of the repository is that | |
| different modules that people may want to use | |
| are organized by type into directory. | |
| In the top-level "testing" directory, we plan to mirror | |
| the directory structure of the top-level of the | |
| repo, so that ideally each file has a test. | |
| So for instance, the directory | |
| bsg_ip_cores/testing/bsg_misc/bsg_binary_plus_one_to_gray | |
| is intended to test the file | |
| bsg_ip_cores/bsg_misc/bsg_binary_plus_one_to_gray.v. | |
| You can use that test as an example. | |
| * Contributing through Testing * | |
| If you would like to contribute, you can start | |
| by writing tests for modules that do not yet have tests. | |
| For writing tests, we have a lot of helpful modules that | |
| already exist in the bsg_ip_cores source base, that you | |
| should use. This way we can use our own philosophy of | |
| reuse even in testing! As you develop tests, you will | |
| come up with your own ideas about what helper modules | |
| we should use, and we can add those to the repo as well. | |
| After you have written tests and have a sense of our | |
| hardware design philosophy, then you can contribute | |
| synthesizeable code to the repository as well. Some of your | |
| code is likely to end up in a chip that we design in the near future! | |
| To run your tests, you can download the demonstration | |
| version of Altera Quartus and Modelsim from the Altera | |
| website. If the code is a testbench, it does not need | |
| to be compiled with Quartus, but it definitely should simulate with modelsim. | |
| Make sure that you have SystemVerilog enabled in those tools | |
| and that you are using the latest versions (e.g. > 15.0 for Modelsim). | |
| Alternatively, you may also use VCS and/or Design Compiler if you have access. | |
| To test different combinations of parameters, you will use a Makefile that | |
| runs your test repeatedly with different arguments. See http://www.gnu.org/software/make/ | |
| for the entire manual in one page so that it is easily searchable. We have | |
| some helpful lines of code for make that will test all combinations of a variety | |
| of input parameters (the bsg_param_scan make function). | |
| Each test should have a header comment that describes the testing rationale; | |
| i.e. explain the design of your test. You should explicitly identify the | |
| state space (inputs and internal state) that should be tested, and also | |
| the parameter space (i.e. different input configuration parameters.) You | |
| should explain particular cases that need to be tested based on inspection | |
| of the code (does the code handle different cases with different code?). | |
| Where possible, brute force testing of the whole state space is a desireable | |
| approach. Note that modules have invariants on their inputs; if these invariants | |
| are not true, then the module's behavior is undefined. However, it would be | |
| good to have asserts that give a warning if input invariants are incorrect. | |
| Each test should be self checking, and assert $error if an answer is incorrect. | |
| For the test, we ignore all output before the reset line goes line | |
| (which is prominently indicated when you use our reset_gen module). | |
| Be sure to immitate the style that is used in the other tests! Seperate your | |
| synthesizeable and non-synthesizeable verilog into seperate always blocks. | |
| * Coding Style Guidelines * | |
| See this document for BSG coding guidelines. | |
| https://docs.google.com/document/d/1xA5XUzBtz_D6aSyIBQUwFk_kSUdckrfxa2uzGjMgmCU/edit# | |
| * Terms * | |
| Note that by contributing code to this repository, you are | |
| agreeing to allow others to use the code freely under | |
| the terms of the open-source license(s) selected by Michael Taylor (prof.taylor@gmail.com) | |
| (see the file LICENSE). |