Refactor examples for handling many boards

The current way examples are done in the repository and shipped in the SDK does not make sense when you have many boards in my opinion so this restructure moves examples that are not specific to any particular platform (e.g hello world) to be generic to every platform supported by Microkit. Signed-off-by: Ivan-Velickovic <[email protected]>
seL4 · Dec 23, 2024 · aa0af13 · aa0af13
1 parent 9bc4568
commit aa0af13
Show file tree

Hide file tree

Showing 57 changed files with 189 additions and 805 deletions.
diff --git a/README.md b/README.md
@@ -189,6 +189,8 @@ LICENSE.md
 LICENSES/$licence.txt
 doc/
 doc/microkit_user_manual.pdf
+example/
+example/$example/
 bin/
 bin/microkit
 board/

diff --git a/build_sdk.py b/build_sdk.py
@@ -73,7 +73,6 @@ class BoardInfo:
     gcc_cpu: Optional[str]
     loader_link_address: int
     kernel_options: KERNEL_OPTIONS
-    examples: Dict[str, Path]
 
 
 @dataclass
@@ -96,9 +95,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "ethernet": Path("example/tqma8xqp1gb/ethernet")
-        }
     ),
     BoardInfo(
         name="zcu102",
@@ -113,9 +109,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/zcu102/hello")
-        }
     ),
     BoardInfo(
         name="maaxboard",
@@ -129,9 +122,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/maaxboard/hello")
-        }
     ),
     BoardInfo(
         name="imx8mm_evk",
@@ -145,9 +135,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "passive_server": Path("example/imx8mm_evk/passive_server")
-        }
     ),
     BoardInfo(
         name="imx8mp_evk",
@@ -161,9 +148,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/imx8mp_evk/hello")
-        }
     ),
     BoardInfo(
         name="imx8mq_evk",
@@ -177,9 +161,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/imx8mq_evk/hello")
-        }
     ),
     BoardInfo(
         name="odroidc2",
@@ -193,9 +174,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/odroidc2/hello")
-        }
     ),
     BoardInfo(
         name="odroidc4",
@@ -209,9 +187,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "timer": Path("example/odroidc4/timer")
-        }
     ),
     BoardInfo(
         name="qemu_virt_aarch64",
@@ -228,10 +203,6 @@ class ConfigInfo:
             "KernelArmExportPTMRUser": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/qemu_virt_aarch64/hello"),
-            "hierarchy": Path("example/qemu_virt_aarch64/hierarchy")
-        }
     ),
     BoardInfo(
         name="qemu_virt_riscv64",
@@ -245,9 +216,6 @@ class ConfigInfo:
             "KernelRiscvExtD": True,
             "KernelRiscvExtF": True,
         },
-        examples={
-            "hello": Path("example/qemu_virt_riscv64/hello"),
-        }
     ),
     BoardInfo(
         name="rockpro64",
@@ -261,9 +229,6 @@ class ConfigInfo:
             "KernelArmHypervisorSupport": True,
             "KernelArmVtimerUpdateVOffset": False,
         },
-        examples={
-            "hello": Path("example/rockpro64/hello")
-        }
     ),
     BoardInfo(
         name="star64",
@@ -276,9 +241,6 @@ class ConfigInfo:
             "KernelRiscvExtD": True,
             "KernelRiscvExtF": True,
         },
-        examples={
-            "hello": Path("example/star64/hello")
-        }
     ),
 )
 
@@ -310,6 +272,15 @@ class ConfigInfo:
 )
 
 
