RHEL-RT Relnotes
From RHEL-RT
Contents |
RHEL-RT Release Notes
Release notes (aka relnotes) are intended to be brief information that someone installing RHEL-RT should be aware of prior to installation. It is not intended to be the full detailed documentation. This page is a draft version for RHEL-RT.
Pre-installation Instructions
A prerequisite to installing RHEL-RT is to do a RHEL5 fresh install. Notes:
- We aren't testing/supporting update installations from RHEL4. Rather, a full system installation is required.
- We certainly do not support a mix of RHEL4/RHEL5 components. It won't work to start with RHEL4 and drop in the realtime kernel and glibc - there are many more dependencies than that.
- RHEL5.1 is the prerequisite baseline install. The originl RHEL5.0 release is not recent enough.
- When doing the initial system installation, you should select the set of packages you normally do to meet the needs of your application environment (ie, nothing realtime specific is required on the initial install).
Post install, you will follow the instructions to incrementally add the realtime specific packages from a separate yum repositiory.
Supplied Realtime Kernel Variants
There are numerous kernel variants provided. The main deployment realtime kernel is identified below as production. Additionally there are several other debug kernels which have successively more diagnostic code compiled in. The reason for doing this is that as the amount of debug code is increased, so does the overhead. The progression from least overhead to most is: kernel-rt-trace, kernel-rt-debug. Lastly the vanilla kernel does not include the realtime features. This is used help distinguish whether bugs were introduced in the realtime features, rather than being an inherent bug in the baseline kernel. The set of kernels is separately provided for x86 (32-bit) and x86-64 (64-bit) systems. Select either set based on whether you intend to run in 32-bit or 64-bit mode.
| Variant | Intended Usage | Notes |
|---|---|---|
| x86 (kernel-rt) | production - Standard 32-bit production realtime kernel | x86 version with PAE enabled (to allow for up to 16G memory) |
| x86 tracing (kernel-rt-trace) | debugging - 32-bit trace kernel | latency tracer enabled - Used to locate latency hotspots |
| x86 debug (kernel-rt-debug) | debugging - 32-bit debugging kernel | latency tracer enabled + other debugging options - Used to debug RT kernel failures |
| x86 vanilla (kernel-rt-vanilla) | debugging - 32-bit base kernel | No RT features, used for comparison |
| x86_64 (kernel-rt) | production - Standard 64-bit production kernel | |
| x86_64 tracing (kernel-rt-tracing) | debugging - 64-bit trace kernel | latency tracer enabled - Used to locate latency hotspots |
| x86_64 debug (kernel-rt-debug) | debugging - 64-bit debugging kernel | latency tracer enabled + other debug options - Used to debug RT kernel failures |
| x86_64 vanilla (kernel-rt-vanilla) | debugging - 64-bit base kernel | No RT features, used for comparison |
Included RPMs
This table lists the RPM packages included in RHEL-RT. It briefly describes why this package is included (replacing a standard RHEL5 version).
Legend:
- Name: package name
- Rationale: why is this included in RHEL-RT
- RT-specific? N = no = this is a generic RHEL5 fix. Y = yes = the package differs from standard RHEL5 and its maintenance stream (or is not applicable on a standard RHEL5 kernel).
- Required? Y = yes = this package is mandatory for correct realtime behavior. N = no = usage is optional.
| Name | Rationale | RT Specific? | Required? |
|---|---|---|---|
| kernel-rt | low latency and preemption functionality | Y | Y |
| rtctl | System startup script used to configure the default realtime scheduling priorities of kernel threads | Y | Y |
| dslimit | shell tool to run a command with a soft CPU limit | N | N |
| tuna | process and IRQ tuning GUI | N | N |
The following packages contain test and debugging programs associated with RHEL-RT.
| Name | Rationale | RT Specific? | Required? |
|---|---|---|---|
| kernel-rt-devel | headers and libraries for kernel development | Y | N |
| kernel-rt-debuginfo | symbols for profiling and debugging use, such as oprofile or systemtap | Y | N |
| kernel-rt-trace | RT kernel with tracing functions compiled in | Y | N - Provided as a diagnostic tool |
| kernel-rt-trace-devel | headers and libraries for development on trace kernel | Y | N - Provided as a diagnostic tool |
| kernel-rt-trace-debuginfo | symbols for profiling and tracing | Y | N - Provided as a diagnostic tool |
| kernel-rt-debug | RT kernel with debugging functions compiled in (slow) | Y | N - Provided as a diagnostic tool |
| kernel-rt-debug-devel | headers and libraries for development on debug kernel | Y | N - Provided as a diagnostic tool |
| kernel-rt-debug-debuginfo | symbols for profiling and tracing | Y | N - Provided as a diagnostic tool |
| kernel-rt-vanilla | Base kernel for comparisons | Y | N - Provided as a diagnostic tool |
| kernel-rt-vanilla-devel | headers and libraries for development on vanilla kernel | Y | N - Provided as a diagnostic tool |
| kernel-rt-vanilla-debuginfo | symbols for profiling and tracing | Y | N - Provided as a diagnostic tool |
| cyclictest | used to measure timer latency and validate realtime functionality (replaces a similar ancient utility called real-feel) | Y | N - Provided as a diagnostic tool |
| signaltest | used to measure signal passing latency and validate realtime functionality | Y | N - Provided as a diagnostic tool |
| rt-watchdog | when setting kernel and realtime application priorities it is possible to incorrectly elevate application processes too high. This can result in starvation of kernel threads - leading to unexpected or hung systems. This is a tool used to detect such hung systems and provide a means to break out and diagnose | Y | N - Provided as a diagnostic tool |
Post-installation Instructions
The following steps are necessary after the realtime packages have been installed:
Known Bugs
An up to date listing of known issues can be found here: RHEL-RT KnownBugs
RHEL5 Differences
This section describes ways in which RHEL-RT is different from standard RHEL5.
- PAE is configured in the x86 realtime kernel
- RHEL5 for x86 (32 bit) includes the following kernel variants (using example version numbers which will vary)
- kernel-2.6.18-8.el5 - this kernel does not have PAE (Physical Address Extention) enabled.
- kernel-PAE-2.6.18-8.el5 - this kernel does have PAE enabled - allowing it to access more than 4G of memory.
- In the RHEL-RT x86 kernel PAE is configured as we anticipate that most systems requiring RT capability will have at least 4G of memory. Note: the maximum memory supported on x86 systems is 16G (which is the same limit as standard RHEL5). Larger memory configurations are supported on the x86-64 kernel.
- RHEL5 for x86 (32 bit) includes the following kernel variants (using example version numbers which will vary)
- 3rd party kernel modules are incompatible with standard RHEL5
- Kernel modules are inherently specific to the kernel they are built for. Since the RHEL-RT kernel is substantially different from the standard RHEL5 kernel, kernel modules are incompatible. In other words, you can't simply take 3rd party driver modules from RHEL5 and use them as-is on RHEL-RT.
- The following are some example 3rd party drivers which ship against standard RHEL5 which do not currently have a RHEL-RT build: EMC Powerpath, NVidia graphics, advanced storage adapter configuration utilities from Qlogic & Emulex.
- Note, the user space syscall interface is compatible with standard RHEL5. These compatibility restrictions pertain only to kernel modules not supplied by Red Hat.
Caveats
/dev/rmem feature
Included in the RHEL-RT is a kernel module called rmem.ko. This module is not loaded by default, and is merely provided to meet the realtime Java conformance tests - specifically the TCK test in the JVM's RTSJ conformance suite. It is a RTSJ requirement of this conformance test that Java programs have direct access to physical memory. This /dev/rmem capability allows user applications to map any arbitrary memory region.
WARNING: By enabling direct memory access to Java applications, numerous normal system security mechanisms are bypassed, leaving the system more vulnearable to attacks by malicious users. For this reason, it is strongly suggested that this feature be exclusively used for RTSJ certification purposes only - not for production deployment.
The kernel module implementing this /dev/rmem capability is being provided only to meet the requirements of RTSJ conformance criteria. We have taken extra measures to ensure the capability is only enabled as a result of direct root system administrator action. The kernel module is by default not loaded. To further prevent accidental usage, the capability is disabled unless the following boot option is specified unprotected_address_spaces=1. As a result of explicitly loading the rmem.ko kernel module the kernel will have a tainted flag, suggesting that support will require reproducing any problems without the presence of the rmem.ko module.
There is another related boot option for this feature. the boot option is:
alloc_rtsj_mem.size=<memsize>
Where an example size is 1024 (bytes). The purpose of this boot option is to reserve contiguous physical kernel memory at boot time for later usage by the java runtime. This memory is allocated at boot time prior to the system memory becoming fragmented. The purpose of which is to avoid allocation failures for large contiguous memory.
In summary: don't use it.
