add top-level and per-arch

This commit is contained in:
Chris Copeland 2023-09-23 20:26:55 -07:00
parent ea7b8d54b1
commit deb13439c5
Signed by: chrisnc
GPG Key ID: 14550DA72485DF30
3 changed files with 83 additions and 0 deletions

10 Normal file
View File

@ -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/ Normal file
View File

@ -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/ Normal file
View File

@ -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](
in Apple's Feedback system.