ChorusOS 5.0 Application Developer's Guide

System configuration

Before beginning to program and run processes that will use the hot restart feature, you must update and configure your system for hot restart. System configuration for hot restart involves the following steps:

Including the necessary ChorusOS optional features in your system
Ensuring that the settings for the tunable parameters used by the hot restart feature are suitable for your system.

These steps are described in the following sections.

Features

To incorporate hot restart into your ChorusOS system, use the ews graphical tool or the configurator(1CC) command line utility to include the following optional features in your system profile:

HOT_RESTART. This feature exports the hot restart API and restart mechanism.
LAPSAFE and LAPBIND. These features provide the necessary support for the HOT_RESTART feature.

Memory Requirements and Design Constraints

The HOT_RESTART feature implements persistent memory as a portion of the random access memory (RAM) on the target device. Although the persistent memory bank does not use virtual memory or swapping, HOT_RESTART is compatible with all three main memory models: flat, protected, and virtual.

The size of the persistent memory bank is defined in bytes by the system tunable parameter, pmm.rambankSize. The value of this parameter is static and cannot be modified while the system is running. In addition, because the RAM persistent memory bank does not use virtual memory or swapping, objects in persistent memory are locked in memory until they are freed. For these two reasons, it is important to ensure that pmm.rambankSize is set to a value realistic for the amount of data likely to be stored in persistent memory at any given time.

A portion of space reserved for an object in the persistent memory bank is known as a persistent memory block. A block is a contiguous set of memory pages, which means that the size of a block is always a multiple of the page size. For more information on the page size relevant to your platform, see the vmPageSize(2K) man page.

For each restartable process that is running, the system stores the following data in persistent memory:

The text and initialized data which were loaded into memory from stable storage. This is known as the process image. The process image occupies a single block of persistent memory.
The executed text, initialized data, and BSS (data initialized to zero), from which the process is running. This is known as the executing image of the process. The executing image occupies two blocks of persistent memory: one block for the text and one block for the data. The heap and stack for the executing process are stored in non-persistent memory.

The persistent memory blocks used to store the process image and executing image are freed only when the originating group terminates cleanly. Note that this may be some time after the process itself has terminated. The process can also allocate its own blocks of persistent memory to store run-time data while executing.

Although it can be difficult to predict the likely required value of pmm.rambankSize in the early stages of the development cycle, the following rule of thumb, derived from the previously mentioned statements, may be of use to developers at the system design stage:

Restartable processes require an absolute minimum of twice their size in persistent memory. This minimum memory portion will accommodate the process's process image and executing image (although it does not enable rounding of memory block sizes to the nearest page).
The process can also allocate additional memory. Therefore, pmm.rambankSize should be greater than twice the combined size of the restartable processes expected to run simultaneously.

Note -

Sharing persistent memory blocks between user processes, or between user and supervisor processes is not supported. Persistent memory blocks can only be shared between supervisor processes.

The default value of the pmm.rambankSize tunable parameter is one megabyte.

Tunable Parameters

The HOT_RESTART feature uses a number of system tunable parameters. Each parameter has a default value which can serve as a guideline, and is generally suitable for getting started with hot restart programming. All tunable parameters are static -- they cannot be modified while the system is running.

Two parameters define the limits for persistent memory occupation of the system's persistent memory bank:

pmm.rambankSize is the maximum amount of persistent memory available in the system (in bytes). The default value is one megabyte (0x100000). See the previous section for guidelines on setting this parameter to suit your system. To run the hot restart demonstration program, you will need to increase the value of this parameter to four megabytes (0x400000).
pmm.maxBlocks is the maximum number of recorded persistent memory blocks which can be allocated in the persistent memory bank. A block is a variable-sized number of contiguous pages of RAM. Each time a process (supervisor or user) issues a request to store a piece of data in persistent memory, a block of the appropriate size, rounded up to the nearest whole page, is allocated. The default value is 30.

Two parameters control the maximum number of restartable processes and restart groups permitted in a system:

hrCtrl.maxprocesses is the maximum number of hot restartable processes which can be registered in the system. A process is registered in the system when it is first run, and remains registered until all processes in its group have terminated cleanly. The default value is 32. If hrCtrl.maxprocesses is greater than 65536, this value will be used instead.
hrCtrl.maxGroups is the maximum number of restart groups that can be present in the system at the same time. Its default value is 32.

Two parameters define the system's restart policy (see "Site Restart"). These parameters are fairly sensitive -- different values can produce very different behavior in the system. The system manages a restart counter for each restart group. Each time a group is restarted, the system increases its restart counter by one.

hrCtrl.interval is the frequency with which a group's restart counter is decreased, in seconds. Every hrCtrl.interval seconds, the system decreases the group's restart counter by one (until the counter reaches zero). The default value for hrCtrl.interval is three seconds.
hrCtrl.maxBadness is the maximum value a group's restart counter can reach before it triggers a site restart. In other words, when a group's restart counter reaches this value, a site restart is automatically performed. The default value is 25. If set to zero, the system will never trigger a site restart.

Building the System Image

After updating your system's features for hot restart and setting the tunable parameters to suit your requirements, you are ready to build the system image.

To run the examples and hot restart demonstration, include the examples directory and X11 library in your system build paths (if they are not already included). For information on building a system image for your particular target platform, see the corresponding document in the ChorusOS 5.0 Target Platform Collection.

After the system image has been correctly built, copy the image to your boot server and reboot the target machine. You are now ready to begin programming and running applications that can use the hot restart feature.