[11287] | 1 | This is Info file gcc.info, produced by Makeinfo version 1.67 from the |
---|
| 2 | input file gcc.texi. |
---|
[8833] | 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 | |
---|
[11287] | 9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
---|
| 10 | Free Software Foundation, Inc. |
---|
[8833] | 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 | |
---|
[11287] | 33 | File: gcc.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format |
---|
[8833] | 34 | |
---|
[11287] | 35 | How Initialization Functions Are Handled |
---|
| 36 | ---------------------------------------- |
---|
[8833] | 37 | |
---|
[11287] | 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 | |
---|
[8833] | 624 | * Menu: |
---|
| 625 | |
---|
[11287] | 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. |
---|
[8833] | 631 | |
---|
[11287] | 632 | |
---|
| 633 | File: gcc.info, Node: All Debuggers, Next: DBX Options, Up: Debugging Info |
---|
[8833] | 634 | |
---|
[11287] | 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 | |
---|