Getting Started

Contents

1. Setup directory
2. Create an AND gate core: “iob_and”
3. Setup and build

Setup directory

The setup directory of a core may have the following structure:

.
├── core_name.py
├── core_name.json
├── document
│   ├── doc_build.mk
│   ├── figures
│   └── tsrc
├── hardware
│   ├── src
│   ├── fpga
│   │   ├── fpga_build.mk
│   │   ├── src
│   │   ├── quartus
│   │   └── vivado
│   ├── modules
│   ├── simulation
│   │   ├── sim_build.mk
│   │   └── src
│   └── syn
│       ├── src
│       └── genus
├── software
│   ├── sw_build.mk
│   └── src
├── scripts
├── submodules
├── Makefile
├── README.md
├── LICENSE
├── CITATION.cff
└── default.nix

Only the core_name.py or core_name.json file is needed to pass the core's description to Py2HWSW. The remaining directories and files are optional.

If the document, hardware, and software directories exist, they will be copied to the build directory, overriding any files already present there, such as standard ones or files from other cores.

The *_build.mk files allow the user to include core specific Makefile targets and variables from the build process. These will be copied to the build directory and included in the standard build process Makefiles.

The src directories contain manually written Verilog/C/TeX sources for the core, should they be needed.

The following directories and files do not follow a mandatory structure, but are typically used for the following purposes:

The hardware/modules and submodules directories typically contain setup directories of other cores.

The scripts directory contains scripts specific to the core, and may be called by the user or from the core_name.py script.

Create an AND gate core: “iob_and”

The simplest core description for Py2HWSW is as follows:

def setup(py_params_dict):
    attributes_dict = {
        "original_name": "iob_and",
        "name": "iob_and",
        "version": "0.1",
        "confs": [
            {
                "name": "W",
                "type": "P",
                "val": "21",
                "min": "1",
                "max": "32",
                "descr": "IO width",
            },
        ],
        "ports": [
            {
                "name": "and_i",
                "descr": "Input port",
                "signals": [
                    {"name": "a", "width": "W", "direction": "input"},
                    {"name": "b", "width": "W", "direction": "input"},
                ],
            },
            {
                "name": "y",
                "descr": "Output port",
                "signals": [
                    {"name": "y", "width": "W", "direction": "output"},
                ],
            },
        ],
        "snippets": [{"verilog_code": "   assign y_o = a_i & b_i;"}],
    }

    return attributes_dict

View Source

More examples and information can be found in the How To Use section.

A set of basic cores to showcase the various Py2HWSW features can be found in the basic_tests directory.

Setup and build

To checkout the source and setup the core:

$ git clone --recursive [email protected]:IObundle/iob-soc.git
$ cd iob-soc
$ nix-shell  # Optional step to install environment with necessary dependencies
$ py2hwsw iob_soc setup

To do a clean setup:

$ py2hwsw iob_soc clean
$ py2hwsw iob_soc setup

The setup process will generate a build directory containing the core's verilog sources and build files. By default, the build directory is ../[core_name]_V[core_version].

To build and run the core in simulation:

$ make -C ../iob_soc_V0.7 sim-run