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