feat(test-framework): Add a test-framework to bao

.gitmodules

@@ -1,3 +1,9 @@
 [submodule "ci"]
 	path = ci
 	url = [email protected]:bao-project/bao-ci.git
+[submodule "tests/bao-tests"]
+	path = tests/bao-tests
+	url = https://github.com/bao-project/bao-tests.git
+[submodule "tests/bao-nix"]
+	path = tests/bao-nix
+	url = https://github.com/bao-project/bao-nix.git

Makefile

@@ -75,7 +75,7 @@ targets:=$(MAKECMDGOALS)
 ifeq ($(targets),)
 targets:=all
 endif
-non_build_targets+=ci clean
+non_build_targets+=ci clean tests
 build_targets:=$(strip $(foreach target, $(targets), \
 	$(if $(findstring $(target),$(non_build_targets)),,$(target))))
 
@@ -391,4 +391,10 @@ $(call ci, format, $(all_c_files))
 .PHONY: ci
 ci: license-check format-check
 
-endif
+tests_dir := $(cur_dir)/tests
+-include $(tests_dir)/tests.mk
+
+.PHONY: tests
+tests: framework 
+
+endif

README.md

@@ -141,3 +141,72 @@ In IEEE Access, 2024. https://ieeexplore.ieee.org/document/10781314
 
 10. Hidemasa Kawasaki and Soramichi Akiyama. "**Running Bao Hypervisor on gem5**"
 In gem5 blog, 2024. https://www.gem5.org/2024/11/12/bao-on-gem5.html
