Skip to content

Commit

Permalink
Merge pull request #975 from arturum1/main
Browse files Browse the repository at this point in the history 
Update README; Rename `PY2HWSW_PATH` to `PY2HWSW_ROOT`.
  • Loading branch information
@jjts
jjts authored Nov 16, 2024
2 parents 8a243e0 + eda18f3 commit 1a2c362
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 89 deletions.
112 changes: 30 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,55 +48,6 @@ To configure your SoC, edit the `iob_soc.py` file, which can be found at the
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 (WIP)

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. Consider placing
these settings in your `.bashrc` file so that they apply to every session.


### Set up the remote simulator server

Using the open-source simulator Icarus Verilog (`iverilog`) as an example, note that in
`submodules/hardware/simulation/icarus.mk,` 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`.

To run the simulator on the server *mysimserver.myorg.com* as user *ivsimuser*, set the following environmental
variables beforehand, or place them in your `.bashrc` file:

```Bash
export IVSIM_SERVER=ivsimserver.myorg.com
export IVSIM_USER=ivsimuser
```

When you start the simulation, IOb-SoC's simulation Makefile will log you on to the server using `ssh,` then `rsync` the files to a remote build directory and run the simulation there. If you do not set these variables, the simulator will run locally if installed.

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

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:

```Bash
export QUARTUS_SERVER=quartusserver.myorg.com
export QUARTUS_USER=quartususer
export CYC5_SERVER=cyc5server.myorg.com
export CYC5_USER=cyc5username
```

In each remote server, the environment variable for the license server used must be defined as in the following example:

```Bash
export [email protected];lic_or_dat_file
```

## Create the build directory

IOb-SoC uses the [Py2HWSW](https://nlnet.nl/project/Py2HWSW/) framework to create a build directory with all the necessary files and makefiles to run the different tools. The build directory is placed in the folder above at ../iob_soc_Vx.y by running the following command from the root directory.
Expand All @@ -119,7 +70,9 @@ You can *emulate* IOb-SoC's on a PC to develop and debug your embedded system. T
```Bash
make pc-emul-run
```

<!--
# TODO: iob-soc repo no longer has sw_build.mk (it comes from iob-system). Should we add it back?
-->
The Makefile compiles and runs the software in the `../iob_soc_Vx.y/software/` directory. The Makefile includes the `sw_build.mk` segment supplied initially in the `./software/` directory in the IOb-SoC root. Please feel free to change this file for your specific project. To run an emulation test comparing the result to the expected result, run
```Bash
make pc-emul-test
Expand All @@ -132,17 +85,17 @@ To simulate IOb-SoC's RTL using a Verilog simulator, run
make sim-run [SIMULATOR=icarus!verilator|xcelium|vcs|questa] [INIT_MEM=0|1] [USE_EXTMEM=0|1]
```

The INIT_MEM variable specifies whether the firmware is initially loaded in the memory, skipping the boot process, and the USE_EXTMEM variable indicates whether an external memory such as DRAM is used, in which case the cache system described above is instantiated.
The INIT_MEM variable specifies whether the firmware is initially loaded in the memory, skipping the boot process, and the USE_EXTMEM variable indicates whether an external memory such as DRAM is used.

The Makefile compiles and runs the software in the `../iob_soc_Vx.y/hardware/simulation` directory. The Makefile includes the `./hardware/simulation/sim_build.mk`, which you can change for your project. To run a simulation test comprising several simulations with different parameters, run
The Makefile compiles and runs the software in the `../iob_soc_Vx.y/hardware/simulation` directory. The Makefile includes the `../iob_soc_Vx.y/hardware/simulation/sim_build.mk`, which you can change for your project. To run a simulation test comprising several simulations with different parameters, run
```Bash
make sim-test
```
The simulation test contents can be edited in IOb-SoC's top Makefile.

Each simulator must be described in the [`./hardware/simulation/<simulator>.mk`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/simulation) file. For example, the file `vcs.mk` describes the VCS simulator.
Each simulator must be described in the [`../iob_soc_Vx.y/hardware/simulation/<simulator>.mk`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/simulation) file. For example, the file `vcs.mk` describes the VCS simulator.

The host machine must run an access server, a Python program in [`./scripts/board_server.py`](https://github.com/IObundle/py2hwsw/blob/main/py2hwsw/scripts/board_server.py), set up to run as a service. The client connects to the host using the SSH protocol and runs the board client program [`./scripts/board_client.py`](https://github.com/IObundle/py2hwsw/blob/main/py2hwsw/scripts/board_client.py). Note that the term *board* is used instead of *simulator* because the same server/client programs control the access to the board and FPGA compilers. The client requests the simulator for GRAB_TIMEOUT seconds, which is 300 seconds by default. Its value can be specified in the `./hardware/fpga/fpga_build.mk` Makefile segment, for example, as
The simulator will timeout after GRAB_TIMEOUT seconds, which is 300 seconds by default. Its value can be specified in the `../iob_soc_Vx.y/hardware/simulation/sim_build.mk` Makefile segment, for example, as
```Bash
GRAB_TIMEOUT ?= 3600
```
Expand All @@ -151,11 +104,11 @@ GRAB_TIMEOUT ?= 3600
## Run on FPGA board

To build and run IOb-SoC on an FPGA board, the FPGA design tools must be
installed locally or remotely. The FPGA board must also be attached to the local
or remote host, not necessarily the same host where the design tools are installed.
installed locally. The FPGA board must also be attached to the local host.

Each board must be described under the [`../iob_soc_Vx.y/hardware/fpga/<tool>/<board_dir>`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/fpga) directory.
For example, the [`../iob_soc_Vx.y/hardware/fpga/vivado/basys3`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/fpga/vivado/basys3) directory contents describe the board BASYS3, which has an FPGA device that can be programmed by the Xilinx/AMD Vivado design tool.

Each board must be described under the [`./hardware/fpga/<tool>/<board_dir>`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/fpga) directory. For example, the [`./hardware/fpga/vivado/BASYS3`](https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/hardware/fpga/vivado/basys3)
directory contents describe the board BASYS3, which has an FPGA device that can be programmed by the Xilinx/AMD Vivado design tool. The access to the board is controlled by the same server/client programs described above for the simulators.
To build an FPGA design of an IOb-SoC system and run it on the board located in the `board_dir` directory, type
```Bash
make fpga-run [BOARD=<board_dir>] [INIT_MEM=0|1] [USE_EXTMEM=0|1]
Expand All @@ -167,30 +120,10 @@ make fpga-test
```
The FPGA test contents can be edited in IOb-SoC's top Makefile.


The remote machines that have an FPGA board attached to it must run our board
access control service script, which can be found in
[`./scripts/board_server.py`](https://github.com/IObundle/py2hwsw/blob/main/py2hwsw/scripts/board_server.py).
When IOb-SoC needs to access a remote
FPGA server, it runs the board access script located in
[`./scripts/board_client.py`](https://github.com/IObundle/py2hwsw/blob/main/py2hwsw/scripts/board_client.py).

To install `board_server.py` as a service, run the following command on the remote FPGA server:
```
sudo make board_server_install
```

To uninstall the service, run

```
sudo make board_server_uninstall
```

Finally, to query the board status, run
```
sudo make board_server_uninstall
```

<!--
# TODO: Explain the `board_client`/`board_server` program. It is also used in local machines.
# Maybe remove the script that uses them in local machines.
-->

## Compile the documentation

Expand Down Expand Up @@ -223,6 +156,18 @@ To clean the build directory, run
make clean
```

