Sophie: coda-doc-5.2.0-4mdk noarch

coda-doc-5.2.0-4mdk.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>RVM: Recoverable Virtual Memory, Release 1.3: RVM Segment Loader</TITLE>
 <LINK HREF="rvm_manual-6.html" REL=next>
 <LINK HREF="rvm_manual-4.html" REL=previous>
 <LINK HREF="rvm_manual.html#toc5" REL=contents>
</HEAD>
<BODY>
<A HREF="rvm_manual-6.html">Next</A>
<A HREF="rvm_manual-4.html">Previous</A>
<A HREF="rvm_manual.html#toc5">Contents</A>
<HR>
<H2><A NAME="RVMseg"></A> <A NAME="s5">5. RVM Segment Loader</A></H2>

<P><EM>Designed and programmed by David C. Steere</EM>
<P>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: <CODE>rvm_create_segment</CODE> and <CODE>rvm_load_segment</CODE>.
<P>To use the segment loader, a segment header must be created
by <CODE>rvm_create_segment</CODE>.  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 <CODE>rvm_load_segment</CODE> can
recognize suitable segments.  
All region lengths must be integral multiple of the
page size of the machine, which is available as the macro
<CODE>RVM_PAGE_SIZE</CODE>.  Virtual memory addresses must be page-aligned.
<P>The load map is prepared in a vector of descriptors for the desired
regions (type <CODE>rvm_region_def_t</CODE>).  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
<CODE>rvm_create_segment</CODE>. 
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.
<P>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.
<P>The segment header establishes the load map for only that segment.
If multiple segments are used, each must have its own header, and 
<CODE>rvm_load_segment</CODE> must be called for each.
<P>The segment loader is used by the RDS allocator (see Chapter 
<A HREF="rvm_manual-6.html#RDS">of RDS</A>) 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.
<P>The header file giving all necessary definitions for the RVM segment
loader is included in Appendix 
<A HREF="rvm_manual-10.html#RVMheaders">of C Declarations</A>.
<P><HR>
<P>
<P>
NAME 
<H3><A HREF="rvm_manual-10.html#RVMheaders">of C Declarations</A></H3>

<P>rvm_create_segment - create segment header
<P>
SYNOPSIS
<H3></H3>

<P>
<PRE>
#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 */
</PRE>
<P>
DESCRIPTION
<H3></H3>

<P><CODE>rvm_create_segment</CODE> 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 <CODE>DevName</CODE>, and the
length of the partition is specified in <CODE>DevLength</CODE>.  If the segment
is represented by a file, <CODE>DevLength</CODE> should be zero.  Also, the
file must exist and be at least one page long.
<P>The parameter <CODE>region_defs</CODE> must point to an array of
<CODE>rvm_region_def_t</CODE> descriptors, with
one descriptor for each region to be loaded by
<CODE>rvm_load_segment</CODE>.  
The descriptor array must be allocated and deallocated by application,
and must be as long as the number of descriptors specified by
<CODE>nregions</CODE>.  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 <CODE>RVM_PAGE_SIZE</CODE>.  If the number of regions
requested by the parameter <CODE>nregions</CODE> causes the header to exceed
page size, the error <CODE>RVM_ENO_MEMORY</CODE> will be returned.
<P>Each <CODE>rvm_region_def_t</CODE> 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 <CODE>RVM_ERANGE</CODE> will be returned.
<P>Regions are not allowed to overlap in virtual
memory.  If this condition is not met, the error code
<CODE>RVM_EVM_OVERLAP</CODE> will be returned.
<P><CODE>rvm_create_segment</CODE> 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 <CODE>region_defs</CODE> array.  The offset is
returned in the <CODE>offset</CODE> field of each descriptor.
<P>The virtual memory specified in the descriptors does not
have to be addressable when calling <CODE>rvm_create_segment</CODE>.
Also, <CODE>rvm_create_segment</CODE> does not map or alter the applications
data in the segment; only the first page of the segment for the header
is affected.
<P>Since it is an initialization function, <CODE>rvm_create_segment</CODE>
performs no internal synchronization, so if there 
is a possibility of concurrent access to the segment,
the application must do appropriate serialization.
<P>An optional RVM options descriptor can be passed to
<CODE>rvm_create_segment</CODE> if no log has been previously declared.
RVM must be initialized before <CODE>rvm_create_segment</CODE> is called.
<P>
<P>
DIAGNOSTICS
<H3></H3>

