<commit_before># Project Oxide - documenting Lattice's 28nm "Nexus" FPGA parts

## Current Status

A framework is in place to parse bitstreams and fuzz bitstream changes. Currently the logic tile (PLC) config and interconnect; basic IO and IOLOGIC config; EBR config; global routing and basic DSP config have been fuzzed. Remaining work includes finishing IO and DSP fuzzing; and fuzzing the hard IP like PCIe, PLLs and DPHY.

nextpnr development is currently in [this branch](https://github.com/daveshah1/nextpnr/tree/nextpnr-nexus).

## Links

- [HTML documentation](https://daveshah1.github.io/prjoxide-html/)

## Getting Started - Complete Flow

### Prerequisites

 - Install the nextpnr and Yosys prerequisites (example for Ubuntu):
 ```
    sudo apt-get install build-essential clang bison flex libreadline-dev \
                     gawk tcl-dev libffi-dev git mercurial graphviz   \
                     xdot pkg-config python python3 libftdi-dev \
                     qt5-default python3-dev libboost-all-dev cmake libeigen3-dev
```
 - Build and install latest git [Yosys](https://github.com/YosysHQ/yosys)
 - Install a Rust toolchain using [rustup](https://rustup.rs/)
 - Build and install [ecpprog](https://github.com/gregdavill/ecpprog)

### Building the prjoxide tool

Clone prjoxide recursively, so you get a copy of the database too

    git clone --recursive https://github.com/daveshah1/prjoxide

A single command line tool `prjoxide` supports subcommands for bitstream packing and unpacking as well as BBA generation for the nextpnr build process. To build and install it, run:

    cd libprjoxide
    cargo install --path prjoxide

This will, by default, install to `~/.cargo/bin` which you may need to add to your `PATH`. You can use `--root` or the `CARGO_INSTALL_ROOT` environment variable to override the installation root.

This executable contains all data embedded in it; so it can be freely moved to another location on your system if required. Consequently, however, you will need to rebuild prjoxide after a database update.

### Building nextpnr-nexus

Clone the development repo and switch to the correct fork

    git clone https://github.com/daveshah1/nextpnr nextpnr-nexus
    cd nextpnr-nexus
    git checkout nextpnr-nexus

Build nextpnr-nexus, making sure to point it to the correct path for the prjoxide tool:

    cmake -DARCH=nexus -DOXIDE_INSTALL_PREFIX=/home/david/.cargo .
    make -j8

### Running the example designs

There are currently examples for the CrossLink-NX EVN and VIP boards in prjoxide.

    cd prjoxide/examples/blinky_evn
    make prog
<commit_msg>Update README to reflect upstreaming<commit_after># Project Oxide - documenting Lattice's 28nm "Nexus" FPGA parts

## Current Status

A framework is in place to parse bitstreams and fuzz bitstream changes. Currently the logic tile (PLC) config and interconnect; basic IO and IOLOGIC config; EBR config; global routing and basic DSP config have been fuzzed. Remaining work includes finishing IO and DSP fuzzing; and fuzzing the hard IP like PCIe, PLLs and DPHY.

nextpnr development is currently in [this branch](https://github.com/daveshah1/nextpnr/tree/nextpnr-nexus).

## Links

- [HTML documentation](https://daveshah1.github.io/prjoxide-html/)

## Getting Started - Complete Flow

### Prerequisites

 - Install the nextpnr and Yosys prerequisites (example for Ubuntu):
 ```
    sudo apt-get install build-essential clang bison flex libreadline-dev \
                     gawk tcl-dev libffi-dev git mercurial graphviz   \
                     xdot pkg-config python python3 libftdi-dev \
                     qt5-default python3-dev libboost-all-dev cmake libeigen3-dev
```
 - Build and install latest git [Yosys](https://github.com/YosysHQ/yosys)
 - Install a Rust toolchain using [rustup](https://rustup.rs/)
 - Build and install [ecpprog](https://github.com/gregdavill/ecpprog)

### Building the prjoxide tool

Clone prjoxide recursively, so you get a copy of the database too

    git clone --recursive https://github.com/daveshah1/prjoxide

A single command line tool `prjoxide` supports subcommands for bitstream packing and unpacking as well as BBA generation for the nextpnr build process. To build and install it, run:

    cd libprjoxide
    cargo install --path prjoxide

This will, by default, install to `~/.cargo/bin` which you may need to add to your `PATH`. You can use `--root` or the `CARGO_INSTALL_ROOT` environment variable to override the installation root.

This executable contains all data embedded in it; so it can be freely moved to another location on your system if required. Consequently, however, you will need to rebuild prjoxide after a database update.

### Building nextpnr-nexus

Clone nextpnr:

    git clone https://github.com/YosysHQ/nextpnr
    cd nextpnr

Build nextpnr-nexus, making sure to point it to the correct path for the prjoxide tool:

    cmake -DARCH=nexus -DOXIDE_INSTALL_PREFIX=/home/david/.cargo .
    make -j8

### Running the example designs

There are currently examples for the CrossLink-NX EVN and VIP boards in prjoxide.

    cd prjoxide/examples/blinky_evn
    make prog

{'fraction_non_alphanumeric': 0.07230320699708455, 'fraction_numerical': 0.004081632653061225, 'mean_word_length': 3.6276978417266186, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, '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': '4273823', 'n_tokens_mistral': 1607, 'n_tokens_neox': 1497, 'n_words': 612}