tock · ppannuto · Mar 12, 2025
diff --git a/examples/tests/mpu/README.md b/examples/tests/mpu/README.md
@@ -1,4 +1,56 @@
 MPU Tests
 =========
 
-Test that the MPU restricts process accesses correctly.
+Tests that the MPU restricts process accesses correctly.
+
+MPU test applications are necessarily somewhat fine-grained, as each MPU
+violation results in termination of the test process.
+
+As it can be annoying to flash myriad apps during development, the tests in the
+top-level directory attempt to exercise all of the reads and writes of regions
+that _should_ work during normal operation (and allow use of a button to inject
+faults for interactive testing). The `unit/` folder holds all of the smaller
+tests which attempt to violate access rules at each of the boundaries.
+
+ ```text
+      Perms?    Application Memory Layout     Relevant Memop(s)       Test
+
+ ╔═   ╒RWX════════ ← mem_start + mem_len.....{3-mem_end} get          unit/mpu_ram_end
+ ║    │...┆Grant Pointers
+ ║    │...┆──────
+ ║    │...┆Process Control Block
+ ║ ╔═ │...┆──────
+ ║    │...┆Grant Regions
+ ║ D  │...┆
+ ║ Y  │...┆  ↓
+ ║ N  │...┆──────  ← kernel_memory_break.....{6-grant start} get      unit/mpu_grant_start
+ ║ A  │...┆
+ ║ M  │rw.┆──────  ← app_break...............{0-brk, 1-sbrk}          unit/mpu_heap_end
+ ║ I  │rw.┆                                    get or move
+ ║ C  │rw.┆  ↑
+ ║    │rw.┆ Heap
+ ║ ╚═ │rw.┆──────  ← app_heap_start..........{11-heap bot} set        (debug facilty; untested)
+      │rw.┆ Data
+ F    │rw.┆──────  ← data_start_pointer......{10-stack top} set       (debug facilty; untested)
+ I    │rw.┆Stack
+ X    │rw.┆  ↓
+ E    │rw.┆
+ D    │rw.┆──────  ← current_stack_pointer
+      │rw.┆
+ ╚═══ ╘═══════════ ← memory_start............{2-mem_start} get        unit/mpu_stack_growth (needs refinement)
+
+ ╔═   ╒RWX ═══════ ← app end.................{5-flash end} get        unit/mpu_flash_end
+ ║    │r.x┆
+      │r.x┆ app
+ F    │r.x┆
+ I  ╔ │r.x┆──────
+ X  T │r..┆
+ E  B │rw.┆ ┍──
+ D  F  rw.┆ ┋   Writeable flash
+      │rw.┆ ┍── regions in the               {9-region[N] end} get    (todo)
+ ║  H │rw.┆ ┝── TBF header                   {8-region[N] start} get  (todo)
+ ║  D │rw.┆ ┕──
+ ║  R │r..┆                                  {7-#flash regions} get   (todo)
+ ║    │r..┆
+ ╚═ ╚ ╘═══════════ ← app start...............{4-flash start} get      unit/mpu_flash_start
+```
diff --git a/examples/tests/mpu/mpu_ram_end/Makefile b/examples/tests/mpu/mpu_ram_end/Makefile
diff --git a/examples/tests/mpu/mpu_flash_end/Makefile → ...les/tests/mpu/unit/mpu_flash_end/Makefile b/examples/tests/mpu/mpu_flash_end/Makefile → ...les/tests/mpu/unit/mpu_flash_end/Makefile
@@ -1,7 +1,7 @@
 # Makefile for user application
 
 # Specify this directory relative to the current application.
-TOCK_USERLAND_BASE_DIR = ../../../..
+TOCK_USERLAND_BASE_DIR = ../../../../..
 
 # Which files to compile.
 C_SRCS := $(wildcard *.c)

diff --git a/examples/tests/mpu/mpu_flash_end/README.md → ...es/tests/mpu/unit/mpu_flash_end/README.md b/examples/tests/mpu/mpu_flash_end/README.md → ...es/tests/mpu/unit/mpu_flash_end/README.md
diff --git a/examples/tests/mpu/mpu_flash_end/main.c → examples/tests/mpu/unit/mpu_flash_end/main.c b/examples/tests/mpu/mpu_flash_end/main.c → examples/tests/mpu/unit/mpu_flash_end/main.c
diff --git a/examples/tests/mpu/mpu_flash_start/Makefile → ...s/tests/mpu/unit/mpu_flash_start/Makefile b/examples/tests/mpu/mpu_flash_start/Makefile → ...s/tests/mpu/unit/mpu_flash_start/Makefile
@@ -1,7 +1,7 @@
 # Makefile for user application
 
 # Specify this directory relative to the current application.
-TOCK_USERLAND_BASE_DIR = ../../../..
+TOCK_USERLAND_BASE_DIR = ../../../../..
 
 # Which files to compile.
 C_SRCS := $(wildcard *.c)

