Finish pass through language-extensions chapter.

I don't like the MMIO bit here, it will probably move at some point.

text/examples/.gitignore

@@ -0,0 +1,2 @@
+compile_commands.json
+.cache

text/examples/bounds_lengths/example.c

@@ -0,0 +1,45 @@
+#define MALLOC_QUOTA 320000
+#include <cheri-builtins.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+void print_capability(void *ptr)
+{
+	unsigned permissions = cheri_permissions_get(ptr);
+	printf(
+	  "0x%x (valid:%d length: 0x%x 0x%x-0x%x otype:%d "
+	  "permissions: %c "
+	  "%c%c%c%c%c%c %c%c %c%c%c)\n",
+	  cheri_address_get(ptr),
+	  cheri_tag_get(ptr),
+	  cheri_length_get(ptr),
+	  cheri_base_get(ptr),
+	  cheri_top_get(ptr),
+	  cheri_type_get(ptr),
+	  (permissions & CHERI_PERM_GLOBAL) ? 'G' : '-',
+	  (permissions & CHERI_PERM_LOAD) ? 'R' : '-',
+	  (permissions & CHERI_PERM_STORE) ? 'W' : '-',
+	  (permissions & CHERI_PERM_LOAD_STORE_CAP) ? 'c' : '-',
+	  (permissions & CHERI_PERM_LOAD_GLOBAL) ? 'g' : '-',
+	  (permissions & CHERI_PERM_LOAD_MUTABLE) ? 'm' : '-',
+	  (permissions & CHERI_PERM_STORE_LOCAL) ? 'l' : '-',
+	  (permissions & CHERI_PERM_SEAL) ? 'S' : '-',
+	  (permissions & CHERI_PERM_UNSEAL) ? 'U' : '-',
+	  (permissions & CHERI_PERM_USER0) ? '0' : '-');
+}
+
+__cheri_compartment("example") int entry(void)
+{
+	// representable_range#begin
+	const size_t Size = 160000;
+	printf("Smallest representable size of %d-byte "
+	       "allocation: %d (0x%x). Alignment mask: 0x%x\n",
+	       Size,
+	       cheri_round_representable_length(Size),
+	       cheri_round_representable_length(Size),
+	       cheri_representable_alignment_mask(Size));
+	void *allocation = malloc(Size);
+	print_capability(allocation);
+	// representable_range#end
+	return 0;
+}

text/examples/bounds_lengths/xmake.lua

@@ -0,0 +1,39 @@
+-- Copyright CHERIoT Contributors.
+-- SPDX-License-Identifier: MIT
+
+set_project("CHERIoT example")
+
+sdkdir = os.getenv("CHERIOT_SDK") or
+	"../../../rtos-source/sdk/"
+includes(sdkdir)
+
+set_toolchains("cheriot-clang")
+
+option("board")
+	set_default("sail")
+
+compartment("example")
+	add_files("example.c")
+
+-- firmware#begin
+-- Firmware image for the example.
+firmware("hello_world")
+	-- RTOS-provided libraries
+	add_deps("freestanding", "stdio")
+	-- Our compartments
+	add_deps("example")
+	on_load(function(target)
+		-- The board to target
+		target:values_set("board", "$(board)")
+		-- Threads to select
+		target:values_set("threads", {
+			{
+				compartment = "example",
+				priority = 1,
+				entry_point = "entry",
+				stack_size = 0x400,
+				trusted_stack_frames = 2
+			}
+		}, {expand = false})
+	end)
+-- firmware#end

text/examples/compare_capabilities/example.c

