quicklogic/README.md

# SymbiFlow for QuickLogic FPGAs

Currently, the supported families are:

- pp3 (EOS-S3 SoC)
- qlf_k4n8

## Quickstart guide

### 1. Build F4PGA Architecture Definitions

Clone the repository:

```bash
git clone https://github.com/SymbiFlow/f4pga-arch-defs
```

Set up the environment:

```bash
make env
```

The command will automatically clone all GIT submodules, setup a Conda environment with all the necessary packages and generate the build system by invoking CMake.

### 2. Generate a bitstream for a sample design

Once the SymbiFlow environment is set up, you can perform the implementation (synthesis, placement and routing) of an example FPGA designs.

Go to the `quicklogic/<family>/tests` directory and choose a design you want to implement e.g:

```bash
cd quicklogic/pp3/tests/counter
make counter-ql-chandalar_bit
```

This will generate a binary bitstream file for the design. The resulting bitstream will be written to the `top.bit` file in the working directory of the design.

Currently supported basic designs in pp3 faimly are:

- btn_counter
- consts
- counter
- lut
- wire

For details of each of the test design please refer to its `README.md` file.

### 3. Programming the EOS S3 SoC

To simplify the programming process, some helper scripts were integrated with the flow.
The scripts can automatically configure the IOMUX of the SoC so that all top-level IO ports of the design are routed to the physical pads of the chip.

In order to generate the JLink programming script, build the following target:

```bash
make counter-ql-chandalar_jlink
```

or to generate OpenOCD script:

```bash
make counter-ql-chandalar_openocd
```

The script will contain both the bitstream and IOMUX configuration.

## Naming convention

The naming convention of all build targets is: `<design_name>-<board_name>_<stage_name>`

The `<design_name>` corresponds to the name of the design.
The `<board_name>` defines the board that the design is targetted for, possible values are `ql-chandalar` and `ql-quickfeather`
The last part `<stage_name>` defines the last stage of the flow that is to be executed.

The most important stages are:

- **eblif**
    Runs Yosys synthesis and generates an EBLIF file suitable for VPR. The output EBLIF file is named `top.eblif`

- **pack**
    Runs VPR packing stage. The packed design is written to the `top.net` file.

- **place**
    Runs VPR placement stage. Design placement is stored in the `top.place` file. IO placement constraints for VPR are written to the `top_io.place` file.

- **route**
    Runs VPR pack, place and route flow. The packed design is written to the `top.net` file. design placement and routing data is stored in the `top.place` and `top.route` files respectively. IO placement constraints for VPR are written to the `top_io.place` file.

- **analysis**
    Runs VPR analysis, writes post-route netlists in BLIF and Verilog format plus an SDF file with post routing timing analysis.

- **fasm**
    Generates the FPGA assembly file (a.k.a. FASM) using the routed design. The FASM file is named `top.fasm`.

- **bit**
    Generates a binary bitstream file from the FASM file using the `qlfasm.py` tool. The bitstream is ready to be loaded to the FPGA.

- **jlink**
    For convenience of programming the EOS S3 SoC, the `jlink` stage generates a command script which configures the IOMUX of the SoC and loads the bitstream to the FPGA. The script is ready to be executed via the *JLink commander* tool.

- **openocd**
    The `openocd` stage generates an OpenOCD script with `load_bitstream` process which configures the IOMUX of the SoC and loads the bitstream to the FPGA. The script is ready to be executed via the *GDB* tool. To do so, connect to target with OpenOCD, append the generated script to command set: `-f top.openocd` and execute in GDB session `monitor load_bitstream`.

- **bit_v**
    Runs the `fasm2bels` tool on the bitstream generated by the `bit` target. The ``fasm2bels`` tool converts a bitstream or a FASM file to a Verilog file containing basic elements (BELs) and connections between them. The resulting file is named `top_bit.v`

Executing a particular stage implies that all stages before it will be executed as well (if needed). They form a dependency chain.

Note: stages **jlink**, **openocd**, **bit_v** are available only for the pp3 family.

## Adding new designs to SymbiFlow

To to add a new design to the flow, and use it as a test follow the guide:

1. Create a subfolder for your design under the `quicklogic/<family>/tests` folder.

1. Add inclusion of the folder in the `quicklogic/<family>/tests/CMakeLists.txt` by adding the following line to it:

    ```plaintext
    add_subdirectory(<your_directory_name>)
    ```

1. Add a `CMakeLists.txt` file to your design. Specify your design settings inside it:

    ```plaintext
    add_fpga_target(
      NAME            <your_design_name>
      BOARD           <target_board_name>
      SOURCES         <verilog sources list>
      INPUT_IO_FILE   <PCF file with IO constraints>
      SDC_FILE        <SDC file with timing constraints>
      )
    ```

    The design name can be anything. For available board names please refer to the `quicklogic/<family>/boards.cmake` file. Input IO constraints have to be given in the *PCF* format. The *SDC* file argument is optional.
    Please also refer to CMake files for existing designs.
    All the files passed to `add_fpga_target` have to be added to the flow with `add_file_target` e.g:

    ```plaintext
    add_file_target(FILE counter.v SCANNER_TYPE verilog)
    add_file_target(FILE chandalar.pcf)
    ```

    The verilog scanner will automatically add all the verilog dependecies explicitely included in the added file.

1. Once this is done go back to the SymbiFlow root directory and re-run the make env command to update build targets:

   ```bash
   make env
   ```

1. Now enter the build directory of your project and run the appropriate target as described:

   ```bash
   cd build/quicklogic/<family>/tests/<your_directory_name>
   make <your_design_name>-<target_board_name>_bit
   ```