## Use another Py2HWSW version

By default, when running the `nix-shell` tool, it will build an environment that contains the Py2HWSW version specified in first lines of the [default.nix file](https://github.com/IObundle/iob-soc/blob/main/default.nix#L8).
You can update the `py2hwsw_commit` and `py2hwsw_sha256` lines of that file to use another version of Py2HWSW from the IObundle's github repository.


If you cloned the Py2HWSW repository to a local directory, you can use that directory as a source for the Py2HWSW nix package.
To use a local directory as a source for Py2HWSW, set the following environment variable with the path to the Py2HWSW root directory:
```Bash
export PY2HWSW_ROOT=/path/to/py2hwsw_root_dir
```


# Acknowledgements

Expand All @@ -232,6 +177,9 @@ The work has been partially performed in the scope of the A-IQ Ready project, wh

The A-IQ Ready project is supported by the Chips Joint Undertaking (Chips JU) - the Public-Private Partnership for research, development, and innovation under Horizon Europe – and National Authorities under Grant Agreement No. 101096658.

<!--
# TODO: Fix these broken image links
-->
![image](https://github.com/IObundle/iob-system/assets/5718971/78f2a3ee-d10b-4989-b221-71154fe6e409) ![image](https://github.com/IObundle/iob-system/assets/5718971/d57e0430-bb60-42e3-82a3-c5b6b0417322)


Expand Down
10 changes: 5 additions & 5 deletions default.nix
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
let
py2hwsw_commit = "0911c61b8d56eb8b2ec7649f4dd7e60dae118617"; # Replace with the desired commit.
py2hwsw_sha256 = "+dyVBeO76c4v95T8cOnaWnYDiD0/2wb0UJRcColJi6A="; # Replace with the actual SHA256 hash.
# Get local py2hwsw path from `PY2HWSW_PATH` env variable
py2hwswPath = builtins.getEnv "PY2HWSW_PATH";
# Get local py2hwsw root from `PY2HWSW_ROOT` env variable
py2hwswRoot = builtins.getEnv "PY2HWSW_ROOT";

# For debug
disable_py2_build = 0;
Expand All @@ -19,8 +19,8 @@ let
pname = "py2hwsw";
version = py2hwsw_commit;
src =
if py2hwswPath != "" then
pkgs.lib.cleanSource py2hwswPath
if py2hwswRoot != "" then
pkgs.lib.cleanSource py2hwswRoot
else
(pkgs.fetchFromGitHub {
owner = "IObundle";
Expand All @@ -45,4 +45,4 @@ in
if disable_py2_build == 0 then
import "${py2hwsw}/lib/python${builtins.substring 0 4 pkgs.python3.version}/site-packages/py2hwsw/lib/default.nix" { inherit pkgs; py2hwsw_pkg = py2hwsw; }
else
import "${py2hwswPath}/py2hwsw/lib/default.nix" { inherit pkgs; py2hwsw_pkg = py2hwsw; }
import "${py2hwswRoot}/py2hwsw/lib/default.nix" { inherit pkgs; py2hwsw_pkg = py2hwsw; }
13 changes: 11 additions & 2 deletions iob_soc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,32 @@ def setup(py_params_dict):
core_dict = {
"version": "0.1",
"parent": {
# IOb-SoC is a child core of iob_system: https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/lib/hardware/iob_system
# IOb-SoC will inherit all attributes/files from the iob_system core.
"core_name": "iob_system",
# Every parameter in the lines below will be passed to the iob_system parent core.
**py_params_dict,
"system_attributes": {
# Every attribute in this dictionary will override/append to the ones of the iob_system parent core.
"board_list": ["aes_ku040_db_g", "cyclonev_gt_dk", "zybo_z7"],
"ports": [
{
# Add new rs232 port for uart
"name": "rs232_m",
"descr": "iob-system uart interface",
"signals": {
"type": "rs232",
},
},
# NOTE: Add other ports here.
],
"blocks": [
{
# Instantiate a UART core from: https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/lib/hardware/iob_uart
"core_name": "iob_uart",
"instance_name": "UART0",
"instance_description": "UART peripheral",
"peripheral_addr_w": 3,
"peripheral_addr_w": 3, # Width of cbus of this peripheral
"parameters": {},
"connect": {
"clk_en_rst_s": "clk_en_rst_s",
Expand All @@ -35,16 +42,18 @@ def setup(py_params_dict):
},
},
{
# Instantiate a TIMER core from: https://github.com/IObundle/py2hwsw/tree/main/py2hwsw/lib/hardware/iob_timer
"core_name": "iob_timer",
"instance_name": "TIMER0",
"instance_description": "Timer peripheral",
"peripheral_addr_w": 4,
"peripheral_addr_w": 4, # Width of cbus of this peripheral
"parameters": {},
"connect": {
"clk_en_rst_s": "clk_en_rst_s",
# Cbus connected automatically
},
},
# NOTE: Add other components/peripherals here.
],
},
},
Expand Down

0 comments on commit 1a2c362

Please sign in to comment.