@@ -0,0 +1,88 @@
+#include <cheri-builtins.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+void print_capability(void *ptr)
+{
+	unsigned permissions = cheri_permissions_get(ptr);
+	printf(
+	  "0x%x (valid:%d length: 0x%x 0x%x-0x%x otype:%d "
+	  "permissions: %c "
+	  "%c%c%c%c%c%c %c%c %c%c%c)\n",
+	  cheri_address_get(ptr),
+	  cheri_tag_get(ptr),
+	  cheri_length_get(ptr),
+	  cheri_base_get(ptr),
+	  cheri_top_get(ptr),
+	  cheri_type_get(ptr),
+	  (permissions & CHERI_PERM_GLOBAL) ? 'G' : '-',
+	  (permissions & CHERI_PERM_LOAD) ? 'R' : '-',
+	  (permissions & CHERI_PERM_STORE) ? 'W' : '-',
+	  (permissions & CHERI_PERM_LOAD_STORE_CAP) ? 'c' : '-',
+	  (permissions & CHERI_PERM_LOAD_GLOBAL) ? 'g' : '-',
+	  (permissions & CHERI_PERM_LOAD_MUTABLE) ? 'm' : '-',
+	  (permissions & CHERI_PERM_STORE_LOCAL) ? 'l' : '-',
+	  (permissions & CHERI_PERM_SEAL) ? 'S' : '-',
+	  (permissions & CHERI_PERM_UNSEAL) ? 'U' : '-',
+	  (permissions & CHERI_PERM_USER0) ? '0' : '-');
+}
+
+__cheri_compartment("example") int entry(void)
+{
+	// capability_equality#begin
+	// A stack allocation
+	char  stackBuffer[23];
+	char *offset = stackBuffer + 4;
+	print_capability(offset);
+	// Reduce the bounds
+	char *bounded = cheri_bounds_set(offset, 4);
+	print_capability(bounded);
+	printf("Equal? %d\n", bounded == offset);
+	printf("Exactly equal? %d\n",
+	       cheri_is_equal_exact(bounded, offset));
+	// Remove permissions
+	char *restricted =
+	  cheri_permissions_and(bounded, CHERI_PERM_LOAD);
+	print_capability(restricted);
+	printf("Equal? %d\n", bounded == restricted);
+	printf("Exactly equal? %d\n",
+	       cheri_is_equal_exact(bounded, restricted));
+	char *untagged = cheri_tag_clear(restricted);
+	print_capability(untagged);
+	printf("Equal? %d\n", untagged == restricted);
+	printf("Exactly equal? %d\n",
+	       cheri_is_equal_exact(untagged, restricted));
+	// capability_equality#end
+
+	// capability_ordering#begin
+	if (bounded > offset)
+	{
+		printf("bounded > offset\n");
+	}
+	else if (bounded < offset)
+	{
+		printf("bounded < offset\n");
+	}
+	else if (cheri_is_equal_exact(bounded, offset))
+	{
+		printf("bounded exactly equals offset\n");
+	}
+	else
+	{
+		printf("bounded is not greater than, less than, nor "
+		       "equal to, offset\n");
+	}
+	// capability_ordering#end
+
+	// capability_subset#begin
+	printf("bounded ⊂ offset? %d\n",
+	       cheri_subset_test(offset, bounded));
+	printf("restricted ⊂ bounded? %d\n",
+	       cheri_subset_test(bounded, restricted));
+	printf("untagged ⊂ restricted? %d\n",
+	       cheri_subset_test(restricted, untagged));
+	printf("offset ⊂ bounded? %d\n",
+	       cheri_subset_test(bounded, offset));
+	// capability_subset#end
+	return 0;
+}

text/examples/compare_capabilities/xmake.lua

@@ -0,0 +1,39 @@
+-- Copyright CHERIoT Contributors.
+-- SPDX-License-Identifier: MIT
+
+set_project("CHERIoT example")
+
+sdkdir = os.getenv("CHERIOT_SDK") or
+	"../../../rtos-source/sdk/"
+includes(sdkdir)
+
+set_toolchains("cheriot-clang")
+
+option("board")
+	set_default("sail")
+
+compartment("example")
+	add_files("example.c")
+
+-- firmware#begin
+-- Firmware image for the example.
+firmware("hello_world")
+	-- RTOS-provided libraries
+	add_deps("freestanding", "stdio")
+	-- Our compartments
+	add_deps("example")
+	on_load(function(target)
+		-- The board to target
+		target:values_set("board", "$(board)")
+		-- Threads to select
+		target:values_set("threads", {
+			{
+				compartment = "example",
+				priority = 1,
+				entry_point = "entry",
+				stack_size = 0x400,
+				trusted_stack_frames = 2
+			}
+		}, {expand = false})
+	end)
+-- firmware#end

