diff options
Diffstat (limited to 'share/doc/gccint/RTL-Template.html')
| -rw-r--r-- | share/doc/gccint/RTL-Template.html | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/share/doc/gccint/RTL-Template.html b/share/doc/gccint/RTL-Template.html new file mode 100644 index 0000000..70279a9 --- /dev/null +++ b/share/doc/gccint/RTL-Template.html @@ -0,0 +1,342 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>GNU Compiler Collection (GCC) Internals: RTL Template</title> + +<meta name="description" content="GNU Compiler Collection (GCC) Internals: RTL Template"> +<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: RTL Template"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Machine-Desc.html#Machine-Desc" rel="up" title="Machine Desc"> +<link href="Output-Template.html#Output-Template" rel="next" title="Output Template"> +<link href="Example.html#Example" rel="previous" title="Example"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="RTL-Template"></a> +<div class="header"> +<p> +Next: <a href="Output-Template.html#Output-Template" accesskey="n" rel="next">Output Template</a>, Previous: <a href="Example.html#Example" accesskey="p" rel="previous">Example</a>, Up: <a href="Machine-Desc.html#Machine-Desc" accesskey="u" rel="up">Machine Desc</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="RTL-Template-1"></a> +<h3 class="section">17.4 RTL Template</h3> +<a name="index-RTL-insn-template"></a> +<a name="index-generating-insns"></a> +<a name="index-insns_002c-generating"></a> +<a name="index-recognizing-insns"></a> +<a name="index-insns_002c-recognizing"></a> + +<p>The RTL template is used to define which insns match the particular pattern +and how to find their operands. For named patterns, the RTL template also +says how to construct an insn from specified operands. +</p> +<p>Construction involves substituting specified operands into a copy of the +template. Matching involves determining the values that serve as the +operands in the insn being matched. Both of these activities are +controlled by special expression types that direct matching and +substitution of the operands. +</p> +<dl compact="compact"> +<dd><a name="index-match_005foperand"></a> +</dd> +<dt><code>(match_operand:<var>m</var> <var>n</var> <var>predicate</var> <var>constraint</var>)</code></dt> +<dd><p>This expression is a placeholder for operand number <var>n</var> of +the insn. When constructing an insn, operand number <var>n</var> +will be substituted at this point. When matching an insn, whatever +appears at this position in the insn will be taken as operand +number <var>n</var>; but it must satisfy <var>predicate</var> or this instruction +pattern will not match at all. +</p> +<p>Operand numbers must be chosen consecutively counting from zero in +each instruction pattern. There may be only one <code>match_operand</code> +expression in the pattern for each operand number. Usually operands +are numbered in the order of appearance in <code>match_operand</code> +expressions. In the case of a <code>define_expand</code>, any operand numbers +used only in <code>match_dup</code> expressions have higher values than all +other operand numbers. +</p> +<p><var>predicate</var> is a string that is the name of a function that +accepts two arguments, an expression and a machine mode. +See <a href="Predicates.html#Predicates">Predicates</a>. During matching, the function will be called with +the putative operand as the expression and <var>m</var> as the mode +argument (if <var>m</var> is not specified, <code>VOIDmode</code> will be used, +which normally causes <var>predicate</var> to accept any mode). If it +returns zero, this instruction pattern fails to match. +<var>predicate</var> may be an empty string; then it means no test is to be +done on the operand, so anything which occurs in this position is +valid. +</p> +<p>Most of the time, <var>predicate</var> will reject modes other than <var>m</var>—but +not always. For example, the predicate <code>address_operand</code> uses +<var>m</var> as the mode of memory ref that the address should be valid for. +Many predicates accept <code>const_int</code> nodes even though their mode is +<code>VOIDmode</code>. +</p> +<p><var>constraint</var> controls reloading and the choice of the best register +class to use for a value, as explained later (see <a href="Constraints.html#Constraints">Constraints</a>). +If the constraint would be an empty string, it can be omitted. +</p> +<p>People are often unclear on the difference between the constraint and the +predicate. The predicate helps decide whether a given insn matches the +pattern. The constraint plays no role in this decision; instead, it +controls various decisions in the case of an insn which does match. +</p> +<a name="index-match_005fscratch"></a> +</dd> +<dt><code>(match_scratch:<var>m</var> <var>n</var> <var>constraint</var>)</code></dt> +<dd><p>This expression is also a placeholder for operand number <var>n</var> +and indicates that operand must be a <code>scratch</code> or <code>reg</code> +expression. +</p> +<p>When matching patterns, this is equivalent to +</p> +<div class="smallexample"> +<pre class="smallexample">(match_operand:<var>m</var> <var>n</var> "scratch_operand" <var>constraint</var>) +</pre></div> + +<p>but, when generating RTL, it produces a (<code>scratch</code>:<var>m</var>) +expression. +</p> +<p>If the last few expressions in a <code>parallel</code> are <code>clobber</code> +expressions whose operands are either a hard register or +<code>match_scratch</code>, the combiner can add or delete them when +necessary. See <a href="Side-Effects.html#Side-Effects">Side Effects</a>. +</p> +<a name="index-match_005fdup"></a> +</dd> +<dt><code>(match_dup <var>n</var>)</code></dt> +<dd><p>This expression is also a placeholder for operand number <var>n</var>. +It is used when the operand needs to appear more than once in the +insn. +</p> +<p>In construction, <code>match_dup</code> acts just like <code>match_operand</code>: +the operand is substituted into the insn being constructed. But in +matching, <code>match_dup</code> behaves differently. It assumes that operand +number <var>n</var> has already been determined by a <code>match_operand</code> +appearing earlier in the recognition template, and it matches only an +identical-looking expression. +</p> +<p>Note that <code>match_dup</code> should not be used to tell the compiler that +a particular register is being used for two operands (example: +<code>add</code> that adds one register to another; the second register is +both an input operand and the output operand). Use a matching +constraint (see <a href="Simple-Constraints.html#Simple-Constraints">Simple Constraints</a>) for those. <code>match_dup</code> is for the cases where one +operand is used in two places in the template, such as an instruction +that computes both a quotient and a remainder, where the opcode takes +two input operands but the RTL template has to refer to each of those +twice; once for the quotient pattern and once for the remainder pattern. +</p> +<a name="index-match_005foperator"></a> +</dd> +<dt><code>(match_operator:<var>m</var> <var>n</var> <var>predicate</var> [<var>operands</var>…])</code></dt> +<dd><p>This pattern is a kind of placeholder for a variable RTL expression +code. +</p> +<p>When constructing an insn, it stands for an RTL expression whose +expression code is taken from that of operand <var>n</var>, and whose +operands are constructed from the patterns <var>operands</var>. +</p> +<p>When matching an expression, it matches an expression if the function +<var>predicate</var> returns nonzero on that expression <em>and</em> the +patterns <var>operands</var> match the operands of the expression. +</p> +<p>Suppose that the function <code>commutative_operator</code> is defined as +follows, to match any expression whose operator is one of the +commutative arithmetic operators of RTL and whose mode is <var>mode</var>: +</p> +<div class="smallexample"> +<pre class="smallexample">int +commutative_operator (x, mode) + rtx x; + machine_mode mode; +{ + enum rtx_code code = GET_CODE (x); + if (GET_MODE (x) != mode) + return 0; + return (GET_RTX_CLASS (code) == RTX_COMM_ARITH + || code == EQ || code == NE); +} +</pre></div> + +<p>Then the following pattern will match any RTL expression consisting +of a commutative operator applied to two general operands: +</p> +<div class="smallexample"> +<pre class="smallexample">(match_operator:SI 3 "commutative_operator" + [(match_operand:SI 1 "general_operand" "g") + (match_operand:SI 2 "general_operand" "g")]) +</pre></div> + +<p>Here the vector <code>[<var>operands</var>…]</code> contains two patterns +because the expressions to be matched all contain two operands. +</p> +<p>When this pattern does match, the two operands of the commutative +operator are recorded as operands 1 and 2 of the insn. (This is done +by the two instances of <code>match_operand</code>.) Operand 3 of the insn +will be the entire commutative expression: use <code>GET_CODE +(operands[3])</code> to see which commutative operator was used. +</p> +<p>The machine mode <var>m</var> of <code>match_operator</code> works like that of +<code>match_operand</code>: it is passed as the second argument to the +predicate function, and that function is solely responsible for +deciding whether the expression to be matched “has” that mode. +</p> +<p>When constructing an insn, argument 3 of the gen-function will specify +the operation (i.e. the expression code) for the expression to be +made. It should be an RTL expression, whose expression code is copied +into a new expression whose operands are arguments 1 and 2 of the +gen-function. The subexpressions of argument 3 are not used; +only its expression code matters. +</p> +<p>When <code>match_operator</code> is used in a pattern for matching an insn, +it usually best if the operand number of the <code>match_operator</code> +is higher than that of the actual operands of the insn. This improves +register allocation because the register allocator often looks at +operands 1 and 2 of insns to see if it can do register tying. +</p> +<p>There is no way to specify constraints in <code>match_operator</code>. The +operand of the insn which corresponds to the <code>match_operator</code> +never has any constraints because it is never reloaded as a whole. +However, if parts of its <var>operands</var> are matched by +<code>match_operand</code> patterns, those parts may have constraints of +their own. +</p> +<a name="index-match_005fop_005fdup"></a> +</dd> +<dt><code>(match_op_dup:<var>m</var> <var>n</var>[<var>operands</var>…])</code></dt> +<dd><p>Like <code>match_dup</code>, except that it applies to operators instead of +operands. When constructing an insn, operand number <var>n</var> will be +substituted at this point. But in matching, <code>match_op_dup</code> behaves +differently. It assumes that operand number <var>n</var> has already been +determined by a <code>match_operator</code> appearing earlier in the +recognition template, and it matches only an identical-looking +expression. +</p> +<a name="index-match_005fparallel"></a> +</dd> +<dt><code>(match_parallel <var>n</var> <var>predicate</var> [<var>subpat</var>…])</code></dt> +<dd><p>This pattern is a placeholder for an insn that consists of a +<code>parallel</code> expression with a variable number of elements. This +expression should only appear at the top level of an insn pattern. +</p> +<p>When constructing an insn, operand number <var>n</var> will be substituted at +this point. When matching an insn, it matches if the body of the insn +is a <code>parallel</code> expression with at least as many elements as the +vector of <var>subpat</var> expressions in the <code>match_parallel</code>, if each +<var>subpat</var> matches the corresponding element of the <code>parallel</code>, +<em>and</em> the function <var>predicate</var> returns nonzero on the +<code>parallel</code> that is the body of the insn. It is the responsibility +of the predicate to validate elements of the <code>parallel</code> beyond +those listed in the <code>match_parallel</code>. +</p> +<p>A typical use of <code>match_parallel</code> is to match load and store +multiple expressions, which can contain a variable number of elements +in a <code>parallel</code>. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">(define_insn "" + [(match_parallel 0 "load_multiple_operation" + [(set (match_operand:SI 1 "gpc_reg_operand" "=r") + (match_operand:SI 2 "memory_operand" "m")) + (use (reg:SI 179)) + (clobber (reg:SI 179))])] + "" + "loadm 0,0,%1,%2") +</pre></div> + +<p>This example comes from <samp>a29k.md</samp>. The function +<code>load_multiple_operation</code> is defined in <samp>a29k.c</samp> and checks +that subsequent elements in the <code>parallel</code> are the same as the +<code>set</code> in the pattern, except that they are referencing subsequent +registers and memory locations. +</p> +<p>An insn that matches this pattern might look like: +</p> +<div class="smallexample"> +<pre class="smallexample">(parallel + [(set (reg:SI 20) (mem:SI (reg:SI 100))) + (use (reg:SI 179)) + (clobber (reg:SI 179)) + (set (reg:SI 21) + (mem:SI (plus:SI (reg:SI 100) + (const_int 4)))) + (set (reg:SI 22) + (mem:SI (plus:SI (reg:SI 100) + (const_int 8))))]) +</pre></div> + +<a name="index-match_005fpar_005fdup"></a> +</dd> +<dt><code>(match_par_dup <var>n</var> [<var>subpat</var>…])</code></dt> +<dd><p>Like <code>match_op_dup</code>, but for <code>match_parallel</code> instead of +<code>match_operator</code>. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Output-Template.html#Output-Template" accesskey="n" rel="next">Output Template</a>, Previous: <a href="Example.html#Example" accesskey="p" rel="previous">Example</a>, Up: <a href="Machine-Desc.html#Machine-Desc" accesskey="u" rel="up">Machine Desc</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |