<commit_before># How to Contribute

Patches are welcome. This is a broad project with many components, 
both software and hardware. Here are some examples of areas to
help out, which are by no means exhaustive:

1. Hardware - Improve performance, increase clock speed, reduce area, 
   add new instructions or memory mapped fixed function blocks. Synthesize 
   for other FPGAs or ASICs (fix errors, add build scripts and config files)
2. Verification - Create new tests and test frameworks, improve existing ones.
3. Compiler - Improve code generation, port other language frontends 
   (especially parallel languages). Port and integrate a symbolic debugger. 
4. Tools - Improve and implement new profiling and performance measurement tools.
5. Benchmarks - A variety of benchmarks help evaluate instruction set or 
   microarchitectural tradeoffs. There are many libraries of parallel benchmarks
   that could be ported.
6. Software - Create a general purpose 3D rendering library, implement a raytracer, 
   port games or demo effects (which do double duty as a tests and benchmarks)

There is a more detailed list of potential feature ideas at:
https://github.com/jbush001/NyuziProcessor/wiki/Backlog

# Submitting Changes

Please read the sections about testing and coding style below. Larger
architectural changes or features should be proposed on the mailing list:

https://groups.google.com/forum/#!forum/nyuzi-processor-dev

There are a number of good pages on how to use github's standard pull
request workflow. https://help.github.com/
Here is a brief summary of how to do this from the command line:

First, set up your repository:

1. Fork the repo: From the main page, press the 'fork' button in the upper
right corner: https://github.com/jbush001/GPGPU

2. Clone this to your local machine (replacing YOUR-USERENAME below with your
github login) and the main project as an upstream so you can sync the latest
changes:
```
git clone https://github.com/YOUR-USERNAME/GPGPU
git remote add upstream https://github.com/jbush001/GPGPU
```

To submit a change:

1. Make sure your master branch is up to date if you haven't updated recently:
<pre>
git checkout master
git pull upstream master
</pre>
2. Make a new topic branch for each submission:
<pre>
 git checkout -b my-new-feature
</pre>
3. Make changes and check into your local repository.
4. Push the change to your fork on github
<pre>
git push origin my-new-feature
</pre>
5. Follow the instructions here to create a pull request: 
https://help.github.com/articles/creating-a-pull-request

When a pull request has been accepted, you can sync it to your master branch
as described in step 1 above.

# Testing Changes

## Verilog 
When adding new features, add tests as necessary to the tests/cosimulation
directory. A README in that directory describes how. In addition, here are
standard tests that should be run to check for regressions:

1. Directed cosimulation tests - Switch to the tests/cosimulation directory
<pre>
> ./runtest.sh *.s
Building branch.s
Random seed is 1411615294
44 total instructions executed
PASS
...
</pre>
2. Random cosimulation tests - Randomized tests aren't checked into the 
tree, but it's easy to create a bunch and run them.  From tests/cosimulation:
<pre>
> ./generate_random.py -m 25
generating random0000.s
generating random0001.s
...
> ./runtest.sh random*.s
Building random0000.s
Random seed is 1411615265
496347 total instructions executed
PASS
</pre>
3. 3D renderer - From the firmware/3D-Renderer directory, execute the renderer 
in verilog simulation. This can takes 4-5 minutes. Ensure it doesn't hang.
Open the fb.bmp file it spits out to ensure it shows a teapot.
<pre>
> make verirun
...
***HALTED***
ran for    16223433 cycles
performance counters:
 l2_writeback                    56646
 l2_miss                        162023
...
</pre>
4. Synthesize for FPGA - The Quartus synthesis tools are more stringent 
than Verilator and catch additional errors and warnings.  Also:
 * Open rtl/fpga/de2-115/output_files/fpga_target.map.summary and check the 
 total number of logic elements to ensure the design still fits on the part 
 and the number of logic elements hasn't gone up excessively (it should be 
 around 73k)
<pre>
Analysis & Synthesis Status : Successful - Wed Sep 10 18:51:56 2014
Quartus II 32-bit Version : 13.1.0 Build 162 10/23/2013 SJ Web Edition
Revision Name : fpga_target<commit_msg>Another tweak<commit_after># How to Contribute

Patches are welcome. This is a broad project with many components, 
both software and hardware. Here are some examples of areas to
help out, which are by no means exhaustive:

1. Hardware - Improve performance, increase clock speed, reduce area, 
   add new instructions or memory mapped fixed function blocks. Synthesize 
   for other FPGAs or ASICs (fix errors, add build scripts and config files)
2. Verification - Create new tests and test frameworks, improve existing ones.
3. Compiler - Improve code generation, port other language frontends 
   (especially parallel languages). Port and integrate a symbolic debugger. 
4. Tools - Improve and implement new profiling and performance measurement tools.
5. Benchmarks - A variety of benchmarks help evaluate instruction set or 
   microarchitectural tradeoffs. There are many libraries of parallel benchmarks
   that could be ported.
6. Software - Create a general purpose 3D rendering library, implement a raytracer, 
   port games or demo effects (which do double duty as a tests and benchmarks)

There is a more detailed list of potential feature ideas at:
https://github.com/jbush001/NyuziProcessor/wiki/Backlog

# Submitting Changes

Please read the sections about testing and coding style below. Larger
architectural changes or features should be proposed on the mailing list:

https://groups.google.com/forum/#!forum/nyuzi-processor-dev

There are a number of good pages on how to use github's standard pull
request workflow. https://help.github.com/
Here is a brief summary of how to do this from the command line:

First, set up your repository:

1. Fork the repo: From the main page, press the 'fork' button in the upper
right corner: https://github.com/jbush001/GPGPU

2. Clone this to your local machine (replacing YOUR-USERENAME below with your
github login) and the main project as an upstream so you can sync the latest
changes:
```
git clone https://github.com/YOUR-USERNAME/GPGPU
git remote add upstream https://github.com/jbush001/GPGPU
```

To submit a change:

1. Make sure your master branch is up to date if you haven't updated recently:
<pre>
git checkout master
git pull upstream master
</pre>
2. Make a new topic branch for each submission:
<pre>
 git checkout -b my-new-feature
</pre>
3. Make changes and check into your local repository.
4. Push the change to your fork on github
<pre>
git push origin my-new-feature
</pre>
5. Follow the instructions here to create a pull request: 
https://help.github.com/articles/creating-a-pull-request

When a pull request has been accepted, you can sync it to your master branch
as described in step 1 above.

# Testing Changes

## Verilog 
When adding new features, add tests as necessary to the tests/cosimulation
directory. A README in that directory describes how. In addition, here are
standard tests that should be run to check for regressions:

1. Directed cosimulation tests - Switch to the tests/cosimulation directory
<pre>
> ./runtest.sh *.s
Building branch.s
Random seed is 1411615294
44 total instructions executed
PASS
...
</pre>
2. Random cosimulation tests - Randomized tests aren't checked into the 
tree, but it's easy to create a bunch and run them.  From tests/cosimulation:
<pre>
> ./generate_random.py -m 25
generating random0000.s
generating random0001.s
...
> ./runtest.sh random*.s
Building random0000.s
Random seed is 1411615265
496347 total instructions executed
PASS
</pre>
3. 3D renderer - From the firmware/3D-Renderer directory, execute the renderer 
in verilog simulation. This can takes 4-5 minutes. Ensure it doesn't hang.
Open the fb.bmp file it spits out to ensure it shows a teapot.
<pre>
> make verirun
...
&#42;&#42;&#42;HALTED&#42;&#42;&#42;
ran for    16223433 cycles
performance counters:
 l2_writeback                    56646
 l2_miss                        162023
...
</pre>
4. Synthesize for FPGA - The Quartus synthesis tools are more stringent 
than Verilator and catch additional errors and warnings.  Also:
 * Open rtl/fpga/de2-115/output_files/fpga_target.map.summary and check the 
 total number of logic elements to ensure the design still fits on the part 
 and the number of logic elements hasn't gone up excessively (it should be 
 around 73k)
<pre>
Analysis & Synthesis Status : Successful - Wed Sep 10 18:51:56 2014
Quartus II 32-bit Version : 13.1.0 Build 162 10/23/2013 SJ Web Edition
Revision Name : fpga_target
{'fraction_non_alphanumeric': 0.06300813008130081, 'fraction_numerical': 0.03071364046973803, 'mean_word_length': 3.9150943396226414, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 37, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6460949', 'n_tokens_mistral': 2700, 'n_tokens_neox': 2399, 'n_words': 1230}