switcher: Rework commentary

Include "Register Atlas"es and updates at key points, making it
hopefully easier to understand what's going on at any given point in the
code.

Annotate arcs in the CFG at their target, not just their source, as well
as IRQ disposition and live-in and live-out register sets.

The intention is that much of this should be amenable to automatic
verification, but no such tooling yet exists.

To ease review, this large commit changes no bytes in the actual
assembled output.

Co-authored-by: David Chisnall <[email protected]>
Co-authored-by: Murali Vijayaraghavan <[email protected]>
Co-authored-by: Robert Norton <[email protected]>

sdk/core/loader/boot.cc

@@ -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;