cargo/README.md

LINSORTER - LinearINsertion SORTER 
=======================================================

Block diagram of the LinearINsertion SORTER is given below and detailed explanation of the each block is given inside submodules `lis` and `wb2axip`.

![Global block scheme of the LINSORTER](./doc/images/LinearSorters.svg)

This directory contains following submodules and directories:

* Submodule `lis` -  contains a linear insertion sorter (LIS) generator written in [Chisel ](http://www.chisel-lang.org) hardware design language. It comprises description of three types of the linear insertion sorter, parameter definition, setup explanation and many other useful information related to blocks that are depicted at presented global block scheme.
* Submodule  `wb2axip` - contains wishbone to AXI4 bridge. Current submodule is forked version of the [ZipCPU/wb2axip](https://github.com/ZipCPU/wb2axip). 
* `doc` - contains global block scheme of the LINSORTER in svg and png format.
* `top/dv/LISTest` - contains verilog testbenches for LINSORTER integrated with Caravel
* `top/rtl/LISTest` - contains `user_proj_example.v` which is the top level verilog file for LINSORTER
* Makefile - has targets for verilog and test generation

## Verilog generation and Chisel tests

**Prerequisites:**
The following software packages should be installed prior to generate Verilog code and Chisel tests:
* [sbt](http://www.scala-sbt.org)
* [Verilator](http://www.veripool.org/wiki/verilator)

In order to generate  `LISTest.v` which contains verilog code for LinearINsertion SORTER, run command:

    $ make verilog_lis

To run Chisel tests, run command:

    $ make test_lis

## Verilog tests

In order to run Verilog tests for LINSORTER connected to Caravel, PDK_ROOT and RISCV32 paths must be set. RISCV32 is path to RV32I Toolchain. For RV32I toolchain installation click [here](https://github.com/cliffordwolf/picorv32#building-a-pure-rv32i-toolchain). To check if paths are set, run command:

    $ make check-env

There are six different tests for LINSORTER connected to Caravel available inside `top/dv/LISTest/lis` directory:
* BIST_LISFIFO_POUT -  data path is:  BIST-> LIS FIFO ->  outStream (8b AXI4-Stream)
* BIST_LISFixed_POUT - data path is: BIST-> LIS Fixed -> outStream (8b AXI4-Stream)
* BIST_LISInput_POUT -  data path is: BIST-> LIS Input ->  outStream (8b AXI4-Stream)
* PIN_LISFIFO_POUT -  data path is: inStream (8b AXI4-Stream) -> LIS FIFO -> outStream (8b AXI4-Stream)
* PIN_LISFixed_POUT - data path is: inStream (8b AXI4-Stream) -> LIS Fixed -> outStream (8b AXI4-Stream)
*  PIN_LISInput_POUT - data path is: inStream (8b AXI4-Stream) -> LIS Input-> outStream (8b AXI4-Stream)

All tests contain C code for appropriate control registers configurations. Output of the LINSORTER is compared with golden model generated by Chisel.  Golden model outputs are available inside `test_run_dir` directory of the `lis` submodule so there is no need to run Chisel tests prior to running Verilog tests. 

So, for testing LINSORTER attached to the Caravel, run command:

    $ make test_top

To clean data generated by Verilog testbenches, run:

    $ make clean_top
    
In order to regenerate Verilog code, run Chisel and Verilog tests, type following command:

    $ make run_all

## Address space for LINSORTER
```
User address space       0x3000_0000
    ├── in_split:      0x3000_0000
    ├── lisFifo:       0x3000_1000
    ├── lisFifo_mux:   0x3000_1100
    ├── lisFixed:      0x3000_2000
    ├── lisFixed_mux:  0x3000_2100
    ├── lisInput:      0x3000_3000
    ├── lisInput_mux:  0x3000_3100
    ├── bist:          0x3000_4000
    ├── bist_split:    0x3000_4100
    ├── out_mux:       0x3000_5000
    ├── uart:          0x3000_6000
    └── uart_split:    0x3000_6100
```