add top-level and per-arch README.md

README.md

@@ -0,0 +1,10 @@
+# rt
+
+`rt` is a real-time operating system capable of full preemption.
+
+`rt` provides many familiar synchronization interfaces and implements them with
+atomics for high performance and preemptibility. `rt`'s non-blocking interfaces
+can be used safely in both tasks and interrupts, and it does not rely on
+disabling interrupts to implement synchronization. On architectures without
+hardware support for atomics, interrupt masking is used to provide an interface
+for atomics with very short gaps in interrupt availability.

arch/arm/README.md

@@ -0,0 +1,62 @@
+# Arm
+
+`rt` supports the following variants of the 32-bit Arm architecture:
+
+ - `armv6-m`
+ - `armv7-m`
+ - `armv8-m.main`
+ - `armv8-m.base`
+ - `armv7-r`
+
+## Cortex-M
+
+On Cortex-M devices, the `rt_syscall_handler` function should be configured as
+the handler for both the SVCall and PendSV exceptions in the NVIC. Both of
+these exceptions should be configured with the lowest exception priority (i.e.,
+the largest numerical value). The `rt_tick_advance` function should be
+configured as the handler for the SysTick exception, and have a priority higher
+than PendSV and SVCall. If desired, a different timer can be used for the tick,
+but it's likely a custom handler that calls `rt_tick_advance` is needed in this
+case if the interrupt is not automatically cleared like SysTick.
+
+Tasks in `rt` use the process stack pointer (`psp`), and on `armv8-m` the
+`psplim` register is used to protect against stack exhaustion.
+
+## Cortex-R
+
+Cortex-R devices can have a variety of different interrupt controllers
+connected to the core's Vectored Interrupt Controller port, and different ways
+of triggering a software interrupt for deferred system call handling.
+Therefore, different Cortex-R devices require different code for these
+purposes. Implementations of the VIC management and software interrupt code for
+the Hercules and Sitara families of Cortex-R devices are provided in respective
+subdirectories of `arch/arm/r`. To build `rt` with support for one of these,
+add the appropriate directory to the preprocessor include path when compiling.
+
+The `rt_syscall_handler_svc` function should be used as the handler for the SVC
+exception and the `rt_syscall_handler` function should be used as the handler
+for the syscall IRQ. Lastly, the tick timer interrupt will need to call
+`rt_tick_advance`, as `rt_tick_advance` is not usable directly as an
+interrupt handler as it is on Cortex-M. If IRQ nesting is implemented, then the
+tick timer interrupt handler must mask the syscall interrupt, either explicitly
+or through a priority mechanism provided by the interrupt controller.
+
+Tasks in `rt` start in system mode and can call `rt_task_drop_privilege` to
+switch to user mode. If nested interrupts are implemented, they should be
+executed in supervisor mode.
+
+## Memory Protection
+
+The memory protection unit available in many Cortex-M and Cortex-R devices is
+supported and can be enabled by compiling with `-DRT_MPU_ENABLE=1`. By default,
+`rt` assumes the MPU has 8 regions, but this can be overridden with
+`-DRT_MPU_NUM_REGIONS=<number>` for processors with more. By default, `rt`
+reserves the 4 highest-priority regions to be reconfigured for every task, with
+one of those regions reserved for the task's stack that is automatically
+initialized along with the task itself. To change the number of per-task MPU
+regions, use `-DRT_MPU_NUM_TASK_REGIONS=<number>`. The remaining lower-priority
+regions can be configured at startup time and will not be modified by `rt`. The
+MPU is never disabled at run-time, even during context switches and interrupts.
+The background MPU region is enabled, so privileged tasks and exceptions will
+have access to memory with the default permissions and attributes unless there
+is a region specifically configured for a given address.

arch/pthread/README.md

@@ -0,0 +1,11 @@
+# pthread
+
+This code allows `rt` to run on Linux and other POSIX systems for simulation
+and testing. Each task is given a pthread, and syscalls and ticks are
+implemented as signals that are handled by the active task (thread).
+
+Unfortunately, this code compiles but does not work reliably on macOS, due to a
+bug in how `pthread_kill` works on that operating system: sometimes a different
+thread will receive a signal than the one passed to `pthread_kill`. This bug is
+tracked as [FB11025104](https://feedbackassistant.apple.com/feedback/11025104)
+in Apple's Feedback system.