Merge pull request #98 from P-Miranda/merge-eth-verilator

Merge latest eth-verilator with SPI linux driver tutorial

.github/workflows/ci.yml

@@ -66,22 +66,22 @@ jobs:
       - name: icarus test
         run: nix-shell --run "make -C ../iob_soc_o* sim-run"
 
-  # verilator-baremetal:
-  #   runs-on: self-hosted
-  #   timeout-minutes: 90
-  #   # run even if previous job failed
-  #   if: ${{ !cancelled() }}
-  #
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #       with:
-  #         submodules: 'recursive'
-  #     - name: clean
-  #       run: nix-shell --run "make clean"
-  #     - name: setup no_init_mem ext_mem
-  #       run: nix-shell --run "make setup INIT_MEM=0 RUN_LINUX=0"
-  #     - name: verilator test
-  #       run: nix-shell --run "make -C ../iob_soc_o* sim-run SIMULATOR=verilator"
+  verilator-baremetal:
+    runs-on: self-hosted
+    timeout-minutes: 90
+    # run even if previous job failed
+    if: ${{ !cancelled() }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+      - name: clean
+        run: nix-shell --run "make clean"
+      - name: setup no_init_mem ext_mem
+        run: nix-shell --run "make setup INIT_MEM=0 RUN_LINUX=0"
+      - name: verilator test
+        run: nix-shell --run "make -C ../iob_soc_o* sim-run SIMULATOR=verilator"
 
 
   cyclonev:

README.md

@@ -314,6 +314,176 @@ export PATH=$PATH:/path/to/riscv/bin
 
 The above command should be added to your `~/.bashrc` file so you do not have to type it on every session.
 
+# Tutorial: Add New Device Driver
+This tutorial presents the steps required to create simple linux character device drivers for a device and use them in OpenCryptoLinux.
+The [IOb-SPI](https://github.com/IObundle/iob-spi) device is used as an example.
+To follow this tutorial, clone the [iob-linux](https://github.com/IObundle/iob-linux) repository.
+
+1. Create device drivers: on the device repository create a `software/linux` directory with the following files:
+```bash
+software/
+├── linux
+│   ├── drivers
+│   │   ├── driver.mk
+│   │   └── iob_spi_main.c
+│   ├── iob_spi.dts
+│   └── Readme.md
+```
+1.1. `software/linux/drivers/driver.mk`: compilation makefile segment
+```make
+iob_spi_master-objs := iob_spi_main.o iob_class/iob_class_utils.o
+```
+1.2. `software/linux/drivers/iob_spi_main.c`: main driver file, see [TODO: SPI commit] for full code snippet. 
+1.2.1. Rename the functions to the particular device
+1.2.2. Update the `iob_spi_read()` function implementation according with the read registers of the device. SPI has the `FL_READY`, `FL_DATAOUT`  and `VERSION` (implicit) read registers:
+```C
+static ssize_t iob_spi_read(struct file *file, char __user *buf, size_t count,
+                             loff_t *ppos) {
+  // (...)
+
+  /* read value from register */
+  switch (*ppos) {
+  // Add one case for each Read software register
+  case IOB_SPI_MASTER_FL_READY_ADDR:
+    value =
+        iob_data_read_reg(iob_spi_data->regbase, IOB_SPI_MASTER_FL_READY_ADDR,
+                          IOB_SPI_MASTER_FL_READY_W);
+    size = (IOB_SPI_MASTER_FL_READY_W >> 3); // bit to bytes
+    pr_info("[Driver] %s: Read FL_READY: 0x%x\n", IOB_SPI_MASTER_DRIVER_NAME,
+            value);
+    break;
+  case IOB_SPI_MASTER_FL_DATAOUT_ADDR:
+    value =
+        iob_data_read_reg(iob_spi_data->regbase, IOB_SPI_MASTER_FL_DATAOUT_ADDR,
+                          IOB_SPI_MASTER_FL_DATAOUT_W);
+    size = (IOB_SPI_MASTER_FL_DATAOUT_W >> 3); // bit to bytes
+    pr_info("[Driver] %s: Read FL_DATAOUT: 0x%x\n", IOB_SPI_MASTER_DRIVER_NAME,
+            value);
+    break;
+  // NOTE: version software register is implicit and always added
+  case IOB_SPI_MASTER_VERSION_ADDR:
+    value = iob_data_read_reg(iob_spi_data->regbase, IOB_SPI_MASTER_VERSION_ADDR,
+                              IOB_SPI_MASTER_VERSION_W);
+    size = (IOB_SPI_MASTER_VERSION_W >> 3); // bit to bytes
+    pr_info("[Driver] %s: Read version 0x%x\n", IOB_SPI_MASTER_DRIVER_NAME, value);
+    break;
+  default:
+    // invalid address - no bytes read
+    return 0;
+  }
+
+  // (...)
+}
+```
+1.2.3. Update the `iob_spi_write()` function implementation according with the write registers of the device. SPI had the `FL_RESET`, `FL_DATAIN`, `FL_ADDRESS`, `FL_COMMAND`, `FL_COMMANDTP` and `FL_VALIDFLG`write registers:
+```C
+static ssize_t iob_spi_write(struct file *file, const char __user *buf,
+                              size_t count, loff_t *ppos) {
+  // (...)
+
+  switch (*ppos) {
+  case IOB_SPI_MASTER_FL_RESET_ADDR:
+    size = (IOB_SPI_MASTER_FL_RESET_W >> 3); // bit to bytes
+    if (read_user_data(buf, size, &value))
+      return -EFAULT;
+    iob_data_write_reg(iob_spi_data->regbase, value,
+                       IOB_SPI_MASTER_FL_RESET_ADDR,
+                       IOB_SPI_MASTER_FL_RESET_W);
+    pr_info("[Driver] %s: FL_RESET iob_spi: 0x%x\n",
+            IOB_SPI_MASTER_DRIVER_NAME, value);
+    break;
+  case IOB_SPI_MASTER_FL_DATAIN_ADDR:
+    // FL_DATAIN access implementation
+    break;
+  case IOB_SPI_MASTER_FL_ADDRESS_ADDR:
+    // FL_ADDRESS access implementation
+    break;
+  case IOB_SPI_MASTER_FL_COMMAND_ADDR:
+    // FL_COMMAND access implementation
+    break;
+  case IOB_SPI_MASTER_FL_COMMANDTP_ADDR:
+    // FL_COMMANDTP access implementation
+    break;
+  case IOB_SPI_MASTER_FL_VALIDFLG_ADDR:
+    // FL_VALIDFLG access implementation
+    break;
+  default:
+      pr_info("[Driver] %s: Invalid write address 0x%x\n", IOB_SPI_MASTER_DRIVER_NAME,
+              (unsigned int)*ppos);
+      // invalid address - no bytes written
+      return 0;
+  }
+
+  return count;
+}
+```
+1.2.4. Notice the string used in the `struct of_device_id`. This string must match the `compatible` field in the device tree to associate the hardware device with the correct driver.
+```C
+static const struct of_device_id of_iob_spi_match[] = {
+    {.compatible = "iobundle,spi0"},
+    {},
+};
+```
+1.3. Generate `iob_spi_master.h` and `iob_spi_master_sysfs_multi.h` header files with the [`drivers.py`](https://github.com/IObundle/iob-linux/blob/main/scripts/drivers.py) script:
+```bash
+python3 .path/to/iob-linux/scripts/drivers.py iob_spi_master -o [output_dir]
+```
+2. Update device tree with device node. The `compatible` string must match with the `compatible` field in the driver source:
+```
+// SPDX-License-Identifier: (GPL-2.0 OR MIT)
+/* Copyright (c) 2024 IObundle */
+
+/dts-v1/;
+
+/ {
+    #address-cells = <1>;
+    #size-cells = <1>;
+    model = "IOb-SoC, VexRiscv";
+    compatible = "IOb-SoC, VexRiscv";
+    // CPU
+    // Memory
+    // Choosen
+    soc {
+        #address-cells = <1>;
+        #size-cells = <1>;
+        compatible = "iobundle,iob-soc", "simple-bus";
+        ranges;
+
+        // Other SOC peripherals go here
+
+        // Add this Node to device tree
+        SPI0: spi@/*SPI0_ADDR_MACRO*/ {
+            compatible = "iobundle,spi0";
+            reg = <0x/*SPI0_ADDR_MACRO*/ 0x100>;
+        };
+
+    };
+};
+```
+3. Compile driver module and add to rootfs.
+3.1. Copy device driver files to [`iob-linux/software/drivers`](https://github.com/IObundle/iob-linux/tree/main/software/drivers)
+3.2. Run `make all` target. Note that linux driver module compilation requires an already built linux kernel:
+```bash
+cd ./path/to/iob-linux/software/drivers
+make all
+```
+3.3. Add module files to buildroot:
+```bash
+# copy module files to directory used to build rootfs
+cp ./path/to/iob-linux/software/drivers $OS_SOFTWARE_DIR
+# change directory to iob-linux
+cd ./path/to/iob-linux
+# re-build buildroot
+make build-buildroot OS_SOFTWARE_DIR=$OS_SOFTWARE_DIR
+```
+4. Load module in linux. After booting into linux, use the `insmod` command to load the new driver modules:
+```bash
+# inside linux console
+insmod ./path/to/driver.ko
+# iob-spi example:
+insmod /drivers/iob_spi_master.ko
+```
+
 # Acknowledgement
 The [OpenCryptoLinux](https://nlnet.nl/project/OpenCryptoLinux/) project was funded through the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073.
 

hardware/simulation/sim_build.mk

@@ -10,6 +10,12 @@ VTOP:=iob_soc_opencryptolinux_tb
 # SOURCES
 ifeq ($(SIMULATOR),verilator)
 
+VSRC+=./src/iob_tasks.cpp
+
+ifeq ($(USE_ETHERNET),1)
+VSRC+=./src/iob_eth_swreg_emb_verilator.c ./src/iob_eth_driver_tb.cpp
+endif
+
 # verilator top module
 VTOP:=iob_soc_opencryptolinux_sim_wrapper