1rdsinit(1) General Commands Manual rdsinit(1)
2
6 rdsinit - RDS heap initialization utility
7
9 rdsinit log data_seg
10 rdsinit log data_seg datalen saddr hlen slen nl chunk
12 rdsinit -f log data_seg datalen saddr hlen slen nl chunk
14
16 rdsinit is a utility that constructs an initialized RDS heap in an RVM
17 segment. It is intended to create a structure that can be loaded by
18 rds_load_heap.
19 There are three different ways of using rdsinit. General users are
21 expected to use first two interactive modes, where users may supply
22 parameters for the rds heap interactively or on command line arguments.
23 However, in both cases, users will be asked interactively to confirm
24 their choice of parameters before rdsinit goes ahead to make any perma‐
25 nent change. These are the preferred modes of using rdsinit. Script
26 writers, however, may prefer to supply all the parameters on the com‐
27 mand line and no confirmation required for those parameters. This is
28 accomodate in the third mode where an additional switch of -f (firm) is
29 supplied on the command line.
30 In any case, two command-line parameters are always required: log and
32 data_seg. The former is the name of the RVM log, which must have pre‐
33 viously been initialized by rvmutl; the latter is the name of the data
34 segment that will be initialized with an RDS heap. If either is miss‐
35 ing, a command line error is printed. If the log has not been initial‐
36 ized, an RVM error will result. A short message indicating RVM ini‐
37 tialization succeeded is then printed. Both the log and data segment
38 can be regular files or raw partitions.
39 After the name of log and data segment, there are six other numeric
41 parameters required. They are summarized here and will be explained
42 one by one in the following paragraphs:
43 datalen
45 Length of data segment
46 saddr Starting address of rvm
48 hlen Heap region length
50 slen Static region length
52 nl Number of lists of free block
54 chunk Chunk size
56 While entering these six numeric parameters, either on command line on
58 via the interactive prompt, users may use numeric number in hexadeci‐
59 mal, decimal or even octal notation. Hexadecimal numbers are preceeded
60 by Ox, decimal numbers are preceeded by nothing and octal numbers are
61 preceded by 0.
62 Special note for long time rdsinit user: the old rdsinit automatically
64 assumed saddr, hlen and slen parameters supplied on command lines are
65 in hexidecimal and did not require the prefix 0x. This is no longer
66 true with this version of rdsinit.
67 Users specify the length of the data segment with the parameter
69 datalen. Again, old version of rdsinit did not require this parameter
70 if the data segment was a regular file and it existed already at the
71 time of running rdsinit. This special case is eliminated: length of
72 data segment must to be supplied in all circumstances.
73 Starting address of rvm, or saddr, is where heap and static region will
75 be mapped into virtual memory. Heap region is located right at the
76 starting address, while static region is located at starting address
77 plus heap region length. Users may need to have some knowledges of the
78 overall layout of the virtual memory use by the system before they can
79 make the right choice of starting address. For example, the starting
80 address of rvm must be much larger than the largest possible break
81 point of your application, and it should not be in conflict other uses
82 of virtual memory (such as use by shared libraries). It must also be
83 on a page boundary. In CMU, we use 0x20000000 (536870912) with Linux
84 and BSD44, or 0x70000000 (1879048192) with Mach. It is possible to
85 choose other values, but you have to choose them carefully.
86 Length of regions of heap and static are specified by the parameter
88 hlen and slen respectively. They both must be integral multiple of
89 pagesize of the system. Also, the combined length of the two regions
90 must be smaller than the length of data segment minus one extra page.
91 Note that the above three parameters: saddr, hlen, slen, are permanent.
93 They can't be changed without re-initizing (and brain-wiping) the data
94 segment.
95 The next two parameters: nl and chunk are related to underlying struc‐
97 ture of management of the heap. RDS uses the Quick Fit method for heap
98 allocation. In this method, free blocks are maintained by a number of
99 free lists, each list for one particular size of free blocks. Specifi‐
100 cally, there will be nl free lists, and each of them will have free
101 blocks of size 1..nl chunk respectively.
102 Chunk size must be integral multiple of sizeof(char *), and be at least
104 RDS_MIN_CHUNK_SIZE. Number of lists must be at least
105 RDS_MIN_FREE_LISTS. For example, a reasonable choice is to have
106 100 free list with chunk size 32 bytes.
107 Once all the parameters are chosen, rdsinit will ask user for confirma‐
109 tion before it goes ahead and make permanent change on the log and data
110 segment. Note in the following example that those numerical arguments
111 are presented in both hexidecimal and decimal (in bracket). It is safe
112 to quit at this point and no permanent changes will be made.
113 The following parameters are chosen:
115 length of data segment: 0xf5000 ( 1003520)
116 starting address of rvm: 0x20000000 ( 536870912)
117 heap len: 0xf0000 ( 983040)
118 static len: 0x4000 ( 16384)
119 nlists: 0x64 ( 100)
120 chunk size: 0x20 ( 32)
121 Do you agree with these parameters ? (y|n|q) y
122 If user supplied the -f (firm) switch on command line, this last con‐
125 firmation will not show up.
126
128 rds_init_heap (3), rds_load_heap (3), rds_zap_heap (3), rvm_create_seg‐
129 ment (3), rvm_load_segment (3), rvmutl (1)
130
132 David C. Steere, created man page
133 Yui W. Lee, modified (Sept 1997)
135 rdsinit(1)