Update README; Rename PY2HWSW_PATH to PY2HWSW_ROOT.

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 [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.
@@ -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
@@ -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
 ```
@@ -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]
@@ -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
 
@@ -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.
 
+<!--
+# 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)
 
 

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; }

iob_soc.py

@@ -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",
@@ -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.
                 ],
             },
         },