+
+
+Testing Framework Usage
+-----------------------
+
+### Prerequisites
+- Ensure [Nix package manager](https://nixos.org/download.html) is installed.
+- After cloning the Bao repository, initialize and update the submodules (bao-nix and bao-tests):
+
+```
+
+git submodule update --init --recursive
+
+```
+
+- Install QEMU for your target platform via Nix (first-time runs may take time):
+
+  For **qemu-aarch64-virt**:
+```
+
+nix-shell -p 'with import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/0c924ec948073580a3c3d438746388d05a38028b.zip") {}; qemu' --run "true"
+
+```
+
+For **qemu-riscv64-virt**:
+```
+
+nix-shell -p 'with import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/0c924ec948073580a3c3d438746388d05a38028b.zip") {}; qemu_full' --run "true"
+
+```
+
+### Running Tests
+To run tests, invoke the framework using the Makefile target:
+
+```
+
+make tests PLATFORM=<platform> RECIPE=<recipe>
+
+```
+
+Example:
+
+```
+
+make tests PLATFORM=qemu-aarch64-virt RECIPE=single-baremetal/default.nix
+
+```
+
+This will run tests on the specified platform with the given recipe.
+
+### Supported Platforms and Test Setups
+The following table summarizes the supported platforms and test setups for the Bao testing framework. It shows which setups support boot tests and which have IRQ tests implemented (e.g., UART and timer interrupts):
+
+| Platform           | Setup            | Boot Tests | IRQ Tests       |
+|:------------------:|:----------------:|:----------:|:---------------:|
+| qemu-aarch64-virt  | single-baremetal | Yes        | UART, Timer     |
+| qemu-aarch64-virt  | single-freertos  | Yes        | UART, Timer     |
+| qemu-aarch64-virt  | single-linux     | Yes        | No              |
+| qemu-riscv64-virt  | single-baremetal | Yes        | UART, Timer     |
+| qemu-riscv64-virt  | single-freertos  | Yes        | UART, Timer     |
+| qemu-riscv64-virt  | single-linux     | Yes        | No              |
+
+Example enabling GICv3:
+
+```
+
+make tests PLATFORM=qemu-aarch64-virt RECIPE=single-baremetal/default.nix IRQC=gicv3
+
+```

tests/README.md

@@ -0,0 +1,135 @@
+# Bao Test Framework
+
+## Overview
+
+The primary goal of the Bao Test Framework is to provide the infrastructure for the testing process of Bao Project components. It encompasses three core components: (i) a C library designed for real-time test handling, (ii) a Python tool for comprehensive test management, and (iii) a build system based on Nix.
+The C library and Python tool are provided in the `bao-tests` repository while the Nix packages required are available in the `bao-nix` repository. Lastly, a folder `recipes` contains all the recipes and tests.
+
+
+
+## How to use
+
+**1. Create a folder inside `recipes` with the following structure**
+
+```
+ tests
+ ├── bao-tests     
+ ├── bao-nix   
+ ├── recipes  
+ │   ├── RECIPE-EXAMPLE   
+ │   │   ├── configs 
+ │   │   ├── src  
+```
+
+The name `RECIPE-EXAMPLE` will be used as an argument when using `make`. 
+The folder `configs` is used to store all the bao configs (link to docs) related to the recipe in question.
+Lastly, the folder `src` is used for test sources.
+
+**2. Create a `.nix` file in the `RECIPE-EXAMPLE` folder.**
+
+The following code is an example of a Nix recipe to build the system with a single baremetal guest.
+
+```nix
+{
+  pkgs ? import (fetchTarball {
+    url = "https://github.com/NixOS/nixpkgs/archive/refs/tags/22.11.tar.gz";
+    sha256 = "sha256:11w3wn2yjhaa5pv20gbfbirvjq6i3m7pqrq2msf0g7cv44vijwgw";
+  }) {},
+  platform ? " ",
+  bao_cfg_repo ? " ",
+  bao_cfg ? " ",
+  list_tests ? " ",
+  list_suites ? " ",
+  log_level ? " ",
+  GIC_VERSION ? " ",
+  IRQC ? " ",
+  IPIC ? " ",
+}:
+
+with pkgs;
+
+let
+  packages = rec {
+
+    setup-cfg  = callPackage ../../bao-nix/pkgs/setup-cfg/setup-cfg.nix{
+      inherit platform;
+      inherit GIC_VERSION;
+      inherit IRQC;
+      inherit IPIC;
+      bao-tests = ../../bao-tests;
+      tests_srcs = ./src;
+      baremetal_patch = ./baremetal.patch;
+    };
+
+    #Build toolchain
+    toolchain = callPackage ../../bao-nix/pkgs/toolchains/${setup-cfg.toolchain_name}.nix{};
+
+    #Build guests
+    guests = [
+          (callPackage (../../bao-nix/pkgs/guest/tf/baremetal.nix)
+                  { 
+                    inherit setup-cfg;
+                    inherit toolchain;
+                    guest_name = "baremetal";
+                    list_tests = "";
+                    list_suites = "CPU_BOOT_CHECK";
+                    inherit log_level;                     
+                  }
+          )
+      ];
+
+    bao_cfg_repo = ./configs;
+
+    #Build Hypervisor
+    bao = callPackage ../../bao-nix/pkgs/bao/bao.nix 
+    { 
+      inherit setup-cfg;
+      inherit toolchain;
+      inherit bao_cfg_repo;
+      inherit bao_cfg;
+      inherit guests; 
+      #bao_srcs_path = /home/mafs/bao-hypervisor;
+    };
+
+    # Build Firmware
+    firmware = callPackage ../../bao-nix/pkgs/firmware/${platform}.nix {
+      inherit toolchain;
+      inherit platform;
+      inherit setup-cfg;
+    };
+    inherit pkgs;
+  };
+in
+  packages
+
+```
+
+The main fields in the recipe that should be modified for other uses are:
+
+* **guests** - This array should include all the the guest used in the bao configuration. 
+* **list_tests** - For each guest that will execute tests, this field should be filled with test names.
+* **list_suits** - Similar to the previous field, but should be filled with suites (groups of tests) instead.
+
+**3. Implement the tests**
+
+Create a `.c` file in the `src` folder and implement the tests following the example below: 
+
+```c
+#include "testf.h"
+
+BAO_TEST(SUITE_NAME, TEST_NAME)
+{
+    printf("Hello World!!!\n");
+}
+```
+
+Every source file that implements tests should include the `testf.h` header.
+A test is defined using the macro `BAO_TEST` with `SUITE_NAME` and `TEST_NAME` as arguments to identify the test in the previous step.
+
+**4. Run the framework**
+
+From the **bao-hypervisor** main directory, to run the test framework you should use the following command:
+
+```
+make tests PLATFORM=platform RECIPE=RECIPE_EXAMPLE
+```

tests/recipes/single-baremetal/baremetal.patch

@@ -0,0 +1,32 @@
+diff --git a/setup.mk b/setup.mk
+index 3a230aa..2edf9ee 100644
+--- a/setup.mk
++++ b/setup.mk
+@@ -29,6 +29,14 @@ src_dirs+=$(src_dir) $(core_dir) $(platform_dir)
+ SRC_DIRS+=$(src_dirs)
+ INC_DIRS+=$(addsuffix /inc, $(src_dirs))
+
++# Test framework setup
++include $(TESTF_REPO_DIR)/src/bao-test.mk
++SRC_DIRS+=$(TESTF_SRC_DIR) $(TESTF_TESTS_DIR)
++C_SRC+=$(TESTF_SRCS)
++INC_DIRS+=$(TESTF_INC_DIR)
++CFLAGS+=$(TESTF_FLAGS)
++# End of test framework setup
++
+ ifeq ($(wildcard $(platform_dir)),)
+ $(error unsupported platform $(PLATFORM))
+ endif
+diff --git a/src/main.c b/src/main.c
+index 9a9e972..69cfa6f 100644
+--- a/src/main.c
++++ b/src/main.c
+@@ -54,6 +54,8 @@ void main(void){
+         printf("Bao bare-metal test guest\n");
+         spin_unlock(&print_lock);
+
++        testf_entry();
++        
+         irq_set_handler(UART_IRQ_ID, uart_rx_handler);
+         irq_set_handler(TIMER_IRQ_ID, timer_handler);
+         irq_set_handler(IPI_IRQ_ID, ipi_handler);

tests/recipes/single-baremetal/configs/qemu-aarch64-virt.c

@@ -0,0 +1,58 @@
+#include <config.h>
+
+VM_IMAGE(baremetal_image, XSTR(BAO_WRKDIR_IMGS/baremetal.bin))
+
+struct config config = {
+
+    CONFIG_HEADER
+
+    .vmlist_size = 1,
+    .vmlist = (struct vm_config[]) {
+        { 
+            .image = {
+                .base_addr = 0x50000000,
+                .load_addr = VM_IMAGE_OFFSET(baremetal_image),
+                .size = VM_IMAGE_SIZE(baremetal_image)
+            },
+
+            .entry = 0x50000000,
+
+            .platform = {
+                .cpu_num = 4,
+
+                .region_num = 1,
+                .regions =  (struct vm_mem_region[]) {
+                    {
+                        .base = 0x50000000,
+                        .size = 0x4000000 
+                    }
+                },
+
+                .dev_num = 2,
+                .devs =  (struct vm_dev_region[]) {
+                    {   
+                        /* PL011 */
+                        .pa = 0x9000000,
+                        .va = 0x9000000,
+                        .size = 0x10000,
+                        .interrupt_num = 1,
+                        .interrupts = (irqid_t[]) {33}                        
+                    },
+                    {   
+                        /* Arch timer interrupt */
+                        .interrupt_num = 1,
+                        .interrupts = 
+                            (irqid_t[]) {27}                         
+                    }
+                },
+
+                .arch = {
+                    .gic = {
+                        .gicd_addr = (paddr_t) 0x08000000,
+                        .gicr_addr = (paddr_t) 0x080A0000,
+                    }
+                }
+            },
+        }
+    },
+};

tests/recipes/single-baremetal/configs/qemu-riscv64-virt.c

@@ -0,0 +1,52 @@
+#include <config.h>
+
+VM_IMAGE(baremetal_image, XSTR(BAO_WRKDIR_IMGS/baremetal.bin))
+
+struct config config  = {
+
+    CONFIG_HEADER
+
+    .vmlist_size = 1,
+    .vmlist = (struct vm_config[]) {
+        { 
+            .image = {
+                .base_addr = 0x80200000,
+                .load_addr = VM_IMAGE_OFFSET(baremetal_image),
+                .size = VM_IMAGE_SIZE(baremetal_image)
+            },
+
+            .entry = 0x80200000,
+
+            .platform = {
+                .cpu_num = 4,
+
+                .region_num = 1,
+                .regions =  (struct vm_mem_region[]) {
+                    {
+                        .base = 0x80200000,
+                        .size = 0x4000000
+                    }
+                },
+
+                .dev_num = 1,
+                .devs =  (struct vm_dev_region[]) {
+                    {
+                        .pa = 0x10000000,   
+                        .va = 0x10000000,  
+                        .size = 0x1000, 
+                        .interrupt_num = 1,
+                        .interrupts = (irqid_t[]) {10}
+                    },
+                },
+
+                .arch = {
+                   .irqc = {
+                        .plic = {
+                            .base = 0xc000000,
+                        },
+                   },
+                },
+            },
+        },
+     }
+};