example: add setvar example

Signed-off-by: Bill Nguyen <bill.nguyen@student.unsw.edu.au>

Author: dreamliner787-9

example/setvar/Makefile

@@ -0,0 +1,58 @@
+#
+# Copyright 2025, UNSW.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+ifeq ($(strip $(BUILD_DIR)),)
+$(error BUILD_DIR must be specified)
+endif
+
+ifeq ($(strip $(MICROKIT_SDK)),)
+$(error MICROKIT_SDK must be specified)
+endif
+
+ifeq ($(strip $(MICROKIT_BOARD)),)
+$(error MICROKIT_BOARD must be specified)
+endif
+
+ifeq ($(strip $(MICROKIT_CONFIG)),)
+$(error MICROKIT_CONFIG must be specified)
+endif
+
+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
+$(error Unsupported ARCH)
+endif
+
+CC := $(TOOLCHAIN)-gcc
+LD := $(TOOLCHAIN)-ld
+AS := $(TOOLCHAIN)-as
+MICROKIT_TOOL ?= $(MICROKIT_SDK)/bin/microkit
+
+SETVAR_OBJS := setvar.o
+
+IMAGES := setvar.elf
+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
+
+IMAGE_FILE = $(BUILD_DIR)/loader.img
+REPORT_FILE = $(BUILD_DIR)/report.txt
+
+all: $(IMAGE_FILE)
+
+$(BUILD_DIR)/%.o: %.c Makefile
+	$(CC) -c $(CFLAGS) $< -o $@
+
+$(BUILD_DIR)/setvar.elf: $(addprefix $(BUILD_DIR)/, $(SETVAR_OBJS))
+	$(LD) $(LDFLAGS) $^ $(LIBS) -o $@
+
+$(IMAGE_FILE) $(REPORT_FILE): $(addprefix $(BUILD_DIR)/, $(IMAGES)) setvar.system
+	$(MICROKIT_TOOL) setvar.system --search-path $(BUILD_DIR) --board $(MICROKIT_BOARD) --config $(MICROKIT_CONFIG) -o $(IMAGE_FILE) -r $(REPORT_FILE)

example/setvar/README.md

@@ -0,0 +1,21 @@
+<!--
+     Copyright 2025, UNSW
+     SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Example - setvar
+
+This is a basic example that demonstrate how to use some `setvar` functionalities that the Microkit provides.
+
+Only QEMU virt (AArch64) is supported in this example. Though verything will work the same way on other
+platforms. But on x86, `setvar region_paddr` won't be supported.
+
+## Building
+
+```sh
+mkdir build
+make BUILD_DIR=build MICROKIT_BOARD=qemu_virt_aarch64 MICROKIT_CONFIG=debug MICROKIT_SDK=/path/to/sdk
+```
+
+## Running
+
+See instructions for your board in the manual.

example/setvar/setvar.c

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025, UNSW.
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+#include <stdint.h>
+#include <microkit.h>
+
+uint64_t mr_with_paddr_vaddr;
+uint64_t mr_with_paddr_paddr;
+
+uint64_t small_mr_no_paddr_paddr;
+uint64_t large_mr_no_paddr_paddr;
+
+uint64_t pl011_paddr;
+
+void init(void)
+{
+    microkit_dbg_puts("Virtual address of 'mr_with_paddr': ");
+    microkit_dbg_put32(mr_with_paddr_vaddr);
+    microkit_dbg_puts("\n");
+    microkit_dbg_puts("Physical address of 'mr_with_paddr': ");
+    microkit_dbg_put32(mr_with_paddr_paddr);
+    microkit_dbg_puts("\n");
+
+    microkit_dbg_puts("Physical address of 'small_mr_no_paddr': ");
+    microkit_dbg_put32(small_mr_no_paddr_paddr);
+    microkit_dbg_puts("\n");
+    microkit_dbg_puts("Physical address of 'large_mr_no_paddr': ");
+    microkit_dbg_put32(large_mr_no_paddr_paddr);
+    microkit_dbg_puts("\n");
+
+    microkit_dbg_puts("Physical address of 'pl011_paddr': ");
+    microkit_dbg_put32(pl011_paddr);
+    microkit_dbg_puts("\n");
+}
+
+void notified(microkit_channel ch)
+{
+}

example/setvar/setvar.system

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2025, UNSW.
+
+ SPDX-License-Identifier: BSD-2-Clause
+-->
+<system>
+    <!-- 0x900_0000 == 150994944 -->
+    <memory_region name="pl011" size="0x1000" phys_addr="0x900_0000" />
+
+    <!-- 0x8000_0000 == 2147483648 -->
+    <memory_region name="mr_with_paddr" size="0x1000" phys_addr="0x8000_0000" />
+
+    <memory_region name="small_mr_no_paddr" size="0x1000" />
+    <memory_region name="large_mr_no_paddr" size="0x200000" page_size="0x200000" />
+
+    <protection_domain name="setvar" priority="1">
+        <program_image path="setvar.elf" />
+
+        <!-- 0x2000_0000 == 536870912 -->
+        <map mr="mr_with_paddr" vaddr="0x2000_0000" setvar_vaddr="mr_with_paddr_vaddr" />
+        <setvar region_paddr="mr_with_paddr" symbol="mr_with_paddr_paddr" />
+        <setvar region_paddr="small_mr_no_paddr" symbol="small_mr_no_paddr_paddr" />
+        <setvar region_paddr="large_mr_no_paddr" symbol="large_mr_no_paddr_paddr" />
+        <setvar region_paddr="pl011" symbol="pl011_paddr" />
+    </protection_domain>
+</system>