diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index 3b853c8..e1fd8c6 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -737,9 +737,8 @@ predicates used with @code{match_operand} have names that end in @samp{_operand}, and those used with @code{match_operator} have names that end in @samp{_operator}. -All predicates are Boolean functions (in the mathematical sense) of -two arguments: the RTL expression that is being considered at that -position in the instruction pattern, and the machine mode that the +Predicates take two arguments: the RTL expression that is being considered +at that position in the instruction pattern, and the machine mode that the @code{match_operand} or @code{match_operator} specifies. In this section, the first argument is called @var{op} and the second argument @var{mode}. Predicates can be called from C as ordinary two-argument @@ -747,39 +746,51 @@ functions; this can be useful in output templates or other machine-specific code. Operand predicates can allow operands that are not actually acceptable -to the hardware, as long as the constraints give reload the ability to -fix them up (@pxref{Constraints}). However, GCC will usually generate -better code if the predicates specify the requirements of the machine -instructions as closely as possible. Reload cannot fix up operands -that must be constants (``immediate operands''); you must use a -predicate that allows only constants, or else enforce the requirement -in the extra condition. +to the hardware, as long as the constraints can be fulfilled, perhaps by +moving the operand between register classes, during register allocation +(@pxref{Constraints}). However, GCC will usually generate better code +if the predicates specify the requirements of the machine instructions +as closely as possible. + +It is an error for the contraints of an operand to be impossible to fulfil +for operands which are valid for the predicate of the operand. One such +example would be the combination of a predicate allowing any operand, +with a constraint requiring only immediate operands. Here, the predicate +may permit a register operand containing a non-constant value, which it would +not be possible to convert to an immediate operand. @cindex predicates and machine modes @cindex normal predicates @cindex special predicates -Most predicates handle their @var{mode} argument in a uniform manner. -If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have -any mode. If @var{mode} is anything else, then @var{op} must have the -same mode, unless @var{op} is a @code{CONST_INT} or integer -@code{CONST_DOUBLE}. These RTL expressions always have -@code{VOIDmode}, so it would be counterproductive to check that their -mode matches. Instead, predicates that accept @code{CONST_INT} and/or -integer @code{CONST_DOUBLE} check that the value stored in the -constant will fit in the requested mode. - -Predicates with this behavior are called @dfn{normal}. -@command{genrecog} can optimize the instruction recognizer based on -knowledge of how normal predicates treat modes. It can also diagnose -certain kinds of common errors in the use of normal predicates; for -instance, it is almost always an error to use a normal predicate -without specifying a mode. - -Predicates that do something different with their @var{mode} argument -are called @dfn{special}. The generic predicates -@code{address_operand} and @code{pmode_register_operand} are special -predicates. @command{genrecog} does not do any optimizations or -diagnosis when special predicates are used. +@dfn{Normal} predicates are those for which the relationship between +@var{mode} and @var{op} can be described in one of the following ways. + +@enumerate +@item +If @var{mode} is @code{VOIDmode} or is unspecified, then @var{op} can have +any mode. + +@item +If @var{mode} is a defined mode, then @var{op} must be of the same mode. + +@item +If @var{op} is a @code{CONST_INT} or an integer @code{CONST_DOUBLE} RTL +expression, @var{mode} can be any mode. The predicate must itself +check that the range of @var{mode} is sufficient to contain the value in +@var{op}. +@end enumerate + +Using normal predicates allows for additional optimization to be +performed in the @command{genrecog} program. This can result in a +more efficient instruction recognizer. @command{genrecog} is also able +to diagnose common errors in the use of normal predicates, such as a +missing @var{mode}. + +Predicates that do not have the relationship described above between their +@var{mode} and @var{op} arguments are called @dfn{special} predicates. +The generic predicates @code{address_operand} and +@code{pmode_register_operand} are special predicates. @command{genrecog} +does not do any optimizations or diagnosis when special predicates are used. @menu * Machine-Independent Predicates:: Predicates available to all back ends. @@ -794,25 +805,25 @@ diagnosis when special predicates are used. These are the generic predicates available to all back ends. They are defined in @file{recog.c}. The first category of predicates allow -only constant, or @dfn{immediate}, operands. +only constant, or @dfn{immediate}, operands and are normal predicates. @defun immediate_operand This predicate allows any sort of constant that fits in @var{mode}. -It is an appropriate choice for instructions that take operands that -must be constant. +It is an appropriate choice for operands to an instruction which requires +a constant. @end defun @defun const_int_operand This predicate allows any @code{CONST_INT} expression that fits in -@var{mode}. It is an appropriate choice for an immediate operand that -does not allow a symbol or label. +@var{mode}. It is an appropriate choice for operands to an instruction +which requires an integer constant that may not be a symbol or a label. @end defun @defun const_double_operand -This predicate accepts any @code{CONST_DOUBLE} expression that has +This predicate allows any @code{CONST_DOUBLE} expression that has exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also -accept @code{CONST_INT}. It is intended for immediate floating point -constants. +accept any @code{CONST_INT} expression. It is an appropriate choice for +operands to an instruction which requires a floating point constant. @end defun @noindent @@ -821,30 +832,33 @@ register. @defun register_operand This predicate allows any @code{REG} or @code{SUBREG} expression that -is valid for @var{mode}. It is often suitable for arithmetic -instruction operands on a RISC machine. +is valid for @var{mode}. It is an appropriate choice for operands to an +instruction which requires a machine register. @end defun @defun pmode_register_operand -This is a slight variant on @code{register_operand} which works around -a limitation in the machine-description reader. +This predicate is a slight variant on @code{register_operand} which works +around a limitation in the machine-description reader. As @code{Pmode} +can be an alias for some other mode, and might vary with machine-specific +options, the machine-description reader is unable to accept @code{P} mode +suffixes (@pxref{Misc}). + +Consequently, the construct: @smallexample (match_operand @var{n} "pmode_register_operand" @var{constraint}) @end smallexample @noindent -means exactly what +expresses what would have otherwise have been written as: @smallexample (match_operand:P @var{n} "register_operand" @var{constraint}) @end smallexample @noindent -would mean, if the machine-description reader accepted @samp{:P} -mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an -alias for some other mode, and might vary with machine-specific -options. @xref{Misc}. +were it not for the deficiencies in the machine-description reader. + @end defun @defun scratch_operand @@ -857,15 +871,15 @@ it should not be used directly. The third category of predicates allow only some kind of memory reference. @defun memory_operand -This predicate allows any valid reference to a quantity of mode +This predicate allows any valid reference to an objects of mode @var{mode} in memory, as determined by the weak form of @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}). @end defun @defun address_operand -This predicate is a little unusual; it allows any operand that is a -valid expression for the @emph{address} of a quantity of mode -@var{mode}, again determined by the weak form of +This is a special predicate which allows any operand that is a +valid expression for the @emph{address} of an object of mode +@var{mode}, as determined by the weak form of @code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to @code{memory_operand}, then @var{exp} is acceptable to @@ -874,29 +888,31 @@ the mode @var{mode}. @end defun @defun indirect_operand -This is a stricter form of @code{memory_operand} which allows only -memory references with a @code{general_operand} as the address -expression. New uses of this predicate are discouraged, because -@code{general_operand} is very permissive, so it's hard to tell what -an @code{indirect_operand} does or does not allow. If a target has -different requirements for memory operands for different instructions, -it is better to define target-specific predicates which enforce the -hardware's requirements explicitly. +This predicate is a stricter form of @code{memory_operand} which allows +only memory references with a @code{general_operand} as the address +expression. New uses of this predicate are discouraged. + +The @code{general_operand} predicate is very permissive, consequently, +an @code{indirect_operand} may permit more address expressions than would +be expected. A target with different requirements for memory operands +for different instructions should instead define target-specific predicates +which enforce the hardware's requirements explicitly. @end defun @defun push_operand This predicate allows a memory reference suitable for pushing a value onto the stack. This will be a @code{MEM} which refers to @code{stack_pointer_rtx}, with a side-effect in its address expression -(@pxref{Incdec}); which one is determined by the +(@pxref{Incdec}). The type of side-effect is defined by the @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}). @end defun @defun pop_operand This predicate allows a memory reference suitable for popping a value -off the stack. Again, this will be a @code{MEM} referring to +off the stack. This will be a @code{MEM} referring to @code{stack_pointer_rtx}, with a side-effect in its address -expression. However, this time @code{STACK_POP_CODE} is expected. +expression. The type of side-effect is defined by the @code{STACK_POP_CODE} +macro. @end defun @noindent @@ -969,27 +985,38 @@ subexpression of @var{op} has one of a given list of RTX codes. The first operand of this expression is a string constant containing a comma-separated list of RTX code names (in lower case). These are the -codes for which the @code{MATCH_CODE} will be true. - -The second operand is a string constant which indicates what -subexpression of @var{op} to examine. If it is absent or the empty -string, @var{op} itself is examined. Otherwise, the string constant -must be a sequence of digits and/or lowercase letters. Each character -indicates a subexpression to extract from the current expression; for -the first character this is @var{op}, for the second and subsequent -characters it is the result of the previous character. A digit -@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l} -extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the -alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The -@code{MATCH_CODE} then examines the RTX code of the subexpression -extracted by the complete string. It is not possible to extract -components of an @code{rtvec} that is not at position 0 within its RTX -object. +expected codes for which the @code{MATCH_CODE} will be true. + +The second, optional, operand is a string constant which indicates which +subexpression of @var{op} to examine. If it is absent or is the empty +string, @var{op} itself is examined. + +Otherwise, the string constant must be a sequence of digits and/or +lowercase letters. Each character indicates a subexpression to extract +from the current expression, @var{e}. For the first character this is +@var{op}, for the second and subsequent characters it is the result of +the subexpression indicated by the previous character. + +A digit @var{n} extracts the @var{n}'th subexpression of the current +expression, as if by @samp{@w{XEXP (@var{e}, @var{n})}}. + +A letter @var{l} extracts an element from the vector subexpression which +is found at operand 0 of the current expression. First @var{l} is +converted to an integer @var{n} by taking the alphabetic ordinal of +@var{l} (0 for `a', 1 for 'b', and so on). @var{n} is then used to extract +the @var{n}'th element of the vector subexpression at operand 0 of the current +expression, as if by @samp{@w{XVECEXP (@var{e}, 0, @var{n})}}. It is not +possible to extract components of an @code{rtvec} that is not at position +0 within its RTX object. + +@code{MATCH_CODE} evaluates to true if the RTX code of the current +expression, @var{e}, having parsed the full string, matches any of +those listed in the expected codes. @item MATCH_TEST This expression has one operand, a string constant containing a C -expression. The predicate's arguments, @var{op} and @var{mode}, are -available with those names in the C expression. The @code{MATCH_TEST} +expression. The arguments to the predicate, @var{op} and @var{mode}, +are available with those names in the C expression. @code{MATCH_TEST} evaluates to true if the C expression evaluates to a nonzero value. @code{MATCH_TEST} expressions must not have side effects. @@ -1001,8 +1028,8 @@ The basic @samp{MATCH_} expressions can be combined using these logical operators, which have the semantics of the C operators @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As in Common Lisp, you may give an @code{AND} or @code{IOR} expression an -arbitrary number of arguments; this has exactly the same effect as -writing a chain of two-argument @code{AND} or @code{IOR} expressions. +arbitrary number of arguments; this has the same effect as writing a +chain of two-argument @code{AND} or @code{IOR} expressions. @end table @item @@ -1015,8 +1042,8 @@ available with those names. If a code block is present in a predicate definition, then the RTL expression must evaluate to true @emph{and} the code block must execute @samp{@w{return true}} for the predicate to allow the operand. -The RTL expression is evaluated first; do not re-check anything in the -code block that was checked in the RTL expression. +The RTL expression is evaluated first. There is no reason to re-check +anything in the code block that was checked in the RTL expression. @end itemize The program @command{genrecog} scans @code{define_predicate} and @@ -1062,10 +1089,10 @@ mode as @var{mode}, or @var{op} is a @code{CONST_INT} or @code{CONST_DOUBLE}. They do @emph{not} check specifically for integer @code{CONST_DOUBLE}, nor do they test that the value of either kind of constant fits in the requested mode. This is because -target-specific predicates that take constants usually have to do more -stringent value checks anyway. If you need the exact same treatment -of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates -provide, use a @code{MATCH_OPERAND} subexpression to call +target-specific predicates that take constants usually have a more restricted +range than that of the full machine mode. If you need the exact same +treatment of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic +predicates provide, use a @code{MATCH_OPERAND} subexpression to call @code{const_int_operand}, @code{const_double_operand}, or @code{immediate_operand}.