This is gccint.info, produced by makeinfo version 7.1 from gccint.texi. Copyright © 1988-2024 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. INFO-DIR-SECTION Software development START-INFO-DIR-ENTRY * gccint: (gccint). Internals of the GNU Compiler Collection. END-INFO-DIR-ENTRY This file documents the internals of the GNU compilers. Copyright © 1988-2024 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.  File: gccint.info, Node: C++ Expressions, Prev: Statements for C and C++, Up: C and C++ Trees 11.10.6 C++ Expressions ----------------------- This section describes expressions specific to the C and C++ front ends. ‘TYPEID_EXPR’ Used to represent a ‘typeid’ expression. ‘NEW_EXPR’ ‘VEC_NEW_EXPR’ Used to represent a call to ‘new’ and ‘new[]’ respectively. ‘DELETE_EXPR’ ‘VEC_DELETE_EXPR’ Used to represent a call to ‘delete’ and ‘delete[]’ respectively. ‘MEMBER_REF’ Represents a reference to a member of a class. ‘THROW_EXPR’ Represents an instance of ‘throw’ in the program. Operand 0, which is the expression to throw, may be ‘NULL_TREE’. ‘AGGR_INIT_EXPR’ An ‘AGGR_INIT_EXPR’ represents the initialization as the return value of a function call, or as the result of a constructor. An ‘AGGR_INIT_EXPR’ will only appear as a full-expression, or as the second operand of a ‘TARGET_EXPR’. ‘AGGR_INIT_EXPR’s have a representation similar to that of ‘CALL_EXPR’s. You can use the ‘AGGR_INIT_EXPR_FN’ and ‘AGGR_INIT_EXPR_ARG’ macros to access the function to call and the arguments to pass. If ‘AGGR_INIT_VIA_CTOR_P’ holds of the ‘AGGR_INIT_EXPR’, then the initialization is via a constructor call. The address of the ‘AGGR_INIT_EXPR_SLOT’ operand, which is always a ‘VAR_DECL’, is taken, and this value replaces the first argument in the argument list. In either case, the expression is void.  File: gccint.info, Node: GIMPLE, Next: Tree SSA, Prev: GENERIC, Up: Top 12 GIMPLE ********* GIMPLE is a three-address representation derived from GENERIC by breaking down GENERIC expressions into tuples of no more than 3 operands (with some exceptions like function calls). GIMPLE was heavily influenced by the SIMPLE IL used by the McCAT compiler project at McGill University, though we have made some different choices. For one thing, SIMPLE doesn't support ‘goto’. Temporaries are introduced to hold intermediate values needed to compute complex expressions. Additionally, all the control structures used in GENERIC are lowered into conditional jumps, lexical scopes are removed and exception regions are converted into an on the side exception region tree. The compiler pass which converts GENERIC into GIMPLE is referred to as the ‘gimplifier’. The gimplifier works recursively, generating GIMPLE tuples out of the original GENERIC expressions. One of the early implementation strategies used for the GIMPLE representation was to use the same internal data structures used by front ends to represent parse trees. This simplified implementation because we could leverage existing functionality and interfaces. However, GIMPLE is a much more restrictive representation than abstract syntax trees (AST), therefore it does not require the full structural complexity provided by the main tree data structure. The GENERIC representation of a function is stored in the ‘DECL_SAVED_TREE’ field of the associated ‘FUNCTION_DECL’ tree node. It is converted to GIMPLE by a call to ‘gimplify_function_tree’. If a front end wants to include language-specific tree codes in the tree representation which it provides to the back end, it must provide a definition of ‘LANG_HOOKS_GIMPLIFY_EXPR’ which knows how to convert the front end trees to GIMPLE. Usually such a hook will involve much of the same code for expanding front end trees to RTL. This function can return fully lowered GIMPLE, or it can return GENERIC trees and let the main gimplifier lower them the rest of the way; this is often simpler. GIMPLE that is not fully lowered is known as "High GIMPLE" and consists of the IL before the pass ‘pass_lower_cf’. High GIMPLE contains some container statements like lexical scopes (represented by ‘GIMPLE_BIND’) and nested expressions (e.g., ‘GIMPLE_TRY’), while "Low GIMPLE" exposes all of the implicit jumps for control and exception expressions directly in the IL and EH region trees. The C and C++ front ends currently convert directly from front end trees to GIMPLE, and hand that off to the back end rather than first converting to GENERIC. Their gimplifier hooks know about all the ‘_STMT’ nodes and how to convert them to GENERIC forms. There was some work done on a genericization pass which would run first, but the existence of ‘STMT_EXPR’ meant that in order to convert all of the C statements into GENERIC equivalents would involve walking the entire tree anyway, so it was simpler to lower all the way. This might change in the future if someone writes an optimization pass which would work better with higher-level trees, but currently the optimizers all expect GIMPLE. You can request to dump a C-like representation of the GIMPLE form with the flag ‘-fdump-tree-gimple’. * Menu: * Tuple representation:: * Class hierarchy of GIMPLE statements:: * GIMPLE instruction set:: * GIMPLE Exception Handling:: * Temporaries:: * Operands:: * Manipulating GIMPLE statements:: * Tuple specific accessors:: * GIMPLE sequences:: * Sequence iterators:: * Adding a new GIMPLE statement code:: * Statement and operand traversals::  File: gccint.info, Node: Tuple representation, Next: Class hierarchy of GIMPLE statements, Up: GIMPLE 12.1 Tuple representation ========================= GIMPLE instructions are tuples of variable size divided in two groups: a header describing the instruction and its locations, and a variable length body with all the operands. Tuples are organized into a hierarchy with 3 main classes of tuples. 12.1.1 ‘gimple’ (gsbase) ------------------------ This is the root of the hierarchy, it holds basic information needed by most GIMPLE statements. There are some fields that may not be relevant to every GIMPLE statement, but those were moved into the base structure to take advantage of holes left by other fields (thus making the structure more compact). The structure takes 4 words (32 bytes) on 64 bit hosts: Field Size (bits) ‘code’ 8 ‘subcode’ 16 ‘no_warning’ 1 ‘visited’ 1 ‘nontemporal_move’ 1 ‘plf’ 2 ‘modified’ 1 ‘has_volatile_ops’ 1 ‘references_memory_p’ 1 ‘uid’ 32 ‘location’ 32 ‘num_ops’ 32 ‘bb’ 64 ‘block’ 63 Total size 32 bytes • ‘code’ Main identifier for a GIMPLE instruction. • ‘subcode’ Used to distinguish different variants of the same basic instruction or provide flags applicable to a given code. The ‘subcode’ flags field has different uses depending on the code of the instruction, but mostly it distinguishes instructions of the same family. The most prominent use of this field is in assignments, where subcode indicates the operation done on the RHS of the assignment. For example, a = b + c is encoded as ‘GIMPLE_ASSIGN ’. • ‘no_warning’ Bitflag to indicate whether a warning has already been issued on this statement. • ‘visited’ General purpose "visited" marker. Set and cleared by each pass when needed. • ‘nontemporal_move’ Bitflag used in assignments that represent non-temporal moves. Although this bitflag is only used in assignments, it was moved into the base to take advantage of the bit holes left by the previous fields. • ‘plf’ Pass Local Flags. This 2-bit mask can be used as general purpose markers by any pass. Passes are responsible for clearing and setting these two flags accordingly. • ‘modified’ Bitflag to indicate whether the statement has been modified. Used mainly by the operand scanner to determine when to re-scan a statement for operands. • ‘has_volatile_ops’ Bitflag to indicate whether this statement contains operands that have been marked volatile. • ‘references_memory_p’ Bitflag to indicate whether this statement contains memory references (i.e., its operands are either global variables, or pointer dereferences or anything that must reside in memory). • ‘uid’ This is an unsigned integer used by passes that want to assign IDs to every statement. These IDs must be assigned and used by each pass. • ‘location’ This is a ‘location_t’ identifier to specify source code location for this statement. It is inherited from the front end. • ‘num_ops’ Number of operands that this statement has. This specifies the size of the operand vector embedded in the tuple. Only used in some tuples, but it is declared in the base tuple to take advantage of the 32-bit hole left by the previous fields. • ‘bb’ Basic block holding the instruction. • ‘block’ Lexical block holding this statement. Also used for debug information generation. 12.1.2 ‘gimple_statement_with_ops’ ---------------------------------- This tuple is actually split in two: ‘gimple_statement_with_ops_base’ and ‘gimple_statement_with_ops’. This is needed to accommodate the way the operand vector is allocated. The operand vector is defined to be an array of 1 element. So, to allocate a dynamic number of operands, the memory allocator (‘gimple_alloc’) simply allocates enough memory to hold the structure itself plus ‘N - 1’ operands which run "off the end" of the structure. For example, to allocate space for a tuple with 3 operands, ‘gimple_alloc’ reserves ‘sizeof (struct gimple_statement_with_ops) + 2 * sizeof (tree)’ bytes. On the other hand, several fields in this tuple need to be shared with the ‘gimple_statement_with_memory_ops’ tuple. So, these common fields are placed in ‘gimple_statement_with_ops_base’ which is then inherited from the other two tuples. ‘gsbase’ 256 ‘def_ops’ 64 ‘use_ops’ 64 ‘op’ ‘num_ops’ * 64 Total 48 + 8 * ‘num_ops’ bytes size • ‘gsbase’ Inherited from ‘struct gimple’. • ‘def_ops’ Array of pointers into the operand array indicating all the slots that contain a variable written-to by the statement. This array is also used for immediate use chaining. Note that it would be possible to not rely on this array, but the changes required to implement this are pretty invasive. • ‘use_ops’ Similar to ‘def_ops’ but for variables read by the statement. • ‘op’ Array of trees with ‘num_ops’ slots. 12.1.3 ‘gimple_statement_with_memory_ops’ ----------------------------------------- This tuple is essentially identical to ‘gimple_statement_with_ops’, except that it contains 4 additional fields to hold vectors related memory stores and loads. Similar to the previous case, the structure is split in two to accommodate for the operand vector (‘gimple_statement_with_memory_ops_base’ and ‘gimple_statement_with_memory_ops’). Field Size (bits) ‘gsbase’ 256 ‘def_ops’ 64 ‘use_ops’ 64 ‘vdef_ops’ 64 ‘vuse_ops’ 64 ‘stores’ 64 ‘loads’ 64 ‘op’ ‘num_ops’ * 64 Total size 80 + 8 * ‘num_ops’ bytes • ‘vdef_ops’ Similar to ‘def_ops’ but for ‘VDEF’ operators. There is one entry per memory symbol written by this statement. This is used to maintain the memory SSA use-def and def-def chains. • ‘vuse_ops’ Similar to ‘use_ops’ but for ‘VUSE’ operators. There is one entry per memory symbol loaded by this statement. This is used to maintain the memory SSA use-def chains. • ‘stores’ Bitset with all the UIDs for the symbols written-to by the statement. This is different than ‘vdef_ops’ in that all the affected symbols are mentioned in this set. If memory partitioning is enabled, the ‘vdef_ops’ vector will refer to memory partitions. Furthermore, no SSA information is stored in this set. • ‘loads’ Similar to ‘stores’, but for memory loads. (Note that there is some amount of redundancy here, it should be possible to reduce memory utilization further by removing these sets). All the other tuples are defined in terms of these three basic ones. Each tuple will add some fields.  File: gccint.info, Node: Class hierarchy of GIMPLE statements, Next: GIMPLE instruction set, Prev: Tuple representation, Up: GIMPLE 12.2 Class hierarchy of GIMPLE statements ========================================= The following diagram shows the C++ inheritance hierarchy of statement kinds, along with their relationships to ‘GSS_’ values (layouts) and ‘GIMPLE_’ values (codes): gimple | layout: GSS_BASE | used for 4 codes: GIMPLE_ERROR_MARK | GIMPLE_NOP | GIMPLE_OMP_SECTIONS_SWITCH | GIMPLE_PREDICT | + gimple_statement_with_ops_base | | (no GSS layout) | | | + gimple_statement_with_ops | | | layout: GSS_WITH_OPS | | | | | + gcond | | | code: GIMPLE_COND | | | | | + gdebug | | | code: GIMPLE_DEBUG | | | | | + ggoto | | | code: GIMPLE_GOTO | | | | | + glabel | | | code: GIMPLE_LABEL | | | | | + gswitch | | code: GIMPLE_SWITCH | | | + gimple_statement_with_memory_ops_base | | layout: GSS_WITH_MEM_OPS_BASE | | | + gimple_statement_with_memory_ops | | | layout: GSS_WITH_MEM_OPS | | | | | + gassign | | | code GIMPLE_ASSIGN | | | | | + greturn | | code GIMPLE_RETURN | | | + gcall | | layout: GSS_CALL, code: GIMPLE_CALL | | | + gasm | | layout: GSS_ASM, code: GIMPLE_ASM | | | + gtransaction | layout: GSS_TRANSACTION, code: GIMPLE_TRANSACTION | + gimple_statement_omp | | layout: GSS_OMP. Used for code GIMPLE_OMP_SECTION | | | + gomp_critical | | layout: GSS_OMP_CRITICAL, code: GIMPLE_OMP_CRITICAL | | | + gomp_for | | layout: GSS_OMP_FOR, code: GIMPLE_OMP_FOR | | | + gomp_parallel_layout | | | layout: GSS_OMP_PARALLEL_LAYOUT | | | | | + gimple_statement_omp_taskreg | | | | | | | + gomp_parallel | | | | code: GIMPLE_OMP_PARALLEL | | | | | | | + gomp_task | | | code: GIMPLE_OMP_TASK | | | | | + gimple_statement_omp_target | | code: GIMPLE_OMP_TARGET | | | + gomp_sections | | layout: GSS_OMP_SECTIONS, code: GIMPLE_OMP_SECTIONS | | | + gimple_statement_omp_single_layout | | layout: GSS_OMP_SINGLE_LAYOUT | | | + gomp_single | | code: GIMPLE_OMP_SINGLE | | | + gomp_teams | code: GIMPLE_OMP_TEAMS | + gbind | layout: GSS_BIND, code: GIMPLE_BIND | + gcatch | layout: GSS_CATCH, code: GIMPLE_CATCH | + geh_filter | layout: GSS_EH_FILTER, code: GIMPLE_EH_FILTER | + geh_else | layout: GSS_EH_ELSE, code: GIMPLE_EH_ELSE | + geh_mnt | layout: GSS_EH_MNT, code: GIMPLE_EH_MUST_NOT_THROW | + gphi | layout: GSS_PHI, code: GIMPLE_PHI | + gimple_statement_eh_ctrl | | layout: GSS_EH_CTRL | | | + gresx | | code: GIMPLE_RESX | | | + geh_dispatch | code: GIMPLE_EH_DISPATCH | + gtry | layout: GSS_TRY, code: GIMPLE_TRY | + gimple_statement_wce | layout: GSS_WCE, code: GIMPLE_WITH_CLEANUP_EXPR | + gomp_continue | layout: GSS_OMP_CONTINUE, code: GIMPLE_OMP_CONTINUE | + gomp_atomic_load | layout: GSS_OMP_ATOMIC_LOAD, code: GIMPLE_OMP_ATOMIC_LOAD | + gimple_statement_omp_atomic_store_layout | layout: GSS_OMP_ATOMIC_STORE_LAYOUT, | code: GIMPLE_OMP_ATOMIC_STORE | + gomp_atomic_store | code: GIMPLE_OMP_ATOMIC_STORE | + gomp_return code: GIMPLE_OMP_RETURN  File: gccint.info, Node: GIMPLE instruction set, Next: GIMPLE Exception Handling, Prev: Class hierarchy of GIMPLE statements, Up: GIMPLE 12.3 GIMPLE instruction set =========================== The following table briefly describes the GIMPLE instruction set. Instruction High GIMPLE Low GIMPLE ‘GIMPLE_ASM’ x x ‘GIMPLE_ASSIGN’ x x ‘GIMPLE_BIND’ x ‘GIMPLE_CALL’ x x ‘GIMPLE_CATCH’ x ‘GIMPLE_COND’ x x ‘GIMPLE_DEBUG’ x x ‘GIMPLE_EH_FILTER’ x ‘GIMPLE_GOTO’ x x ‘GIMPLE_LABEL’ x x ‘GIMPLE_NOP’ x x ‘GIMPLE_OMP_ATOMIC_LOAD’ x x ‘GIMPLE_OMP_ATOMIC_STORE’ x x ‘GIMPLE_OMP_CONTINUE’ x x ‘GIMPLE_OMP_CRITICAL’ x x ‘GIMPLE_OMP_FOR’ x x ‘GIMPLE_OMP_MASTER’ x x ‘GIMPLE_OMP_ORDERED’ x x ‘GIMPLE_OMP_PARALLEL’ x x ‘GIMPLE_OMP_RETURN’ x x ‘GIMPLE_OMP_SECTION’ x x ‘GIMPLE_OMP_SECTIONS’ x x ‘GIMPLE_OMP_SECTIONS_SWITCH’ x x ‘GIMPLE_OMP_SINGLE’ x x ‘GIMPLE_PHI’ x ‘GIMPLE_OMP_STRUCTURED_BLOCK’ x ‘GIMPLE_RESX’ x ‘GIMPLE_RETURN’ x x ‘GIMPLE_SWITCH’ x x ‘GIMPLE_TRY’ x  File: gccint.info, Node: GIMPLE Exception Handling, Next: Temporaries, Prev: GIMPLE instruction set, Up: GIMPLE 12.4 Exception Handling ======================= Other exception handling constructs are represented using ‘GIMPLE_TRY_CATCH’. ‘GIMPLE_TRY_CATCH’ has two operands. The first operand is a sequence of statements to execute. If executing these statements does not throw an exception, then the second operand is ignored. Otherwise, if an exception is thrown, then the second operand of the ‘GIMPLE_TRY_CATCH’ is checked. The second operand may have the following forms: 1. A sequence of statements to execute. When an exception occurs, these statements are executed, and then the exception is rethrown. 2. A sequence of ‘GIMPLE_CATCH’ statements. Each ‘GIMPLE_CATCH’ has a list of applicable exception types and handler code. If the thrown exception matches one of the caught types, the associated handler code is executed. If the handler code falls off the bottom, execution continues after the original ‘GIMPLE_TRY_CATCH’. 3. A ‘GIMPLE_EH_FILTER’ statement. This has a list of permitted exception types, and code to handle a match failure. If the thrown exception does not match one of the allowed types, the associated match failure code is executed. If the thrown exception does match, it continues unwinding the stack looking for the next handler. Currently throwing an exception is not directly represented in GIMPLE, since it is implemented by calling a function. At some point in the future we will want to add some way to express that the call will throw an exception of a known type. Just before running the optimizers, the compiler lowers the high-level EH constructs above into a set of ‘goto’s, magic labels, and EH regions. Continuing to unwind at the end of a cleanup is represented with a ‘GIMPLE_RESX’.  File: gccint.info, Node: Temporaries, Next: Operands, Prev: GIMPLE Exception Handling, Up: GIMPLE 12.5 Temporaries ================ When gimplification encounters a subexpression that is too complex, it creates a new temporary variable to hold the value of the subexpression, and adds a new statement to initialize it before the current statement. These special temporaries are known as ‘expression temporaries’, and are allocated using ‘get_formal_tmp_var’. The compiler tries to always evaluate identical expressions into the same temporary, to simplify elimination of redundant calculations. We can only use expression temporaries when we know that it will not be reevaluated before its value is used, and that it will not be otherwise modified(1). Other temporaries can be allocated using ‘get_initialized_tmp_var’ or ‘create_tmp_var’. Currently, an expression like ‘a = b + 5’ is not reduced any further. We tried converting it to something like T1 = b + 5; a = T1; but this bloated the representation for minimal benefit. However, a variable which must live in memory cannot appear in an expression; its value is explicitly loaded into a temporary first. Similarly, storing the value of an expression to a memory variable goes through a temporary. ---------- Footnotes ---------- (1) These restrictions are derived from those in Morgan 4.8.  File: gccint.info, Node: Operands, Next: Manipulating GIMPLE statements, Prev: Temporaries, Up: GIMPLE 12.6 Operands ============= In general, expressions in GIMPLE consist of an operation and the appropriate number of simple operands; these operands must either be a GIMPLE rvalue (‘is_gimple_val’), i.e. a constant or a register variable. More complex operands are factored out into temporaries, so that a = b + c + d becomes T1 = b + c; a = T1 + d; The same rule holds for arguments to a ‘GIMPLE_CALL’. The target of an assignment is usually a variable, but can also be a ‘MEM_REF’ or a compound lvalue as described below. * Menu: * Compound Expressions:: * Compound Lvalues:: * Conditional Expressions:: * Logical Operators::  File: gccint.info, Node: Compound Expressions, Next: Compound Lvalues, Up: Operands 12.6.1 Compound Expressions --------------------------- The left-hand side of a C comma expression is simply moved into a separate statement.  File: gccint.info, Node: Compound Lvalues, Next: Conditional Expressions, Prev: Compound Expressions, Up: Operands 12.6.2 Compound Lvalues ----------------------- Currently compound lvalues involving array and structure field references are not broken down; an expression like ‘a.b[2] = 42’ is not reduced any further (though complex array subscripts are). This restriction is a workaround for limitations in later optimizers; if we were to convert this to T1 = &a.b; T1[2] = 42; alias analysis would not remember that the reference to ‘T1[2]’ came by way of ‘a.b’, so it would think that the assignment could alias another member of ‘a’; this broke ‘struct-alias-1.c’. Future optimizer improvements may make this limitation unnecessary.  File: gccint.info, Node: Conditional Expressions, Next: Logical Operators, Prev: Compound Lvalues, Up: Operands 12.6.3 Conditional Expressions ------------------------------ A C ‘?:’ expression is converted into an ‘if’ statement with each branch assigning to the same temporary. So, a = b ? c : d; becomes if (b == 1) T1 = c; else T1 = d; a = T1; The GIMPLE level if-conversion pass re-introduces ‘?:’ expression, if appropriate. It is used to vectorize loops with conditions using vector conditional operations. Note that in GIMPLE, ‘if’ statements are represented using ‘GIMPLE_COND’, as described below.  File: gccint.info, Node: Logical Operators, Prev: Conditional Expressions, Up: Operands 12.6.4 Logical Operators ------------------------ Except when they appear in the condition operand of a ‘GIMPLE_COND’, logical 'and' and 'or' operators are simplified as follows: ‘a = b && c’ becomes T1 = (bool)b; if (T1 == true) T1 = (bool)c; a = T1; Note that ‘T1’ in this example cannot be an expression temporary, because it has two different assignments. 12.6.5 Manipulating operands ---------------------------- All gimple operands are of type ‘tree’. But only certain types of trees are allowed to be used as operand tuples. Basic validation is controlled by the function ‘get_gimple_rhs_class’, which given a tree code, returns an ‘enum’ with the following values of type ‘enum gimple_rhs_class’ • ‘GIMPLE_INVALID_RHS’ The tree cannot be used as a GIMPLE operand. • ‘GIMPLE_TERNARY_RHS’ The tree is a valid GIMPLE ternary operation. • ‘GIMPLE_BINARY_RHS’ The tree is a valid GIMPLE binary operation. • ‘GIMPLE_UNARY_RHS’ The tree is a valid GIMPLE unary operation. • ‘GIMPLE_SINGLE_RHS’ The tree is a single object, that cannot be split into simpler operands (for instance, ‘SSA_NAME’, ‘VAR_DECL’, ‘COMPONENT_REF’, etc). This operand class also acts as an escape hatch for tree nodes that may be flattened out into the operand vector, but would need more than two slots on the RHS. For instance, a ‘COND_EXPR’ expression of the form ‘(a op b) ? x : y’ could be flattened out on the operand vector using 4 slots, but it would also require additional processing to distinguish ‘c = a op b’ from ‘c = a op b ? x : y’. In time, these special case tree expressions should be flattened into the operand vector. For tree nodes in the categories ‘GIMPLE_TERNARY_RHS’, ‘GIMPLE_BINARY_RHS’ and ‘GIMPLE_UNARY_RHS’, they cannot be stored inside tuples directly. They first need to be flattened and separated into individual components. For instance, given the GENERIC expression a = b + c its tree representation is: MODIFY_EXPR , PLUS_EXPR , VAR_DECL >> In this case, the GIMPLE form for this statement is logically identical to its GENERIC form but in GIMPLE, the ‘PLUS_EXPR’ on the RHS of the assignment is not represented as a tree, instead the two operands are taken out of the ‘PLUS_EXPR’ sub-tree and flattened into the GIMPLE tuple as follows: GIMPLE_ASSIGN , VAR_DECL , VAR_DECL > 12.6.6 Operand vector allocation -------------------------------- The operand vector is stored at the bottom of the three tuple structures that accept operands. This means, that depending on the code of a given statement, its operand vector will be at different offsets from the base of the structure. To access tuple operands use the following accessors -- GIMPLE function: unsigned gimple_num_ops (gimple g) Returns the number of operands in statement G. -- GIMPLE function: tree gimple_op (gimple g, unsigned i) Returns operand ‘I’ from statement ‘G’. -- GIMPLE function: tree * gimple_ops (gimple g) Returns a pointer into the operand vector for statement ‘G’. This is computed using an internal table called ‘gimple_ops_offset_’[]. This table is indexed by the gimple code of ‘G’. When the compiler is built, this table is filled-in using the sizes of the structures used by each statement code defined in gimple.def. Since the operand vector is at the bottom of the structure, for a gimple code ‘C’ the offset is computed as sizeof (struct-of ‘C’) - sizeof (tree). This mechanism adds one memory indirection to every access when using ‘gimple_op’(), if this becomes a bottleneck, a pass can choose to memoize the result from ‘gimple_ops’() and use that to access the operands. 12.6.7 Operand validation ------------------------- When adding a new operand to a gimple statement, the operand will be validated according to what each tuple accepts in its operand vector. These predicates are called by the ‘gimple_NAME_set_...()’. Each tuple will use one of the following predicates (Note, this list is not exhaustive): -- GIMPLE function: bool is_gimple_val (tree t) Returns true if t is a "GIMPLE value", which are all the non-addressable stack variables (variables for which ‘is_gimple_reg’ returns true) and constants (expressions for which ‘is_gimple_min_invariant’ returns true). -- GIMPLE function: bool is_gimple_addressable (tree t) Returns true if t is a symbol or memory reference whose address can be taken. -- GIMPLE function: bool is_gimple_asm_val (tree t) Similar to ‘is_gimple_val’ but it also accepts hard registers. -- GIMPLE function: bool is_gimple_call_addr (tree t) Return true if t is a valid expression to use as the function called by a ‘GIMPLE_CALL’. -- GIMPLE function: bool is_gimple_mem_ref_addr (tree t) Return true if t is a valid expression to use as first operand of a ‘MEM_REF’ expression. -- GIMPLE function: bool is_gimple_constant (tree t) Return true if t is a valid gimple constant. -- GIMPLE function: bool is_gimple_min_invariant (tree t) Return true if t is a valid minimal invariant. This is different from constants, in that the specific value of t may not be known at compile time, but it is known that it doesn't change (e.g., the address of a function local variable). -- GIMPLE function: bool is_gimple_ip_invariant (tree t) Return true if t is an interprocedural invariant. This means that t is a valid invariant in all functions (e.g. it can be an address of a global variable but not of a local one). -- GIMPLE function: bool is_gimple_ip_invariant_address (tree t) Return true if t is an ‘ADDR_EXPR’ that does not change once the program is running (and which is valid in all functions). 12.6.8 Statement validation --------------------------- -- GIMPLE function: bool is_gimple_assign (gimple g) Return true if the code of g is ‘GIMPLE_ASSIGN’. -- GIMPLE function: bool is_gimple_call (gimple g) Return true if the code of g is ‘GIMPLE_CALL’. -- GIMPLE function: bool is_gimple_debug (gimple g) Return true if the code of g is ‘GIMPLE_DEBUG’. -- GIMPLE function: bool gimple_assign_cast_p (const_gimple g) Return true if g is a ‘GIMPLE_ASSIGN’ that performs a type cast operation. -- GIMPLE function: bool gimple_debug_bind_p (gimple g) Return true if g is a ‘GIMPLE_DEBUG’ that binds the value of an expression to a variable. -- GIMPLE function: bool is_gimple_omp (gimple g) Return true if g is any of the OpenMP codes. -- GIMPLE function: bool gimple_debug_begin_stmt_p (gimple g) Return true if g is a ‘GIMPLE_DEBUG’ that marks the beginning of a source statement. -- GIMPLE function: bool gimple_debug_inline_entry_p (gimple g) Return true if g is a ‘GIMPLE_DEBUG’ that marks the entry point of an inlined function. -- GIMPLE function: bool gimple_debug_nonbind_marker_p (gimple g) Return true if g is a ‘GIMPLE_DEBUG’ that marks a program location, without any variable binding.  File: gccint.info, Node: Manipulating GIMPLE statements, Next: Tuple specific accessors, Prev: Operands, Up: GIMPLE 12.7 Manipulating GIMPLE statements =================================== This section documents all the functions available to handle each of the GIMPLE instructions. 12.7.1 Common accessors ----------------------- The following are common accessors for gimple statements. -- GIMPLE function: enum gimple_code gimple_code (gimple g) Return the code for statement ‘G’. -- GIMPLE function: basic_block gimple_bb (gimple g) Return the basic block to which statement ‘G’ belongs to. -- GIMPLE function: tree gimple_block (gimple g) Return the lexical scope block holding statement ‘G’. -- GIMPLE function: enum tree_code gimple_expr_code (gimple stmt) Return the tree code for the expression computed by ‘STMT’. This is only meaningful for ‘GIMPLE_CALL’, ‘GIMPLE_ASSIGN’ and ‘GIMPLE_COND’. If ‘STMT’ is ‘GIMPLE_CALL’, it will return ‘CALL_EXPR’. For ‘GIMPLE_COND’, it returns the code of the comparison predicate. For ‘GIMPLE_ASSIGN’ it returns the code of the operation performed by the ‘RHS’ of the assignment. -- GIMPLE function: void gimple_set_block (gimple g, tree block) Set the lexical scope block of ‘G’ to ‘BLOCK’. -- GIMPLE function: location_t gimple_locus (gimple g) Return locus information for statement ‘G’. -- GIMPLE function: void gimple_set_locus (gimple g, location_t locus) Set locus information for statement ‘G’. -- GIMPLE function: bool gimple_locus_empty_p (gimple g) Return true if ‘G’ does not have locus information. -- GIMPLE function: bool gimple_no_warning_p (gimple stmt) Return true if no warnings should be emitted for statement ‘STMT’. -- GIMPLE function: void gimple_set_visited (gimple stmt, bool visited_p) Set the visited status on statement ‘STMT’ to ‘VISITED_P’. -- GIMPLE function: bool gimple_visited_p (gimple stmt) Return the visited status on statement ‘STMT’. -- GIMPLE function: void gimple_set_plf (gimple stmt, enum plf_mask plf, bool val_p) Set pass local flag ‘PLF’ on statement ‘STMT’ to ‘VAL_P’. -- GIMPLE function: unsigned int gimple_plf (gimple stmt, enum plf_mask plf) Return the value of pass local flag ‘PLF’ on statement ‘STMT’. -- GIMPLE function: bool gimple_has_ops (gimple g) Return true if statement ‘G’ has register or memory operands. -- GIMPLE function: bool gimple_has_mem_ops (gimple g) Return true if statement ‘G’ has memory operands. -- GIMPLE function: unsigned gimple_num_ops (gimple g) Return the number of operands for statement ‘G’. -- GIMPLE function: tree * gimple_ops (gimple g) Return the array of operands for statement ‘G’. -- GIMPLE function: tree gimple_op (gimple g, unsigned i) Return operand ‘I’ for statement ‘G’. -- GIMPLE function: tree * gimple_op_ptr (gimple g, unsigned i) Return a pointer to operand ‘I’ for statement ‘G’. -- GIMPLE function: void gimple_set_op (gimple g, unsigned i, tree op) Set operand ‘I’ of statement ‘G’ to ‘OP’. -- GIMPLE function: bitmap gimple_addresses_taken (gimple stmt) Return the set of symbols that have had their address taken by ‘STMT’. -- GIMPLE function: struct def_optype_d * gimple_def_ops (gimple g) Return the set of ‘DEF’ operands for statement ‘G’. -- GIMPLE function: void gimple_set_def_ops (gimple g, struct def_optype_d *def) Set ‘DEF’ to be the set of ‘DEF’ operands for statement ‘G’. -- GIMPLE function: struct use_optype_d * gimple_use_ops (gimple g) Return the set of ‘USE’ operands for statement ‘G’. -- GIMPLE function: void gimple_set_use_ops (gimple g, struct use_optype_d *use) Set ‘USE’ to be the set of ‘USE’ operands for statement ‘G’. -- GIMPLE function: struct voptype_d * gimple_vuse_ops (gimple g) Return the set of ‘VUSE’ operands for statement ‘G’. -- GIMPLE function: void gimple_set_vuse_ops (gimple g, struct voptype_d *ops) Set ‘OPS’ to be the set of ‘VUSE’ operands for statement ‘G’. -- GIMPLE function: struct voptype_d * gimple_vdef_ops (gimple g) Return the set of ‘VDEF’ operands for statement ‘G’. -- GIMPLE function: void gimple_set_vdef_ops (gimple g, struct voptype_d *ops) Set ‘OPS’ to be the set of ‘VDEF’ operands for statement ‘G’. -- GIMPLE function: bitmap gimple_loaded_syms (gimple g) Return the set of symbols loaded by statement ‘G’. Each element of the set is the ‘DECL_UID’ of the corresponding symbol. -- GIMPLE function: bitmap gimple_stored_syms (gimple g) Return the set of symbols stored by statement ‘G’. Each element of the set is the ‘DECL_UID’ of the corresponding symbol. -- GIMPLE function: bool gimple_modified_p (gimple g) Return true if statement ‘G’ has operands and the modified field has been set. -- GIMPLE function: bool gimple_has_volatile_ops (gimple stmt) Return true if statement ‘STMT’ contains volatile operands. -- GIMPLE function: void gimple_set_has_volatile_ops (gimple stmt, bool volatilep) Return true if statement ‘STMT’ contains volatile operands. -- GIMPLE function: void update_stmt (gimple s) Mark statement ‘S’ as modified, and update it. -- GIMPLE function: void update_stmt_if_modified (gimple s) Update statement ‘S’ if it has been marked modified. -- GIMPLE function: gimple gimple_copy (gimple stmt) Return a deep copy of statement ‘STMT’.  File: gccint.info, Node: Tuple specific accessors, Next: GIMPLE sequences, Prev: Manipulating GIMPLE statements, Up: GIMPLE 12.8 Tuple specific accessors ============================= * Menu: * GIMPLE_ASM:: * GIMPLE_ASSIGN:: * GIMPLE_BIND:: * GIMPLE_CALL:: * GIMPLE_CATCH:: * GIMPLE_COND:: * GIMPLE_DEBUG:: * GIMPLE_EH_FILTER:: * GIMPLE_LABEL:: * GIMPLE_GOTO:: * GIMPLE_NOP:: * GIMPLE_OMP_ATOMIC_LOAD:: * GIMPLE_OMP_ATOMIC_STORE:: * GIMPLE_OMP_CONTINUE:: * GIMPLE_OMP_CRITICAL:: * GIMPLE_OMP_FOR:: * GIMPLE_OMP_MASTER:: * GIMPLE_OMP_ORDERED:: * GIMPLE_OMP_PARALLEL:: * GIMPLE_OMP_RETURN:: * GIMPLE_OMP_SECTION:: * GIMPLE_OMP_SECTIONS:: * GIMPLE_OMP_SINGLE:: * GIMPLE_OMP_STRUCTURED_BLOCK:: * GIMPLE_PHI:: * GIMPLE_RESX:: * GIMPLE_RETURN:: * GIMPLE_SWITCH:: * GIMPLE_TRY:: * GIMPLE_WITH_CLEANUP_EXPR::  File: gccint.info, Node: GIMPLE_ASM, Next: GIMPLE_ASSIGN, Up: Tuple specific accessors 12.8.1 ‘GIMPLE_ASM’ ------------------- -- GIMPLE function: gasm *gimple_build_asm_vec ( const char *string, vec *inputs, vec *outputs, vec *clobbers, vec *labels) Build a ‘GIMPLE_ASM’ statement. This statement is used for building in-line assembly constructs. ‘STRING’ is the assembly code. ‘INPUTS’, ‘OUTPUTS’, ‘CLOBBERS’ and ‘LABELS’ are the inputs, outputs, clobbered registers and labels. -- GIMPLE function: unsigned gimple_asm_ninputs (const gasm *g) Return the number of input operands for ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: unsigned gimple_asm_noutputs (const gasm *g) Return the number of output operands for ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: unsigned gimple_asm_nclobbers (const gasm *g) Return the number of clobber operands for ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: tree gimple_asm_input_op (const gasm *g, unsigned index) Return input operand ‘INDEX’ of ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: void gimple_asm_set_input_op (gasm *g, unsigned index, tree in_op) Set ‘IN_OP’ to be input operand ‘INDEX’ in ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: tree gimple_asm_output_op (const gasm *g, unsigned index) Return output operand ‘INDEX’ of ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: void gimple_asm_set_output_op (gasm *g, unsigned index, tree out_op) Set ‘OUT_OP’ to be output operand ‘INDEX’ in ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: tree gimple_asm_clobber_op (const gasm *g, unsigned index) Return clobber operand ‘INDEX’ of ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: void gimple_asm_set_clobber_op (gasm *g, unsigned index, tree clobber_op) Set ‘CLOBBER_OP’ to be clobber operand ‘INDEX’ in ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: const char * gimple_asm_string (const gasm *g) Return the string representing the assembly instruction in ‘GIMPLE_ASM’ ‘G’. -- GIMPLE function: bool gimple_asm_volatile_p (const gasm *g) Return true if ‘G’ is an asm statement marked volatile. -- GIMPLE function: void gimple_asm_set_volatile (gasm *g, bool volatile_p) Mark asm statement ‘G’ as volatile or non-volatile based on ‘VOLATILE_P’.  File: gccint.info, Node: GIMPLE_ASSIGN, Next: GIMPLE_BIND, Prev: GIMPLE_ASM, Up: Tuple specific accessors 12.8.2 ‘GIMPLE_ASSIGN’ ---------------------- -- GIMPLE function: gassign *gimple_build_assign (tree lhs, tree rhs) Build a ‘GIMPLE_ASSIGN’ statement. The left-hand side is an lvalue passed in lhs. The right-hand side can be either a unary or binary tree expression. The expression tree rhs will be flattened and its operands assigned to the corresponding operand slots in the new statement. This function is useful when you already have a tree expression that you want to convert into a tuple. However, try to avoid building expression trees for the sole purpose of calling this function. If you already have the operands in separate trees, it is better to use ‘gimple_build_assign’ with ‘enum tree_code’ argument and separate arguments for each operand. -- GIMPLE function: gassign *gimple_build_assign (tree lhs, enum tree_code subcode, tree op1, tree op2, tree op3) This function is similar to two operand ‘gimple_build_assign’, but is used to build a ‘GIMPLE_ASSIGN’ statement when the operands of the right-hand side of the assignment are already split into different operands. The left-hand side is an lvalue passed in lhs. Subcode is the ‘tree_code’ for the right-hand side of the assignment. Op1, op2 and op3 are the operands. -- GIMPLE function: gassign *gimple_build_assign (tree lhs, enum tree_code subcode, tree op1, tree op2) Like the above 5 operand ‘gimple_build_assign’, but with the last argument ‘NULL’ - this overload should not be used for ‘GIMPLE_TERNARY_RHS’ assignments. -- GIMPLE function: gassign *gimple_build_assign (tree lhs, enum tree_code subcode, tree op1) Like the above 4 operand ‘gimple_build_assign’, but with the last argument ‘NULL’ - this overload should be used only for ‘GIMPLE_UNARY_RHS’ and ‘GIMPLE_SINGLE_RHS’ assignments. -- GIMPLE function: gimple gimplify_assign (tree dst, tree src, gimple_seq *seq_p) Build a new ‘GIMPLE_ASSIGN’ tuple and append it to the end of ‘*SEQ_P’. ‘DST’/‘SRC’ are the destination and source respectively. You can pass ungimplified trees in ‘DST’ or ‘SRC’, in which case they will be converted to a gimple operand if necessary. This function returns the newly created ‘GIMPLE_ASSIGN’ tuple. -- GIMPLE function: enum tree_code gimple_assign_rhs_code (gimple g) Return the code of the expression computed on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: enum gimple_rhs_class gimple_assign_rhs_class (gimple g) Return the gimple rhs class of the code for the expression computed on the rhs of assignment statement ‘G’. This will never return ‘GIMPLE_INVALID_RHS’. -- GIMPLE function: tree gimple_assign_lhs (gimple g) Return the ‘LHS’ of assignment statement ‘G’. -- GIMPLE function: tree * gimple_assign_lhs_ptr (gimple g) Return a pointer to the ‘LHS’ of assignment statement ‘G’. -- GIMPLE function: tree gimple_assign_rhs1 (gimple g) Return the first operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: tree * gimple_assign_rhs1_ptr (gimple g) Return the address of the first operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: tree gimple_assign_rhs2 (gimple g) Return the second operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: tree * gimple_assign_rhs2_ptr (gimple g) Return the address of the second operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: tree gimple_assign_rhs3 (gimple g) Return the third operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: tree * gimple_assign_rhs3_ptr (gimple g) Return the address of the third operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: void gimple_assign_set_lhs (gimple g, tree lhs) Set ‘LHS’ to be the ‘LHS’ operand of assignment statement ‘G’. -- GIMPLE function: void gimple_assign_set_rhs1 (gimple g, tree rhs) Set ‘RHS’ to be the first operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: void gimple_assign_set_rhs2 (gimple g, tree rhs) Set ‘RHS’ to be the second operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: void gimple_assign_set_rhs3 (gimple g, tree rhs) Set ‘RHS’ to be the third operand on the ‘RHS’ of assignment statement ‘G’. -- GIMPLE function: bool gimple_assign_cast_p (const_gimple s) Return true if ‘S’ is a type-cast assignment.  File: gccint.info, Node: GIMPLE_BIND, Next: GIMPLE_CALL, Prev: GIMPLE_ASSIGN, Up: Tuple specific accessors 12.8.3 ‘GIMPLE_BIND’ -------------------- -- GIMPLE function: gbind *gimple_build_bind (tree vars, gimple_seq body) Build a ‘GIMPLE_BIND’ statement with a list of variables in ‘VARS’ and a body of statements in sequence ‘BODY’. -- GIMPLE function: tree gimple_bind_vars (const gbind *g) Return the variables declared in the ‘GIMPLE_BIND’ statement ‘G’. -- GIMPLE function: void gimple_bind_set_vars (gbind *g, tree vars) Set ‘VARS’ to be the set of variables declared in the ‘GIMPLE_BIND’ statement ‘G’. -- GIMPLE function: void gimple_bind_append_vars (gbind *g, tree vars) Append ‘VARS’ to the set of variables declared in the ‘GIMPLE_BIND’ statement ‘G’. -- GIMPLE function: gimple_seq gimple_bind_body (gbind *g) Return the GIMPLE sequence contained in the ‘GIMPLE_BIND’ statement ‘G’. -- GIMPLE function: void gimple_bind_set_body (gbind *g, gimple_seq seq) Set ‘SEQ’ to be sequence contained in the ‘GIMPLE_BIND’ statement ‘G’. -- GIMPLE function: void gimple_bind_add_stmt (gbind *gs, gimple stmt) Append a statement to the end of a ‘GIMPLE_BIND’'s body. -- GIMPLE function: void gimple_bind_add_seq (gbind *gs, gimple_seq seq) Append a sequence of statements to the end of a ‘GIMPLE_BIND’'s body. -- GIMPLE function: tree gimple_bind_block (const gbind *g) Return the ‘TREE_BLOCK’ node associated with ‘GIMPLE_BIND’ statement ‘G’. This is analogous to the ‘BIND_EXPR_BLOCK’ field in trees. -- GIMPLE function: void gimple_bind_set_block (gbind *g, tree block) Set ‘BLOCK’ to be the ‘TREE_BLOCK’ node associated with ‘GIMPLE_BIND’ statement ‘G’.  File: gccint.info, Node: GIMPLE_CALL, Next: GIMPLE_CATCH, Prev: GIMPLE_BIND, Up: Tuple specific accessors 12.8.4 ‘GIMPLE_CALL’ -------------------- -- GIMPLE function: gcall *gimple_build_call (tree fn, unsigned nargs, ...) Build a ‘GIMPLE_CALL’ statement to function ‘FN’. The argument ‘FN’ must be either a ‘FUNCTION_DECL’ or a gimple call address as determined by ‘is_gimple_call_addr’. ‘NARGS’ are the number of arguments. The rest of the arguments follow the argument ‘NARGS’, and must be trees that are valid as rvalues in gimple (i.e., each operand is validated with ‘is_gimple_operand’). -- GIMPLE function: gcall *gimple_build_call_from_tree (tree call_expr, tree fnptrtype) Build a ‘GIMPLE_CALL’ from a ‘CALL_EXPR’ node. The arguments and the function are taken from the expression directly. The type of the ‘GIMPLE_CALL’ is set from the second parameter passed by a caller. This routine assumes that ‘call_expr’ is already in GIMPLE form. That is, its operands are GIMPLE values and the function call needs no further simplification. All the call flags in ‘call_expr’ are copied over to the new ‘GIMPLE_CALL’. -- GIMPLE function: gcall *gimple_build_call_vec (tree fn, vec args) Identical to ‘gimple_build_call’ but the arguments are stored in a ‘vec’. -- GIMPLE function: tree gimple_call_lhs (gimple g) Return the ‘LHS’ of call statement ‘G’. -- GIMPLE function: tree * gimple_call_lhs_ptr (gimple g) Return a pointer to the ‘LHS’ of call statement ‘G’. -- GIMPLE function: void gimple_call_set_lhs (gimple g, tree lhs) Set ‘LHS’ to be the ‘LHS’ operand of call statement ‘G’. -- GIMPLE function: tree gimple_call_fn (gimple g) Return the tree node representing the function called by call statement ‘G’. -- GIMPLE function: void gimple_call_set_fn (gcall *g, tree fn) Set ‘FN’ to be the function called by call statement ‘G’. This has to be a gimple value specifying the address of the called function. -- GIMPLE function: tree gimple_call_fndecl (gimple g) If a given ‘GIMPLE_CALL’'s callee is a ‘FUNCTION_DECL’, return it. Otherwise return ‘NULL’. This function is analogous to ‘get_callee_fndecl’ in ‘GENERIC’. -- GIMPLE function: tree gimple_call_set_fndecl (gimple g, tree fndecl) Set the called function to ‘FNDECL’. -- GIMPLE function: tree gimple_call_return_type (const gcall *g) Return the type returned by call statement ‘G’. -- GIMPLE function: tree gimple_call_chain (gimple g) Return the static chain for call statement ‘G’. -- GIMPLE function: void gimple_call_set_chain (gcall *g, tree chain) Set ‘CHAIN’ to be the static chain for call statement ‘G’. -- GIMPLE function: unsigned gimple_call_num_args (gimple g) Return the number of arguments used by call statement ‘G’. -- GIMPLE function: tree gimple_call_arg (gimple g, unsigned index) Return the argument at position ‘INDEX’ for call statement ‘G’. The first argument is 0. -- GIMPLE function: tree * gimple_call_arg_ptr (gimple g, unsigned index) Return a pointer to the argument at position ‘INDEX’ for call statement ‘G’. -- GIMPLE function: void gimple_call_set_arg (gimple g, unsigned index, tree arg) Set ‘ARG’ to be the argument at position ‘INDEX’ for call statement ‘G’. -- GIMPLE function: void gimple_call_set_tail (gcall *s) Mark call statement ‘S’ as being a tail call (i.e., a call just before the exit of a function). These calls are candidate for tail call optimization. -- GIMPLE function: bool gimple_call_tail_p (gcall *s) Return true if ‘GIMPLE_CALL’ ‘S’ is marked as a tail call. -- GIMPLE function: bool gimple_call_noreturn_p (gimple s) Return true if ‘S’ is a noreturn call. -- GIMPLE function: gimple gimple_call_copy_skip_args (gcall *stmt, bitmap args_to_skip) Build a ‘GIMPLE_CALL’ identical to ‘STMT’ but skipping the arguments in the positions marked by the set ‘ARGS_TO_SKIP’.  File: gccint.info, Node: GIMPLE_CATCH, Next: GIMPLE_COND, Prev: GIMPLE_CALL, Up: Tuple specific accessors 12.8.5 ‘GIMPLE_CATCH’ --------------------- -- GIMPLE function: gcatch *gimple_build_catch (tree types, gimple_seq handler) Build a ‘GIMPLE_CATCH’ statement. ‘TYPES’ are the tree types this catch handles. ‘HANDLER’ is a sequence of statements with the code for the handler. -- GIMPLE function: tree gimple_catch_types (const gcatch *g) Return the types handled by ‘GIMPLE_CATCH’ statement ‘G’. -- GIMPLE function: tree * gimple_catch_types_ptr (gcatch *g) Return a pointer to the types handled by ‘GIMPLE_CATCH’ statement ‘G’. -- GIMPLE function: gimple_seq gimple_catch_handler (gcatch *g) Return the GIMPLE sequence representing the body of the handler of ‘GIMPLE_CATCH’ statement ‘G’. -- GIMPLE function: void gimple_catch_set_types (gcatch *g, tree t) Set ‘T’ to be the set of types handled by ‘GIMPLE_CATCH’ ‘G’. -- GIMPLE function: void gimple_catch_set_handler (gcatch *g, gimple_seq handler) Set ‘HANDLER’ to be the body of ‘GIMPLE_CATCH’ ‘G’.  File: gccint.info, Node: GIMPLE_COND, Next: GIMPLE_DEBUG, Prev: GIMPLE_CATCH, Up: Tuple specific accessors 12.8.6 ‘GIMPLE_COND’ -------------------- -- GIMPLE function: gcond *gimple_build_cond ( enum tree_code pred_code, tree lhs, tree rhs, tree t_label, tree f_label) Build a ‘GIMPLE_COND’ statement. ‘A’ ‘GIMPLE_COND’ statement compares ‘LHS’ and ‘RHS’ and if the condition in ‘PRED_CODE’ is true, jump to the label in ‘t_label’, otherwise jump to the label in ‘f_label’. ‘PRED_CODE’ are relational operator tree codes like ‘EQ_EXPR’, ‘LT_EXPR’, ‘LE_EXPR’, ‘NE_EXPR’, etc. -- GIMPLE function: gcond *gimple_build_cond_from_tree (tree cond, tree t_label, tree f_label) Build a ‘GIMPLE_COND’ statement from the conditional expression tree ‘COND’. ‘T_LABEL’ and ‘F_LABEL’ are as in ‘gimple_build_cond’. -- GIMPLE function: enum tree_code gimple_cond_code (gimple g) Return the code of the predicate computed by conditional statement ‘G’. -- GIMPLE function: void gimple_cond_set_code (gcond *g, enum tree_code code) Set ‘CODE’ to be the predicate code for the conditional statement ‘G’. -- GIMPLE function: tree gimple_cond_lhs (gimple g) Return the ‘LHS’ of the predicate computed by conditional statement ‘G’. -- GIMPLE function: void gimple_cond_set_lhs (gcond *g, tree lhs) Set ‘LHS’ to be the ‘LHS’ operand of the predicate computed by conditional statement ‘G’. -- GIMPLE function: tree gimple_cond_rhs (gimple g) Return the ‘RHS’ operand of the predicate computed by conditional ‘G’. -- GIMPLE function: void gimple_cond_set_rhs (gcond *g, tree rhs) Set ‘RHS’ to be the ‘RHS’ operand of the predicate computed by conditional statement ‘G’. -- GIMPLE function: tree gimple_cond_true_label (const gcond *g) Return the label used by conditional statement ‘G’ when its predicate evaluates to true. -- GIMPLE function: void gimple_cond_set_true_label (gcond *g, tree label) Set ‘LABEL’ to be the label used by conditional statement ‘G’ when its predicate evaluates to true. -- GIMPLE function: void gimple_cond_set_false_label (gcond *g, tree label) Set ‘LABEL’ to be the label used by conditional statement ‘G’ when its predicate evaluates to false. -- GIMPLE function: tree gimple_cond_false_label (const gcond *g) Return the label used by conditional statement ‘G’ when its predicate evaluates to false. -- GIMPLE function: void gimple_cond_make_false (gcond *g) Set the conditional ‘COND_STMT’ to be of the form 'if (1 == 0)'. -- GIMPLE function: void gimple_cond_make_true (gcond *g) Set the conditional ‘COND_STMT’ to be of the form 'if (1 == 1)'.  File: gccint.info, Node: GIMPLE_DEBUG, Next: GIMPLE_EH_FILTER, Prev: GIMPLE_COND, Up: Tuple specific accessors 12.8.7 ‘GIMPLE_DEBUG’ --------------------- -- GIMPLE function: gdebug *gimple_build_debug_bind (tree var, tree value, gimple stmt) Build a ‘GIMPLE_DEBUG’ statement with ‘GIMPLE_DEBUG_BIND’ ‘subcode’. The effect of this statement is to tell debug information generation machinery that the value of user variable ‘var’ is given by ‘value’ at that point, and to remain with that value until ‘var’ runs out of scope, a dynamically-subsequent debug bind statement overrides the binding, or conflicting values reach a control flow merge point. Even if components of the ‘value’ expression change afterwards, the variable is supposed to retain the same value, though not necessarily the same location. It is expected that ‘var’ be most often a tree for automatic user variables (‘VAR_DECL’ or ‘PARM_DECL’) that satisfy the requirements for gimple registers, but it may also be a tree for a scalarized component of a user variable (‘ARRAY_REF’, ‘COMPONENT_REF’), or a debug temporary (‘DEBUG_EXPR_DECL’). As for ‘value’, it can be an arbitrary tree expression, but it is recommended that it be in a suitable form for a gimple assignment ‘RHS’. It is not expected that user variables that could appear as ‘var’ ever appear in ‘value’, because in the latter we'd have their ‘SSA_NAME’s instead, but even if they were not in SSA form, user variables appearing in ‘value’ are to be regarded as part of the executable code space, whereas those in ‘var’ are to be regarded as part of the source code space. There is no way to refer to the value bound to a user variable within a ‘value’ expression. If ‘value’ is ‘GIMPLE_DEBUG_BIND_NOVALUE’, debug information generation machinery is informed that the variable ‘var’ is unbound, i.e., that its value is indeterminate, which sometimes means it is really unavailable, and other times that the compiler could not keep track of it. Block and location information for the newly-created stmt are taken from ‘stmt’, if given. -- GIMPLE function: tree gimple_debug_bind_get_var (gimple stmt) Return the user variable VAR that is bound at ‘stmt’. -- GIMPLE function: tree gimple_debug_bind_get_value (gimple stmt) Return the value expression that is bound to a user variable at ‘stmt’. -- GIMPLE function: tree * gimple_debug_bind_get_value_ptr (gimple stmt) Return a pointer to the value expression that is bound to a user variable at ‘stmt’. -- GIMPLE function: void gimple_debug_bind_set_var (gimple stmt, tree var) Modify the user variable bound at ‘stmt’ to VAR. -- GIMPLE function: void gimple_debug_bind_set_value (gimple stmt, tree var) Modify the value bound to the user variable bound at ‘stmt’ to VALUE. -- GIMPLE function: void gimple_debug_bind_reset_value (gimple stmt) Modify the value bound to the user variable bound at ‘stmt’ so that the variable becomes unbound. -- GIMPLE function: bool gimple_debug_bind_has_value_p (gimple stmt) Return ‘TRUE’ if ‘stmt’ binds a user variable to a value, and ‘FALSE’ if it unbinds the variable. -- GIMPLE function: gimple gimple_build_debug_begin_stmt (tree block, location_t location) Build a ‘GIMPLE_DEBUG’ statement with ‘GIMPLE_DEBUG_BEGIN_STMT’ ‘subcode’. The effect of this statement is to tell debug information generation machinery that the user statement at the given ‘location’ and ‘block’ starts at the point at which the statement is inserted. The intent is that side effects (e.g. variable bindings) of all prior user statements are observable, and that none of the side effects of subsequent user statements are. -- GIMPLE function: gimple gimple_build_debug_inline_entry (tree block, location_t location) Build a ‘GIMPLE_DEBUG’ statement with ‘GIMPLE_DEBUG_INLINE_ENTRY’ ‘subcode’. The effect of this statement is to tell debug information generation machinery that a function call at ‘location’ underwent inline substitution, that ‘block’ is the enclosing lexical block created for the substitution, and that at the point of the program in which the stmt is inserted, all parameters for the inlined function are bound to the respective arguments, and none of the side effects of its stmts are observable.  File: gccint.info, Node: GIMPLE_EH_FILTER, Next: GIMPLE_LABEL, Prev: GIMPLE_DEBUG, Up: Tuple specific accessors 12.8.8 ‘GIMPLE_EH_FILTER’ ------------------------- -- GIMPLE function: geh_filter *gimple_build_eh_filter (tree types, gimple_seq failure) Build a ‘GIMPLE_EH_FILTER’ statement. ‘TYPES’ are the filter's types. ‘FAILURE’ is a sequence with the filter's failure action. -- GIMPLE function: tree gimple_eh_filter_types (gimple g) Return the types handled by ‘GIMPLE_EH_FILTER’ statement ‘G’. -- GIMPLE function: tree * gimple_eh_filter_types_ptr (gimple g) Return a pointer to the types handled by ‘GIMPLE_EH_FILTER’ statement ‘G’. -- GIMPLE function: gimple_seq gimple_eh_filter_failure (gimple g) Return the sequence of statement to execute when ‘GIMPLE_EH_FILTER’ statement fails. -- GIMPLE function: void gimple_eh_filter_set_types (geh_filter *g, tree types) Set ‘TYPES’ to be the set of types handled by ‘GIMPLE_EH_FILTER’ ‘G’. -- GIMPLE function: void gimple_eh_filter_set_failure (geh_filter *g, gimple_seq failure) Set ‘FAILURE’ to be the sequence of statements to execute on failure for ‘GIMPLE_EH_FILTER’ ‘G’. -- GIMPLE function: tree gimple_eh_must_not_throw_fndecl ( geh_mnt *eh_mnt_stmt) Get the function decl to be called by the MUST_NOT_THROW region. -- GIMPLE function: void gimple_eh_must_not_throw_set_fndecl ( geh_mnt *eh_mnt_stmt, tree decl) Set the function decl to be called by GS to DECL.  File: gccint.info, Node: GIMPLE_LABEL, Next: GIMPLE_GOTO, Prev: GIMPLE_EH_FILTER, Up: Tuple specific accessors 12.8.9 ‘GIMPLE_LABEL’ --------------------- -- GIMPLE function: glabel *gimple_build_label (tree label) Build a ‘GIMPLE_LABEL’ statement with corresponding to the tree label, ‘LABEL’. -- GIMPLE function: tree gimple_label_label (const glabel *g) Return the ‘LABEL_DECL’ node used by ‘GIMPLE_LABEL’ statement ‘G’. -- GIMPLE function: void gimple_label_set_label (glabel *g, tree label) Set ‘LABEL’ to be the ‘LABEL_DECL’ node used by ‘GIMPLE_LABEL’ statement ‘G’.  File: gccint.info, Node: GIMPLE_GOTO, Next: GIMPLE_NOP, Prev: GIMPLE_LABEL, Up: Tuple specific accessors 12.8.10 ‘GIMPLE_GOTO’ --------------------- -- GIMPLE function: ggoto *gimple_build_goto (tree dest) Build a ‘GIMPLE_GOTO’ statement to label ‘DEST’. -- GIMPLE function: tree gimple_goto_dest (gimple g) Return the destination of the unconditional jump ‘G’. -- GIMPLE function: void gimple_goto_set_dest (ggoto *g, tree dest) Set ‘DEST’ to be the destination of the unconditional jump ‘G’.  File: gccint.info, Node: GIMPLE_NOP, Next: GIMPLE_OMP_ATOMIC_LOAD, Prev: GIMPLE_GOTO, Up: Tuple specific accessors 12.8.11 ‘GIMPLE_NOP’ -------------------- -- GIMPLE function: gimple gimple_build_nop (void) Build a ‘GIMPLE_NOP’ statement. -- GIMPLE function: bool gimple_nop_p (gimple g) Returns ‘TRUE’ if statement ‘G’ is a ‘GIMPLE_NOP’.  File: gccint.info, Node: GIMPLE_OMP_ATOMIC_LOAD, Next: GIMPLE_OMP_ATOMIC_STORE, Prev: GIMPLE_NOP, Up: Tuple specific accessors 12.8.12 ‘GIMPLE_OMP_ATOMIC_LOAD’ -------------------------------- -- GIMPLE function: gomp_atomic_load *gimple_build_omp_atomic_load ( tree lhs, tree rhs) Build a ‘GIMPLE_OMP_ATOMIC_LOAD’ statement. ‘LHS’ is the left-hand side of the assignment. ‘RHS’ is the right-hand side of the assignment. -- GIMPLE function: void gimple_omp_atomic_load_set_lhs ( gomp_atomic_load *g, tree lhs) Set the ‘LHS’ of an atomic load. -- GIMPLE function: tree gimple_omp_atomic_load_lhs ( const gomp_atomic_load *g) Get the ‘LHS’ of an atomic load. -- GIMPLE function: void gimple_omp_atomic_load_set_rhs ( gomp_atomic_load *g, tree rhs) Set the ‘RHS’ of an atomic set. -- GIMPLE function: tree gimple_omp_atomic_load_rhs ( const gomp_atomic_load *g) Get the ‘RHS’ of an atomic set.  File: gccint.info, Node: GIMPLE_OMP_ATOMIC_STORE, Next: GIMPLE_OMP_CONTINUE, Prev: GIMPLE_OMP_ATOMIC_LOAD, Up: Tuple specific accessors 12.8.13 ‘GIMPLE_OMP_ATOMIC_STORE’ --------------------------------- -- GIMPLE function: gomp_atomic_store *gimple_build_omp_atomic_store ( tree val) Build a ‘GIMPLE_OMP_ATOMIC_STORE’ statement. ‘VAL’ is the value to be stored. -- GIMPLE function: void gimple_omp_atomic_store_set_val ( gomp_atomic_store *g, tree val) Set the value being stored in an atomic store. -- GIMPLE function: tree gimple_omp_atomic_store_val ( const gomp_atomic_store *g) Return the value being stored in an atomic store.  File: gccint.info, Node: GIMPLE_OMP_CONTINUE, Next: GIMPLE_OMP_CRITICAL, Prev: GIMPLE_OMP_ATOMIC_STORE, Up: Tuple specific accessors 12.8.14 ‘GIMPLE_OMP_CONTINUE’ ----------------------------- -- GIMPLE function: gomp_continue *gimple_build_omp_continue ( tree control_def, tree control_use) Build a ‘GIMPLE_OMP_CONTINUE’ statement. ‘CONTROL_DEF’ is the definition of the control variable. ‘CONTROL_USE’ is the use of the control variable. -- GIMPLE function: tree gimple_omp_continue_control_def ( const gomp_continue *s) Return the definition of the control variable on a ‘GIMPLE_OMP_CONTINUE’ in ‘S’. -- GIMPLE function: tree gimple_omp_continue_control_def_ptr ( gomp_continue *s) Same as above, but return the pointer. -- GIMPLE function: tree gimple_omp_continue_set_control_def ( gomp_continue *s) Set the control variable definition for a ‘GIMPLE_OMP_CONTINUE’ statement in ‘S’. -- GIMPLE function: tree gimple_omp_continue_control_use ( const gomp_continue *s) Return the use of the control variable on a ‘GIMPLE_OMP_CONTINUE’ in ‘S’. -- GIMPLE function: tree gimple_omp_continue_control_use_ptr ( gomp_continue *s) Same as above, but return the pointer. -- GIMPLE function: tree gimple_omp_continue_set_control_use ( gomp_continue *s) Set the control variable use for a ‘GIMPLE_OMP_CONTINUE’ statement in ‘S’.  File: gccint.info, Node: GIMPLE_OMP_CRITICAL, Next: GIMPLE_OMP_FOR, Prev: GIMPLE_OMP_CONTINUE, Up: Tuple specific accessors 12.8.15 ‘GIMPLE_OMP_CRITICAL’ ----------------------------- -- GIMPLE function: gomp_critical *gimple_build_omp_critical ( gimple_seq body, tree name) Build a ‘GIMPLE_OMP_CRITICAL’ statement. ‘BODY’ is the sequence of statements for which only one thread can execute. ‘NAME’ is an optional identifier for this critical block. -- GIMPLE function: tree gimple_omp_critical_name ( const gomp_critical *g) Return the name associated with ‘OMP_CRITICAL’ statement ‘G’. -- GIMPLE function: tree * gimple_omp_critical_name_ptr ( gomp_critical *g) Return a pointer to the name associated with ‘OMP’ critical statement ‘G’. -- GIMPLE function: void gimple_omp_critical_set_name ( gomp_critical *g, tree name) Set ‘NAME’ to be the name associated with ‘OMP’ critical statement ‘G’.  File: gccint.info, Node: GIMPLE_OMP_FOR, Next: GIMPLE_OMP_MASTER, Prev: GIMPLE_OMP_CRITICAL, Up: Tuple specific accessors 12.8.16 ‘GIMPLE_OMP_FOR’ ------------------------ -- GIMPLE function: gomp_for *gimple_build_omp_for (gimple_seq body, tree clauses, tree index, tree initial, tree final, tree incr, gimple_seq pre_body, enum tree_code omp_for_cond) Build a ‘GIMPLE_OMP_FOR’ statement. ‘BODY’ is sequence of statements inside the for loop. ‘CLAUSES’, are any of the loop construct's clauses. ‘PRE_BODY’ is the sequence of statements that are loop invariant. ‘INDEX’ is the index variable. ‘INITIAL’ is the initial value of ‘INDEX’. ‘FINAL’ is final value of ‘INDEX’. OMP_FOR_COND is the predicate used to compare ‘INDEX’ and ‘FINAL’. ‘INCR’ is the increment expression. -- GIMPLE function: tree gimple_omp_for_clauses (gimple g) Return the clauses associated with ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree * gimple_omp_for_clauses_ptr (gimple g) Return a pointer to the ‘OMP_FOR’ ‘G’. -- GIMPLE function: void gimple_omp_for_set_clauses (gimple g, tree clauses) Set ‘CLAUSES’ to be the list of clauses associated with ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree gimple_omp_for_index (gimple g) Return the index variable for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree * gimple_omp_for_index_ptr (gimple g) Return a pointer to the index variable for ‘OMP_FOR’ ‘G’. -- GIMPLE function: void gimple_omp_for_set_index (gimple g, tree index) Set ‘INDEX’ to be the index variable for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree gimple_omp_for_initial (gimple g) Return the initial value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree * gimple_omp_for_initial_ptr (gimple g) Return a pointer to the initial value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: void gimple_omp_for_set_initial (gimple g, tree initial) Set ‘INITIAL’ to be the initial value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree gimple_omp_for_final (gimple g) Return the final value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree * gimple_omp_for_final_ptr (gimple g) turn a pointer to the final value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: void gimple_omp_for_set_final (gimple g, tree final) Set ‘FINAL’ to be the final value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree gimple_omp_for_incr (gimple g) Return the increment value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: tree * gimple_omp_for_incr_ptr (gimple g) Return a pointer to the increment value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: void gimple_omp_for_set_incr (gimple g, tree incr) Set ‘INCR’ to be the increment value for ‘OMP_FOR’ ‘G’. -- GIMPLE function: gimple_seq gimple_omp_for_pre_body (gimple g) Return the sequence of statements to execute before the ‘OMP_FOR’ statement ‘G’ starts. -- GIMPLE function: void gimple_omp_for_set_pre_body (gimple g, gimple_seq pre_body) Set ‘PRE_BODY’ to be the sequence of statements to execute before the ‘OMP_FOR’ statement ‘G’ starts. -- GIMPLE function: void gimple_omp_for_set_cond (gimple g, enum tree_code cond) Set ‘COND’ to be the condition code for ‘OMP_FOR’ ‘G’. -- GIMPLE function: enum tree_code gimple_omp_for_cond (gimple g) Return the condition code associated with ‘OMP_FOR’ ‘G’.  File: gccint.info, Node: GIMPLE_OMP_MASTER, Next: GIMPLE_OMP_ORDERED, Prev: GIMPLE_OMP_FOR, Up: Tuple specific accessors 12.8.17 ‘GIMPLE_OMP_MASTER’ --------------------------- -- GIMPLE function: gimple gimple_build_omp_master (gimple_seq body) Build a ‘GIMPLE_OMP_MASTER’ statement. ‘BODY’ is the sequence of statements to be executed by just the master.  File: gccint.info, Node: GIMPLE_OMP_ORDERED, Next: GIMPLE_OMP_PARALLEL, Prev: GIMPLE_OMP_MASTER, Up: Tuple specific accessors 12.8.18 ‘GIMPLE_OMP_ORDERED’ ---------------------------- -- GIMPLE function: gimple gimple_build_omp_ordered (gimple_seq body) Build a ‘GIMPLE_OMP_ORDERED’ statement. ‘BODY’ is the sequence of statements inside a loop that will executed in sequence.  File: gccint.info, Node: GIMPLE_OMP_PARALLEL, Next: GIMPLE_OMP_RETURN, Prev: GIMPLE_OMP_ORDERED, Up: Tuple specific accessors 12.8.19 ‘GIMPLE_OMP_PARALLEL’ ----------------------------- -- GIMPLE function: gomp_parallel *gimple_build_omp_parallel (gimple_seq body, tree clauses, tree child_fn, tree data_arg) Build a ‘GIMPLE_OMP_PARALLEL’ statement. ‘BODY’ is sequence of statements which are executed in parallel. ‘CLAUSES’, are the ‘OMP’ parallel construct's clauses. ‘CHILD_FN’ is the function created for the parallel threads to execute. ‘DATA_ARG’ are the shared data argument(s). -- GIMPLE function: bool gimple_omp_parallel_combined_p (gimple g) Return true if ‘OMP’ parallel statement ‘G’ has the ‘GF_OMP_PARALLEL_COMBINED’ flag set. -- GIMPLE function: void gimple_omp_parallel_set_combined_p (gimple g) Set the ‘GF_OMP_PARALLEL_COMBINED’ field in ‘OMP’ parallel statement ‘G’. -- GIMPLE function: gimple_seq gimple_omp_body (gimple g) Return the body for the ‘OMP’ statement ‘G’. -- GIMPLE function: void gimple_omp_set_body (gimple g, gimple_seq body) Set ‘BODY’ to be the body for the ‘OMP’ statement ‘G’. -- GIMPLE function: tree gimple_omp_parallel_clauses (gimple g) Return the clauses associated with ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: tree * gimple_omp_parallel_clauses_ptr ( gomp_parallel *g) Return a pointer to the clauses associated with ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: void gimple_omp_parallel_set_clauses ( gomp_parallel *g, tree clauses) Set ‘CLAUSES’ to be the list of clauses associated with ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: tree gimple_omp_parallel_child_fn ( const gomp_parallel *g) Return the child function used to hold the body of ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: tree * gimple_omp_parallel_child_fn_ptr ( gomp_parallel *g) Return a pointer to the child function used to hold the body of ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: void gimple_omp_parallel_set_child_fn ( gomp_parallel *g, tree child_fn) Set ‘CHILD_FN’ to be the child function for ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: tree gimple_omp_parallel_data_arg ( const gomp_parallel *g) Return the artificial argument used to send variables and values from the parent to the children threads in ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: tree * gimple_omp_parallel_data_arg_ptr ( gomp_parallel *g) Return a pointer to the data argument for ‘OMP_PARALLEL’ ‘G’. -- GIMPLE function: void gimple_omp_parallel_set_data_arg ( gomp_parallel *g, tree data_arg) Set ‘DATA_ARG’ to be the data argument for ‘OMP_PARALLEL’ ‘G’.  File: gccint.info, Node: GIMPLE_OMP_RETURN, Next: GIMPLE_OMP_SECTION, Prev: GIMPLE_OMP_PARALLEL, Up: Tuple specific accessors 12.8.20 ‘GIMPLE_OMP_RETURN’ --------------------------- -- GIMPLE function: gimple gimple_build_omp_return (bool wait_p) Build a ‘GIMPLE_OMP_RETURN’ statement. ‘WAIT_P’ is true if this is a non-waiting return. -- GIMPLE function: void gimple_omp_return_set_nowait (gimple s) Set the nowait flag on ‘GIMPLE_OMP_RETURN’ statement ‘S’. -- GIMPLE function: bool gimple_omp_return_nowait_p (gimple g) Return true if ‘OMP’ return statement ‘G’ has the ‘GF_OMP_RETURN_NOWAIT’ flag set.  File: gccint.info, Node: GIMPLE_OMP_SECTION, Next: GIMPLE_OMP_SECTIONS, Prev: GIMPLE_OMP_RETURN, Up: Tuple specific accessors 12.8.21 ‘GIMPLE_OMP_SECTION’ ---------------------------- -- GIMPLE function: gimple gimple_build_omp_section (gimple_seq body) Build a ‘GIMPLE_OMP_SECTION’ statement for a sections statement. ‘BODY’ is the sequence of statements in the section. -- GIMPLE function: bool gimple_omp_section_last_p (gimple g) Return true if ‘OMP’ section statement ‘G’ has the ‘GF_OMP_SECTION_LAST’ flag set. -- GIMPLE function: void gimple_omp_section_set_last (gimple g) Set the ‘GF_OMP_SECTION_LAST’ flag on ‘G’.  File: gccint.info, Node: GIMPLE_OMP_SECTIONS, Next: GIMPLE_OMP_SINGLE, Prev: GIMPLE_OMP_SECTION, Up: Tuple specific accessors 12.8.22 ‘GIMPLE_OMP_SECTIONS’ ----------------------------- -- GIMPLE function: gomp_sections *gimple_build_omp_sections ( gimple_seq body, tree clauses) Build a ‘GIMPLE_OMP_SECTIONS’ statement. ‘BODY’ is a sequence of section statements. ‘CLAUSES’ are any of the ‘OMP’ sections construct's clauses: private, firstprivate, lastprivate, reduction, and nowait. -- GIMPLE function: gimple gimple_build_omp_sections_switch (void) Build a ‘GIMPLE_OMP_SECTIONS_SWITCH’ statement. -- GIMPLE function: tree gimple_omp_sections_control (gimple g) Return the control variable associated with the ‘GIMPLE_OMP_SECTIONS’ in ‘G’. -- GIMPLE function: tree * gimple_omp_sections_control_ptr (gimple g) Return a pointer to the clauses associated with the ‘GIMPLE_OMP_SECTIONS’ in ‘G’. -- GIMPLE function: void gimple_omp_sections_set_control (gimple g, tree control) Set ‘CONTROL’ to be the set of clauses associated with the ‘GIMPLE_OMP_SECTIONS’ in ‘G’. -- GIMPLE function: tree gimple_omp_sections_clauses (gimple g) Return the clauses associated with ‘OMP_SECTIONS’ ‘G’. -- GIMPLE function: tree * gimple_omp_sections_clauses_ptr (gimple g) Return a pointer to the clauses associated with ‘OMP_SECTIONS’ ‘G’. -- GIMPLE function: void gimple_omp_sections_set_clauses (gimple g, tree clauses) Set ‘CLAUSES’ to be the set of clauses associated with ‘OMP_SECTIONS’ ‘G’.  File: gccint.info, Node: GIMPLE_OMP_SINGLE, Next: GIMPLE_OMP_STRUCTURED_BLOCK, Prev: GIMPLE_OMP_SECTIONS, Up: Tuple specific accessors 12.8.23 ‘GIMPLE_OMP_SINGLE’ --------------------------- -- GIMPLE function: gomp_single *gimple_build_omp_single ( gimple_seq body, tree clauses) Build a ‘GIMPLE_OMP_SINGLE’ statement. ‘BODY’ is the sequence of statements that will be executed once. ‘CLAUSES’ are any of the ‘OMP’ single construct's clauses: private, firstprivate, copyprivate, nowait. -- GIMPLE function: tree gimple_omp_single_clauses (gimple g) Return the clauses associated with ‘OMP_SINGLE’ ‘G’. -- GIMPLE function: tree * gimple_omp_single_clauses_ptr (gimple g) Return a pointer to the clauses associated with ‘OMP_SINGLE’ ‘G’. -- GIMPLE function: void gimple_omp_single_set_clauses ( gomp_single *g, tree clauses) Set ‘CLAUSES’ to be the clauses associated with ‘OMP_SINGLE’ ‘G’.  File: gccint.info, Node: GIMPLE_OMP_STRUCTURED_BLOCK, Next: GIMPLE_PHI, Prev: GIMPLE_OMP_SINGLE, Up: Tuple specific accessors 12.8.24 ‘GIMPLE_OMP_STRUCTURED_BLOCK’ ------------------------------------- Like the GENERIC equivalent ‘OMP_STRUCTURED_BLOCK’, this GIMPLE statement does not correspond directly to an OpenMP directive, and exists only to permit error checking of transfers of control in/out of structured block sequences (the ‘diagnose_omp_blocks’ pass in ‘omp-low.cc’). All ‘GIMPLE_OMP_STRUCTURED_BLOCK’ nodes are eliminated during OpenMP lowering. -- GIMPLE function: gimple gimple_build_omp_structured_block (gimple_seq body) Build a ‘GIMPLE_OMP_STRUCTURED_BLOCK’ statement. ‘BODY’ is the sequence of statements in the structured block sequence.  File: gccint.info, Node: GIMPLE_PHI, Next: GIMPLE_RESX, Prev: GIMPLE_OMP_STRUCTURED_BLOCK, Up: Tuple specific accessors 12.8.25 ‘GIMPLE_PHI’ -------------------- -- GIMPLE function: unsigned gimple_phi_capacity (gimple g) Return the maximum number of arguments supported by ‘GIMPLE_PHI’ ‘G’. -- GIMPLE function: unsigned gimple_phi_num_args (gimple g) Return the number of arguments in ‘GIMPLE_PHI’ ‘G’. This must always be exactly the number of incoming edges for the basic block holding ‘G’. -- GIMPLE function: tree gimple_phi_result (gimple g) Return the ‘SSA’ name created by ‘GIMPLE_PHI’ ‘G’. -- GIMPLE function: tree * gimple_phi_result_ptr (gimple g) Return a pointer to the ‘SSA’ name created by ‘GIMPLE_PHI’ ‘G’. -- GIMPLE function: void gimple_phi_set_result (gphi *g, tree result) Set ‘RESULT’ to be the ‘SSA’ name created by ‘GIMPLE_PHI’ ‘G’. -- GIMPLE function: struct phi_arg_d * gimple_phi_arg (gimple g, index) Return the ‘PHI’ argument corresponding to incoming edge ‘INDEX’ for ‘GIMPLE_PHI’ ‘G’. -- GIMPLE function: void gimple_phi_set_arg (gphi *g, index, struct phi_arg_d * phiarg) Set ‘PHIARG’ to be the argument corresponding to incoming edge ‘INDEX’ for ‘GIMPLE_PHI’ ‘G’.  File: gccint.info, Node: GIMPLE_RESX, Next: GIMPLE_RETURN, Prev: GIMPLE_PHI, Up: Tuple specific accessors 12.8.26 ‘GIMPLE_RESX’ --------------------- -- GIMPLE function: gresx *gimple_build_resx (int region) Build a ‘GIMPLE_RESX’ statement which is a statement. This statement is a placeholder for _Unwind_Resume before we know if a function call or a branch is needed. ‘REGION’ is the exception region from which control is flowing. -- GIMPLE function: int gimple_resx_region (const gresx *g) Return the region number for ‘GIMPLE_RESX’ ‘G’. -- GIMPLE function: void gimple_resx_set_region (gresx *g, int region) Set ‘REGION’ to be the region number for ‘GIMPLE_RESX’ ‘G’.  File: gccint.info, Node: GIMPLE_RETURN, Next: GIMPLE_SWITCH, Prev: GIMPLE_RESX, Up: Tuple specific accessors 12.8.27 ‘GIMPLE_RETURN’ ----------------------- -- GIMPLE function: greturn *gimple_build_return (tree retval) Build a ‘GIMPLE_RETURN’ statement whose return value is retval. -- GIMPLE function: tree gimple_return_retval (const greturn *g) Return the return value for ‘GIMPLE_RETURN’ ‘G’. -- GIMPLE function: void gimple_return_set_retval (greturn *g, tree retval) Set ‘RETVAL’ to be the return value for ‘GIMPLE_RETURN’ ‘G’.  File: gccint.info, Node: GIMPLE_SWITCH, Next: GIMPLE_TRY, Prev: GIMPLE_RETURN, Up: Tuple specific accessors 12.8.28 ‘GIMPLE_SWITCH’ ----------------------- -- GIMPLE function: gswitch *gimple_build_switch (tree index, tree default_label, vec *args) Build a ‘GIMPLE_SWITCH’ statement. ‘INDEX’ is the index variable to switch on, and ‘DEFAULT_LABEL’ represents the default label. ‘ARGS’ is a vector of ‘CASE_LABEL_EXPR’ trees that contain the non-default case labels. Each label is a tree of code ‘CASE_LABEL_EXPR’. -- GIMPLE function: unsigned gimple_switch_num_labels ( const gswitch *g) Return the number of labels associated with the switch statement ‘G’. -- GIMPLE function: void gimple_switch_set_num_labels (gswitch *g, unsigned nlabels) Set ‘NLABELS’ to be the number of labels for the switch statement ‘G’. -- GIMPLE function: tree gimple_switch_index (const gswitch *g) Return the index variable used by the switch statement ‘G’. -- GIMPLE function: void gimple_switch_set_index (gswitch *g, tree index) Set ‘INDEX’ to be the index variable for switch statement ‘G’. -- GIMPLE function: tree gimple_switch_label (const gswitch *g, unsigned index) Return the label numbered ‘INDEX’. The default label is 0, followed by any labels in a switch statement. -- GIMPLE function: void gimple_switch_set_label (gswitch *g, unsigned index, tree label) Set the label number ‘INDEX’ to ‘LABEL’. 0 is always the default label. -- GIMPLE function: tree gimple_switch_default_label ( const gswitch *g) Return the default label for a switch statement. -- GIMPLE function: void gimple_switch_set_default_label (gswitch *g, tree label) Set the default label for a switch statement.  File: gccint.info, Node: GIMPLE_TRY, Next: GIMPLE_WITH_CLEANUP_EXPR, Prev: GIMPLE_SWITCH, Up: Tuple specific accessors 12.8.29 ‘GIMPLE_TRY’ -------------------- -- GIMPLE function: gtry *gimple_build_try (gimple_seq eval, gimple_seq cleanup, unsigned int kind) Build a ‘GIMPLE_TRY’ statement. ‘EVAL’ is a sequence with the expression to evaluate. ‘CLEANUP’ is a sequence of statements to run at clean-up time. ‘KIND’ is the enumeration value ‘GIMPLE_TRY_CATCH’ if this statement denotes a try/catch construct or ‘GIMPLE_TRY_FINALLY’ if this statement denotes a try/finally construct. -- GIMPLE function: enum gimple_try_flags gimple_try_kind (gimple g) Return the kind of try block represented by ‘GIMPLE_TRY’ ‘G’. This is either ‘GIMPLE_TRY_CATCH’ or ‘GIMPLE_TRY_FINALLY’. -- GIMPLE function: bool gimple_try_catch_is_cleanup (gimple g) Return the ‘GIMPLE_TRY_CATCH_IS_CLEANUP’ flag. -- GIMPLE function: gimple_seq gimple_try_eval (gimple g) Return the sequence of statements used as the body for ‘GIMPLE_TRY’ ‘G’. -- GIMPLE function: gimple_seq gimple_try_cleanup (gimple g) Return the sequence of statements used as the cleanup body for ‘GIMPLE_TRY’ ‘G’. -- GIMPLE function: void gimple_try_set_catch_is_cleanup (gimple g, bool catch_is_cleanup) Set the ‘GIMPLE_TRY_CATCH_IS_CLEANUP’ flag. -- GIMPLE function: void gimple_try_set_eval (gtry *g, gimple_seq eval) Set ‘EVAL’ to be the sequence of statements to use as the body for ‘GIMPLE_TRY’ ‘G’. -- GIMPLE function: void gimple_try_set_cleanup (gtry *g, gimple_seq cleanup) Set ‘CLEANUP’ to be the sequence of statements to use as the cleanup body for ‘GIMPLE_TRY’ ‘G’.  File: gccint.info, Node: GIMPLE_WITH_CLEANUP_EXPR, Prev: GIMPLE_TRY, Up: Tuple specific accessors 12.8.30 ‘GIMPLE_WITH_CLEANUP_EXPR’ ---------------------------------- -- GIMPLE function: gimple gimple_build_wce (gimple_seq cleanup) Build a ‘GIMPLE_WITH_CLEANUP_EXPR’ statement. ‘CLEANUP’ is the clean-up expression. -- GIMPLE function: gimple_seq gimple_wce_cleanup (gimple g) Return the cleanup sequence for cleanup statement ‘G’. -- GIMPLE function: void gimple_wce_set_cleanup (gimple g, gimple_seq cleanup) Set ‘CLEANUP’ to be the cleanup sequence for ‘G’. -- GIMPLE function: bool gimple_wce_cleanup_eh_only (gimple g) Return the ‘CLEANUP_EH_ONLY’ flag for a ‘WCE’ tuple. -- GIMPLE function: void gimple_wce_set_cleanup_eh_only (gimple g, bool eh_only_p) Set the ‘CLEANUP_EH_ONLY’ flag for a ‘WCE’ tuple.  File: gccint.info, Node: GIMPLE sequences, Next: Sequence iterators, Prev: Tuple specific accessors, Up: GIMPLE 12.9 GIMPLE sequences ===================== GIMPLE sequences are the tuple equivalent of ‘STATEMENT_LIST’'s used in ‘GENERIC’. They are used to chain statements together, and when used in conjunction with sequence iterators, provide a framework for iterating through statements. GIMPLE sequences are of type struct ‘gimple_sequence’, but are more commonly passed by reference to functions dealing with sequences. The type for a sequence pointer is ‘gimple_seq’ which is the same as struct ‘gimple_sequence’ *. When declaring a local sequence, you can define a local variable of type struct ‘gimple_sequence’. When declaring a sequence allocated on the garbage collected heap, use the function ‘gimple_seq_alloc’ documented below. There are convenience functions for iterating through sequences in the section entitled Sequence Iterators. Below is a list of functions to manipulate and query sequences. -- GIMPLE function: void gimple_seq_add_stmt (gimple_seq *seq, gimple g) Link a gimple statement to the end of the sequence *‘SEQ’ if ‘G’ is not ‘NULL’. If *‘SEQ’ is ‘NULL’, allocate a sequence before linking. -- GIMPLE function: void gimple_seq_add_seq (gimple_seq *dest, gimple_seq src) Append sequence ‘SRC’ to the end of sequence *‘DEST’ if ‘SRC’ is not ‘NULL’. If *‘DEST’ is ‘NULL’, allocate a new sequence before appending. -- GIMPLE function: gimple_seq gimple_seq_deep_copy (gimple_seq src) Perform a deep copy of sequence ‘SRC’ and return the result. -- GIMPLE function: gimple_seq gimple_seq_reverse (gimple_seq seq) Reverse the order of the statements in the sequence ‘SEQ’. Return ‘SEQ’. -- GIMPLE function: gimple gimple_seq_first (gimple_seq s) Return the first statement in sequence ‘S’. -- GIMPLE function: gimple gimple_seq_last (gimple_seq s) Return the last statement in sequence ‘S’. -- GIMPLE function: void gimple_seq_set_last (gimple_seq s, gimple last) Set the last statement in sequence ‘S’ to the statement in ‘LAST’. -- GIMPLE function: void gimple_seq_set_first (gimple_seq s, gimple first) Set the first statement in sequence ‘S’ to the statement in ‘FIRST’. -- GIMPLE function: void gimple_seq_init (gimple_seq s) Initialize sequence ‘S’ to an empty sequence. -- GIMPLE function: gimple_seq gimple_seq_alloc (void) Allocate a new sequence in the garbage collected store and return it. -- GIMPLE function: void gimple_seq_copy (gimple_seq dest, gimple_seq src) Copy the sequence ‘SRC’ into the sequence ‘DEST’. -- GIMPLE function: bool gimple_seq_empty_p (gimple_seq s) Return true if the sequence ‘S’ is empty. -- GIMPLE function: gimple_seq bb_seq (basic_block bb) Returns the sequence of statements in ‘BB’. -- GIMPLE function: void set_bb_seq (basic_block bb, gimple_seq seq) Sets the sequence of statements in ‘BB’ to ‘SEQ’. -- GIMPLE function: bool gimple_seq_singleton_p (gimple_seq seq) Determine whether ‘SEQ’ contains exactly one statement.  File: gccint.info, Node: Sequence iterators, Next: Adding a new GIMPLE statement code, Prev: GIMPLE sequences, Up: GIMPLE 12.10 Sequence iterators ======================== Sequence iterators are convenience constructs for iterating through statements in a sequence. Given a sequence ‘SEQ’, here is a typical use of gimple sequence iterators: gimple_stmt_iterator gsi; for (gsi = gsi_start (seq); !gsi_end_p (gsi); gsi_next (&gsi)) { gimple g = gsi_stmt (gsi); /* Do something with gimple statement G. */ } Backward iterations are possible: for (gsi = gsi_last (seq); !gsi_end_p (gsi); gsi_prev (&gsi)) Forward and backward iterations on basic blocks are possible with ‘gsi_start_bb’ and ‘gsi_last_bb’. In the documentation below we sometimes refer to enum ‘gsi_iterator_update’. The valid options for this enumeration are: • ‘GSI_NEW_STMT’ Only valid when a single statement is added. Move the iterator to it. • ‘GSI_SAME_STMT’ Leave the iterator at the same statement. • ‘GSI_CONTINUE_LINKING’ Move iterator to whatever position is suitable for linking other statements in the same direction. Below is a list of the functions used to manipulate and use statement iterators. -- GIMPLE function: gimple_stmt_iterator gsi_start (gimple_seq seq) Return a new iterator pointing to the sequence ‘SEQ’'s first statement. If ‘SEQ’ is empty, the iterator's basic block is ‘NULL’. Use ‘gsi_start_bb’ instead when the iterator needs to always have the correct basic block set. -- GIMPLE function: gimple_stmt_iterator gsi_start_bb (basic_block bb) Return a new iterator pointing to the first statement in basic block ‘BB’. -- GIMPLE function: gimple_stmt_iterator gsi_last (gimple_seq seq) Return a new iterator initially pointing to the last statement of sequence ‘SEQ’. If ‘SEQ’ is empty, the iterator's basic block is ‘NULL’. Use ‘gsi_last_bb’ instead when the iterator needs to always have the correct basic block set. -- GIMPLE function: gimple_stmt_iterator gsi_last_bb (basic_block bb) Return a new iterator pointing to the last statement in basic block ‘BB’. -- GIMPLE function: bool gsi_end_p (gimple_stmt_iterator i) Return ‘TRUE’ if at the end of ‘I’. -- GIMPLE function: bool gsi_one_before_end_p (gimple_stmt_iterator i) Return ‘TRUE’ if we're one statement before the end of ‘I’. -- GIMPLE function: void gsi_next (gimple_stmt_iterator *i) Advance the iterator to the next gimple statement. -- GIMPLE function: void gsi_prev (gimple_stmt_iterator *i) Advance the iterator to the previous gimple statement. -- GIMPLE function: gimple gsi_stmt (gimple_stmt_iterator i) Return the current stmt. -- GIMPLE function: gimple_stmt_iterator gsi_after_labels (basic_block bb) Return a block statement iterator that points to the first non-label statement in block ‘BB’. -- GIMPLE function: gimple * gsi_stmt_ptr (gimple_stmt_iterator *i) Return a pointer to the current stmt. -- GIMPLE function: basic_block gsi_bb (gimple_stmt_iterator i) Return the basic block associated with this iterator. -- GIMPLE function: gimple_seq gsi_seq (gimple_stmt_iterator i) Return the sequence associated with this iterator. -- GIMPLE function: void gsi_remove (gimple_stmt_iterator *i, bool remove_eh_info) Remove the current stmt from the sequence. The iterator is updated to point to the next statement. When ‘REMOVE_EH_INFO’ is true we remove the statement pointed to by iterator ‘I’ from the ‘EH’ tables. Otherwise we do not modify the ‘EH’ tables. Generally, ‘REMOVE_EH_INFO’ should be true when the statement is going to be removed from the ‘IL’ and not reinserted elsewhere. -- GIMPLE function: void gsi_link_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode) Links the sequence of statements ‘SEQ’ before the statement pointed by iterator ‘I’. ‘MODE’ indicates what to do with the iterator after insertion (see ‘enum gsi_iterator_update’ above). -- GIMPLE function: void gsi_link_before (gimple_stmt_iterator *i, gimple g, enum gsi_iterator_update mode) Links statement ‘G’ before the statement pointed-to by iterator ‘I’. Updates iterator ‘I’ according to ‘MODE’. -- GIMPLE function: void gsi_link_seq_after (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode) Links sequence ‘SEQ’ after the statement pointed-to by iterator ‘I’. ‘MODE’ is as in ‘gsi_insert_after’. -- GIMPLE function: void gsi_link_after (gimple_stmt_iterator *i, gimple g, enum gsi_iterator_update mode) Links statement ‘G’ after the statement pointed-to by iterator ‘I’. ‘MODE’ is as in ‘gsi_insert_after’. -- GIMPLE function: gimple_seq gsi_split_seq_after (gimple_stmt_iterator i) Move all statements in the sequence after ‘I’ to a new sequence. Return this new sequence. -- GIMPLE function: gimple_seq gsi_split_seq_before (gimple_stmt_iterator *i) Move all statements in the sequence before ‘I’ to a new sequence. Return this new sequence. -- GIMPLE function: void gsi_replace (gimple_stmt_iterator *i, gimple stmt, bool update_eh_info) Replace the statement pointed-to by ‘I’ to ‘STMT’. If ‘UPDATE_EH_INFO’ is true, the exception handling information of the original statement is moved to the new statement. -- GIMPLE function: void gsi_insert_before (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode) Insert statement ‘STMT’ before the statement pointed-to by iterator ‘I’, update ‘STMT’'s basic block and scan it for new operands. ‘MODE’ specifies how to update iterator ‘I’ after insertion (see enum ‘gsi_iterator_update’). -- GIMPLE function: void gsi_insert_seq_before (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode) Like ‘gsi_insert_before’, but for all the statements in ‘SEQ’. -- GIMPLE function: void gsi_insert_after (gimple_stmt_iterator *i, gimple stmt, enum gsi_iterator_update mode) Insert statement ‘STMT’ after the statement pointed-to by iterator ‘I’, update ‘STMT’'s basic block and scan it for new operands. ‘MODE’ specifies how to update iterator ‘I’ after insertion (see enum ‘gsi_iterator_update’). -- GIMPLE function: void gsi_insert_seq_after (gimple_stmt_iterator *i, gimple_seq seq, enum gsi_iterator_update mode) Like ‘gsi_insert_after’, but for all the statements in ‘SEQ’. -- GIMPLE function: gimple_stmt_iterator gsi_for_stmt (gimple stmt) Finds iterator for ‘STMT’. -- GIMPLE function: void gsi_move_after (gimple_stmt_iterator *from, gimple_stmt_iterator *to) Move the statement at ‘FROM’ so it comes right after the statement at ‘TO’. -- GIMPLE function: void gsi_move_before (gimple_stmt_iterator *from, gimple_stmt_iterator *to) Move the statement at ‘FROM’ so it comes right before the statement at ‘TO’. -- GIMPLE function: void gsi_move_to_bb_end (gimple_stmt_iterator *from, basic_block bb) Move the statement at ‘FROM’ to the end of basic block ‘BB’. -- GIMPLE function: void gsi_insert_on_edge (edge e, gimple stmt) Add ‘STMT’ to the pending list of edge ‘E’. No actual insertion is made until a call to ‘gsi_commit_edge_inserts’() is made. -- GIMPLE function: void gsi_insert_seq_on_edge (edge e, gimple_seq seq) Add the sequence of statements in ‘SEQ’ to the pending list of edge ‘E’. No actual insertion is made until a call to ‘gsi_commit_edge_inserts’() is made. -- GIMPLE function: basic_block gsi_insert_on_edge_immediate (edge e, gimple stmt) Similar to ‘gsi_insert_on_edge’+‘gsi_commit_edge_inserts’. If a new block has to be created, it is returned. -- GIMPLE function: void gsi_commit_one_edge_insert (edge e, basic_block *new_bb) Commit insertions pending at edge ‘E’. If a new block is created, set ‘NEW_BB’ to this block, otherwise set it to ‘NULL’. -- GIMPLE function: void gsi_commit_edge_inserts (void) This routine will commit all pending edge insertions, creating any new basic blocks which are necessary.  File: gccint.info, Node: Adding a new GIMPLE statement code, Next: Statement and operand traversals, Prev: Sequence iterators, Up: GIMPLE 12.11 Adding a new GIMPLE statement code ======================================== The first step in adding a new GIMPLE statement code, is modifying the file ‘gimple.def’, which contains all the GIMPLE codes. Then you must add a corresponding gimple subclass located in ‘gimple.h’. This in turn, will require you to add a corresponding ‘GTY’ tag in ‘gsstruct.def’, and code to handle this tag in ‘gss_for_code’ which is located in ‘gimple.cc’. In order for the garbage collector to know the size of the structure you created in ‘gimple.h’, you need to add a case to handle your new GIMPLE statement in ‘gimple_size’ which is located in ‘gimple.cc’. You will probably want to create a function to build the new gimple statement in ‘gimple.cc’. The function should be called ‘gimple_build_NEW-TUPLE-NAME’, and should return the new tuple as a pointer to the appropriate gimple subclass. If your new statement requires accessors for any members or operands it may have, put simple inline accessors in ‘gimple.h’ and any non-trivial accessors in ‘gimple.cc’ with a corresponding prototype in ‘gimple.h’. You should add the new statement subclass to the class hierarchy diagram in ‘gimple.texi’.  File: gccint.info, Node: Statement and operand traversals, Prev: Adding a new GIMPLE statement code, Up: GIMPLE 12.12 Statement and operand traversals ====================================== There are two functions available for walking statements and sequences: ‘walk_gimple_stmt’ and ‘walk_gimple_seq’, accordingly, and a third function for walking the operands in a statement: ‘walk_gimple_op’. -- GIMPLE function: tree walk_gimple_stmt (gimple_stmt_iterator *gsi, walk_stmt_fn callback_stmt, walk_tree_fn callback_op, struct walk_stmt_info *wi) This function is used to walk the current statement in ‘GSI’, optionally using traversal state stored in ‘WI’. If ‘WI’ is ‘NULL’, no state is kept during the traversal. The callback ‘CALLBACK_STMT’ is called. If ‘CALLBACK_STMT’ returns true, it means that the callback function has handled all the operands of the statement and it is not necessary to walk its operands. If ‘CALLBACK_STMT’ is ‘NULL’ or it returns false, ‘CALLBACK_OP’ is called on each operand of the statement via ‘walk_gimple_op’. If ‘walk_gimple_op’ returns non-‘NULL’ for any operand, the remaining operands are not scanned. The return value is that returned by the last call to ‘walk_gimple_op’, or ‘NULL_TREE’ if no ‘CALLBACK_OP’ is specified. -- GIMPLE function: tree walk_gimple_op (gimple stmt, walk_tree_fn callback_op, struct walk_stmt_info *wi) Use this function to walk the operands of statement ‘STMT’. Every operand is walked via ‘walk_tree’ with optional state information in ‘WI’. ‘CALLBACK_OP’ is called on each operand of ‘STMT’ via ‘walk_tree’. Additional parameters to ‘walk_tree’ must be stored in ‘WI’. For each operand ‘OP’, ‘walk_tree’ is called as: walk_tree (&OP, CALLBACK_OP, WI, PSET) If ‘CALLBACK_OP’ returns non-‘NULL’ for an operand, the remaining operands are not scanned. The return value is that returned by the last call to ‘walk_tree’, or ‘NULL_TREE’ if no ‘CALLBACK_OP’ is specified. -- GIMPLE function: tree walk_gimple_seq (gimple_seq seq, walk_stmt_fn callback_stmt, walk_tree_fn callback_op, struct walk_stmt_info *wi) This function walks all the statements in the sequence ‘SEQ’ calling ‘walk_gimple_stmt’ on each one. ‘WI’ is as in ‘walk_gimple_stmt’. If ‘walk_gimple_stmt’ returns non-‘NULL’, the walk is stopped and the value returned. Otherwise, all the statements are walked and ‘NULL_TREE’ returned.  File: gccint.info, Node: Tree SSA, Next: RTL, Prev: GIMPLE, Up: Top 13 Analysis and Optimization of GIMPLE tuples ********************************************* GCC uses three main intermediate languages to represent the program during compilation: GENERIC, GIMPLE and RTL. GENERIC is a language-independent representation generated by each front end. It is used to serve as an interface between the parser and optimizer. GENERIC is a common representation that is able to represent programs written in all the languages supported by GCC. GIMPLE and RTL are used to optimize the program. GIMPLE is used for target and language independent optimizations (e.g., inlining, constant propagation, tail call elimination, redundancy elimination, etc). Much like GENERIC, GIMPLE is a language independent, tree based representation. However, it differs from GENERIC in that the GIMPLE grammar is more restrictive: expressions contain no more than 3 operands (except function calls), it has no control flow structures and expressions with side effects are only allowed on the right hand side of assignments. See the chapter describing GENERIC and GIMPLE for more details. This chapter describes the data structures and functions used in the GIMPLE optimizers (also known as "tree optimizers" or "middle end"). In particular, it focuses on all the macros, data structures, functions and programming constructs needed to implement optimization passes for GIMPLE. * Menu: * Annotations:: Attributes for variables. * SSA Operands:: SSA names referenced by GIMPLE statements. * SSA:: Static Single Assignment representation. * Alias analysis:: Representing aliased loads and stores. * Memory model:: Memory model used by the middle-end.  File: gccint.info, Node: Annotations, Next: SSA Operands, Up: Tree SSA 13.1 Annotations ================ The optimizers need to associate attributes with variables during the optimization process. For instance, we need to know whether a variable has aliases. All these attributes are stored in data structures called annotations which are then linked to the field ‘ann’ in ‘struct tree_common’.  File: gccint.info, Node: SSA Operands, Next: SSA, Prev: Annotations, Up: Tree SSA 13.2 SSA Operands ================= Almost every GIMPLE statement will contain a reference to a variable or memory location. Since statements come in different shapes and sizes, their operands are going to be located at various spots inside the statement's tree. To facilitate access to the statement's operands, they are organized into lists associated inside each statement's annotation. Each element in an operand list is a pointer to a ‘VAR_DECL’, ‘PARM_DECL’ or ‘SSA_NAME’ tree node. This provides a very convenient way of examining and replacing operands. Data flow analysis and optimization is done on all tree nodes representing variables. Any node for which ‘SSA_VAR_P’ returns nonzero is considered when scanning statement operands. However, not all ‘SSA_VAR_P’ variables are processed in the same way. For the purposes of optimization, we need to distinguish between references to local scalar variables and references to globals, statics, structures, arrays, aliased variables, etc. The reason is simple, the compiler can gather complete data flow information for a local scalar. On the other hand, a global variable may be modified by a function call, it may not be possible to keep track of all the elements of an array or the fields of a structure, etc. The operand scanner gathers two kinds of operands: “real” and “virtual”. An operand for which ‘is_gimple_reg’ returns true is considered real, otherwise it is a virtual operand. We also distinguish between uses and definitions. An operand is used if its value is loaded by the statement (e.g., the operand at the RHS of an assignment). If the statement assigns a new value to the operand, the operand is considered a definition (e.g., the operand at the LHS of an assignment). Virtual and real operands also have very different data flow properties. Real operands are unambiguous references to the full object that they represent. For instance, given { int a, b; a = b } Since ‘a’ and ‘b’ are non-aliased locals, the statement ‘a = b’ will have one real definition and one real use because variable ‘a’ is completely modified with the contents of variable ‘b’. Real definition are also known as “killing definitions”. Similarly, the use of ‘b’ reads all its bits. In contrast, virtual operands are used with variables that can have a partial or ambiguous reference. This includes structures, arrays, globals, and aliased variables. In these cases, we have two types of definitions. For globals, structures, and arrays, we can determine from a statement whether a variable of these types has a killing definition. If the variable does, then the statement is marked as having a “must definition” of that variable. However, if a statement is only defining a part of the variable (i.e. a field in a structure), or if we know that a statement might define the variable but we cannot say for sure, then we mark that statement as having a “may definition”. For instance, given { int a, b, *p; if (...) p = &a; else p = &b; *p = 5; return *p; } The assignment ‘*p = 5’ may be a definition of ‘a’ or ‘b’. If we cannot determine statically where ‘p’ is pointing to at the time of the store operation, we create virtual definitions to mark that statement as a potential definition site for ‘a’ and ‘b’. Memory loads are similarly marked with virtual use operands. Virtual operands are shown in tree dumps right before the statement that contains them. To request a tree dump with virtual operands, use the ‘-vops’ option to ‘-fdump-tree’: { int a, b, *p; if (...) p = &a; else p = &b; # a = VDEF # b = VDEF *p = 5; # VUSE # VUSE return *p; } Notice that ‘VDEF’ operands have two copies of the referenced variable. This indicates that this is not a killing definition of that variable. In this case we refer to it as a “may definition” or “aliased store”. The presence of the second copy of the variable in the ‘VDEF’ operand will become important when the function is converted into SSA form. This will be used to link all the non-killing definitions to prevent optimizations from making incorrect assumptions about them. Operands are updated as soon as the statement is finished via a call to ‘update_stmt’. If statement elements are changed via ‘SET_USE’ or ‘SET_DEF’, then no further action is required (i.e., those macros take care of updating the statement). If changes are made by manipulating the statement's tree directly, then a call must be made to ‘update_stmt’ when complete. Calling one of the ‘bsi_insert’ routines or ‘bsi_replace’ performs an implicit call to ‘update_stmt’. 13.2.1 Operand Iterators And Access Routines -------------------------------------------- Operands are collected by ‘tree-ssa-operands.cc’. They are stored inside each statement's annotation and can be accessed through either the operand iterators or an access routine. The following access routines are available for examining operands: 1. ‘SINGLE_SSA_{USE,DEF,TREE}_OPERAND’: These accessors will return NULL unless there is exactly one operand matching the specified flags. If there is exactly one operand, the operand is returned as either a ‘tree’, ‘def_operand_p’, or ‘use_operand_p’. tree t = SINGLE_SSA_TREE_OPERAND (stmt, flags); use_operand_p u = SINGLE_SSA_USE_OPERAND (stmt, SSA_ALL_VIRTUAL_USES); def_operand_p d = SINGLE_SSA_DEF_OPERAND (stmt, SSA_OP_ALL_DEFS); 2. ‘ZERO_SSA_OPERANDS’: This macro returns true if there are no operands matching the specified flags. if (ZERO_SSA_OPERANDS (stmt, SSA_OP_ALL_VIRTUALS)) return; 3. ‘NUM_SSA_OPERANDS’: This macro Returns the number of operands matching 'flags'. This actually executes a loop to perform the count, so only use this if it is really needed. int count = NUM_SSA_OPERANDS (stmt, flags) If you wish to iterate over some or all operands, use the ‘FOR_EACH_SSA_{USE,DEF,TREE}_OPERAND’ iterator. For example, to print all the operands for a statement: void print_ops (tree stmt) { ssa_op_iter; tree var; FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_ALL_OPERANDS) print_generic_expr (stderr, var, TDF_SLIM); } How to choose the appropriate iterator: 1. Determine whether you are need to see the operand pointers, or just the trees, and choose the appropriate macro: Need Macro: ---- ------- use_operand_p FOR_EACH_SSA_USE_OPERAND def_operand_p FOR_EACH_SSA_DEF_OPERAND tree FOR_EACH_SSA_TREE_OPERAND 2. You need to declare a variable of the type you are interested in, and an ssa_op_iter structure which serves as the loop controlling variable. 3. Determine which operands you wish to use, and specify the flags of those you are interested in. They are documented in ‘tree-ssa-operands.h’: #define SSA_OP_USE 0x01 /* Real USE operands. */ #define SSA_OP_DEF 0x02 /* Real DEF operands. */ #define SSA_OP_VUSE 0x04 /* VUSE operands. */ #define SSA_OP_VDEF 0x08 /* VDEF operands. */ /* These are commonly grouped operand flags. */ #define SSA_OP_VIRTUAL_USES (SSA_OP_VUSE) #define SSA_OP_VIRTUAL_DEFS (SSA_OP_VDEF) #define SSA_OP_ALL_VIRTUALS (SSA_OP_VIRTUAL_USES | SSA_OP_VIRTUAL_DEFS) #define SSA_OP_ALL_USES (SSA_OP_VIRTUAL_USES | SSA_OP_USE) #define SSA_OP_ALL_DEFS (SSA_OP_VIRTUAL_DEFS | SSA_OP_DEF) #define SSA_OP_ALL_OPERANDS (SSA_OP_ALL_USES | SSA_OP_ALL_DEFS) So if you want to look at the use pointers for all the ‘USE’ and ‘VUSE’ operands, you would do something like: use_operand_p use_p; ssa_op_iter iter; FOR_EACH_SSA_USE_OPERAND (use_p, stmt, iter, (SSA_OP_USE | SSA_OP_VUSE)) { process_use_ptr (use_p); } The ‘TREE’ macro is basically the same as the ‘USE’ and ‘DEF’ macros, only with the use or def dereferenced via ‘USE_FROM_PTR (use_p)’ and ‘DEF_FROM_PTR (def_p)’. Since we aren't using operand pointers, use and defs flags can be mixed. tree var; ssa_op_iter iter; FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_VUSE) { print_generic_expr (stderr, var, TDF_SLIM); } ‘VDEF’s are broken into two flags, one for the ‘DEF’ portion (‘SSA_OP_VDEF’) and one for the USE portion (‘SSA_OP_VUSE’). There are many examples in the code, in addition to the documentation in ‘tree-ssa-operands.h’ and ‘ssa-iterators.h’. There are also a couple of variants on the stmt iterators regarding PHI nodes. ‘FOR_EACH_PHI_ARG’ Works exactly like ‘FOR_EACH_SSA_USE_OPERAND’, except it works over ‘PHI’ arguments instead of statement operands. /* Look at every virtual PHI use. */ FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_VIRTUAL_USES) { my_code; } /* Look at every real PHI use. */ FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_USES) my_code; /* Look at every PHI use. */ FOR_EACH_PHI_ARG (use_p, phi_stmt, iter, SSA_OP_ALL_USES) my_code; ‘FOR_EACH_PHI_OR_STMT_{USE,DEF}’ works exactly like ‘FOR_EACH_SSA_{USE,DEF}_OPERAND’, except it will function on either a statement or a ‘PHI’ node. These should be used when it is appropriate but they are not quite as efficient as the individual ‘FOR_EACH_PHI’ and ‘FOR_EACH_SSA’ routines. FOR_EACH_PHI_OR_STMT_USE (use_operand_p, stmt, iter, flags) { my_code; } FOR_EACH_PHI_OR_STMT_DEF (def_operand_p, phi, iter, flags) { my_code; } 13.2.2 Immediate Uses --------------------- Immediate use information is now always available. Using the immediate use iterators, you may examine every use of any ‘SSA_NAME’. For instance, to change each use of ‘ssa_var’ to ‘ssa_var2’ and call fold_stmt on each stmt after that is done: use_operand_p imm_use_p; imm_use_iterator iterator; tree ssa_var, stmt; FOR_EACH_IMM_USE_STMT (stmt, iterator, ssa_var) { FOR_EACH_IMM_USE_ON_STMT (imm_use_p, iterator) SET_USE (imm_use_p, ssa_var_2); fold_stmt (stmt); } There are 2 iterators which can be used. ‘FOR_EACH_IMM_USE_FAST’ is used when the immediate uses are not changed, i.e., you are looking at the uses, but not setting them. If they do get changed, then care must be taken that things are not changed under the iterators, so use the ‘FOR_EACH_IMM_USE_STMT’ and ‘FOR_EACH_IMM_USE_ON_STMT’ iterators. They attempt to preserve the sanity of the use list by moving all the uses for a statement into a controlled position, and then iterating over those uses. Then the optimization can manipulate the stmt when all the uses have been processed. This is a little slower than the FAST version since it adds a placeholder element and must sort through the list a bit for each statement. This placeholder element must be also be removed if the loop is terminated early; a destructor takes care of that when leaving the ‘FOR_EACH_IMM_USE_STMT’ scope. There are checks in ‘verify_ssa’ which verify that the immediate use list is up to date, as well as checking that an optimization didn't break from the loop without using this macro. It is safe to simply 'break'; from a ‘FOR_EACH_IMM_USE_FAST’ traverse. Some useful functions and macros: 1. ‘has_zero_uses (ssa_var)’ : Returns true if there are no uses of ‘ssa_var’. 2. ‘has_single_use (ssa_var)’ : Returns true if there is only a single use of ‘ssa_var’. 3. ‘single_imm_use (ssa_var, use_operand_p *ptr, tree *stmt)’ : Returns true if there is only a single use of ‘ssa_var’, and also returns the use pointer and statement it occurs in, in the second and third parameters. 4. ‘num_imm_uses (ssa_var)’ : Returns the number of immediate uses of ‘ssa_var’. It is better not to use this if possible since it simply utilizes a loop to count the uses. 5. ‘PHI_ARG_INDEX_FROM_USE (use_p)’ : Given a use within a ‘PHI’ node, return the index number for the use. An assert is triggered if the use isn't located in a ‘PHI’ node. 6. ‘USE_STMT (use_p)’ : Return the statement a use occurs in. Note that uses are not put into an immediate use list until their statement is actually inserted into the instruction stream via a ‘bsi_*’ routine. It is also still possible to utilize lazy updating of statements, but this should be used only when absolutely required. Both alias analysis and the dominator optimizations currently do this. When lazy updating is being used, the immediate use information is out of date and cannot be used reliably. Lazy updating is achieved by simply marking statements modified via calls to ‘gimple_set_modified’ instead of ‘update_stmt’. When lazy updating is no longer required, all the modified statements must have ‘update_stmt’ called in order to bring them up to date. This must be done before the optimization is finished, or ‘verify_ssa’ will trigger an abort. This is done with a simple loop over the instruction stream: block_stmt_iterator bsi; basic_block bb; FOR_EACH_BB (bb) { for (bsi = bsi_start (bb); !bsi_end_p (bsi); bsi_next (&bsi)) update_stmt_if_modified (bsi_stmt (bsi)); }  File: gccint.info, Node: SSA, Next: Alias analysis, Prev: SSA Operands, Up: Tree SSA 13.3 Static Single Assignment ============================= Most of the tree optimizers rely on the data flow information provided by the Static Single Assignment (SSA) form. We implement the SSA form as described in ‘R. Cytron, J. Ferrante, B. Rosen, M. Wegman, and K. Zadeck. Efficiently Computing Static Single Assignment Form and the Control Dependence Graph. ACM Transactions on Programming Languages and Systems, 13(4):451-490, October 1991’. The SSA form is based on the premise that program variables are assigned in exactly one location in the program. Multiple assignments to the same variable create new versions of that variable. Naturally, actual programs are seldom in SSA form initially because variables tend to be assigned multiple times. The compiler modifies the program representation so that every time a variable is assigned in the code, a new version of the variable is created. Different versions of the same variable are distinguished by subscripting the variable name with its version number. Variables used in the right-hand side of expressions are renamed so that their version number matches that of the most recent assignment. We represent variable versions using ‘SSA_NAME’ nodes. The renaming process in ‘tree-ssa.cc’ wraps every real and virtual operand with an ‘SSA_NAME’ node which contains the version number and the statement that created the ‘SSA_NAME’. Only definitions and virtual definitions may create new ‘SSA_NAME’ nodes. Sometimes, flow of control makes it impossible to determine the most recent version of a variable. In these cases, the compiler inserts an artificial definition for that variable called “PHI function” or “PHI node”. This new definition merges all the incoming versions of the variable to create a new name for it. For instance, if (...) a_1 = 5; else if (...) a_2 = 2; else a_3 = 13; # a_4 = PHI return a_4; Since it is not possible to determine which of the three branches will be taken at runtime, we don't know which of ‘a_1’, ‘a_2’ or ‘a_3’ to use at the return statement. So, the SSA renamer creates a new version ‘a_4’ which is assigned the result of "merging" ‘a_1’, ‘a_2’ and ‘a_3’. Hence, PHI nodes mean "one of these operands. I don't know which". The following functions can be used to examine PHI nodes -- Function: gimple_phi_result (PHI) Returns the ‘SSA_NAME’ created by PHI node PHI (i.e., PHI's LHS). -- Function: gimple_phi_num_args (PHI) Returns the number of arguments in PHI. This number is exactly the number of incoming edges to the basic block holding PHI. -- Function: gimple_phi_arg (PHI, I) Returns Ith argument of PHI. -- Function: gimple_phi_arg_edge (PHI, I) Returns the incoming edge for the Ith argument of PHI. -- Function: gimple_phi_arg_def (PHI, I) Returns the ‘SSA_NAME’ for the Ith argument of PHI. 13.3.1 Preserving the SSA form ------------------------------ Some optimization passes make changes to the function that invalidate the SSA property. This can happen when a pass has added new symbols or changed the program so that variables that were previously aliased aren't anymore. Whenever something like this happens, the affected symbols must be renamed into SSA form again. Transformations that emit new code or replicate existing statements will also need to update the SSA form. Since GCC implements two different SSA forms for register and virtual variables, keeping the SSA form up to date depends on whether you are updating register or virtual names. In both cases, the general idea behind incremental SSA updates is similar: when new SSA names are created, they typically are meant to replace other existing names in the program. For instance, given the following code: 1 L0: 2 x_1 = PHI (0, x_5) 3 if (x_1 < 10) 4 if (x_1 > 7) 5 y_2 = 0 6 else 7 y_3 = x_1 + x_7 8 endif 9 x_5 = x_1 + 1 10 goto L0; 11 endif Suppose that we insert new names ‘x_10’ and ‘x_11’ (lines ‘4’ and ‘8’). 1 L0: 2 x_1 = PHI (0, x_5) 3 if (x_1 < 10) 4 x_10 = ... 5 if (x_1 > 7) 6 y_2 = 0 7 else 8 x_11 = ... 9 y_3 = x_1 + x_7 10 endif 11 x_5 = x_1 + 1 12 goto L0; 13 endif We want to replace all the uses of ‘x_1’ with the new definitions of ‘x_10’ and ‘x_11’. Note that the only uses that should be replaced are those at lines ‘5’, ‘9’ and ‘11’. Also, the use of ‘x_7’ at line ‘9’ should _not_ be replaced (this is why we cannot just mark symbol ‘x’ for renaming). Additionally, we may need to insert a PHI node at line ‘11’ because that is a merge point for ‘x_10’ and ‘x_11’. So the use of ‘x_1’ at line ‘11’ will be replaced with the new PHI node. The insertion of PHI nodes is optional. They are not strictly necessary to preserve the SSA form, and depending on what the caller inserted, they may not even be useful for the optimizers. Updating the SSA form is a two step process. First, the pass has to identify which names need to be updated and/or which symbols need to be renamed into SSA form for the first time. When new names are introduced to replace existing names in the program, the mapping between the old and the new names are registered by calling ‘register_new_name_mapping’ (note that if your pass creates new code by duplicating basic blocks, the call to ‘tree_duplicate_bb’ will set up the necessary mappings automatically). After the replacement mappings have been registered and new symbols marked for renaming, a call to ‘update_ssa’ makes the registered changes. This can be done with an explicit call or by creating ‘TODO’ flags in the ‘tree_opt_pass’ structure for your pass. There are several ‘TODO’ flags that control the behavior of ‘update_ssa’: • ‘TODO_update_ssa’. Update the SSA form inserting PHI nodes for newly exposed symbols and virtual names marked for updating. When updating real names, only insert PHI nodes for a real name ‘O_j’ in blocks reached by all the new and old definitions for ‘O_j’. If the iterated dominance frontier for ‘O_j’ is not pruned, we may end up inserting PHI nodes in blocks that have one or more edges with no incoming definition for ‘O_j’. This would lead to uninitialized warnings for ‘O_j’'s symbol. • ‘TODO_update_ssa_no_phi’. Update the SSA form without inserting any new PHI nodes at all. This is used by passes that have either inserted all the PHI nodes themselves or passes that need only to patch use-def and def-def chains for virtuals (e.g., DCE). • ‘TODO_update_ssa_full_phi’. Insert PHI nodes everywhere they are needed. No pruning of the IDF is done. This is used by passes that need the PHI nodes for ‘O_j’ even if it means that some arguments will come from the default definition of ‘O_j’'s symbol (e.g., ‘pass_linear_transform’). WARNING: If you need to use this flag, chances are that your pass may be doing something wrong. Inserting PHI nodes for an old name where not all edges carry a new replacement may lead to silent codegen errors or spurious uninitialized warnings. • ‘TODO_update_ssa_only_virtuals’. Passes that update the SSA form on their own may want to delegate the updating of virtual names to the generic updater. Since FUD chains are easier to maintain, this simplifies the work they need to do. NOTE: If this flag is used, any OLD->NEW mappings for real names are explicitly destroyed and only the symbols marked for renaming are processed. 13.3.2 Examining ‘SSA_NAME’ nodes --------------------------------- The following macros can be used to examine ‘SSA_NAME’ nodes -- Macro: SSA_NAME_DEF_STMT (VAR) Returns the statement S that creates the ‘SSA_NAME’ VAR. If S is an empty statement (i.e., ‘IS_EMPTY_STMT (S)’ returns ‘true’), it means that the first reference to this variable is a USE or a VUSE. -- Macro: SSA_NAME_VERSION (VAR) Returns the version number of the ‘SSA_NAME’ object VAR. 13.3.3 Walking the dominator tree --------------------------------- -- Tree SSA function: void walk_dominator_tree (WALK_DATA, BB) This function walks the dominator tree for the current CFG calling a set of callback functions defined in STRUCT DOM_WALK_DATA in ‘domwalk.h’. The call back functions you need to define give you hooks to execute custom code at various points during traversal: 1. Once to initialize any local data needed while processing BB and its children. This local data is pushed into an internal stack which is automatically pushed and popped as the walker traverses the dominator tree. 2. Once before traversing all the statements in the BB. 3. Once for every statement inside BB. 4. Once after traversing all the statements and before recursing into BB's dominator children. 5. It then recurses into all the dominator children of BB. 6. After recursing into all the dominator children of BB it can, optionally, traverse every statement in BB again (i.e., repeating steps 2 and 3). 7. Once after walking the statements in BB and BB's dominator children. At this stage, the block local data stack is popped.  File: gccint.info, Node: Alias analysis, Next: Memory model, Prev: SSA, Up: Tree SSA 13.4 Alias analysis =================== Alias analysis in GIMPLE SSA form consists of two pieces. First the virtual SSA web ties conflicting memory accesses and provides a SSA use-def chain and SSA immediate-use chains for walking possibly dependent memory accesses. Second an alias-oracle can be queried to disambiguate explicit and implicit memory references. 1. Memory SSA form. All statements that may use memory have exactly one accompanied use of a virtual SSA name that represents the state of memory at the given point in the IL. All statements that may define memory have exactly one accompanied definition of a virtual SSA name using the previous state of memory and defining the new state of memory after the given point in the IL. int i; int foo (void) { # .MEM_3 = VDEF <.MEM_2(D)> i = 1; # VUSE <.MEM_3> return i; } The virtual SSA names in this case are ‘.MEM_2(D)’ and ‘.MEM_3’. The store to the global variable ‘i’ defines ‘.MEM_3’ invalidating ‘.MEM_2(D)’. The load from ‘i’ uses that new state ‘.MEM_3’. The virtual SSA web serves as constraints to SSA optimizers preventing illegitimate code-motion and optimization. It also provides a way to walk related memory statements. 2. Points-to and escape analysis. Points-to analysis builds a set of constraints from the GIMPLE SSA IL representing all pointer operations and facts we do or do not know about pointers. Solving this set of constraints yields a conservatively correct solution for each pointer variable in the program (though we are only interested in SSA name pointers) as to what it may possibly point to. This points-to solution for a given SSA name pointer is stored in the ‘pt_solution’ sub-structure of the ‘SSA_NAME_PTR_INFO’ record. The following accessor functions are available: • ‘pt_solution_includes’ • ‘pt_solutions_intersect’ Points-to analysis also computes the solution for two special set of pointers, ‘ESCAPED’ and ‘CALLUSED’. Those represent all memory that has escaped the scope of analysis or that is used by pure or nested const calls. 3. Type-based alias analysis Type-based alias analysis is frontend dependent though generic support is provided by the middle-end in ‘alias.cc’. TBAA code is used by both tree optimizers and RTL optimizers. Every language that wishes to perform language-specific alias analysis should define a function that computes, given a ‘tree’ node, an alias set for the node. Nodes in different alias sets are not allowed to alias. For an example, see the C front-end function ‘c_get_alias_set’. 4. Tree alias-oracle The tree alias-oracle provides means to disambiguate two memory references and memory references against statements. The following queries are available: • ‘refs_may_alias_p’ • ‘ref_maybe_used_by_stmt_p’ • ‘stmt_may_clobber_ref_p’ In addition to those two kind of statement walkers are available walking statements related to a reference ref. ‘walk_non_aliased_vuses’ walks over dominating memory defining statements and calls back if the statement does not clobber ref providing the non-aliased VUSE. The walk stops at the first clobbering statement or if asked to. ‘walk_aliased_vdefs’ walks over dominating memory defining statements and calls back on each statement clobbering ref providing its aliasing VDEF. The walk stops if asked to.  File: gccint.info, Node: Memory model, Prev: Alias analysis, Up: Tree SSA 13.5 Memory model ================= The memory model used by the middle-end models that of the C/C++ languages. The middle-end has the notion of an effective type of a memory region which is used for type-based alias analysis. The following is a refinement of ISO C99 6.5/6, clarifying the block copy case to follow common sense and extending the concept of a dynamic effective type to objects with a declared type as required for C++. The effective type of an object for an access to its stored value is the declared type of the object or the effective type determined by a previous store to it. If a value is stored into an object through an lvalue having a type that is not a character type, then the type of the lvalue becomes the effective type of the object for that access and for subsequent accesses that do not modify the stored value. If a value is copied into an object using memcpy or memmove, or is copied as an array of character type, then the effective type of the modified object for that access and for subsequent accesses that do not modify the value is undetermined. For all other accesses to an object, the effective type of the object is simply the type of the lvalue used for the access.  File: gccint.info, Node: RTL, Next: Control Flow, Prev: Tree SSA, Up: Top 14 RTL Representation ********************* The last part of the compiler work is done on a low-level intermediate representation called Register Transfer Language. In this language, the instructions to be output are described, pretty much one by one, in an algebraic form that describes what the instruction does. RTL is inspired by Lisp lists. It has both an internal form, made up of structures that point at other structures, and a textual form that is used in the machine description and in printed debugging dumps. The textual form uses nested parentheses to indicate the pointers in the internal form. * Menu: * RTL Objects:: Expressions vs vectors vs strings vs integers. * RTL Classes:: Categories of RTL expression objects, and their structure. * Accessors:: Macros to access expression operands or vector elts. * Special Accessors:: Macros to access specific annotations on RTL. * Flags:: Other flags in an RTL expression. * Machine Modes:: Describing the size and format of a datum. * Constants:: Expressions with constant values. * Regs and Memory:: Expressions representing register contents or memory. * Arithmetic:: Expressions representing arithmetic on other expressions. * Comparisons:: Expressions representing comparison of expressions. * Bit-Fields:: Expressions representing bit-fields in memory or reg. * Vector Operations:: Expressions involving vector datatypes. * Conversions:: Extending, truncating, floating or fixing. * RTL Declarations:: Declaring volatility, constancy, etc. * Side Effects:: Expressions for storing in registers, etc. * Incdec:: Embedded side-effects for autoincrement addressing. * Assembler:: Representing ‘asm’ with operands. * Debug Information:: Expressions representing debugging information. * Insns:: Expression types for entire insns. * Calls:: RTL representation of function call insns. * RTL SSA:: An on-the-side SSA form for RTL * Sharing:: Some expressions are unique; others *must* be copied. * Reading RTL:: Reading textual RTL from a file.  File: gccint.info, Node: RTL Objects, Next: RTL Classes, Up: RTL 14.1 RTL Object Types ===================== RTL uses five kinds of objects: expressions, integers, wide integers, strings and vectors. Expressions are the most important ones. An RTL expression ("RTX", for short) is a C structure, but it is usually referred to with a pointer; a type that is given the typedef name ‘rtx’. An integer is simply an ‘int’; their written form uses decimal digits. A wide integer is an integral object whose type is ‘HOST_WIDE_INT’; their written form uses decimal digits. A string is a sequence of characters. In core it is represented as a ‘char *’ in usual C fashion, and it is written in C syntax as well. However, strings in RTL may never be null. If you write an empty string in a machine description, it is represented in core as a null pointer rather than as a pointer to a null character. In certain contexts, these null pointers instead of strings are valid. Within RTL code, strings are most commonly found inside ‘symbol_ref’ expressions, but they appear in other contexts in the RTL expressions that make up machine descriptions. In a machine description, strings are normally written with double quotes, as you would in C. However, strings in machine descriptions may extend over many lines, which is invalid C, and adjacent string constants are not concatenated as they are in C. Any string constant may be surrounded with a single set of parentheses. Sometimes this makes the machine description easier to read. There is also a special syntax for strings, which can be useful when C code is embedded in a machine description. Wherever a string can appear, it is also valid to write a C-style brace block. The entire brace block, including the outermost pair of braces, is considered to be the string constant. Double quote characters inside the braces are not special. Therefore, if you write string constants in the C code, you need not escape each quote character with a backslash. A vector contains an arbitrary number of pointers to expressions. The number of elements in the vector is explicitly present in the vector. The written form of a vector consists of square brackets (‘[...]’) surrounding the elements, in sequence and with whitespace separating them. Vectors of length zero are not created; null pointers are used instead. Expressions are classified by “expression codes” (also called RTX codes). The expression code is a name defined in ‘rtl.def’, which is also (in uppercase) a C enumeration constant. The possible expression codes and their meanings are machine-independent. The code of an RTX can be extracted with the macro ‘GET_CODE (X)’ and altered with ‘PUT_CODE (X, NEWCODE)’. The expression code determines how many operands the expression contains, and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell by looking at an operand what kind of object it is. Instead, you must know from its context--from the expression code of the containing expression. For example, in an expression of code ‘subreg’, the first operand is to be regarded as an expression and the second operand as a polynomial integer. In an expression of code ‘plus’, there are two operands, both of which are to be regarded as expressions. In a ‘symbol_ref’ expression, there is one operand, which is to be regarded as a string. Expressions are written as parentheses containing the name of the expression type, its flags and machine mode if any, and then the operands of the expression (separated by spaces). Expression code names in the ‘md’ file are written in lowercase, but when they appear in C code they are written in uppercase. In this manual, they are shown as follows: ‘const_int’. In a few contexts a null pointer is valid where an expression is normally wanted. The written form of this is ‘(nil)’.  File: gccint.info, Node: RTL Classes, Next: Accessors, Prev: RTL Objects, Up: RTL 14.2 RTL Classes and Formats ============================ The various expression codes are divided into several “classes”, which are represented by single characters. You can determine the class of an RTX code with the macro ‘GET_RTX_CLASS (CODE)’. Currently, ‘rtl.def’ defines these classes: ‘RTX_OBJ’ An RTX code that represents an actual object, such as a register (‘REG’) or a memory location (‘MEM’, ‘SYMBOL_REF’). ‘LO_SUM’ is also included; instead, ‘SUBREG’ and ‘STRICT_LOW_PART’ are not in this class, but in class ‘RTX_EXTRA’. ‘RTX_CONST_OBJ’ An RTX code that represents a constant object. ‘HIGH’ is also included in this class. ‘RTX_COMPARE’ An RTX code for a non-symmetric comparison, such as ‘GEU’ or ‘LT’. ‘RTX_COMM_COMPARE’ An RTX code for a symmetric (commutative) comparison, such as ‘EQ’ or ‘ORDERED’. ‘RTX_UNARY’ An RTX code for a unary arithmetic operation, such as ‘NEG’, ‘NOT’, or ‘ABS’. This category also includes value extension (sign or zero) and conversions between integer and floating point. ‘RTX_COMM_ARITH’ An RTX code for a commutative binary operation, such as ‘PLUS’ or ‘AND’. ‘NE’ and ‘EQ’ are comparisons, so they have class ‘RTX_COMM_COMPARE’. ‘RTX_BIN_ARITH’ An RTX code for a non-commutative binary operation, such as ‘MINUS’, ‘DIV’, or ‘ASHIFTRT’. ‘RTX_BITFIELD_OPS’ An RTX code for a bit-field operation. Currently only ‘ZERO_EXTRACT’ and ‘SIGN_EXTRACT’. These have three inputs and are lvalues (so they can be used for insertion as well). *Note Bit-Fields::. ‘RTX_TERNARY’ An RTX code for other three input operations. Currently only ‘IF_THEN_ELSE’, ‘VEC_MERGE’, ‘SIGN_EXTRACT’, ‘ZERO_EXTRACT’, and ‘FMA’. ‘RTX_INSN’ An RTX code for an entire instruction: ‘INSN’, ‘JUMP_INSN’, and ‘CALL_INSN’. *Note Insns::. ‘RTX_MATCH’ An RTX code for something that matches in insns, such as ‘MATCH_DUP’. These only occur in machine descriptions. ‘RTX_AUTOINC’ An RTX code for an auto-increment addressing mode, such as ‘POST_INC’. ‘XEXP (X, 0)’ gives the auto-modified register. ‘RTX_EXTRA’ All other RTX codes. This category includes the remaining codes used only in machine descriptions (‘DEFINE_*’, etc.). It also includes all the codes describing side effects (‘SET’, ‘USE’, ‘CLOBBER’, etc.) and the non-insns that may appear on an insn chain, such as ‘NOTE’, ‘BARRIER’, and ‘CODE_LABEL’. ‘SUBREG’ is also part of this class. For each expression code, ‘rtl.def’ specifies the number of contained objects and their kinds using a sequence of characters called the “format” of the expression code. For example, the format of ‘subreg’ is ‘ep’. These are the most commonly used format characters: ‘e’ An expression (actually a pointer to an expression). ‘i’ An integer. ‘w’ A wide integer. ‘s’ A string. ‘E’ A vector of expressions. A few other format characters are used occasionally: ‘u’ ‘u’ is equivalent to ‘e’ except that it is printed differently in debugging dumps. It is used for pointers to insns. ‘n’ ‘n’ is equivalent to ‘i’ except that it is printed differently in debugging dumps. It is used for the line number or code number of a ‘note’ insn. ‘S’ ‘S’ indicates a string which is optional. In the RTL objects in core, ‘S’ is equivalent to ‘s’, but when the object is read, from an ‘md’ file, the string value of this operand may be omitted. An omitted string is taken to be the null string. ‘V’ ‘V’ indicates a vector which is optional. In the RTL objects in core, ‘V’ is equivalent to ‘E’, but when the object is read from an ‘md’ file, the vector value of this operand may be omitted. An omitted vector is effectively the same as a vector of no elements. ‘B’ ‘B’ indicates a pointer to basic block structure. ‘p’ A polynomial integer. At present this is used only for ‘SUBREG_BYTE’. ‘0’ ‘0’ means a slot whose contents do not fit any normal category. ‘0’ slots are not printed at all in dumps, and are often used in special ways by small parts of the compiler. There are macros to get the number of operands and the format of an expression code: ‘GET_RTX_LENGTH (CODE)’ Number of operands of an RTX of code CODE. ‘GET_RTX_FORMAT (CODE)’ The format of an RTX of code CODE, as a C string. Some classes of RTX codes always have the same format. For example, it is safe to assume that all comparison operations have format ‘ee’. ‘RTX_UNARY’ All codes of this class have format ‘e’. ‘RTX_BIN_ARITH’ ‘RTX_COMM_ARITH’ ‘RTX_COMM_COMPARE’ ‘RTX_COMPARE’ All codes of these classes have format ‘ee’. ‘RTX_BITFIELD_OPS’ ‘RTX_TERNARY’ All codes of these classes have format ‘eee’. ‘RTX_INSN’ All codes of this class have formats that begin with ‘iuueiee’. *Note Insns::. Note that not all RTL objects linked onto an insn chain are of class ‘RTX_INSN’. ‘RTX_CONST_OBJ’ ‘RTX_OBJ’ ‘RTX_MATCH’ ‘RTX_EXTRA’ You can make no assumptions about the format of these codes.  File: gccint.info, Node: Accessors, Next: Special Accessors, Prev: RTL Classes, Up: RTL 14.3 Access to Operands ======================= Operands of expressions are accessed using the macros ‘XEXP’, ‘XINT’, ‘XWINT’ and ‘XSTR’. Each of these macros takes two arguments: an expression-pointer (RTX) and an operand number (counting from zero). Thus, XEXP (X, 2) accesses operand 2 of expression X, as an expression. XINT (X, 2) accesses the same operand as an integer. ‘XSTR’, used in the same fashion, would access it as a string. Any operand can be accessed as an integer, as an expression or as a string. You must choose the correct method of access for the kind of value actually stored in the operand. You would do this based on the expression code of the containing expression. That is also how you would know how many operands there are. For example, if X is an ‘int_list’ expression, you know that it has two operands which can be correctly accessed as ‘XINT (X, 0)’ and ‘XEXP (X, 1)’. Incorrect accesses like ‘XEXP (X, 0)’ and ‘XINT (X, 1)’ would compile, but would trigger an internal compiler error when rtl checking is enabled. Nothing stops you from writing ‘XEXP (X, 28)’ either, but this will access memory past the end of the expression with unpredictable results. Access to operands which are vectors is more complicated. You can use the macro ‘XVEC’ to get the vector-pointer itself, or the macros ‘XVECEXP’ and ‘XVECLEN’ to access the elements and length of a vector. ‘XVEC (EXP, IDX)’ Access the vector-pointer which is operand number IDX in EXP. ‘XVECLEN (EXP, IDX)’ Access the length (number of elements) in the vector which is in operand number IDX in EXP. This value is an ‘int’. ‘XVECEXP (EXP, IDX, ELTNUM)’ Access element number ELTNUM in the vector which is in operand number IDX in EXP. This value is an RTX. It is up to you to make sure that ELTNUM is not negative and is less than ‘XVECLEN (EXP, IDX)’. All the macros defined in this section expand into lvalues and therefore can be used to assign the operands, lengths and vector elements as well as to access them.  File: gccint.info, Node: Special Accessors, Next: Flags, Prev: Accessors, Up: RTL 14.4 Access to Special Operands =============================== Some RTL nodes have special annotations associated with them. ‘MEM’ ‘MEM_ALIAS_SET (X)’ If 0, X is not in any alias set, and may alias anything. Otherwise, X can only alias ‘MEM’s in a conflicting alias set. This value is set in a language-dependent manner in the front-end, and should not be altered in the back-end. In some front-ends, these numbers may correspond in some way to types, or other language-level entities, but they need not, and the back-end makes no such assumptions. These set numbers are tested with ‘alias_sets_conflict_p’. ‘MEM_EXPR (X)’ If this register is known to hold the value of some user-level declaration, this is that tree node. It may also be a ‘COMPONENT_REF’, in which case this is some field reference, and ‘TREE_OPERAND (X, 0)’ contains the declaration, or another ‘COMPONENT_REF’, or null if there is no compile-time object associated with the reference. ‘MEM_OFFSET_KNOWN_P (X)’ True if the offset of the memory reference from ‘MEM_EXPR’ is known. ‘MEM_OFFSET (X)’ provides the offset if so. ‘MEM_OFFSET (X)’ The offset from the start of ‘MEM_EXPR’. The value is only valid if ‘MEM_OFFSET_KNOWN_P (X)’ is true. ‘MEM_SIZE_KNOWN_P (X)’ True if the size of the memory reference is known. ‘MEM_SIZE (X)’ provides its size if so. ‘MEM_SIZE (X)’ The size in bytes of the memory reference. This is mostly relevant for ‘BLKmode’ references as otherwise the size is implied by the mode. The value is only valid if ‘MEM_SIZE_KNOWN_P (X)’ is true. ‘MEM_ALIGN (X)’ The known alignment in bits of the memory reference. ‘MEM_ADDR_SPACE (X)’ The address space of the memory reference. This will commonly be zero for the generic address space. ‘REG’ ‘ORIGINAL_REGNO (X)’ This field holds the number the register "originally" had; for a pseudo register turned into a hard reg this will hold the old pseudo register number. ‘REG_EXPR (X)’ If this register is known to hold the value of some user-level declaration, this is that tree node. ‘REG_OFFSET (X)’ If this register is known to hold the value of some user-level declaration, this is the offset into that logical storage. ‘SYMBOL_REF’ ‘SYMBOL_REF_DECL (X)’ If the ‘symbol_ref’ X was created for a ‘VAR_DECL’ or a ‘FUNCTION_DECL’, that tree is recorded here. If this value is null, then X was created by back end code generation routines, and there is no associated front end symbol table entry. ‘SYMBOL_REF_DECL’ may also point to a tree of class ‘'c'’, that is, some sort of constant. In this case, the ‘symbol_ref’ is an entry in the per-file constant pool; again, there is no associated front end symbol table entry. ‘SYMBOL_REF_CONSTANT (X)’ If ‘CONSTANT_POOL_ADDRESS_P (X)’ is true, this is the constant pool entry for X. It is null otherwise. ‘SYMBOL_REF_DATA (X)’ A field of opaque type used to store ‘SYMBOL_REF_DECL’ or ‘SYMBOL_REF_CONSTANT’. ‘SYMBOL_REF_FLAGS (X)’ In a ‘symbol_ref’, this is used to communicate various predicates about the symbol. Some of these are common enough to be computed by common code, some are specific to the target. The common bits are: ‘SYMBOL_FLAG_FUNCTION’ Set if the symbol refers to a function. ‘SYMBOL_FLAG_LOCAL’ Set if the symbol is local to this "module". See ‘TARGET_BINDS_LOCAL_P’. ‘SYMBOL_FLAG_EXTERNAL’ Set if this symbol is not defined in this translation unit. Note that this is not the inverse of ‘SYMBOL_FLAG_LOCAL’. ‘SYMBOL_FLAG_SMALL’ Set if the symbol is located in the small data section. See ‘TARGET_IN_SMALL_DATA_P’. ‘SYMBOL_REF_TLS_MODEL (X)’ This is a multi-bit field accessor that returns the ‘tls_model’ to be used for a thread-local storage symbol. It returns zero for non-thread-local symbols. ‘SYMBOL_FLAG_HAS_BLOCK_INFO’ Set if the symbol has ‘SYMBOL_REF_BLOCK’ and ‘SYMBOL_REF_BLOCK_OFFSET’ fields. ‘SYMBOL_FLAG_ANCHOR’ Set if the symbol is used as a section anchor. "Section anchors" are symbols that have a known position within an ‘object_block’ and that can be used to access nearby members of that block. They are used to implement ‘-fsection-anchors’. If this flag is set, then ‘SYMBOL_FLAG_HAS_BLOCK_INFO’ will be too. Bits beginning with ‘SYMBOL_FLAG_MACH_DEP’ are available for the target's use. ‘SYMBOL_REF_BLOCK (X)’ If ‘SYMBOL_REF_HAS_BLOCK_INFO_P (X)’, this is the ‘object_block’ structure to which the symbol belongs, or ‘NULL’ if it has not been assigned a block. ‘SYMBOL_REF_BLOCK_OFFSET (X)’ If ‘SYMBOL_REF_HAS_BLOCK_INFO_P (X)’, this is the offset of X from the first object in ‘SYMBOL_REF_BLOCK (X)’. The value is negative if X has not yet been assigned to a block, or it has not been given an offset within that block.  File: gccint.info, Node: Flags, Next: Machine Modes, Prev: Special Accessors, Up: RTL 14.5 Flags in an RTL Expression =============================== RTL expressions contain several flags (one-bit bit-fields) that are used in certain types of expression. Most often they are accessed with the following macros, which expand into lvalues. ‘CROSSING_JUMP_P (X)’ Nonzero in a ‘jump_insn’ if it crosses between hot and cold sections, which could potentially be very far apart in the executable. The presence of this flag indicates to other optimizations that this branching instruction should not be "collapsed" into a simpler branching construct. It is used when the optimization to partition basic blocks into hot and cold sections is turned on. ‘CONSTANT_POOL_ADDRESS_P (X)’ Nonzero in a ‘symbol_ref’ if it refers to part of the current function's constant pool. For most targets these addresses are in a ‘.rodata’ section entirely separate from the function, but for some targets the addresses are close to the beginning of the function. In either case GCC assumes these addresses can be addressed directly, perhaps with the help of base registers. Stored in the ‘unchanging’ field and printed as ‘/u’. ‘INSN_ANNULLED_BRANCH_P (X)’ In a ‘jump_insn’, ‘call_insn’, or ‘insn’ indicates that the branch is an annulling one. See the discussion under ‘sequence’ below. Stored in the ‘unchanging’ field and printed as ‘/u’. ‘INSN_DELETED_P (X)’ In an ‘insn’, ‘call_insn’, ‘jump_insn’, ‘code_label’, ‘jump_table_data’, ‘barrier’, or ‘note’, nonzero if the insn has been deleted. Stored in the ‘volatil’ field and printed as ‘/v’. ‘INSN_FROM_TARGET_P (X)’ In an ‘insn’ or ‘jump_insn’ or ‘call_insn’ in a delay slot of a branch, indicates that the insn is from the target of the branch. If the branch insn has ‘INSN_ANNULLED_BRANCH_P’ set, this insn will only be executed if the branch is taken. For annulled branches with ‘INSN_FROM_TARGET_P’ clear, the insn will be executed only if the branch is not taken. When ‘INSN_ANNULLED_BRANCH_P’ is not set, this insn will always be executed. Stored in the ‘in_struct’ field and printed as ‘/s’. ‘LABEL_PRESERVE_P (X)’ In a ‘code_label’ or ‘note’, indicates that the label is referenced by code or data not visible to the RTL of a given function. Labels referenced by a non-local goto will have this bit set. Stored in the ‘in_struct’ field and printed as ‘/s’. ‘LABEL_REF_NONLOCAL_P (X)’ In ‘label_ref’ and ‘reg_label’ expressions, nonzero if this is a reference to a non-local label. Stored in the ‘volatil’ field and printed as ‘/v’. ‘MEM_KEEP_ALIAS_SET_P (X)’ In ‘mem’ expressions, 1 if we should keep the alias set for this mem unchanged when we access a component. Set to 1, for example, when we are already in a non-addressable component of an aggregate. Stored in the ‘jump’ field and printed as ‘/j’. ‘MEM_VOLATILE_P (X)’ In ‘mem’, ‘asm_operands’, and ‘asm_input’ expressions, nonzero for volatile memory references. Stored in the ‘volatil’ field and printed as ‘/v’. ‘MEM_NOTRAP_P (X)’ In ‘mem’, nonzero for memory references that will not trap. Stored in the ‘call’ field and printed as ‘/c’. ‘MEM_POINTER (X)’ Nonzero in a ‘mem’ if the memory reference holds a pointer. Stored in the ‘frame_related’ field and printed as ‘/f’. ‘MEM_READONLY_P (X)’ Nonzero in a ‘mem’, if the memory is statically allocated and read-only. Read-only in this context means never modified during the lifetime of the program, not necessarily in ROM or in write-disabled pages. A common example of the later is a shared library's global offset table. This table is initialized by the runtime loader, so the memory is technically writable, but after control is transferred from the runtime loader to the application, this memory will never be subsequently modified. Stored in the ‘unchanging’ field and printed as ‘/u’. ‘PREFETCH_SCHEDULE_BARRIER_P (X)’ In a ‘prefetch’, indicates that the prefetch is a scheduling barrier. No other INSNs will be moved over it. Stored in the ‘volatil’ field and printed as ‘/v’. ‘REG_FUNCTION_VALUE_P (X)’ Nonzero in a ‘reg’ if it is the place in which this function's value is going to be returned. (This happens only in a hard register.) Stored in the ‘return_val’ field and printed as ‘/i’. ‘REG_POINTER (X)’ Nonzero in a ‘reg’ if the register holds a pointer. Stored in the ‘frame_related’ field and printed as ‘/f’. ‘REG_USERVAR_P (X)’ In a ‘reg’, nonzero if it corresponds to a variable present in the user's source code. Zero for temporaries generated internally by the compiler. Stored in the ‘volatil’ field and printed as ‘/v’. The same hard register may be used also for collecting the values of functions called by this one, but ‘REG_FUNCTION_VALUE_P’ is zero in this kind of use. ‘RTL_CONST_CALL_P (X)’ In a ‘call_insn’ indicates that the insn represents a call to a const function. Stored in the ‘unchanging’ field and printed as ‘/u’. ‘RTL_PURE_CALL_P (X)’ In a ‘call_insn’ indicates that the insn represents a call to a pure function. Stored in the ‘return_val’ field and printed as ‘/i’. ‘RTL_CONST_OR_PURE_CALL_P (X)’ In a ‘call_insn’, true if ‘RTL_CONST_CALL_P’ or ‘RTL_PURE_CALL_P’ is true. ‘RTL_LOOPING_CONST_OR_PURE_CALL_P (X)’ In a ‘call_insn’ indicates that the insn represents a possibly infinite looping call to a const or pure function. Stored in the ‘call’ field and printed as ‘/c’. Only true if one of ‘RTL_CONST_CALL_P’ or ‘RTL_PURE_CALL_P’ is true. ‘RTX_FRAME_RELATED_P (X)’ Nonzero in an ‘insn’, ‘call_insn’, ‘jump_insn’, ‘barrier’, or ‘set’ which is part of a function prologue and sets the stack pointer, sets the frame pointer, or saves a register. This flag should also be set on an instruction that sets up a temporary register to use in place of the frame pointer. Stored in the ‘frame_related’ field and printed as ‘/f’. In particular, on RISC targets where there are limits on the sizes of immediate constants, it is sometimes impossible to reach the register save area directly from the stack pointer. In that case, a temporary register is used that is near enough to the register save area, and the Canonical Frame Address, i.e., DWARF2's logical frame pointer, register must (temporarily) be changed to be this temporary register. So, the instruction that sets this temporary register must be marked as ‘RTX_FRAME_RELATED_P’. If the marked instruction is overly complex (defined in terms of what ‘dwarf2out_frame_debug_expr’ can handle), you will also have to create a ‘REG_FRAME_RELATED_EXPR’ note and attach it to the instruction. This note should contain a simple expression of the computation performed by this instruction, i.e., one that ‘dwarf2out_frame_debug_expr’ can handle. This flag is required for exception handling support on targets with RTL prologues. ‘SCHED_GROUP_P (X)’ During instruction scheduling, in an ‘insn’, ‘call_insn’, ‘jump_insn’ or ‘jump_table_data’, indicates that the previous insn must be scheduled together with this insn. This is used to ensure that certain groups of instructions will not be split up by the instruction scheduling pass, for example, ‘use’ insns before a ‘call_insn’ may not be separated from the ‘call_insn’. Stored in the ‘in_struct’ field and printed as ‘/s’. ‘SET_IS_RETURN_P (X)’ For a ‘set’, nonzero if it is for a return. Stored in the ‘jump’ field and printed as ‘/j’. ‘SIBLING_CALL_P (X)’ For a ‘call_insn’, nonzero if the insn is a sibling call. Stored in the ‘jump’ field and printed as ‘/j’. ‘STRING_POOL_ADDRESS_P (X)’ For a ‘symbol_ref’ expression, nonzero if it addresses this function's string constant pool. Stored in the ‘frame_related’ field and printed as ‘/f’. ‘SUBREG_PROMOTED_UNSIGNED_P (X)’ Returns a value greater then zero for a ‘subreg’ that has ‘SUBREG_PROMOTED_VAR_P’ nonzero if the object being referenced is kept zero-extended, zero if it is kept sign-extended, and less then zero if it is extended some other way via the ‘ptr_extend’ instruction. Stored in the ‘unchanging’ field and ‘volatil’ field, printed as ‘/u’ and ‘/v’. This macro may only be used to get the value it may not be used to change the value. Use ‘SUBREG_PROMOTED_UNSIGNED_SET’ to change the value. ‘SUBREG_PROMOTED_UNSIGNED_SET (X)’ Set the ‘unchanging’ and ‘volatil’ fields in a ‘subreg’ to reflect zero, sign, or other extension. If ‘volatil’ is zero, then ‘unchanging’ as nonzero means zero extension and as zero means sign extension. If ‘volatil’ is nonzero then some other type of extension was done via the ‘ptr_extend’ instruction. ‘SUBREG_PROMOTED_VAR_P (X)’ Nonzero in a ‘subreg’ if it was made when accessing an object that was promoted to a wider mode in accord with the ‘PROMOTED_MODE’ machine description macro (*note Storage Layout::). In this case, the mode of the ‘subreg’ is the declared mode of the object and the mode of ‘SUBREG_REG’ is the mode of the register that holds the object. Promoted variables are always either sign- or zero-extended to the wider mode on every assignment. Stored in the ‘in_struct’ field and printed as ‘/s’. ‘SYMBOL_REF_USED (X)’ In a ‘symbol_ref’, indicates that X has been used. This is normally only used to ensure that X is only declared external once. Stored in the ‘used’ field. ‘SYMBOL_REF_WEAK (X)’ In a ‘symbol_ref’, indicates that X has been declared weak. Stored in the ‘return_val’ field and printed as ‘/i’. ‘SYMBOL_REF_FLAG (X)’ In a ‘symbol_ref’, this is used as a flag for machine-specific purposes. Stored in the ‘volatil’ field and printed as ‘/v’. Most uses of ‘SYMBOL_REF_FLAG’ are historic and may be subsumed by ‘SYMBOL_REF_FLAGS’. Certainly use of ‘SYMBOL_REF_FLAGS’ is mandatory if the target requires more than one bit of storage. These are the fields to which the above macros refer: ‘call’ In a ‘mem’, 1 means that the memory reference will not trap. In a ‘call’, 1 means that this pure or const call may possibly infinite loop. In an RTL dump, this flag is represented as ‘/c’. ‘frame_related’ In an ‘insn’ or ‘set’ expression, 1 means that it is part of a function prologue and sets the stack pointer, sets the frame pointer, saves a register, or sets up a temporary register to use in place of the frame pointer. In ‘reg’ expressions, 1 means that the register holds a pointer. In ‘mem’ expressions, 1 means that the memory reference holds a pointer. In ‘symbol_ref’ expressions, 1 means that the reference addresses this function's string constant pool. In an RTL dump, this flag is represented as ‘/f’. ‘in_struct’ In ‘reg’ expressions, it is 1 if the register has its entire life contained within the test expression of some loop. In ‘subreg’ expressions, 1 means that the ‘subreg’ is accessing an object that has had its mode promoted from a wider mode. In ‘label_ref’ expressions, 1 means that the referenced label is outside the innermost loop containing the insn in which the ‘label_ref’ was found. In ‘code_label’ expressions, it is 1 if the label may never be deleted. This is used for labels which are the target of non-local gotos. Such a label that would have been deleted is replaced with a ‘note’ of type ‘NOTE_INSN_DELETED_LABEL’. In an ‘insn’ during dead-code elimination, 1 means that the insn is dead code. In an ‘insn’ or ‘jump_insn’ during reorg for an insn in the delay slot of a branch, 1 means that this insn is from the target of the branch. In an ‘insn’ during instruction scheduling, 1 means that this insn must be scheduled as part of a group together with the previous insn. In an RTL dump, this flag is represented as ‘/s’. ‘return_val’ In ‘reg’ expressions, 1 means the register contains the value to be returned by the current function. On machines that pass parameters in registers, the same register number may be used for parameters as well, but this flag is not set on such uses. In ‘symbol_ref’ expressions, 1 means the referenced symbol is weak. In ‘call’ expressions, 1 means the call is pure. In an RTL dump, this flag is represented as ‘/i’. ‘jump’ In a ‘mem’ expression, 1 means we should keep the alias set for this mem unchanged when we access a component. In a ‘set’, 1 means it is for a return. In a ‘call_insn’, 1 means it is a sibling call. In a ‘jump_insn’, 1 means it is a crossing jump. In an RTL dump, this flag is represented as ‘/j’. ‘unchanging’ In ‘reg’ and ‘mem’ expressions, 1 means that the value of the expression never changes. In ‘subreg’ expressions, it is 1 if the ‘subreg’ references an unsigned object whose mode has been promoted to a wider mode. In an ‘insn’ or ‘jump_insn’ in the delay slot of a branch instruction, 1 means an annulling branch should be used. In a ‘symbol_ref’ expression, 1 means that this symbol addresses something in the per-function constant pool. In a ‘call_insn’ 1 means that this instruction is a call to a const function. In an RTL dump, this flag is represented as ‘/u’. ‘used’ This flag is used directly (without an access macro) at the end of RTL generation for a function, to count the number of times an expression appears in insns. Expressions that appear more than once are copied, according to the rules for shared structure (*note Sharing::). For a ‘reg’, it is used directly (without an access macro) by the leaf register renumbering code to ensure that each register is only renumbered once. In a ‘symbol_ref’, it indicates that an external declaration for the symbol has already been written. ‘volatil’ In a ‘mem’, ‘asm_operands’, or ‘asm_input’ expression, it is 1 if the memory reference is volatile. Volatile memory references may not be deleted, reordered or combined. In a ‘symbol_ref’ expression, it is used for machine-specific purposes. In a ‘reg’ expression, it is 1 if the value is a user-level variable. 0 indicates an internal compiler temporary. In an ‘insn’, 1 means the insn has been deleted. In ‘label_ref’ and ‘reg_label’ expressions, 1 means a reference to a non-local label. In ‘prefetch’ expressions, 1 means that the containing insn is a scheduling barrier. In an RTL dump, this flag is represented as ‘/v’.  File: gccint.info, Node: Machine Modes, Next: Constants, Prev: Flags, Up: RTL 14.6 Machine Modes ================== A machine mode describes a size of data object and the representation used for it. In the C code, machine modes are represented by an enumeration type, ‘machine_mode’, defined in ‘machmode.def’. Each RTL expression has room for a machine mode and so do certain kinds of tree expressions (declarations and types, to be precise). In debugging dumps and machine descriptions, the machine mode of an RTL expression is written after the expression code with a colon to separate them. The letters ‘mode’ which appear at the end of each machine mode name are omitted. For example, ‘(reg:SI 38)’ is a ‘reg’ expression with machine mode ‘SImode’. If the mode is ‘VOIDmode’, it is not written at all. Here is a table of machine modes. The term "byte" below refers to an object of ‘BITS_PER_UNIT’ bits (*note Storage Layout::). ‘BImode’ "Bit" mode represents a single bit, for predicate registers. ‘QImode’ "Quarter-Integer" mode represents a single byte treated as an integer. ‘HImode’ "Half-Integer" mode represents a two-byte integer. ‘PSImode’ "Partial Single Integer" mode represents an integer which occupies four bytes but which doesn't really use all four. On some machines, this is the right mode to use for pointers. ‘SImode’ "Single Integer" mode represents a four-byte integer. ‘PDImode’ "Partial Double Integer" mode represents an integer which occupies eight bytes but which doesn't really use all eight. On some machines, this is the right mode to use for certain pointers. ‘DImode’ "Double Integer" mode represents an eight-byte integer. ‘TImode’ "Tetra Integer" (?) mode represents a sixteen-byte integer. ‘OImode’ "Octa Integer" (?) mode represents a thirty-two-byte integer. ‘XImode’ "Hexadeca Integer" (?) mode represents a sixty-four-byte integer. ‘QFmode’ "Quarter-Floating" mode represents a quarter-precision (single byte) floating point number. ‘HFmode’ "Half-Floating" mode represents a half-precision (two byte) floating point number. ‘TQFmode’ "Three-Quarter-Floating" (?) mode represents a three-quarter-precision (three byte) floating point number. ‘SFmode’ "Single Floating" mode represents a four byte floating point number. In the common case, of a processor with IEEE arithmetic and 8-bit bytes, this is a single-precision IEEE floating point number; it can also be used for double-precision (on processors with 16-bit bytes) and single-precision VAX and IBM types. ‘DFmode’ "Double Floating" mode represents an eight byte floating point number. In the common case, of a processor with IEEE arithmetic and 8-bit bytes, this is a double-precision IEEE floating point number. ‘XFmode’ "Extended Floating" mode represents an IEEE extended floating point number. This mode only has 80 meaningful bits (ten bytes). Some processors require such numbers to be padded to twelve bytes, others to sixteen; this mode is used for either. ‘SDmode’ "Single Decimal Floating" mode represents a four byte decimal floating point number (as distinct from conventional binary floating point). ‘DDmode’ "Double Decimal Floating" mode represents an eight byte decimal floating point number. ‘TDmode’ "Tetra Decimal Floating" mode represents a sixteen byte decimal floating point number all 128 of whose bits are meaningful. ‘TFmode’ "Tetra Floating" mode represents a sixteen byte floating point number all 128 of whose bits are meaningful. One common use is the IEEE quad-precision format. ‘QQmode’ "Quarter-Fractional" mode represents a single byte treated as a signed fractional number. The default format is "s.7". ‘HQmode’ "Half-Fractional" mode represents a two-byte signed fractional number. The default format is "s.15". ‘SQmode’ "Single Fractional" mode represents a four-byte signed fractional number. The default format is "s.31". ‘DQmode’ "Double Fractional" mode represents an eight-byte signed fractional number. The default format is "s.63". ‘TQmode’ "Tetra Fractional" mode represents a sixteen-byte signed fractional number. The default format is "s.127". ‘UQQmode’ "Unsigned Quarter-Fractional" mode represents a single byte treated as an unsigned fractional number. The default format is ".8". ‘UHQmode’ "Unsigned Half-Fractional" mode represents a two-byte unsigned fractional number. The default format is ".16". ‘USQmode’ "Unsigned Single Fractional" mode represents a four-byte unsigned fractional number. The default format is ".32". ‘UDQmode’ "Unsigned Double Fractional" mode represents an eight-byte unsigned fractional number. The default format is ".64". ‘UTQmode’ "Unsigned Tetra Fractional" mode represents a sixteen-byte unsigned fractional number. The default format is ".128". ‘HAmode’ "Half-Accumulator" mode represents a two-byte signed accumulator. The default format is "s8.7". ‘SAmode’ "Single Accumulator" mode represents a four-byte signed accumulator. The default format is "s16.15". ‘DAmode’ "Double Accumulator" mode represents an eight-byte signed accumulator. The default format is "s32.31". ‘TAmode’ "Tetra Accumulator" mode represents a sixteen-byte signed accumulator. The default format is "s64.63". ‘UHAmode’ "Unsigned Half-Accumulator" mode represents a two-byte unsigned accumulator. The default format is "8.8". ‘USAmode’ "Unsigned Single Accumulator" mode represents a four-byte unsigned accumulator. The default format is "16.16". ‘UDAmode’ "Unsigned Double Accumulator" mode represents an eight-byte unsigned accumulator. The default format is "32.32". ‘UTAmode’ "Unsigned Tetra Accumulator" mode represents a sixteen-byte unsigned accumulator. The default format is "64.64". ‘CCmode’ "Condition Code" mode represents the value of a condition code, which is a machine-specific set of bits used to represent the result of a comparison operation. Other machine-specific modes may also be used for the condition code. (*note Condition Code::). ‘BLKmode’ "Block" mode represents values that are aggregates to which none of the other modes apply. In RTL, only memory references can have this mode, and only if they appear in string-move or vector instructions. On machines which have no such instructions, ‘BLKmode’ will not appear in RTL. ‘VOIDmode’ Void mode means the absence of a mode or an unspecified mode. For example, RTL expressions of code ‘const_int’ have mode ‘VOIDmode’ because they can be taken to have whatever mode the context requires. In debugging dumps of RTL, ‘VOIDmode’ is expressed by the absence of any mode. ‘QCmode, HCmode, SCmode, DCmode, XCmode, TCmode’ These modes stand for a complex number represented as a pair of floating point values. The floating point values are in ‘QFmode’, ‘HFmode’, ‘SFmode’, ‘DFmode’, ‘XFmode’, and ‘TFmode’, respectively. ‘CQImode, CHImode, CSImode, CDImode, CTImode, COImode, CPSImode’ These modes stand for a complex number represented as a pair of integer values. The integer values are in ‘QImode’, ‘HImode’, ‘SImode’, ‘DImode’, ‘TImode’, ‘OImode’, and ‘PSImode’, respectively. ‘BND32mode BND64mode’ These modes stand for bounds for pointer of 32 and 64 bit size respectively. Mode size is double pointer mode size. The machine description defines ‘Pmode’ as a C macro which expands into the machine mode used for addresses. Normally this is the mode whose size is ‘BITS_PER_WORD’, ‘SImode’ on 32-bit machines. The only modes which a machine description must support are ‘QImode’, and the modes corresponding to ‘BITS_PER_WORD’, ‘FLOAT_TYPE_SIZE’ and ‘DOUBLE_TYPE_SIZE’. The compiler will attempt to use ‘DImode’ for 8-byte structures and unions, but this can be prevented by overriding the definition of ‘MAX_FIXED_MODE_SIZE’. Alternatively, you can have the compiler use ‘TImode’ for 16-byte structures and unions. Likewise, you can arrange for the C type ‘short int’ to avoid using ‘HImode’. Very few explicit references to machine modes remain in the compiler and these few references will soon be removed. Instead, the machine modes are divided into mode classes. These are represented by the enumeration type ‘enum mode_class’ defined in ‘machmode.h’. The possible mode classes are: ‘MODE_INT’ Integer modes. By default these are ‘BImode’, ‘QImode’, ‘HImode’, ‘SImode’, ‘DImode’, ‘TImode’, and ‘OImode’. ‘MODE_PARTIAL_INT’ The "partial integer" modes, ‘PQImode’, ‘PHImode’, ‘PSImode’ and ‘PDImode’. ‘MODE_FLOAT’ Floating point modes. By default these are ‘QFmode’, ‘HFmode’, ‘TQFmode’, ‘SFmode’, ‘DFmode’, ‘XFmode’ and ‘TFmode’. ‘MODE_DECIMAL_FLOAT’ Decimal floating point modes. By default these are ‘SDmode’, ‘DDmode’ and ‘TDmode’. ‘MODE_FRACT’ Signed fractional modes. By default these are ‘QQmode’, ‘HQmode’, ‘SQmode’, ‘DQmode’ and ‘TQmode’. ‘MODE_UFRACT’ Unsigned fractional modes. By default these are ‘UQQmode’, ‘UHQmode’, ‘USQmode’, ‘UDQmode’ and ‘UTQmode’. ‘MODE_ACCUM’ Signed accumulator modes. By default these are ‘HAmode’, ‘SAmode’, ‘DAmode’ and ‘TAmode’. ‘MODE_UACCUM’ Unsigned accumulator modes. By default these are ‘UHAmode’, ‘USAmode’, ‘UDAmode’ and ‘UTAmode’. ‘MODE_COMPLEX_INT’ Complex integer modes. (These are not currently implemented). ‘MODE_COMPLEX_FLOAT’ Complex floating point modes. By default these are ‘QCmode’, ‘HCmode’, ‘SCmode’, ‘DCmode’, ‘XCmode’, and ‘TCmode’. ‘MODE_CC’ Modes representing condition code values. These are ‘CCmode’ plus any ‘CC_MODE’ modes listed in the ‘MACHINE-modes.def’. *Note Jump Patterns::, also see *note Condition Code::. ‘MODE_POINTER_BOUNDS’ Pointer bounds modes. Used to represent values of pointer bounds type. Operations in these modes may be executed as NOPs depending on hardware features and environment setup. ‘MODE_OPAQUE’ This is a mode class for modes that don't want to provide operations other than register moves, memory moves, loads, stores, and ‘unspec’s. They have a size and precision and that's all. ‘MODE_RANDOM’ This is a catchall mode class for modes which don't fit into the above classes. Currently ‘VOIDmode’ and ‘BLKmode’ are in ‘MODE_RANDOM’. ‘machmode.h’ also defines various wrapper classes that combine a ‘machine_mode’ with a static assertion that a particular condition holds. The classes are: ‘scalar_int_mode’ A mode that has class ‘MODE_INT’ or ‘MODE_PARTIAL_INT’. ‘scalar_float_mode’ A mode that has class ‘MODE_FLOAT’ or ‘MODE_DECIMAL_FLOAT’. ‘scalar_mode’ A mode that holds a single numerical value. In practice this means that the mode is a ‘scalar_int_mode’, is a ‘scalar_float_mode’, or has class ‘MODE_FRACT’, ‘MODE_UFRACT’, ‘MODE_ACCUM’, ‘MODE_UACCUM’ or ‘MODE_POINTER_BOUNDS’. ‘complex_mode’ A mode that has class ‘MODE_COMPLEX_INT’ or ‘MODE_COMPLEX_FLOAT’. ‘fixed_size_mode’ A mode whose size is known at compile time. Named modes use the most constrained of the available wrapper classes, if one exists, otherwise they use ‘machine_mode’. For example, ‘QImode’ is a ‘scalar_int_mode’, ‘SFmode’ is a ‘scalar_float_mode’ and ‘BLKmode’ is a plain ‘machine_mode’. It is possible to refer to any mode as a raw ‘machine_mode’ by adding the ‘E_’ prefix, where ‘E’ stands for "enumeration". For example, the raw ‘machine_mode’ names of the modes just mentioned are ‘E_QImode’, ‘E_SFmode’ and ‘E_BLKmode’ respectively. The wrapper classes implicitly convert to ‘machine_mode’ and to any wrapper class that represents a more general condition; for example ‘scalar_int_mode’ and ‘scalar_float_mode’ both convert to ‘scalar_mode’ and all three convert to ‘fixed_size_mode’. The classes act like ‘machine_mode’s that accept only certain named modes. ‘machmode.h’ also defines a template class ‘opt_mode’ that holds a ‘T’ or nothing, where ‘T’ can be either ‘machine_mode’ or one of the wrapper classes above. The main operations on an ‘opt_mode’ X are as follows: ‘X.exists ()’ Return true if X holds a mode rather than nothing. ‘X.exists (&Y)’ Return true if X holds a mode rather than nothing, storing the mode in Y if so. Y must be assignment-compatible with T. ‘X.require ()’ Assert that X holds a mode rather than nothing and return that mode. ‘X = Y’ Set X to Y, where Y is a T or implicitly converts to a T. The default constructor sets an ‘opt_mode’ to nothing. There is also a constructor that takes an initial value of type T. It is possible to use the ‘is-a.h’ accessors on a ‘machine_mode’ or machine mode wrapper X: ‘is_a (X)’ Return true if X meets the conditions for wrapper class T. ‘is_a (X, &Y)’ Return true if X meets the conditions for wrapper class T, storing it in Y if so. Y must be assignment-compatible with T. ‘as_a (X)’ Assert that X meets the conditions for wrapper class T and return it as a T. ‘dyn_cast (X)’ Return an ‘opt_mode’ that holds X if X meets the conditions for wrapper class T and that holds nothing otherwise. The purpose of these wrapper classes is to give stronger static type checking. For example, if a function takes a ‘scalar_int_mode’, a caller that has a general ‘machine_mode’ must either check or assert that the code is indeed a scalar integer first, using one of the functions above. The wrapper classes are normal C++ classes, with user-defined constructors. Sometimes it is useful to have a POD version of the same type, particularly if the type appears in a ‘union’. The template class ‘pod_mode’ provides a POD version of wrapper class T. It is assignment-compatible with T and implicitly converts to both ‘machine_mode’ and T. Here are some C macros that relate to machine modes: ‘GET_MODE (X)’ Returns the machine mode of the RTX X. ‘PUT_MODE (X, NEWMODE)’ Alters the machine mode of the RTX X to be NEWMODE. ‘NUM_MACHINE_MODES’ Stands for the number of machine modes available on the target machine. This is one greater than the largest numeric value of any machine mode. ‘GET_MODE_NAME (M)’ Returns the name of mode M as a string. ‘GET_MODE_CLASS (M)’ Returns the mode class of mode M. ‘GET_MODE_WIDER_MODE (M)’ Returns the next wider natural mode. For example, the expression ‘GET_MODE_WIDER_MODE (QImode)’ returns ‘HImode’. ‘GET_MODE_SIZE (M)’ Returns the size in bytes of a datum of mode M. ‘GET_MODE_BITSIZE (M)’ Returns the size in bits of a datum of mode M. ‘GET_MODE_IBIT (M)’ Returns the number of integral bits of a datum of fixed-point mode M. ‘GET_MODE_FBIT (M)’ Returns the number of fractional bits of a datum of fixed-point mode M. ‘GET_MODE_MASK (M)’ Returns a bitmask containing 1 for all bits in a word that fit within mode M. This macro can only be used for modes whose bitsize is less than or equal to ‘HOST_BITS_PER_INT’. ‘GET_MODE_ALIGNMENT (M)’ Return the required alignment, in bits, for an object of mode M. ‘GET_MODE_UNIT_SIZE (M)’ Returns the size in bytes of the subunits of a datum of mode M. This is the same as ‘GET_MODE_SIZE’ except in the case of complex modes. For them, the unit size is the size of the real or imaginary part. ‘GET_MODE_NUNITS (M)’ Returns the number of units contained in a mode, i.e., ‘GET_MODE_SIZE’ divided by ‘GET_MODE_UNIT_SIZE’. ‘GET_CLASS_NARROWEST_MODE (C)’ Returns the narrowest mode in mode class C. The following 3 variables are defined on every target. They can be used to allocate buffers that are guaranteed to be large enough to hold any value that can be represented on the target. The first two can be overridden by defining them in the target's mode.def file, however, the value must be a constant that can determined very early in the compilation process. The third symbol cannot be overridden. ‘BITS_PER_UNIT’ The number of bits in an addressable storage unit (byte). If you do not define this, the default is 8. ‘MAX_BITSIZE_MODE_ANY_INT’ The maximum bitsize of any mode that is used in integer math. This should be overridden by the target if it uses large integers as containers for larger vectors but otherwise never uses the contents to compute integer values. ‘MAX_BITSIZE_MODE_ANY_MODE’ The bitsize of the largest mode on the target. The default value is the largest mode size given in the mode definition file, which is always correct for targets whose modes have a fixed size. Targets that might increase the size of a mode beyond this default should define ‘MAX_BITSIZE_MODE_ANY_MODE’ to the actual upper limit in ‘MACHINE-modes.def’. The global variables ‘byte_mode’ and ‘word_mode’ contain modes whose classes are ‘MODE_INT’ and whose bitsizes are either ‘BITS_PER_UNIT’ or ‘BITS_PER_WORD’, respectively. On 32-bit machines, these are ‘QImode’ and ‘SImode’, respectively.  File: gccint.info, Node: Constants, Next: Regs and Memory, Prev: Machine Modes, Up: RTL 14.7 Constant Expression Types ============================== The simplest RTL expressions are those that represent constant values. ‘(const_int I)’ This type of expression represents the integer value I. I is customarily accessed with the macro ‘INTVAL’ as in ‘INTVAL (EXP)’, which is equivalent to ‘XWINT (EXP, 0)’. Constants generated for modes with fewer bits than in ‘HOST_WIDE_INT’ must be sign extended to full width (e.g., with ‘gen_int_mode’). For constants for modes with more bits than in ‘HOST_WIDE_INT’ the implied high order bits of that constant are copies of the top bit. Note however that values are neither inherently signed nor inherently unsigned; where necessary, signedness is determined by the rtl operation instead. There is only one expression object for the integer value zero; it is the value of the variable ‘const0_rtx’. Likewise, the only expression for integer value one is found in ‘const1_rtx’, the only expression for integer value two is found in ‘const2_rtx’, and the only expression for integer value negative one is found in ‘constm1_rtx’. Any attempt to create an expression of code ‘const_int’ and value zero, one, two or negative one will return ‘const0_rtx’, ‘const1_rtx’, ‘const2_rtx’ or ‘constm1_rtx’ as appropriate. Similarly, there is only one object for the integer whose value is ‘STORE_FLAG_VALUE’. It is found in ‘const_true_rtx’. If ‘STORE_FLAG_VALUE’ is one, ‘const_true_rtx’ and ‘const1_rtx’ will point to the same object. If ‘STORE_FLAG_VALUE’ is −1, ‘const_true_rtx’ and ‘constm1_rtx’ will point to the same object. ‘(const_double:M I0 I1 ...)’ This represents either a floating-point constant of mode M or (on older ports that do not define ‘TARGET_SUPPORTS_WIDE_INT’) an integer constant too large to fit into ‘HOST_BITS_PER_WIDE_INT’ bits but small enough to fit within twice that number of bits. In the latter case, M will be ‘VOIDmode’. For integral values constants for modes with more bits than twice the number in ‘HOST_WIDE_INT’ the implied high order bits of that constant are copies of the top bit of ‘CONST_DOUBLE_HIGH’. Note however that integral values are neither inherently signed nor inherently unsigned; where necessary, signedness is determined by the rtl operation instead. On more modern ports, ‘CONST_DOUBLE’ only represents floating point values. New ports define ‘TARGET_SUPPORTS_WIDE_INT’ to make this designation. If M is ‘VOIDmode’, the bits of the value are stored in I0 and I1. I0 is customarily accessed with the macro ‘CONST_DOUBLE_LOW’ and I1 with ‘CONST_DOUBLE_HIGH’. If the constant is floating point (regardless of its precision), then the number of integers used to store the value depends on the size of ‘REAL_VALUE_TYPE’ (*note Floating Point::). The integers represent a floating point number, but not precisely in the target machine's or host machine's floating point format. To convert them to the precise bit pattern used by the target machine, use the macro ‘REAL_VALUE_TO_TARGET_DOUBLE’ and friends (*note Data Output::). The host dependency for the number of integers used to store a double value makes it problematic for machine descriptions to use expressions of code ‘const_double’ and therefore a syntactic alias has been provided: (const_double_zero:M) standing for: (const_double:M 0 0 ...) for matching the floating-point value zero, possibly the only useful one. ‘(const_wide_int:M NUNITS ELT0 ...)’ This contains an array of ‘HOST_WIDE_INT’s that is large enough to hold any constant that can be represented on the target. This form of rtl is only used on targets that define ‘TARGET_SUPPORTS_WIDE_INT’ to be nonzero and then ‘CONST_DOUBLE’s are only used to hold floating-point values. If the target leaves ‘TARGET_SUPPORTS_WIDE_INT’ defined as 0, ‘CONST_WIDE_INT’s are not used and ‘CONST_DOUBLE’s are as they were before. The values are stored in a compressed format. The higher-order 0s or -1s are not represented if they are just the logical sign extension of the number that is represented. ‘CONST_WIDE_INT_VEC (CODE)’ Returns the entire array of ‘HOST_WIDE_INT’s that are used to store the value. This macro should be rarely used. ‘CONST_WIDE_INT_NUNITS (CODE)’ The number of ‘HOST_WIDE_INT’s used to represent the number. Note that this generally is smaller than the number of ‘HOST_WIDE_INT’s implied by the mode size. ‘CONST_WIDE_INT_ELT (CODE,I)’ Returns the ‘i’th element of the array. Element 0 is contains the low order bits of the constant. ‘(const_fixed:M ...)’ Represents a fixed-point constant of mode M. The operand is a data structure of type ‘struct fixed_value’ and is accessed with the macro ‘CONST_FIXED_VALUE’. The high part of data is accessed with ‘CONST_FIXED_VALUE_HIGH’; the low part is accessed with ‘CONST_FIXED_VALUE_LOW’. ‘(const_poly_int:M [C0 C1 ...])’ Represents a ‘poly_int’-style polynomial integer with coefficients C0, C1, .... The coefficients are ‘wide_int’-based integers rather than rtxes. ‘CONST_POLY_INT_COEFFS’ gives the values of individual coefficients (which is mostly only useful in low-level routines) and ‘const_poly_int_value’ gives the full ‘poly_int’ value. ‘(const_vector:M [X0 X1 ...])’ Represents a vector constant. The values in square brackets are elements of the vector, which are always ‘const_int’, ‘const_wide_int’, ‘const_double’ or ‘const_fixed’ expressions. Each vector constant V is treated as a specific instance of an arbitrary-length sequence that itself contains ‘CONST_VECTOR_NPATTERNS (V)’ interleaved patterns. Each pattern has the form: { BASE0, BASE1, BASE1 + STEP, BASE1 + STEP * 2, ... } The first three elements in each pattern are enough to determine the values of the other elements. However, if all STEPs are zero, only the first two elements are needed. If in addition each BASE1 is equal to the corresponding BASE0, only the first element in each pattern is needed. The number of determining elements per pattern is given by ‘CONST_VECTOR_NELTS_PER_PATTERN (V)’. For example, the constant: { 0, 1, 2, 6, 3, 8, 4, 10, 5, 12, 6, 14, 7, 16, 8, 18 } is interpreted as an interleaving of the sequences: { 0, 2, 3, 4, 5, 6, 7, 8 } { 1, 6, 8, 10, 12, 14, 16, 18 } where the sequences are represented by the following patterns: BASE0 == 0, BASE1 == 2, STEP == 1 BASE0 == 1, BASE1 == 6, STEP == 2 In this case: CONST_VECTOR_NPATTERNS (V) == 2 CONST_VECTOR_NELTS_PER_PATTERN (V) == 3 Thus the first 6 elements (‘{ 0, 1, 2, 6, 3, 8 }’) are enough to determine the whole sequence; we refer to them as the "encoded" elements. They are the only elements present in the square brackets for variable-length ‘const_vector’s (i.e. for ‘const_vector’s whose mode M has a variable number of elements). However, as a convenience to code that needs to handle both ‘const_vector’s and ‘parallel’s, all elements are present in the square brackets for fixed-length ‘const_vector’s; the encoding scheme simply reduces the amount of work involved in processing constants that follow a regular pattern. Sometimes this scheme can create two possible encodings of the same vector. For example { 0, 1 } could be seen as two patterns with one element each or one pattern with two elements (BASE0 and BASE1). The canonical encoding is always the one with the fewest patterns or (if both encodings have the same number of patterns) the one with the fewest encoded elements. ‘const_vector_encoding_nelts (V)’ gives the total number of encoded elements in V, which is 6 in the example above. ‘CONST_VECTOR_ENCODED_ELT (V, I)’ accesses the value of encoded element I. ‘CONST_VECTOR_DUPLICATE_P (V)’ is true if V simply contains repeated instances of ‘CONST_VECTOR_NPATTERNS (V)’ values. This is a shorthand for testing ‘CONST_VECTOR_NELTS_PER_PATTERN (V) == 1’. ‘CONST_VECTOR_STEPPED_P (V)’ is true if at least one pattern in V has a nonzero step. This is a shorthand for testing ‘CONST_VECTOR_NELTS_PER_PATTERN (V) == 3’. ‘CONST_VECTOR_NUNITS (V)’ gives the total number of elements in V; it is a shorthand for getting the number of units in ‘GET_MODE (V)’. The utility function ‘const_vector_elt’ gives the value of an arbitrary element as an ‘rtx’. ‘const_vector_int_elt’ gives the same value as a ‘wide_int’. ‘(const_string STR)’ Represents a constant string with value STR. Currently this is used only for insn attributes (*note Insn Attributes::) since constant strings in C are placed in memory. ‘(symbol_ref:MODE SYMBOL)’ Represents the value of an assembler label for data. SYMBOL is a string that describes the name of the assembler label. If it starts with a ‘*’, the label is the rest of SYMBOL not including the ‘*’. Otherwise, the label is SYMBOL, usually prefixed with ‘_’. The ‘symbol_ref’ contains a mode, which is usually ‘Pmode’. Usually that is the only mode for which a symbol is directly valid. ‘(label_ref:MODE LABEL)’ Represents the value of an assembler label for code. It contains one operand, an expression, which must be a ‘code_label’ or a ‘note’ of type ‘NOTE_INSN_DELETED_LABEL’ that appears in the instruction sequence to identify the place where the label should go. The reason for using a distinct expression type for code label references is so that jump optimization can distinguish them. The ‘label_ref’ contains a mode, which is usually ‘Pmode’. Usually that is the only mode for which a label is directly valid. ‘(const:M EXP)’ Represents a constant that is the result of an assembly-time arithmetic computation. The operand, EXP, contains only ‘const_int’, ‘symbol_ref’, ‘label_ref’ or ‘unspec’ expressions, combined with ‘plus’ and ‘minus’. Any such ‘unspec’s are target-specific and typically represent some form of relocation operator. M should be a valid address mode. ‘(high:M EXP)’ Represents the high-order bits of EXP. The number of bits is machine-dependent and is normally the number of bits specified in an instruction that initializes the high order bits of a register. It is used with ‘lo_sum’ to represent the typical two-instruction sequence used in RISC machines to reference large immediate values and/or link-time constants such as global memory addresses. In the latter case, M is ‘Pmode’ and EXP is usually a constant expression involving ‘symbol_ref’. The macro ‘CONST0_RTX (MODE)’ refers to an expression with value 0 in mode MODE. If mode MODE is of mode class ‘MODE_INT’, it returns ‘const0_rtx’. If mode MODE is of mode class ‘MODE_FLOAT’, it returns a ‘CONST_DOUBLE’ expression in mode MODE. Otherwise, it returns a ‘CONST_VECTOR’ expression in mode MODE. Similarly, the macro ‘CONST1_RTX (MODE)’ refers to an expression with value 1 in mode MODE and similarly for ‘CONST2_RTX’. The ‘CONST1_RTX’ and ‘CONST2_RTX’ macros are undefined for vector modes.  File: gccint.info, Node: Regs and Memory, Next: Arithmetic, Prev: Constants, Up: RTL 14.8 Registers and Memory ========================= Here are the RTL expression types for describing access to machine registers and to main memory. ‘(reg:M N)’ For small values of the integer N (those that are less than ‘FIRST_PSEUDO_REGISTER’), this stands for a reference to machine register number N: a “hard register”. For larger values of N, it stands for a temporary value or “pseudo register”. The compiler's strategy is to generate code assuming an unlimited number of such pseudo registers, and later convert them into hard registers or into memory references. M is the machine mode of the reference. It is necessary because machines can generally refer to each register in more than one mode. For example, a register may contain a full word but there may be instructions to refer to it as a half word or as a single byte, as well as instructions to refer to it as a floating point number of various precisions. Even for a register that the machine can access in only one mode, the mode must always be specified. The symbol ‘FIRST_PSEUDO_REGISTER’ is defined by the machine description, since the number of hard registers on the machine is an invariant characteristic of the machine. Note, however, that not all of the machine registers must be general registers. All the machine registers that can be used for storage of data are given hard register numbers, even those that can be used only in certain instructions or can hold only certain types of data. A hard register may be accessed in various modes throughout one function, but each pseudo register is given a natural mode and is accessed only in that mode. When it is necessary to describe an access to a pseudo register using a nonnatural mode, a ‘subreg’ expression is used. A ‘reg’ expression with a machine mode that specifies more than one word of data may actually stand for several consecutive registers. If in addition the register number specifies a hardware register, then it actually represents several consecutive hardware registers starting with the specified one. Each pseudo register number used in a function's RTL code is represented by a unique ‘reg’ expression. Some pseudo register numbers, those within the range of ‘FIRST_VIRTUAL_REGISTER’ to ‘LAST_VIRTUAL_REGISTER’ only appear during the RTL generation phase and are eliminated before the optimization phases. These represent locations in the stack frame that cannot be determined until RTL generation for the function has been completed. The following virtual register numbers are defined: ‘VIRTUAL_INCOMING_ARGS_REGNUM’ This points to the first word of the incoming arguments passed on the stack. Normally these arguments are placed there by the caller, but the callee may have pushed some arguments that were previously passed in registers. When RTL generation is complete, this virtual register is replaced by the sum of the register given by ‘ARG_POINTER_REGNUM’ and the value of ‘FIRST_PARM_OFFSET’. ‘VIRTUAL_STACK_VARS_REGNUM’ If ‘FRAME_GROWS_DOWNWARD’ is defined to a nonzero value, this points to immediately above the first variable on the stack. Otherwise, it points to the first variable on the stack. ‘VIRTUAL_STACK_VARS_REGNUM’ is replaced with the sum of the register given by ‘FRAME_POINTER_REGNUM’ and the value ‘TARGET_STARTING_FRAME_OFFSET’. ‘VIRTUAL_STACK_DYNAMIC_REGNUM’ This points to the location of dynamically allocated memory on the stack immediately after the stack pointer has been adjusted by the amount of memory desired. This virtual register is replaced by the sum of the register given by ‘STACK_POINTER_REGNUM’ and the value ‘STACK_DYNAMIC_OFFSET’. ‘VIRTUAL_OUTGOING_ARGS_REGNUM’ This points to the location in the stack at which outgoing arguments should be written when the stack is pre-pushed (arguments pushed using push insns should always use ‘STACK_POINTER_REGNUM’). This virtual register is replaced by the sum of the register given by ‘STACK_POINTER_REGNUM’ and the value ‘STACK_POINTER_OFFSET’. ‘(subreg:M1 REG:M2 BYTENUM)’ ‘subreg’ expressions are used to refer to a register in a machine mode other than its natural one, or to refer to one register of a multi-part ‘reg’ that actually refers to several registers. Each pseudo register has a natural mode. If it is necessary to operate on it in a different mode, the register must be enclosed in a ‘subreg’. There are currently three supported types for the first operand of a ‘subreg’: • pseudo registers This is the most common case. Most ‘subreg’s have pseudo ‘reg’s as their first operand. • mem ‘subreg’s of ‘mem’ were common in earlier versions of GCC and are still supported. During the reload pass these are replaced by plain ‘mem’s. On machines that do not do instruction scheduling, use of ‘subreg’s of ‘mem’ are still used, but this is no longer recommended. Such ‘subreg’s are considered to be ‘register_operand’s rather than ‘memory_operand’s before and during reload. Because of this, the scheduling passes cannot properly schedule instructions with ‘subreg’s of ‘mem’, so for machines that do scheduling, ‘subreg’s of ‘mem’ should never be used. To support this, the combine and recog passes have explicit code to inhibit the creation of ‘subreg’s of ‘mem’ when ‘INSN_SCHEDULING’ is defined. The use of ‘subreg’s of ‘mem’ after the reload pass is an area that is not well understood and should be avoided. There is still some code in the compiler to support this, but this code has possibly rotted. This use of ‘subreg’s is discouraged and will most likely not be supported in the future. • hard registers It is seldom necessary to wrap hard registers in ‘subreg’s; such registers would normally reduce to a single ‘reg’ rtx. This use of ‘subreg’s is discouraged and may not be supported in the future. ‘subreg’s of ‘subreg’s are not supported. Using ‘simplify_gen_subreg’ is the recommended way to avoid this problem. ‘subreg’s come in two distinct flavors, each having its own usage and rules: Paradoxical subregs When M1 is strictly wider than M2, the ‘subreg’ expression is called “paradoxical”. The canonical test for this class of ‘subreg’ is: paradoxical_subreg_p (M1, M2) Paradoxical ‘subreg’s can be used as both lvalues and rvalues. When used as an lvalue, the low-order bits of the source value are stored in REG and the high-order bits are discarded. When used as an rvalue, the low-order bits of the ‘subreg’ are taken from REG while the high-order bits may or may not be defined. The high-order bits of rvalues are defined in the following circumstances: • ‘subreg’s of ‘mem’ When M2 is smaller than a word, the macro ‘LOAD_EXTEND_OP’, can control how the high-order bits are defined. • ‘subreg’ of ‘reg’s The upper bits are defined when ‘SUBREG_PROMOTED_VAR_P’ is true. ‘SUBREG_PROMOTED_UNSIGNED_P’ describes what the upper bits hold. Such subregs usually represent local variables, register variables and parameter pseudo variables that have been promoted to a wider mode. BYTENUM is always zero for a paradoxical ‘subreg’, even on big-endian targets. For example, the paradoxical ‘subreg’: (set (subreg:SI (reg:HI X) 0) Y) stores the lower 2 bytes of Y in X and discards the upper 2 bytes. A subsequent: (set Z (subreg:SI (reg:HI X) 0)) would set the lower two bytes of Z to Y and set the upper two bytes to an unknown value assuming ‘SUBREG_PROMOTED_VAR_P’ is false. Normal subregs When M1 is at least as narrow as M2 the ‘subreg’ expression is called “normal”. Normal ‘subreg’s restrict consideration to certain bits of REG. For this purpose, REG is divided into individually-addressable blocks in which each block has: REGMODE_NATURAL_SIZE (M2) bytes. Usually the value is ‘UNITS_PER_WORD’; that is, most targets usually treat each word of a register as being independently addressable. There are two types of normal ‘subreg’. If M1 is known to be no bigger than a block, the ‘subreg’ refers to the least-significant part (or “lowpart”) of one block of REG. If M1 is known to be larger than a block, the ‘subreg’ refers to two or more complete blocks. When used as an lvalue, ‘subreg’ is a block-based accessor. Storing to a ‘subreg’ modifies all the blocks of REG that overlap the ‘subreg’, but it leaves the other blocks of REG alone. When storing to a normal ‘subreg’ that is smaller than a block, the other bits of the referenced block are usually left in an undefined state. This laxity makes it easier to generate efficient code for such instructions. To represent an instruction that preserves all the bits outside of those in the ‘subreg’, use ‘strict_low_part’ or ‘zero_extract’ around the ‘subreg’. BYTENUM must identify the offset of the first byte of the ‘subreg’ from the start of REG, assuming that REG is laid out in memory order. The memory order of bytes is defined by two target macros, ‘WORDS_BIG_ENDIAN’ and ‘BYTES_BIG_ENDIAN’: • ‘WORDS_BIG_ENDIAN’, if set to 1, says that byte number zero is part of the most significant word; otherwise, it is part of the least significant word. • ‘BYTES_BIG_ENDIAN’, if set to 1, says that byte number zero is the most significant byte within a word; otherwise, it is the least significant byte within a word. On a few targets, ‘FLOAT_WORDS_BIG_ENDIAN’ disagrees with ‘WORDS_BIG_ENDIAN’. However, most parts of the compiler treat floating point values as if they had the same endianness as integer values. This works because they handle them solely as a collection of integer values, with no particular numerical value. Only real.cc and the runtime libraries care about ‘FLOAT_WORDS_BIG_ENDIAN’. Thus, (subreg:HI (reg:SI X) 2) on a ‘BYTES_BIG_ENDIAN’, ‘UNITS_PER_WORD == 4’ target is the same as (subreg:HI (reg:SI X) 0) on a little-endian, ‘UNITS_PER_WORD == 4’ target. Both ‘subreg’s access the lower two bytes of register X. Note that the byte offset is a polynomial integer; it may not be a compile-time constant on targets with variable-sized modes. However, the restrictions above mean that there are only a certain set of acceptable offsets for a given combination of M1 and M2. The compiler can always tell which blocks a valid subreg occupies, and whether the subreg is a lowpart of a block. A ‘MODE_PARTIAL_INT’ mode behaves as if it were as wide as the corresponding ‘MODE_INT’ mode, except that it has a number of undefined bits, which are determined by the precision of the mode. For example, on a little-endian target which defines ‘PSImode’ to have a precision of 20 bits: (subreg:PSI (reg:SI 0) 0) accesses the low 20 bits of ‘(reg:SI 0)’. Continuing with a ‘PSImode’ precision of 20 bits, if we assume ‘REGMODE_NATURAL_SIZE (DImode) <= 4’, then the following two ‘subreg’s: (subreg:PSI (reg:DI 0) 0) (subreg:PSI (reg:DI 0) 4) represent accesses to the low 20 bits of the two halves of ‘(reg:DI 0)’. If ‘REGMODE_NATURAL_SIZE (PSImode) <= 2’ then these two ‘subreg’s: (subreg:HI (reg:PSI 0) 0) (subreg:HI (reg:PSI 0) 2) represent independent 2-byte accesses that together span the whole of ‘(reg:PSI 0)’. Storing to the first ‘subreg’ does not affect the value of the second, and vice versa, so the assignment: (set (subreg:HI (reg:PSI 0) 0) (reg:HI 4)) sets the low 16 bits of ‘(reg:PSI 0)’ to ‘(reg:HI 4)’, and the high 4 defined bits of ‘(reg:PSI 0)’ retain their original value. The behavior here is the same as for normal ‘subreg’s, when there are no ‘MODE_PARTIAL_INT’ modes involved. The rules above apply to both pseudo REGs and hard REGs. If the semantics are not correct for particular combinations of M1, M2 and hard REG, the target-specific code must ensure that those combinations are never used. For example: TARGET_CAN_CHANGE_MODE_CLASS (M2, M1, CLASS) must be false for every class CLASS that includes REG. GCC must be able to determine at compile time whether a subreg is paradoxical, whether it occupies a whole number of blocks, or whether it is a lowpart of a block. This means that certain combinations of variable-sized mode are not permitted. For example, if M2 holds N ‘SI’ values, where N is greater than zero, it is not possible to form a ‘DI’ ‘subreg’ of it; such a ‘subreg’ would be paradoxical when N is 1 but not when N is greater than 1. The first operand of a ‘subreg’ expression is customarily accessed with the ‘SUBREG_REG’ macro and the second operand is customarily accessed with the ‘SUBREG_BYTE’ macro. It has been several years since a platform in which ‘BYTES_BIG_ENDIAN’ not equal to ‘WORDS_BIG_ENDIAN’ has been tested. Anyone wishing to support such a platform in the future may be confronted with code rot. ‘(scratch:M)’ This represents a scratch register that will be required for the execution of a single instruction and not used subsequently. It is converted into a ‘reg’ by either the local register allocator or the reload pass. ‘scratch’ is usually present inside a ‘clobber’ operation (*note Side Effects::). On some machines, the condition code register is given a register number and a ‘reg’ is used. Other machines store condition codes in general registers; in such cases a pseudo register should be used. Some machines, such as the SPARC and RS/6000, have two sets of arithmetic instructions, one that sets and one that does not set the condition code. This is best handled by normally generating the instruction that does not set the condition code, and making a pattern that both performs the arithmetic and sets the condition code register. For examples, search for ‘addcc’ and ‘andcc’ in ‘sparc.md’. ‘(pc)’ This represents the machine's program counter. It has no operands and may not have a machine mode. ‘(pc)’ may be validly used only in certain specific contexts in jump instructions. There is only one expression object of code ‘pc’; it is the value of the variable ‘pc_rtx’. Any attempt to create an expression of code ‘pc’ will return ‘pc_rtx’. All instructions that do not jump alter the program counter implicitly by incrementing it, but there is no need to mention this in the RTL. ‘(mem:M ADDR ALIAS)’ This RTX represents a reference to main memory at an address represented by the expression ADDR. M specifies how large a unit of memory is accessed. ALIAS specifies an alias set for the reference. In general two items are in different alias sets if they cannot reference the same memory address. The construct ‘(mem:BLK (scratch))’ is considered to alias all other memories. Thus it may be used as a memory barrier in epilogue stack deallocation patterns. ‘(concatM RTX RTX)’ This RTX represents the concatenation of two other RTXs. This is used for complex values. It should only appear in the RTL attached to declarations and during RTL generation. It should not appear in the ordinary insn chain. ‘(concatnM [RTX ...])’ This RTX represents the concatenation of all the RTX to make a single value. Like ‘concat’, this should only appear in declarations, and not in the insn chain.  File: gccint.info, Node: Arithmetic, Next: Comparisons, Prev: Regs and Memory, Up: RTL 14.9 RTL Expressions for Arithmetic =================================== Unless otherwise specified, all the operands of arithmetic expressions must be valid for mode M. An operand is valid for mode M if it has mode M, or if it is a ‘const_int’ or ‘const_double’ and M is a mode of class ‘MODE_INT’. For commutative binary operations, constants should be placed in the second operand. ‘(plus:M X Y)’ ‘(ss_plus:M X Y)’ ‘(us_plus:M X Y)’ These three expressions all represent the sum of the values represented by X and Y carried out in machine mode M. They differ in their behavior on overflow of integer modes. ‘plus’ wraps round modulo the width of M; ‘ss_plus’ saturates at the maximum signed value representable in M; ‘us_plus’ saturates at the maximum unsigned value. ‘(lo_sum:M X Y)’ This expression represents the sum of X and the low-order bits of Y. It is used with ‘high’ (*note Constants::) to represent the typical two-instruction sequence used in RISC machines to reference large immediate values and/or link-time constants such as global memory addresses. In the latter case, M is ‘Pmode’ and Y is usually a constant expression involving ‘symbol_ref’. The number of low order bits is machine-dependent but is normally the number of bits in mode M minus the number of bits set by ‘high’. ‘(minus:M X Y)’ ‘(ss_minus:M X Y)’ ‘(us_minus:M X Y)’ These three expressions represent the result of subtracting Y from X, carried out in mode M. Behavior on overflow is the same as for the three variants of ‘plus’ (see above). ‘(compare:M X Y)’ Represents the result of subtracting Y from X for purposes of comparison. The result is computed without overflow, as if with infinite precision. Of course, machines cannot really subtract with infinite precision. However, they can pretend to do so when only the sign of the result will be used, which is the case when the result is stored in the condition code. And that is the _only_ way this kind of expression may validly be used: as a value to be stored in the condition codes, in a register. *Note Comparisons::. The mode M is not related to the modes of X and Y, but instead is the mode of the condition code value. It is some mode in class ‘MODE_CC’, often ‘CCmode’. *Note Condition Code::. If M is ‘CCmode’, the operation returns sufficient information (in an unspecified format) so that any comparison operator can be applied to the result of the ‘COMPARE’ operation. For other modes in class ‘MODE_CC’, the operation only returns a subset of this information. Normally, X and Y must have the same mode. Otherwise, ‘compare’ is valid only if the mode of X is in class ‘MODE_INT’ and Y is a ‘const_int’ or ‘const_double’ with mode ‘VOIDmode’. The mode of X determines what mode the comparison is to be done in; thus it must not be ‘VOIDmode’. If one of the operands is a constant, it should be placed in the second operand and the comparison code adjusted as appropriate. A ‘compare’ specifying two ‘VOIDmode’ constants is not valid since there is no way to know in what mode the comparison is to be performed; the comparison must either be folded during the compilation or the first operand must be loaded into a register while its mode is still known. ‘(neg:M X)’ ‘(ss_neg:M X)’ ‘(us_neg:M X)’ These two expressions represent the negation (subtraction from zero) of the value represented by X, carried out in mode M. They differ in the behavior on overflow of integer modes. In the case of ‘neg’, the negation of the operand may be a number not representable in mode M, in which case it is truncated to M. ‘ss_neg’ and ‘us_neg’ ensure that an out-of-bounds result saturates to the maximum or minimum signed or unsigned value. ‘(mult:M X Y)’ ‘(ss_mult:M X Y)’ ‘(us_mult:M X Y)’ Represents the signed product of the values represented by X and Y carried out in machine mode M. ‘ss_mult’ and ‘us_mult’ ensure that an out-of-bounds result saturates to the maximum or minimum signed or unsigned value. Some machines support a multiplication that generates a product wider than the operands. Write the pattern for this as (mult:M (sign_extend:M X) (sign_extend:M Y)) where M is wider than the modes of X and Y, which need not be the same. For unsigned widening multiplication, use the same idiom, but with ‘zero_extend’ instead of ‘sign_extend’. ‘(smul_highpart:M X Y)’ ‘(umul_highpart:M X Y)’ Represents the high-part multiplication of X and Y carried out in machine mode M. ‘smul_highpart’ returns the high part of a signed multiplication, ‘umul_highpart’ returns the high part of an unsigned multiplication. ‘(fma:M X Y Z)’ Represents the ‘fma’, ‘fmaf’, and ‘fmal’ builtin functions, which compute ‘X * Y + Z’ without doing an intermediate rounding step. ‘(div:M X Y)’ ‘(ss_div:M X Y)’ Represents the quotient in signed division of X by Y, carried out in machine mode M. If M is a floating point mode, it represents the exact quotient; otherwise, the integerized quotient. ‘ss_div’ ensures that an out-of-bounds result saturates to the maximum or minimum signed value. Some machines have division instructions in which the operands and quotient widths are not all the same; you should represent such instructions using ‘truncate’ and ‘sign_extend’ as in, (truncate:M1 (div:M2 X (sign_extend:M2 Y))) ‘(udiv:M X Y)’ ‘(us_div:M X Y)’ Like ‘div’ but represents unsigned division. ‘us_div’ ensures that an out-of-bounds result saturates to the maximum or minimum unsigned value. ‘(mod:M X Y)’ ‘(umod:M X Y)’ Like ‘div’ and ‘udiv’ but represent the remainder instead of the quotient. ‘(smin:M X Y)’ ‘(smax:M X Y)’ Represents the smaller (for ‘smin’) or larger (for ‘smax’) of X and Y, interpreted as signed values in mode M. When used with floating point, if both operands are zeros, or if either operand is ‘NaN’, then it is unspecified which of the two operands is returned as the result. ‘(umin:M X Y)’ ‘(umax:M X Y)’ Like ‘smin’ and ‘smax’, but the values are interpreted as unsigned integers. ‘(not:M X)’ Represents the bitwise complement of the value represented by X, carried out in mode M, which must be a fixed-point machine mode. ‘(and:M X Y)’ Represents the bitwise logical-and of the values represented by X and Y, carried out in machine mode M, which must be a fixed-point machine mode. ‘(ior:M X Y)’ Represents the bitwise inclusive-or of the values represented by X and Y, carried out in machine mode M, which must be a fixed-point mode. ‘(xor:M X Y)’ Represents the bitwise exclusive-or of the values represented by X and Y, carried out in machine mode M, which must be a fixed-point mode. ‘(ashift:M X C)’ ‘(ss_ashift:M X C)’ ‘(us_ashift:M X C)’ These three expressions represent the result of arithmetically shifting X left by C places. They differ in their behavior on overflow of integer modes. An ‘ashift’ operation is a plain shift with no special behavior in case of a change in the sign bit; ‘ss_ashift’ and ‘us_ashift’ saturates to the minimum or maximum representable value if any of the bits shifted out differs from the final sign bit. X have mode M, a fixed-point machine mode. C be a fixed-point mode or be a constant with mode ‘VOIDmode’; which mode is determined by the mode called for in the machine description entry for the left-shift instruction. For example, on the VAX, the mode of C is ‘QImode’ regardless of M. ‘(lshiftrt:M X C)’ ‘(ashiftrt:M X C)’ Like ‘ashift’ but for right shift. Unlike the case for left shift, these two operations are distinct. ‘(rotate:M X C)’ ‘(rotatert:M X C)’ Similar but represent left and right rotate. If C is a constant, use ‘rotate’. ‘(abs:M X)’ ‘(ss_abs:M X)’ Represents the absolute value of X, computed in mode M. ‘ss_abs’ ensures that an out-of-bounds result saturates to the maximum signed value. ‘(sqrt:M X)’ Represents the square root of X, computed in mode M. Most often M will be a floating point mode. ‘(ffs:M X)’ Represents one plus the index of the least significant 1-bit in X, represented as an integer of mode M. (The value is zero if X is zero.) The mode of X must be M or ‘VOIDmode’. ‘(clrsb:M X)’ Represents the number of redundant leading sign bits in X, represented as an integer of mode M, starting at the most significant bit position. This is one less than the number of leading sign bits (either 0 or 1), with no special cases. The mode of X must be M or ‘VOIDmode’. ‘(clz:M X)’ Represents the number of leading 0-bits in X, represented as an integer of mode M, starting at the most significant bit position. If X is zero, the value is determined by ‘CLZ_DEFINED_VALUE_AT_ZERO’ (*note Misc::). Note that this is one of the few expressions that is not invariant under widening. The mode of X must be M or ‘VOIDmode’. ‘(ctz:M X)’ Represents the number of trailing 0-bits in X, represented as an integer of mode M, starting at the least significant bit position. If X is zero, the value is determined by ‘CTZ_DEFINED_VALUE_AT_ZERO’ (*note Misc::). Except for this case, ‘ctz(x)’ is equivalent to ‘ffs(X) - 1’. The mode of X must be M or ‘VOIDmode’. ‘(popcount:M X)’ Represents the number of 1-bits in X, represented as an integer of mode M. The mode of X must be M or ‘VOIDmode’. ‘(parity:M X)’ Represents the number of 1-bits modulo 2 in X, represented as an integer of mode M. The mode of X must be M or ‘VOIDmode’. ‘(bswap:M X)’ Represents the value X with the order of bytes reversed, carried out in mode M, which must be a fixed-point machine mode. The mode of X must be M or ‘VOIDmode’. ‘(bitreverse:M X)’ Represents the value X with the order of bits reversed, carried out in mode M, which must be a fixed-point machine mode. The mode of X must be M or ‘VOIDmode’. ‘(copysign:M X Y)’ Represents the value X with the sign of Y. Both X and Y must have floating point machine mode M.  File: gccint.info, Node: Comparisons, Next: Bit-Fields, Prev: Arithmetic, Up: RTL 14.10 Comparison Operations =========================== Comparison operators test a relation on two operands and are considered to represent a machine-dependent nonzero value described by, but not necessarily equal to, ‘STORE_FLAG_VALUE’ (*note Misc::) if the relation holds, or zero if it does not, for comparison operators whose results have a 'MODE_INT' mode, ‘FLOAT_STORE_FLAG_VALUE’ (*note Misc::) if the relation holds, or zero if it does not, for comparison operators that return floating-point values, and a vector of either ‘VECTOR_STORE_FLAG_VALUE’ (*note Misc::) if the relation holds, or of zeros if it does not, for comparison operators that return vector results. The mode of the comparison operation is independent of the mode of the data being compared. If the comparison operation is being tested (e.g., the first operand of an ‘if_then_else’), the mode must be ‘VOIDmode’. A comparison operation compares two data objects. The mode of the comparison is determined by the operands; they must both be valid for a common machine mode. A comparison with both operands constant would be invalid as the machine mode could not be deduced from it, but such a comparison should never exist in RTL due to constant folding. Usually only one style of comparisons is supported on a particular machine, but the combine pass will try to merge operations to produce code like ‘(eq X Y)’, in case it exists in the context of the particular insn involved. Inequality comparisons come in two flavors, signed and unsigned. Thus, there are distinct expression codes ‘gt’ and ‘gtu’ for signed and unsigned greater-than. These can produce different results for the same pair of integer values: for example, 1 is signed greater-than −1 but not unsigned greater-than, because −1 when regarded as unsigned is actually ‘0xffffffff’ which is greater than 1. The signed comparisons are also used for floating point values. Floating point comparisons are distinguished by the machine modes of the operands. ‘(eq:M X Y)’ ‘STORE_FLAG_VALUE’ if the values represented by X and Y are equal, otherwise 0. ‘(ne:M X Y)’ ‘STORE_FLAG_VALUE’ if the values represented by X and Y are not equal, otherwise 0. ‘(gt:M X Y)’ ‘STORE_FLAG_VALUE’ if the X is greater than Y. If they are fixed-point, the comparison is done in a signed sense. ‘(gtu:M X Y)’ Like ‘gt’ but does unsigned comparison, on fixed-point numbers only. ‘(lt:M X Y)’ ‘(ltu:M X Y)’ Like ‘gt’ and ‘gtu’ but test for "less than". ‘(ge:M X Y)’ ‘(geu:M X Y)’ Like ‘gt’ and ‘gtu’ but test for "greater than or equal". ‘(le:M X Y)’ ‘(leu:M X Y)’ Like ‘gt’ and ‘gtu’ but test for "less than or equal". ‘(if_then_else COND THEN ELSE)’ This is not a comparison operation but is listed here because it is always used in conjunction with a comparison operation. To be precise, COND is a comparison expression. This expression represents a choice, according to COND, between the value represented by THEN and the one represented by ELSE. On most machines, ‘if_then_else’ expressions are valid only to express conditional jumps. ‘(cond [TEST1 VALUE1 TEST2 VALUE2 ...] DEFAULT)’ Similar to ‘if_then_else’, but more general. Each of TEST1, TEST2, ... is performed in turn. The result of this expression is the VALUE corresponding to the first nonzero test, or DEFAULT if none of the tests are nonzero expressions. This is currently not valid for instruction patterns and is supported only for insn attributes. *Note Insn Attributes::.  File: gccint.info, Node: Bit-Fields, Next: Vector Operations, Prev: Comparisons, Up: RTL 14.11 Bit-Fields ================ Special expression codes exist to represent bit-field instructions. ‘(sign_extract:M LOC SIZE POS)’ This represents a reference to a sign-extended bit-field contained or starting in LOC (a memory or register reference). The bit-field is SIZE bits wide and starts at bit POS. The compilation option ‘BITS_BIG_ENDIAN’ says which end of the memory unit POS counts from. If LOC is in memory, its mode must be a single-byte integer mode. If LOC is in a register, the mode to use is specified by the operand of the ‘insv’ or ‘extv’ pattern (*note Standard Names::) and is usually a full-word integer mode, which is the default if none is specified. The mode of POS is machine-specific and is also specified in the ‘insv’ or ‘extv’ pattern. The mode M is the same as the mode that would be used for LOC if it were a register. A ‘sign_extract’ cannot appear as an lvalue, or part thereof, in RTL. ‘(zero_extract:M LOC SIZE POS)’ Like ‘sign_extract’ but refers to an unsigned or zero-extended bit-field. The same sequence of bits are extracted, but they are filled to an entire word with zeros instead of by sign-extension. Unlike ‘sign_extract’, this type of expressions can be lvalues in RTL; they may appear on the left side of an assignment, indicating insertion of a value into the specified bit-field.  File: gccint.info, Node: Vector Operations, Next: Conversions, Prev: Bit-Fields, Up: RTL 14.12 Vector Operations ======================= All normal RTL expressions can be used with vector modes; they are interpreted as operating on each part of the vector independently. Additionally, there are a few new expressions to describe specific vector operations. ‘(vec_merge:M VEC1 VEC2 ITEMS)’ This describes a merge operation between two vectors. The result is a vector of mode M; its elements are selected from either VEC1 or VEC2. Which elements are selected is described by ITEMS, which is a bit mask represented by a ‘const_int’; a zero bit indicates the corresponding element in the result vector is taken from VEC2 while a set bit indicates it is taken from VEC1. ‘(vec_select:M VEC1 SELECTION)’ This describes an operation that selects parts of a vector. VEC1 is the source vector, and SELECTION is a ‘parallel’ that contains a ‘const_int’ (or another expression, if the selection can be made at runtime) for each of the subparts of the result vector, giving the number of the source subpart that should be stored into it. The result mode M is either the submode for a single element of VEC1 (if only one subpart is selected), or another vector mode with that element submode (if multiple subparts are selected). ‘(vec_concat:M X1 X2)’ Describes a vector concat operation. The result is a concatenation of the vectors or scalars X1 and X2; its length is the sum of the lengths of the two inputs. ‘(vec_duplicate:M X)’ This operation converts a scalar into a vector or a small vector into a larger one by duplicating the input values. The output vector mode must have the same submodes as the input vector mode or the scalar modes, and the number of output parts must be an integer multiple of the number of input parts. ‘(vec_series:M BASE STEP)’ This operation creates a vector in which element I is equal to ‘BASE + I*STEP’. M must be a vector integer mode.  File: gccint.info, Node: Conversions, Next: RTL Declarations, Prev: Vector Operations, Up: RTL 14.13 Conversions ================= All conversions between machine modes must be represented by explicit conversion operations. For example, an expression which is the sum of a byte and a full word cannot be written as ‘(plus:SI (reg:QI 34) (reg:SI 80))’ because the ‘plus’ operation requires two operands of the same machine mode. Therefore, the byte-sized operand is enclosed in a conversion operation, as in (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) The conversion operation is not a mere placeholder, because there may be more than one way of converting from a given starting mode to the desired final mode. The conversion operation code says how to do it. For all conversion operations, X must not be ‘VOIDmode’ because the mode in which to do the conversion would not be known. The conversion must either be done at compile-time or X must be placed into a register. ‘(sign_extend:M X)’ Represents the result of sign-extending the value X to machine mode M. M must be a fixed-point mode and X a fixed-point value of a mode narrower than M. ‘(zero_extend:M X)’ Represents the result of zero-extending the value X to machine mode M. M must be a fixed-point mode and X a fixed-point value of a mode narrower than M. ‘(float_extend:M X)’ Represents the result of extending the value X to machine mode M. M must be a floating point mode and X a floating point value of a mode narrower than M. ‘(truncate:M X)’ Represents the result of truncating the value X to machine mode M. M must be a fixed-point mode and X a fixed-point value of a mode wider than M. ‘(ss_truncate:M X)’ Represents the result of truncating the value X to machine mode M, using signed saturation in the case of overflow. Both M and the mode of X must be fixed-point modes. ‘(us_truncate:M X)’ Represents the result of truncating the value X to machine mode M, using unsigned saturation in the case of overflow. Both M and the mode of X must be fixed-point modes. ‘(float_truncate:M X)’ Represents the result of truncating the value X to machine mode M. M must be a floating point mode and X a floating point value of a mode wider than M. ‘(float:M X)’ Represents the result of converting fixed point value X, regarded as signed, to floating point mode M. ‘(unsigned_float:M X)’ Represents the result of converting fixed point value X, regarded as unsigned, to floating point mode M. ‘(fix:M X)’ When M is a floating-point mode, represents the result of converting floating point value X (valid for mode M) to an integer, still represented in floating point mode M, by rounding towards zero. When M is a fixed-point mode, represents the result of converting floating point value X to mode M, regarded as signed. How rounding is done is not specified, so this operation may be used validly in compiling C code only for integer-valued operands. ‘(unsigned_fix:M X)’ Represents the result of converting floating point value X to fixed point mode M, regarded as unsigned. How rounding is done is not specified. ‘(fract_convert:M X)’ Represents the result of converting fixed-point value X to fixed-point mode M, signed integer value X to fixed-point mode M, floating-point value X to fixed-point mode M, fixed-point value X to integer mode M regarded as signed, or fixed-point value X to floating-point mode M. When overflows or underflows happen, the results are undefined. ‘(sat_fract:M X)’ Represents the result of converting fixed-point value X to fixed-point mode M, signed integer value X to fixed-point mode M, or floating-point value X to fixed-point mode M. When overflows or underflows happen, the results are saturated to the maximum or the minimum. ‘(unsigned_fract_convert:M X)’ Represents the result of converting fixed-point value X to integer mode M regarded as unsigned, or unsigned integer value X to fixed-point mode M. When overflows or underflows happen, the results are undefined. ‘(unsigned_sat_fract:M X)’ Represents the result of converting unsigned integer value X to fixed-point mode M. When overflows or underflows happen, the results are saturated to the maximum or the minimum.  File: gccint.info, Node: RTL Declarations, Next: Side Effects, Prev: Conversions, Up: RTL 14.14 Declarations ================== Declaration expression codes do not represent arithmetic operations but rather state assertions about their operands. ‘(strict_low_part (subreg:M (reg:N R) 0))’ This expression code is used in only one context: as the destination operand of a ‘set’ expression. In addition, the operand of this expression must be a non-paradoxical ‘subreg’ expression. The presence of ‘strict_low_part’ says that the part of the register which is meaningful in mode N, but is not part of mode M, is not to be altered. Normally, an assignment to such a subreg is allowed to have undefined effects on the rest of the register when M is smaller than ‘REGMODE_NATURAL_SIZE (N)’.  File: gccint.info, Node: Side Effects, Next: Incdec, Prev: RTL Declarations, Up: RTL 14.15 Side Effect Expressions ============================= The expression codes described so far represent values, not actions. But machine instructions never produce values; they are meaningful only for their side effects on the state of the machine. Special expression codes are used to represent side effects. The body of an instruction is always one of these side effect codes; the codes described above, which represent values, appear only as the operands of these. ‘(set LVAL X)’ Represents the action of storing the value of X into the place represented by LVAL. LVAL must be an expression representing a place that can be stored in: ‘reg’ (or ‘subreg’, ‘strict_low_part’ or ‘zero_extract’), ‘mem’, ‘pc’, or ‘parallel’. If LVAL is a ‘reg’, ‘subreg’ or ‘mem’, it has a machine mode; then X must be valid for that mode. If LVAL is a ‘reg’ whose machine mode is less than the full width of the register, then it means that the part of the register specified by the machine mode is given the specified value and the rest of the register receives an undefined value. Likewise, if LVAL is a ‘subreg’ whose machine mode is narrower than the mode of the register, the rest of the register can be changed in an undefined way. If LVAL is a ‘strict_low_part’ of a subreg, then the part of the register specified by the machine mode of the ‘subreg’ is given the value X and the rest of the register is not changed. If LVAL is a ‘zero_extract’, then the referenced part of the bit-field (a memory or register reference) specified by the ‘zero_extract’ is given the value X and the rest of the bit-field is not changed. Note that ‘sign_extract’ cannot appear in LVAL. If LVAL is a ‘parallel’, it is used to represent the case of a function returning a structure in multiple registers. Each element of the ‘parallel’ is an ‘expr_list’ whose first operand is a ‘reg’ and whose second operand is a ‘const_int’ representing the offset (in bytes) into the structure at which the data in that register corresponds. The first element may be null to indicate that the structure is also passed partly in memory. If LVAL is ‘(pc)’, we have a jump instruction, and the possibilities for X are very limited. It may be a ‘label_ref’ expression (unconditional jump). It may be an ‘if_then_else’ (conditional jump), in which case either the second or the third operand must be ‘(pc)’ (for the case which does not jump) and the other of the two must be a ‘label_ref’ (for the case which does jump). X may also be a ‘mem’ or ‘(plus:SI (pc) Y)’, where Y may be a ‘reg’ or a ‘mem’; these unusual patterns are used to represent jumps through branch tables. If LVAL is not ‘(pc)’, the mode of LVAL must not be ‘VOIDmode’ and the mode of X must be valid for the mode of LVAL. LVAL is customarily accessed with the ‘SET_DEST’ macro and X with the ‘SET_SRC’ macro. ‘(return)’ As the sole expression in a pattern, represents a return from the current function, on machines where this can be done with one instruction, such as VAXen. On machines where a multi-instruction "epilogue" must be executed in order to return from the function, returning is done by jumping to a label which precedes the epilogue, and the ‘return’ expression code is never used. Inside an ‘if_then_else’ expression, represents the value to be placed in ‘pc’ to return to the caller. Note that an insn pattern of ‘(return)’ is logically equivalent to ‘(set (pc) (return))’, but the latter form is never used. ‘(simple_return)’ Like ‘(return)’, but truly represents only a function return, while ‘(return)’ may represent an insn that also performs other functions of the function epilogue. Like ‘(return)’, this may also occur in conditional jumps. ‘(call FUNCTION NARGS)’ Represents a function call. FUNCTION is a ‘mem’ expression whose address is the address of the function to be called. NARGS is an expression which can be used for two purposes: on some machines it represents the number of bytes of stack argument; on others, it represents the number of argument registers. Each machine has a standard machine mode which FUNCTION must have. The machine description defines macro ‘FUNCTION_MODE’ to expand into the requisite mode name. The purpose of this mode is to specify what kind of addressing is allowed, on machines where the allowed kinds of addressing depend on the machine mode being addressed. ‘(clobber X)’ Represents the storing or possible storing of an unpredictable, undescribed value into X, which must be a ‘reg’, ‘scratch’, ‘parallel’ or ‘mem’ expression. One place this is used is in string instructions that store standard values into particular hard registers. It may not be worth the trouble to describe the values that are stored, but it is essential to inform the compiler that the registers will be altered, lest it attempt to keep data in them across the string instruction. If X is ‘(mem:BLK (const_int 0))’ or ‘(mem:BLK (scratch))’, it means that all memory locations must be presumed clobbered. If X is a ‘parallel’, it has the same meaning as a ‘parallel’ in a ‘set’ expression. Note that the machine description classifies certain hard registers as "call-clobbered". All function call instructions are assumed by default to clobber these registers, so there is no need to use ‘clobber’ expressions to indicate this fact. Also, each function call is assumed to have the potential to alter any memory location, unless the function is declared ‘const’. If the last group of expressions in a ‘parallel’ are each a ‘clobber’ expression whose arguments are ‘reg’ or ‘match_scratch’ (*note RTL Template::) expressions, the combiner phase can add the appropriate ‘clobber’ expressions to an insn it has constructed when doing so will cause a pattern to be matched. This feature can be used, for example, on a machine that whose multiply and add instructions don't use an MQ register but which has an add-accumulate instruction that does clobber the MQ register. Similarly, a combined instruction might require a temporary register while the constituent instructions might not. When a ‘clobber’ expression for a register appears inside a ‘parallel’ with other side effects, the register allocator guarantees that the register is unoccupied both before and after that insn if it is a hard register clobber. For pseudo-register clobber, the register allocator and the reload pass do not assign the same hard register to the clobber and the input operands if there is an insn alternative containing the ‘&’ constraint (*note Modifiers::) for the clobber and the hard register is in register classes of the clobber in the alternative. You can clobber either a specific hard register, a pseudo register, or a ‘scratch’ expression; in the latter two cases, GCC will allocate a hard register that is available there for use as a temporary. For instructions that require a temporary register, you should use ‘scratch’ instead of a pseudo-register because this will allow the combiner phase to add the ‘clobber’ when required. You do this by coding (‘clobber’ (‘match_scratch’ ...)). If you do clobber a pseudo register, use one which appears nowhere else--generate a new one each time. Otherwise, you may confuse CSE. There is one other known use for clobbering a pseudo register in a ‘parallel’: when one of the input operands of the insn is also clobbered by the insn. In this case, using the same pseudo register in the clobber and elsewhere in the insn produces the expected results. ‘(use X)’ Represents the use of the value of X. It indicates that the value in X at this point in the program is needed, even though it may not be apparent why this is so. Therefore, the compiler will not attempt to delete previous instructions whose only effect is to store a value in X. X must be a ‘reg’ expression. In some situations, it may be tempting to add a ‘use’ of a register in a ‘parallel’ to describe a situation where the value of a special register will modify the behavior of the instruction. A hypothetical example might be a pattern for an addition that can either wrap around or use saturating addition depending on the value of a special control register: (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3) (reg:SI 4)] 0)) (use (reg:SI 1))]) This will not work, several of the optimizers only look at expressions locally; it is very likely that if you have multiple insns with identical inputs to the ‘unspec’, they will be optimized away even if register 1 changes in between. This means that ‘use’ can _only_ be used to describe that the register is live. You should think twice before adding ‘use’ statements, more often you will want to use ‘unspec’ instead. The ‘use’ RTX is most commonly useful to describe that a fixed register is implicitly used in an insn. It is also safe to use in patterns where the compiler knows for other reasons that the result of the whole pattern is variable, such as ‘cpymemM’ or ‘call’ patterns. During the reload phase, an insn that has a ‘use’ as pattern can carry a reg_equal note. These ‘use’ insns will be deleted before the reload phase exits. During the delayed branch scheduling phase, X may be an insn. This indicates that X previously was located at this place in the code and its data dependencies need to be taken into account. These ‘use’ insns will be deleted before the delayed branch scheduling phase exits. ‘(parallel [X0 X1 ...])’ Represents several side effects performed in parallel. The square brackets stand for a vector; the operand of ‘parallel’ is a vector of expressions. X0, X1 and so on are individual side effect expressions--expressions of code ‘set’, ‘call’, ‘return’, ‘simple_return’, ‘clobber’ or ‘use’. "In parallel" means that first all the values used in the individual side-effects are computed, and second all the actual side-effects are performed. For example, (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) (set (mem:SI (reg:SI 1)) (reg:SI 1))]) says unambiguously that the values of hard register 1 and the memory location addressed by it are interchanged. In both places where ‘(reg:SI 1)’ appears as a memory address it refers to the value in register 1 _before_ the execution of the insn. It follows that it is _incorrect_ to use ‘parallel’ and expect the result of one ‘set’ to be available for the next one. For example, people sometimes attempt to represent a jump-if-zero instruction this way: (parallel [(set (reg:CC CC_REG) (reg:SI 34)) (set (pc) (if_then_else (eq (reg:CC CC_REG) (const_int 0)) (label_ref ...) (pc)))]) But this is incorrect, because it says that the jump condition depends on the condition code value _before_ this instruction, not on the new value that is set by this instruction. Peephole optimization, which takes place together with final assembly code output, can produce insns whose patterns consist of a ‘parallel’ whose elements are the operands needed to output the resulting assembler code--often ‘reg’, ‘mem’ or constant expressions. This would not be well-formed RTL at any other stage in compilation, but it is OK then because no further optimization remains to be done. ‘(cond_exec [COND EXPR])’ Represents a conditionally executed expression. The EXPR is executed only if the COND is nonzero. The COND expression must not have side-effects, but the EXPR may very well have side-effects. ‘(sequence [INSNS ...])’ Represents a sequence of insns. If a ‘sequence’ appears in the chain of insns, then each of the INSNS that appears in the sequence must be suitable for appearing in the chain of insns, i.e. must satisfy the ‘INSN_P’ predicate. After delay-slot scheduling is completed, an insn and all the insns that reside in its delay slots are grouped together into a ‘sequence’. The insn requiring the delay slot is the first insn in the vector; subsequent insns are to be placed in the delay slot. ‘INSN_ANNULLED_BRANCH_P’ is set on an insn in a delay slot to indicate that a branch insn should be used that will conditionally annul the effect of the insns in the delay slots. In such a case, ‘INSN_FROM_TARGET_P’ indicates that the insn is from the target of the branch and should be executed only if the branch is taken; otherwise the insn should be executed only if the branch is not taken. *Note Delay Slots::. Some back ends also use ‘sequence’ objects for purposes other than delay-slot groups. This is not supported in the common parts of the compiler, which treat such sequences as delay-slot groups. DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed using ‘sequence’ objects as the value of a ‘RTX_FRAME_RELATED_P’ note. This only happens if the CFA adjustments cannot be easily derived from the pattern of the instruction to which the note is attached. In such cases, the value of the note is used instead of best-guesing the semantics of the instruction. The back end can attach notes containing a ‘sequence’ of ‘set’ patterns that express the effect of the parent instruction. These expression codes appear in place of a side effect, as the body of an insn, though strictly speaking they do not always describe side effects as such: ‘(asm_input S)’ Represents literal assembler code as described by the string S. ‘(unspec [OPERANDS ...] INDEX)’ ‘(unspec_volatile [OPERANDS ...] INDEX)’ Represents a machine-specific operation on OPERANDS. INDEX selects between multiple machine-specific operations. ‘unspec_volatile’ is used for volatile operations and operations that may trap; ‘unspec’ is used for other operations. These codes may appear inside a ‘pattern’ of an insn, inside a ‘parallel’, or inside an expression. ‘(addr_vec:M [LR0 LR1 ...])’ Represents a table of jump addresses. The vector elements LR0, etc., are ‘label_ref’ expressions. The mode M specifies how much space is given to each address; normally M would be ‘Pmode’. ‘(addr_diff_vec:M BASE [LR0 LR1 ...] MIN MAX FLAGS)’ Represents a table of jump addresses expressed as offsets from BASE. The vector elements LR0, etc., are ‘label_ref’ expressions and so is BASE. The mode M specifies how much space is given to each address-difference. MIN and MAX are set up by branch shortening and hold a label with a minimum and a maximum address, respectively. FLAGS indicates the relative position of BASE, MIN and MAX to the containing insn and of MIN and MAX to BASE. See rtl.def for details. ‘(prefetch:M ADDR RW LOCALITY)’ Represents prefetch of memory at address ADDR. Operand RW is 1 if the prefetch is for data to be written, 0 otherwise; targets that do not support write prefetches should treat this as a normal prefetch. Operand LOCALITY specifies the amount of temporal locality; 0 if there is none or 1, 2, or 3 for increasing levels of temporal locality; targets that do not support locality hints should ignore this. This insn is used to minimize cache-miss latency by moving data into a cache before it is accessed. It should use only non-faulting data prefetch instructions.  File: gccint.info, Node: Incdec, Next: Assembler, Prev: Side Effects, Up: RTL 14.16 Embedded Side-Effects on Addresses ======================================== Six special side-effect expression codes appear as memory addresses. ‘(pre_dec:M X)’ Represents the side effect of decrementing X by a standard amount and represents also the value that X has after being decremented. X must be a ‘reg’ or ‘mem’, but most machines allow only a ‘reg’. M must be the machine mode for pointers on the machine in use. The amount X is decremented by is the length in bytes of the machine mode of the containing memory reference of which this expression serves as the address. Here is an example of its use: (mem:DF (pre_dec:SI (reg:SI 39))) This says to decrement pseudo register 39 by the length of a ‘DFmode’ value and use the result to address a ‘DFmode’ value. ‘(pre_inc:M X)’ Similar, but specifies incrementing X instead of decrementing it. ‘(post_dec:M X)’ Represents the same side effect as ‘pre_dec’ but a different value. The value represented here is the value X has before being decremented. ‘(post_inc:M X)’ Similar, but specifies incrementing X instead of decrementing it. ‘(post_modify:M X Y)’ Represents the side effect of setting X to Y and represents X before X is modified. X must be a ‘reg’ or ‘mem’, but most machines allow only a ‘reg’. M must be the machine mode for pointers on the machine in use. The expression Y must be one of three forms: ‘(plus:M X Z)’, ‘(minus:M X Z)’, or ‘(plus:M X I)’, where Z is an index register and I is a constant. Here is an example of its use: (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48)))) This says to modify pseudo register 42 by adding the contents of pseudo register 48 to it, after the use of what ever 42 points to. ‘(pre_modify:M X EXPR)’ Similar except side effects happen before the use. These embedded side effect expressions must be used with care. Instruction patterns may not use them. Until the ‘flow’ pass of the compiler, they may occur only to represent pushes onto the stack. The ‘flow’ pass finds cases where registers are incremented or decremented in one instruction and used as an address shortly before or after; these cases are then transformed to use pre- or post-increment or -decrement. If a register used as the operand of these expressions is used in another address in an insn, the original value of the register is used. Uses of the register outside of an address are not permitted within the same insn as a use in an embedded side effect expression because such insns behave differently on different machines and hence must be treated as ambiguous and disallowed. An instruction that can be represented with an embedded side effect could also be represented using ‘parallel’ containing an additional ‘set’ to describe how the address register is altered. This is not done because machines that allow these operations at all typically allow them wherever a memory address is called for. Describing them as additional parallel stores would require doubling the number of entries in the machine description.  File: gccint.info, Node: Assembler, Next: Debug Information, Prev: Incdec, Up: RTL 14.17 Assembler Instructions as Expressions =========================================== The RTX code ‘asm_operands’ represents a value produced by a user-specified assembler instruction. It is used to represent an ‘asm’ statement with arguments. An ‘asm’ statement with a single output operand, like this: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); is represented using a single ‘asm_operands’ RTX which represents the value that is stored in ‘outputvar’: (set RTX-FOR-OUTPUTVAR (asm_operands "foo %1,%2,%0" "a" 0 [RTX-FOR-ADDITION-RESULT RTX-FOR-*Z] [(asm_input:M1 "g") (asm_input:M2 "di")])) Here the operands of the ‘asm_operands’ RTX are the assembler template string, the output-operand's constraint, the index-number of the output operand among the output operands specified, a vector of input operand RTX's, and a vector of input-operand modes and constraints. The mode M1 is the mode of the sum ‘x+y’; M2 is that of ‘*z’. When an ‘asm’ statement has multiple output values, its insn has several such ‘set’ RTX's inside of a ‘parallel’. Each ‘set’ contains an ‘asm_operands’; all of these share the same assembler template and vectors, but each contains the constraint for the respective output operand. They are also distinguished by the output-operand index number, which is 0, 1, ... for successive output operands.  File: gccint.info, Node: Debug Information, Next: Insns, Prev: Assembler, Up: RTL 14.18 Variable Location Debug Information in RTL ================================================ Variable tracking relies on ‘MEM_EXPR’ and ‘REG_EXPR’ annotations to determine what user variables memory and register references refer to. Variable tracking at assignments uses these notes only when they refer to variables that live at fixed locations (e.g., addressable variables, global non-automatic variables). For variables whose location may vary, it relies on the following types of notes. ‘(var_location:MODE VAR EXP STAT)’ Binds variable ‘var’, a tree, to value EXP, an RTL expression. It appears only in ‘NOTE_INSN_VAR_LOCATION’ and ‘DEBUG_INSN’s, with slightly different meanings. MODE, if present, represents the mode of EXP, which is useful if it is a modeless expression. STAT is only meaningful in notes, indicating whether the variable is known to be initialized or uninitialized. ‘(debug_expr:MODE DECL)’ Stands for the value bound to the ‘DEBUG_EXPR_DECL’ DECL, that points back to it, within value expressions in ‘VAR_LOCATION’ nodes. ‘(debug_implicit_ptr:MODE DECL)’ Stands for the location of a DECL that is no longer addressable. ‘(entry_value:MODE DECL)’ Stands for the value a DECL had at the entry point of the containing function. ‘(debug_parameter_ref:MODE DECL)’ Refers to a parameter that was completely optimized out. ‘(debug_marker:MODE)’ Marks a program location. With ‘VOIDmode’, it stands for the beginning of a statement, a recommended inspection point logically after all prior side effects, and before any subsequent side effects. With ‘BLKmode’, it indicates an inline entry point: the lexical block encoded in the ‘INSN_LOCATION’ is the enclosing block that encloses the inlined function.  File: gccint.info, Node: Insns, Next: Calls, Prev: Debug Information, Up: RTL 14.19 Insns =========== The RTL representation of the code for a function is a doubly-linked chain of objects called “insns”. Insns are expressions with special codes that are used for no other purpose. Some insns are actual instructions; others represent dispatch tables for ‘switch’ statements; others represent labels to jump to or various sorts of declarative information. In addition to its own specific data, each insn must have a unique id-number that distinguishes it from all other insns in the current function (after delayed branch scheduling, copies of an insn with the same id-number may be present in multiple places in a function, but these copies will always be identical and will only appear inside a ‘sequence’), and chain pointers to the preceding and following insns. These three fields occupy the same position in every insn, independent of the expression code of the insn. They could be accessed with ‘XEXP’ and ‘XINT’, but instead three special macros are always used: ‘INSN_UID (I)’ Accesses the unique id of insn I. ‘PREV_INSN (I)’ Accesses the chain pointer to the insn preceding I. If I is the first insn, this is a null pointer. ‘NEXT_INSN (I)’ Accesses the chain pointer to the insn following I. If I is the last insn, this is a null pointer. The first insn in the chain is obtained by calling ‘get_insns’; the last insn is the result of calling ‘get_last_insn’. Within the chain delimited by these insns, the ‘NEXT_INSN’ and ‘PREV_INSN’ pointers must always correspond: if INSN is not the first insn, NEXT_INSN (PREV_INSN (INSN)) == INSN is always true and if INSN is not the last insn, PREV_INSN (NEXT_INSN (INSN)) == INSN is always true. After delay slot scheduling, some of the insns in the chain might be ‘sequence’ expressions, which contain a vector of insns. The value of ‘NEXT_INSN’ in all but the last of these insns is the next insn in the vector; the value of ‘NEXT_INSN’ of the last insn in the vector is the same as the value of ‘NEXT_INSN’ for the ‘sequence’ in which it is contained. Similar rules apply for ‘PREV_INSN’. This means that the above invariants are not necessarily true for insns inside ‘sequence’ expressions. Specifically, if INSN is the first insn in a ‘sequence’, ‘NEXT_INSN (PREV_INSN (INSN))’ is the insn containing the ‘sequence’ expression, as is the value of ‘PREV_INSN (NEXT_INSN (INSN))’ if INSN is the last insn in the ‘sequence’ expression. You can use these expressions to find the containing ‘sequence’ expression. Every insn has one of the following expression codes: ‘insn’ The expression code ‘insn’ is used for instructions that do not jump and do not do function calls. ‘sequence’ expressions are always contained in insns with code ‘insn’ even if one of those insns should jump or do function calls. Insns with code ‘insn’ have four additional fields beyond the three mandatory ones listed above. These four are described in a table below. ‘jump_insn’ The expression code ‘jump_insn’ is used for instructions that may jump (or, more generally, may contain ‘label_ref’ expressions to which ‘pc’ can be set in that instruction). If there is an instruction to return from the current function, it is recorded as a ‘jump_insn’. ‘jump_insn’ insns have the same extra fields as ‘insn’ insns, accessed in the same way and in addition contain a field ‘JUMP_LABEL’ which is defined once jump optimization has completed. For simple conditional and unconditional jumps, this field contains the ‘code_label’ to which this insn will (possibly conditionally) branch. In a more complex jump, ‘JUMP_LABEL’ records one of the labels that the insn refers to; other jump target labels are recorded as ‘REG_LABEL_TARGET’ notes. The exception is ‘addr_vec’ and ‘addr_diff_vec’, where ‘JUMP_LABEL’ is ‘NULL_RTX’ and the only way to find the labels is to scan the entire body of the insn. Return insns count as jumps, but their ‘JUMP_LABEL’ is ‘RETURN’ or ‘SIMPLE_RETURN’. ‘call_insn’ The expression code ‘call_insn’ is used for instructions that may do function calls. It is important to distinguish these instructions because they imply that certain registers and memory locations may be altered unpredictably. ‘call_insn’ insns have the same extra fields as ‘insn’ insns, accessed in the same way and in addition contain a field ‘CALL_INSN_FUNCTION_USAGE’, which contains a list (chain of ‘expr_list’ expressions) containing ‘use’, ‘clobber’ and sometimes ‘set’ expressions that denote hard registers and ‘mem’s used or clobbered by the called function. A ‘mem’ generally points to a stack slot in which arguments passed to the libcall by reference (*note TARGET_PASS_BY_REFERENCE: Register Arguments.) are stored. If the argument is caller-copied (*note TARGET_CALLEE_COPIES: Register Arguments.), the stack slot will be mentioned in ‘clobber’ and ‘use’ entries; if it's callee-copied, only a ‘use’ will appear, and the ‘mem’ may point to addresses that are not stack slots. Registers occurring inside a ‘clobber’ in this list augment registers specified in ‘CALL_USED_REGISTERS’ (*note Register Basics::). If the list contains a ‘set’ involving two registers, it indicates that the function returns one of its arguments. Such a ‘set’ may look like a no-op if the same register holds the argument and the return value. ‘code_label’ A ‘code_label’ insn represents a label that a jump insn can jump to. It contains two special fields of data in addition to the three standard ones. ‘CODE_LABEL_NUMBER’ is used to hold the “label number”, a number that identifies this label uniquely among all the labels in the compilation (not just in the current function). Ultimately, the label is represented in the assembler output as an assembler label, usually of the form ‘LN’ where N is the label number. When a ‘code_label’ appears in an RTL expression, it normally appears within a ‘label_ref’ which represents the address of the label, as a number. Besides as a ‘code_label’, a label can also be represented as a ‘note’ of type ‘NOTE_INSN_DELETED_LABEL’. The field ‘LABEL_NUSES’ is only defined once the jump optimization phase is completed. It contains the number of times this label is referenced in the current function. The field ‘LABEL_KIND’ differentiates four different types of labels: ‘LABEL_NORMAL’, ‘LABEL_STATIC_ENTRY’, ‘LABEL_GLOBAL_ENTRY’, and ‘LABEL_WEAK_ENTRY’. The only labels that do not have type ‘LABEL_NORMAL’ are “alternate entry points” to the current function. These may be static (visible only in the containing translation unit), global (exposed to all translation units), or weak (global, but can be overridden by another symbol with the same name). Much of the compiler treats all four kinds of label identically. Some of it needs to know whether or not a label is an alternate entry point; for this purpose, the macro ‘LABEL_ALT_ENTRY_P’ is provided. It is equivalent to testing whether ‘LABEL_KIND (label) == LABEL_NORMAL’. The only place that cares about the distinction between static, global, and weak alternate entry points, besides the front-end code that creates them, is the function ‘output_alternate_entry_point’, in ‘final.cc’. To set the kind of a label, use the ‘SET_LABEL_KIND’ macro. ‘jump_table_data’ A ‘jump_table_data’ insn is a placeholder for the jump-table data of a ‘casesi’ or ‘tablejump’ insn. They are placed after a ‘tablejump_p’ insn. A ‘jump_table_data’ insn is not part o a basic blockm but it is associated with the basic block that ends with the ‘tablejump_p’ insn. The ‘PATTERN’ of a ‘jump_table_data’ is always either an ‘addr_vec’ or an ‘addr_diff_vec’, and a ‘jump_table_data’ insn is always preceded by a ‘code_label’. The ‘tablejump_p’ insn refers to that ‘code_label’ via its ‘JUMP_LABEL’. ‘barrier’ Barriers are placed in the instruction stream when control cannot flow past them. They are placed after unconditional jump instructions to indicate that the jumps are unconditional and after calls to ‘volatile’ functions, which do not return (e.g., ‘exit’). They contain no information beyond the three standard fields. ‘note’ ‘note’ insns are used to represent additional debugging and declarative information. They contain two nonstandard fields, an integer which is accessed with the macro ‘NOTE_LINE_NUMBER’ and a string accessed with ‘NOTE_SOURCE_FILE’. If ‘NOTE_LINE_NUMBER’ is positive, the note represents the position of a source line and ‘NOTE_SOURCE_FILE’ is the source file name that the line came from. These notes control generation of line number data in the assembler output. Otherwise, ‘NOTE_LINE_NUMBER’ is not really a line number but a code with one of the following values (and ‘NOTE_SOURCE_FILE’ must contain a null pointer): ‘NOTE_INSN_DELETED’ Such a note is completely ignorable. Some passes of the compiler delete insns by altering them into notes of this kind. ‘NOTE_INSN_DELETED_LABEL’ This marks what used to be a ‘code_label’, but was not used for other purposes than taking its address and was transformed to mark that no code jumps to it. ‘NOTE_INSN_BLOCK_BEG’ ‘NOTE_INSN_BLOCK_END’ These types of notes indicate the position of the beginning and end of a level of scoping of variable names. They control the output of debugging information. ‘NOTE_INSN_EH_REGION_BEG’ ‘NOTE_INSN_EH_REGION_END’ These types of notes indicate the position of the beginning and end of a level of scoping for exception handling. ‘NOTE_EH_HANDLER’ identifies which region is associated with these notes. ‘NOTE_INSN_FUNCTION_BEG’ Appears at the start of the function body, after the function prologue. ‘NOTE_INSN_VAR_LOCATION’ This note is used to generate variable location debugging information. It indicates that the user variable in its ‘VAR_LOCATION’ operand is at the location given in the RTL expression, or holds a value that can be computed by evaluating the RTL expression from that static point in the program up to the next such note for the same user variable. ‘NOTE_INSN_BEGIN_STMT’ This note is used to generate ‘is_stmt’ markers in line number debugging information. It indicates the beginning of a user statement. ‘NOTE_INSN_INLINE_ENTRY’ This note is used to generate ‘entry_pc’ for inlined subroutines in debugging information. It indicates an inspection point at which all arguments for the inlined function have been bound, and before its first statement. These codes are printed symbolically when they appear in debugging dumps. ‘debug_insn’ The expression code ‘debug_insn’ is used for pseudo-instructions that hold debugging information for variable tracking at assignments (see ‘-fvar-tracking-assignments’ option). They are the RTL representation of ‘GIMPLE_DEBUG’ statements (*note GIMPLE_DEBUG::), with a ‘VAR_LOCATION’ operand that binds a user variable tree to an RTL representation of the ‘value’ in the corresponding statement. A ‘DEBUG_EXPR’ in it stands for the value bound to the corresponding ‘DEBUG_EXPR_DECL’. ‘GIMPLE_DEBUG_BEGIN_STMT’ and ‘GIMPLE_DEBUG_INLINE_ENTRY’ are expanded to RTL as a ‘DEBUG_INSN’ with a ‘DEBUG_MARKER’ ‘PATTERN’; the difference is the RTL mode: the former's ‘DEBUG_MARKER’ is ‘VOIDmode’, whereas the latter is ‘BLKmode’; information about the inlined function can be taken from the lexical block encoded in the ‘INSN_LOCATION’. These ‘DEBUG_INSN’s, that do not carry ‘VAR_LOCATION’ information, just ‘DEBUG_MARKER’s, can be detected by testing ‘DEBUG_MARKER_INSN_P’, whereas those that do can be recognized as ‘DEBUG_BIND_INSN_P’. Throughout optimization passes, ‘DEBUG_INSN’s are not reordered with respect to each other, particularly during scheduling. Binding information is kept in pseudo-instruction form, so that, unlike notes, it gets the same treatment and adjustments that regular instructions would. It is the variable tracking pass that turns these pseudo-instructions into ‘NOTE_INSN_VAR_LOCATION’, ‘NOTE_INSN_BEGIN_STMT’ and ‘NOTE_INSN_INLINE_ENTRY’ notes, analyzing control flow, value equivalences and changes to registers and memory referenced in value expressions, propagating the values of debug temporaries and determining expressions that can be used to compute the value of each user variable at as many points (ranges, actually) in the program as possible. Unlike ‘NOTE_INSN_VAR_LOCATION’, the value expression in an ‘INSN_VAR_LOCATION’ denotes a value at that specific point in the program, rather than an expression that can be evaluated at any later point before an overriding ‘VAR_LOCATION’ is encountered. E.g., if a user variable is bound to a ‘REG’ and then a subsequent insn modifies the ‘REG’, the note location would keep mapping the user variable to the register across the insn, whereas the insn location would keep the variable bound to the value, so that the variable tracking pass would emit another location note for the variable at the point in which the register is modified. The machine mode of an insn is normally ‘VOIDmode’, but some phases use the mode for various purposes. The common subexpression elimination pass sets the mode of an insn to ‘QImode’ when it is the first insn in a block that has already been processed. The second Haifa scheduling pass, for targets that can multiple issue, sets the mode of an insn to ‘TImode’ when it is believed that the instruction begins an issue group. That is, when the instruction cannot issue simultaneously with the previous. This may be relied on by later passes, in particular machine-dependent reorg. Here is a table of the extra fields of ‘insn’, ‘jump_insn’ and ‘call_insn’ insns: ‘PATTERN (I)’ An expression for the side effect performed by this insn. This must be one of the following codes: ‘set’, ‘call’, ‘use’, ‘clobber’, ‘return’, ‘simple_return’, ‘asm_input’, ‘asm_output’, ‘addr_vec’, ‘addr_diff_vec’, ‘trap_if’, ‘unspec’, ‘unspec_volatile’, ‘parallel’, ‘cond_exec’, or ‘sequence’. If it is a ‘parallel’, each element of the ‘parallel’ must be one these codes, except that ‘parallel’ expressions cannot be nested and ‘addr_vec’ and ‘addr_diff_vec’ are not permitted inside a ‘parallel’ expression. ‘INSN_CODE (I)’ An integer that says which pattern in the machine description matches this insn, or −1 if the matching has not yet been attempted. Such matching is never attempted and this field remains −1 on an insn whose pattern consists of a single ‘use’, ‘clobber’, ‘asm_input’, ‘addr_vec’ or ‘addr_diff_vec’ expression. Matching is also never attempted on insns that result from an ‘asm’ statement. These contain at least one ‘asm_operands’ expression. The function ‘asm_noperands’ returns a non-negative value for such insns. In the debugging output, this field is printed as a number followed by a symbolic representation that locates the pattern in the ‘md’ file as some small positive or negative offset from a named pattern. ‘REG_NOTES (I)’ A list (chain of ‘expr_list’, ‘insn_list’ and ‘int_list’ expressions) giving miscellaneous information about the insn. It is often information pertaining to the registers used in this insn. The ‘REG_NOTES’ field of an insn is a chain that includes ‘expr_list’ and ‘int_list’ expressions as well as ‘insn_list’ expressions. There are several kinds of register notes, which are distinguished by the machine mode, which in a register note is really understood as being an ‘enum reg_note’. The first operand OP of the note is data whose meaning depends on the kind of note. The macro ‘REG_NOTE_KIND (X)’ returns the kind of register note. Its counterpart, the macro ‘PUT_REG_NOTE_KIND (X, NEWKIND)’ sets the register note type of X to be NEWKIND. Register notes are of three classes: They may say something about an input to an insn, they may say something about an output of an insn, or they may create a linkage between two insns. These register notes annotate inputs to an insn: ‘REG_DEAD’ The value in OP dies in this insn; that is to say, altering the value immediately after this insn would not affect the future behavior of the program. It does not follow that the register OP has no useful value after this insn since OP is not necessarily modified by this insn. Rather, no subsequent instruction uses the contents of OP. ‘REG_UNUSED’ The register OP being set by this insn will not be used in a subsequent insn. This differs from a ‘REG_DEAD’ note, which indicates that the value in an input will not be used subsequently. These two notes are independent; both may be present for the same register. ‘REG_INC’ The register OP is incremented (or decremented; at this level there is no distinction) by an embedded side effect inside this insn. This means it appears in a ‘post_inc’, ‘pre_inc’, ‘post_dec’ or ‘pre_dec’ expression. ‘REG_NONNEG’ The register OP is known to have a nonnegative value when this insn is reached. This is used by special looping instructions that terminate when the register goes negative. The ‘REG_NONNEG’ note is added only to ‘doloop_end’ insns, if its pattern uses a ‘ge’ condition. ‘REG_LABEL_OPERAND’ This insn uses OP, a ‘code_label’ or a ‘note’ of type ‘NOTE_INSN_DELETED_LABEL’, but is not a ‘jump_insn’, or it is a ‘jump_insn’ that refers to the operand as an ordinary operand. The label may still eventually be a jump target, but if so in an indirect jump in a subsequent insn. The presence of this note allows jump optimization to be aware that OP is, in fact, being used, and flow optimization to build an accurate flow graph. ‘REG_LABEL_TARGET’ This insn is a ‘jump_insn’ but not an ‘addr_vec’ or ‘addr_diff_vec’. It uses OP, a ‘code_label’ as a direct or indirect jump target. Its purpose is similar to that of ‘REG_LABEL_OPERAND’. This note is only present if the insn has multiple targets; the last label in the insn (in the highest numbered insn-field) goes into the ‘JUMP_LABEL’ field and does not have a ‘REG_LABEL_TARGET’ note. *Note JUMP_LABEL: Insns. ‘REG_SETJMP’ Appears attached to each ‘CALL_INSN’ to ‘setjmp’ or a related function. The following notes describe attributes of outputs of an insn: ‘REG_EQUIV’ ‘REG_EQUAL’ This note is only valid on an insn that sets only one register and indicates that that register will be equal to OP at run time; the scope of this equivalence differs between the two types of notes. The value which the insn explicitly copies into the register may look different from OP, but they will be equal at run time. If the output of the single ‘set’ is a ‘strict_low_part’ or ‘zero_extract’ expression, the note refers to the register that is contained in its first operand. For ‘REG_EQUIV’, the register is equivalent to OP throughout the entire function, and could validly be replaced in all its occurrences by OP. ("Validly" here refers to the data flow of the program; simple replacement may make some insns invalid.) For example, when a constant is loaded into a register that is never assigned any other value, this kind of note is used. When a parameter is copied into a pseudo-register at entry to a function, a note of this kind records that the register is equivalent to the stack slot where the parameter was passed. Although in this case the register may be set by other insns, it is still valid to replace the register by the stack slot throughout the function. A ‘REG_EQUIV’ note is also used on an instruction which copies a register parameter into a pseudo-register at entry to a function, if there is a stack slot where that parameter could be stored. Although other insns may set the pseudo-register, it is valid for the compiler to replace the pseudo-register by stack slot throughout the function, provided the compiler ensures that the stack slot is properly initialized by making the replacement in the initial copy instruction as well. This is used on machines for which the calling convention allocates stack space for register parameters. See ‘REG_PARM_STACK_SPACE’ in *note Stack Arguments::. In the case of ‘REG_EQUAL’, the register that is set by this insn will be equal to OP at run time at the end of this insn but not necessarily elsewhere in the function. In this case, OP is typically an arithmetic expression. For example, when a sequence of insns such as a library call is used to perform an arithmetic operation, this kind of note is attached to the insn that produces or copies the final value. These two notes are used in different ways by the compiler passes. ‘REG_EQUAL’ is used by passes prior to register allocation (such as common subexpression elimination and loop optimization) to tell them how to think of that value. ‘REG_EQUIV’ notes are used by register allocation to indicate that there is an available substitute expression (either a constant or a ‘mem’ expression for the location of a parameter on the stack) that may be used in place of a register if insufficient registers are available. Except for stack homes for parameters, which are indicated by a ‘REG_EQUIV’ note and are not useful to the early optimization passes and pseudo registers that are equivalent to a memory location throughout their entire life, which is not detected until later in the compilation, all equivalences are initially indicated by an attached ‘REG_EQUAL’ note. In the early stages of register allocation, a ‘REG_EQUAL’ note is changed into a ‘REG_EQUIV’ note if OP is a constant and the insn represents the only set of its destination register. Thus, compiler passes prior to register allocation need only check for ‘REG_EQUAL’ notes and passes subsequent to register allocation need only check for ‘REG_EQUIV’ notes. These notes describe linkages between insns. They occur in pairs: one insn has one of a pair of notes that points to a second insn, which has the inverse note pointing back to the first insn. ‘REG_DEP_TRUE’ This indicates a true dependence (a read after write dependence). ‘REG_DEP_OUTPUT’ This indicates an output dependence (a write after write dependence). ‘REG_DEP_ANTI’ This indicates an anti dependence (a write after read dependence). These notes describe information gathered from gcov profile data. They are stored in the ‘REG_NOTES’ field of an insn. ‘REG_BR_PROB’ This is used to specify the ratio of branches to non-branches of a branch insn according to the profile data. The note is represented as an ‘int_list’ expression whose integer value is an encoding of ‘profile_probability’ type. ‘profile_probability’ provide member function ‘from_reg_br_prob_note’ and ‘to_reg_br_prob_note’ to extract and store the probability into the RTL encoding. ‘REG_BR_PRED’ These notes are found in JUMP insns after delayed branch scheduling has taken place. They indicate both the direction and the likelihood of the JUMP. The format is a bitmask of ATTR_FLAG_* values. ‘REG_FRAME_RELATED_EXPR’ This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression is used in place of the actual insn pattern. This is done in cases where the pattern is either complex or misleading. The note ‘REG_CALL_NOCF_CHECK’ is used in conjunction with the ‘-fcf-protection=branch’ option. The note is set if a ‘nocf_check’ attribute is specified for a function type or a pointer to function type. The note is stored in the ‘REG_NOTES’ field of an insn. ‘REG_CALL_NOCF_CHECK’ Users have control through the ‘nocf_check’ attribute to identify which calls to a function should be skipped from control-flow instrumentation when the option ‘-fcf-protection=branch’ is specified. The compiler puts a ‘REG_CALL_NOCF_CHECK’ note on each ‘CALL_INSN’ instruction that has a function type marked with a ‘nocf_check’ attribute. For convenience, the machine mode in an ‘insn_list’ or ‘expr_list’ is printed using these symbolic codes in debugging dumps. The only difference between the expression codes ‘insn_list’ and ‘expr_list’ is that the first operand of an ‘insn_list’ is assumed to be an insn and is printed in debugging dumps as the insn's unique id; the first operand of an ‘expr_list’ is printed in the ordinary way as an expression.