|
466
|
1 <chapter>
|
|
|
2 <title>Characteristics of Compiled Programs</title>
|
|
|
3
|
|
|
4 <section>
|
|
|
5 <title>The Object Code Module</title>
|
|
|
6 <para>
|
|
468
|
7 The compiler produces position-independent, reentrant 6809 code
|
|
|
8 in a standard OS-9 memory module format. The format of an executable
|
|
|
9 program module is shown below. Detailed descriptions of each
|
|
|
10 section of the module are given on following pages.
|
|
466
|
11 </para>
|
|
468
|
12 <informalfigure>
|
|
|
13 <screen>
|
|
618
|
14 Module Section
|
|
|
15 Offset Size (bytes)
|
|
466
|
16
|
|
468
|
17 +-------------------------------+
|
|
618
|
18 $00 ! !
|
|
|
19 ! Module Header ! 8
|
|
468
|
20 ! !
|
|
|
21 !-------------------------------!
|
|
618
|
22 $09 ! Execution Offset ! ---+ 2
|
|
|
23 !-------------------------------! !
|
|
|
24 $0B ! Permanent Storage Size ! ! 2
|
|
|
25 !-------------------------------! !
|
|
|
26 $0D ! Module Name ! !
|
|
|
27 ! . . . . . . . . . . . . . . . ! !
|
|
|
28 v v <--+
|
|
|
29 : Executable code :
|
|
|
30 : . . . . . . . . . . . . . . . :
|
|
|
31 : String Literals :
|
|
|
32 ^ ^
|
|
468
|
33 !-------------------------------!
|
|
618
|
34 ! Initializing Data Size ! 2
|
|
468
|
35 !-------------------------------!
|
|
618
|
36 v v
|
|
|
37 : Initializing Data :
|
|
|
38 ^ ^
|
|
|
39 !-------------------------------!
|
|
|
40 ! Data-text Reference Count ! 2
|
|
|
41 !-------------------------------!
|
|
468
|
42 v v
|
|
|
43 : Data-text Reference Offsets :
|
|
|
44 ^ ^
|
|
618
|
45 !-------------------------------!
|
|
|
46 ! Data-data Reference Count ! 2
|
|
|
47 !-------------------------------!
|
|
|
48 v v
|
|
|
49 : Data-data Reference Offsets :
|
|
|
50 ^ ^
|
|
|
51 !-------------------------------!
|
|
|
52 ! CRC Check Value ! 3
|
|
|
53 !-------------------------------!
|
|
468
|
54 </screen>
|
|
|
55 </informalfigure>
|
|
466
|
56 <section>
|
|
468
|
57 <title>Module Header</title>
|
|
466
|
58 <para>
|
|
468
|
59 This is a standard module header with the type/language byte set to
|
|
|
60 $11 (Program + 6809 Object Code), and the attribute/revision byte
|
|
|
61 set to $81 (Reentrant + 1).
|
|
466
|
62 </para>
|
|
|
63 </section>
|
|
530
|
64
|
|
|
65 <section>
|
|
|
66 <title>Execution Offset</title>
|
|
|
67 <para>
|
|
618
|
68 Used by OS-9 to locate where to start execution of the program.
|
|
530
|
69 </para>
|
|
|
70 </section>
|
|
|
71
|
|
|
72 <section>
|
|
|
73 <title>Storage Size</title>
|
|
|
74 <para>
|
|
618
|
75 Storage size is the initial default allocation of memory for data,
|
|
|
76 stack, and parameter area. For a full description of memory
|
|
|
77 allowcation, see the section entitled
|
|
|
78 <quote><link linkend="memorymanagement">Memory Management</link></quote> located
|
|
|
79 elsewhere in this manual.
|
|
530
|
80 </para>
|
|
|
81 </section>
|
|
|
82
|
|
|
83 <section>
|
|
|
84 <title>Module Name</title>
|
|
|
85 <para>
|
|
618
|
86 Module name is used by OS-9 to enter the module in the module
|
|
|
87 directory. The module name is followed by the edition byte encoded
|
|
|
88 in cstart. If this situation is not desired it may be overridden by
|
|
|
89 the -E= option in cc.
|
|
530
|
90 </para>
|
|
|
91 </section>
|
|
|
92
|
|
|
93 <section>
|
|
|
94 <title>Information</title>
|
|
|
95 <para>
|
|
618
|
96 Any strings preceded by the directive "info" in an assembly code
|
|
|
97 file will be placed here. A major use of this facility is to place
|
|
|
98 in the module the version number and/or a copyright notice. Note
|
|
|
99 that the '#asm' pre-compiler instruction may be used in a C source
|
|
|
100 file to enable the inclusion of this directive in the compiler-generated
|
|
|
101 assembly code file.
|
|
530
|
102 </para>
|
|
|
103 </section>
|
|
|
104
|
|
|
105 <section>
|
|
|
106 <title>Executable Code</title>
|
|
|
107 <para>
|
|
618
|
108 The machine code instructions of the program.
|
|
530
|
109 </para>
|
|
|
110 </section>
|
|
|
111
|
|
|
112 <section>
|
|
|
113 <title>String Literals</title>
|
|
|
114 <para>
|
|
618
|
115 Quoted string in the C source are placed here. They are in the
|
|
|
116 null-terminated form expected by the functions in the Standard
|
|
|
117 Library. NOTE: the definition of the C language assumes that
|
|
|
118 strings are in the DATA area and are therefore subject to alteration
|
|
|
119 without making the program non-reentrant. However, in order to avoid
|
|
|
120 the dublication of memory requirements which would be necesary if
|
|
|
121 they were to be in the data area, they are placed in the TEXT
|
|
|
122 (executable) section of the module. Putting the strings in the
|
|
|
123 executable section implies that no attempt should be made by a C
|
|
|
124 programmer to alter string literals. They should be copied out
|
|
|
125 first. The exception that proves the rule is the initialization of
|
|
|
126 an array of type char like this:
|
|
|
127 <programlisting>
|
|
|
128 char message[] = "Hello world\n";
|
|
|
129 </programlisting>
|
|
|
130 The string will be found in the array 'message' in the data area and
|
|
|
131 can be altered.
|
|
530
|
132 </para>
|
|
|
133 </section>
|
|
|
134
|
|
|
135 <section>
|
|
|
136 <title>Initializing Data and its Size</title>
|
|
|
137 <para>
|
|
618
|
138 If a C program contains initializers, the data for the initial
|
|
|
139 values of the variables is placed in this section. The definition
|
|
|
140 of C states that all uninitialized global and static variables have
|
|
|
141 the value zero when the program starts running, so the startuo
|
|
|
142 rougtine of each C program first copies the data from the module into
|
|
|
143 the data area and then clears the rest of the data memory to nulls.
|
|
530
|
144 </para>
|
|
|
145 </section>
|
|
|
146
|
|
|
147 <section>
|
|
|
148 <title>Data References</title>
|
|
|
149 <para>
|
|
618
|
150 No absolute addresses are known at compile time under OS-9, so where
|
|
|
151 there are pointer values in the initializating data, they must be
|
|
|
152 adjusted at run time so that they reflect the absolute values at
|
|
|
153 that time. The startup routine uses the two data reference tables
|
|
|
154 to locate the values that need alteration and adjusts them by the
|
|
|
155 absolute values of the bases of the executable code and data
|
|
|
156 respectively.
|
|
|
157 </para>
|
|
|
158 <para>
|
|
|
159 For example, suppose there are the following statements in the
|
|
|
160 program being compiled:
|
|
|
161 <programlisting>
|
|
|
162 char *p = "I'm a string!";
|
|
|
163 char **q = &p;
|
|
|
164 </programlisting>
|
|
|
165 These declarations tell the compiler that there is to be a char
|
|
|
166 pointer variable, 'p', whose initial value is the address of the
|
|
|
167 string and a pointer to a char pointer, 'q', whose initial value is
|
|
|
168 the address of 'p'. The variables must be in the DATA section of
|
|
|
169 memory at run time because they are potentially alterable, but
|
|
|
170 absolute addresses are not known until run time, so the values that
|
|
|
171 'p' and 'q' must have are not known at compile time. The string
|
|
|
172 will be placed by the compiler in the TEXT section and will not be
|
|
|
173 copied out to DATA memory by the startup routine. The initializing
|
|
|
174 data section of the program module will contain entries for 'p' and
|
|
|
175 'q'. They will have as values the offsets of the string from the
|
|
|
176 base of the TEXT section and the offset of the location of 'p' from
|
|
|
177 the base of the DATA section respectively.
|
|
|
178 </para>
|
|
|
179 <para>
|
|
|
180 The startup routine will first copy all the entries in the initializing
|
|
|
181 data section into their allotted places in the DATA section.
|
|
|
182 Then it will scan the data-text reference table for the offsets of
|
|
|
183 values that need to have the addresses of the base of the TEXT
|
|
|
184 section added to them. Among these will be the "p" which, after
|
|
|
185 updating, will point to the string which is in the TEXT section.
|
|
|
186 Similarly, after a scan of the data-data references, "q" will point
|
|
|
187 to (contain the absolute of) "p".
|
|
530
|
188 </para>
|
|
|
189 </section>
|
|
|
190 </section>
|
|
|
191
|
|
618
|
192 <section id="memorymanagement">
|
|
530
|
193 <title>Memory Management</title>
|
|
|
194 <para>
|
|
|
195 The C compiler and its support programs have default conditions
|
|
|
196 such that the average programmer need not be concerned with details
|
|
|
197 of memory management. However, there are situations where advanced
|
|
|
198 programmers may wish to tailor the storage allocation of a program
|
|
|
199 for special situations. The following information explains in
|
|
|
200 detail how a C program's data area is allocated and used.
|
|
|
201 </para>
|
|
|
202
|
|
|
203 <section>
|
|
|
204 <title>Typical C Program Memory Map</title>
|
|
|
205 <para>
|
|
618
|
206 A storage area is allocated by OS-9 when the C program is executed.
|
|
|
207 The layout of this memory is as follows:
|
|
|
208 </para>
|
|
|
209 <screen>
|
|
|
210 high addresses
|
|
|
211 | | <- SBRK() adds more
|
|
|
212 | | memory here
|
|
|
213 | |
|
|
|
214 !------------------! <- memend
|
|
|
215 ! parameters !
|
|
|
216 !------------------!
|
|
|
217 ! !
|
|
|
218 Current stack | stack | <- sp register
|
|
|
219 reservation -> !..................!
|
|
|
220 ! v !
|
|
|
221 ! ! <- standard I/O buffers
|
|
|
222 ! free memory ! allocated here
|
|
|
223 Current top ! !
|
|
|
224 of data -> !........^.........! <- IBRK() changes this
|
|
|
225 ! ! memory bound upward
|
|
|
226 ! requested memory !
|
|
|
227 !------------------! <-- end
|
|
|
228 ! uninitialized !
|
|
|
229 ! data !
|
|
|
230 !------------------! <-- edata
|
|
|
231 ! initialized !
|
|
|
232 ! data !
|
|
|
233 !------------------!
|
|
|
234 ^ ! direct page !
|
|
|
235 dpsiz ! variables !
|
|
|
236 v +------------------+ <-- y,dp registers
|
|
|
237 low addresses
|
|
|
238 </screen>
|
|
|
239 <para>
|
|
|
240 The overall size of this memory area is defined by the "storage
|
|
|
241 size" value stored in the program's module header. This can be
|
|
|
242 overridden to assign the program additional memory if the OS-9 Shell
|
|
|
243 "#" command is used.
|
|
|
244 </para>
|
|
|
245 <para>
|
|
|
246 The parameter area is where the parameter string from the
|
|
|
247 calling process (typically the OS-9 Shell) is placed by the system.
|
|
|
248 The initializing routine for C programs converts the parameters into
|
|
|
249 null-terminated strings and makes pointers to them available to
|
|
|
250 'main()' via 'argc' and 'argv'.
|
|
|
251 </para>
|
|
|
252 <para>
|
|
|
253 The stack area is the currently reserved memory for exclusive
|
|
|
254 use of the stack. As each C function is entered, a routine in the
|
|
|
255 system interface is called to reserve enough stack space for the use
|
|
|
256 of the function with an addition of 64 bytes. The 64 bytes are for
|
|
|
257 the use of user-written assembly code functions and/or the system
|
|
|
258 interface and/or arithmetic routines. A record is kept of the
|
|
|
259 lowest address so far granted for the stack. If the area requested
|
|
|
260 would not bring this lower then the C function is allowed to
|
|
|
261 proceed. If the new lower limit would mean that the stack area
|
|
|
262 would overlap the data area, the program stops with the message:
|
|
|
263 <screen>
|
|
|
264 **** STACK OVERFLOW ****
|
|
|
265 </screen>
|
|
|
266 on the standard error output. Otherwise, the new lower limit is
|
|
|
267 set, and the C function resumes as before.
|
|
|
268 </para>
|
|
|
269 <para>
|
|
|
270 The direct page variables area is where variables reside
|
|
|
271 that have been defined with the storage class 'direct' in the C
|
|
|
272 source code or in the 'direct' segment in assembly code source.
|
|
|
273 Notice that the size of this area is always at least one byte (to
|
|
|
274 ensure that no pointer to a variable can have the value NULL or 0)
|
|
|
275 and that it is not necessarily 256 bytes.
|
|
|
276 </para>
|
|
|
277 <para>
|
|
|
278 The uninitialized data area is where the remainder of the
|
|
|
279 uninitialized program variables reside. These two areas are, in
|
|
|
280 fact, cleared to all zeros by the program entry routine. The
|
|
|
281 initialized data area is where the initialized variables of the
|
|
|
282 program reside. There are two globally defined values which may be
|
|
|
283 referred to: 'edata' and 'end', which are the addresses of one byte
|
|
|
284 higher than the initialized data and one byte higher than the
|
|
|
285 uninitialized data respectively. Note that these are not variables;
|
|
|
286 the values are accesses in C by using the '&' operator as in:
|
|
|
287 <programlisting>
|
|
|
288 high = &end;
|
|
|
289 low = &edata;
|
|
|
290 </programlisting>
|
|
|
291 and in assembler:
|
|
|
292 <programlisting>
|
|
|
293 leax end,y
|
|
|
294 stx high,y
|
|
|
295 </programlisting>
|
|
|
296 The Y register points to the base of the data area and variables are
|
|
|
297 addresses using Y-offset indexed instructions.
|
|
|
298 </para>
|
|
|
299 <para>
|
|
|
300 When the program starts running, the remaining memory is
|
|
|
301 assigned to the "free" area. A program may call "ibrk()" to
|
|
|
302 request additional working memory (initialized to zeros) from the
|
|
|
303 free memory area. Alternatively, more memory can be dynamically
|
|
|
304 obtained using the "sbrk()" which requests additional memory from
|
|
|
305 the operating system and returns its lower bound. If this fails
|
|
|
306 because OS-9 refuses to grant more memory for any reason "sbrk()"
|
|
|
307 will return -1.
|
|
530
|
308 </para>
|
|
|
309 </section>
|
|
|
310
|
|
|
311 <section>
|
|
|
312 <title>Compile Time Memory Allocation</title>
|
|
|
313 <para>
|
|
618
|
314 If not instructed otherwise, the linker will automatically
|
|
|
315 allocate 1k bytes more than the total size of the program's
|
|
|
316 variables and strings. This size will normally be adequate to cover
|
|
|
317 the parameter area, stack requirements, and Standard Library file
|
|
|
318 buffers. The allocation size may be altered when using the compiler
|
|
|
319 by using the "-m" option on the command line. The memory
|
|
|
320 requirements may be stated in pages, for example,
|
|
|
321 <programlisting>
|
|
|
322 cc prg.c -m=2
|
|
|
323 </programlisting>
|
|
|
324 which allocates 512 bytes extra, or in kilobytes, for example:
|
|
|
325 <programlisting>
|
|
|
326 cc prg.c -m=10k
|
|
|
327 </programlisting>
|
|
|
328 The linker will ignore the request if the size is less than 256 bytes.
|
|
530
|
329 </para>
|
|
565
|
330 <para>
|
|
|
331 The following rules can serve as a rough guide to estimate how
|
|
|
332 much memory to specify:
|
|
|
333 </para>
|
|
|
334 <orderedlist>
|
|
|
335 <listitem><para>
|
|
|
336 The parameter area should be large enough for any anticipated
|
|
|
337 command line string.
|
|
|
338 </para></listitem>
|
|
|
339 <listitem><para>
|
|
|
340 The stack should not be less than 128 bytes and should take
|
|
|
341 into account the depth of function calling chains and any
|
|
|
342 recursion.
|
|
|
343 </para></listitem>
|
|
|
344 <listitem><para>
|
|
|
345 All function arguments and local variables occupy stack space
|
|
|
346 and each function entered needs 4 bytes more for the return
|
|
|
347 address and temporary storage of the calling function's register
|
|
|
348 variable.
|
|
|
349 </para></listitem>
|
|
|
350 <listitem><para>
|
|
|
351 Free memory is requested by the Standard Library I/O
|
|
|
352 functions for buffers at the rate of 256 bytes per accessed
|
|
|
353 file. The does not apply to the lower level service request I/O
|
|
|
354 functions such as "open()", "read()" or "write()" not to
|
|
|
355 "stderr" which is always un-buffered, but it does apply to both
|
|
|
356 "stdin" and "stdout" (see the Standard Library documentation).
|
|
|
357 </para></listitem>
|
|
|
358 </orderedlist>
|
|
|
359 <para>
|
|
|
360 A good method for getting a feel for how much memory is
|
|
|
361 needed by your program is to allow the linker to set the memory size
|
|
|
362 to its usually conservative value. Then, if the program runs
|
|
|
363 with a variety of input satisfactorily but memory is limited on the
|
|
|
364 system, try reducing the allocation at the next compilation. If a
|
|
|
365 stack overflow occurs or an "ibrk()" call returns -1, then try
|
|
|
366 increasing the memory next time. You cannot damage the system by
|
|
|
367 getting it wrong, but data may be lost if the program runs out of
|
|
|
368 space at a crucial time. It pays to be in error on the generous
|
|
|
369 side.
|
|
|
370 </para>
|
|
530
|
371 </section>
|
|
468
|
372 </section>
|
|
466
|
373 </chapter>
|
