2 Copyright 1988-2022 Free Software Foundation, Inc.
3 This is part of the GCC manual.
4 For copying conditions, see the copyright.rst file.
6 .. index:: insn attributes, instruction attributes
10 Instruction Attributes
11 **********************
13 In addition to describing the instruction supported by the target machine,
14 the :samp:`md` file also defines a group of :dfn:`attributes` and a set of
15 values for each. Every generated insn is assigned a value for each attribute.
16 One possible attribute would be the effect that the insn has on the machine's
23 .. index:: defining attributes and their values, attributes, defining, define_attr
25 .. _defining-attributes:
27 Defining Attributes and their Values
28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
30 The ``define_attr`` expression is used to define each attribute required
31 by the target machine. It looks like:
35 (define_attr name list-of-values default)
37 :samp:`{name}` is a string specifying the name of the attribute being
38 defined. Some attributes are used in a special way by the rest of the
39 compiler. The ``enabled`` attribute can be used to conditionally
40 enable or disable insn alternatives (see :ref:`disable-insn-alternatives`). The ``predicable`` attribute, together with a
41 suitable ``define_cond_exec`` (see :ref:`conditional-execution`), can
42 be used to automatically generate conditional variants of instruction
43 patterns. The ``mnemonic`` attribute can be used to check for the
44 instruction mnemonic (see :ref:`mnemonic-attribute`). The compiler
45 internally uses the names ``ce_enabled`` and ``nonce_enabled``,
46 so they should not be used elsewhere as alternative names.
48 :samp:`{list-of-values}` is either a string that specifies a comma-separated
49 list of values that can be assigned to the attribute, or a null string to
50 indicate that the attribute takes numeric values.
52 :samp:`{default}` is an attribute expression that gives the value of this
53 attribute for insns that match patterns whose definition does not include
54 an explicit value for this attribute. See :ref:`attr-example`, for more
55 information on the handling of defaults. See :ref:`constant-attributes`,
56 for information on attributes that do not depend on any particular insn.
58 .. index:: insn-attr.h
60 For each defined attribute, a number of definitions are written to the
61 :samp:`insn-attr.h` file. For cases where an explicit set of values is
62 specified for an attribute, the following are defined:
64 * A :samp:`#define` is written for the symbol :samp:`HAVE_ATTR_{name}`.
66 * An enumerated class is defined for :samp:`attr_{name}` with
67 elements of the form :samp:`{upper-name}_{upper-value}` where
68 the attribute name and value are first converted to uppercase.
70 * A function :samp:`get_attr_{name}` is defined that is passed an insn and
71 returns the attribute value for that insn.
73 For example, if the following is present in the :samp:`md` file:
77 (define_attr "type" "branch,fp,load,store,arith" ...)
79 the following lines will be written to the file :samp:`insn-attr.h`.
83 #define HAVE_ATTR_type 1
84 enum attr_type {TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
85 TYPE_STORE, TYPE_ARITH};
86 extern enum attr_type get_attr_type ();
88 If the attribute takes numeric values, no ``enum`` type will be
89 defined and the function to obtain the attribute's value will return
92 There are attributes which are tied to a specific meaning. These
93 attributes are not free to use for other purposes:
96 The ``length`` attribute is used to calculate the length of emitted
97 code chunks. This is especially important when verifying branch
98 distances. See :ref:`insn-lengths`.
101 The ``enabled`` attribute can be defined to prevent certain
102 alternatives of an insn definition from being used during code
103 generation. See :ref:`disable-insn-alternatives`.
106 The ``mnemonic`` attribute can be defined to implement instruction
107 specific checks in e.g. the pipeline description.
108 See :ref:`mnemonic-attribute`.
110 For each of these special attributes, the corresponding
111 :samp:`HAVE_ATTR_{name}` :samp:`#define` is also written when the
112 attribute is not defined; in that case, it is defined as :samp:`0`.
114 .. index:: define_enum_attr
116 .. _define_enum_attr:
118 Another way of defining an attribute is to use:
122 (define_enum_attr "attr" "enum" default)
124 This works in just the same way as ``define_attr``, except that
125 the list of values is taken from a separate enumeration called
126 :samp:`{enum}` (see :ref:`define_enum`). This form allows you to use
127 the same list of values for several attributes without having to
128 repeat the list each time. For example:
132 (define_enum "processor" [
137 (define_enum_attr "arch" "processor"
138 (const (symbol_ref "target_arch")))
139 (define_enum_attr "tune" "processor"
140 (const (symbol_ref "target_tune")))
142 defines the same attributes as:
146 (define_attr "arch" "model_a,model_b,..."
147 (const (symbol_ref "target_arch")))
148 (define_attr "tune" "model_a,model_b,..."
149 (const (symbol_ref "target_tune")))
151 but without duplicating the processor list. The second example defines two
152 separate C enums (``attr_arch`` and ``attr_tune``) whereas the first
153 defines a single C enum (``processor``).
155 .. index:: attribute expressions
159 Attribute Expressions
160 ^^^^^^^^^^^^^^^^^^^^^
162 RTL expressions used to define attributes use the codes described above
163 plus a few specific to attribute definitions, to be discussed below.
164 Attribute value expressions must have one of the following forms:
166 .. index:: const_int and attributes
168 :samp:`(const_int {i})`
169 The integer :samp:`{i}` specifies the value of a numeric attribute. :samp:`{i}`
170 must be non-negative.
172 The value of a numeric attribute can be specified either with a
173 ``const_int``, or as an integer represented as a string in
174 ``const_string``, ``eq_attr`` (see below), ``attr``,
175 ``symbol_ref``, simple arithmetic expressions, and ``set_attr``
176 overrides on specific instructions (see :ref:`tagging-insns`).
178 .. index:: const_string and attributes
180 :samp:`(const_string {value})`
181 The string :samp:`{value}` specifies a constant attribute value.
182 If :samp:`{value}` is specified as :samp:`"*"`, it means that the default value of
183 the attribute is to be used for the insn containing this expression.
184 :samp:`"*"` obviously cannot be used in the :samp:`{default}` expression
185 of a ``define_attr``.
187 If the attribute whose value is being specified is numeric, :samp:`{value}`
188 must be a string containing a non-negative integer (normally
189 ``const_int`` would be used in this case). Otherwise, it must
190 contain one of the valid values for the attribute.
192 .. index:: if_then_else and attributes
194 :samp:`(if_then_else {test} {true-value} {false-value})`
195 :samp:`{test}` specifies an attribute test, whose format is defined below.
196 The value of this expression is :samp:`{true-value}` if :samp:`{test}` is true,
197 otherwise it is :samp:`{false-value}`.
199 .. index:: cond and attributes
201 :samp:`(cond [{test1} {value1} ...] {default})`
202 The first operand of this expression is a vector containing an even
203 number of expressions and consisting of pairs of :samp:`{test}` and :samp:`{value}`
204 expressions. The value of the ``cond`` expression is that of the
205 :samp:`{value}` corresponding to the first true :samp:`{test}` expression. If
206 none of the :samp:`{test}` expressions are true, the value of the ``cond``
207 expression is that of the :samp:`{default}` expression.
209 :samp:`{test}` expressions can have one of the following forms:
211 .. index:: const_int and attribute tests
213 :samp:`(const_int {i})`
214 This test is true if :samp:`{i}` is nonzero and false otherwise.
216 .. index:: not and attributes, ior and attributes, and and attributes
218 :samp:`(not {test})` :samp:`(ior {test1} {test2})` :samp:`(and {test1} {test2})`
219 These tests are true if the indicated logical function is true.
221 .. index:: match_operand and attributes
223 :samp:`(match_operand:{m} {n} {pred} {constraints})`
224 This test is true if operand :samp:`{n}` of the insn whose attribute value
225 is being determined has mode :samp:`{m}` (this part of the test is ignored
226 if :samp:`{m}` is ``VOIDmode``) and the function specified by the string
227 :samp:`{pred}` returns a nonzero value when passed operand :samp:`{n}` and mode
228 :samp:`{m}` (this part of the test is ignored if :samp:`{pred}` is the null
231 The :samp:`{constraints}` operand is ignored and should be the null string.
233 .. index:: match_test and attributes
235 :samp:`(match_test {c-expr})`
236 The test is true if C expression :samp:`{c-expr}` is true. In non-constant
237 attributes, :samp:`{c-expr}` has access to the following variables:
240 The rtl instruction under test.
242 :samp:`{which_alternative}`
243 The ``define_insn`` alternative that :samp:`{insn}` matches.
244 See :ref:`output-statement`.
247 An array of :samp:`{insn}` 's rtl operands.
249 :samp:`{c-expr}` behaves like the condition in a C ``if`` statement,
250 so there is no need to explicitly convert the expression into a boolean
251 0 or 1 value. For example, the following two tests are equivalent:
256 (match_test "(x & 2) != 0")
258 .. index:: le and attributes, leu and attributes, lt and attributes, gt and attributes, gtu and attributes, ge and attributes, geu and attributes, ne and attributes, eq and attributes, plus and attributes, minus and attributes, mult and attributes, div and attributes, mod and attributes, abs and attributes, neg and attributes, ashift and attributes, lshiftrt and attributes, ashiftrt and attributes
260 :samp:`(le {arith1} {arith2})` :samp:`(leu {arith1} {arith2})` :samp:`(lt {arith1} {arith2})` :samp:`(ltu {arith1} {arith2})` :samp:`(gt {arith1} {arith2})` :samp:`(gtu {arith1} {arith2})` :samp:`(ge {arith1} {arith2})` :samp:`(geu {arith1} {arith2})` :samp:`(ne {arith1} {arith2})` :samp:`(eq {arith1} {arith2})`
261 These tests are true if the indicated comparison of the two arithmetic
262 expressions is true. Arithmetic expressions are formed with
263 ``plus``, ``minus``, ``mult``, ``div``, ``mod``,
264 ``abs``, ``neg``, ``and``, ``ior``, ``xor``, ``not``,
265 ``ashift``, ``lshiftrt``, and ``ashiftrt`` expressions.
269 ``const_int`` and ``symbol_ref`` are always valid terms (see :ref:`insn-lengths`,for additional forms). ``symbol_ref`` is a string
270 denoting a C expression that yields an ``int`` when evaluated by the
271 :samp:`get_attr_...` routine. It should normally be a global
276 :samp:`(eq_attr {name} {value})`
277 :samp:`{name}` is a string specifying the name of an attribute.
279 :samp:`{value}` is a string that is either a valid value for attribute
280 :samp:`{name}`, a comma-separated list of values, or :samp:`!` followed by a
281 value or list. If :samp:`{value}` does not begin with a :samp:`!`, this
282 test is true if the value of the :samp:`{name}` attribute of the current
283 insn is in the list specified by :samp:`{value}`. If :samp:`{value}` begins
284 with a :samp:`!`, this test is true if the attribute's value is
285 *not* in the specified list.
291 (eq_attr "type" "load,store")
297 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
299 If :samp:`{name}` specifies an attribute of :samp:`alternative`, it refers to the
300 value of the compiler variable ``which_alternative``
301 (see :ref:`output-statement`) and the values must be small integers. For
306 (eq_attr "alternative" "2,3")
312 (ior (eq (symbol_ref "which_alternative") (const_int 2))
313 (eq (symbol_ref "which_alternative") (const_int 3)))
315 Note that, for most attributes, an ``eq_attr`` test is simplified in cases
316 where the value of the attribute being tested is known for all insns matching
317 a particular pattern. This is by far the most common case.
321 :samp:`(attr_flag {name})`
322 The value of an ``attr_flag`` expression is true if the flag
323 specified by :samp:`{name}` is true for the ``insn`` currently being
326 :samp:`{name}` is a string specifying one of a fixed set of flags to test.
327 Test the flags ``forward`` and ``backward`` to determine the
328 direction of a conditional branch.
330 This example describes a conditional branch delay slot which
331 can be nullified for forward branches that are taken (annul-true) or
332 for backward branches which are not taken (annul-false).
336 (define_delay (eq_attr "type" "cbranch")
337 [(eq_attr "in_branch_delay" "true")
338 (and (eq_attr "in_branch_delay" "true")
339 (attr_flag "forward"))
340 (and (eq_attr "in_branch_delay" "true")
341 (attr_flag "backward"))])
343 The ``forward`` and ``backward`` flags are false if the current
344 ``insn`` being scheduled is not a conditional branch.
346 ``attr_flag`` is only used during delay slot scheduling and has no
347 meaning to other passes of the compiler.
351 :samp:`(attr {name})`
352 The value of another attribute is returned. This is most useful
353 for numeric attributes, as ``eq_attr`` and ``attr_flag``
354 produce more efficient code for non-numeric attributes.
356 .. index:: tagging insns, assigning attribute values to insns
360 Assigning Attribute Values to Insns
361 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
363 The value assigned to an attribute of an insn is primarily determined by
364 which pattern is matched by that insn (or which ``define_peephole``
365 generated it). Every ``define_insn`` and ``define_peephole`` can
366 have an optional last argument to specify the values of attributes for
367 matching insns. The value of any attribute not specified in a particular
368 insn is set to the default value for that attribute, as specified in its
369 ``define_attr``. Extensive use of default values for attributes
370 permits the specification of the values for only one or two attributes
371 in the definition of most insn patterns, as seen in the example in the
374 The optional last argument of ``define_insn`` and
375 ``define_peephole`` is a vector of expressions, each of which defines
376 the value for a single attribute. The most general way of assigning an
377 attribute's value is to use a ``set`` expression whose first operand is an
378 ``attr`` expression giving the name of the attribute being set. The
379 second operand of the ``set`` is an attribute expression
380 (see :ref:`expressions`) giving the value of the attribute.
382 When the attribute value depends on the :samp:`alternative` attribute
383 (i.e., which is the applicable alternative in the constraint of the
384 insn), the ``set_attr_alternative`` expression can be used. It
385 allows the specification of a vector of attribute expressions, one for
390 When the generality of arbitrary attribute expressions is not required,
391 the simpler ``set_attr`` expression can be used, which allows
392 specifying a string giving either a single attribute value or a list
393 of attribute values, one for each alternative.
395 The form of each of the above specifications is shown below. In each case,
396 :samp:`{name}` is a string specifying the attribute to be set.
398 :samp:`(set_attr {name} {value-string})`
399 :samp:`{value-string}` is either a string giving the desired attribute value,
400 or a string containing a comma-separated list giving the values for
401 succeeding alternatives. The number of elements must match the number
402 of alternatives in the constraint of the insn pattern.
404 Note that it may be useful to specify :samp:`*` for some alternative, in
405 which case the attribute will assume its default value for insns matching
408 .. index:: set_attr_alternative
410 :samp:`(set_attr_alternative {name} [{value1} {value2} ...])`
411 Depending on the alternative of the insn, the value will be one of the
412 specified values. This is a shorthand for using a ``cond`` with
413 tests on the :samp:`alternative` attribute.
417 :samp:`(set (attr {name}) {value})`
418 The first operand of this ``set`` must be the special RTL expression
419 ``attr``, whose sole operand is a string giving the name of the
420 attribute being set. :samp:`{value}` is the value of the attribute.
422 The following shows three different ways of representing the same
423 attribute value specification:
427 (set_attr "type" "load,store,arith")
429 (set_attr_alternative "type"
430 [(const_string "load") (const_string "store")
431 (const_string "arith")])
434 (cond [(eq_attr "alternative" "1") (const_string "load")
435 (eq_attr "alternative" "2") (const_string "store")]
436 (const_string "arith")))
438 .. index:: define_asm_attributes
440 The ``define_asm_attributes`` expression provides a mechanism to
441 specify the attributes assigned to insns produced from an ``asm``
442 statement. It has the form:
446 (define_asm_attributes [attr-sets])
448 where :samp:`{attr-sets}` is specified the same as for both the
449 ``define_insn`` and the ``define_peephole`` expressions.
451 These values will typically be the 'worst case' attribute values. For
452 example, they might indicate that the condition code will be clobbered.
454 A specification for a ``length`` attribute is handled specially. The
455 way to compute the length of an ``asm`` insn is to multiply the
456 length specified in the expression ``define_asm_attributes`` by the
457 number of machine instructions specified in the ``asm`` statement,
458 determined by counting the number of semicolons and newlines in the
459 string. Therefore, the value of the ``length`` attribute specified
460 in a ``define_asm_attributes`` should be the maximum possible length
461 of a single machine instruction.
463 .. index:: attribute specifications example, attribute specifications
467 Example of Attribute Specifications
468 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
470 The judicious use of defaulting is important in the efficient use of
471 insn attributes. Typically, insns are divided into :dfn:`types` and an
472 attribute, customarily called ``type``, is used to represent this
473 value. This attribute is normally used only to define the default value
474 for other attributes. An example will clarify this usage.
476 Assume we have a RISC machine with a condition code and in which only
477 full-word operations are performed in registers. Let us assume that we
478 can divide all insns into loads, stores, (integer) arithmetic
479 operations, floating point operations, and branches.
481 Here we will concern ourselves with determining the effect of an insn on
482 the condition code and will limit ourselves to the following possible
483 effects: The condition code can be set unpredictably (clobbered), not
484 be changed, be set to agree with the results of the operation, or only
485 changed if the item previously set into the condition code has been
488 Here is part of a sample :samp:`md` file for such a machine:
492 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
494 (define_attr "cc" "clobber,unchanged,set,change0"
495 (cond [(eq_attr "type" "load")
496 (const_string "change0")
497 (eq_attr "type" "store,branch")
498 (const_string "unchanged")
499 (eq_attr "type" "arith")
500 (if_then_else (match_operand:SI 0 "" "")
502 (const_string "clobber"))]
503 (const_string "clobber")))
506 [(set (match_operand:SI 0 "general_operand" "=r,r,m")
507 (match_operand:SI 1 "general_operand" "r,m,r"))]
513 [(set_attr "type" "arith,load,store")])
515 Note that we assume in the above example that arithmetic operations
516 performed on quantities smaller than a machine word clobber the condition
517 code since they will set the condition code to a value corresponding to the
520 .. index:: insn lengths, computing, computing the length of an insn
524 Computing the Length of an Insn
525 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
527 For many machines, multiple types of branch instructions are provided, each
528 for different length branch displacements. In most cases, the assembler
529 will choose the correct instruction to use. However, when the assembler
530 cannot do so, GCC can when a special attribute, the ``length``
531 attribute, is defined. This attribute must be defined to have numeric
532 values by specifying a null string in its ``define_attr``.
534 In the case of the ``length`` attribute, two additional forms of
535 arithmetic terms are allowed in test expressions:
537 .. index:: match_dup and attributes
539 :samp:`(match_dup {n})`
540 This refers to the address of operand :samp:`{n}` of the current insn, which
541 must be a ``label_ref``.
543 .. index:: pc and attributes
546 For non-branch instructions and backward branch instructions, this refers
547 to the address of the current insn. But for forward branch instructions,
548 this refers to the address of the next insn, because the length of the
549 current insn is to be computed.
551 .. index:: addr_vec, length of, addr_diff_vec, length of
553 For normal insns, the length will be determined by value of the
554 ``length`` attribute. In the case of ``addr_vec`` and
555 ``addr_diff_vec`` insn patterns, the length is computed as
556 the number of vectors multiplied by the size of each vector.
558 Lengths are measured in addressable storage units (bytes).
560 Note that it is possible to call functions via the ``symbol_ref``
561 mechanism to compute the length of an insn. However, if you use this
562 mechanism you must provide dummy clauses to express the maximum length
563 without using the function call. You can see an example of this in the
564 ``pa`` machine description for the ``call_symref`` pattern.
566 The following macros can be used to refine the length computation:
568 .. index:: ADJUST_INSN_LENGTH
570 :samp:`ADJUST_INSN_LENGTH ({insn}, {length})`
571 If defined, modifies the length assigned to instruction :samp:`{insn}` as a
572 function of the context in which it is used. :samp:`{length}` is an lvalue
573 that contains the initially computed length of the insn and should be
574 updated with the correct length of the insn.
576 This macro will normally not be required. A case in which it is
577 required is the ROMP. On this machine, the size of an ``addr_vec``
578 insn must be increased by two to compensate for the fact that alignment
581 .. index:: get_attr_length
583 The routine that returns ``get_attr_length`` (the value of the
584 ``length`` attribute) can be used by the output routine to
585 determine the form of the branch instruction to be written, as the
586 example below illustrates.
588 As an example of the specification of variable-length branches, consider
589 the IBM 360. If we adopt the convention that a register will be set to
590 the starting address of a function, we can jump to labels within 4k of
591 the start using a four-byte instruction. Otherwise, we need a six-byte
592 sequence to load the address from memory and then branch to it.
594 On such a machine, a pattern for a branch instruction might be specified
601 (label_ref (match_operand 0 "" "")))]
604 return (get_attr_length (insn) == 4
605 ? "b %l0" : "l r15,=a(%l0); br r15");
607 [(set (attr "length")
608 (if_then_else (lt (match_dup 0) (const_int 4096))
612 .. index:: constant attributes
614 .. _constant-attributes:
619 A special form of ``define_attr``, where the expression for the
620 default value is a ``const`` expression, indicates an attribute that
621 is constant for a given run of the compiler. Constant attributes may be
622 used to specify which variety of processor is used. For example,
626 (define_attr "cpu" "m88100,m88110,m88000"
628 (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
629 (symbol_ref "TARGET_88110") (const_string "m88110")]
630 (const_string "m88000"))))
632 (define_attr "memory" "fast,slow"
634 (if_then_else (symbol_ref "TARGET_FAST_MEM")
635 (const_string "fast")
636 (const_string "slow"))))
638 The routine generated for constant attributes has no parameters as it
639 does not depend on any particular insn. RTL expressions used to define
640 the value of a constant attribute may use the ``symbol_ref`` form,
641 but may not use either the ``match_operand`` form or ``eq_attr``
642 forms involving insn attributes.
644 .. index:: mnemonic attribute
646 .. _mnemonic-attribute:
651 The ``mnemonic`` attribute is a string type attribute holding the
652 instruction mnemonic for an insn alternative. The attribute values
653 will automatically be generated by the machine description parser if
654 there is an attribute definition in the md file:
658 (define_attr "mnemonic" "unknown" (const_string "unknown"))
660 The default value can be freely chosen as long as it does not collide
661 with any of the instruction mnemonics. This value will be used
662 whenever the machine description parser is not able to determine the
663 mnemonic string. This might be the case for output templates
664 containing more than a single instruction as in
665 ``"mvcle\t%0,%1,0\;jo\t.-4"``.
667 The ``mnemonic`` attribute set is not generated automatically if the
668 instruction string is generated via C code.
670 An existing ``mnemonic`` attribute set in an insn definition will not
671 be overriden by the md file parser. That way it is possible to
672 manually set the instruction mnemonics for the cases where the md file
673 parser fails to determine it automatically.
675 The ``mnemonic`` attribute is useful for dealing with instruction
676 specific properties in the pipeline description without defining
677 additional insn attributes.
681 (define_attr "ooo_expanded" ""
682 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
686 .. index:: delay slots, defining
690 Delay Slot Scheduling
691 ^^^^^^^^^^^^^^^^^^^^^
693 The insn attribute mechanism can be used to specify the requirements for
694 delay slots, if any, on a target machine. An instruction is said to
695 require a :dfn:`delay slot` if some instructions that are physically
696 after the instruction are executed as if they were located before it.
697 Classic examples are branch and call instructions, which often execute
698 the following instruction before the branch or call is performed.
700 On some machines, conditional branch instructions can optionally
701 :dfn:`annul` instructions in the delay slot. This means that the
702 instruction will not be executed for certain branch outcomes. Both
703 instructions that annul if the branch is true and instructions that
704 annul if the branch is false are supported.
706 Delay slot scheduling differs from instruction scheduling in that
707 determining whether an instruction needs a delay slot is dependent only
708 on the type of instruction being generated, not on data flow between the
709 instructions. See the next section for a discussion of data-dependent
710 instruction scheduling.
712 .. index:: define_delay
714 The requirement of an insn needing one or more delay slots is indicated
715 via the ``define_delay`` expression. It has the following form:
720 [delay-1 annul-true-1 annul-false-1
721 delay-2 annul-true-2 annul-false-2
724 :samp:`{test}` is an attribute test that indicates whether this
725 ``define_delay`` applies to a particular insn. If so, the number of
726 required delay slots is determined by the length of the vector specified
727 as the second argument. An insn placed in delay slot :samp:`{n}` must
728 satisfy attribute test :samp:`{delay-n}`. :samp:`{annul-true-n}` is an
729 attribute test that specifies which insns may be annulled if the branch
730 is true. Similarly, :samp:`{annul-false-n}` specifies which insns in the
731 delay slot may be annulled if the branch is false. If annulling is not
732 supported for that delay slot, ``(nil)`` should be coded.
734 For example, in the common case where branch and call insns require
735 a single delay slot, which may contain any insn other than a branch or
736 call, the following would be placed in the :samp:`md` file:
740 (define_delay (eq_attr "type" "branch,call")
741 [(eq_attr "type" "!branch,call") (nil) (nil)])
743 Multiple ``define_delay`` expressions may be specified. In this
744 case, each such expression specifies different delay slot requirements
745 and there must be no insn for which tests in two ``define_delay``
746 expressions are both true.
748 For example, if we have a machine that requires one delay slot for branches
749 but two for calls, no delay slot can contain a branch or call insn,
750 and any valid insn in the delay slot for the branch can be annulled if the
751 branch is true, we might represent this as follows:
755 (define_delay (eq_attr "type" "branch")
756 [(eq_attr "type" "!branch,call")
757 (eq_attr "type" "!branch,call")
760 (define_delay (eq_attr "type" "call")
761 [(eq_attr "type" "!branch,call") (nil) (nil)
762 (eq_attr "type" "!branch,call") (nil) (nil)])
764 .. the above is *still* too long. -mew 4feb93
766 .. index:: processor pipeline description, processor functional units, instruction latency time, interlock delays, data dependence delays, reservation delays, pipeline hazard recognizer, automaton based pipeline description, regular expressions, deterministic finite state automaton, automaton based scheduler, RISC, VLIW
768 .. _processor-pipeline-description:
770 Specifying processor pipeline description
771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
773 To achieve better performance, most modern processors
774 (super-pipelined, superscalar RISC, and VLIW
775 processors) have many :dfn:`functional units` on which several
776 instructions can be executed simultaneously. An instruction starts
777 execution if its issue conditions are satisfied. If not, the
778 instruction is stalled until its conditions are satisfied. Such
779 :dfn:`interlock (pipeline) delay` causes interruption of the fetching
780 of successor instructions (or demands nop instructions, e.g. for some
783 There are two major kinds of interlock delays in modern processors.
784 The first one is a data dependence delay determining :dfn:`instruction
785 latency time`. The instruction execution is not started until all
786 source data have been evaluated by prior instructions (there are more
787 complex cases when the instruction execution starts even when the data
788 are not available but will be ready in given time after the
789 instruction execution start). Taking the data dependence delays into
790 account is simple. The data dependence (true, output, and
791 anti-dependence) delay between two instructions is given by a
792 constant. In most cases this approach is adequate. The second kind
793 of interlock delays is a reservation delay. The reservation delay
794 means that two instructions under execution will be in need of shared
795 processors resources, i.e. buses, internal registers, and/or
796 functional units, which are reserved for some time. Taking this kind
797 of delay into account is complex especially for modern RISC
800 The task of exploiting more processor parallelism is solved by an
801 instruction scheduler. For a better solution to this problem, the
802 instruction scheduler has to have an adequate description of the
803 processor parallelism (or :dfn:`pipeline description`). GCC
804 machine descriptions describe processor parallelism and functional
805 unit reservations for groups of instructions with the aid of
806 :dfn:`regular expressions`.
808 The GCC instruction scheduler uses a :dfn:`pipeline hazard recognizer` to
809 figure out the possibility of the instruction issue by the processor
810 on a given simulated processor cycle. The pipeline hazard recognizer is
811 automatically generated from the processor pipeline description. The
812 pipeline hazard recognizer generated from the machine description
813 is based on a deterministic finite state automaton (DFA):
814 the instruction issue is possible if there is a transition from one
815 automaton state to another one. This algorithm is very fast, and
816 furthermore, its speed is not dependent on processor
819 .. [#f1] However, the size of the automaton depends on
820 processor complexity. To limit this effect, machine descriptions
821 can split orthogonal parts of the machine description among several
822 automata: but then, since each of these must be stepped independently,
823 this does cause a small decrease in the algorithm's performance.
825 .. index:: automaton based pipeline description
827 The rest of this section describes the directives that constitute
828 an automaton-based processor pipeline description. The order of
829 these constructions within the machine description file is not
832 .. index:: define_automaton, pipeline hazard recognizer
834 The following optional construction describes names of automata
835 generated and used for the pipeline hazards recognition. Sometimes
836 the generated finite state automaton used by the pipeline hazard
837 recognizer is large. If we use more than one automaton and bind functional
838 units to the automata, the total size of the automata is usually
839 less than the size of the single automaton. If there is no one such
840 construction, only one finite state automaton is generated.
844 (define_automaton automata-names)
846 :samp:`{automata-names}` is a string giving names of the automata. The
847 names are separated by commas. All the automata should have unique names.
848 The automaton name is used in the constructions ``define_cpu_unit`` and
849 ``define_query_cpu_unit``.
851 .. index:: define_cpu_unit, processor functional units
853 Each processor functional unit used in the description of instruction
854 reservations should be described by the following construction.
858 (define_cpu_unit unit-names [automaton-name])
860 :samp:`{unit-names}` is a string giving the names of the functional units
861 separated by commas. Don't use name :samp:`nothing`, it is reserved
864 :samp:`{automaton-name}` is a string giving the name of the automaton with
865 which the unit is bound. The automaton should be described in
866 construction ``define_automaton``. You should give
867 :dfn:`automaton-name`, if there is a defined automaton.
869 The assignment of units to automata are constrained by the uses of the
870 units in insn reservations. The most important constraint is: if a
871 unit reservation is present on a particular cycle of an alternative
872 for an insn reservation, then some unit from the same automaton must
873 be present on the same cycle for the other alternatives of the insn
874 reservation. The rest of the constraints are mentioned in the
875 description of the subsequent constructions.
877 .. index:: define_query_cpu_unit, querying function unit reservations
879 The following construction describes CPU functional units analogously
880 to ``define_cpu_unit``. The reservation of such units can be
881 queried for an automaton state. The instruction scheduler never
882 queries reservation of functional units for given automaton state. So
883 as a rule, you don't need this construction. This construction could
884 be used for future code generation goals (e.g. to generate
885 VLIW insn templates).
889 (define_query_cpu_unit unit-names [automaton-name])
891 :samp:`{unit-names}` is a string giving names of the functional units
894 :samp:`{automaton-name}` is a string giving the name of the automaton with
895 which the unit is bound.
897 .. index:: define_insn_reservation, instruction latency time, regular expressions, data bypass
899 The following construction is the major one to describe pipeline
900 characteristics of an instruction.
904 (define_insn_reservation insn-name default_latency
907 :samp:`{default_latency}` is a number giving latency time of the
908 instruction. There is an important difference between the old
909 description and the automaton based pipeline description. The latency
910 time is used for all dependencies when we use the old description. In
911 the automaton based pipeline description, the given latency time is only
912 used for true dependencies. The cost of anti-dependencies is always
913 zero and the cost of output dependencies is the difference between
914 latency times of the producing and consuming insns (if the difference
915 is negative, the cost is considered to be zero). You can always
916 change the default costs for any description by using the target hook
917 ``TARGET_SCHED_ADJUST_COST`` (see :ref:`scheduling`).
919 :samp:`{insn-name}` is a string giving the internal name of the insn. The
920 internal names are used in constructions ``define_bypass`` and in
921 the automaton description file generated for debugging. The internal
922 name has nothing in common with the names in ``define_insn``. It is a
923 good practice to use insn classes described in the processor manual.
925 :samp:`{condition}` defines what RTL insns are described by this
926 construction. You should remember that you will be in trouble if
927 :samp:`{condition}` for two or more different
928 ``define_insn_reservation`` constructions is TRUE for an insn. In
929 this case what reservation will be used for the insn is not defined.
930 Such cases are not checked during generation of the pipeline hazards
931 recognizer because in general recognizing that two conditions may have
932 the same value is quite difficult (especially if the conditions
933 contain ``symbol_ref``). It is also not checked during the
934 pipeline hazard recognizer work because it would slow down the
935 recognizer considerably.
937 :samp:`{regexp}` is a string describing the reservation of the cpu's functional
938 units by the instruction. The reservations are described by a regular
939 expression according to the following syntax:
943 regexp = regexp "," oneof
946 oneof = oneof "|" allof
949 allof = allof "+" repeat
952 repeat = element "*" number
955 element = cpu_function_unit_name
961 * :samp:`,` is used for describing the start of the next cycle in
964 * :samp:`|` is used for describing a reservation described by the first
965 regular expression **or** a reservation described by the second
966 regular expression **or** etc.
968 * :samp:`+` is used for describing a reservation described by the first
969 regular expression **and** a reservation described by the
970 second regular expression **and** etc.
972 * :samp:`*` is used for convenience and simply means a sequence in which
973 the regular expression are repeated :samp:`{number}` times with cycle
974 advancing (see :samp:`,`).
976 * :samp:`cpu_function_unit_name` denotes reservation of the named
979 * :samp:`reservation_name` --- see description of construction
980 :samp:`define_reservation`.
982 * :samp:`nothing` denotes no unit reservations.
984 .. index:: define_reservation
986 Sometimes unit reservations for different insns contain common parts.
987 In such case, you can simplify the pipeline description by describing
988 the common part by the following construction
992 (define_reservation reservation-name regexp)
994 :samp:`{reservation-name}` is a string giving name of :samp:`{regexp}`.
995 Functional unit names and reservation names are in the same name
996 space. So the reservation names should be different from the
997 functional unit names and cannot be the reserved name :samp:`nothing`.
999 .. index:: define_bypass, instruction latency time, data bypass
1001 The following construction is used to describe exceptions in the
1002 latency time for given instruction pair. This is so called bypasses.
1006 (define_bypass number out_insn_names in_insn_names
1009 :samp:`{number}` defines when the result generated by the instructions
1010 given in string :samp:`{out_insn_names}` will be ready for the
1011 instructions given in string :samp:`{in_insn_names}`. Each of these
1012 strings is a comma-separated list of filename-style globs and
1013 they refer to the names of ``define_insn_reservation`` s.
1018 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
1020 defines a bypass between instructions that start with
1021 :samp:`cpu1_load_` or :samp:`cpu1_store_` and those that start with
1024 :samp:`{guard}` is an optional string giving the name of a C function which
1025 defines an additional guard for the bypass. The function will get the
1026 two insns as parameters. If the function returns zero the bypass will
1027 be ignored for this case. The additional guard is necessary to
1028 recognize complicated bypasses, e.g. when the consumer is only an address
1029 of insn :samp:`store` (not a stored value).
1031 If there are more one bypass with the same output and input insns, the
1032 chosen bypass is the first bypass with a guard in description whose
1033 guard function returns nonzero. If there is no such bypass, then
1034 bypass without the guard function is chosen.
1036 .. index:: exclusion_set, presence_set, final_presence_set, absence_set, final_absence_set, VLIW, RISC
1038 The following five constructions are usually used to describe
1039 VLIW processors, or more precisely, to describe a placement
1040 of small instructions into VLIW instruction slots. They
1041 can be used for RISC processors, too.
1045 (exclusion_set unit-names unit-names)
1046 (presence_set unit-names patterns)
1047 (final_presence_set unit-names patterns)
1048 (absence_set unit-names patterns)
1049 (final_absence_set unit-names patterns)
1051 :samp:`{unit-names}` is a string giving names of functional units
1052 separated by commas.
1054 :samp:`{patterns}` is a string giving patterns of functional units
1055 separated by comma. Currently pattern is one unit or units
1056 separated by white-spaces.
1058 The first construction (:samp:`exclusion_set`) means that each
1059 functional unit in the first string cannot be reserved simultaneously
1060 with a unit whose name is in the second string and vice versa. For
1061 example, the construction is useful for describing processors
1062 (e.g. some SPARC processors) with a fully pipelined floating point
1063 functional unit which can execute simultaneously only single floating
1064 point insns or only double floating point insns.
1066 The second construction (:samp:`presence_set`) means that each
1067 functional unit in the first string cannot be reserved unless at
1068 least one of pattern of units whose names are in the second string is
1069 reserved. This is an asymmetric relation. For example, it is useful
1070 for description that VLIW :samp:`slot1` is reserved after
1071 :samp:`slot0` reservation. We could describe it by the following
1076 (presence_set "slot1" "slot0")
1078 Or :samp:`slot1` is reserved only after :samp:`slot0` and unit :samp:`b0`
1079 reservation. In this case we could write
1083 (presence_set "slot1" "slot0 b0")
1085 The third construction (:samp:`final_presence_set`) is analogous to
1086 :samp:`presence_set`. The difference between them is when checking is
1087 done. When an instruction is issued in given automaton state
1088 reflecting all current and planned unit reservations, the automaton
1089 state is changed. The first state is a source state, the second one
1090 is a result state. Checking for :samp:`presence_set` is done on the
1091 source state reservation, checking for :samp:`final_presence_set` is
1092 done on the result reservation. This construction is useful to
1093 describe a reservation which is actually two subsequent reservations.
1094 For example, if we use
1098 (presence_set "slot1" "slot0")
1100 the following insn will be never issued (because :samp:`slot1` requires
1101 :samp:`slot0` which is absent in the source state).
1105 (define_reservation "insn_and_nop" "slot0 + slot1")
1107 but it can be issued if we use analogous :samp:`final_presence_set`.
1109 The forth construction (:samp:`absence_set`) means that each functional
1110 unit in the first string can be reserved only if each pattern of units
1111 whose names are in the second string is not reserved. This is an
1112 asymmetric relation (actually :samp:`exclusion_set` is analogous to
1113 this one but it is symmetric). For example it might be useful in a
1114 VLIW description to say that :samp:`slot0` cannot be reserved
1115 after either :samp:`slot1` or :samp:`slot2` have been reserved. This
1116 can be described as:
1120 (absence_set "slot0" "slot1, slot2")
1122 Or :samp:`slot2` cannot be reserved if :samp:`slot0` and unit :samp:`b0`
1123 are reserved or :samp:`slot1` and unit :samp:`b1` are reserved. In
1124 this case we could write
1128 (absence_set "slot2" "slot0 b0, slot1 b1")
1130 All functional units mentioned in a set should belong to the same
1133 The last construction (:samp:`final_absence_set`) is analogous to
1134 :samp:`absence_set` but checking is done on the result (state)
1135 reservation. See comments for :samp:`final_presence_set`.
1137 .. index:: automata_option, deterministic finite state automaton, nondeterministic finite state automaton, finite state automaton minimization
1139 You can control the generator of the pipeline hazard recognizer with
1140 the following construction.
1144 (automata_option options)
1146 :samp:`{options}` is a string giving options which affect the generated
1147 code. Currently there are the following options:
1149 * :dfn:`no-minimization` makes no minimization of the automaton. This is
1150 only worth to do when we are debugging the description and need to
1151 look more accurately at reservations of states.
1153 * :dfn:`time` means printing time statistics about the generation of
1156 * :dfn:`stats` means printing statistics about the generated automata
1157 such as the number of DFA states, NDFA states and arcs.
1159 * :dfn:`v` means a generation of the file describing the result automata.
1160 The file has suffix :samp:`.dfa` and can be used for the description
1161 verification and debugging.
1163 * :dfn:`w` means a generation of warning instead of error for
1164 non-critical errors.
1166 * :dfn:`no-comb-vect` prevents the automaton generator from generating
1167 two data structures and comparing them for space efficiency. Using
1168 a comb vector to represent transitions may be better, but it can be
1169 very expensive to construct. This option is useful if the build
1170 process spends an unacceptably long time in genautomata.
1172 * :dfn:`ndfa` makes nondeterministic finite state automata. This affects
1173 the treatment of operator :samp:`|` in the regular expressions. The
1174 usual treatment of the operator is to try the first alternative and,
1175 if the reservation is not possible, the second alternative. The
1176 nondeterministic treatment means trying all alternatives, some of them
1177 may be rejected by reservations in the subsequent insns.
1179 * :dfn:`collapse-ndfa` modifies the behavior of the generator when
1180 producing an automaton. An additional state transition to collapse a
1181 nondeterministic NDFA state to a deterministic DFA
1182 state is generated. It can be triggered by passing ``const0_rtx`` to
1183 state_transition. In such an automaton, cycle advance transitions are
1184 available only for these collapsed states. This option is useful for
1185 ports that want to use the ``ndfa`` option, but also want to use
1186 ``define_query_cpu_unit`` to assign units to insns issued in a cycle.
1188 * :dfn:`progress` means output of a progress bar showing how many states
1189 were generated so far for automaton being processed. This is useful
1190 during debugging a DFA description. If you see too many
1191 generated states, you could interrupt the generator of the pipeline
1192 hazard recognizer and try to figure out a reason for generation of the
1195 As an example, consider a superscalar RISC machine which can
1196 issue three insns (two integer insns and one floating point insn) on
1197 the cycle but can finish only two insns. To describe this, we define
1198 the following functional units.
1202 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
1203 (define_cpu_unit "port0, port1")
1205 All simple integer insns can be executed in any integer pipeline and
1206 their result is ready in two cycles. The simple integer insns are
1207 issued into the first pipeline unless it is reserved, otherwise they
1208 are issued into the second pipeline. Integer division and
1209 multiplication insns can be executed only in the second integer
1210 pipeline and their results are ready correspondingly in 9 and 4
1211 cycles. The integer division is not pipelined, i.e. the subsequent
1212 integer division insn cannot be issued until the current division
1213 insn finished. Floating point insns are fully pipelined and their
1214 results are ready in 3 cycles. Where the result of a floating point
1215 insn is used by an integer insn, an additional delay of one cycle is
1216 incurred. To describe all of this we could specify
1220 (define_cpu_unit "div")
1222 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
1223 "(i0_pipeline | i1_pipeline), (port0 | port1)")
1225 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
1226 "i1_pipeline, nothing*2, (port0 | port1)")
1228 (define_insn_reservation "div" 9 (eq_attr "type" "div")
1229 "i1_pipeline, div*7, div + (port0 | port1)")
1231 (define_insn_reservation "float" 3 (eq_attr "type" "float")
1232 "f_pipeline, nothing, (port0 | port1))
1234 (define_bypass 4 "float" "simple,mult,div")
1236 To simplify the description we could describe the following reservation
1240 (define_reservation "finish" "port0|port1")
1242 and use it in all ``define_insn_reservation`` as in the following
1247 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
1248 "(i0_pipeline | i1_pipeline), finish")