README_contributing

* 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.sv.  
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).