Skip to content

Commit

Permalink
review readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jjts
jjts committed Oct 24, 2021
1 parent 7e61283 commit 316575e
Show file tree
Hide file tree
Showing 3 changed files with 110 additions and 87 deletions.
1 change: 0 additions & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,6 @@ clean:
make sim-clean
make fpga-clean
make doc-clean
# make asic-clean

clean-all: test-clean

Expand Down
193 changes: 108 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,162 +23,180 @@ for CentOS 7 and Ubuntu 18.04 or 20.04 LTS.

## Clone the repository

The first step is to clone this repository. IOb-SoC git sub-module trees, and
GitHub will ask for your password for each downloaded module. To avoid this,
The first step is to clone this repository. IOb-SoC uses git sub-module trees, and
GitHub will ask for your password for each downloaded module if you clone by *https*. To avoid this,
setup GitHub access with *ssh* and type:
```
git clone --recursive [email protected]:IObundle/iob-soc.git
cd iob-soc
```

Alternatively, you can clone this repository using *https*. You might want to
cache your credentials before cloning the repository, using:
``git config --global credential.helper 'cache --timeout=<time_in_seconds>'``
Alternatively, you can still clone this repository using *https* if you cache
your credentials before cloning the repository, using: ``git config --global
credential.helper 'cache --timeout=<time_in_seconds>'``


## Configure your SoC

To configure your system edit the *system.mk* file, which can be found at the
repository root. In this file, you can find the system configuration variables;
each variable is explained by a comment.
repository root. This file has the system configuration variables;
hopefully, each variable is explained by a comment.


## Set environment variables for local or remote building and running

The various simulators, FPGA compilers and FPGA boards may be run locally or
The various simulators, FPGA compilers and FPGA boards may run locally or
remotely. For running a tool remotely, you need to set two environmental
variables: the server logical name and the server user name. You may place these
settings in your .bashrc file, so that they apply to every session.
variables: the server logical name and the server user name. Consider placing
these settings in your .bashrc file, so that they apply to every session.


### Set up the remote simulator server

For example, in `hardware/simulation/icarus/Makefile`, the variable for the
server logical name, SIM\_SERVER, is set to IVSIM\_SERVER, and the variable for
the user name, SIM\_USER, is set to IVSIM_USER. Hence, you need to set the
latter variables as in the following example:
Using open-source simulator Icarus Verilog as an example, note that in
`hardware/simulation/icarus/Makefile`, the variable for the server logical name,
SIM\_SERVER, is set to IVSIM\_SERVER, and the variable for the user name,
SIM\_USER, is set to IVSIM_USER. If you do not set these variables the simulator
will run locally. To run the simulator on server *mysimserver.myorg.com* as
user *ivsimuser*, set the following environmental variables beforehand:

```
export IVSIM_SERVER=mysimserver.myorg.com
export IVSIM_USER=myusername
export IVSIM_SERVER=ivsimserver.myorg.com
export IVSIM_USER=ivsimuser
```

### Set up the remote FPGA toolchain and board servers

For example, in `hardware/fpga/quartus/CYCLONEV-GT-DK/Makefile` the variable for
the FPGA tool server logical name, FPGA\_SERVER, is set to QUARTUS\_SERVER, and the
variable for the user name, FPGA\_USER, is set to QUARTUS\_USER; the variable for
the board server, BOARD\_SERVER, is set to CYC5\_SERVER, and the variable for
the board user, BOARD\_USER, is set to CYC5_USER. Hence, you need to set the
latter variables as in the following example:
Using the CYCLONEV-GT-DK board as an example, note that in
`hardware/fpga/quartus/CYCLONEV-GT-DK/Makefile` the variable for the FPGA tool
server logical name, FPGA\_SERVER, is set to QUARTUS\_SERVER, and the variable
for the user name, FPGA\_USER, is set to QUARTUS\_USER; the variable for the
board server, BOARD\_SERVER, is set to CYC5\_SERVER, and the variable for the
board user, BOARD\_USER, is set to CYC5_USER. As in the previous example, set
these variables as follows:

```
export QUARTUS_SERVER=<hostname.domain>
export QUARTUS_USER=<username>
export CYC5_SERVER=<hostname.domain>
export CYC5_USER=<username>
export QUARTUS_SERVER=quartusserver.myorg.com
export QUARTUS_USER=quartususer
export CYC5_SERVER=cyc5server.myorg.com
export CYC5_USER=cyc5username
```

### Set up the remote ASIC toolchain server

In `hardware/asic/Makefile`, the variable for the server logical name,
ASIC\_SERVER, is set to CADENCE\_SERVER, and the variable for the user name
ASIC\_USER is set to CADENCE\_USER. Hence, you need to set the latter variables
as in the following example:
Using the umc130 node as an example, note that in `hardware/asic/Makefile`, the
variable for the server logical name, ASIC\_SERVER, is set to CADENCE\_SERVER,
and the variable for the user name ASIC\_USER is set to CADENCE\_USER. Hence,
set these variables as follows:

```
export CADENCE_SERVER=<hostname.domain>
export CADENCE_USER=<username>
export CADENCE_SERVER=cadenceserver.myorg.com
export CADENCE_USER=cadenceuser
```

In each remote server, the environmental variables for tool paths and license
In each remote server, the environment variables for the executable paths and license
servers used must be defined as in the following example:

```
export QUARTUSPATH=/path/to/quartus
export VIVADOPATH=/path/to/vivado
...
export LM_LICENSE_FILE=port@hostname.domain;lic_or_dat_file
export LM_LICENSE_FILE=port@licenseserver.myorg.com;lic_or_dat_file
```


## Simulate the system

To simulate IOb-SoC, the simulator must be installed, either locally or
remotely, and must have a run directory under the `hardware/simulation`
directory. To simulate, type:
directory, such as the `hardware/simulation/icarus` directory. To simulate,
type:

```
make [sim] [SIMULATOR=<simulator directory name>] [<control parameters>]
```
where `<simulator directory name>` is the name of the simulator's run directory,
and `<control parameters>` are system configuration parameters passed in the
command line, overriding those in the system.mk file. For example, `<control
parameters>` can be replaced with `INIT_MEM=0 RUN_EXTMEM=1`.

`<simulator directory name>` is the name of the simulator's run directory,

`<control parameters>` are system configuration parameters passed in the
command line, overriding those in the system.mk file. Example control
parameters are `INIT_MEM=0 RUN_EXTMEM=1`.

To visualise simulation waveforms use the `VCD=1` control parameter. It will
open the Gtkwave visualisation program.
open the Gtkwave waveform visualisation program.

To clean simulation generated files, type:
```
make sim-clean [SIMULATOR=<simulator directory name>]
```

For more details, read the Makefile in each simulator directory.
For more details, read the Makefile in each simulator directory. The Makefile
includes the Makefile segment `simulation.mk`, which contains statements that
apply to any simulator. In turn, `simulation.mk` includes the Makefile segment
`system.mk`, which contains main system parameters. The Makefile in the
simulator's directory, with the segments recursively included as described, is
construed as a single large Makefile.

## Emulate the system on PC

If there are embedded software compilation or runtime issues you may want to
emulate the system on a PC ot debug those issues. To emulate IOb-SoC's embedded
If there are embedded software compilation or runtime issues you can
*emulate* the system on a PC to debug the issues. To emulate IOb-SoC's embedded
software on a PC, type:

```
make pc-emul [<control parameters>]
```
where `<control parameters>` are system configuration parameters passed in the
command line, overriding those in the system.mk file. For example, `<control
parameters>` can be replaced with `INIT_MEM=0 RUN_EXTMEM=1`.
command line, overriding those in the system.mk file. Example control
parameters are `INIT_MEM=0 RUN_EXTMEM=1`.

To clean the PC compilation generated files, type:
```
make pc-emul-clean
```

For more details, read the Makefile in the `software/pc-emul` directory.
For more details, read the Makefile in the `software/pc-emul` directory. As
explained for the simulation make file, note the Makefile segments recursively
included.


## Build and run on FPGA board

To build and run IOb-SoC on an FPGA board, the FPGA design tools must be
installed, either locally or remotely, the board must be attached to the local
host or to a remote host, and each board must have a run directory under the
`hardware/fpga` directory, for example the `hardware/fpga/BASYS3` directory. The
FPGA tools and board hosts may be different.
host or to a remote host, and each board must have a build directory under the
`hardware/fpga/<tool>` directory, for example the `hardware/fpga/vivado/BASYS3`
directory. The FPGA tools and board hosts may be different.

To build only, type
```
make fpga-build [BOARD=<board directory name>] [<control parameters>]
```
where `<board directory name>` is the name of the board's run directory, and
`<control parameters>` are system configuration parameters passed in the command
line, overriding those in the system.mk file. For example, `<control
parameters>` can be replaced with `INIT_MEM=0 RUN_EXTMEM=1`, etc. For more details,
read the Makefile in the board directory.
line, overriding those in the system.mk file. For example,
```
make fpga-build BOARD=BASYS3 INIT_MEM=0 RUN_EXTMEM=1
```

For more details read the Makefile in the board directory, and follow the
recursively included Makefile segments as explained before.

To build and run, type:
```
make fpga-run [BOARD=<board directory name>] [<control parameters>]
```

Before running, the FPGA is loaded with the configuration bitstream. However if
the bitstream checksum matches that of the last loaded bitstream, kept in file
`/tmp/<board directory name>.load`, this step is skipped. If, for some reason,
the FPGA does not run, you may interrupt it with Ctr-C. Then run make fpga-run
again and force the bitstream to be reloaded using control parameter FORCE=1.
The FPGA is loaded with the configuration bitstream before running. However,
this step is skipped if the bitstream checksum matches that of the last loaded
bitstream, kept in file `/tmp/<board directory name>.load`. If, for some reason,
the run gets stuck, you may interrupt it with Ctr-C. Then, you may try again
forcing the bitstream to be reloaded using control parameter FORCE=1.

