RVM: Recoverable Virtual Memory, Release 1.3: RVM Segment Loader

5. RVM Segment Loader

Designed and programmed by David C. Steere

The RVM segment loader provides a mechanism that allows a load map to be created for a segment. Regions can then be mapped to specific virtual memory addresses or to virtual memory allocated by RVM in a single library call. There are only two library functions: rvm_create_segment and rvm_load_segment .

To use the segment loader, a segment header must be created by rvm_create_segment . The header, which occupies the first page of the segment, the load map for regions defined within the segment, and a version identifier so that rvm_load_segment can recognize suitable segments. All region lengths must be integral multiple of the page size of the machine, which is available as the macro RVM_PAGE_SIZE . Virtual memory addresses must be page-aligned.

The load map is prepared in a vector of descriptors for the desired regions (type rvm_region_def_t ). The descriptors specify just two parameters: the region length and the virtual memory address where the region is to be loaded. The offsets of the regions in the segment are assigned by rvm_create_segment . If pointers are included in the data, a fixed virtual memory address must be specified so that the loader will place the region there at each loading. If there are no pointers, the segment loader can be instructed to allocate space for the region by specifying an address of zero. The segment loader will make virtual memory addressable as necessary when loading.

The virtual memory address for the first region should be specified far enough beyond the applications break point so that the program can grow during development. Otherwise, there will have to be a way to modify the pointers or rebuild the structures.

The segment header establishes the load map for only that segment. If multiple segments are used, each must have its own header, and rvm_load_segment must be called for each.

The segment loader is used by the RDS allocator (see Chapter of RDS ) to automate loading of a persistent heap region and a statically allocated region. A utility program is available to create the segment header and initialize the heap so that it is easily loaded.

The header file giving all necessary definitions for the RVM segment loader is included in Appendix of C Declarations .

NAME

of C Declarations

rvm_create_segment - create segment header

SYNOPSIS

#include "rvm_segment.h

typedef struct
    {
    rvm_offset_t        offset;
    rvm_length_t        length;
    char                *vmaddr;
    }
rvm_region_def_t;

rvm_return_t rvm_create_segment (DevName, DevLength, options,
                                 nregions, regions)

char             *DevName;  /* name of heap segment */
rvm_offset_t     DevLength; /* length of heap raw partition */
rvm_options_t    *options;  /* optional pointer to an options record */
unsigned long    nregions;  /* number of region descriptors */
rvm_region_def_t *region_defs; /* pointer to array of region descriptors */

DESCRIPTION

rvm_create_segment is used to initialize the segment header with the region load map. The name of the file or partition for the segment is specified by DevName , and the length of the partition is specified in DevLength . If the segment is represented by a file, DevLength should be zero. Also, the file must exist and be at least one page long.

The parameter region_defs must point to an array of rvm_region_def_t descriptors, with one descriptor for each region to be loaded by rvm_load_segment . The descriptor array must be allocated and deallocated by application, and must be as long as the number of descriptors specified by nregions . The maximum number of regions that can be described in the header is limited by the page size of the machine, which is available as the macro RVM_PAGE_SIZE . If the number of regions requested by the parameter nregions causes the header to exceed page size, the error RVM_ENO_MEMORY will be returned.

Each rvm_region_def_t descriptor requires the regions virtual memory address and its length. The virtual memory address where the region will be loaded must be page-aligned. It can be specified as zero and, if so, will cause the loader to allocate virtual memory for the region. Regions containing pointers must specify an address to guarantee that they are loaded in the same place each time. The region length must be an integral multiple of the page size, or the error code RVM_ERANGE will be returned.

Regions are not allowed to overlap in virtual memory. If this condition is not met, the error code RVM_EVM_OVERLAP will be returned.

rvm_create_segment assigns space in the segment to the header and regions contiguously, beginning with the header at byte zero and with length equal to the page size. The regions are allocated next, in the order of their occurrence in the region_defs array. The offset is returned in the offset field of each descriptor.

