src/Testcases/BlackParrot/external/basejump_stl/README_contributing - third_party/Surelog - Git at Google

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