If many users are trying to run the same FPGA board they will be queued in file
`/tmp/<board directory name>.queue`, before being able to load the bistream and
run. After a successful run or Ctr-C interrupt, the user is dequeued.
`/tmp/<board directory name>.queue`. Users will orderly load their bitstream
onto the board and start running it. After a successful run or Ctr-C interrupt,
the user is de-queued.


To clean the FPGA compilation generated files, type
Expand All @@ -189,19 +207,22 @@ make fpga-clean [BOARD=<board directory name>]
## Compile the documentation

To compile documents, the LaTeX document preparation software must be
installed. To compile the document given by the DOC variable, type:
installed. Each document that can be compiled has a build directory under the
`document`directory. Currently there are two document build directories:
`presentation` and `pb` (product brief). The document to build is specified by
the DOC control parameter. To compile the document, type:
```
make doc [DOC=<document directory name>]
```


To clean the compilation files of the document given by the DOC variable, type:
To clean the document's build directory, type:
```
make doc-clean [DOC=<document directory name>]
```

For more details, read the Makefile in each document's directory

For more details, read the Makefile in each document's directory, and follow the
recursively included Makefile segments as explained before.


## Testing
Expand All @@ -212,33 +233,30 @@ To run a series of simulation tests on the simulator selected by the SIMULATOR
variable, type:

```
make test-simulator [SIMULATOR=<simulator directory name>]
make test-simulator [SIMULATOR=<simulator directory>]
```

The above command creates a file called `test.log` in directory
`hardware/simulation/<simulator directory name>`, which is compared to file
`test.expected`in the same directory; if they differ, the test is aborted.
The above command produces a test log file called `test.log` in the simulator's
directory. The `test.log` file is compared with the `test.expected` file, which
resides in the same directory; if they differ, the test fails; otherwise, it
passes.

To run the series of simulation tests on all the simulators listed in the
SIM\_LIST variable, type:

```
make test-all-simulators [SIM_LIST="<simulator directory name list>"]
make test-all-simulators [SIM_LIST="<simulator directory list>"]
```
where `<simulator directory name list>` is the list of sub-directory names in directory `hardware/simulation`, which correspond to simulator names.

where `<simulator directory list>` is the list of sub-directories in directory
`hardware/simulation`, which correspond to simulator names.

To clean the files produced when testing all simulators, type:

```
make clean-all-simulators
```

The above simulation and board test commands will produce a test log file called
`test.log` in each simulator or board sub-directory. With the `test-all-simulators` or the `test-all-boards` targets, the
`test.log` file is compared with the expected file log in the respective
simulator or board directory; if they differ, an error is issued.



### Board test

Expand All @@ -249,9 +267,10 @@ variable, type:
make test-board [BOARD=<board directory name>]
```

The above command creates the file `software/console/test.log`, which is
compared to file `hardware/fpga/<FPGA compiler name>/<board directory
name>/test.expected`; if they differ, the test is aborted.
The above command produces a test log file called `test.log` in the board's
directory. The `test.log` file is compared with the `test.expected` file, which
resides in the same directory; if they differ, the test fails; otherwise, it
passes.

To run the series of board tests on all the boards listed in the BOARD\_LIST
variable, type:
Expand All @@ -268,12 +287,15 @@ make clean-all-boards

### Documentation test

To compile and test the document given in the DOC, variable, type:
To compile and test the document selected by the DOC, variable, type:

```
make test-doc [DOC=<document directory name>]
```

The resulting Latex .aux file is compared with a known-good .aux file. If the
match the test passes; otherwise it fails.

To test all documents listed in the DOC\_LIST variable, type:

```
Expand All @@ -294,8 +316,8 @@ make test

## Cleaning

The following command will clean the selected directories for simulation and
board runs, locally and in the remote servers:
The following command will clean the selected simulation, board and document
directories, locally and in the remote servers:

```
make clean
Expand All @@ -309,11 +331,12 @@ make clean

```
git clone https://github.com/riscv/riscv-gnu-toolchain
git checkout 2021.01.26
```

### Prerequisites

For Ubuntu OS and its variants:
For the Ubuntu OS and its variants:

```
sudo apt install autoconf automake autotools-dev curl python3 python2 libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
Expand All @@ -332,10 +355,10 @@ cd riscv-gnu-toolchain
sudo make -j$(nproc)
```

This will take a while... After it is done, type:
This will take a while. After it is done, type:
```
export PATH=$PATH:/path/to/riscv/bin
```

The above command should be added to the bottom of your ~/.bashrc file, so that
you do not have to type it every session.
The above command should be added to your ~/.bashrc file, so that
you do not have to type it on every session.
3 changes: 2 additions & 1 deletion hardware/fpga/fpga.mk
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,8 @@ queue-out-remote:
#

test: clean-testlog test1 test2 test3
diff -q $(CONSOLE_DIR)/test.log test.expected
mv $(CONSOLE_DIR)/test.log .
diff -q test.log test.expected

test1:
make clean
Expand Down

0 comments on commit 316575e

Please sign in to comment.