The virtual memory specified in the descriptors does not have to be addressable when calling rvm_create_segment . Also, rvm_create_segment does not map or alter the applications data in the segment; only the first page of the segment for the header is affected.

Since it is an initialization function, rvm_create_segment performs no internal synchronization, so if there is a possibility of concurrent access to the segment, the application must do appropriate serialization.

An optional RVM options descriptor can be passed to rvm_create_segment if no log has been previously declared. RVM must be initialized before rvm_create_segment is called.

DIAGNOSTICS

RVM_SUCCESS: success
RVM_ERANGE: a region length is not page sized
RVM_EVM_OVERLAP: region mappings oberlap in virtual mapping
RVM_ENO_MEMORY: heap exhausted, or header cannot be allocated
RVM_EOPTIONS: invalid options record or pointer
RVM_ELOG: no log file has been specified
RVM_EINIT: RVM not initialized

SEE ALSO

rvm_load_segment (3) , rvm_map (3) , rds_zap_heap (3) , rds_load_heap (3) , rdsinit (1)

AUTHOR

David C. Steere

BUGS

Specification of region allocations with the offset field of the region descriptors is not allowed.

NAME

rvm_load_segment - automatically map regions of segment

SYNOPSIS

#include "rvm_segment.h

typedef struct
    {
    rvm_offset_t        offset;
    rvm_length_t        length;
    char                *vmaddr;
    }
rvm_region_def_t;

rvm_return_t rvm_load_segment (DevName, DevLength, options,
                               nregions, regions)

char             *DevName;  /* name of heap segment */
rvm_offset_t     DevLength; /* length of heap raw partition */
rvm_options_t    *options;  /* optional pointer to an options record */
unsigned long    *nregions;  /* number of region descriptors  */
rvm_region_def_t *regions[]; /* pointer to array of region descriptors  */

DESCRIPTION

rvm_load_segment is used to automatically map the regions of a segment prepared with rvm_create_segment . The name of the file or partition for the segment is specified by DevName , and the length of the partition is specified in DevLength . If the heap is in a file, DevLength should be zero.

rvm_load_segment will first to load the array of rvm_region_def_t descriptors contained in the segment header. If the segment header is not recognizable, the error RVM_ESEGMENT_HDR will be returned. A version identifier will also be checked, and if the version of the segment library that created the header does not match the version of the library linked with the application, the error RVM_EVERSION_SKEW will be returned. Otherwise, the address and length of the region descriptors array will be returned in regions and nregions , respectively. The header array must be deallocated by the application.

After the header is verified, each of the regions will be mapped via rvm_map . Allocation of virtual memory is done by rvm_load_segment , so the application must not attempt allocation, or the error RVM_ERANGE will result. Regions whose virtual memory address is non-zero will be automatically mapped to that address. Regions with zero virtual memory addresses will have space allocated by RVM, and the allocated address will be returned in the vmaddr field of the descriptor. After successful completion of rvm_load_segment , all data specified by the header is addressable to the application.

Regions are not allowed to overlap in either the segment or virtual memory. If this condition is not met, the error codes RVM_EOVERLAP or RVM_EVM_OVERLAP will be returned, as appropriate.

Since it is an initialization function, rvm_load_segment performs no internal synchronization, so if there is a possibility of concurrent access to the segment, the application must do appropriate serialization.

An optional RVM options descriptor can be passed to rvm_load_segment if no log has been previously declared. RVM must be initialized before rvm_load_segment is called.

DIAGNOSTICS

RVM_SUCCESS: success
RVM_ESEGMENT_HDR: segment header invalid
RVM_EVERSION_SKEW: segment header built with different version of segment loader library
RVM_EOVERLAP: segment regions overlap
RVM_EVM_OVERLAP: segment regions overlap in virtual memory
RVM_EOPTIONS: invalid options record or pointer
RVM_ENO_MEMORY: heap exhausted, or buffer cannot be allocated
RVM_ELOG: no log file has been specified or invalid file name
RVM_EINIT: RVM not initialized

Coda File System

5. RVM Segment Loader

of C Declarations