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 <i.velickovic@unsw.edu.au>

Author: Ivan-Velickovic

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/Makefileexample/tqma8xqp1gb/ethernet/Makefile renamed to 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,15 @@
+# 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.