+EXAMPLES={
+    "hello": Path("example/hello"),
+    "ethernet": Path("example/ethernet"),
+    "passive_server": Path("example/passive_server"),
+    "hierarchy": Path("example/hierarchy"),
+    "timer": Path("example/timer"),
+}
+
+
 def tar_filter(tarinfo: TarInfo) -> TarInfo:
     """This is used to change the tarinfo when created the .tar.gz archive.
 
@@ -681,19 +652,20 @@ def main() -> None:
             build_elf_component("loader", root_dir, build_dir, board, config, loader_defines)
             build_elf_component("monitor", root_dir, build_dir, board, config, [])
             build_lib_component("libmicrokit", root_dir, build_dir, board, config)
-        # Setup the examples
-        for example, example_path in board.examples.items():
-            include_dir = root_dir / "board" / board.name / "example" / example
-            source_dir = example_path
-            for p in source_dir.rglob("*"):
-                if not p.is_file():
-                    continue
-                rel = p.relative_to(source_dir)
-                dest = include_dir / rel
-                dest.parent.mkdir(exist_ok=True, parents=True)
-                dest.unlink(missing_ok=True)
-                copy(p, dest)
-                dest.chmod(0o744)
+
+    # Setup the examples
+    for example, example_path in EXAMPLES.items():
+        include_dir = root_dir / "example" / example
+        source_dir = example_path
+        for p in source_dir.rglob("*"):
+            if not p.is_file():
+                continue
+            rel = p.relative_to(source_dir)
+            dest = include_dir / rel
+            dest.parent.mkdir(exist_ok=True, parents=True)
+            dest.unlink(missing_ok=True)
+            copy(p, dest)
+            dest.chmod(0o744)
 
     if not args.skip_tar:
         # At this point we create a tar.gz file

diff --git a/dev_build.py b/dev_build.py
@@ -90,9 +90,9 @@ def main():
 
     # Choose the makefile based on the `--example-from-sdk` command line flag
     makefile_directory = (
-        f"{release}/board/{args.board}/example/{args.example}"
+        f"{release}/example/{args.example}"
         if args.example_from_sdk
-        else f"{CWD.absolute()}/example/{args.board}/{args.example}"
+        else f"{CWD.absolute()}/example/{args.example}"
     )
 
     cmd = ["make", "-C", makefile_directory]

diff --git a/docs/manual.md b/docs/manual.md
@@ -331,7 +331,7 @@ Additionally, for each supported board configuration the following are provided:
 * `kernel.elf`
 * `monitor.elf`
 
-For some boards there are also examples provided in the `examples` directory.
+There are also examples provided in the `example` directory.
 
 The Microkit SDK does **not** provide, nor require, any specific build system.
 The user is free to build their system using whatever build system is deemed most appropriate for their specific use case.

diff --git a/example/tqma8xqp1gb/ethernet/Makefile → example/ethernet/Makefile b/example/tqma8xqp1gb/ethernet/Makefile → example/ethernet/Makefile
@@ -19,6 +19,10 @@ ifeq ($(strip $(MICROKIT_CONFIG)),)
 $(error MICROKIT_CONFIG must be specified)
 endif
 
+ifneq ($(MICROKIT_BOARD),tqma8xqp1gb)
+$(error Unsupported MICROKIT_BOARD given, only tqma8xqp1gb supported)
+endif
+
 TOOLCHAIN := aarch64-none-elf
 
 CPU := cortex-a35

diff --git a/example/ethernet/README.md b/example/ethernet/README.md
@@ -0,0 +1,19 @@
+<!--
+     Copyright 2021, Breakaway Consulting Pty. Ltd.
+     SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Example - Ethernet
+
+This example shows an ethernet system for the TQMa8XQP platform.
+It also includes a driver for the general purpose timer on the platform.
+
+## Building
+
+```sh
+mkdir build
+make BUILD_DIR=build MICROKIT_BOARD=tqma8xqp1gb MICROKIT_CONFIG=<debug/release/benchmark> MICROKIT_SDK=/path/to/sdk
+```
+
+## Running
+
+See instructions for your board in the manual.
diff --git a/example/tqma8xqp1gb/ethernet/eth.c → example/ethernet/eth.c b/example/tqma8xqp1gb/ethernet/eth.c → example/ethernet/eth.c
diff --git a/example/tqma8xqp1gb/ethernet/ethernet.system → example/ethernet/ethernet.system b/example/tqma8xqp1gb/ethernet/ethernet.system → example/ethernet/ethernet.system
diff --git a/example/tqma8xqp1gb/ethernet/foo.c → example/ethernet/foo.c b/example/tqma8xqp1gb/ethernet/foo.c → example/ethernet/foo.c
diff --git a/example/tqma8xqp1gb/ethernet/gpt.c → example/ethernet/gpt.c b/example/tqma8xqp1gb/ethernet/gpt.c → example/ethernet/gpt.c
diff --git a/example/tqma8xqp1gb/ethernet/pass.c → example/ethernet/pass.c b/example/tqma8xqp1gb/ethernet/pass.c → example/ethernet/pass.c
diff --git a/example/qemu_virt_riscv64/hello/Makefile → example/hello/Makefile b/example/qemu_virt_riscv64/hello/Makefile → example/hello/Makefile
@@ -19,7 +19,20 @@ ifeq ($(strip $(MICROKIT_CONFIG)),)
 $(error MICROKIT_CONFIG must be specified)
 endif
 
-TOOLCHAIN := riscv64-unknown-elf
+BOARD_DIR := $(MICROKIT_SDK)/board/$(MICROKIT_BOARD)/$(MICROKIT_CONFIG)
+
+ARCH := ${shell grep 'CONFIG_SEL4_ARCH  ' $(BOARD_DIR)/include/kernel/gen_config.h | cut -d' ' -f4}
+
+ifeq ($(ARCH),aarch64)
+	TOOLCHAIN := aarch64-none-elf
+	# No specific AArch64 flags
+	CFLAGS_ARCH :=
+else ifeq ($(ARCH),riscv64)
+	TOOLCHAIN := riscv64-unknown-elf
+	CFLAGS_ARCH := -march=rv64imafdc_zicsr_zifencei -mabi=lp64d
+else
+$(error Unsupported ARCH)
+endif
 
 CC := $(TOOLCHAIN)-gcc
 LD := $(TOOLCHAIN)-ld
@@ -28,10 +41,8 @@ MICROKIT_TOOL ?= $(MICROKIT_SDK)/bin/microkit
 
 HELLO_OBJS := hello.o
 
-BOARD_DIR := $(MICROKIT_SDK)/board/$(MICROKIT_BOARD)/$(MICROKIT_CONFIG)
-
 IMAGES := hello.elf
-CFLAGS := -mstrict-align -nostdlib -ffreestanding -g -O3 -Wall  -Wno-unused-function -Werror -I$(BOARD_DIR)/include -march=rv64imafdc_zicsr_zifencei -mabi=lp64d
+CFLAGS := -mstrict-align -nostdlib -ffreestanding -g -O3 -Wall  -Wno-unused-function -Werror -I$(BOARD_DIR)/include $(CFLAGS_ARCH)
 LDFLAGS := -L$(BOARD_DIR)/lib
 LIBS := -lmicrokit -Tmicrokit.ld
 

diff --git a/example/hello/README.md b/example/hello/README.md
@@ -0,0 +1,21 @@
+<!--
+     Copyright 2024, UNSW
+     SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Example - Hello World
+
+This is a basic hello world example that has a single protection domain
+that simply prints "hello, world!" upon initialisation.
+
+All supported platforms are supported in this example.
+
+## Building
+
+```sh
+mkdir build
+make BUILD_DIR=build MICROKIT_BOARD=<board> MICROKIT_CONFIG=<debug/release/benchmark> MICROKIT_SDK=/path/to/sdk
+```
+
+## Running
+
+See instructions for your board in the manual.
diff --git a/example/imx8mp_evk/hello/hello.c → example/hello/hello.c b/example/imx8mp_evk/hello/hello.c → example/hello/hello.c
diff --git a/example/imx8mp_evk/hello/hello.system → example/hello/hello.system b/example/imx8mp_evk/hello/hello.system → example/hello/hello.system
diff --git a/example/qemu_virt_aarch64/hierarchy/Makefile → example/hierarchy/Makefile b/example/qemu_virt_aarch64/hierarchy/Makefile → example/hierarchy/Makefile
@@ -19,9 +19,20 @@ ifeq ($(strip $(MICROKIT_CONFIG)),)
 $(error MICROKIT_CONFIG must be specified)
 endif
 
-TOOLCHAIN := aarch64-none-elf
+BOARD_DIR := $(MICROKIT_SDK)/board/$(MICROKIT_BOARD)/$(MICROKIT_CONFIG)
 
-CPU := cortex-a53
+ARCH := ${shell grep 'CONFIG_SEL4_ARCH  ' $(BOARD_DIR)/include/kernel/gen_config.h | cut -d' ' -f4}
+
+ifeq ($(ARCH),aarch64)
+	TOOLCHAIN := aarch64-none-elf
+	# No specific AArch64 flags
+	CFLAGS_ARCH :=
+else ifeq ($(ARCH),riscv64)
+	TOOLCHAIN := riscv64-unknown-elf
+	CFLAGS_ARCH := -march=rv64imafdc_zicsr_zifencei -mabi=lp64d
+else
+$(error Unsupported ARCH)
+endif
 
 CC := $(TOOLCHAIN)-gcc
 LD := $(TOOLCHAIN)-ld
@@ -32,10 +43,8 @@ RESTARTER_OBJS := restarter.o
 CRASHER_OBJS := crasher.o
 HELLO_OBJS := hello.o
 
-BOARD_DIR := $(MICROKIT_SDK)/board/$(MICROKIT_BOARD)/$(MICROKIT_CONFIG)
-
 IMAGES := restarter.elf crasher.elf hello.elf
-CFLAGS := -mcpu=$(CPU) -mstrict-align -nostdlib -ffreestanding -g -O3 -Wall  -Wno-unused-function -Werror -I$(BOARD_DIR)/include
+CFLAGS := -mstrict-align -nostdlib -ffreestanding -g -O3 -Wall  -Wno-unused-function -Werror -I$(BOARD_DIR)/include $(CFLAGS_ARCH)
 LDFLAGS := -L$(BOARD_DIR)/lib
 LIBS := -lmicrokit -Tmicrokit.ld
 

diff --git a/example/hierarchy/README.md b/example/hierarchy/README.md
@@ -0,0 +1,23 @@
+<!--
+     Copyright 2024, UNSW
+     SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Example - Hierarchy
+
+This example shows off the parent/child PD concept in Microkit as
+well as fault handling. The parent 'restarter' PD recieves faults
+from the 'crasher' PD that is intentionally crashing and then
+resets the crasher's program counter.
+
+All supported platforms are supported in this example.
+
+## Building
+
+```sh
+mkdir build
+make BUILD_DIR=build MICROKIT_BOARD=<board> MICROKIT_CONFIG=<debug/release/benchmark> MICROKIT_SDK=/path/to/sdk
+```
+
+## Running
+
+See instructions for your board in the manual.
diff --git a/...ple/qemu_virt_aarch64/hierarchy/crasher.c → example/hierarchy/crasher.c b/...ple/qemu_virt_aarch64/hierarchy/crasher.c → example/hierarchy/crasher.c
diff --git a/example/imx8mp_evk/imx8mq_evk/hello/hello.c → example/hierarchy/hello.c b/example/imx8mp_evk/imx8mq_evk/hello/hello.c → example/hierarchy/hello.c
diff --git a/...mu_virt_aarch64/hierarchy/hierachy.system → example/hierarchy/hierachy.system b/...mu_virt_aarch64/hierarchy/hierachy.system → example/hierarchy/hierachy.system
diff --git a/...e/qemu_virt_aarch64/hierarchy/restarter.c → example/hierarchy/restarter.c b/...e/qemu_virt_aarch64/hierarchy/restarter.c → example/hierarchy/restarter.c