<P>
<DL>
<DT><B>RVM_SUCCESS</B><DD><P>success
<DT><B>RVM_ERANGE</B><DD><P>a region length is not page sized
<DT><B>RVM_EVM_OVERLAP</B><DD><P>region mappings oberlap in virtual mapping
<DT><B>RVM_ENO_MEMORY</B><DD><P>heap exhausted, or header cannot be allocated
<DT><B>RVM_EOPTIONS</B><DD><P>invalid options record or pointer
<DT><B>RVM_ELOG</B><DD><P>no log file has been specified
<DT><B>RVM_EINIT</B><DD><P>RVM not initialized
</DL>
<P>
SEE ALSO
<H3></H3>

<P><CODE>rvm_load_segment (3)</CODE>, <CODE>rvm_map (3)</CODE>, <CODE>rds_zap_heap (3)</CODE>,
<CODE>rds_load_heap (3)</CODE>, <CODE>rdsinit (1)</CODE>
<P>
<P>
AUTHOR
<H3></H3>

<P>David C. Steere
<P>
<P>
BUGS
<H3></H3>

<P>Specification of region allocations with the <CODE>offset</CODE> field of the
region descriptors is not allowed.
<P>
<P>
<HR>NAME 
<H3></H3>

<P>rvm_load_segment - automatically map regions of segment
<P>
SYNOPSIS
<H3></H3>

<P>
<PRE>
#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  */
</PRE>
<P>
DESCRIPTION
<H3></H3>

<P><CODE>rvm_load_segment</CODE> is used to automatically map the regions of a
segment prepared with <CODE>rvm_create_segment</CODE>.  The name of the file or
partition for the segment is specified by <CODE>DevName</CODE>, and the
length of the partition is specified in <CODE>DevLength</CODE>.  If the heap 
is in a file, <CODE>DevLength</CODE> should be zero.
<P><CODE>rvm_load_segment</CODE> will first to load the
array of <CODE>rvm_region_def_t</CODE> descriptors contained in the segment
header.  If the segment header is not recognizable, the error
<CODE>RVM_ESEGMENT_HDR</CODE> 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 <CODE>RVM_EVERSION_SKEW</CODE> will be returned.
Otherwise, the address and length of the region descriptors array will
be returned in regions and <CODE>nregions</CODE>, respectively.
The header array must be deallocated by the application.
<P>After the header is verified, each of the regions will be mapped via
<CODE>rvm_map</CODE>.  Allocation of virtual memory is done by
<CODE>rvm_load_segment</CODE>, so the application must not attempt allocation, or
the error <CODE>RVM_ERANGE</CODE> 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 <CODE>vmaddr</CODE> field of the descriptor.  
After successful completion of
<CODE>rvm_load_segment</CODE>, all data specified by the header is addressable
to the application.
<P>Regions are not allowed to overlap in either the segment or virtual
memory.  If this condition is not met, the error codes
<CODE>RVM_EOVERLAP</CODE> or <CODE>RVM_EVM_OVERLAP</CODE> will be returned, as
appropriate.
<P>Since it is an initialization function, <CODE>rvm_load_segment</CODE>
performs no internal synchronization, so if there 
is a possibility of concurrent access to the segment,
the application must do appropriate serialization.
<P>An optional RVM options descriptor can be passed to
<CODE>rvm_load_segment</CODE> if no log has been previously declared.
RVM must be initialized before <CODE>rvm_load_segment</CODE> is called.
<P>
<P>
DIAGNOSTICS
<H3></H3>

<P>
<DL>
<DT><B>RVM_SUCCESS</B><DD><P>success
<DT><B>RVM_ESEGMENT_HDR</B><DD><P>segment header invalid
<DT><B>RVM_EVERSION_SKEW</B><DD><P>segment header built with different version of
segment loader library
<DT><B>RVM_EOVERLAP</B><DD><P>segment regions overlap
<DT><B>RVM_EVM_OVERLAP</B><DD><P>segment regions overlap in virtual memory
<DT><B>RVM_EOPTIONS</B><DD><P>invalid options record or pointer
<DT><B>RVM_ENO_MEMORY</B><DD><P>heap exhausted, or buffer cannot be allocated
<DT><B>RVM_ELOG</B><DD><P>no log file has been specified or invalid file name
<DT><B>RVM_EINIT</B><DD><P>RVM not initialized
</DL>
<P>
SEE ALSO
<H3></H3>

<P><CODE>rvm_create_segment (3)</CODE>, <CODE>rvm_map (3)</CODE>, <CODE>rds_load_heap (3)</CODE>
<P>
<P>
AUTHOR
<H3></H3>

<P>David C. Steere
<P>
<P>
<HR>
<HR>
<A HREF="rvm_manual-6.html">Next</A>
<A HREF="rvm_manual-4.html">Previous</A>
<A HREF="rvm_manual.html#toc5">Contents</A>
</BODY>
</HTML>