examples/01.hello_world/README.md - 3p/cheriot-rtos - Git at Google


            
            Hello World example

            
            ===================


            This example shows a simple hello-world firmware image, with a single thread and a single compartment.

            
            This uses the debug facilities to write a message directly to the UART.


            The [`xmake.lua`](xmake.lua) file contains the build instructions for this example.

            
            This file contains two libraries (one providing `memcpy`, the other `clz`) that can be used by multiple compartments, and a single compartment (beyond the RTOS components).


            The code for the compartment is all in [`hello.cc`](hello.cc).

            
            This file first imports the debug facilities:


            ```c++

            
            using Debug = ConditionalDebug<true, "Hello world compartment">;

            
            ```


            The `ConditionalDebug` template is intended to allow the first argument to be an expression that may include macro definitions so that debugging can be selectively enabled for subsets of a program at build time.

            
            For now, we're just enabling it unconditionally so that we can use its `log` method to write to the UART.


            This will, indirectly, use the `MMIO_CAPABILITY` macro, which imports a memory-mapped I/O device, the target platform's default UART.

            
            Our example compartment will be granted direct access to the UART, which it can then use from its entry point function, `say_hello`.


            Note that the definition of this function uses a macro to indicate the compartment that it is in (`"hello"`).

            
            This macro is normally used on function definitions, rather than declarations, and allows the compiler to either export the function when it is defined or insert cross-compartment calls when it is used when compiling code for another compartment.


            We also include the SDK header `fail-simulator-on-error.h`. This defines a

            
            simple [compartment error handler](../docs/ErrorHandling.md) that reports any

            
            unexpected errors and ends the simulation with exit code 1 (FAILURE). This is

            
            necessary because the default behaviour would silently exit the thread,

            
            potentially hiding errors.
	Hello World example
	===================

	This example shows a simple hello-world firmware image, with a single thread and a single compartment.
	This uses the debug facilities to write a message directly to the UART.

	The [`xmake.lua`](xmake.lua) file contains the build instructions for this example.
	This file contains two libraries (one providing `memcpy`, the other `clz`) that can be used by multiple compartments, and a single compartment (beyond the RTOS components).

	The code for the compartment is all in [`hello.cc`](hello.cc).
	This file first imports the debug facilities:

	```c++
	using Debug = ConditionalDebug<true, "Hello world compartment">;
	```

	The `ConditionalDebug` template is intended to allow the first argument to be an expression that may include macro definitions so that debugging can be selectively enabled for subsets of a program at build time.
	For now, we're just enabling it unconditionally so that we can use its `log` method to write to the UART.

	This will, indirectly, use the `MMIO_CAPABILITY` macro, which imports a memory-mapped I/O device, the target platform's default UART.
	Our example compartment will be granted direct access to the UART, which it can then use from its entry point function, `say_hello`.

	Note that the definition of this function uses a macro to indicate the compartment that it is in (`"hello"`).
	This macro is normally used on function definitions, rather than declarations, and allows the compiler to either export the function when it is defined or insert cross-compartment calls when it is used when compiling code for another compartment.

	We also include the SDK header `fail-simulator-on-error.h`. This defines a
	simple [compartment error handler](../docs/ErrorHandling.md) that reports any
	unexpected errors and ends the simulation with exit code 1 (FAILURE). This is
	necessary because the default behaviour would silently exit the thread,
	potentially hiding errors.