# RTL Coding

## Organization

### lib/oclib_*

Library elements

## Naming Style

### Modules
- lowercase_underlined
- OC reserved prefixes: `oclib_*`, `oc_*`
- Complete words: `oclib_synchronizer`
    - Except for standard cases (`oclib_fifo`, `oclib_csr_to_drp`)

### Parameters
- CamelCase
- Full words
  
### Ports/Signals
- lowercase_underlined
- Clocks must start with `clock`
    - Various backend flows may rely on this
    - Single clock modules should just have `clock`
    - Multi-clock modules can use the default `clock` and others (`clockJtag`), or just several non-default clocks (`clockRead`, `clockWrite`)
- Resets should start with `reset`
    - When >1 reset, labels match clock (`clockAxi`/`resetAxi`)
 
### Indentation
- Matches Verilog-Mode for Emacs

## Defines

### Automatically set by `eda`

`eda sim` always sets `SIMULATION` (with no value) regardless of tool. Most simulator tools
additionally set `SIMULATION=1` via their tool config. Use `SIMULATION` to gate simulation-only
code such as assertions, coverage, and `$display` calls:

```systemverilog
`ifdef SIMULATION
  assert (valid) else $fatal(1, "invalid");
`endif
```

Each tool sets its own `OC_TOOL_*` define. RTL can use these to conditionalize
tool-specific workarounds. Example for open-source simulators:

| Tool | Define(s) set |
|---|---|
| `verilator` | `SIMULATION=1` |
| `iverilog` | `SIMULATION=1`, `IVERILOG=1` |
| `questa` | `OC_TOOL_QUESTA=1` |
| `riviera` | `OC_TOOL_RIVIERA=1`, `RIVIERA=1` |
| `modelsim_ase` | `OC_TOOL_MODELSIM_ASE=1` |

The full list of tool defines is in `opencos/eda_config_defaults.yml` under each tool's `defines:`
key, and is also documented in `docs/eda.md`.

`SEED` is **not** automatically set; to expose the seed to RTL pass `+define+SEED=%SEED%` on the
`eda sim` command line or in a DEPS file (`%SEED%` is expanded by `eda` to the actual seed value).

`SYNTHESIS` is conventionally set by synthesis tools, but is not set automatically by `eda` —
add it to the DEPS `defines:` for synthesis targets or use an `eda_config.yml` override.

### Reserved define namespaces

- Universal: `SIMULATION`, `SYNTHESIS`, `SEED`
- OC reserved prefix: `OC_*`
- Tool and version: `OC_TOOL_*`
    - e.g. `OC_TOOL_VIVADO`, `OC_TOOL_VIVADO_2022.2`
- Library: `OC_LIBRARY_*`
    - e.g. `OC_LIBRARY_ULTRASCALE_PLUS`
- Target: `OC_TARGET_*`
    - e.g. `OC_TARGET_U200`
  
## Includes
- Default settings by EDA
    - `+incdir+<Root of OpenCOS repo>`
    - `+libext+.sv+.v`
- Include files should use header guards
    - ``ifdef __LIB_OCLIB_DEFINES_VH`
- RTL files should ``include` their dependencies (not include them in DEPS)

## Parameters
- Always have default values
    - they may be invalid and caught with a static assert
    - purpose here is to ensure modules can report detailed error ("You must set parameter X because ...") instead of not compiling