WIP: various tweaks to, and a pile of documentation for, the switcher and exception handler

sdk/core/loader/boot.cc

@@ -596,9 +596,9 @@ namespace
 			{
 				if (contains<ExportEntry>(lib.exportTable, possibleLibcall))
 				{
-					// TODO: Library export tables are not used after the
-					// loader has run, we could move them to the end of the
-					// image and make that space available for the heap.
+					// Library export tables are not used after the loader has
+					// run; our linker script places them to the end of the
+					// image, which we make available for the heap.
 					return createLibCall(build_pcc(lib));
 				}
 			}
@@ -850,6 +850,8 @@ namespace
 		 * than by fiat of initial construction.  The switcher will detect the
 		 * trusted stack underflow and will signal the scheduler that the thread
 		 * has exited and should not be brought back on core.
+		 *
+		 * See core/switcher/entry.S:/^switcher_after_compartment_call.
 		 */
 		auto threadInitialReturn =
 		  build<void, Root::Type::Execute, SwitcherPccPermissions>(

sdk/core/loader/types.h

@@ -365,6 +365,7 @@ namespace loader
 			/**
 			 * The PCC-relative location of the cross-compartment call return
 			 * path, used to build the initial return addresses for threads.
+			 * That is, "switcher_after_compartment_call".
 			 */
 			uint16_t crossCallReturnEntry;
 
@@ -1097,7 +1098,7 @@ namespace loader
 
 		/**
 		 * Flags.  The low three bits indicate the number of registers that
-		 * should be cleared in the compartment switcher.  The next two bits
+		 * should be passed in the compartment switcher.  The next two bits
 		 * indicate the interrupt status.  The remaining three are currently
 		 * unused.
 		 */

sdk/core/switcher/tstack.h

@@ -10,7 +10,13 @@
 
 struct TrustedStackFrame
 {
-	/// caller's stack
+	/**
+	 * Caller's stack pointer, at time of cross-compartment entry, pointing at
+	 * switcher's register spills (.Lswitch_entry_first_spill and following).
+	 *
+	 * The address of this pointer is the (upper) limit of the stack capability
+	 * given to the callee.
+	 */
 	void *csp;
 	/**
 	 * The callee's export table.  This is stored here so that we can find the
@@ -28,6 +34,13 @@ struct TrustedStackFrame
 	uint16_t errorHandlerCount;
 };
 
+/**
+ * Each thread in the system has, and is identified by, its Trusted Stack.
+ * These structures hold an activation frame (a TrustedStackFrame) for each
+ * active cross-compartment call as well as a "spill" register context, used
+ * mostly for preemption (but also as staging space when a thread is adopting a
+ * new context as part of exception handlng).
+ */
 template<size_t NFrames>
 struct TrustedStackGeneric
 {

sdk/firmware.ldscript.in

@@ -163,7 +163,7 @@ SECTIONS
 		# Compartment switcher end
 		SHORT(.compartment_switcher_end - .compartment_switcher_start);
 		# Cross-compartment call return path
-		SHORT(switcher_skip_compartment_call - .compartment_switcher_start);
+		SHORT(switcher_after_compartment_call - .compartment_switcher_start);
 		# Compartment switcher sealing key
 		SHORT(compartment_switcher_sealing_key - .compartment_switcher_start);
 		# Switcher's copy of the scheduler's PCC.

sdk/include/assembly-helpers.h

@@ -92,7 +92,7 @@ struct CheckSize
 #else
 #	define EXPORT_ASSEMBLY_NAME(name, value)
 #	define EXPORT_ASSEMBLY_EXPRESSION(name, expression, value)
-#	define EXPORT_ASSEMBLY_OFFSET(structure, field, name)
+#	define EXPORT_ASSEMBLY_OFFSET(structure, field, value)
 #	define EXPORT_ASSEMBLY_SIZE(structure, name, value)
 #	define EXPORT_ASSEMBLY_OFFSET_NAMED(structure, field, value, name)
 #endif

sdk/lib/unwind_error_handler/unwind.S

@@ -6,7 +6,7 @@
  *
  * If there is no registered CleanupList structure (equivalently, there's no
  * CHERIOT_DURING block active at the time of the fault), then this requests
- * unwnding out of the compartment.  Otherwise, we will longjmp() out to the
+ * unwinding out of the compartment.  Otherwise, we will longjmp() out to the
  * indicated handler (that is, the CHERIOT_HANDLER block associated with the
  * current CHERIOT_DURING block), having reset the compartment error handler
  * invocation counter to zero.

tests/crash_recovery-test.cc

@@ -13,8 +13,9 @@ std::atomic<bool> expectFault;
 static void test_irqs_are_enabled()
 {
 	void *r = __builtin_return_address(0);
-	TEST(__builtin_cheri_type_get(r) == CheriSealTypeReturnSentryEnabling,
-	     "Calling context has IRQs disabled");
+	TEST_EQUAL(__builtin_cheri_type_get(r),
+	           CheriSealTypeReturnSentryEnabling,
+	           "Calling context has IRQs disabled");
 }
 
 extern "C" enum ErrorRecoveryBehaviour