Metadata-Version: 2.4
Name: peakrdl-fw-hdl
Version: 0.1.0
Summary: Generate Featherweight-HDL register descriptions from compiled SystemRDL input
Author: Matthew Ballance
License: Apache-2.0
Project-URL: Source, https://git.dvkit.org/featherweight-hdl/peakrdl-fw-hdl
Keywords: SystemRDL,PeakRDL,CSR,compiler,tool,registers,generator,SystemVerilog,featherweight-hdl,fw-hdl
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: systemrdl-compiler~=1.31
Requires-Dist: jinja2>=2.9
Provides-Extra: cli
Requires-Dist: peakrdl-cli>=1.2.3; extra == "cli"
Dynamic: license-file

# PeakRDL-fw-hdl

A [PeakRDL](https://peakrdl.readthedocs.io) export plug-in that turns a SystemRDL
register model into a **Featherweight-HDL register description** — the
SystemVerilog class form built on `fw_reg_block #(W)` / `fw_reg #(T)`.

The output is class-level model source, not RTL and not a UVM RAL model: it is
consumed both by simulation testbenches and by fw-hdl's own synthesis front end,
which lowers it to a register-block module.

## Install

```bash
pip install peakrdl-fw-hdl[cli]
```

## Use

```bash
peakrdl fw-hdl my_ip.rdl -o my_ip_reg_pkg.sv
```

In goes SystemRDL:

```systemrdl
reg dma_ch_csr {
    field { sw = rw; hw = r; }                ch_en[0:0];
    field { sw = r;  hw = w; }                busy[10:10];
    field { sw = r;  hw = w; onread = rclr; } int_done[21:21];
};

addrmap dma_regs {
    dma_ch_csr csr @ 0x0;
};
```

Out comes the fw-hdl idiom:

```systemverilog
package dma_reg_pkg;
    import fw_hdl_pkg::*;

    typedef struct packed {
        bit [9:0] reserved_31_22; // 31:22 RESERVED
        bit       int_done;       // 21 ROC
        bit [9:0] reserved_20_11; // 20:11 RESERVED
        bit       busy;           // 10 RO
        bit [8:0] reserved_9_1;   // 9:1 RESERVED
        bit       ch_en;          // 0 RW
    } dma_ch_csr_t;

    class dma_regs extends fw_reg_block #(32);
        fw_reg #(dma_ch_csr_t) csr; // 0x0000

        function new(string name);
            super.new(name);
            csr = new("csr", this, 'h0,
                      .sw_wmask(dma_ch_csr__sw_wmask()),
                      .hw_wmask(dma_ch_csr__hw_wmask()),
                      .rclr_mask(dma_ch_csr__rclr_mask()));
        endfunction

        static function dma_ch_csr_t dma_ch_csr__sw_wmask();
            return '{ ch_en:1, default:'0 };
        endfunction
        // ... hw_wmask, rclr_mask
    endclass
endpackage: dma_reg_pkg
```

SystemRDL says more than fw-hdl's four behavior words (`reset`, `sw_wmask`,
`hw_wmask`, `rclr_mask`) can express. Everything that does not fit is reported at
the field that caused it, with a stable message code, and annotated in the
generated source — never silently changed. `--strict` turns those reports into
errors.

## Documentation

- [`docs/`](docs/) — installation, usage, the normative mapping reference, and
  the limitations table
- [`docs/design.md`](docs/design.md) — why the mapping is what it is
- [Featherweight HDL](https://git.dvkit.org/featherweight-hdl/fw-hdl) — the
  register class library this targets

## License

Apache-2.0
