From 516d223ed8045ac9e0007999edab5b3bf1336c24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artur=20N=C3=B3brega?= Date: Wed, 13 Nov 2024 22:39:18 +0000 Subject: [PATCH 1/3] refactor(default.nix): Rename `PY2HWSW_PATH` to `PY2HWSW_ROOT` --- default.nix | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/default.nix b/default.nix index 2ae04f586..124bb4f81 100644 --- a/default.nix +++ b/default.nix @@ -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; @@ -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"; @@ -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; } From 769bc029e3ae7bed72e14f51ffead5531b7a38b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artur=20N=C3=B3brega?= Date: Thu, 14 Nov 2024 00:40:27 +0000 Subject: [PATCH 2/3] docs(iob_soc): Add comments to iob_soc.py --- iob_soc.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/iob_soc.py b/iob_soc.py index 0636c42d8..9817d01c0 100644 --- a/iob_soc.py +++ b/iob_soc.py @@ -8,12 +8,17 @@ 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": { @@ -23,6 +28,7 @@ def setup(py_params_dict): ], "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", @@ -35,6 +41,7 @@ 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", From eda18f3ca3eca880a92cf322c0f7d620f0cf057d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Artur=20N=C3=B3brega?= Date: Thu, 14 Nov 2024 14:28:08 +0000 Subject: [PATCH 3/3] docs(README.md): Update README. --- README.md | 112 ++++++++++++++--------------------------------------- iob_soc.py | 6 ++- 2 files changed, 34 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 510776f24..1d320883e 100644 --- a/README.md +++ b/README.md @@ -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 LM_LICENSE_FILE=port@licenseserver.myorg.com;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. @@ -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 ``` - + 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 @@ -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/.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/.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 ``` @@ -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//`](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//`](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=] [INIT_MEM=0|1] [USE_EXTMEM=0|1] @@ -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 -``` - + ## Compile the documentation @@ -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 @@ -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. + ![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) diff --git a/iob_soc.py b/iob_soc.py index 9817d01c0..a85ebc892 100644 --- a/iob_soc.py +++ b/iob_soc.py @@ -25,6 +25,7 @@ def setup(py_params_dict): "type": "rs232", }, }, + # NOTE: Add other ports here. ], "blocks": [ { @@ -32,7 +33,7 @@ def setup(py_params_dict): "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", @@ -45,13 +46,14 @@ def setup(py_params_dict): "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. ], }, },