Refactor examples for handling many boards

README.md

@@ -189,6 +189,8 @@ LICENSE.md
 LICENSES/$licence.txt
 doc/
 doc/microkit_user_manual.pdf
+example/
+example/$example/
 bin/
 bin/microkit
 board/

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

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]

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.

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

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.

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
 

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.

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
 

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.