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
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
success
a region length is not page sized
region mappings oberlap in virtual mapping
heap exhausted, or header cannot be allocated
invalid options record or pointer
no log file has been specified
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.
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
success
segment header invalid
segment header built with different version of segment loader library
segment regions overlap
segment regions overlap in virtual memory
invalid options record or pointer
heap exhausted, or buffer cannot be allocated
no log file has been specified or invalid file name
RVM not initialized
SEE ALSO
rvm_create_segment (3)
,
rvm_map (3)
,
rds_load_heap (3)
AUTHOR
David C. Steere