source: trunk/third/gcc/gcc.info-22 @ 8834

Revision 8834, 49.1 KB checked in by ghudson, 28 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r8833, which included commits to RCS files with non-trunk default branches.
Line 
1This is Info file gcc.info, produced by Makeinfo-1.55 from the input
2file 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
7Boston, MA 02111-1307 USA
8
9   Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software
10Foundation, Inc.
11
12   Permission is granted to make and distribute verbatim copies of this
13manual provided the copyright notice and this permission notice are
14preserved on all copies.
15
16   Permission is granted to copy and distribute modified versions of
17this manual under the conditions for verbatim copying, provided also
18that the sections entitled "GNU General Public License," "Funding for
19Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20included exactly as in the original, and provided that the entire
21resulting derived work is distributed under the terms of a permission
22notice identical to this one.
23
24   Permission is granted to copy and distribute translations of this
25manual into another language, under the above conditions for modified
26versions, except that the sections entitled "GNU General Public
27License," "Funding for Free Software," and "Protect Your Freedom--Fight
28`Look And Feel'", and this permission notice, may be included in
29translations approved by the Free Software Foundation instead of in the
30original English.
31
32
33File: gcc.info,  Node: Library Calls,  Next: Addressing Modes,  Prev: Trampolines,  Up: Target Macros
34
35Implicit Calls to Library Routines
36==================================
37
38   Here is an explanation of implicit calls to library routines.
39
40`MULSI3_LIBCALL'
41     A C string constant giving the name of the function to call for
42     multiplication of one signed full-word by another.  If you do not
43     define this macro, the default name is used, which is `__mulsi3',
44     a function defined in `libgcc.a'.
45
46`DIVSI3_LIBCALL'
47     A C string constant giving the name of the function to call for
48     division of one signed full-word by another.  If you do not define
49     this macro, the default name is used, which is `__divsi3', a
50     function defined in `libgcc.a'.
51
52`UDIVSI3_LIBCALL'
53     A C string constant giving the name of the function to call for
54     division of one unsigned full-word by another.  If you do not
55     define this macro, the default name is used, which is `__udivsi3',
56     a function defined in `libgcc.a'.
57
58`MODSI3_LIBCALL'
59     A C string constant giving the name of the function to call for the
60     remainder in division of one signed full-word by another.  If you
61     do not define this macro, the default name is used, which is
62     `__modsi3', a function defined in `libgcc.a'.
63
64`UMODSI3_LIBCALL'
65     A C string constant giving the name of the function to call for the
66     remainder in division of one unsigned full-word by another.  If
67     you do not define this macro, the default name is used, which is
68     `__umodsi3', a function defined in `libgcc.a'.
69
70`MULDI3_LIBCALL'
71     A C string constant giving the name of the function to call for
72     multiplication of one signed double-word by another.  If you do not
73     define this macro, the default name is used, which is `__muldi3',
74     a function defined in `libgcc.a'.
75
76`DIVDI3_LIBCALL'
77     A C string constant giving the name of the function to call for
78     division of one signed double-word by another.  If you do not
79     define this macro, the default name is used, which is `__divdi3', a
80     function defined in `libgcc.a'.
81
82`UDIVDI3_LIBCALL'
83     A C string constant giving the name of the function to call for
84     division of one unsigned full-word by another.  If you do not
85     define this macro, the default name is used, which is `__udivdi3',
86     a function defined in `libgcc.a'.
87
88`MODDI3_LIBCALL'
89     A C string constant giving the name of the function to call for the
90     remainder in division of one signed double-word by another.  If
91     you do not define this macro, the default name is used, which is
92     `__moddi3', a function defined in `libgcc.a'.
93
94`UMODDI3_LIBCALL'
95     A C string constant giving the name of the function to call for the
96     remainder in division of one unsigned full-word by another.  If
97     you do not define this macro, the default name is used, which is
98     `__umoddi3', a function defined in `libgcc.a'.
99
100`INIT_TARGET_OPTABS'
101     Define this macro as a C statement that declares additional library
102     routines renames existing ones. `init_optabs' calls this macro
103     after initializing all the normal library routines.
104
105`TARGET_EDOM'
106     The value of `EDOM' on the target machine, as a C integer constant
107     expression.  If you don't define this macro, GNU CC does not
108     attempt to deposit the value of `EDOM' into `errno' directly.
109     Look in `/usr/include/errno.h' to find the value of `EDOM' on your
110     system.
111
112     If you do not define `TARGET_EDOM', then compiled code reports
113     domain errors by calling the library function and letting it
114     report the error.  If mathematical functions on your system use
115     `matherr' when there is an error, then you should leave
116     `TARGET_EDOM' undefined so that `matherr' is used normally.
117
118`GEN_ERRNO_RTX'
119     Define this macro as a C expression to create an rtl expression
120     that refers to the global "variable" `errno'.  (On certain systems,
121     `errno' may not actually be a variable.)  If you don't define this
122     macro, a reasonable default is used.
123
124`TARGET_MEM_FUNCTIONS'
125     Define this macro if GNU CC should generate calls to the System V
126     (and ANSI C) library functions `memcpy' and `memset' rather than
127     the BSD functions `bcopy' and `bzero'.
128
129`LIBGCC_NEEDS_DOUBLE'
130     Define this macro if only `float' arguments cannot be passed to
131     library routines (so they must be converted to `double').  This
132     macro affects both how library calls are generated and how the
133     library routines in `libgcc1.c' accept their arguments.  It is
134     useful on machines where floating and fixed point arguments are
135     passed differently, such as the i860.
136
137`FLOAT_ARG_TYPE'
138     Define this macro to override the type used by the library
139     routines to pick up arguments of type `float'.  (By default, they
140     use a union of `float' and `int'.)
141
142     The obvious choice would be `float'--but that won't work with
143     traditional C compilers that expect all arguments declared as
144     `float' to arrive as `double'.  To avoid this conversion, the
145     library routines ask for the value as some other type and then
146     treat it as a `float'.
147
148     On some systems, no other type will work for this.  For these
149     systems, you must use `LIBGCC_NEEDS_DOUBLE' instead, to force
150     conversion of the values `double' before they are passed.
151
152`FLOATIFY (PASSED-VALUE)'
153     Define this macro to override the way library routines redesignate
154     a `float' argument as a `float' instead of the type it was passed
155     as.  The default is an expression which takes the `float' field of
156     the union.
157
158`FLOAT_VALUE_TYPE'
159     Define this macro to override the type used by the library
160     routines to return values that ought to have type `float'.  (By
161     default, they use `int'.)
162
163     The obvious choice would be `float'--but that won't work with
164     traditional C compilers gratuitously convert values declared as
165     `float' into `double'.
166
167`INTIFY (FLOAT-VALUE)'
168     Define this macro to override the way the value of a
169     `float'-returning library routine should be packaged in order to
170     return it.  These functions are actually declared to return type
171     `FLOAT_VALUE_TYPE' (normally `int').
172
173     These values can't be returned as type `float' because traditional
174     C compilers would gratuitously convert the value to a `double'.
175
176     A local variable named `intify' is always available when the macro
177     `INTIFY' is used.  It is a union of a `float' field named `f' and
178     a field named `i' whose type is `FLOAT_VALUE_TYPE' or `int'.
179
180     If you don't define this macro, the default definition works by
181     copying the value through that union.
182
183`nongcc_SI_type'
184     Define this macro as the name of the data type corresponding to
185     `SImode' in the system's own C compiler.
186
187     You need not define this macro if that type is `long int', as it
188     usually is.
189
190`nongcc_word_type'
191     Define this macro as the name of the data type corresponding to the
192     word_mode in the system's own C compiler.
193
194     You need not define this macro if that type is `long int', as it
195     usually is.
196
197`perform_...'
198     Define these macros to supply explicit C statements to carry out
199     various arithmetic operations on types `float' and `double' in the
200     library routines in `libgcc1.c'.  See that file for a full list of
201     these macros and their arguments.
202
203     On most machines, you don't need to define any of these macros,
204     because the C compiler that comes with the system takes care of
205     doing them.
206
207`NEXT_OBJC_RUNTIME'
208     Define this macro to generate code for Objective C message sending
209     using the calling convention of the NeXT system.  This calling
210     convention involves passing the object, the selector and the
211     method arguments all at once to the method-lookup library function.
212
213     The default calling convention passes just the object and the
214     selector to the lookup function, which returns a pointer to the
215     method.
216
217
218File: gcc.info,  Node: Addressing Modes,  Next: Condition Code,  Prev: Library Calls,  Up: Target Macros
219
220Addressing Modes
221================
222
223   This is about addressing modes.
224
225`HAVE_POST_INCREMENT'
226     Define this macro if the machine supports post-increment
227     addressing.
228
229`HAVE_PRE_INCREMENT'
230`HAVE_POST_DECREMENT'
231`HAVE_PRE_DECREMENT'
232     Similar for other kinds of addressing.
233
234`CONSTANT_ADDRESS_P (X)'
235     A C expression that is 1 if the RTX X is a constant which is a
236     valid address.  On most machines, this can be defined as
237     `CONSTANT_P (X)', but a few machines are more restrictive in which
238     constant addresses are supported.
239
240     `CONSTANT_P' accepts integer-values expressions whose values are
241     not explicitly known, such as `symbol_ref', `label_ref', and
242     `high' expressions and `const' arithmetic expressions, in addition
243     to `const_int' and `const_double' expressions.
244
245`MAX_REGS_PER_ADDRESS'
246     A number, the maximum number of registers that can appear in a
247     valid memory address.  Note that it is up to you to specify a
248     value equal to the maximum number that `GO_IF_LEGITIMATE_ADDRESS'
249     would ever accept.
250
251`GO_IF_LEGITIMATE_ADDRESS (MODE, X, LABEL)'
252     A C compound statement with a conditional `goto LABEL;' executed
253     if X (an RTX) is a legitimate memory address on the target machine
254     for a memory operand of mode MODE.
255
256     It usually pays to define several simpler macros to serve as
257     subroutines for this one.  Otherwise it may be too complicated to
258     understand.
259
260     This macro must exist in two variants: a strict variant and a
261     non-strict one.  The strict variant is used in the reload pass.  It
262     must be defined so that any pseudo-register that has not been
263     allocated a hard register is considered a memory reference.  In
264     contexts where some kind of register is required, a pseudo-register
265     with no hard register must be rejected.
266
267     The non-strict variant is used in other passes.  It must be
268     defined to accept all pseudo-registers in every context where some
269     kind of register is required.
270
271     Compiler source files that want to use the strict variant of this
272     macro define the macro `REG_OK_STRICT'.  You should use an `#ifdef
273     REG_OK_STRICT' conditional to define the strict variant in that
274     case and the non-strict variant otherwise.
275
276     Subroutines to check for acceptable registers for various purposes
277     (one for base registers, one for index registers, and so on) are
278     typically among the subroutines used to define
279     `GO_IF_LEGITIMATE_ADDRESS'.  Then only these subroutine macros
280     need have two variants; the higher levels of macros may be the
281     same whether strict or not.
282
283     Normally, constant addresses which are the sum of a `symbol_ref'
284     and an integer are stored inside a `const' RTX to mark them as
285     constant.  Therefore, there is no need to recognize such sums
286     specifically as legitimate addresses.  Normally you would simply
287     recognize any `const' as legitimate.
288
289     Usually `PRINT_OPERAND_ADDRESS' is not prepared to handle constant
290     sums that are not marked with  `const'.  It assumes that a naked
291     `plus' indicates indexing.  If so, then you *must* reject such
292     naked constant sums as illegitimate addresses, so that none of
293     them will be given to `PRINT_OPERAND_ADDRESS'.
294
295     On some machines, whether a symbolic address is legitimate depends
296     on the section that the address refers to.  On these machines,
297     define the macro `ENCODE_SECTION_INFO' to store the information
298     into the `symbol_ref', and then check for it here.  When you see a
299     `const', you will have to look inside it to find the `symbol_ref'
300     in order to determine the section.  *Note Assembler Format::.
301
302     The best way to modify the name string is by adding text to the
303     beginning, with suitable punctuation to prevent any ambiguity.
304     Allocate the new name in `saveable_obstack'.  You will have to
305     modify `ASM_OUTPUT_LABELREF' to remove and decode the added text
306     and output the name accordingly, and define `STRIP_NAME_ENCODING'
307     to access the original name string.
308
309     You can check the information stored here into the `symbol_ref' in
310     the definitions of the macros `GO_IF_LEGITIMATE_ADDRESS' and
311     `PRINT_OPERAND_ADDRESS'.
312
313`REG_OK_FOR_BASE_P (X)'
314     A C expression that is nonzero if X (assumed to be a `reg' RTX) is
315     valid for use as a base register.  For hard registers, it should
316     always accept those which the hardware permits and reject the
317     others.  Whether the macro accepts or rejects pseudo registers
318     must be controlled by `REG_OK_STRICT' as described above.  This
319     usually requires two variant definitions, of which `REG_OK_STRICT'
320     controls the one actually used.
321
322`REG_OK_FOR_INDEX_P (X)'
323     A C expression that is nonzero if X (assumed to be a `reg' RTX) is
324     valid for use as an index register.
325
326     The difference between an index register and a base register is
327     that the index register may be scaled.  If an address involves the
328     sum of two registers, neither one of them scaled, then either one
329     may be labeled the "base" and the other the "index"; but whichever
330     labeling is used must fit the machine's constraints of which
331     registers may serve in each capacity.  The compiler will try both
332     labelings, looking for one that is valid, and will reload one or
333     both registers only if neither labeling works.
334
335`LEGITIMIZE_ADDRESS (X, OLDX, MODE, WIN)'
336     A C compound statement that attempts to replace X with a valid
337     memory address for an operand of mode MODE.  WIN will be a C
338     statement label elsewhere in the code; the macro definition may use
339
340          GO_IF_LEGITIMATE_ADDRESS (MODE, X, WIN);
341
342     to avoid further processing if the address has become legitimate.
343
344     X will always be the result of a call to `break_out_memory_refs',
345     and OLDX will be the operand that was given to that function to
346     produce X.
347
348     The code generated by this macro should not alter the substructure
349     of X.  If it transforms X into a more legitimate form, it should
350     assign X (which will always be a C variable) a new value.
351
352     It is not necessary for this macro to come up with a legitimate
353     address.  The compiler has standard ways of doing so in all cases.
354     In fact, it is safe for this macro to do nothing.  But often a
355     machine-dependent strategy can generate better code.
356
357`GO_IF_MODE_DEPENDENT_ADDRESS (ADDR, LABEL)'
358     A C statement or compound statement with a conditional `goto
359     LABEL;' executed if memory address X (an RTX) can have different
360     meanings depending on the machine mode of the memory reference it
361     is used for or if the address is valid for some modes but not
362     others.
363
364     Autoincrement and autodecrement addresses typically have
365     mode-dependent effects because the amount of the increment or
366     decrement is the size of the operand being addressed.  Some
367     machines have other mode-dependent addresses.  Many RISC machines
368     have no mode-dependent addresses.
369
370     You may assume that ADDR is a valid address for the machine.
371
372`LEGITIMATE_CONSTANT_P (X)'
373     A C expression that is nonzero if X is a legitimate constant for
374     an immediate operand on the target machine.  You can assume that X
375     satisfies `CONSTANT_P', so you need not check this.  In fact, `1'
376     is a suitable definition for this macro on machines where anything
377     `CONSTANT_P' is valid.
378
379
380File: gcc.info,  Node: Condition Code,  Next: Costs,  Prev: Addressing Modes,  Up: Target Macros
381
382Condition Code Status
383=====================
384
385   This describes the condition code status.
386
387   The file `conditions.h' defines a variable `cc_status' to describe
388how the condition code was computed (in case the interpretation of the
389condition code depends on the instruction that it was set by).  This
390variable contains the RTL expressions on which the condition code is
391currently based, and several standard flags.
392
393   Sometimes additional machine-specific flags must be defined in the
394machine description header file.  It can also add additional
395machine-specific information by defining `CC_STATUS_MDEP'.
396
397`CC_STATUS_MDEP'
398     C code for a data type which is used for declaring the `mdep'
399     component of `cc_status'.  It defaults to `int'.
400
401     This macro is not used on machines that do not use `cc0'.
402
403`CC_STATUS_MDEP_INIT'
404     A C expression to initialize the `mdep' field to "empty".  The
405     default definition does nothing, since most machines don't use the
406     field anyway.  If you want to use the field, you should probably
407     define this macro to initialize it.
408
409     This macro is not used on machines that do not use `cc0'.
410
411`NOTICE_UPDATE_CC (EXP, INSN)'
412     A C compound statement to set the components of `cc_status'
413     appropriately for an insn INSN whose body is EXP.  It is this
414     macro's responsibility to recognize insns that set the condition
415     code as a byproduct of other activity as well as those that
416     explicitly set `(cc0)'.
417
418     This macro is not used on machines that do not use `cc0'.
419
420     If there are insns that do not set the condition code but do alter
421     other machine registers, this macro must check to see whether they
422     invalidate the expressions that the condition code is recorded as
423     reflecting.  For example, on the 68000, insns that store in address
424     registers do not set the condition code, which means that usually
425     `NOTICE_UPDATE_CC' can leave `cc_status' unaltered for such insns.
426     But suppose that the previous insn set the condition code based
427     on location `a4@(102)' and the current insn stores a new value in
428     `a4'.  Although the condition code is not changed by this, it will
429     no longer be true that it reflects the contents of `a4@(102)'.
430     Therefore, `NOTICE_UPDATE_CC' must alter `cc_status' in this case
431     to say that nothing is known about the condition code value.
432
433     The definition of `NOTICE_UPDATE_CC' must be prepared to deal with
434     the results of peephole optimization: insns whose patterns are
435     `parallel' RTXs containing various `reg', `mem' or constants which
436     are just the operands.  The RTL structure of these insns is not
437     sufficient to indicate what the insns actually do.  What
438     `NOTICE_UPDATE_CC' should do when it sees one is just to run
439     `CC_STATUS_INIT'.
440
441     A possible definition of `NOTICE_UPDATE_CC' is to call a function
442     that looks at an attribute (*note Insn Attributes::.) named, for
443     example, `cc'.  This avoids having detailed information about
444     patterns in two places, the `md' file and in `NOTICE_UPDATE_CC'.
445
446`EXTRA_CC_MODES'
447     A list of names to be used for additional modes for condition code
448     values in registers (*note Jump Patterns::.).  These names are
449     added to `enum machine_mode' and all have class `MODE_CC'.  By
450     convention, they should start with `CC' and end with `mode'.
451
452     You should only define this macro if your machine does not use
453     `cc0' and only if additional modes are required.
454
455`EXTRA_CC_NAMES'
456     A list of C strings giving the names for the modes listed in
457     `EXTRA_CC_MODES'.  For example, the Sparc defines this macro and
458     `EXTRA_CC_MODES' as
459
460          #define EXTRA_CC_MODES CC_NOOVmode, CCFPmode, CCFPEmode
461          #define EXTRA_CC_NAMES "CC_NOOV", "CCFP", "CCFPE"
462
463     This macro is not required if `EXTRA_CC_MODES' is not defined.
464
465`SELECT_CC_MODE (OP, X, Y)'
466     Returns a mode from class `MODE_CC' to be used when comparison
467     operation code OP is applied to rtx X and Y.  For example, on the
468     Sparc, `SELECT_CC_MODE' is defined as (see *note Jump Patterns::.
469     for a description of the reason for this definition)
470
471          #define SELECT_CC_MODE(OP,X,Y) \
472            (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT          \
473             ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode)    \
474             : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS    \
475                 || GET_CODE (X) == NEG) \
476                ? CC_NOOVmode : CCmode))
477
478     You need not define this macro if `EXTRA_CC_MODES' is not defined.
479
480`CANONICALIZE_COMPARISON (CODE, OP0, OP1)'
481     One some machines not all possible comparisons are defined, but
482     you can convert an invalid comparison into a valid one.  For
483     example, the Alpha does not have a `GT' comparison, but you can
484     use an `LT' comparison instead and swap the order of the operands.
485
486     On such machines, define this macro to be a C statement to do any
487     required conversions.  CODE is the initial comparison code and OP0
488     and OP1 are the left and right operands of the comparison,
489     respectively.  You should modify CODE, OP0, and OP1 as required.
490
491     GNU CC will not assume that the comparison resulting from this
492     macro is valid but will see if the resulting insn matches a
493     pattern in the `md' file.
494
495     You need not define this macro if it would never change the
496     comparison code or operands.
497
498`REVERSIBLE_CC_MODE (MODE)'
499     A C expression whose value is one if it is always safe to reverse a
500     comparison whose mode is MODE.  If `SELECT_CC_MODE' can ever
501     return MODE for a floating-point inequality comparison, then
502     `REVERSIBLE_CC_MODE (MODE)' must be zero.
503
504     You need not define this macro if it would always returns zero or
505     if the floating-point format is anything other than
506     `IEEE_FLOAT_FORMAT'.  For example, here is the definition used on
507     the Sparc, where floating-point inequality comparisons are always
508     given `CCFPEmode':
509
510          #define REVERSIBLE_CC_MODE(MODE)  ((MODE) != CCFPEmode)
511
512
513File: gcc.info,  Node: Costs,  Next: Sections,  Prev: Condition Code,  Up: Target Macros
514
515Describing Relative Costs of Operations
516=======================================
517
518   These macros let you describe the relative speed of various
519operations on the target machine.
520
521`CONST_COSTS (X, CODE, OUTER_CODE)'
522     A part of a C `switch' statement that describes the relative costs
523     of constant RTL expressions.  It must contain `case' labels for
524     expression codes `const_int', `const', `symbol_ref', `label_ref'
525     and `const_double'.  Each case must ultimately reach a `return'
526     statement to return the relative cost of the use of that kind of
527     constant value in an expression.  The cost may depend on the
528     precise value of the constant, which is available for examination
529     in X, and the rtx code of the expression in which it is contained,
530     found in OUTER_CODE.
531
532     CODE is the expression code--redundant, since it can be obtained
533     with `GET_CODE (X)'.
534
535`RTX_COSTS (X, CODE, OUTER_CODE)'
536     Like `CONST_COSTS' but applies to nonconstant RTL expressions.
537     This can be used, for example, to indicate how costly a multiply
538     instruction is.  In writing this macro, you can use the construct
539     `COSTS_N_INSNS (N)' to specify a cost equal to N fast
540     instructions.  OUTER_CODE is the code of the expression in which X
541     is contained.
542
543     This macro is optional; do not define it if the default cost
544     assumptions are adequate for the target machine.
545
546`ADDRESS_COST (ADDRESS)'
547     An expression giving the cost of an addressing mode that contains
548     ADDRESS.  If not defined, the cost is computed from the ADDRESS
549     expression and the `CONST_COSTS' values.
550
551     For most CISC machines, the default cost is a good approximation
552     of the true cost of the addressing mode.  However, on RISC
553     machines, all instructions normally have the same length and
554     execution time.  Hence all addresses will have equal costs.
555
556     In cases where more than one form of an address is known, the form
557     with the lowest cost will be used.  If multiple forms have the
558     same, lowest, cost, the one that is the most complex will be used.
559
560     For example, suppose an address that is equal to the sum of a
561     register and a constant is used twice in the same basic block.
562     When this macro is not defined, the address will be computed in a
563     register and memory references will be indirect through that
564     register.  On machines where the cost of the addressing mode
565     containing the sum is no higher than that of a simple indirect
566     reference, this will produce an additional instruction and
567     possibly require an additional register.  Proper specification of
568     this macro eliminates this overhead for such machines.
569
570     Similar use of this macro is made in strength reduction of loops.
571
572     ADDRESS need not be valid as an address.  In such a case, the cost
573     is not relevant and can be any value; invalid addresses need not be
574     assigned a different cost.
575
576     On machines where an address involving more than one register is as
577     cheap as an address computation involving only one register,
578     defining `ADDRESS_COST' to reflect this can cause two registers to
579     be live over a region of code where only one would have been if
580     `ADDRESS_COST' were not defined in that manner.  This effect should
581     be considered in the definition of this macro.  Equivalent costs
582     should probably only be given to addresses with different numbers
583     of registers on machines with lots of registers.
584
585     This macro will normally either not be defined or be defined as a
586     constant.
587
588`REGISTER_MOVE_COST (FROM, TO)'
589     A C expression for the cost of moving data from a register in class
590     FROM to one in class TO.  The classes are expressed using the
591     enumeration values such as `GENERAL_REGS'.  A value of 4 is the
592     default; other values are interpreted relative to that.
593
594     It is not required that the cost always equal 2 when FROM is the
595     same as TO; on some machines it is expensive to move between
596     registers if they are not general registers.
597
598     If reload sees an insn consisting of a single `set' between two
599     hard registers, and if `REGISTER_MOVE_COST' applied to their
600     classes returns a value of 2, reload does not check to ensure that
601     the constraints of the insn are met.  Setting a cost of other than
602     2 will allow reload to verify that the constraints are met.  You
603     should do this if the `movM' pattern's constraints do not allow
604     such copying.
605
606`MEMORY_MOVE_COST (M)'
607     A C expression for the cost of moving data of mode M between a
608     register and memory.  A value of 2 is the default; this cost is
609     relative to those in `REGISTER_MOVE_COST'.
610
611     If moving between registers and memory is more expensive than
612     between two registers, you should define this macro to express the
613     relative cost.
614
615`BRANCH_COST'
616     A C expression for the cost of a branch instruction.  A value of 1
617     is the default; other values are interpreted relative to that.
618
619   Here are additional macros which do not specify precise relative
620costs, but only that certain actions are more expensive than GNU CC
621would ordinarily expect.
622
623`SLOW_BYTE_ACCESS'
624     Define this macro as a C expression which is nonzero if accessing
625     less than a word of memory (i.e. a `char' or a `short') is no
626     faster than accessing a word of memory, i.e., if such access
627     require more than one instruction or if there is no difference in
628     cost between byte and (aligned) word loads.
629
630     When this macro is not defined, the compiler will access a field by
631     finding the smallest containing object; when it is defined, a
632     fullword load will be used if alignment permits.  Unless bytes
633     accesses are faster than word accesses, using word accesses is
634     preferable since it may eliminate subsequent memory access if
635     subsequent accesses occur to other fields in the same word of the
636     structure, but to different bytes.
637
638`SLOW_ZERO_EXTEND'
639     Define this macro if zero-extension (of a `char' or `short' to an
640     `int') can be done faster if the destination is a register that is
641     known to be zero.
642
643     If you define this macro, you must have instruction patterns that
644     recognize RTL structures like this:
645
646          (set (strict_low_part (subreg:QI (reg:SI ...) 0)) ...)
647
648     and likewise for `HImode'.
649
650`SLOW_UNALIGNED_ACCESS'
651     Define this macro to be the value 1 if unaligned accesses have a
652     cost many times greater than aligned accesses, for example if they
653     are emulated in a trap handler.
654
655     When this macro is non-zero, the compiler will act as if
656     `STRICT_ALIGNMENT' were non-zero when generating code for block
657     moves.  This can cause significantly more instructions to be
658     produced.  Therefore, do not set this macro non-zero if unaligned
659     accesses only add a cycle or two to the time for a memory access.
660
661     If the value of this macro is always zero, it need not be defined.
662
663`DONT_REDUCE_ADDR'
664     Define this macro to inhibit strength reduction of memory
665     addresses.  (On some machines, such strength reduction seems to do
666     harm rather than good.)
667
668`MOVE_RATIO'
669     The number of scalar move insns which should be generated instead
670     of a string move insn or a library call.  Increasing the value
671     will always make code faster, but eventually incurs high cost in
672     increased code size.
673
674     If you don't define this, a reasonable default is used.
675
676`NO_FUNCTION_CSE'
677     Define this macro if it is as good or better to call a constant
678     function address than to call an address kept in a register.
679
680`NO_RECURSIVE_FUNCTION_CSE'
681     Define this macro if it is as good or better for a function to call
682     itself with an explicit address than to call an address kept in a
683     register.
684
685`ADJUST_COST (INSN, LINK, DEP_INSN, COST)'
686     A C statement (sans semicolon) to update the integer variable COST
687     based on the relationship between INSN that is dependent on
688     DEP_INSN through the dependence LINK.  The default is to make no
689     adjustment to COST.  This can be used for example to specify to
690     the scheduler that an output- or anti-dependence does not incur
691     the same cost as a data-dependence.
692
693
694File: gcc.info,  Node: Sections,  Next: PIC,  Prev: Costs,  Up: Target Macros
695
696Dividing the Output into Sections (Texts, Data, ...)
697====================================================
698
699   An object file is divided into sections containing different types of
700data.  In the most common case, there are three sections: the "text
701section", which holds instructions and read-only data; the "data
702section", which holds initialized writable data; and the "bss section",
703which holds uninitialized data.  Some systems have other kinds of
704sections.
705
706   The compiler must tell the assembler when to switch sections.  These
707macros control what commands to output to tell the assembler this.  You
708can also define additional sections.
709
710`TEXT_SECTION_ASM_OP'
711     A C expression whose value is a string containing the assembler
712     operation that should precede instructions and read-only data.
713     Normally `".text"' is right.
714
715`DATA_SECTION_ASM_OP'
716     A C expression whose value is a string containing the assembler
717     operation to identify the following data as writable initialized
718     data.  Normally `".data"' is right.
719
720`SHARED_SECTION_ASM_OP'
721     if defined, a C expression whose value is a string containing the
722     assembler operation to identify the following data as shared data.
723     If not defined, `DATA_SECTION_ASM_OP' will be used.
724
725`INIT_SECTION_ASM_OP'
726     if defined, a C expression whose value is a string containing the
727     assembler operation to identify the following data as
728     initialization code.  If not defined, GNU CC will assume such a
729     section does not exist.
730
731`EXTRA_SECTIONS'
732     A list of names for sections other than the standard two, which are
733     `in_text' and `in_data'.  You need not define this macro on a
734     system with no other sections (that GCC needs to use).
735
736`EXTRA_SECTION_FUNCTIONS'
737     One or more functions to be defined in `varasm.c'.  These
738     functions should do jobs analogous to those of `text_section' and
739     `data_section', for your additional sections.  Do not define this
740     macro if you do not define `EXTRA_SECTIONS'.
741
742`READONLY_DATA_SECTION'
743     On most machines, read-only variables, constants, and jump tables
744     are placed in the text section.  If this is not the case on your
745     machine, this macro should be defined to be the name of a function
746     (either `data_section' or a function defined in `EXTRA_SECTIONS')
747     that switches to the section to be used for read-only items.
748
749     If these items should be placed in the text section, this macro
750     should not be defined.
751
752`SELECT_SECTION (EXP, RELOC)'
753     A C statement or statements to switch to the appropriate section
754     for output of EXP.  You can assume that EXP is either a `VAR_DECL'
755     node or a constant of some sort.  RELOC indicates whether the
756     initial value of EXP requires link-time relocations.  Select the
757     section by calling `text_section' or one of the alternatives for
758     other sections.
759
760     Do not define this macro if you put all read-only variables and
761     constants in the read-only data section (usually the text section).
762
763`SELECT_RTX_SECTION (MODE, RTX)'
764     A C statement or statements to switch to the appropriate section
765     for output of RTX in mode MODE.  You can assume that RTX is some
766     kind of constant in RTL.  The argument MODE is redundant except in
767     the case of a `const_int' rtx.  Select the section by calling
768     `text_section' or one of the alternatives for other sections.
769
770     Do not define this macro if you put all constants in the read-only
771     data section.
772
773`JUMP_TABLES_IN_TEXT_SECTION'
774     Define this macro if jump tables (for `tablejump' insns) should be
775     output in the text section, along with the assembler instructions.
776     Otherwise, the readonly data section is used.
777
778     This macro is irrelevant if there is no separate readonly data
779     section.
780
781`ENCODE_SECTION_INFO (DECL)'
782     Define this macro if references to a symbol must be treated
783     differently depending on something about the variable or function
784     named by the symbol (such as what section it is in).
785
786     The macro definition, if any, is executed immediately after the
787     rtl for DECL has been created and stored in `DECL_RTL (DECL)'.
788     The value of the rtl will be a `mem' whose address is a
789     `symbol_ref'.
790
791     The usual thing for this macro to do is to record a flag in the
792     `symbol_ref' (such as `SYMBOL_REF_FLAG') or to store a modified
793     name string in the `symbol_ref' (if one bit is not enough
794     information).
795
796`STRIP_NAME_ENCODING (VAR, SYM_NAME)'
797     Decode SYM_NAME and store the real name part in VAR, sans the
798     characters that encode section info.  Define this macro if
799     `ENCODE_SECTION_INFO' alters the symbol's name string.
800
801
802File: gcc.info,  Node: PIC,  Next: Assembler Format,  Prev: Sections,  Up: Target Macros
803
804Position Independent Code
805=========================
806
807   This section describes macros that help implement generation of
808position independent code.  Simply defining these macros is not enough
809to generate valid PIC; you must also add support to the macros
810`GO_IF_LEGITIMATE_ADDRESS' and `PRINT_OPERAND_ADDRESS', as well as
811`LEGITIMIZE_ADDRESS'.  You must modify the definition of `movsi' to do
812something appropriate when the source operand contains a symbolic
813address.  You may also need to alter the handling of switch statements
814so that they use relative addresses.
815
816`PIC_OFFSET_TABLE_REGNUM'
817     The register number of the register used to address a table of
818     static data addresses in memory.  In some cases this register is
819     defined by a processor's "application binary interface" (ABI).
820     When this macro is defined, RTL is generated for this register
821     once, as with the stack pointer and frame pointer registers.  If
822     this macro is not defined, it is up to the machine-dependent files
823     to allocate such a register (if necessary).
824
825`PIC_OFFSET_TABLE_REG_CALL_CLOBBERED'
826     Define this macro if the register defined by
827     `PIC_OFFSET_TABLE_REGNUM' is clobbered by calls.  Do not define
828     this macro if `PPIC_OFFSET_TABLE_REGNUM' is not defined.
829
830`FINALIZE_PIC'
831     By generating position-independent code, when two different
832     programs (A and B) share a common library (libC.a), the text of
833     the library can be shared whether or not the library is linked at
834     the same address for both programs.  In some of these
835     environments, position-independent code requires not only the use
836     of different addressing modes, but also special code to enable the
837     use of these addressing modes.
838
839     The `FINALIZE_PIC' macro serves as a hook to emit these special
840     codes once the function is being compiled into assembly code, but
841     not before.  (It is not done before, because in the case of
842     compiling an inline function, it would lead to multiple PIC
843     prologues being included in functions which used inline functions
844     and were compiled to assembly language.)
845
846`LEGITIMATE_PIC_OPERAND_P (X)'
847     A C expression that is nonzero if X is a legitimate immediate
848     operand on the target machine when generating position independent
849     code.  You can assume that X satisfies `CONSTANT_P', so you need
850     not check this.  You can also assume FLAG_PIC is true, so you need
851     not check it either.  You need not define this macro if all
852     constants (including `SYMBOL_REF') can be immediate operands when
853     generating position independent code.
854
855
856File: gcc.info,  Node: Assembler Format,  Next: Debugging Info,  Prev: PIC,  Up: Target Macros
857
858Defining the Output Assembler Language
859======================================
860
861   This section describes macros whose principal purpose is to describe
862how to write instructions in assembler language-rather than what the
863instructions do.
864
865* Menu:
866
867* File Framework::       Structural information for the assembler file.
868* Data Output::          Output of constants (numbers, strings, addresses).
869* Uninitialized Data::   Output of uninitialized variables.
870* Label Output::         Output and generation of labels.
871* Initialization::       General principles of initialization
872                           and termination routines.
873* Macros for Initialization::
874                         Specific macros that control the handling of
875                           initialization and termination routines.
876* Instruction Output::   Output of actual instructions.
877* Dispatch Tables::      Output of jump tables.
878* Alignment Output::     Pseudo ops for alignment and skipping data.
879
880
881File: gcc.info,  Node: File Framework,  Next: Data Output,  Up: Assembler Format
882
883The Overall Framework of an Assembler File
884------------------------------------------
885
886   This describes the overall framework of an assembler file.
887
888`ASM_FILE_START (STREAM)'
889     A C expression which outputs to the stdio stream STREAM some
890     appropriate text to go at the start of an assembler file.
891
892     Normally this macro is defined to output a line containing
893     `#NO_APP', which is a comment that has no effect on most
894     assemblers but tells the GNU assembler that it can save time by not
895     checking for certain assembler constructs.
896
897     On systems that use SDB, it is necessary to output certain
898     commands; see `attasm.h'.
899
900`ASM_FILE_END (STREAM)'
901     A C expression which outputs to the stdio stream STREAM some
902     appropriate text to go at the end of an assembler file.
903
904     If this macro is not defined, the default is to output nothing
905     special at the end of the file.  Most systems don't require any
906     definition.
907
908     On systems that use SDB, it is necessary to output certain
909     commands; see `attasm.h'.
910
911`ASM_IDENTIFY_GCC (FILE)'
912     A C statement to output assembler commands which will identify the
913     object file as having been compiled with GNU CC (or another GNU
914     compiler).
915
916     If you don't define this macro, the string `gcc_compiled.:' is
917     output.  This string is calculated to define a symbol which, on
918     BSD systems, will never be defined for any other reason.  GDB
919     checks for the presence of this symbol when reading the symbol
920     table of an executable.
921
922     On non-BSD systems, you must arrange communication with GDB in
923     some other fashion.  If GDB is not used on your system, you can
924     define this macro with an empty body.
925
926`ASM_COMMENT_START'
927     A C string constant describing how to begin a comment in the target
928     assembler language.  The compiler assumes that the comment will
929     end at the end of the line.
930
931`ASM_APP_ON'
932     A C string constant for text to be output before each `asm'
933     statement or group of consecutive ones.  Normally this is
934     `"#APP"', which is a comment that has no effect on most assemblers
935     but tells the GNU assembler that it must check the lines that
936     follow for all valid assembler constructs.
937
938`ASM_APP_OFF'
939     A C string constant for text to be output after each `asm'
940     statement or group of consecutive ones.  Normally this is
941     `"#NO_APP"', which tells the GNU assembler to resume making the
942     time-saving assumptions that are valid for ordinary compiler
943     output.
944
945`ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME)'
946     A C statement to output COFF information or DWARF debugging
947     information which indicates that filename NAME is the current
948     source file to the stdio stream STREAM.
949
950     This macro need not be defined if the standard form of output for
951     the file format in use is appropriate.
952
953`ASM_OUTPUT_SOURCE_LINE (STREAM, LINE)'
954     A C statement to output DBX or SDB debugging information before
955     code for line number LINE of the current source file to the stdio
956     stream STREAM.
957
958     This macro need not be defined if the standard form of debugging
959     information for the debugger in use is appropriate.
960
961`ASM_OUTPUT_IDENT (STREAM, STRING)'
962     A C statement to output something to the assembler file to handle a
963     `#ident' directive containing the text STRING.  If this macro is
964     not defined, nothing is output for a `#ident' directive.
965
966`ASM_OUTPUT_SECTION_NAME (STREAM, DECL, NAME)'
967     A C statement to output something to the assembler file to switch
968     to section NAME for object DECL which is either a `FUNCTION_DECL',
969     a `VAR_DECL' or `NULL_TREE'.  Some target formats do not support
970     arbitrary sections.  Do not define this macro in such cases.
971
972     At present this macro is only used to support section attributes.
973     When this macro is undefined, section attributes are disabled.
974
975`OBJC_PROLOGUE'
976     A C statement to output any assembler statements which are
977     required to precede any Objective C object definitions or message
978     sending.  The statement is executed only when compiling an
979     Objective C program.
980
981
982File: gcc.info,  Node: Data Output,  Next: Uninitialized Data,  Prev: File Framework,  Up: Assembler Format
983
984Output of Data
985--------------
986
987   This describes data output.
988
989`ASM_OUTPUT_LONG_DOUBLE (STREAM, VALUE)'
990`ASM_OUTPUT_DOUBLE (STREAM, VALUE)'
991`ASM_OUTPUT_FLOAT (STREAM, VALUE)'
992`ASM_OUTPUT_THREE_QUARTER_FLOAT (STREAM, VALUE)'
993`ASM_OUTPUT_SHORT_FLOAT (STREAM, VALUE)'
994`ASM_OUTPUT_BYTE_FLOAT (STREAM, VALUE)'
995     A C statement to output to the stdio stream STREAM an assembler
996     instruction to assemble a floating-point constant of `TFmode',
997     `DFmode', `SFmode', `TQFmode', `HFmode', or `QFmode',
998     respectively, whose value is VALUE.  VALUE will be a C expression
999     of type `REAL_VALUE_TYPE'.  Macros such as
1000     `REAL_VALUE_TO_TARGET_DOUBLE' are useful for writing these
1001     definitions.
1002
1003`ASM_OUTPUT_QUADRUPLE_INT (STREAM, EXP)'
1004`ASM_OUTPUT_DOUBLE_INT (STREAM, EXP)'
1005`ASM_OUTPUT_INT (STREAM, EXP)'
1006`ASM_OUTPUT_SHORT (STREAM, EXP)'
1007`ASM_OUTPUT_CHAR (STREAM, EXP)'
1008     A C statement to output to the stdio stream STREAM an assembler
1009     instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes,
1010     respectively, whose value is VALUE.  The argument EXP will be an
1011     RTL expression which represents a constant value.  Use
1012     `output_addr_const (STREAM, EXP)' to output this value as an
1013     assembler expression.
1014
1015     For sizes larger than `UNITS_PER_WORD', if the action of a macro
1016     would be identical to repeatedly calling the macro corresponding to
1017     a size of `UNITS_PER_WORD', once for each word, you need not define
1018     the macro.
1019
1020`ASM_OUTPUT_BYTE (STREAM, VALUE)'
1021     A C statement to output to the stdio stream STREAM an assembler
1022     instruction to assemble a single byte containing the number VALUE.
1023
1024`ASM_BYTE_OP'
1025     A C string constant giving the pseudo-op to use for a sequence of
1026     single-byte constants.  If this macro is not defined, the default
1027     is `"byte"'.
1028
1029`ASM_OUTPUT_ASCII (STREAM, PTR, LEN)'
1030     A C statement to output to the stdio stream STREAM an assembler
1031     instruction to assemble a string constant containing the LEN bytes
1032     at PTR.  PTR will be a C expression of type `char *' and LEN a C
1033     expression of type `int'.
1034
1035     If the assembler has a `.ascii' pseudo-op as found in the Berkeley
1036     Unix assembler, do not define the macro `ASM_OUTPUT_ASCII'.
1037
1038`ASM_OUTPUT_POOL_PROLOGUE (FILE FUNNAME FUNDECL SIZE)'
1039     A C statement to output assembler commands to define the start of
1040     the constant pool for a function.  FUNNAME is a string giving the
1041     name of the function.  Should the return type of the function be
1042     required, it can be obtained via FUNDECL.  SIZE is the size, in
1043     bytes, of the constant pool that will be written immediately after
1044     this call.
1045
1046     If no constant-pool prefix is required, the usual case, this macro
1047     need not be defined.
1048
1049`ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO)'
1050     A C statement (with or without semicolon) to output a constant in
1051     the constant pool, if it needs special treatment.  (This macro
1052     need not do anything for RTL expressions that can be output
1053     normally.)
1054
1055     The argument FILE is the standard I/O stream to output the
1056     assembler code on.  X is the RTL expression for the constant to
1057     output, and MODE is the machine mode (in case X is a `const_int').
1058     ALIGN is the required alignment for the value X; you should
1059     output an assembler directive to force this much alignment.
1060
1061     The argument LABELNO is a number to use in an internal label for
1062     the address of this pool entry.  The definition of this macro is
1063     responsible for outputting the label definition at the proper
1064     place.  Here is how to do this:
1065
1066          ASM_OUTPUT_INTERNAL_LABEL (FILE, "LC", LABELNO);
1067
1068     When you output a pool entry specially, you should end with a
1069     `goto' to the label JUMPTO.  This will prevent the same pool entry
1070     from being output a second time in the usual manner.
1071
1072     You need not define this macro if it would do nothing.
1073
1074`IS_ASM_LOGICAL_LINE_SEPARATOR (C)'
1075     Define this macro as a C expression which is nonzero if C is used
1076     as a logical line separator by the assembler.
1077
1078     If you do not define this macro, the default is that only the
1079     character `;' is treated as a logical line separator.
1080
1081`ASM_OPEN_PAREN'
1082`ASM_CLOSE_PAREN'
1083     These macros are defined as C string constant, describing the
1084     syntax in the assembler for grouping arithmetic expressions.  The
1085     following definitions are correct for most assemblers:
1086
1087          #define ASM_OPEN_PAREN "("
1088          #define ASM_CLOSE_PAREN ")"
1089
1090   These macros are provided by `real.h' for writing the definitions of
1091`ASM_OUTPUT_DOUBLE' and the like:
1092
1093`REAL_VALUE_TO_TARGET_SINGLE (X, L)'
1094`REAL_VALUE_TO_TARGET_DOUBLE (X, L)'
1095`REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L)'
1096     These translate X, of type `REAL_VALUE_TYPE', to the target's
1097     floating point representation, and store its bit pattern in the
1098     array of `long int' whose address is L.  The number of elements in
1099     the output array is determined by the size of the desired target
1100     floating point data type: 32 bits of it go in each `long int' array
1101     element.  Each array element holds 32 bits of the result, even if
1102     `long int' is wider than 32 bits on the host machine.
1103
1104     The array element values are designed so that you can print them
1105     out using `fprintf' in the order they should appear in the target
1106     machine's memory.
1107
1108`REAL_VALUE_TO_DECIMAL (X, FORMAT, STRING)'
1109     This macro converts X, of type `REAL_VALUE_TYPE', to a decimal
1110     number and stores it as a string into STRING.  You must pass, as
1111     STRING, the address of a long enough block of space to hold the
1112     result.
1113
1114     The argument FORMAT is a `printf'-specification that serves as a
1115     suggestion for how to format the output string.
1116
Note: See TracBrowser for help on using the repository browser.