Raise pull requests against the [develop](https://github.com/Wren6991/Hazard3/tree/develop) branch. Do not raise pull requests directly against [stable](https://github.com/Wren6991/Hazard3/tree/stable).
I do not merge pull requests which modify hardware sources in the `hdl/` directory. I close these pull requests without reading the patch.
The contents of the `hdl/` directory have a single author. I will not expose people taping out Hazard3 to the possibility of your employer chasing you for your contribution by harassing them legally. A contribution agreement does not solve this, because you may sign it without the legal capability to do so, and **what is taped out cannot be taped back in.**
If you are reading this as a software engineer, please understand that the ASIC industry is more hostile to open-source projects than the software industry is, and I am trying my hardest to build a core that other people can safely use.
(I am not trying to be obstructive; if a community fork of Hazard3 gets traction I am happy to contribute and help out with issues and questions. However, the core RTL in this repository will remain single-author.)
Do not raise issues with suggested code changes to core RTL. This is the same thing as a pull request, and I will close the issue without reading the patch. Please clearly identify the issue and I will fix it.
## Issues
There are three main categories of issues which are helpful to the project: _bug reports_, _feature requests_ and _questions_.
### Bug Reports
If you find a bug in the Hazard3 repository, please report it. This includes:
1. A functional bug in Hazard3 such as mis-execution, or ISA non-compliance
2. A compatibility issue with your tools
* Please do not raise cosmetic lint issues: the intersection of clean Verilog across all lint tools is the empty set. Hazard3 is lint-clean with Verilator lint.
* A lint issue relating to simulation/synthesis mismatch is important though, and falls under point **1** above.
Before I fix a bug I must reproduce it on my own machine. I cannot fix issues on faith as this is unlikely to result in a reliable or complete fix. Please include the following in a bug report to ensure I can reproduce the issue:
I am overwhelmingly more likely to implement requests for standard RISC-V ISA features than custom ones. As a rule, I don't implement standard RISC-V features that are not at least in the Frozen state. Please also consider the availability of toolchain support and upstream tests.
### Questions
The following questions are relevant to this repository and I am happy to answer them:
* Questions about Hazard3's implementation-defined behaviour in relation to the RISC-V standards
* Questions about tools used to build the Hazard3 simulator or tests (which are not covered by [Readme.md](Readme.md))
The following questions are not relevant and I am likely to either ignore or close them:
* Questions about Verilog
* The IEEE 1364-2005 PDF can be found online
* The best way to learn is to just do it ([instructional video](https://www.youtube.com/watch?v=ZXsQAXx_ao0))
* Get an FPGA board like an iCEBreaker and get hacking
* Yosys and nextpnr are great if you are already familiar with software tooling
* Start with blinking an LED, then PWM the LED, then implement UART TX, then UART RX
* Questions about the RISC-V ISA
* Get the latest ISA manual [here](https://github.com/riscv/riscv-isa-manual/releases/latest) (you want the _unprivileged_ manual first -- I find the HTML version more readable these days)
* There are some excellent books on the topic. I recommend the RISC-V edition of _Computer Organization and Design_ by Patterson & Hennessy for a gentle introduction to computer architecture as well as the RISC-V ISA.
* Questions which are not questions, i.e. telling me how clever you are
