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