text/examples/manipulate_capabilities_cxx/example.cc

@@ -0,0 +1,64 @@
+#include <cheri.hh>
+#include <stdio.h>
+#include <stdlib.h>
+
+// print_capability#begin
+void print_capability(CHERI::Capability<void> ptr)
+{
+	using P                          = CHERI::Permission;
+	ptraddr_t            address     = ptr.address();
+	CHERI::PermissionSet permissions = ptr.permissions();
+	printf("0x%x (valid:%d length: 0x%x 0x%x-0x%x otype:%d "
+	       "permissions: %c "
+	       "%c%c%c%c%c%c %c%c %c%c%c)\n",
+	       address,
+	       ptr.is_valid(),
+	       ptr.length(),
+	       ptr.base(),
+	       ptr.top(),
+	       ptr.type(),
+	       (permissions.contains(P::Global)) ? 'G' : '-',
+	       (permissions.contains(P::Load)) ? 'R' : '-',
+	       (permissions.contains(P::Store)) ? 'W' : '-',
+	       (permissions.contains(P::LoadStoreCapability))
+	         ? 'c'
+	         : '-',
+	       (permissions.contains(P::LoadGlobal)) ? 'g' : '-',
+	       (permissions.contains(P::LoadMutable)) ? 'm' : '-',
+	       (permissions.contains(P::StoreLocal)) ? 'l' : '-',
+	       (permissions.contains(P::Seal)) ? 'S' : '-',
+	       (permissions.contains(P::Unseal)) ? 'U' : '-',
+	       (permissions.contains(P::Global)) ? '0' : '-');
+}
+// print_capability#end
+
+__cheri_compartment("example") int entry(void)
+{
+	// capability_manipulation#begin
+	// A stack allocation
+	char stackBuffer[23];
+	print_capability(stackBuffer);
+	// A heap allocation
+	CHERI::Capability<void> heapBuffer = new char[23];
+	print_capability(heapBuffer);
+	// Setting the bounds of a heap capability
+	auto bounded     = heapBuffer;
+	bounded.bounds() = 23;
+	print_capability(bounded);
+	// Removing permissions from a heap capability
+	bounded.permissions() &= CHERI::Permission::Load;
+	print_capability(bounded);
+	print_capability(heapBuffer);
+	// capability_manipulation#end
+
+	// capability_equality#begin
+	printf("heapBuffer == bounded? %d\n",
+	       heapBuffer == bounded);
+	printf("heapBuffer == bounded (as raw pointers)? %d\n",
+	       heapBuffer.get() == bounded.get());
+	printf(
+	  "heapBuffer == bounded (as address comparison)? %d\n",
+	  heapBuffer.address() == bounded.address());
+	// capability_equality#end
+	return 0;
+}

text/examples/manipulate_capabilities_cxx/xmake.lua

@@ -0,0 +1,39 @@
+-- Copyright CHERIoT Contributors.
+-- SPDX-License-Identifier: MIT
+
+set_project("CHERIoT example")
+
+sdkdir = os.getenv("CHERIOT_SDK") or
+	"../../../rtos-source/sdk/"
+includes(sdkdir)
+
+set_toolchains("cheriot-clang")
+
+option("board")
+	set_default("sail")
+
+compartment("example")
+	add_files("example.cc")
+
+-- firmware#begin
+-- Firmware image for the example.
+firmware("hello_world")
+	-- RTOS-provided libraries
+	add_deps("freestanding", "stdio")
+	-- Our compartments
+	add_deps("example")
+	on_load(function(target)
+		-- The board to target
+		target:values_set("board", "$(board)")
+		-- Threads to select
+		target:values_set("threads", {
+			{
+				compartment = "example",
+				priority = 1,
+				entry_point = "entry",
+				stack_size = 0x400,
+				trusted_stack_frames = 2
+			}
+		}, {expand = false})
+	end)
+-- firmware#end