* RTL Introduction:: Introduction to CGEN's RTL
* Trade-offs:: Various trade-offs in the design
* Rules and notes:: Rules and notes common to all entries
+* RTL Versions:: Supported versions and differences
* Definitions:: Definitions in the description file
* Attributes:: Random data associated with any entry
* Architecture variants:: Specifying variations of a CPU
* Hardware elements:: Elements of a CPU
* Instruction fields:: Fields of an instruction
* Enumerated constants:: Assigning useful names to important numbers
+* Keywords:: Like enums, plus string table
* Instruction operands:: Operands of instructions
* Derived operands:: Operands for CISC-like architectures
* Instructions:: Instructions
Whether to use @samp{()} or @samp{#f} is largely a matter of style.
@end itemize
+@node RTL Versions
+@section RTL Versions
+
+CGEN has minimal support for making changes to the language without
+breaking existing ports. We do not put much effort into this because
+over time it can become unmaintainable, but for some changes it is
+useful to have a temporary window in which older versions are supported.
+
+@menu
+* Specifying the RTL version::
+* List of supported RTL versions::
+@end menu
+
+@node Specifying the RTL version
+@subsection Specifying the RTL version
+
+Specify the version of RTL that your cpu description was written to
+with @samp{define-rtl-version}.
+
+Syntax:
+
+@example
+(define-rtl-version major-version minor-version)
+@end example
+
+When setting the RTL version, it must be the first thing done
+in the description file or the behaviour is undefined.
+After the RTL version is set, if it is changed the behavior is undefined.
+
+Note that one can still set it to the same version multiple times.
+This is useful when the description is spread among several files,
+and one is debugging/testing files individually.
+
+The default RTL version, if @samp{define-rtl-version} is elided, is 0.7.
+
+The latest RTL version is 0.8:
+
+@example
+(define-rtl-version 0 8)
+@end example
+
+Every increment in major and minor versions is generally non-upward
+compatible (otherwise the version would not have been incremented -
+CGEN does not keep support for older versions long).
+
+@node List of supported RTL versions
+@subsection List of supported RTL versions
+
+CGEN currently supports the following RTL versions.
+
+@itemize @bullet
+
+@item 0.7 @code{(define-rtl-version 0 7)}
+
+This is the original RTL version.
+It is the default if no version is specified.
+It is supported by CGEN versions 1.0, 1.1, and the current development tree.
+Support for it will probably be removed for the CGEN 1.2 release.
+
+@item 0.8 @code{(define-rtl-version 0 8)}
+
+This version changed the syntax for defining keywords.
+@xref{Keywords}.
+The @samp{print-name} field was renamed to @samp{enum-prefix}
+and the @samp{prefix} field was renamed to @samp{name-prefix}.
+
+Previous syntax:
+
+@smallexample
+(define-keyword
+ (name keyword-name)
+ (comment "description")
+ (attrs attribute-list)
+ (mode mode-name)
+ (print-name "prefix-for-enum-values-with-trailing-dash")
+ (prefix "prefix-for-names-in-string-table")
+ (values value-list)
+)
+@end smallexample
+
+New syntax:
+
+@smallexample
+(define-keyword
+ (name keyword-name)
+ (comment "description")
+ (attrs attribute-list)
+ (mode mode-name)
+ (enum-prefix "prefix-for-enum-values")
+ (name-prefix "prefix-for-names-in-string-table")
+ (values value-list)
+)
+@end smallexample
+
+Note that @samp{print-name} has been replaced with @samp{enum-prefix}
+and @samp{prefix} has been replaced with @samp{name-prefix}.
+
+Furthermore, there is also a difference between the behavior of
+@samp{print-name} and @samp{enum-prefix}.
+When computing complete enum names with @samp{print-name},
+CGEN adds a @samp{-} between the prefix and the enum name.
+CGEN does not insert a @samp{-} with @samp{enum-prefix}.
+
+@end itemize
+
@node Definitions
@section Definitions
@cindex Definitions
base instruction.
@xref{Instruction fields}, for more information.
-??? There is currently no explicit way to specify a different instruction
-word bitsize for particular instructions, it is derived from the instruction
-field specs.
-
@subsubsection default-insn-bitsize
The default size of an instruction in bits. It is generally the size of
where @samp{index-type} specifies the kind of index and @samp{arg1 arg2 ...}
are arguments to @samp{index-type}.
-The are two supported values for @samp{index-type}: @code{keyword}
+There are two supported values for @samp{index-type}: @code{keyword}
and @code{extern-keyword}. The difference is that indices defined with
@code{keyword} are kept internal to the hardware element's definition
and are not usable elsewhere, whereas @code{extern-keyword} specifies
-a set of indices defined elsewhere.
+a set of indices defined elsewhere with @code{define-keyword}.
@subsubsection keyword
@example
-@code{(indices keyword "prefix" ((name1 value1) (name2 value2) ...))}
+@code{(indices keyword name-prefix ((name1 value1) (name2 value2) ...))}
@end example
-@samp{prefix} is the common prefix for each of the index names.
+@samp{name-prefix} is the assembler prefix common to each of the index names,
+and is added to name in the generated lookup table.
For example, SPARC registers usually begin with @samp{"%"}.
Each @samp{(name value)} pair maps a name with an index number.
An index can be specified multiple times, for example, when a register
has multiple names.
+There may be gaps in the index list, e.g. for invalid/reserved registers.
+
+No enum is defined for keywords defined this way.
+If you want an enum use @samp{define-keyword} and @samp{extern-keyword}.
+
Example from Thumb:
@example
@code{(indices extern-keyword keyword-name)}
@end example
+Often one wants to make the keywords available for general use,
+i.e. to arbitrary tools.
+@xref{Keywords}.
+When the collection of indices is defined with @samp{define-keyword}
+refer to it in the @samp{indices} field with @samp{extern-keyword}.
+
Example from M32R:
@example
(define-keyword
(name gr-names)
- (print-name h-gr)
- (prefix "")
+ (enum-prefix H-GR-)
(values (fp 13) (lr 14) (sp 15)
(r0 0) (r1 1) (r2 2) (r3 3) (r4 4) (r5 5) (r6 6) (r7 7)
(r8 8) (r9 9) (r10 10) (r11 11) (r12 12) (r13 13) (r14 14) (r15 15))
@code{index} is the name of the index as it appears in @code{expression}.
-At present, @code{sequence}, @code{parallel}, and @code{case} expressions
-are not allowed here.
+At present, @code{sequence}, @code{parallel}, @code{do-count}
+and @code{case} expressions are not allowed here.
@subsection set
@code{define-arch}.
If using the long form of specifying the field's position
-(@samp{word-offset} is present) then this value is the value within
+(i.e., @samp{word-offset} is specified) then this value is the value within
the containing word. If using the short form then this value includes
the word offset. See the Porting document for more info
(@pxref{Writing define-ifield}).
Convention requires each enum value to be prefixed with the same text.
Rather than specifying the prefix in each entry, it is specified once, here.
Convention requires @samp{prefix} not contain any lowercase characters.
+You generally want to end @samp{prefix} with @samp{-} or @samp{_}
+as the complete name of each enum value is @samp{prefix} + @samp{value-name}.
+The convention is to use @samp{-}, though this convention is not
+adhered to as well as the other conventions.
+@c FIXME
+
+The default value is @samp{""}.
@subsection ifield
The name of the instruction field that the enum is intended for. This
must be a simple ifield, not a multi-ifield.
+@anchor{a-enum-values}
@subsection values
A list of possible values. Each element has one of the following forms:
The syntax for numbers is Scheme's, so hex numbers are @code{#xnnnn}.
A value of @code{-} means use the next value (previous value plus 1).
+Enum values currently always have mode @samp{INT}.
+
Example:
@example
@end example
This defines an instruction enum for field @samp{f-op1} with values
-OP1_0, OP1_1, ..., OP1_15.
+OP1_0, OP1_1, ..., OP1_15. These values can be directly used in
+instruction format specs. This applies to ``instruction enums'' only.
+One can use normal enums in instruction format specs but one needs to
+explicitly specify the ifield, e.g. (f-op1 OP1_0).
+
+@node Keywords
+@section Keywords
+@cindex Keywords
+
+Keywords are like enums, @xref{Enumerated constants},
+but they also cause a table of names of each value to be generated.
+This is useful for things like registers where you want
+arbitrary tools to have access to the table of names.
+
+The syntax for defining keywords changed from RTL version 0.7 to
+RTL version 0.8. @xref{RTL Versions}.
+
+RTL version 0.7 syntax:
+
+@example
+(define-keyword
+ (name keyword-name)
+ (comment "description")
+ (attrs attribute-list)
+ (mode mode-name)
+ (print-name "prefix-for-enum-values-without-trailing-dash")
+ (prefix "prefix-for-names-in-string-table")
+ (values value-list)
+)
+@end example
+
+RTL version 0.8 syntax:
+
+@example
+(define-keyword
+ (name keyword-name)
+ (comment "description")
+ (attrs attribute-list)
+ (mode mode-name)
+ (enum-prefix "prefix-for-enum-values")
+ (name-prefix "prefix-for-names-in-string-table")
+ (values value-list)
+)
+@end example
+
+Note that @samp{print-name} has been replaced with @samp{enum-prefix}
+and @samp{prefix} has been replaced with @samp{name-prefix}.
+
+Furthermore, there is also a difference between the behavior of
+@samp{print-name} and @samp{enum-prefix}.
+When computing complete enum names with @samp{print-name},
+CGEN adds a @samp{-} between the prefix and the enum name.
+CGEN does not insert a @samp{-} with @samp{enum-prefix}.
+
+@subsection mode
+
+This is the mode to reference and record the keyword's value in.
+The default is @samp{INT}. It is normally not necessary to use
+something else.
+
+@subsection print-name
+
+@emph{NOTE: This is for RTL version 0.7 only.}
+
+This value plus a trailing @samp{-} is passed as the @samp{prefix}
+parameter when defining the corresponding enum. @xref{Enumerated constants}.
+
+Convention requires @samp{print-name} not contain any lowercase characters.
+
+The default value is the keyword's name in uppercase.
+
+@subsection prefix
+
+@emph{NOTE: This is for RTL version 0.7 only.}
+
+@samp{prefix} is the assembler prefix common to each of the index names,
+and is added to name in the generated lookup table.
+For example, SPARC registers usually begin with @samp{"%"}.
+It is @emph{not} added to the corresponding enum value names.
+
+The default value is @samp{""}.
+
+@subsection enum-prefix
+
+@emph{NOTE: This is for RTL version 0.8 and higher.
+You must specify the RTL version at the top of the description file.}
+
+This value is passed as the @samp{prefix} parameter when defining the
+corresponding enum. @xref{Enumerated constants}.
+
+@emph{NOTE:} Unlike @samp{print-name} in RTL version @samp{0.7},
+@samp{-} is not appended when defining the corresponding enum.
+
+Convention requires @samp{enum-prefix} not contain any lowercase characters.
+
+The default value is the keyword's name in uppercase + @samp{-}.
+
+@subsection name-prefix
+
+@emph{NOTE: This is for RTL version 0.8 and higher.
+You must specify the RTL version at the top of the description file.}
+
+@samp{name-prefix} is the assembler prefix common to each of the index names,
+and is added to name in the generated lookup table.
+For example, SPARC registers usually begin with @samp{"%"}.
+It is @emph{not} added to the corresponding enum value names.
+
+The default value is @samp{""}.
+
+@subsection values
+
+The @samp{values} field has the same syntax as the @samp{values}
+field of @samp{define-enum}. @xref{a-enum-values, Enum Values}.
+
+Example from M32R:
+
+@smallexample
+(define-keyword
+ (name gr-names)
+ (enum-prefix H-GR-)
+ (values (fp 13) (lr 14) (sp 15)
+ (r0 0) (r1 1) (r2 2) (r3 3) (r4 4) (r5 5) (r6 6) (r7 7)
+ (r8 8) (r9 9) (r10 10) (r11 11) (r12 12) (r13 13) (r14 14) (r15 15))
+)
+@end smallexample
+
+Referencing enum values from this keyword in the .cpu file would use
+@samp{H-GR-} + @samp{register-name}. E.g., H-GR-r12.
@node Instruction operands
@section Instruction operands
The required elements are: @code{name}, @code{type}, @code{mode},
and if @code{type} is not a scaler @code{index}.
-There is no convention for prefixing operands,
-and generally for readability's sake operands don't have a prefix.
-
@subsection name
This is the name of the operand as a Scheme symbol.
like @samp{o-} would avoid collisions with other semantic elements, but
operands are used often enough that any prefix is a hassle.
+Note that if you @emph{do} decide to prefix operand names, e.g. use
+a style like @samp{o-foo}, then you will need to remember to use the
+@samp{$@{o-foo@}} form in the assembler syntax and not the @samp{$o-foo}
+form because the latter only takes alphanumeric characters.
+@xref{assembler-syntax, syntax}.
+
@subsection attrs
A list of attributes. In addition to attributes defined for the operand,
An assertion of what values any instruction fields will or will not have
in the containing instruction.
-??? A better name for this might be "constraint".
+@anchor{ifield-assertion-rtl}
+The syntax of the assertion is a restricted subset of RTL.
+It may only contain @samp{andif}, @samp{eq}, @samp{ne},
+and may only use scalar instruction fields
+@footnote{A scalar instruction field is a simple ifield
+(not a multi or derived ifield), or a multi-ifield consisting
+of only simple ifields.}
+and integers as operands.
+Furthermore, ifields must be specified in the first operand of
+@samp{eq}, @samp{ne}.
+
+As a degenerate case, a single non-zero integer, is also supported,
+meaning the assertion passes.
+
+In addition, the assertion may also use @samp{member}.
+
+Syntax: @code{(member ifield-name (number-list value1 [value2 ...]))}
+@footnote{Like all rtx, the full syntax is
+@code{(member [(options)] [member-mode] ifield-name (number-list [(options)] [numlist-mode] value1 [value2 ...]))},
+but @samp{options} and @samp{mode} are not really useful here.
+@samp{member-mode} is @samp{BI}, since the result is a boolean value.}
+
+The result of @samp{member} is one if the value of the ifield
+is a member of the list @code{(value1 [value2 ...])}.
+Otherwise the result is zero.
+
+If the result of the assertion is non-zero, the assertion passes.
+Otherwise it fails, and the instruction is not selected for that
+particular bit pattern.
@subsection getter
For macro-instructions, don't use during disassembly.
@end table
+@anchor{assembler-syntax}
@subsection syntax
This is a character string consisting of raw characters and operands.
This is an expression with a boolean result that is run as the final
part of instruction decoding to verify a match.
+The syntax of the assertion is a restricted subset of RTL.
+@xref{ifield-assertion-rtl}.
+
@subsection semantics
@cindex Semantics
@c ??? Endianness issues have yet to be decided.
@c Blech. Time to decide them.
-@item (sequence mode ((mode1 local1) ...) expr1 expr2 ...)
-Execute @samp{expr1}, @samp{expr2}, etc. sequentially. @samp{mode} is the
-mode of the result, which is defined to be that of the last expression.
+@item (sequence mode ((mode1 local1) ...) expr1 ...)
+Execute @samp{expr1}, @samp{expr2}, etc. sequentially.
+At least one expression must be specified, even if the result
+mode is @samp{VOID}.
+
+The result, if non-void-mode, is the value of the last expression.
+
+@samp{mode} is the mode of the result.
+If @samp{mode} is elided it is set to @samp{VOID} (void mode).
+
`@code{((mode1 local1) ...)}' is a set of local variables.
@item (parallel mode empty expr1 ...)
Execute @samp{expr1}, @samp{expr2}, etc. in parallel. All inputs are
-read before any output is written. @samp{empty} must be @samp{()} and
-is present for consistency with @samp{sequence}. @samp{mode} must be
-@samp{VOID} (void mode).
+read before any output is written.
+At least one expression must be specified.
+
+@samp{empty} must be @samp{()} and
+is present for consistency with @samp{sequence}.
+
+@samp{mode} must be @samp{VOID} (void mode), or it can be elided.
+
+@item (do-count mode iteration-variable number-of-iterations expr1 ...)
+This is a simple looping operation.
+Execute @samp{expr1}, @samp{expr2}, etc. the specified number of times.
+At least one expression must be specified.
+
+@samp{iteration-variable} will contain the iteration number and is
+available for use in expressions. It has mode @samp{INT}.
+It's value will be 0 ... @samp{number-of-iterations} - 1.
+
+@samp{number-of-iterations} is an rtl expression of mode INT
+(or a compatible mode). It is computed once and may not be modified
+inside the loop.
+
+@samp{mode} must be @samp{VOID} (void mode), or it can be elided.
@item (unop mode operand)
-Perform a unary arithmetic operation. @samp{unop} is one of @code{neg},
+Perform a unary arithmetic operation.
+
+@samp{unop} is one of @code{neg},
@code{abs}, @code{inv}, @code{not}, @code{zflag}, @code{nflag}.
@code{zflag} returns a bit indicating if @samp{operand} is
zero. @code{nflag} returns a bit indicating if @samp{operand} is
whereas @code{not} returns its logical negation.
@item (binop mode operand1 operand2)
-Perform a binary arithmetic operation. @samp{binop} is one of
+Perform a binary arithmetic operation.
+
+@samp{binop} is one of
@code{add}, @code{sub}, @code{and}, @code{or}, @code{xor}, @code{mul},
@code{div}, @code{udiv}, @code{mod}, @code{umod}.
@item (binop-with-bit mode operand1 operand2 operand3)
Same as @samp{binop}, except taking 3 operands. The third operand is
-always a single bit. @samp{binop-with-bit} is one of @code{addc},
+always a single bit.
+
+@samp{binop-with-bit} is one of @code{addc},
@code{addc-cflag}, @code{addc-oflag}, @code{subc}, @code{subc-cflag},
@code{subc-oflag}.
Perform a shift operation.
@samp{operand1} is shifted (or rotated) by the amount specified
in @samp{operand2}.
+
@samp{shiftop} is one of @code{sll}, @code{srl}, @code{sra},
@code{ror}, @code{rol}.
+
@samp{mode} must match the mode of @samp{operand1}.
The mode of @samp{operand1} may be any integral mode.
The mode of @samp{operand2} may be any integral mode, and need not match
If the architecture handles negative or large shift amounts,
that needs to be handled in the surrounding RTL.
-@item (boolifop mode operand1 operand2)
-Perform a sequential boolean operation. @samp{operand2} is not processed
-if @samp{operand1} ``fails''. @samp{boolifop} is one of @code{andif},
-@code{orif}.
-@c Extend to handle more than two operands?
+@item (andif mode operand1 operand2)
+Evaluate @samp{operand1}.
+If it evaluates to zero the result is zero,
+and @samp{operand2} is not evaluated.
+If @samp{operand1} evaluates to non-zero, then evaluate @samp{operand2}.
+If it evaluates to non-zero the result is one,
+otherwise the result is zero.
+
+The mode of the result is @samp{BI}.
+@samp{mode} is generally elided or is @samp{BI}.
+
+@item (orif mode operand1 operand2)
+Evaluate @samp{operand1}.
+If it evaluates to non-zero the result is one,
+and @samp{operand2} is not evaluated.
+If @samp{operand1} evaluates to zero, then evaluate @samp{operand2}.
+If it evaluates to non-zero the result is one,
+otherwise the result is zero.
+
+The mode of the result is @samp{BI}.
+@samp{mode} is generally elided or is @samp{BI}.
@item (convop mode operand)
-Perform a mode->mode conversion operation. @samp{convop} is one of
+Perform a mode->mode conversion operation.
+
+@samp{convop} is one of
@code{ext}, @code{zext}, @code{trunc}, @code{float}, @code{ufloat},
@code{fix}, @code{ufix}.
@item (cmpop mode operand1 operand2)
-Perform a comparison. @samp{cmpop} is one of @code{eq}, @code{ne},
+Perform a comparison.
+
+@samp{cmpop} is one of @code{eq}, @code{ne},
@code{lt}, @code{le}, @code{gt}, @code{ge}, @code{ltu}, @code{leu},
@code{gtu}, @code{geu}.
@c floating point compare-unordered?
+If the comparison succeeds the result is one,
+otherwise the result is zero.
+The mode of the result is @samp{BI}.
+
@item (mathop mode operand)
-Perform a mathematical operation. @samp{mathop} is one of @code{sqrt},
-@code{cos}, @code{sin}.
+Perform a mathematical operation.
+
+@samp{mathop} is one of @code{sqrt}, @code{cos}, @code{sin}.
@item (if mode condition then [else])
Standard @code{if} statement.
Skip the next instruction if @samp{yes?} is non-zero. This rtx is
an experiment and will probably change.
-@item (attr mode kind attr-name)
-Return the value of attribute @samp{attr-name} in mode
-@samp{mode}. @samp{kind} must currently be @samp{insn}: the current
-instruction.
-
@item (symbol name)
Return a symbol with value @samp{name}, for use in attribute
processing. This is equivalent to @samp{quote} in Scheme but
@samp{quote} sounds too jargonish.
-@item (eq-attr mode attr-name value)
-Return non-zero if the value of attribute @samp{attr-name} is
-@samp{value}. If @samp{value} is a list return ``true'' if
-@samp{attr-name} is any of the listed values.
+@item (int-attr mode object attr-name)
+Return the value of attribute @samp{attr-name} in mode @samp{mode}.
+@samp{object} must currently be @samp{(current-insn)}, the current instruction,
+or @samp{(current-mach)}, the current machine.
+The attribute's value must be representable as an integer.
+
+@item (eq-attr mode object attr-name value)
+Return non-zero if the value of attribute @samp{attr-name} of
+object @samp{object} is @samp{value}.
+
+@emph{NOTE:} List values of @samp{value} may be changed to allow use the
+@samp{number-list} rtx function.
+If @samp{value} is a list return ``true'' if the attribute is any of
+the listed values. But this is not implemented yet.
@item (index-of operand)
Return the index of @samp{operand}. For registers this is the register number.
@item a memory reference, created with (mem mode address)
@item a constant, created with (const mode value)
@item a `sequence' local variable
+@item a `do-count' iteration variable
@item another expression
@end itemize
OSDN Git Service
