architecture-porting.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3=============================================
  4Porting an architecture to support PREEMPT_RT
  5=============================================
  6
  7:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
  8
  9This list outlines the architecture specific requirements that must be
 10implemented in order to enable PREEMPT_RT. Once all required features are
 11implemented, ARCH_SUPPORTS_RT can be selected in architecture’s Kconfig to make
 12PREEMPT_RT selectable.
 13Many prerequisites (genirq support for example) are enforced by the common code
 14and are omitted here.
 15
 16The optional features are not strictly required but it is worth to consider
 17them.
 18
 19Requirements
 20------------
 21
 22Forced threaded interrupts
 23  CONFIG_IRQ_FORCED_THREADING must be selected. Any interrupts that must
 24  remain in hard-IRQ context must be marked with IRQF_NO_THREAD. This
 25  requirement applies for instance to clocksource event interrupts,
 26  perf interrupts and cascading interrupt-controller handlers.
 27
 28PREEMPTION support
 29  Kernel preemption must be supported and requires that
 30  CONFIG_ARCH_NO_PREEMPT remain unselected. Scheduling requests, such as those
 31  issued from an interrupt or other exception handler, must be processed
 32  immediately.
 33
 34POSIX CPU timers and KVM
 35  POSIX CPU timers must expire from thread context rather than directly within
 36  the timer interrupt. This behavior is enabled by setting the configuration
 37  option CONFIG_HAVE_POSIX_CPU_TIMERS_TASK_WORK.
 38  When KVM is enabled, CONFIG_KVM_XFER_TO_GUEST_WORK must also be set to ensure
 39  that any pending work, such as POSIX timer expiration, is handled before
 40  transitioning into guest mode.
 41
 42Hard-IRQ and Soft-IRQ stacks
 43  Soft interrupts are handled in the thread context in which they are raised. If
 44  a soft interrupt is triggered from hard-IRQ context, its execution is deferred
 45  to the ksoftirqd thread. Preemption is never disabled during soft interrupt
 46  handling, which makes soft interrupts preemptible.
 47  If an architecture provides a custom __do_softirq() implementation that uses a
 48  separate stack, it must select CONFIG_HAVE_SOFTIRQ_ON_OWN_STACK. The
 49  functionality should only be enabled when CONFIG_SOFTIRQ_ON_OWN_STACK is set.
 50
 51FPU and SIMD access in kernel mode
 52  FPU and SIMD registers are typically not used in kernel mode and are therefore
 53  not saved during kernel preemption. As a result, any kernel code that uses
 54  these registers must be enclosed within a kernel_fpu_begin() and
 55  kernel_fpu_end() section.
 56  The kernel_fpu_begin() function usually invokes local_bh_disable() to prevent
 57  interruptions from softirqs and to disable regular preemption. This allows the
 58  protected code to run safely in both thread and softirq contexts.
 59  On PREEMPT_RT kernels, however, kernel_fpu_begin() must not call
 60  local_bh_disable(). Instead, it should use preempt_disable(), since softirqs
 61  are always handled in thread context under PREEMPT_RT. In this case, disabling
 62  preemption alone is sufficient.
 63  The crypto subsystem operates on memory pages and requires users to "walk and
 64  map" these pages while processing a request. This operation must occur outside
 65  the kernel_fpu_begin()/ kernel_fpu_end() section because it requires preemption
 66  to be enabled. These preemption points are generally sufficient to avoid
 67  excessive scheduling latency.
 68
 69Exception handlers
 70  Exception handlers, such as the page fault handler, typically enable interrupts
 71  early, before invoking any generic code to process the exception. This is
 72  necessary because handling a page fault may involve operations that can sleep.
 73  Enabling interrupts is especially important on PREEMPT_RT, where certain
 74  locks, such as spinlock_t, become sleepable. For example, handling an
 75  invalid opcode may result in sending a SIGILL signal to the user task. A
 76  debug excpetion will send a SIGTRAP signal.
 77  In both cases, if the exception occurred in user space, it is safe to enable
 78  interrupts early. Sending a signal requires both interrupts and kernel
 79  preemption to be enabled.
 80
 81Optional features
 82-----------------
 83
 84Timer and clocksource
 85  A high-resolution clocksource and clockevents device are recommended. The
 86  clockevents device should support the CLOCK_EVT_FEAT_ONESHOT feature for
 87  optimal timer behavior. In most cases, microsecond-level accuracy is
 88  sufficient
 89
 90Lazy preemption
 91  This mechanism allows an in-kernel scheduling request for non-real-time tasks
 92  to be delayed until the task is about to return to user space. It helps avoid
 93  preempting a task that holds a sleeping lock at the time of the scheduling
 94  request.
 95  With CONFIG_GENERIC_IRQ_ENTRY enabled, supporting this feature requires
 96  defining a bit for TIF_NEED_RESCHED_LAZY, preferably near TIF_NEED_RESCHED.
 97
 98Serial console with NBCON
 99  With PREEMPT_RT enabled, all console output is handled by a dedicated thread
100  rather than directly from the context in which printk() is invoked. This design
101  allows printk() to be safely used in atomic contexts.
102  However, this also means that if the kernel crashes and cannot switch to the
103  printing thread, no output will be visible preventing the system from printing
104  its final messages.
105  There are exceptions for immediate output, such as during panic() handling. To
106  support this, the console driver must implement new-style lock handling. This
107  involves setting the CON_NBCON flag in console::flags and providing
108  implementations for the write_atomic, write_thread, device_lock, and
109  device_unlock callbacks.