| This is Info file gcc.info, produced by Makeinfo version 1.68 from the |
| input file gcc.texi. |
| |
| This file documents the use and the internals of the GNU compiler. |
| |
| Published by the Free Software Foundation 59 Temple Place - Suite 330 |
| Boston, MA 02111-1307 USA |
| |
| Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided also |
| that the sections entitled "GNU General Public License," "Funding for |
| Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
| included exactly as in the original, and provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions, except that the sections entitled "GNU General Public |
| License," "Funding for Free Software," and "Protect Your Freedom--Fight |
| `Look And Feel'", and this permission notice, may be included in |
| translations approved by the Free Software Foundation instead of in the |
| original English. |
| |
| |
| File: gcc.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format |
| |
| How Initialization Functions Are Handled |
| ---------------------------------------- |
| |
| The compiled code for certain languages includes "constructors" |
| (also called "initialization routines")--functions to initialize data |
| in the program when the program is started. These functions need to be |
| called before the program is "started"--that is to say, before `main' |
| is called. |
| |
| Compiling some languages generates "destructors" (also called |
| "termination routines") that should be called when the program |
| terminates. |
| |
| To make the initialization and termination functions work, the |
| compiler must output something in the assembler code to cause those |
| functions to be called at the appropriate time. When you port the |
| compiler to a new system, you need to specify how to do this. |
| |
| There are two major ways that GCC currently supports the execution of |
| initialization and termination functions. Each way has two variants. |
| Much of the structure is common to all four variations. |
| |
| The linker must build two lists of these functions--a list of |
| initialization functions, called `__CTOR_LIST__', and a list of |
| termination functions, called `__DTOR_LIST__'. |
| |
| Each list always begins with an ignored function pointer (which may |
| hold 0, -1, or a count of the function pointers after it, depending on |
| the environment). This is followed by a series of zero or more function |
| pointers to constructors (or destructors), followed by a function |
| pointer containing zero. |
| |
| Depending on the operating system and its executable file format, |
| either `crtstuff.c' or `libgcc2.c' traverses these lists at startup |
| time and exit time. Constructors are called in reverse order of the |
| list; destructors in forward order. |
| |
| The best way to handle static constructors works only for object file |
| formats which provide arbitrarily-named sections. A section is set |
| aside for a list of constructors, and another for a list of destructors. |
| Traditionally these are called `.ctors' and `.dtors'. Each object file |
| that defines an initialization function also puts a word in the |
| constructor section to point to that function. The linker accumulates |
| all these words into one contiguous `.ctors' section. Termination |
| functions are handled similarly. |
| |
| To use this method, you need appropriate definitions of the macros |
| `ASM_OUTPUT_CONSTRUCTOR' and `ASM_OUTPUT_DESTRUCTOR'. Usually you can |
| get them by including `svr4.h'. |
| |
| When arbitrary sections are available, there are two variants, |
| depending upon how the code in `crtstuff.c' is called. On systems that |
| support an "init" section which is executed at program startup, parts |
| of `crtstuff.c' are compiled into that section. The program is linked |
| by the `gcc' driver like this: |
| |
| ld -o OUTPUT_FILE crtbegin.o ... crtend.o -lgcc |
| |
| The head of a function (`__do_global_ctors') appears in the init |
| section of `crtbegin.o'; the remainder of the function appears in the |
| init section of `crtend.o'. The linker will pull these two parts of |
| the section together, making a whole function. If any of the user's |
| object files linked into the middle of it contribute code, then that |
| code will be executed as part of the body of `__do_global_ctors'. |
| |
| To use this variant, you must define the `INIT_SECTION_ASM_OP' macro |
| properly. |
| |
| If no init section is available, do not define |
| `INIT_SECTION_ASM_OP'. Then `__do_global_ctors' is built into the text |
| section like all other functions, and resides in `libgcc.a'. When GCC |
| compiles any function called `main', it inserts a procedure call to |
| `__main' as the first executable code after the function prologue. The |
| `__main' function, also defined in `libgcc2.c', simply calls |
| `__do_global_ctors'. |
| |
| In file formats that don't support arbitrary sections, there are |
| again two variants. In the simplest variant, the GNU linker (GNU `ld') |
| and an `a.out' format must be used. In this case, |
| `ASM_OUTPUT_CONSTRUCTOR' is defined to produce a `.stabs' entry of type |
| `N_SETT', referencing the name `__CTOR_LIST__', and with the address of |
| the void function containing the initialization code as its value. The |
| GNU linker recognizes this as a request to add the value to a "set"; |
| the values are accumulated, and are eventually placed in the executable |
| as a vector in the format described above, with a leading (ignored) |
| count and a trailing zero element. `ASM_OUTPUT_DESTRUCTOR' is handled |
| similarly. Since no init section is available, the absence of |
| `INIT_SECTION_ASM_OP' causes the compilation of `main' to call `__main' |
| as above, starting the initialization process. |
| |
| The last variant uses neither arbitrary sections nor the GNU linker. |
| This is preferable when you want to do dynamic linking and when using |
| file formats which the GNU linker does not support, such as `ECOFF'. In |
| this case, `ASM_OUTPUT_CONSTRUCTOR' does not produce an `N_SETT' |
| symbol; initialization and termination functions are recognized simply |
| by their names. This requires an extra program in the linkage step, |
| called `collect2'. This program pretends to be the linker, for use |
| with GNU CC; it does its job by running the ordinary linker, but also |
| arranges to include the vectors of initialization and termination |
| functions. These functions are called via `__main' as described above. |
| |
| Choosing among these configuration options has been simplified by a |
| set of operating-system-dependent files in the `config' subdirectory. |
| These files define all of the relevant parameters. Usually it is |
| sufficient to include one into your specific machine-dependent |
| configuration file. These files are: |
| |
| `aoutos.h' |
| For operating systems using the `a.out' format. |
| |
| `next.h' |
| For operating systems using the `MachO' format. |
| |
| `svr3.h' |
| For System V Release 3 and similar systems using `COFF' format. |
| |
| `svr4.h' |
| For System V Release 4 and similar systems using `ELF' format. |
| |
| `vms.h' |
| For the VMS operating system. |
| |
| The following section describes the specific macros that control and |
| customize the handling of initialization and termination functions. |
| |
| |
| File: gcc.info, Node: Macros for Initialization, Next: Instruction Output, Prev: Initialization, Up: Assembler Format |
| |
| Macros Controlling Initialization Routines |
| ------------------------------------------ |
| |
| Here are the macros that control how the compiler handles |
| initialization and termination functions: |
| |
| `INIT_SECTION_ASM_OP' |
| If defined, a C string constant for the assembler operation to |
| identify the following data as initialization code. If not |
| defined, GNU CC will assume such a section does not exist. When |
| you are using special sections for initialization and termination |
| functions, this macro also controls how `crtstuff.c' and |
| `libgcc2.c' arrange to run the initialization functions. |
| |
| `HAS_INIT_SECTION' |
| If defined, `main' will not call `__main' as described above. |
| This macro should be defined for systems that control the contents |
| of the init section on a symbol-by-symbol basis, such as OSF/1, |
| and should not be defined explicitly for systems that support |
| `INIT_SECTION_ASM_OP'. |
| |
| `LD_INIT_SWITCH' |
| If defined, a C string constant for a switch that tells the linker |
| that the following symbol is an initialization routine. |
| |
| `LD_FINI_SWITCH' |
| If defined, a C string constant for a switch that tells the linker |
| that the following symbol is a finalization routine. |
| |
| `INVOKE__main' |
| If defined, `main' will call `__main' despite the presence of |
| `INIT_SECTION_ASM_OP'. This macro should be defined for systems |
| where the init section is not actually run automatically, but is |
| still useful for collecting the lists of constructors and |
| destructors. |
| |
| `ASM_OUTPUT_CONSTRUCTOR (STREAM, NAME)' |
| Define this macro as a C statement to output on the stream STREAM |
| the assembler code to arrange to call the function named NAME at |
| initialization time. |
| |
| Assume that NAME is the name of a C function generated |
| automatically by the compiler. This function takes no arguments. |
| Use the function `assemble_name' to output the name NAME; this |
| performs any system-specific syntactic transformations such as |
| adding an underscore. |
| |
| If you don't define this macro, nothing special is output to |
| arrange to call the function. This is correct when the function |
| will be called in some other manner--for example, by means of the |
| `collect2' program, which looks through the symbol table to find |
| these functions by their names. |
| |
| `ASM_OUTPUT_DESTRUCTOR (STREAM, NAME)' |
| This is like `ASM_OUTPUT_CONSTRUCTOR' but used for termination |
| functions rather than initialization functions. |
| |
| If your system uses `collect2' as the means of processing |
| constructors, then that program normally uses `nm' to scan an object |
| file for constructor functions to be called. On certain kinds of |
| systems, you can define these macros to make `collect2' work faster |
| (and, in some cases, make it work at all): |
| |
| `OBJECT_FORMAT_COFF' |
| Define this macro if the system uses COFF (Common Object File |
| Format) object files, so that `collect2' can assume this format |
| and scan object files directly for dynamic constructor/destructor |
| functions. |
| |
| `OBJECT_FORMAT_ROSE' |
| Define this macro if the system uses ROSE format object files, so |
| that `collect2' can assume this format and scan object files |
| directly for dynamic constructor/destructor functions. |
| |
| These macros are effective only in a native compiler; `collect2' as |
| part of a cross compiler always uses `nm' for the target machine. |
| |
| `REAL_NM_FILE_NAME' |
| Define this macro as a C string constant containing the file name |
| to use to execute `nm'. The default is to search the path |
| normally for `nm'. |
| |
| If your system supports shared libraries and has a program to list |
| the dynamic dependencies of a given library or executable, you can |
| define these macros to enable support for running initialization |
| and termination functions in shared libraries: |
| |
| `LDD_SUFFIX' |
| Define this macro to a C string constant containing the name of the |
| program which lists dynamic dependencies, like `"ldd"' under SunOS |
| 4. |
| |
| `PARSE_LDD_OUTPUT (PTR)' |
| Define this macro to be C code that extracts filenames from the |
| output of the program denoted by `LDD_SUFFIX'. PTR is a variable |
| of type `char *' that points to the beginning of a line of output |
| from `LDD_SUFFIX'. If the line lists a dynamic dependency, the |
| code must advance PTR to the beginning of the filename on that |
| line. Otherwise, it must set PTR to `NULL'. |
| |
| |
| File: gcc.info, Node: Instruction Output, Next: Dispatch Tables, Prev: Macros for Initialization, Up: Assembler Format |
| |
| Output of Assembler Instructions |
| -------------------------------- |
| |
| This describes assembler instruction output. |
| |
| `REGISTER_NAMES' |
| A C initializer containing the assembler's names for the machine |
| registers, each one as a C string constant. This is what |
| translates register numbers in the compiler into assembler |
| language. |
| |
| `ADDITIONAL_REGISTER_NAMES' |
| If defined, a C initializer for an array of structures containing |
| a name and a register number. This macro defines additional names |
| for hard registers, thus allowing the `asm' option in declarations |
| to refer to registers using alternate names. |
| |
| `ASM_OUTPUT_OPCODE (STREAM, PTR)' |
| Define this macro if you are using an unusual assembler that |
| requires different names for the machine instructions. |
| |
| The definition is a C statement or statements which output an |
| assembler instruction opcode to the stdio stream STREAM. The |
| macro-operand PTR is a variable of type `char *' which points to |
| the opcode name in its "internal" form--the form that is written |
| in the machine description. The definition should output the |
| opcode name to STREAM, performing any translation you desire, and |
| increment the variable PTR to point at the end of the opcode so |
| that it will not be output twice. |
| |
| In fact, your macro definition may process less than the entire |
| opcode name, or more than the opcode name; but if you want to |
| process text that includes `%'-sequences to substitute operands, |
| you must take care of the substitution yourself. Just be sure to |
| increment PTR over whatever text should not be output normally. |
| |
| If you need to look at the operand values, they can be found as the |
| elements of `recog_operand'. |
| |
| If the macro definition does nothing, the instruction is output in |
| the usual way. |
| |
| `FINAL_PRESCAN_INSN (INSN, OPVEC, NOPERANDS)' |
| If defined, a C statement to be executed just prior to the output |
| of assembler code for INSN, to modify the extracted operands so |
| they will be output differently. |
| |
| Here the argument OPVEC is the vector containing the operands |
| extracted from INSN, and NOPERANDS is the number of elements of |
| the vector which contain meaningful data for this insn. The |
| contents of this vector are what will be used to convert the insn |
| template into assembler code, so you can change the assembler |
| output by changing the contents of the vector. |
| |
| This macro is useful when various assembler syntaxes share a single |
| file of instruction patterns; by defining this macro differently, |
| you can cause a large class of instructions to be output |
| differently (such as with rearranged operands). Naturally, |
| variations in assembler syntax affecting individual insn patterns |
| ought to be handled by writing conditional output routines in |
| those patterns. |
| |
| If this macro is not defined, it is equivalent to a null statement. |
| |
| `FINAL_PRESCAN_LABEL' |
| If defined, `FINAL_PRESCAN_INSN' will be called on each |
| `CODE_LABEL'. In that case, OPVEC will be a null pointer and |
| NOPERANDS will be zero. |
| |
| `PRINT_OPERAND (STREAM, X, CODE)' |
| A C compound statement to output to stdio stream STREAM the |
| assembler syntax for an instruction operand X. X is an RTL |
| expression. |
| |
| CODE is a value that can be used to specify one of several ways of |
| printing the operand. It is used when identical operands must be |
| printed differently depending on the context. CODE comes from the |
| `%' specification that was used to request printing of the |
| operand. If the specification was just `%DIGIT' then CODE is 0; |
| if the specification was `%LTR DIGIT' then CODE is the ASCII code |
| for LTR. |
| |
| If X is a register, this macro should print the register's name. |
| The names can be found in an array `reg_names' whose type is `char |
| *[]'. `reg_names' is initialized from `REGISTER_NAMES'. |
| |
| When the machine description has a specification `%PUNCT' (a `%' |
| followed by a punctuation character), this macro is called with a |
| null pointer for X and the punctuation character for CODE. |
| |
| `PRINT_OPERAND_PUNCT_VALID_P (CODE)' |
| A C expression which evaluates to true if CODE is a valid |
| punctuation character for use in the `PRINT_OPERAND' macro. If |
| `PRINT_OPERAND_PUNCT_VALID_P' is not defined, it means that no |
| punctuation characters (except for the standard one, `%') are used |
| in this way. |
| |
| `PRINT_OPERAND_ADDRESS (STREAM, X)' |
| A C compound statement to output to stdio stream STREAM the |
| assembler syntax for an instruction operand that is a memory |
| reference whose address is X. X is an RTL expression. |
| |
| On some machines, the syntax for a symbolic address depends on the |
| section that the address refers to. On these machines, define the |
| macro `ENCODE_SECTION_INFO' to store the information into the |
| `symbol_ref', and then check for it here. *Note Assembler |
| Format::. |
| |
| `DBR_OUTPUT_SEQEND(FILE)' |
| A C statement, to be executed after all slot-filler instructions |
| have been output. If necessary, call `dbr_sequence_length' to |
| determine the number of slots filled in a sequence (zero if not |
| currently outputting a sequence), to decide how many no-ops to |
| output, or whatever. |
| |
| Don't define this macro if it has nothing to do, but it is helpful |
| in reading assembly output if the extent of the delay sequence is |
| made explicit (e.g. with white space). |
| |
| Note that output routines for instructions with delay slots must be |
| prepared to deal with not being output as part of a sequence (i.e. |
| when the scheduling pass is not run, or when no slot fillers could |
| be found.) The variable `final_sequence' is null when not |
| processing a sequence, otherwise it contains the `sequence' rtx |
| being output. |
| |
| `REGISTER_PREFIX' |
| `LOCAL_LABEL_PREFIX' |
| `USER_LABEL_PREFIX' |
| `IMMEDIATE_PREFIX' |
| If defined, C string expressions to be used for the `%R', `%L', |
| `%U', and `%I' options of `asm_fprintf' (see `final.c'). These |
| are useful when a single `md' file must support multiple assembler |
| formats. In that case, the various `tm.h' files can define these |
| macros differently. |
| |
| `ASSEMBLER_DIALECT' |
| If your target supports multiple dialects of assembler language |
| (such as different opcodes), define this macro as a C expression |
| that gives the numeric index of the assembler language dialect to |
| use, with zero as the first variant. |
| |
| If this macro is defined, you may use constructs of the form |
| `{option0|option1|option2...}' in the output templates of patterns |
| (*note Output Template::.) or in the first argument of |
| `asm_fprintf'. This construct outputs `option0', `option1' or |
| `option2', etc., if the value of `ASSEMBLER_DIALECT' is zero, one |
| or two, etc. Any special characters within these strings retain |
| their usual meaning. |
| |
| If you do not define this macro, the characters `{', `|' and `}' |
| do not have any special meaning when used in templates or operands |
| to `asm_fprintf'. |
| |
| Define the macros `REGISTER_PREFIX', `LOCAL_LABEL_PREFIX', |
| `USER_LABEL_PREFIX' and `IMMEDIATE_PREFIX' if you can express the |
| variations in assemble language syntax with that mechanism. Define |
| `ASSEMBLER_DIALECT' and use the `{option0|option1}' syntax if the |
| syntax variant are larger and involve such things as different |
| opcodes or operand order. |
| |
| `ASM_OUTPUT_REG_PUSH (STREAM, REGNO)' |
| A C expression to output to STREAM some assembler code which will |
| push hard register number REGNO onto the stack. The code need not |
| be optimal, since this macro is used only when profiling. |
| |
| `ASM_OUTPUT_REG_POP (STREAM, REGNO)' |
| A C expression to output to STREAM some assembler code which will |
| pop hard register number REGNO off of the stack. The code need |
| not be optimal, since this macro is used only when profiling. |
| |
| |
| File: gcc.info, Node: Dispatch Tables, Next: Exception Region Output, Prev: Instruction Output, Up: Assembler Format |
| |
| Output of Dispatch Tables |
| ------------------------- |
| |
| This concerns dispatch tables. |
| |
| `ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, VALUE, REL)' |
| A C statement to output to the stdio stream STREAM an assembler |
| pseudo-instruction to generate a difference between two labels. |
| VALUE and REL are the numbers of two internal labels. The |
| definitions of these labels are output using |
| `ASM_OUTPUT_INTERNAL_LABEL', and they must be printed in the same |
| way here. For example, |
| |
| fprintf (STREAM, "\t.word L%d-L%d\n", |
| VALUE, REL) |
| |
| You must provide this macro on machines where the addresses in a |
| dispatch table are relative to the table's own address. If |
| defined, GNU CC will also use this macro on all machines when |
| producing PIC. |
| |
| `ASM_OUTPUT_ADDR_VEC_ELT (STREAM, VALUE)' |
| This macro should be provided on machines where the addresses in a |
| dispatch table are absolute. |
| |
| The definition should be a C statement to output to the stdio |
| stream STREAM an assembler pseudo-instruction to generate a |
| reference to a label. VALUE is the number of an internal label |
| whose definition is output using `ASM_OUTPUT_INTERNAL_LABEL'. For |
| example, |
| |
| fprintf (STREAM, "\t.word L%d\n", VALUE) |
| |
| `ASM_OUTPUT_CASE_LABEL (STREAM, PREFIX, NUM, TABLE)' |
| Define this if the label before a jump-table needs to be output |
| specially. The first three arguments are the same as for |
| `ASM_OUTPUT_INTERNAL_LABEL'; the fourth argument is the jump-table |
| which follows (a `jump_insn' containing an `addr_vec' or |
| `addr_diff_vec'). |
| |
| This feature is used on system V to output a `swbeg' statement for |
| the table. |
| |
| If this macro is not defined, these labels are output with |
| `ASM_OUTPUT_INTERNAL_LABEL'. |
| |
| `ASM_OUTPUT_CASE_END (STREAM, NUM, TABLE)' |
| Define this if something special must be output at the end of a |
| jump-table. The definition should be a C statement to be executed |
| after the assembler code for the table is written. It should write |
| the appropriate code to stdio stream STREAM. The argument TABLE |
| is the jump-table insn, and NUM is the label-number of the |
| preceding label. |
| |
| If this macro is not defined, nothing special is output at the end |
| of the jump-table. |
| |
| |
| File: gcc.info, Node: Exception Region Output, Next: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format |
| |
| Assembler Commands for Exception Regions |
| ---------------------------------------- |
| |
| This describes commands marking the start and the end of an exception |
| region. |
| |
| `ASM_OUTPUT_EH_REGION_BEG ()' |
| A C expression to output text to mark the start of an exception |
| region. |
| |
| This macro need not be defined on most platforms. |
| |
| `ASM_OUTPUT_EH_REGION_END ()' |
| A C expression to output text to mark the end of an exception |
| region. |
| |
| This macro need not be defined on most platforms. |
| |
| `EXCEPTION_SECTION ()' |
| A C expression to switch to the section in which the main |
| exception table is to be placed (*note Sections::.). The default |
| is a section named `.gcc_except_table' on machines that support |
| named sections via `ASM_OUTPUT_SECTION_NAME', otherwise if `-fpic' |
| or `-fPIC' is in effect, the `data_section', otherwise the |
| `readonly_data_section'. |
| |
| `EH_FRAME_SECTION_ASM_OP' |
| If defined, a C string constant for the assembler operation to |
| switch to the section for exception handling frame unwind |
| information. If not defined, GNU CC will provide a default |
| definition if the target supports named sections. `crtstuff.c' |
| uses this macro to switch to the appropriate section. |
| |
| You should define this symbol if your target supports DWARF 2 frame |
| unwind information and the default definition does not work. |
| |
| `OMIT_EH_TABLE ()' |
| A C expression that is nonzero if the normal exception table output |
| should be omitted. |
| |
| This macro need not be defined on most platforms. |
| |
| `EH_TABLE_LOOKUP ()' |
| Alternate runtime support for looking up an exception at runtime |
| and finding the associated handler, if the default method won't |
| work. |
| |
| This macro need not be defined on most platforms. |
| |
| `DOESNT_NEED_UNWINDER' |
| A C expression that decides whether or not the current function |
| needs to have a function unwinder generated for it. See the file |
| `except.c' for details on when to define this, and how. |
| |
| `MASK_RETURN_ADDR' |
| An rtx used to mask the return address found via RETURN_ADDR_RTX, |
| so that it does not contain any extraneous set bits in it. |
| |
| `DWARF2_UNWIND_INFO' |
| Define this macro to 0 if your target supports DWARF 2 frame unwind |
| information, but it does not yet work with exception handling. |
| Otherwise, if your target supports this information (if it defines |
| `INCOMING_RETURN_ADDR_RTX' and either `UNALIGNED_INT_ASM_OP' or |
| `OBJECT_FORMAT_ELF'), GCC will provide a default definition of 1. |
| |
| If this macro is defined to 1, the DWARF 2 unwinder will be the |
| default exception handling mechanism; otherwise, setjmp/longjmp |
| will be used by default. |
| |
| If this macro is defined to anything, the DWARF 2 unwinder will be |
| used instead of inline unwinders and __unwind_function in the |
| non-setjmp case. |
| |
| |
| File: gcc.info, Node: Alignment Output, Prev: Exception Region Output, Up: Assembler Format |
| |
| Assembler Commands for Alignment |
| -------------------------------- |
| |
| This describes commands for alignment. |
| |
| `ASM_OUTPUT_ALIGN_CODE (FILE)' |
| A C expression to output text to align the location counter in the |
| way that is desirable at a point in the code that is reached only |
| by jumping. |
| |
| This macro need not be defined if you don't want any special |
| alignment to be done at such a time. Most machine descriptions do |
| not currently define the macro. |
| |
| `ASM_OUTPUT_LOOP_ALIGN (FILE)' |
| A C expression to output text to align the location counter in the |
| way that is desirable at the beginning of a loop. |
| |
| This macro need not be defined if you don't want any special |
| alignment to be done at such a time. Most machine descriptions do |
| not currently define the macro. |
| |
| `ASM_OUTPUT_SKIP (STREAM, NBYTES)' |
| A C statement to output to the stdio stream STREAM an assembler |
| instruction to advance the location counter by NBYTES bytes. |
| Those bytes should be zero when loaded. NBYTES will be a C |
| expression of type `int'. |
| |
| `ASM_NO_SKIP_IN_TEXT' |
| Define this macro if `ASM_OUTPUT_SKIP' should not be used in the |
| text section because it fails put zeros in the bytes that are |
| skipped. This is true on many Unix systems, where the pseudo-op |
| to skip bytes produces no-op instructions rather than zeros when |
| used in the text section. |
| |
| `ASM_OUTPUT_ALIGN (STREAM, POWER)' |
| A C statement to output to the stdio stream STREAM an assembler |
| command to advance the location counter to a multiple of 2 to the |
| POWER bytes. POWER will be a C expression of type `int'. |
| |
| |
| File: gcc.info, Node: Debugging Info, Next: Cross-compilation, Prev: Assembler Format, Up: Target Macros |
| |
| Controlling Debugging Information Format |
| ======================================== |
| |
| This describes how to specify debugging information. |
| |
| * Menu: |
| |
| * All Debuggers:: Macros that affect all debugging formats uniformly. |
| * DBX Options:: Macros enabling specific options in DBX format. |
| * DBX Hooks:: Hook macros for varying DBX format. |
| * File Names and DBX:: Macros controlling output of file names in DBX format. |
| * SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. |
| |
| |
| File: gcc.info, Node: All Debuggers, Next: DBX Options, Up: Debugging Info |
| |
| Macros Affecting All Debugging Formats |
| -------------------------------------- |
| |
| These macros affect all debugging formats. |
| |
| `DBX_REGISTER_NUMBER (REGNO)' |
| A C expression that returns the DBX register number for the |
| compiler register number REGNO. In simple cases, the value of this |
| expression may be REGNO itself. But sometimes there are some |
| registers that the compiler knows about and DBX does not, or vice |
| versa. In such cases, some register may need to have one number in |
| the compiler and another for DBX. |
| |
| If two registers have consecutive numbers inside GNU CC, and they |
| can be used as a pair to hold a multiword value, then they *must* |
| have consecutive numbers after renumbering with |
| `DBX_REGISTER_NUMBER'. Otherwise, debuggers will be unable to |
| access such a pair, because they expect register pairs to be |
| consecutive in their own numbering scheme. |
| |
| If you find yourself defining `DBX_REGISTER_NUMBER' in way that |
| does not preserve register pairs, then what you must do instead is |
| redefine the actual register numbering scheme. |
| |
| `DEBUGGER_AUTO_OFFSET (X)' |
| A C expression that returns the integer offset value for an |
| automatic variable having address X (an RTL expression). The |
| default computation assumes that X is based on the frame-pointer |
| and gives the offset from the frame-pointer. This is required for |
| targets that produce debugging output for DBX or COFF-style |
| debugging output for SDB and allow the frame-pointer to be |
| eliminated when the `-g' options is used. |
| |
| `DEBUGGER_ARG_OFFSET (OFFSET, X)' |
| A C expression that returns the integer offset value for an |
| argument having address X (an RTL expression). The nominal offset |
| is OFFSET. |
| |
| `PREFERRED_DEBUGGING_TYPE' |
| A C expression that returns the type of debugging output GNU CC |
| produces when the user specifies `-g' or `-ggdb'. Define this if |
| you have arranged for GNU CC to support more than one format of |
| debugging output. Currently, the allowable values are `DBX_DEBUG', |
| `SDB_DEBUG', `DWARF_DEBUG', `DWARF2_DEBUG', and `XCOFF_DEBUG'. |
| |
| The value of this macro only affects the default debugging output; |
| the user can always get a specific type of output by using |
| `-gstabs', `-gcoff', `-gdwarf-1', `-gdwarf-2', or `-gxcoff'. |
| |
| |
| File: gcc.info, Node: DBX Options, Next: DBX Hooks, Prev: All Debuggers, Up: Debugging Info |
| |
| Specific Options for DBX Output |
| ------------------------------- |
| |
| These are specific options for DBX output. |
| |
| `DBX_DEBUGGING_INFO' |
| Define this macro if GNU CC should produce debugging output for DBX |
| in response to the `-g' option. |
| |
| `XCOFF_DEBUGGING_INFO' |
| Define this macro if GNU CC should produce XCOFF format debugging |
| output in response to the `-g' option. This is a variant of DBX |
| format. |
| |
| `DEFAULT_GDB_EXTENSIONS' |
| Define this macro to control whether GNU CC should by default |
| generate GDB's extended version of DBX debugging information |
| (assuming DBX-format debugging information is enabled at all). If |
| you don't define the macro, the default is 1: always generate the |
| extended information if there is any occasion to. |
| |
| `DEBUG_SYMS_TEXT' |
| Define this macro if all `.stabs' commands should be output while |
| in the text section. |
| |
| `ASM_STABS_OP' |
| A C string constant naming the assembler pseudo op to use instead |
| of `.stabs' to define an ordinary debugging symbol. If you don't |
| define this macro, `.stabs' is used. This macro applies only to |
| DBX debugging information format. |
| |
| `ASM_STABD_OP' |
| A C string constant naming the assembler pseudo op to use instead |
| of `.stabd' to define a debugging symbol whose value is the current |
| location. If you don't define this macro, `.stabd' is used. This |
| macro applies only to DBX debugging information format. |
| |
| `ASM_STABN_OP' |
| A C string constant naming the assembler pseudo op to use instead |
| of `.stabn' to define a debugging symbol with no name. If you |
| don't define this macro, `.stabn' is used. This macro applies |
| only to DBX debugging information format. |
| |
| `DBX_NO_XREFS' |
| Define this macro if DBX on your system does not support the |
| construct `xsTAGNAME'. On some systems, this construct is used to |
| describe a forward reference to a structure named TAGNAME. On |
| other systems, this construct is not supported at all. |
| |
| `DBX_CONTIN_LENGTH' |
| A symbol name in DBX-format debugging information is normally |
| continued (split into two separate `.stabs' directives) when it |
| exceeds a certain length (by default, 80 characters). On some |
| operating systems, DBX requires this splitting; on others, |
| splitting must not be done. You can inhibit splitting by defining |
| this macro with the value zero. You can override the default |
| splitting-length by defining this macro as an expression for the |
| length you desire. |
| |
| `DBX_CONTIN_CHAR' |
| Normally continuation is indicated by adding a `\' character to |
| the end of a `.stabs' string when a continuation follows. To use |
| a different character instead, define this macro as a character |
| constant for the character you want to use. Do not define this |
| macro if backslash is correct for your system. |
| |
| `DBX_STATIC_STAB_DATA_SECTION' |
| Define this macro if it is necessary to go to the data section |
| before outputting the `.stabs' pseudo-op for a non-global static |
| variable. |
| |
| `DBX_TYPE_DECL_STABS_CODE' |
| The value to use in the "code" field of the `.stabs' directive for |
| a typedef. The default is `N_LSYM'. |
| |
| `DBX_STATIC_CONST_VAR_CODE' |
| The value to use in the "code" field of the `.stabs' directive for |
| a static variable located in the text section. DBX format does not |
| provide any "right" way to do this. The default is `N_FUN'. |
| |
| `DBX_REGPARM_STABS_CODE' |
| The value to use in the "code" field of the `.stabs' directive for |
| a parameter passed in registers. DBX format does not provide any |
| "right" way to do this. The default is `N_RSYM'. |
| |
| `DBX_REGPARM_STABS_LETTER' |
| The letter to use in DBX symbol data to identify a symbol as a |
| parameter passed in registers. DBX format does not customarily |
| provide any way to do this. The default is `'P''. |
| |
| `DBX_MEMPARM_STABS_LETTER' |
| The letter to use in DBX symbol data to identify a symbol as a |
| stack parameter. The default is `'p''. |
| |
| `DBX_FUNCTION_FIRST' |
| Define this macro if the DBX information for a function and its |
| arguments should precede the assembler code for the function. |
| Normally, in DBX format, the debugging information entirely |
| follows the assembler code. |
| |
| `DBX_LBRAC_FIRST' |
| Define this macro if the `N_LBRAC' symbol for a block should |
| precede the debugging information for variables and functions |
| defined in that block. Normally, in DBX format, the `N_LBRAC' |
| symbol comes first. |
| |
| `DBX_BLOCKS_FUNCTION_RELATIVE' |
| Define this macro if the value of a symbol describing the scope of |
| a block (`N_LBRAC' or `N_RBRAC') should be relative to the start |
| of the enclosing function. Normally, GNU C uses an absolute |
| address. |
| |
| `DBX_USE_BINCL' |
| Define this macro if GNU C should generate `N_BINCL' and `N_EINCL' |
| stabs for included header files, as on Sun systems. This macro |
| also directs GNU C to output a type number as a pair of a file |
| number and a type number within the file. Normally, GNU C does not |
| generate `N_BINCL' or `N_EINCL' stabs, and it outputs a single |
| number for a type number. |
| |
| |
| File: gcc.info, Node: DBX Hooks, Next: File Names and DBX, Prev: DBX Options, Up: Debugging Info |
| |
| Open-Ended Hooks for DBX Format |
| ------------------------------- |
| |
| These are hooks for DBX format. |
| |
| `DBX_OUTPUT_LBRAC (STREAM, NAME)' |
| Define this macro to say how to output to STREAM the debugging |
| information for the start of a scope level for variable names. The |
| argument NAME is the name of an assembler symbol (for use with |
| `assemble_name') whose value is the address where the scope begins. |
| |
| `DBX_OUTPUT_RBRAC (STREAM, NAME)' |
| Like `DBX_OUTPUT_LBRAC', but for the end of a scope level. |
| |
| `DBX_OUTPUT_ENUM (STREAM, TYPE)' |
| Define this macro if the target machine requires special handling |
| to output an enumeration type. The definition should be a C |
| statement (sans semicolon) to output the appropriate information |
| to STREAM for the type TYPE. |
| |
| `DBX_OUTPUT_FUNCTION_END (STREAM, FUNCTION)' |
| Define this macro if the target machine requires special output at |
| the end of the debugging information for a function. The |
| definition should be a C statement (sans semicolon) to output the |
| appropriate information to STREAM. FUNCTION is the |
| `FUNCTION_DECL' node for the function. |
| |
| `DBX_OUTPUT_STANDARD_TYPES (SYMS)' |
| Define this macro if you need to control the order of output of the |
| standard data types at the beginning of compilation. The argument |
| SYMS is a `tree' which is a chain of all the predefined global |
| symbols, including names of data types. |
| |
| Normally, DBX output starts with definitions of the types for |
| integers and characters, followed by all the other predefined |
| types of the particular language in no particular order. |
| |
| On some machines, it is necessary to output different particular |
| types first. To do this, define `DBX_OUTPUT_STANDARD_TYPES' to |
| output those symbols in the necessary order. Any predefined types |
| that you don't explicitly output will be output afterward in no |
| particular order. |
| |
| Be careful not to define this macro so that it works only for C. |
| There are no global variables to access most of the built-in |
| types, because another language may have another set of types. |
| The way to output a particular type is to look through SYMS to see |
| if you can find it. Here is an example: |
| |
| { |
| tree decl; |
| for (decl = syms; decl; decl = TREE_CHAIN (decl)) |
| if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), |
| "long int")) |
| dbxout_symbol (decl); |
| ... |
| } |
| |
| This does nothing if the expected type does not exist. |
| |
| See the function `init_decl_processing' in `c-decl.c' to find the |
| names to use for all the built-in C types. |
| |
| Here is another way of finding a particular type: |
| |
| { |
| tree decl; |
| for (decl = syms; decl; decl = TREE_CHAIN (decl)) |
| if (TREE_CODE (decl) == TYPE_DECL |
| && (TREE_CODE (TREE_TYPE (decl)) |
| == INTEGER_CST) |
| && TYPE_PRECISION (TREE_TYPE (decl)) == 16 |
| && TYPE_UNSIGNED (TREE_TYPE (decl))) |
| /* This must be `unsigned short'. */ |
| dbxout_symbol (decl); |
| ... |
| } |
| |
| `NO_DBX_FUNCTION_END' |
| Some stabs encapsulation formats (in particular ECOFF), cannot |
| handle the `.stabs "",N_FUN,,0,0,Lscope-function-1' gdb dbx |
| extention construct. On those machines, define this macro to turn |
| this feature off without disturbing the rest of the gdb extensions. |
| |
| |
| File: gcc.info, Node: File Names and DBX, Next: SDB and DWARF, Prev: DBX Hooks, Up: Debugging Info |
| |
| File Names in DBX Format |
| ------------------------ |
| |
| This describes file names in DBX format. |
| |
| `DBX_WORKING_DIRECTORY' |
| Define this if DBX wants to have the current directory recorded in |
| each object file. |
| |
| Note that the working directory is always recorded if GDB |
| extensions are enabled. |
| |
| `DBX_OUTPUT_MAIN_SOURCE_FILENAME (STREAM, NAME)' |
| A C statement to output DBX debugging information to the stdio |
| stream STREAM which indicates that file NAME is the main source |
| file--the file specified as the input file for compilation. This |
| macro is called only once, at the beginning of compilation. |
| |
| This macro need not be defined if the standard form of output for |
| DBX debugging information is appropriate. |
| |
| `DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (STREAM, NAME)' |
| A C statement to output DBX debugging information to the stdio |
| stream STREAM which indicates that the current directory during |
| compilation is named NAME. |
| |
| This macro need not be defined if the standard form of output for |
| DBX debugging information is appropriate. |
| |
| `DBX_OUTPUT_MAIN_SOURCE_FILE_END (STREAM, NAME)' |
| A C statement to output DBX debugging information at the end of |
| compilation of the main source file NAME. |
| |
| If you don't define this macro, nothing special is output at the |
| end of compilation, which is correct for most machines. |
| |
| `DBX_OUTPUT_SOURCE_FILENAME (STREAM, NAME)' |
| A C statement to output DBX debugging information to the stdio |
| stream STREAM which indicates that file NAME is the current source |
| file. This output is generated each time input shifts to a |
| different source file as a result of `#include', the end of an |
| included file, or a `#line' command. |
| |
| This macro need not be defined if the standard form of output for |
| DBX debugging information is appropriate. |
| |
| |
| File: gcc.info, Node: SDB and DWARF, Prev: File Names and DBX, Up: Debugging Info |
| |
| Macros for SDB and DWARF Output |
| ------------------------------- |
| |
| Here are macros for SDB and DWARF output. |
| |
| `SDB_DEBUGGING_INFO' |
| Define this macro if GNU CC should produce COFF-style debugging |
| output for SDB in response to the `-g' option. |
| |
| `DWARF_DEBUGGING_INFO' |
| Define this macro if GNU CC should produce dwarf format debugging |
| output in response to the `-g' option. |
| |
| `DWARF2_DEBUGGING_INFO' |
| Define this macro if GNU CC should produce dwarf version 2 format |
| debugging output in response to the `-g' option. |
| |
| To support optional call frame debugging information, you must also |
| define `INCOMING_RETURN_ADDR_RTX' and either set |
| `RTX_FRAME_RELATED_P' on the prologue insns if you use RTL for the |
| prologue, or call `dwarf2out_def_cfa' and `dwarf2out_reg_save' as |
| appropriate from `FUNCTION_PROLOGUE' if you don't. |
| |
| `PUT_SDB_...' |
| Define these macros to override the assembler syntax for the |
| special SDB assembler directives. See `sdbout.c' for a list of |
| these macros and their arguments. If the standard syntax is used, |
| you need not define them yourself. |
| |
| `SDB_DELIM' |
| Some assemblers do not support a semicolon as a delimiter, even |
| between SDB assembler directives. In that case, define this macro |
| to be the delimiter to use (usually `\n'). It is not necessary to |
| define a new set of `PUT_SDB_OP' macros if this is the only change |
| required. |
| |
| `SDB_GENERATE_FAKE' |
| Define this macro to override the usual method of constructing a |
| dummy name for anonymous structure and union types. See |
| `sdbout.c' for more information. |
| |
| `SDB_ALLOW_UNKNOWN_REFERENCES' |
| Define this macro to allow references to unknown structure, union, |
| or enumeration tags to be emitted. Standard COFF does not allow |
| handling of unknown references, MIPS ECOFF has support for it. |
| |
| `SDB_ALLOW_FORWARD_REFERENCES' |
| Define this macro to allow references to structure, union, or |
| enumeration tags that have not yet been seen to be handled. Some |
| assemblers choke if forward tags are used, while some require it. |
| |
| |
| File: gcc.info, Node: Cross-compilation, Next: Misc, Prev: Debugging Info, Up: Target Macros |
| |
| Cross Compilation and Floating Point |
| ==================================== |
| |
| While all modern machines use 2's complement representation for |
| integers, there are a variety of representations for floating point |
| numbers. This means that in a cross-compiler the representation of |
| floating point numbers in the compiled program may be different from |
| that used in the machine doing the compilation. |
| |
| Because different representation systems may offer different amounts |
| of range and precision, the cross compiler cannot safely use the host |
| machine's floating point arithmetic. Therefore, floating point |
| constants must be represented in the target machine's format. This |
| means that the cross compiler cannot use `atof' to parse a floating |
| point constant; it must have its own special routine to use instead. |
| Also, constant folding must emulate the target machine's arithmetic (or |
| must not be done at all). |
| |
| The macros in the following table should be defined only if you are |
| cross compiling between different floating point formats. |
| |
| Otherwise, don't define them. Then default definitions will be set |
| up which use `double' as the data type, `==' to test for equality, etc. |
| |
| You don't need to worry about how many times you use an operand of |
| any of these macros. The compiler never uses operands which have side |
| effects. |
| |
| `REAL_VALUE_TYPE' |
| A macro for the C data type to be used to hold a floating point |
| value in the target machine's format. Typically this would be a |
| `struct' containing an array of `int'. |
| |
| `REAL_VALUES_EQUAL (X, Y)' |
| A macro for a C expression which compares for equality the two |
| values, X and Y, both of type `REAL_VALUE_TYPE'. |
| |
| `REAL_VALUES_LESS (X, Y)' |
| A macro for a C expression which tests whether X is less than Y, |
| both values being of type `REAL_VALUE_TYPE' and interpreted as |
| floating point numbers in the target machine's representation. |
| |
| `REAL_VALUE_LDEXP (X, SCALE)' |
| A macro for a C expression which performs the standard library |
| function `ldexp', but using the target machine's floating point |
| representation. Both X and the value of the expression have type |
| `REAL_VALUE_TYPE'. The second argument, SCALE, is an integer. |
| |
| `REAL_VALUE_FIX (X)' |
| A macro whose definition is a C expression to convert the |
| target-machine floating point value X to a signed integer. X has |
| type `REAL_VALUE_TYPE'. |
| |
| `REAL_VALUE_UNSIGNED_FIX (X)' |
| A macro whose definition is a C expression to convert the |
| target-machine floating point value X to an unsigned integer. X |
| has type `REAL_VALUE_TYPE'. |
| |
| `REAL_VALUE_RNDZINT (X)' |
| A macro whose definition is a C expression to round the |
| target-machine floating point value X towards zero to an integer |
| value (but still as a floating point number). X has type |
| `REAL_VALUE_TYPE', and so does the value. |
| |
| `REAL_VALUE_UNSIGNED_RNDZINT (X)' |
| A macro whose definition is a C expression to round the |
| target-machine floating point value X towards zero to an unsigned |
| integer value (but still represented as a floating point number). |
| X has type `REAL_VALUE_TYPE', and so does the value. |
| |
| `REAL_VALUE_ATOF (STRING, MODE)' |
| A macro for a C expression which converts STRING, an expression of |
| type `char *', into a floating point number in the target machine's |
| representation for mode MODE. The value has type |
| `REAL_VALUE_TYPE'. |
| |
| `REAL_INFINITY' |
| Define this macro if infinity is a possible floating point value, |
| and therefore division by 0 is legitimate. |
| |
| `REAL_VALUE_ISINF (X)' |
| A macro for a C expression which determines whether X, a floating |
| point value, is infinity. The value has type `int'. By default, |
| this is defined to call `isinf'. |
| |
| `REAL_VALUE_ISNAN (X)' |
| A macro for a C expression which determines whether X, a floating |
| point value, is a "nan" (not-a-number). The value has type `int'. |
| By default, this is defined to call `isnan'. |
| |
| Define the following additional macros if you want to make floating |
| point constant folding work while cross compiling. If you don't define |
| them, cross compilation is still possible, but constant folding will |
| not happen for floating point values. |
| |
| `REAL_ARITHMETIC (OUTPUT, CODE, X, Y)' |
| A macro for a C statement which calculates an arithmetic operation |
| of the two floating point values X and Y, both of type |
| `REAL_VALUE_TYPE' in the target machine's representation, to |
| produce a result of the same type and representation which is |
| stored in OUTPUT (which will be a variable). |
| |
| The operation to be performed is specified by CODE, a tree code |
| which will always be one of the following: `PLUS_EXPR', |
| `MINUS_EXPR', `MULT_EXPR', `RDIV_EXPR', `MAX_EXPR', `MIN_EXPR'. |
| |
| The expansion of this macro is responsible for checking for |
| overflow. If overflow happens, the macro expansion should execute |
| the statement `return 0;', which indicates the inability to |
| perform the arithmetic operation requested. |
| |
| `REAL_VALUE_NEGATE (X)' |
| A macro for a C expression which returns the negative of the |
| floating point value X. Both X and the value of the expression |
| have type `REAL_VALUE_TYPE' and are in the target machine's |
| floating point representation. |
| |
| There is no way for this macro to report overflow, since overflow |
| can't happen in the negation operation. |
| |
| `REAL_VALUE_TRUNCATE (MODE, X)' |
| A macro for a C expression which converts the floating point value |
| X to mode MODE. |
| |
| Both X and the value of the expression are in the target machine's |
| floating point representation and have type `REAL_VALUE_TYPE'. |
| However, the value should have an appropriate bit pattern to be |
| output properly as a floating constant whose precision accords |
| with mode MODE. |
| |
| There is no way for this macro to report overflow. |
| |
| `REAL_VALUE_TO_INT (LOW, HIGH, X)' |
| A macro for a C expression which converts a floating point value X |
| into a double-precision integer which is then stored into LOW and |
| HIGH, two variables of type INT. |
| |
| `REAL_VALUE_FROM_INT (X, LOW, HIGH, MODE)' |
| A macro for a C expression which converts a double-precision |
| integer found in LOW and HIGH, two variables of type INT, into a |
| floating point value which is then stored into X. The value is in |
| the target machine's representation for mode MODE and has the type |
| `REAL_VALUE_TYPE'. |
| |