diff --git a/examples/tests/mpu/mpu_flash_start/README.md → .../tests/mpu/unit/mpu_flash_start/README.md b/examples/tests/mpu/mpu_flash_start/README.md → .../tests/mpu/unit/mpu_flash_start/README.md
diff --git a/examples/tests/mpu/mpu_flash_start/main.c → ...les/tests/mpu/unit/mpu_flash_start/main.c b/examples/tests/mpu/mpu_flash_start/main.c → ...les/tests/mpu/unit/mpu_flash_start/main.c
diff --git a/examples/tests/mpu/mpu_grant_start/Makefile → ...s/tests/mpu/unit/mpu_grant_start/Makefile b/examples/tests/mpu/mpu_grant_start/Makefile → ...s/tests/mpu/unit/mpu_grant_start/Makefile
@@ -1,7 +1,7 @@
 # Makefile for user application
 
 # Specify this directory relative to the current application.
-TOCK_USERLAND_BASE_DIR = ../../../..
+TOCK_USERLAND_BASE_DIR = ../../../../..
 
 # Which files to compile.
 C_SRCS := $(wildcard *.c)

diff --git a/examples/tests/mpu/mpu_grant_start/README.md → .../tests/mpu/unit/mpu_grant_start/README.md b/examples/tests/mpu/mpu_grant_start/README.md → .../tests/mpu/unit/mpu_grant_start/README.md
diff --git a/examples/tests/mpu/mpu_grant_start/main.c → ...les/tests/mpu/unit/mpu_grant_start/main.c b/examples/tests/mpu/mpu_grant_start/main.c → ...les/tests/mpu/unit/mpu_grant_start/main.c
diff --git a/examples/tests/mpu/mpu_heap_end/Makefile → ...ples/tests/mpu/unit/mpu_heap_end/Makefile b/examples/tests/mpu/mpu_heap_end/Makefile → ...ples/tests/mpu/unit/mpu_heap_end/Makefile
@@ -1,7 +1,7 @@
 # Makefile for user application
 
 # Specify this directory relative to the current application.
-TOCK_USERLAND_BASE_DIR = ../../../..
+TOCK_USERLAND_BASE_DIR = ../../../../..
 
 # Which files to compile.
 C_SRCS := $(wildcard *.c)

diff --git a/examples/tests/mpu/mpu_heap_end/README.md → ...les/tests/mpu/unit/mpu_heap_end/README.md b/examples/tests/mpu/mpu_heap_end/README.md → ...les/tests/mpu/unit/mpu_heap_end/README.md
diff --git a/examples/tests/mpu/mpu_heap_end/main.c → examples/tests/mpu/unit/mpu_heap_end/main.c b/examples/tests/mpu/mpu_heap_end/main.c → examples/tests/mpu/unit/mpu_heap_end/main.c
diff --git a/examples/tests/mpu/unit/mpu_ram_end/Makefile b/examples/tests/mpu/unit/mpu_ram_end/Makefile
@@ -0,0 +1,13 @@
+# Makefile for user application
+
+# Specify this directory relative to the current application.
+TOCK_USERLAND_BASE_DIR = ../../../../..
+
+# Which files to compile.
+C_SRCS := $(wildcard *.c)
+
+STACK_SIZE := 1024
+
+# Include userland master makefile. Contains rules and flags for actually
+# building the application.
+include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk
diff --git a/examples/tests/mpu/mpu_ram_end/README.md → ...ples/tests/mpu/unit/mpu_ram_end/README.md b/examples/tests/mpu/mpu_ram_end/README.md → ...ples/tests/mpu/unit/mpu_ram_end/README.md
diff --git a/examples/tests/mpu/mpu_ram_end/main.c → examples/tests/mpu/unit/mpu_ram_end/main.c b/examples/tests/mpu/mpu_ram_end/main.c → examples/tests/mpu/unit/mpu_ram_end/main.c
diff --git a/examples/tests/mpu/mpu_stack_growth/Makefile → .../tests/mpu/unit/mpu_stack_growth/Makefile b/examples/tests/mpu/mpu_stack_growth/Makefile → .../tests/mpu/unit/mpu_stack_growth/Makefile
@@ -1,7 +1,7 @@
 # Makefile for user application
 
 # Specify this directory relative to the current application.
-TOCK_USERLAND_BASE_DIR = ../../../..
+TOCK_USERLAND_BASE_DIR = ../../../../..
 
 # Which files to compile.
 C_SRCS := $(wildcard *.c)

diff --git a/examples/tests/mpu/mpu_stack_growth/main.c → ...es/tests/mpu/unit/mpu_stack_growth/main.c b/examples/tests/mpu/mpu_stack_growth/main.c → ...es/tests/mpu/unit/mpu_stack_growth/main.c