rdsinit(1)rdsinit(1)NAMErdsinit - RDS heap initialization utility
SYNOPSISrdsinit log data_seg
rdsinit log data_seg datalen saddr hlen slen nl chunk
rdsinit-f log data_seg datalen saddr hlen slen nl chunk
DESCRIPTIONrdsinit is a utility that constructs an initialized RDS heap in an RVM
segment. It is intended to create a structure that can be loaded by
rds_load_heap.
There are three different ways of using rdsinit. General users are
expected to use first two interactive modes, where users may supply
parameters for the rds heap interactively or on command line arguments.
However, in both cases, users will be asked interactively to confirm
their choice of parameters before rdsinit goes ahead to make any perma‐
nent change. These are the preferred modes of using rdsinit. Script
writers, however, may prefer to supply all the parameters on the com‐
mand line and no confirmation required for those parameters. This is
accomodate in the third mode where an additional switch of -f (firm) is
supplied on the command line.
In any case, two command-line parameters are always required: log and
data_seg. The former is the name of the RVM log, which must have pre‐
viously been initialized by rvmutl; the latter is the name of the data
segment that will be initialized with an RDS heap. If either is miss‐
ing, a command line error is printed. If the log has not been initial‐
ized, an RVM error will result. A short message indicating RVM ini‐
tialization succeeded is then printed. Both the log and data segment
can be regular files or raw partitions.
After the name of log and data segment, there are six other numeric
parameters required. They are summarized here and will be explained
one by one in the following paragraphs:
datalen
Length of data segment
saddr Starting address of rvm
hlen Heap region length
slen Static region length
nl Number of lists of free block
chunk Chunk size
While entering these six numeric parameters, either on command line on
via the interactive prompt, users may use numeric number in hexadeci‐
mal, decimal or even octal notation. Hexadecimal numbers are preceeded
by Ox, decimal numbers are preceeded by nothing and octal numbers are
preceded by 0.
Special note for long time rdsinit user: the old rdsinit automatically
assumed saddr, hlen and slen parameters supplied on command lines are
in hexidecimal and did not require the prefix 0x. This is no longer
true with this version of rdsinit.
Users specify the length of the data segment with the parameter
datalen. Again, old version of rdsinit did not require this parameter
if the data segment was a regular file and it existed already at the
time of running rdsinit. This special case is eliminated: length of
data segment must to be supplied in all circumstances.
Starting address of rvm, or saddr, is where heap and static region will
be mapped into virtual memory. Heap region is located right at the
starting address, while static region is located at starting address
plus heap region length. Users may need to have some knowledges of the
overall layout of the virtual memory use by the system before they can
make the right choice of starting address. For example, the starting
address of rvm must be much larger than the largest possible break
point of your application, and it should not be in conflict other uses
of virtual memory (such as use by shared libraries). It must also be
on a page boundary. In CMU, we use 0x20000000 (536870912) with Linux
and BSD44, or 0x70000000 (1879048192) with Mach. It is possible to
choose other values, but you have to choose them carefully.
Length of regions of heap and static are specified by the parameter
hlen and slen respectively. They both must be integral multiple of
pagesize of the system. Also, the combined length of the two regions
must be smaller than the length of data segment minus one extra page.
Note that the above three parameters: saddr, hlen, slen, are permanent.
They can't be changed without re-initizing (and brain-wiping) the data
segment.
The next two parameters: nl and chunk are related to underlying struc‐
ture of management of the heap. RDS uses the Quick Fit method for heap
allocation. In this method, free blocks are maintained by a number of
free lists, each list for one particular size of free blocks. Specifi‐
cally, there will be nl free lists, and each of them will have free
blocks of size 1..nl chunk respectively.
Chunk size must be integral multiple of sizeof(char *), and be at least
RDS_MIN_CHUNK_SIZE. Number of lists must be at least
RDS_MIN_FREE_LISTS. For example, a reasonable choice is to have
100 free list with chunk size 32 bytes.
Once all the parameters are chosen, rdsinit will ask user for confirma‐
tion before it goes ahead and make permanent change on the log and data
segment. Note in the following example that those numerical arguments
are presented in both hexidecimal and decimal (in bracket). It is safe
to quit at this point and no permanent changes will be made.
The following parameters are chosen:
length of data segment: 0xf5000 ( 1003520)
starting address of rvm: 0x20000000 ( 536870912)
heap len: 0xf0000 ( 983040)
static len: 0x4000 ( 16384)
nlists: 0x64 ( 100)
chunk size: 0x20 ( 32)
Do you agree with these parameters ? (y|n|q) y
If user supplied the -f (firm) switch on command line, this last con‐
firmation will not show up.
SEE ALSO
rds_init_heap (3), rds_load_heap (3), rds_zap_heap (3), rvm_create_seg‐
ment (3), rvm_load_segment (3), rvmutl (1)
AUTHOR
David C. Steere, created man page
Yui W. Lee, modified (Sept 1997)
rdsinit(1)
