1 | This is Info file gcc.info, produced by Makeinfo version 1.67 from the |
---|
2 | input file gcc.texi. |
---|
3 | |
---|
4 | This file documents the use and the internals of the GNU compiler. |
---|
5 | |
---|
6 | Published by the Free Software Foundation 59 Temple Place - Suite 330 |
---|
7 | Boston, MA 02111-1307 USA |
---|
8 | |
---|
9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
---|
10 | Free Software Foundation, Inc. |
---|
11 | |
---|
12 | Permission is granted to make and distribute verbatim copies of this |
---|
13 | manual provided the copyright notice and this permission notice are |
---|
14 | preserved on all copies. |
---|
15 | |
---|
16 | Permission is granted to copy and distribute modified versions of |
---|
17 | this manual under the conditions for verbatim copying, provided also |
---|
18 | that the sections entitled "GNU General Public License," "Funding for |
---|
19 | Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
---|
20 | included exactly as in the original, and provided that the entire |
---|
21 | resulting derived work is distributed under the terms of a permission |
---|
22 | notice identical to this one. |
---|
23 | |
---|
24 | Permission is granted to copy and distribute translations of this |
---|
25 | manual into another language, under the above conditions for modified |
---|
26 | versions, except that the sections entitled "GNU General Public |
---|
27 | License," "Funding for Free Software," and "Protect Your Freedom--Fight |
---|
28 | `Look And Feel'", and this permission notice, may be included in |
---|
29 | translations approved by the Free Software Foundation instead of in the |
---|
30 | original English. |
---|
31 | |
---|
32 | |
---|
33 | File: gcc.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format |
---|
34 | |
---|
35 | How Initialization Functions Are Handled |
---|
36 | ---------------------------------------- |
---|
37 | |
---|
38 | The compiled code for certain languages includes "constructors" |
---|
39 | (also called "initialization routines")--functions to initialize data |
---|
40 | in the program when the program is started. These functions need to be |
---|
41 | called before the program is "started"--that is to say, before `main' |
---|
42 | is called. |
---|
43 | |
---|
44 | Compiling some languages generates "destructors" (also called |
---|
45 | "termination routines") that should be called when the program |
---|
46 | terminates. |
---|
47 | |
---|
48 | To make the initialization and termination functions work, the |
---|
49 | compiler must output something in the assembler code to cause those |
---|
50 | functions to be called at the appropriate time. When you port the |
---|
51 | compiler to a new system, you need to specify how to do this. |
---|
52 | |
---|
53 | There are two major ways that GCC currently supports the execution of |
---|
54 | initialization and termination functions. Each way has two variants. |
---|
55 | Much of the structure is common to all four variations. |
---|
56 | |
---|
57 | The linker must build two lists of these functions--a list of |
---|
58 | initialization functions, called `__CTOR_LIST__', and a list of |
---|
59 | termination functions, called `__DTOR_LIST__'. |
---|
60 | |
---|
61 | Each list always begins with an ignored function pointer (which may |
---|
62 | hold 0, -1, or a count of the function pointers after it, depending on |
---|
63 | the environment). This is followed by a series of zero or more function |
---|
64 | pointers to constructors (or destructors), followed by a function |
---|
65 | pointer containing zero. |
---|
66 | |
---|
67 | Depending on the operating system and its executable file format, |
---|
68 | either `crtstuff.c' or `libgcc2.c' traverses these lists at startup |
---|
69 | time and exit time. Constructors are called in reverse order of the |
---|
70 | list; destructors in forward order. |
---|
71 | |
---|
72 | The best way to handle static constructors works only for object file |
---|
73 | formats which provide arbitrarily-named sections. A section is set |
---|
74 | aside for a list of constructors, and another for a list of destructors. |
---|
75 | Traditionally these are called `.ctors' and `.dtors'. Each object file |
---|
76 | that defines an initialization function also puts a word in the |
---|
77 | constructor section to point to that function. The linker accumulates |
---|
78 | all these words into one contiguous `.ctors' section. Termination |
---|
79 | functions are handled similarly. |
---|
80 | |
---|
81 | To use this method, you need appropriate definitions of the macros |
---|
82 | `ASM_OUTPUT_CONSTRUCTOR' and `ASM_OUTPUT_DESTRUCTOR'. Usually you can |
---|
83 | get them by including `svr4.h'. |
---|
84 | |
---|
85 | When arbitrary sections are available, there are two variants, |
---|
86 | depending upon how the code in `crtstuff.c' is called. On systems that |
---|
87 | support an "init" section which is executed at program startup, parts |
---|
88 | of `crtstuff.c' are compiled into that section. The program is linked |
---|
89 | by the `gcc' driver like this: |
---|
90 | |
---|
91 | ld -o OUTPUT_FILE crtbegin.o ... crtend.o -lgcc |
---|
92 | |
---|
93 | The head of a function (`__do_global_ctors') appears in the init |
---|
94 | section of `crtbegin.o'; the remainder of the function appears in the |
---|
95 | init section of `crtend.o'. The linker will pull these two parts of |
---|
96 | the section together, making a whole function. If any of the user's |
---|
97 | object files linked into the middle of it contribute code, then that |
---|
98 | code will be executed as part of the body of `__do_global_ctors'. |
---|
99 | |
---|
100 | To use this variant, you must define the `INIT_SECTION_ASM_OP' macro |
---|
101 | properly. |
---|
102 | |
---|
103 | If no init section is available, do not define |
---|
104 | `INIT_SECTION_ASM_OP'. Then `__do_global_ctors' is built into the text |
---|
105 | section like all other functions, and resides in `libgcc.a'. When GCC |
---|
106 | compiles any function called `main', it inserts a procedure call to |
---|
107 | `__main' as the first executable code after the function prologue. The |
---|
108 | `__main' function, also defined in `libgcc2.c', simply calls |
---|
109 | `__do_global_ctors'. |
---|
110 | |
---|
111 | In file formats that don't support arbitrary sections, there are |
---|
112 | again two variants. In the simplest variant, the GNU linker (GNU `ld') |
---|
113 | and an `a.out' format must be used. In this case, |
---|
114 | `ASM_OUTPUT_CONSTRUCTOR' is defined to produce a `.stabs' entry of type |
---|
115 | `N_SETT', referencing the name `__CTOR_LIST__', and with the address of |
---|
116 | the void function containing the initialization code as its value. The |
---|
117 | GNU linker recognizes this as a request to add the value to a "set"; |
---|
118 | the values are accumulated, and are eventually placed in the executable |
---|
119 | as a vector in the format described above, with a leading (ignored) |
---|
120 | count and a trailing zero element. `ASM_OUTPUT_DESTRUCTOR' is handled |
---|
121 | similarly. Since no init section is available, the absence of |
---|
122 | `INIT_SECTION_ASM_OP' causes the compilation of `main' to call `__main' |
---|
123 | as above, starting the initialization process. |
---|
124 | |
---|
125 | The last variant uses neither arbitrary sections nor the GNU linker. |
---|
126 | This is preferable when you want to do dynamic linking and when using |
---|
127 | file formats which the GNU linker does not support, such as `ECOFF'. In |
---|
128 | this case, `ASM_OUTPUT_CONSTRUCTOR' does not produce an `N_SETT' |
---|
129 | symbol; initialization and termination functions are recognized simply |
---|
130 | by their names. This requires an extra program in the linkage step, |
---|
131 | called `collect2'. This program pretends to be the linker, for use |
---|
132 | with GNU CC; it does its job by running the ordinary linker, but also |
---|
133 | arranges to include the vectors of initialization and termination |
---|
134 | functions. These functions are called via `__main' as described above. |
---|
135 | |
---|
136 | Choosing among these configuration options has been simplified by a |
---|
137 | set of operating-system-dependent files in the `config' subdirectory. |
---|
138 | These files define all of the relevant parameters. Usually it is |
---|
139 | sufficient to include one into your specific machine-dependent |
---|
140 | configuration file. These files are: |
---|
141 | |
---|
142 | `aoutos.h' |
---|
143 | For operating systems using the `a.out' format. |
---|
144 | |
---|
145 | `next.h' |
---|
146 | For operating systems using the `MachO' format. |
---|
147 | |
---|
148 | `svr3.h' |
---|
149 | For System V Release 3 and similar systems using `COFF' format. |
---|
150 | |
---|
151 | `svr4.h' |
---|
152 | For System V Release 4 and similar systems using `ELF' format. |
---|
153 | |
---|
154 | `vms.h' |
---|
155 | For the VMS operating system. |
---|
156 | |
---|
157 | The following section describes the specific macros that control and |
---|
158 | customize the handling of initialization and termination functions. |
---|
159 | |
---|
160 | |
---|
161 | File: gcc.info, Node: Macros for Initialization, Next: Instruction Output, Prev: Initialization, Up: Assembler Format |
---|
162 | |
---|
163 | Macros Controlling Initialization Routines |
---|
164 | ------------------------------------------ |
---|
165 | |
---|
166 | Here are the macros that control how the compiler handles |
---|
167 | initialization and termination functions: |
---|
168 | |
---|
169 | `INIT_SECTION_ASM_OP' |
---|
170 | If defined, a C string constant for the assembler operation to |
---|
171 | identify the following data as initialization code. If not |
---|
172 | defined, GNU CC will assume such a section does not exist. When |
---|
173 | you are using special sections for initialization and termination |
---|
174 | functions, this macro also controls how `crtstuff.c' and |
---|
175 | `libgcc2.c' arrange to run the initialization functions. |
---|
176 | |
---|
177 | `HAS_INIT_SECTION' |
---|
178 | If defined, `main' will not call `__main' as described above. |
---|
179 | This macro should be defined for systems that control the contents |
---|
180 | of the init section on a symbol-by-symbol basis, such as OSF/1, |
---|
181 | and should not be defined explicitly for systems that support |
---|
182 | `INIT_SECTION_ASM_OP'. |
---|
183 | |
---|
184 | `LD_INIT_SWITCH' |
---|
185 | If defined, a C string constant for a switch that tells the linker |
---|
186 | that the following symbol is an initialization routine. |
---|
187 | |
---|
188 | `LD_FINI_SWITCH' |
---|
189 | If defined, a C string constant for a switch that tells the linker |
---|
190 | that the following symbol is a finalization routine. |
---|
191 | |
---|
192 | `INVOKE__main' |
---|
193 | If defined, `main' will call `__main' despite the presence of |
---|
194 | `INIT_SECTION_ASM_OP'. This macro should be defined for systems |
---|
195 | where the init section is not actually run automatically, but is |
---|
196 | still useful for collecting the lists of constructors and |
---|
197 | destructors. |
---|
198 | |
---|
199 | `ASM_OUTPUT_CONSTRUCTOR (STREAM, NAME)' |
---|
200 | Define this macro as a C statement to output on the stream STREAM |
---|
201 | the assembler code to arrange to call the function named NAME at |
---|
202 | initialization time. |
---|
203 | |
---|
204 | Assume that NAME is the name of a C function generated |
---|
205 | automatically by the compiler. This function takes no arguments. |
---|
206 | Use the function `assemble_name' to output the name NAME; this |
---|
207 | performs any system-specific syntactic transformations such as |
---|
208 | adding an underscore. |
---|
209 | |
---|
210 | If you don't define this macro, nothing special is output to |
---|
211 | arrange to call the function. This is correct when the function |
---|
212 | will be called in some other manner--for example, by means of the |
---|
213 | `collect2' program, which looks through the symbol table to find |
---|
214 | these functions by their names. |
---|
215 | |
---|
216 | `ASM_OUTPUT_DESTRUCTOR (STREAM, NAME)' |
---|
217 | This is like `ASM_OUTPUT_CONSTRUCTOR' but used for termination |
---|
218 | functions rather than initialization functions. |
---|
219 | |
---|
220 | If your system uses `collect2' as the means of processing |
---|
221 | constructors, then that program normally uses `nm' to scan an object |
---|
222 | file for constructor functions to be called. On certain kinds of |
---|
223 | systems, you can define these macros to make `collect2' work faster |
---|
224 | (and, in some cases, make it work at all): |
---|
225 | |
---|
226 | `OBJECT_FORMAT_COFF' |
---|
227 | Define this macro if the system uses COFF (Common Object File |
---|
228 | Format) object files, so that `collect2' can assume this format |
---|
229 | and scan object files directly for dynamic constructor/destructor |
---|
230 | functions. |
---|
231 | |
---|
232 | `OBJECT_FORMAT_ROSE' |
---|
233 | Define this macro if the system uses ROSE format object files, so |
---|
234 | that `collect2' can assume this format and scan object files |
---|
235 | directly for dynamic constructor/destructor functions. |
---|
236 | |
---|
237 | These macros are effective only in a native compiler; `collect2' as |
---|
238 | part of a cross compiler always uses `nm' for the target machine. |
---|
239 | |
---|
240 | `REAL_NM_FILE_NAME' |
---|
241 | Define this macro as a C string constant containing the file name |
---|
242 | to use to execute `nm'. The default is to search the path |
---|
243 | normally for `nm'. |
---|
244 | |
---|
245 | If your system supports shared libraries and has a program to list |
---|
246 | the dynamic dependencies of a given library or executable, you can |
---|
247 | define these macros to enable support for running initialization |
---|
248 | and termination functions in shared libraries: |
---|
249 | |
---|
250 | `LDD_SUFFIX' |
---|
251 | Define this macro to a C string constant containing the name of the |
---|
252 | program which lists dynamic dependencies, like `"ldd"' under SunOS |
---|
253 | 4. |
---|
254 | |
---|
255 | `PARSE_LDD_OUTPUT (PTR)' |
---|
256 | Define this macro to be C code that extracts filenames from the |
---|
257 | output of the program denoted by `LDD_SUFFIX'. PTR is a variable |
---|
258 | of type `char *' that points to the beginning of a line of output |
---|
259 | from `LDD_SUFFIX'. If the line lists a dynamic dependency, the |
---|
260 | code must advance PTR to the beginning of the filename on that |
---|
261 | line. Otherwise, it must set PTR to `NULL'. |
---|
262 | |
---|
263 | |
---|
264 | File: gcc.info, Node: Instruction Output, Next: Dispatch Tables, Prev: Macros for Initialization, Up: Assembler Format |
---|
265 | |
---|
266 | Output of Assembler Instructions |
---|
267 | -------------------------------- |
---|
268 | |
---|
269 | This describes assembler instruction output. |
---|
270 | |
---|
271 | `REGISTER_NAMES' |
---|
272 | A C initializer containing the assembler's names for the machine |
---|
273 | registers, each one as a C string constant. This is what |
---|
274 | translates register numbers in the compiler into assembler |
---|
275 | language. |
---|
276 | |
---|
277 | `ADDITIONAL_REGISTER_NAMES' |
---|
278 | If defined, a C initializer for an array of structures containing |
---|
279 | a name and a register number. This macro defines additional names |
---|
280 | for hard registers, thus allowing the `asm' option in declarations |
---|
281 | to refer to registers using alternate names. |
---|
282 | |
---|
283 | `ASM_OUTPUT_OPCODE (STREAM, PTR)' |
---|
284 | Define this macro if you are using an unusual assembler that |
---|
285 | requires different names for the machine instructions. |
---|
286 | |
---|
287 | The definition is a C statement or statements which output an |
---|
288 | assembler instruction opcode to the stdio stream STREAM. The |
---|
289 | macro-operand PTR is a variable of type `char *' which points to |
---|
290 | the opcode name in its "internal" form--the form that is written |
---|
291 | in the machine description. The definition should output the |
---|
292 | opcode name to STREAM, performing any translation you desire, and |
---|
293 | increment the variable PTR to point at the end of the opcode so |
---|
294 | that it will not be output twice. |
---|
295 | |
---|
296 | In fact, your macro definition may process less than the entire |
---|
297 | opcode name, or more than the opcode name; but if you want to |
---|
298 | process text that includes `%'-sequences to substitute operands, |
---|
299 | you must take care of the substitution yourself. Just be sure to |
---|
300 | increment PTR over whatever text should not be output normally. |
---|
301 | |
---|
302 | If you need to look at the operand values, they can be found as the |
---|
303 | elements of `recog_operand'. |
---|
304 | |
---|
305 | If the macro definition does nothing, the instruction is output in |
---|
306 | the usual way. |
---|
307 | |
---|
308 | `FINAL_PRESCAN_INSN (INSN, OPVEC, NOPERANDS)' |
---|
309 | If defined, a C statement to be executed just prior to the output |
---|
310 | of assembler code for INSN, to modify the extracted operands so |
---|
311 | they will be output differently. |
---|
312 | |
---|
313 | Here the argument OPVEC is the vector containing the operands |
---|
314 | extracted from INSN, and NOPERANDS is the number of elements of |
---|
315 | the vector which contain meaningful data for this insn. The |
---|
316 | contents of this vector are what will be used to convert the insn |
---|
317 | template into assembler code, so you can change the assembler |
---|
318 | output by changing the contents of the vector. |
---|
319 | |
---|
320 | This macro is useful when various assembler syntaxes share a single |
---|
321 | file of instruction patterns; by defining this macro differently, |
---|
322 | you can cause a large class of instructions to be output |
---|
323 | differently (such as with rearranged operands). Naturally, |
---|
324 | variations in assembler syntax affecting individual insn patterns |
---|
325 | ought to be handled by writing conditional output routines in |
---|
326 | those patterns. |
---|
327 | |
---|
328 | If this macro is not defined, it is equivalent to a null statement. |
---|
329 | |
---|
330 | `FINAL_PRESCAN_LABEL' |
---|
331 | If defined, `FINAL_PRESCAN_INSN' will be called on each |
---|
332 | `CODE_LABEL'. In that case, OPVEC will be a null pointer and |
---|
333 | NOPERANDS will be zero. |
---|
334 | |
---|
335 | `PRINT_OPERAND (STREAM, X, CODE)' |
---|
336 | A C compound statement to output to stdio stream STREAM the |
---|
337 | assembler syntax for an instruction operand X. X is an RTL |
---|
338 | expression. |
---|
339 | |
---|
340 | CODE is a value that can be used to specify one of several ways of |
---|
341 | printing the operand. It is used when identical operands must be |
---|
342 | printed differently depending on the context. CODE comes from the |
---|
343 | `%' specification that was used to request printing of the |
---|
344 | operand. If the specification was just `%DIGIT' then CODE is 0; |
---|
345 | if the specification was `%LTR DIGIT' then CODE is the ASCII code |
---|
346 | for LTR. |
---|
347 | |
---|
348 | If X is a register, this macro should print the register's name. |
---|
349 | The names can be found in an array `reg_names' whose type is `char |
---|
350 | *[]'. `reg_names' is initialized from `REGISTER_NAMES'. |
---|
351 | |
---|
352 | When the machine description has a specification `%PUNCT' (a `%' |
---|
353 | followed by a punctuation character), this macro is called with a |
---|
354 | null pointer for X and the punctuation character for CODE. |
---|
355 | |
---|
356 | `PRINT_OPERAND_PUNCT_VALID_P (CODE)' |
---|
357 | A C expression which evaluates to true if CODE is a valid |
---|
358 | punctuation character for use in the `PRINT_OPERAND' macro. If |
---|
359 | `PRINT_OPERAND_PUNCT_VALID_P' is not defined, it means that no |
---|
360 | punctuation characters (except for the standard one, `%') are used |
---|
361 | in this way. |
---|
362 | |
---|
363 | `PRINT_OPERAND_ADDRESS (STREAM, X)' |
---|
364 | A C compound statement to output to stdio stream STREAM the |
---|
365 | assembler syntax for an instruction operand that is a memory |
---|
366 | reference whose address is X. X is an RTL expression. |
---|
367 | |
---|
368 | On some machines, the syntax for a symbolic address depends on the |
---|
369 | section that the address refers to. On these machines, define the |
---|
370 | macro `ENCODE_SECTION_INFO' to store the information into the |
---|
371 | `symbol_ref', and then check for it here. *Note Assembler |
---|
372 | Format::. |
---|
373 | |
---|
374 | `DBR_OUTPUT_SEQEND(FILE)' |
---|
375 | A C statement, to be executed after all slot-filler instructions |
---|
376 | have been output. If necessary, call `dbr_sequence_length' to |
---|
377 | determine the number of slots filled in a sequence (zero if not |
---|
378 | currently outputting a sequence), to decide how many no-ops to |
---|
379 | output, or whatever. |
---|
380 | |
---|
381 | Don't define this macro if it has nothing to do, but it is helpful |
---|
382 | in reading assembly output if the extent of the delay sequence is |
---|
383 | made explicit (e.g. with white space). |
---|
384 | |
---|
385 | Note that output routines for instructions with delay slots must be |
---|
386 | prepared to deal with not being output as part of a sequence (i.e. |
---|
387 | when the scheduling pass is not run, or when no slot fillers could |
---|
388 | be found.) The variable `final_sequence' is null when not |
---|
389 | processing a sequence, otherwise it contains the `sequence' rtx |
---|
390 | being output. |
---|
391 | |
---|
392 | `REGISTER_PREFIX' |
---|
393 | `LOCAL_LABEL_PREFIX' |
---|
394 | `USER_LABEL_PREFIX' |
---|
395 | `IMMEDIATE_PREFIX' |
---|
396 | If defined, C string expressions to be used for the `%R', `%L', |
---|
397 | `%U', and `%I' options of `asm_fprintf' (see `final.c'). These |
---|
398 | are useful when a single `md' file must support multiple assembler |
---|
399 | formats. In that case, the various `tm.h' files can define these |
---|
400 | macros differently. |
---|
401 | |
---|
402 | `ASSEMBLER_DIALECT' |
---|
403 | If your target supports multiple dialects of assembler language |
---|
404 | (such as different opcodes), define this macro as a C expression |
---|
405 | that gives the numeric index of the assembler language dialect to |
---|
406 | use, with zero as the first variant. |
---|
407 | |
---|
408 | If this macro is defined, you may use constructs of the form |
---|
409 | `{option0|option1|option2...}' in the output templates of patterns |
---|
410 | (*note Output Template::.) or in the first argument of |
---|
411 | `asm_fprintf'. This construct outputs `option0', `option1' or |
---|
412 | `option2', etc., if the value of `ASSEMBLER_DIALECT' is zero, one |
---|
413 | or two, etc. Any special characters within these strings retain |
---|
414 | their usual meaning. |
---|
415 | |
---|
416 | If you do not define this macro, the characters `{', `|' and `}' |
---|
417 | do not have any special meaning when used in templates or operands |
---|
418 | to `asm_fprintf'. |
---|
419 | |
---|
420 | Define the macros `REGISTER_PREFIX', `LOCAL_LABEL_PREFIX', |
---|
421 | `USER_LABEL_PREFIX' and `IMMEDIATE_PREFIX' if you can express the |
---|
422 | variations in assembler language syntax with that mechanism. |
---|
423 | Define `ASSEMBLER_DIALECT' and use the `{option0|option1}' syntax |
---|
424 | if the syntax variant are larger and involve such things as |
---|
425 | different opcodes or operand order. |
---|
426 | |
---|
427 | `ASM_OUTPUT_REG_PUSH (STREAM, REGNO)' |
---|
428 | A C expression to output to STREAM some assembler code which will |
---|
429 | push hard register number REGNO onto the stack. The code need not |
---|
430 | be optimal, since this macro is used only when profiling. |
---|
431 | |
---|
432 | `ASM_OUTPUT_REG_POP (STREAM, REGNO)' |
---|
433 | A C expression to output to STREAM some assembler code which will |
---|
434 | pop hard register number REGNO off of the stack. The code need |
---|
435 | not be optimal, since this macro is used only when profiling. |
---|
436 | |
---|
437 | |
---|
438 | File: gcc.info, Node: Dispatch Tables, Next: Exception Region Output, Prev: Instruction Output, Up: Assembler Format |
---|
439 | |
---|
440 | Output of Dispatch Tables |
---|
441 | ------------------------- |
---|
442 | |
---|
443 | This concerns dispatch tables. |
---|
444 | |
---|
445 | `ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, VALUE, REL)' |
---|
446 | A C statement to output to the stdio stream STREAM an assembler |
---|
447 | pseudo-instruction to generate a difference between two labels. |
---|
448 | VALUE and REL are the numbers of two internal labels. The |
---|
449 | definitions of these labels are output using |
---|
450 | `ASM_OUTPUT_INTERNAL_LABEL', and they must be printed in the same |
---|
451 | way here. For example, |
---|
452 | |
---|
453 | fprintf (STREAM, "\t.word L%d-L%d\n", |
---|
454 | VALUE, REL) |
---|
455 | |
---|
456 | You must provide this macro on machines where the addresses in a |
---|
457 | dispatch table are relative to the table's own address. If |
---|
458 | defined, GNU CC will also use this macro on all machines when |
---|
459 | producing PIC. |
---|
460 | |
---|
461 | `ASM_OUTPUT_ADDR_VEC_ELT (STREAM, VALUE)' |
---|
462 | This macro should be provided on machines where the addresses in a |
---|
463 | dispatch table are absolute. |
---|
464 | |
---|
465 | The definition should be a C statement to output to the stdio |
---|
466 | stream STREAM an assembler pseudo-instruction to generate a |
---|
467 | reference to a label. VALUE is the number of an internal label |
---|
468 | whose definition is output using `ASM_OUTPUT_INTERNAL_LABEL'. For |
---|
469 | example, |
---|
470 | |
---|
471 | fprintf (STREAM, "\t.word L%d\n", VALUE) |
---|
472 | |
---|
473 | `ASM_OUTPUT_CASE_LABEL (STREAM, PREFIX, NUM, TABLE)' |
---|
474 | Define this if the label before a jump-table needs to be output |
---|
475 | specially. The first three arguments are the same as for |
---|
476 | `ASM_OUTPUT_INTERNAL_LABEL'; the fourth argument is the jump-table |
---|
477 | which follows (a `jump_insn' containing an `addr_vec' or |
---|
478 | `addr_diff_vec'). |
---|
479 | |
---|
480 | This feature is used on system V to output a `swbeg' statement for |
---|
481 | the table. |
---|
482 | |
---|
483 | If this macro is not defined, these labels are output with |
---|
484 | `ASM_OUTPUT_INTERNAL_LABEL'. |
---|
485 | |
---|
486 | `ASM_OUTPUT_CASE_END (STREAM, NUM, TABLE)' |
---|
487 | Define this if something special must be output at the end of a |
---|
488 | jump-table. The definition should be a C statement to be executed |
---|
489 | after the assembler code for the table is written. It should write |
---|
490 | the appropriate code to stdio stream STREAM. The argument TABLE |
---|
491 | is the jump-table insn, and NUM is the label-number of the |
---|
492 | preceding label. |
---|
493 | |
---|
494 | If this macro is not defined, nothing special is output at the end |
---|
495 | of the jump-table. |
---|
496 | |
---|
497 | |
---|
498 | File: gcc.info, Node: Exception Region Output, Next: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format |
---|
499 | |
---|
500 | Assembler Commands for Exception Regions |
---|
501 | ---------------------------------------- |
---|
502 | |
---|
503 | This describes commands marking the start and the end of an exception |
---|
504 | region. |
---|
505 | |
---|
506 | `ASM_OUTPUT_EH_REGION_BEG ()' |
---|
507 | A C expression to output text to mark the start of an exception |
---|
508 | region. |
---|
509 | |
---|
510 | This macro need not be defined on most platforms. |
---|
511 | |
---|
512 | `ASM_OUTPUT_EH_REGION_END ()' |
---|
513 | A C expression to output text to mark the end of an exception |
---|
514 | region. |
---|
515 | |
---|
516 | This macro need not be defined on most platforms. |
---|
517 | |
---|
518 | `EXCEPTION_SECTION ()' |
---|
519 | A C expression to switch to the section in which the main |
---|
520 | exception table is to be placed (*note Sections::.). The default |
---|
521 | is a section named `.gcc_except_table' on machines that support |
---|
522 | named sections via `ASM_OUTPUT_SECTION_NAME', otherwise if `-fpic' |
---|
523 | or `-fPIC' is in effect, the `data_section', otherwise the |
---|
524 | `readonly_data_section'. |
---|
525 | |
---|
526 | `EH_FRAME_SECTION_ASM_OP' |
---|
527 | If defined, a C string constant for the assembler operation to |
---|
528 | switch to the section for exception handling frame unwind |
---|
529 | information. If not defined, GNU CC will provide a default |
---|
530 | definition if the target supports named sections. `crtstuff.c' |
---|
531 | uses this macro to switch to the appropriate section. |
---|
532 | |
---|
533 | You should define this symbol if your target supports DWARF 2 frame |
---|
534 | unwind information and the default definition does not work. |
---|
535 | |
---|
536 | `OMIT_EH_TABLE ()' |
---|
537 | A C expression that is nonzero if the normal exception table output |
---|
538 | should be omitted. |
---|
539 | |
---|
540 | This macro need not be defined on most platforms. |
---|
541 | |
---|
542 | `EH_TABLE_LOOKUP ()' |
---|
543 | Alternate runtime support for looking up an exception at runtime |
---|
544 | and finding the associated handler, if the default method won't |
---|
545 | work. |
---|
546 | |
---|
547 | This macro need not be defined on most platforms. |
---|
548 | |
---|
549 | `DOESNT_NEED_UNWINDER' |
---|
550 | A C expression that decides whether or not the current function |
---|
551 | needs to have a function unwinder generated for it. See the file |
---|
552 | `except.c' for details on when to define this, and how. |
---|
553 | |
---|
554 | `MASK_RETURN_ADDR' |
---|
555 | An rtx used to mask the return address found via RETURN_ADDR_RTX, |
---|
556 | so that it does not contain any extraneous set bits in it. |
---|
557 | |
---|
558 | `DWARF2_UNWIND_INFO' |
---|
559 | Define this macro to 0 if your target supports DWARF 2 frame unwind |
---|
560 | information, but it does not yet work with exception handling. |
---|
561 | Otherwise, if your target supports this information (if it defines |
---|
562 | `INCOMING_RETURN_ADDR_RTX' and either `UNALIGNED_INT_ASM_OP' or |
---|
563 | `OBJECT_FORMAT_ELF'), GCC will provide a default definition of 1. |
---|
564 | |
---|
565 | If this macro is defined to 1, the DWARF 2 unwinder will be the |
---|
566 | default exception handling mechanism; otherwise, setjmp/longjmp |
---|
567 | will be used by default. |
---|
568 | |
---|
569 | If this macro is defined to anything, the DWARF 2 unwinder will be |
---|
570 | used instead of inline unwinders and __unwind_function in the |
---|
571 | non-setjmp case. |
---|
572 | |
---|
573 | |
---|
574 | File: gcc.info, Node: Alignment Output, Prev: Exception Region Output, Up: Assembler Format |
---|
575 | |
---|
576 | Assembler Commands for Alignment |
---|
577 | -------------------------------- |
---|
578 | |
---|
579 | This describes commands for alignment. |
---|
580 | |
---|
581 | `ASM_OUTPUT_ALIGN_CODE (FILE)' |
---|
582 | A C expression to output text to align the location counter in the |
---|
583 | way that is desirable at a point in the code that is reached only |
---|
584 | by jumping. |
---|
585 | |
---|
586 | This macro need not be defined if you don't want any special |
---|
587 | alignment to be done at such a time. Most machine descriptions do |
---|
588 | not currently define the macro. |
---|
589 | |
---|
590 | `ASM_OUTPUT_LOOP_ALIGN (FILE)' |
---|
591 | A C expression to output text to align the location counter in the |
---|
592 | way that is desirable at the beginning of a loop. |
---|
593 | |
---|
594 | This macro need not be defined if you don't want any special |
---|
595 | alignment to be done at such a time. Most machine descriptions do |
---|
596 | not currently define the macro. |
---|
597 | |
---|
598 | `ASM_OUTPUT_SKIP (STREAM, NBYTES)' |
---|
599 | A C statement to output to the stdio stream STREAM an assembler |
---|
600 | instruction to advance the location counter by NBYTES bytes. |
---|
601 | Those bytes should be zero when loaded. NBYTES will be a C |
---|
602 | expression of type `int'. |
---|
603 | |
---|
604 | `ASM_NO_SKIP_IN_TEXT' |
---|
605 | Define this macro if `ASM_OUTPUT_SKIP' should not be used in the |
---|
606 | text section because it fails put zeros in the bytes that are |
---|
607 | skipped. This is true on many Unix systems, where the pseudo-op |
---|
608 | to skip bytes produces no-op instructions rather than zeros when |
---|
609 | used in the text section. |
---|
610 | |
---|
611 | `ASM_OUTPUT_ALIGN (STREAM, POWER)' |
---|
612 | A C statement to output to the stdio stream STREAM an assembler |
---|
613 | command to advance the location counter to a multiple of 2 to the |
---|
614 | POWER bytes. POWER will be a C expression of type `int'. |
---|
615 | |
---|
616 | |
---|
617 | File: gcc.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Target Macros |
---|
618 | |
---|
619 | Controlling Debugging Information Format |
---|
620 | ======================================== |
---|
621 | |
---|
622 | This describes how to specify debugging information. |
---|
623 | |
---|
624 | * Menu: |
---|
625 | |
---|
626 | * All Debuggers:: Macros that affect all debugging formats uniformly. |
---|
627 | * DBX Options:: Macros enabling specific options in DBX format. |
---|
628 | * DBX Hooks:: Hook macros for varying DBX format. |
---|
629 | * File Names and DBX:: Macros controlling output of file names in DBX format. |
---|
630 | * SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. |
---|
631 | |
---|
632 | |
---|
633 | File: gcc.info, Node: All Debuggers, Next: DBX Options, Up: Debugging Info |
---|
634 | |
---|
635 | Macros Affecting All Debugging Formats |
---|
636 | -------------------------------------- |
---|
637 | |
---|
638 | These macros affect all debugging formats. |
---|
639 | |
---|
640 | `DBX_REGISTER_NUMBER (REGNO)' |
---|
641 | A C expression that returns the DBX register number for the |
---|
642 | compiler register number REGNO. In simple cases, the value of this |
---|
643 | expression may be REGNO itself. But sometimes there are some |
---|
644 | registers that the compiler knows about and DBX does not, or vice |
---|
645 | versa. In such cases, some register may need to have one number in |
---|
646 | the compiler and another for DBX. |
---|
647 | |
---|
648 | If two registers have consecutive numbers inside GNU CC, and they |
---|
649 | can be used as a pair to hold a multiword value, then they *must* |
---|
650 | have consecutive numbers after renumbering with |
---|
651 | `DBX_REGISTER_NUMBER'. Otherwise, debuggers will be unable to |
---|
652 | access such a pair, because they expect register pairs to be |
---|
653 | consecutive in their own numbering scheme. |
---|
654 | |
---|
655 | If you find yourself defining `DBX_REGISTER_NUMBER' in way that |
---|
656 | does not preserve register pairs, then what you must do instead is |
---|
657 | redefine the actual register numbering scheme. |
---|
658 | |
---|
659 | `DEBUGGER_AUTO_OFFSET (X)' |
---|
660 | A C expression that returns the integer offset value for an |
---|
661 | automatic variable having address X (an RTL expression). The |
---|
662 | default computation assumes that X is based on the frame-pointer |
---|
663 | and gives the offset from the frame-pointer. This is required for |
---|
664 | targets that produce debugging output for DBX or COFF-style |
---|
665 | debugging output for SDB and allow the frame-pointer to be |
---|
666 | eliminated when the `-g' options is used. |
---|
667 | |
---|
668 | `DEBUGGER_ARG_OFFSET (OFFSET, X)' |
---|
669 | A C expression that returns the integer offset value for an |
---|
670 | argument having address X (an RTL expression). The nominal offset |
---|
671 | is OFFSET. |
---|
672 | |
---|
673 | `PREFERRED_DEBUGGING_TYPE' |
---|
674 | A C expression that returns the type of debugging output GNU CC |
---|
675 | should produce when the user specifies just `-g'. Define this if |
---|
676 | you have arranged for GNU CC to support more than one format of |
---|
677 | debugging output. Currently, the allowable values are `DBX_DEBUG', |
---|
678 | `SDB_DEBUG', `DWARF_DEBUG', `DWARF2_DEBUG', and `XCOFF_DEBUG'. |
---|
679 | |
---|
680 | When the user specifies `-ggdb', GNU CC normally also uses the |
---|
681 | value of this macro to select the debugging output format, but |
---|
682 | with two exceptions. If `DWARF2_DEBUGGING_INFO' is defined and |
---|
683 | `LINKER_DOES_NOT_WORK_WITH_DWARF2' is not defined, GNU CC uses the |
---|
684 | value `DWARF2_DEBUG'. Otherwise, if `DBX_DEBUGGING_INFO' is |
---|
685 | defined, GNU CC uses `DBX_DEBUG'. |
---|
686 | |
---|
687 | The value of this macro only affects the default debugging output; |
---|
688 | the user can always get a specific type of output by using |
---|
689 | `-gstabs', `-gcoff', `-gdwarf-1', `-gdwarf-2', or `-gxcoff'. |
---|
690 | |
---|
691 | |
---|
692 | File: gcc.info, Node: DBX Options, Next: DBX Hooks, Prev: All Debuggers, Up: Debugging Info |
---|
693 | |
---|
694 | Specific Options for DBX Output |
---|
695 | ------------------------------- |
---|
696 | |
---|
697 | These are specific options for DBX output. |
---|
698 | |
---|
699 | `DBX_DEBUGGING_INFO' |
---|
700 | Define this macro if GNU CC should produce debugging output for DBX |
---|
701 | in response to the `-g' option. |
---|
702 | |
---|
703 | `XCOFF_DEBUGGING_INFO' |
---|
704 | Define this macro if GNU CC should produce XCOFF format debugging |
---|
705 | output in response to the `-g' option. This is a variant of DBX |
---|
706 | format. |
---|
707 | |
---|
708 | `DEFAULT_GDB_EXTENSIONS' |
---|
709 | Define this macro to control whether GNU CC should by default |
---|
710 | generate GDB's extended version of DBX debugging information |
---|
711 | (assuming DBX-format debugging information is enabled at all). If |
---|
712 | you don't define the macro, the default is 1: always generate the |
---|
713 | extended information if there is any occasion to. |
---|
714 | |
---|
715 | `DEBUG_SYMS_TEXT' |
---|
716 | Define this macro if all `.stabs' commands should be output while |
---|
717 | in the text section. |
---|
718 | |
---|
719 | `ASM_STABS_OP' |
---|
720 | A C string constant naming the assembler pseudo op to use instead |
---|
721 | of `.stabs' to define an ordinary debugging symbol. If you don't |
---|
722 | define this macro, `.stabs' is used. This macro applies only to |
---|
723 | DBX debugging information format. |
---|
724 | |
---|
725 | `ASM_STABD_OP' |
---|
726 | A C string constant naming the assembler pseudo op to use instead |
---|
727 | of `.stabd' to define a debugging symbol whose value is the current |
---|
728 | location. If you don't define this macro, `.stabd' is used. This |
---|
729 | macro applies only to DBX debugging information format. |
---|
730 | |
---|
731 | `ASM_STABN_OP' |
---|
732 | A C string constant naming the assembler pseudo op to use instead |
---|
733 | of `.stabn' to define a debugging symbol with no name. If you |
---|
734 | don't define this macro, `.stabn' is used. This macro applies |
---|
735 | only to DBX debugging information format. |
---|
736 | |
---|
737 | `DBX_NO_XREFS' |
---|
738 | Define this macro if DBX on your system does not support the |
---|
739 | construct `xsTAGNAME'. On some systems, this construct is used to |
---|
740 | describe a forward reference to a structure named TAGNAME. On |
---|
741 | other systems, this construct is not supported at all. |
---|
742 | |
---|
743 | `DBX_CONTIN_LENGTH' |
---|
744 | A symbol name in DBX-format debugging information is normally |
---|
745 | continued (split into two separate `.stabs' directives) when it |
---|
746 | exceeds a certain length (by default, 80 characters). On some |
---|
747 | operating systems, DBX requires this splitting; on others, |
---|
748 | splitting must not be done. You can inhibit splitting by defining |
---|
749 | this macro with the value zero. You can override the default |
---|
750 | splitting-length by defining this macro as an expression for the |
---|
751 | length you desire. |
---|
752 | |
---|
753 | `DBX_CONTIN_CHAR' |
---|
754 | Normally continuation is indicated by adding a `\' character to |
---|
755 | the end of a `.stabs' string when a continuation follows. To use |
---|
756 | a different character instead, define this macro as a character |
---|
757 | constant for the character you want to use. Do not define this |
---|
758 | macro if backslash is correct for your system. |
---|
759 | |
---|
760 | `DBX_STATIC_STAB_DATA_SECTION' |
---|
761 | Define this macro if it is necessary to go to the data section |
---|
762 | before outputting the `.stabs' pseudo-op for a non-global static |
---|
763 | variable. |
---|
764 | |
---|
765 | `DBX_TYPE_DECL_STABS_CODE' |
---|
766 | The value to use in the "code" field of the `.stabs' directive for |
---|
767 | a typedef. The default is `N_LSYM'. |
---|
768 | |
---|
769 | `DBX_STATIC_CONST_VAR_CODE' |
---|
770 | The value to use in the "code" field of the `.stabs' directive for |
---|
771 | a static variable located in the text section. DBX format does not |
---|
772 | provide any "right" way to do this. The default is `N_FUN'. |
---|
773 | |
---|
774 | `DBX_REGPARM_STABS_CODE' |
---|
775 | The value to use in the "code" field of the `.stabs' directive for |
---|
776 | a parameter passed in registers. DBX format does not provide any |
---|
777 | "right" way to do this. The default is `N_RSYM'. |
---|
778 | |
---|
779 | `DBX_REGPARM_STABS_LETTER' |
---|
780 | The letter to use in DBX symbol data to identify a symbol as a |
---|
781 | parameter passed in registers. DBX format does not customarily |
---|
782 | provide any way to do this. The default is `'P''. |
---|
783 | |
---|
784 | `DBX_MEMPARM_STABS_LETTER' |
---|
785 | The letter to use in DBX symbol data to identify a symbol as a |
---|
786 | stack parameter. The default is `'p''. |
---|
787 | |
---|
788 | `DBX_FUNCTION_FIRST' |
---|
789 | Define this macro if the DBX information for a function and its |
---|
790 | arguments should precede the assembler code for the function. |
---|
791 | Normally, in DBX format, the debugging information entirely |
---|
792 | follows the assembler code. |
---|
793 | |
---|
794 | `DBX_LBRAC_FIRST' |
---|
795 | Define this macro if the `N_LBRAC' symbol for a block should |
---|
796 | precede the debugging information for variables and functions |
---|
797 | defined in that block. Normally, in DBX format, the `N_LBRAC' |
---|
798 | symbol comes first. |
---|
799 | |
---|
800 | `DBX_BLOCKS_FUNCTION_RELATIVE' |
---|
801 | Define this macro if the value of a symbol describing the scope of |
---|
802 | a block (`N_LBRAC' or `N_RBRAC') should be relative to the start |
---|
803 | of the enclosing function. Normally, GNU C uses an absolute |
---|
804 | address. |
---|
805 | |
---|
806 | `DBX_USE_BINCL' |
---|
807 | Define this macro if GNU C should generate `N_BINCL' and `N_EINCL' |
---|
808 | stabs for included header files, as on Sun systems. This macro |
---|
809 | also directs GNU C to output a type number as a pair of a file |
---|
810 | number and a type number within the file. Normally, GNU C does not |
---|
811 | generate `N_BINCL' or `N_EINCL' stabs, and it outputs a single |
---|
812 | number for a type number. |
---|
813 | |
---|
814 | |
---|
815 | File: gcc.info, Node: DBX Hooks, Next: File Names and DBX, Prev: DBX Options, Up: Debugging Info |
---|
816 | |
---|
817 | Open-Ended Hooks for DBX Format |
---|
818 | ------------------------------- |
---|
819 | |
---|
820 | These are hooks for DBX format. |
---|
821 | |
---|
822 | `DBX_OUTPUT_LBRAC (STREAM, NAME)' |
---|
823 | Define this macro to say how to output to STREAM the debugging |
---|
824 | information for the start of a scope level for variable names. The |
---|
825 | argument NAME is the name of an assembler symbol (for use with |
---|
826 | `assemble_name') whose value is the address where the scope begins. |
---|
827 | |
---|
828 | `DBX_OUTPUT_RBRAC (STREAM, NAME)' |
---|
829 | Like `DBX_OUTPUT_LBRAC', but for the end of a scope level. |
---|
830 | |
---|
831 | `DBX_OUTPUT_ENUM (STREAM, TYPE)' |
---|
832 | Define this macro if the target machine requires special handling |
---|
833 | to output an enumeration type. The definition should be a C |
---|
834 | statement (sans semicolon) to output the appropriate information |
---|
835 | to STREAM for the type TYPE. |
---|
836 | |
---|
837 | `DBX_OUTPUT_FUNCTION_END (STREAM, FUNCTION)' |
---|
838 | Define this macro if the target machine requires special output at |
---|
839 | the end of the debugging information for a function. The |
---|
840 | definition should be a C statement (sans semicolon) to output the |
---|
841 | appropriate information to STREAM. FUNCTION is the |
---|
842 | `FUNCTION_DECL' node for the function. |
---|
843 | |
---|
844 | `DBX_OUTPUT_STANDARD_TYPES (SYMS)' |
---|
845 | Define this macro if you need to control the order of output of the |
---|
846 | standard data types at the beginning of compilation. The argument |
---|
847 | SYMS is a `tree' which is a chain of all the predefined global |
---|
848 | symbols, including names of data types. |
---|
849 | |
---|
850 | Normally, DBX output starts with definitions of the types for |
---|
851 | integers and characters, followed by all the other predefined |
---|
852 | types of the particular language in no particular order. |
---|
853 | |
---|
854 | On some machines, it is necessary to output different particular |
---|
855 | types first. To do this, define `DBX_OUTPUT_STANDARD_TYPES' to |
---|
856 | output those symbols in the necessary order. Any predefined types |
---|
857 | that you don't explicitly output will be output afterward in no |
---|
858 | particular order. |
---|
859 | |
---|
860 | Be careful not to define this macro so that it works only for C. |
---|
861 | There are no global variables to access most of the built-in |
---|
862 | types, because another language may have another set of types. |
---|
863 | The way to output a particular type is to look through SYMS to see |
---|
864 | if you can find it. Here is an example: |
---|
865 | |
---|
866 | { |
---|
867 | tree decl; |
---|
868 | for (decl = syms; decl; decl = TREE_CHAIN (decl)) |
---|
869 | if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), |
---|
870 | "long int")) |
---|
871 | dbxout_symbol (decl); |
---|
872 | ... |
---|
873 | } |
---|
874 | |
---|
875 | This does nothing if the expected type does not exist. |
---|
876 | |
---|
877 | See the function `init_decl_processing' in `c-decl.c' to find the |
---|
878 | names to use for all the built-in C types. |
---|
879 | |
---|
880 | Here is another way of finding a particular type: |
---|
881 | |
---|
882 | { |
---|
883 | tree decl; |
---|
884 | for (decl = syms; decl; decl = TREE_CHAIN (decl)) |
---|
885 | if (TREE_CODE (decl) == TYPE_DECL |
---|
886 | && (TREE_CODE (TREE_TYPE (decl)) |
---|
887 | == INTEGER_CST) |
---|
888 | && TYPE_PRECISION (TREE_TYPE (decl)) == 16 |
---|
889 | && TYPE_UNSIGNED (TREE_TYPE (decl))) |
---|
890 | /* This must be `unsigned short'. */ |
---|
891 | dbxout_symbol (decl); |
---|
892 | ... |
---|
893 | } |
---|
894 | |
---|
895 | `NO_DBX_FUNCTION_END' |
---|
896 | Some stabs encapsulation formats (in particular ECOFF), cannot |
---|
897 | handle the `.stabs "",N_FUN,,0,0,Lscope-function-1' gdb dbx |
---|
898 | extention construct. On those machines, define this macro to turn |
---|
899 | this feature off without disturbing the rest of the gdb extensions. |
---|
900 | |
---|
901 | |
---|
902 | File: gcc.info, Node: File Names and DBX, Next: SDB and DWARF, Prev: DBX Hooks, Up: Debugging Info |
---|
903 | |
---|
904 | File Names in DBX Format |
---|
905 | ------------------------ |
---|
906 | |
---|
907 | This describes file names in DBX format. |
---|
908 | |
---|
909 | `DBX_WORKING_DIRECTORY' |
---|
910 | Define this if DBX wants to have the current directory recorded in |
---|
911 | each object file. |
---|
912 | |
---|
913 | Note that the working directory is always recorded if GDB |
---|
914 | extensions are enabled. |
---|
915 | |
---|
916 | `DBX_OUTPUT_MAIN_SOURCE_FILENAME (STREAM, NAME)' |
---|
917 | A C statement to output DBX debugging information to the stdio |
---|
918 | stream STREAM which indicates that file NAME is the main source |
---|
919 | file--the file specified as the input file for compilation. This |
---|
920 | macro is called only once, at the beginning of compilation. |
---|
921 | |
---|
922 | This macro need not be defined if the standard form of output for |
---|
923 | DBX debugging information is appropriate. |
---|
924 | |
---|
925 | `DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (STREAM, NAME)' |
---|
926 | A C statement to output DBX debugging information to the stdio |
---|
927 | stream STREAM which indicates that the current directory during |
---|
928 | compilation is named NAME. |
---|
929 | |
---|
930 | This macro need not be defined if the standard form of output for |
---|
931 | DBX debugging information is appropriate. |
---|
932 | |
---|
933 | `DBX_OUTPUT_MAIN_SOURCE_FILE_END (STREAM, NAME)' |
---|
934 | A C statement to output DBX debugging information at the end of |
---|
935 | compilation of the main source file NAME. |
---|
936 | |
---|
937 | If you don't define this macro, nothing special is output at the |
---|
938 | end of compilation, which is correct for most machines. |
---|
939 | |
---|
940 | `DBX_OUTPUT_SOURCE_FILENAME (STREAM, NAME)' |
---|
941 | A C statement to output DBX debugging information to the stdio |
---|
942 | stream STREAM which indicates that file NAME is the current source |
---|
943 | file. This output is generated each time input shifts to a |
---|
944 | different source file as a result of `#include', the end of an |
---|
945 | included file, or a `#line' command. |
---|
946 | |
---|
947 | This macro need not be defined if the standard form of output for |
---|
948 | DBX debugging information is appropriate. |
---|
949 | |
---|
950 | |
---|
951 | File: gcc.info, Node: SDB and DWARF, Prev: File Names and DBX, Up: Debugging Info |
---|
952 | |
---|
953 | Macros for SDB and DWARF Output |
---|
954 | ------------------------------- |
---|
955 | |
---|
956 | Here are macros for SDB and DWARF output. |
---|
957 | |
---|
958 | `SDB_DEBUGGING_INFO' |
---|
959 | Define this macro if GNU CC should produce COFF-style debugging |
---|
960 | output for SDB in response to the `-g' option. |
---|
961 | |
---|
962 | `DWARF_DEBUGGING_INFO' |
---|
963 | Define this macro if GNU CC should produce dwarf format debugging |
---|
964 | output in response to the `-g' option. |
---|
965 | |
---|
966 | `DWARF2_DEBUGGING_INFO' |
---|
967 | Define this macro if GNU CC should produce dwarf version 2 format |
---|
968 | debugging output in response to the `-g' option. |
---|
969 | |
---|
970 | To support optional call frame debugging information, you must also |
---|
971 | define `INCOMING_RETURN_ADDR_RTX' and either set |
---|
972 | `RTX_FRAME_RELATED_P' on the prologue insns if you use RTL for the |
---|
973 | prologue, or call `dwarf2out_def_cfa' and `dwarf2out_reg_save' as |
---|
974 | appropriate from `FUNCTION_PROLOGUE' if you don't. |
---|
975 | |
---|
976 | `LINKER_DOES_NOT_WORK_WITH_DWARF2' |
---|
977 | Define this macro if the linker does not work with Dwarf version 2. |
---|
978 | Normally, if the user specifies only `-ggdb' GNU CC will use Dwarf |
---|
979 | version 2 if available; this macro disables this. See the |
---|
980 | description of the `PREFERRED_DEBUGGING_TYPE' macro for more |
---|
981 | details. |
---|
982 | |
---|
983 | `PUT_SDB_...' |
---|
984 | Define these macros to override the assembler syntax for the |
---|
985 | special SDB assembler directives. See `sdbout.c' for a list of |
---|
986 | these macros and their arguments. If the standard syntax is used, |
---|
987 | you need not define them yourself. |
---|
988 | |
---|
989 | `SDB_DELIM' |
---|
990 | Some assemblers do not support a semicolon as a delimiter, even |
---|
991 | between SDB assembler directives. In that case, define this macro |
---|
992 | to be the delimiter to use (usually `\n'). It is not necessary to |
---|
993 | define a new set of `PUT_SDB_OP' macros if this is the only change |
---|
994 | required. |
---|
995 | |
---|
996 | `SDB_GENERATE_FAKE' |
---|
997 | Define this macro to override the usual method of constructing a |
---|
998 | dummy name for anonymous structure and union types. See |
---|
999 | `sdbout.c' for more information. |
---|
1000 | |
---|
1001 | `SDB_ALLOW_UNKNOWN_REFERENCES' |
---|
1002 | Define this macro to allow references to unknown structure, union, |
---|
1003 | or enumeration tags to be emitted. Standard COFF does not allow |
---|
1004 | handling of unknown references, MIPS ECOFF has support for it. |
---|
1005 | |
---|
1006 | `SDB_ALLOW_FORWARD_REFERENCES' |
---|
1007 | Define this macro to allow references to structure, union, or |
---|
1008 | enumeration tags that have not yet been seen to be handled. Some |
---|
1009 | assemblers choke if forward tags are used, while some require it. |
---|
1010 | |
---|
1011 | |
---|
1012 | File: gcc.info, Node: Cross-compilation, Next: Misc, Prev: Debugging Info, Up: Target Macros |
---|
1013 | |
---|
1014 | Cross Compilation and Floating Point |
---|
1015 | ==================================== |
---|
1016 | |
---|
1017 | While all modern machines use 2's complement representation for |
---|
1018 | integers, there are a variety of representations for floating point |
---|
1019 | numbers. This means that in a cross-compiler the representation of |
---|
1020 | floating point numbers in the compiled program may be different from |
---|
1021 | that used in the machine doing the compilation. |
---|
1022 | |
---|
1023 | Because different representation systems may offer different amounts |
---|
1024 | of range and precision, the cross compiler cannot safely use the host |
---|
1025 | machine's floating point arithmetic. Therefore, floating point |
---|
1026 | constants must be represented in the target machine's format. This |
---|
1027 | means that the cross compiler cannot use `atof' to parse a floating |
---|
1028 | point constant; it must have its own special routine to use instead. |
---|
1029 | Also, constant folding must emulate the target machine's arithmetic (or |
---|
1030 | must not be done at all). |
---|
1031 | |
---|
1032 | The macros in the following table should be defined only if you are |
---|
1033 | cross compiling between different floating point formats. |
---|
1034 | |
---|
1035 | Otherwise, don't define them. Then default definitions will be set |
---|
1036 | up which use `double' as the data type, `==' to test for equality, etc. |
---|
1037 | |
---|
1038 | You don't need to worry about how many times you use an operand of |
---|
1039 | any of these macros. The compiler never uses operands which have side |
---|
1040 | effects. |
---|
1041 | |
---|
1042 | `REAL_VALUE_TYPE' |
---|
1043 | A macro for the C data type to be used to hold a floating point |
---|
1044 | value in the target machine's format. Typically this would be a |
---|
1045 | `struct' containing an array of `int'. |
---|
1046 | |
---|
1047 | `REAL_VALUES_EQUAL (X, Y)' |
---|
1048 | A macro for a C expression which compares for equality the two |
---|
1049 | values, X and Y, both of type `REAL_VALUE_TYPE'. |
---|
1050 | |
---|
1051 | `REAL_VALUES_LESS (X, Y)' |
---|
1052 | A macro for a C expression which tests whether X is less than Y, |
---|
1053 | both values being of type `REAL_VALUE_TYPE' and interpreted as |
---|
1054 | floating point numbers in the target machine's representation. |
---|
1055 | |
---|
1056 | `REAL_VALUE_LDEXP (X, SCALE)' |
---|
1057 | A macro for a C expression which performs the standard library |
---|
1058 | function `ldexp', but using the target machine's floating point |
---|
1059 | representation. Both X and the value of the expression have type |
---|
1060 | `REAL_VALUE_TYPE'. The second argument, SCALE, is an integer. |
---|
1061 | |
---|
1062 | `REAL_VALUE_FIX (X)' |
---|
1063 | A macro whose definition is a C expression to convert the |
---|
1064 | target-machine floating point value X to a signed integer. X has |
---|
1065 | type `REAL_VALUE_TYPE'. |
---|
1066 | |
---|
1067 | `REAL_VALUE_UNSIGNED_FIX (X)' |
---|
1068 | A macro whose definition is a C expression to convert the |
---|
1069 | target-machine floating point value X to an unsigned integer. X |
---|
1070 | has type `REAL_VALUE_TYPE'. |
---|
1071 | |
---|
1072 | `REAL_VALUE_RNDZINT (X)' |
---|
1073 | A macro whose definition is a C expression to round the |
---|
1074 | target-machine floating point value X towards zero to an integer |
---|
1075 | value (but still as a floating point number). X has type |
---|
1076 | `REAL_VALUE_TYPE', and so does the value. |
---|
1077 | |
---|
1078 | `REAL_VALUE_UNSIGNED_RNDZINT (X)' |
---|
1079 | A macro whose definition is a C expression to round the |
---|
1080 | target-machine floating point value X towards zero to an unsigned |
---|
1081 | integer value (but still represented as a floating point number). |
---|
1082 | X has type `REAL_VALUE_TYPE', and so does the value. |
---|
1083 | |
---|
1084 | `REAL_VALUE_ATOF (STRING, MODE)' |
---|
1085 | A macro for a C expression which converts STRING, an expression of |
---|
1086 | type `char *', into a floating point number in the target machine's |
---|
1087 | representation for mode MODE. The value has type |
---|
1088 | `REAL_VALUE_TYPE'. |
---|
1089 | |
---|
1090 | `REAL_INFINITY' |
---|
1091 | Define this macro if infinity is a possible floating point value, |
---|
1092 | and therefore division by 0 is legitimate. |
---|
1093 | |
---|
1094 | `REAL_VALUE_ISINF (X)' |
---|
1095 | A macro for a C expression which determines whether X, a floating |
---|
1096 | point value, is infinity. The value has type `int'. By default, |
---|
1097 | this is defined to call `isinf'. |
---|
1098 | |
---|
1099 | `REAL_VALUE_ISNAN (X)' |
---|
1100 | A macro for a C expression which determines whether X, a floating |
---|
1101 | point value, is a "nan" (not-a-number). The value has type `int'. |
---|
1102 | By default, this is defined to call `isnan'. |
---|
1103 | |
---|
1104 | Define the following additional macros if you want to make floating |
---|
1105 | point constant folding work while cross compiling. If you don't define |
---|
1106 | them, cross compilation is still possible, but constant folding will |
---|
1107 | not happen for floating point values. |
---|
1108 | |
---|
1109 | `REAL_ARITHMETIC (OUTPUT, CODE, X, Y)' |
---|
1110 | A macro for a C statement which calculates an arithmetic operation |
---|
1111 | of the two floating point values X and Y, both of type |
---|
1112 | `REAL_VALUE_TYPE' in the target machine's representation, to |
---|
1113 | produce a result of the same type and representation which is |
---|
1114 | stored in OUTPUT (which will be a variable). |
---|
1115 | |
---|
1116 | The operation to be performed is specified by CODE, a tree code |
---|
1117 | which will always be one of the following: `PLUS_EXPR', |
---|
1118 | `MINUS_EXPR', `MULT_EXPR', `RDIV_EXPR', `MAX_EXPR', `MIN_EXPR'. |
---|
1119 | |
---|
1120 | The expansion of this macro is responsible for checking for |
---|
1121 | overflow. If overflow happens, the macro expansion should execute |
---|
1122 | the statement `return 0;', which indicates the inability to |
---|
1123 | perform the arithmetic operation requested. |
---|
1124 | |
---|
1125 | `REAL_VALUE_NEGATE (X)' |
---|
1126 | A macro for a C expression which returns the negative of the |
---|
1127 | floating point value X. Both X and the value of the expression |
---|
1128 | have type `REAL_VALUE_TYPE' and are in the target machine's |
---|
1129 | floating point representation. |
---|
1130 | |
---|
1131 | There is no way for this macro to report overflow, since overflow |
---|
1132 | can't happen in the negation operation. |
---|
1133 | |
---|
1134 | `REAL_VALUE_TRUNCATE (MODE, X)' |
---|
1135 | A macro for a C expression which converts the floating point value |
---|
1136 | X to mode MODE. |
---|
1137 | |
---|
1138 | Both X and the value of the expression are in the target machine's |
---|
1139 | floating point representation and have type `REAL_VALUE_TYPE'. |
---|
1140 | However, the value should have an appropriate bit pattern to be |
---|
1141 | output properly as a floating constant whose precision accords |
---|
1142 | with mode MODE. |
---|
1143 | |
---|
1144 | There is no way for this macro to report overflow. |
---|
1145 | |
---|
1146 | `REAL_VALUE_TO_INT (LOW, HIGH, X)' |
---|
1147 | A macro for a C expression which converts a floating point value X |
---|
1148 | into a double-precision integer which is then stored into LOW and |
---|
1149 | HIGH, two variables of type INT. |
---|
1150 | |
---|
1151 | `REAL_VALUE_FROM_INT (X, LOW, HIGH, MODE)' |
---|
1152 | A macro for a C expression which converts a double-precision |
---|
1153 | integer found in LOW and HIGH, two variables of type INT, into a |
---|
1154 | floating point value which is then stored into X. The value is in |
---|
1155 | the target machine's representation for mode MODE and has the type |
---|
1156 | `REAL_VALUE_TYPE'. |
---|
1157 | |
---|