Merge pull request #67 from PedroAntunes178/master

README (update), IOBSOC (update), bootloader (very small update)

README.md

@@ -2,6 +2,36 @@
 
 IOb-SoC-OpenCryptoLinux is a System-on-Chip (SoC) template comprising an open-source RISC-V processor (VexRiscv), an internal boot memory subsystem, a UART, and an interface to external memory. The external memory interface is a 3rd party memory controller IP (typically a DDR controller) using an AXI4 master bus.
 
+## Getting Started (Quickly)
+
+This section offers a quick guide for users to start using IOb-SoC-OpenCryptoLinux. The following commands streamline the setup process for simulation and running on an FPGA board:
+
+```bash
+# Clone the repository
+git clone --recursive [email protected]:IObundle/iob-soc-opencryptolinux.git
+# Navigate to the project directory
+cd iob-soc-opencryptolinux
+# Simulate bare-metal firmware with IVerilog and Verilator
+make sim-test
+# Simulate the Linux OS with Verilator
+make sim-test-linux
+# Run Linux on the KU board by default
+make fpga-run
+# After running `fpga-run`, select either bare-metal firmware (with `RUN_LINUX` is 0) or the Linux OS (with `RUN_LINUX` is 1)
+make fpga-connect RUN_LINUX=0
+```
+
+These commands aim to expedite the setup process for both simulation and FPGA board execution. Adjust the values as needed for your specific use case.
+
+## Differences to [IOb-SoC](https://github.com/IObundle/iob-soc)
+This section outlines the distinctions between IOb-SoC and IOb-SoC-OpenCryptoLinux.
+
+Compared to IOb-SoC, IOb-SoC-OpenCryptoLinux features a distinct CPU and employs AXI in the internal signals, deviating from the IOb-bus used by IOb-SoC. Another significant difference is the placement of firmware, as the one in IOb-SoC-OpenCryptoLinux always resides in external memory.
+
+Additionally, the bootloader in IOb-SoC-OpenCryptoLinux differs from that in IOb-SoC. In IOb-SoC-OpenCryptoLinux, the bootloader is directly loaded into internal RAM, whereas in IOb-SoC, the bootloader binary starts in ROM and is then copied to RAM.
+
+The boot control unit in IOb-SoC-OpenCryptoLinux, unlike IOb-SoC, is a distinct module and exclusively manages the boot process state. On the software side, the IOb-SoC-OpenCryptoLinux bootloader initially loads a file named iob_mem.config, which specifies the files and their respective memory addresses to be copied into external memory.
+
 ## Nix environment
 
 You can use

iob_soc_opencryptolinux.py

@@ -113,9 +113,9 @@ def _post_setup(cls):
             if os.path.isfile(src_file):
                 shutil.copy2(src_file, dst)
 
-        # Copy NonCanonical script to scripts build directory
+        # Copy terminalMode script to scripts build directory
         dst = f"{cls.build_dir}/scripts"
-        src_file = f"{__class__.setup_dir}/submodules/IOBSOC/submodules/LIB/scripts/noncanonical.py"
+        src_file = f"{__class__.setup_dir}/submodules/IOBSOC/submodules/LIB/scripts/terminalMode.py"
         shutil.copy2(src_file, dst)
         src_file = f"{__class__.setup_dir}/scripts/check_if_run_linux.py"
         shutil.copy2(src_file, dst)

scripts/check_if_run_linux.py

@@ -8,9 +8,9 @@
 else:
     RUN_LINUX = "0"
 
-# Generate "iob_mem.txt" according to which binary firmware the SoC should load to RAM
+# Generate "iob_mem.config" according to which binary firmware the SoC should load to RAM
 
-iob_mem_file = f"{ROOT_DIR}/hardware/iob_mem.txt"
+iob_mem_file = f"{ROOT_DIR}/hardware/iob_mem.config"
 with open(iob_mem_file, "w") as file:
     if RUN_LINUX == "1":
         file.write(

software/src/iob_soc_opencryptolinux_boot.c

@@ -45,7 +45,7 @@ int main() {
   }
 
 #ifndef IOB_SOC_OPENCRYPTOLINUX_INIT_MEM
-  file_size = uart16550_recvfile("../iob_mem.txt", prog_start_addr);
+  file_size = uart16550_recvfile("../iob_mem.config", prog_start_addr);
   // compute_mem_load_txt
   int state = 0;
   int file_name_count = 0;