CGEN's Register Transfer Language
*********************************

CGEN uses a variant of GCC's Register Transfer Language as the basis for its CPU description language.

RTL Introduction
================

The description language, or RTL (While RTL stands for Register Transfer Language, it is also used to denote the CPU description language as a whole.), needs to support the definition of all the architectural and implementation features of a CPU, as well as enough information for all intended applications.  At present this is just the opcodes table and an ISA level simulator, but it is not intended that applications be restricted to these two areas.  The goal is having an application independent description of the CPU.  In the end that's a lot to ask for from one language.  Certainly gate level specification of a CPU is not attempted!

The syntax of the language is inspired by GCC's RTL and by the Scheme programming language, theoretically taking the best of both.  To what extent that is true, and to what extent that is sufficient inspiration is certainly open to discussion.  In actuality, there isn't much difference here from GCC's RTL that is attributable to being Scheme-ish.  One important Scheme-derived concept is arbitrary precision of constants. Sign or zero extension of constants in GCC has always been a source of problems.  In CGEN'S RTL constants have modes and there are both signed and unsigned modes.

Here is a graphical layout of the hierarchy of elements of a .cpu file.

                                architecture
                               /            \
                         cpu-family1        cpu-family2  ...
                           /     \            /      \
                     machine1   machine2  machine3   ...
                      /   \
                  model1  model2  ...

Each of these elements is explained in more detail below.  The architecture is one of sparc, m32r, etc.  Within the sparc architecture, cpu-family might be sparc32, sparc64, etc.  Within the sparc32 CPU family, the machine might be sparc-v8, sparclite, etc.  Within the sparc-v8 machine classification, model might be hypersparc, supersparc, etc.

Instructions form their own hierarchy as each instruction may be supported by more than one machine.  Also, some architectures can handle more than one instruction set on one chip (e.g. ARM).

                          isa
                           |
                      instruction
                         /   \
                  operand1  operand2  ...
                     |         |
              hw1+ifield1   hw2+ifield2  ...

Each of these elements is explained in more detail below.

Trade-offs
==========

While CGEN is written in Scheme, this is not a requirement.  The description language should be considered absent of any particular implementation, though certainly some things were done to simplify reading .cpu files with Scheme.  Scheme related choices have been made in areas that have no serious impact on the usefulness of the CPU description language.  Places where that is not the case need to be revisited, though there currently are no known ones.

One place where the Scheme implementation influenced the design of CGEN's RTL is in the handling of modes.  The Scheme implementation was simplified by treating modes as an explicit argument, rather than as an optional suffix of the operation name.  For example, compare (add SI dr sr) in CGEN versus (add:SI dr sr) in GCC RTL.  The mode is treated as optional so a shorthand form of (add dr sr) works.

Rules and notes
===============

A few basic guidelines for all entries:

  * Names must be valid Scheme symbols.

  * Comments are used, for example, to comment the generated C code (It is possible to produce a reference manual from .cpu files and such an application wouldn't be a bad idea.).

  * Comments may be any number of lines, though generally succinct comments are preferable (It would be reasonable to have a short form and a long form of comment. Either as two entries are as one entry with the short form separated from the long form via some delimiter (say the first newline).).

  * Everything is case sensitive. (??? This is true in RTL, though some apps add symbols and convert case that can cause collisions.)

  * While "_" is a valid character to use in symbols, "-" is preferred

  * Except for the comment and attrs fields and unless otherwise specified all fields must be present.

  * Symbols used to be allowed anywhere a string can be used. This is what earlier versions of Guile supported. Guile is more strict now, so this relaxation is gone. The reverse is generally not allowed, strings can't be used in place of symbols.

  * Use () or #f to indicate ``not specified'', unless otherwise specified.  This is not necessary for define-foo elements, one can just elide the entry, but it is useful for define-*-foo that take a fixed number of arguments.  E.g., define-normal-ifield. Whether to use () or #f is largely a matter of style.

Definitions
===========

Each entry has the same format: (define-foo arg1 arg2 ...), where foo designates the type of entry (e.g. define-insn).  In the general case each argument is a name/value pair expressed as (name value). (*Note: Another style in common use is `:name value' and doesn't require parentheses.  Maybe that would be a better way to go here.  The current style is easier to construct from macros though.)

While the general case is flexible, it also is excessively verbose in the normal case.  To reduce this verbosity, a second version of most define-foo's, generally named define-normal-foo or define-simple-foo, exist that takes a fixed number of positional arguments.  With pmacros they can be even shortened further to just their acronym.  E.g. define-normal-ifield -> dnf. Ports are free to write their own preprocessor macros to simplify things further as desired. See sections titled ``Simplification macros'' later in this chapter.

Attributes
==========

Attributes are used throughout for specifying various properties. For portability reasons attributes can only have 32 bit integral values (signed or unsigned).

There are four kinds of attributes: boolean, integer, enumerated, and bitset. Boolean attributes can be achieved via others, but they occur frequently enough that they are special cased (and one bit can be used to record them). Bitset attributes are a useful simplification when one wants to indicate an object can be in one of many states (e.g. an instruction may be supported by multiple machines).

String attributes might be a useful addition. Another useful addition might be functional attributes (the attribute is computed at run-time - currently all attributes are computed at compile time).  One way to implement functional attributes would be to record the attributes as byte-code and lazily evaluate them, caching the results as appropriate.  The syntax has been done to not preclude either as an upward compatible extension.

Attributes must be defined before they can be used. There are several predefined attributes for entry types that need them (instruction field, hardware, operand, and instruction).  Predefined attributes are documented in each relevant section.

In C applications an enum is created that defines all the attributes. Applications that wish to be architecture independent need the attribute to have the same value across all architectures.  This is achieved by giving the attribute the INDEX attribute (Yes, attributes can have attributes.), which specifies the enum value must be fixed across all architectures.

Convention requires attribute names consist of uppercase letters, numbers, "-", and "_", and must begin with a letter. To be consistent with Scheme, "-" is preferred over "_".

Boolean Attributes
------------------

Boolean attributes are defined with:

     (define-attr
       (type boolean)
       (for user-list)
       (name attribute-name)
       (comment "attribute comment")
       (attrs attribute-attributes)
     )

The default value of boolean attributes is always false.  This can be relaxed, but it's one extra complication that is currently unnecessary. Boolean attributes are specified in either of two forms: (NAME expr), NAME, and !NAME. The first form is the canonical form.  The latter two are shorthand versions. NAME means "true" and !NAME means "false". expr is an expression that evaluates to 0 for false and non-zero for true  (The details of expr is still undecided.).

user-list is a space separated list of entry types that will use the attribute.  Possible values are: attr, enum, cpu, mach, model, ifield, hardware, operand, insn and macro-insn.  If omitted all are considered users of the attribute.

Integer Attributes
------------------

Integer attributes are defined with:

     (define-attr
       (type integer)
       (for user-list)
       (name attribute-name)
       (comment "attribute comment")
       (attrs attribute-attributes)
       (default expr)
     )

If omitted, the default is 0.

(*Note: The details of expr is still undecided. For now it must be an integer.)

Integer attributes are specified with (NAME expr).

Enumerated Attributes
---------------------

Enumerated attributes are the same as integer attributes except the range of possible values is restricted and each value has a name. Enumerated attributes are defined with

     (define-attr
       (type enum)
       (for user-list)
       (name attribute-name)
       (comment "attribute comment")
       (attrs attribute-attributes)
       (values enum-value1 enum-value2 ...)
       (default expr)
     )

If omitted, the default is the first specified value.

(*Note: The details of expr is still undecided. For now it must be the name of one of the specified values.)

Enum attributes are specified with (NAME expr).

Bitset Attributes
-----------------

Bitset attributes are for situations where you want to indicate something is a subset of a small set of possibilities.  The MACH attribute uses this for example to allow specifying which of the various machines support a particular insn. (*Note: At present the maximum number of possibilities is 32. This is an implementation restriction which can be relaxed, but there's currently no rush.)

Bitset attributes are defined with:

     (define-attr
       (type bitset)
       (for user-list)
       (name attribute-name)
       (comment "attribute comment")
       (attrs attribute-attributes)
       (values enum-value1 enum-value2 ...)
       (default default-name)
     )

default-name must be the name of one of the specified values.  If omitted, it is the first value.

Bitset attributes are specified with (NAME val1,val2,...).  There must be no spaces in ``val1,val2,...'' and each value must be a valid Scheme symbol.

(*Note: It's not clear whether allowing arbitrary expressions will be useful here, but doing so is not precluded.  For now each value must be the name of one of the specified values.)

Architecture variants
=====================

The base architecture and its variants are described in four parts: define-arch, define-isa, define-cpu, and define-mach.

define-arch
-----------

define-arch describes the overall architecture, and must be present.

The syntax of define-arch is:

     (define-arch
       (name architecture-name) ; e.g. m32r
       (comment "description")  ; e.g. "Mitsubishi M32R"
       (attrs attribute-list)
       (default-alignment aligned|unaligned|forced)
       (insn-lsb0? #f|#t)
       (machs mach-name-list)
       (isas isa-name-list)
     )

default-alignment
.................

Specify the default alignment to use when fetching data (and instructions) from memory.  At present this can't be overridden, but support can be added if necessary.  The default is aligned.

insn-lsb0?
..........

Specifies whether the most significant or least significant bit in a word is bit number 0.  Generally this should conform to the convention in the architecture manual.  This is independent of endianness and is an architecture wide specification.  There is no support for using different bit numbering conventions within an architecture.

Instruction fields are always numbered beginning with the most significant bit.  That is, the `start' of a field is always its most significant bit.  For example, a 4 bit field in the uppermost bits of a 32 bit instruction would have a start/length of (31 4) when insn-lsb0? = #t, and (0 4) when insn-lsb0? = #f.

mach-name-list
..............

The list of names of machines in the architecture. There should be one entry for each define-mach.

isa-name-list
.............

The list of names of instruction sets in the architecture. There must be one for each define-isa. An example of an architecture with more than one is the ARM which has a 32 bit instruction set and a 16 bit "Thumb" instruction set (the sizes here refer to instruction size).

define-isa
----------

define-isa describes aspects of the instruction set. A minimum of one ISA must be defined.

The syntax of define-isa is:

     (define-isa
       (name isa-name)
       (comment "description")
       (attrs attribute-list)
       (default-insn-word-bitsize n)
       (default-insn-bitsize n)
       (base-insn-bitsize n)
       ; (decode-assist (b0 b1 b2 ...)) ; generally unnecessary
       (liw-insns n)
       (parallel-insns n)
       (condition ifield-name expr)
       (setup-semantics expr)
       ; (decode-splits decode-split-list) ; support temporarily disabled
       ; ??? missing here are fetch/execute specs
     )

default-insn-word-bitsize
.........................

Specifies the default size of an instruction word in bits. This affects the numbering of field bits in words beyond the base instruction. See 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.

default-insn-bitsize
....................

The default size of an instruction in bits. It is generally the size of the smallest instruction. It is used when parsing instruction fields. It is also used by the disassembler to know how many bytes to skip for unrecognized instructions.

base-insn-bitsize
.................

The minimum size of an instruction, in bits, to fetch during execution. If the architecture has a variable length instruction set, this is the size of the initial word to fetch.  There is no need to specify the maximum length of an instruction, that can be computed from the instructions.  Examples:

i386
     8

M68k
     16

SPARC
     32

M32R
     32

The M32R case is interesting because instructions can be 16 or 32 bits. However instructions on 32 bit boundaries can always be fetched 32 bits at a time as 16 bit instructions always come in pairs.

decode-assist
.............

Override CGEN's heuristics about which bits to initially use to decode instructions in a simulator.  For example on the SPARC these are bits: 31 30 24 23 22 21 20 19.  The entire decoder can be machine generated, so this field is entirely optional.  Since the heuristics are quite good, you should only use this field if you have evidence that you can pick a better set, in which case the CGEN developers would like to hear from you!

??? It might be useful to provide greater control, but this is sufficient for now.

It is okay if the opcode bits are over-specified for some instructions. It is also okay if the opcode bits are under-specified for some instructions. The machine generated decoder will properly handle both these situations. Just pick a useful number of bits that distinguishes most instructions. It is usually best to not pick more than 8 bits to keep the size of the initial decode table down.

Bit numbering is defined by the insn-lsb0? field.

liw-insns
.........

The number of instructions the CPU always fetches at once.  This is intended for architectures like the M32R, and does not refer to a CPU's ability to pre-fetch instructions.  The default is 1.

parallel-insns
..............

The maximum number of instructions the CPU can execute in parallel.  The default is 1.

??? Rename this to max-parallel-insns?

condition
.........

Some architectures like ARM and ARC conditionally execute every instruction based on the condition specified by one instruction field. The condition spec exists to support these architectures. ifield-name is the name of the instruction field denoting the condition and expression is an RTL expressions that returns the value of the condition (false=zero, true=non-zero).

setup-semantics
...............

Specify a statement to be performed prior to executing particular instructions. This is used, for example, on the ARM where the value of the program counter (general register 15) is a function of the instruction (it is either pc+8 or pc+12, depending on the instruction).

decode-splits
.............

Specify a list of field names and values to split instructions up by. This is used, for example, on the ARM where the behavior of some instructions is quite different when the destination register is r15 (the pc).

The syntax is:

     (decode-splits
       (ifield1-name
        constraints
        ((split1-name (value1 value2 ...)) (split2-name ...)))
       (ifield2-name
        ...)
     )

constraints is work-in-progress and should be () for now.

One copy of each instruction satisfying constraint is made for each specified split.  The semantics of each copy are then simplified based on the known values of the specified instruction field.

define-cpu
----------

define-cpu defines a ``CPU family'' which is a programmer specified collection of related machines.  What constitutes a family is work-in-progress however it is intended to distinguish things like sparc32 vs sparc64.  Machines in a family are sufficiently similar that the simulator semantic code can handle any differences at run time.  At least that's the current idea.  A minimum of one CPU family must be defined. (FIXME: Using "cpu" in "cpu-family" here is confusing. Need a better name.  Maybe just "family"?)

The syntax of define-cpu is:

     (define-cpu
       (name cpu-name)
       (comment "description")
       (attrs attribute-list)
       (endian big|little|either)
       (insn-endian big|little|either)
       (data-endian big|little|either)
       (float-endian big|little|either)
       (word-bitsize n)
       (insn-chunk-bitsize n)
       (parallel-insns n)
       (file-transform transformation)
     )

endian
......

The endianness of the architecture is one of three values: big, little and either.

An architecture may have multiple endiannesses, including one for each of: instructions, integers, and floats (not that that's intended to be the complete list).  These are specified with insn-endian, data-endian, and float-endian respectively.

Possible values for insn-endian are: big, little, and either.  If missing, the value is taken from endian.

Possible values for data-endian and float-endian are: big, big-words, little, little-words and either. If big-words then each word is little-endian. If little-words then each word is big-endian. If missing, the value is taken from endian.

??? Support for these is work-in-progress.  All forms are recognized by the .cpu file reader, but not all are supported internally.

word-bitsize
............

The number of bits in a word.  In GCC, this is BITS_PER_WORD.

insn-chunk-bitsize
..................

The number of bits in an instruction word chunk, for purposes of per-chunk endianness conversion.  The default is zero, meaning no chunking is required.

parallel-insns
..............

This is the same as the parallel-insns spec of define-isa. It allows a CPU family to override the value.

file-transform
..............

Specify the file name transformation of generated code.

Each generated file has a named related to the ISA or CPU family. Sometimes generated code needs to know the name of another generated file (e.g. #include's). At present file-transform specifies the suffix.

For example, M32R/x generated files have an `x' suffix, as in cpux.h for the cpu.h header.  This is indicated with (file-transform "x").

??? Ideally generated code wouldn't need to know anything about file names. This breaks down for #include's.  It can be fixed with symlinks or other means.

define-mach
-----------

define-mach defines a distinct variant of a CPU.  It currently has a one-to-one correspondence with BFD's "mach number".  A minimum of one mach must be defined.

The syntax of define-mach is:

     (define-mach
       (name mach-name)
       (comment "description")
       (attrs attribute-list)
       (cpu cpu-family-name)
       (bfd-name "bfd-name")
       (isas isa-name-list)
     )

bfd-name
........

The name of the mach as used by BFD.  If not specified the name of the mach is used.

isas
....

List of names of ISA's the machine supports.

Model variants
==============

For each `machine', as defined here, there is one or more `models'. There must be at least one model for each machine. (*Note: There could be a default, but requiring one doesn't involve that much extra typing and forces the programmer to at least think about such things.)

     (define-model
       (name model-name)
       (comment "description")
       (attrs attribute-list)
       (mach machine-name)
       (state (variable-name-1 variable-mode-1) ...)
       (unit name "comment" (attributes)
     	issue done state inputs outputs profile)
     )

mach
----

The name of the machine the model is an implementation of.

state
-----

A list of variable-name/mode pairs for recording global function unit state.  For example on the M32R the value is (state (h-gr UINT)) and is a bitmask of which register(s) are the targets of loads and thus subject to load stalls.

unit
----

Specifies a function unit.  Any number of function units may be specified. The u-exec unit must be specified as it is the default.

The syntax is:

       (unit name "comment" (attributes)
          issue done state inputs outputs profile)

issue is the number of operations that may be in progress. It originates from GCC function unit specification.  In general the value should be 1.

done is the latency of the unit.  The value is the number of cycles until the result is ready.

state has the same syntax as the global model `state' and is a list of variable-name/mode pairs.

inputs is a list of inputs to the function unit. Each element is (operand-name mode default-value).

outputs is a list of outputs of the function unit. Each element is (operand-name mode default-value).

profile is an rtl-code sequence that performs function unit modeling.  At present the only possible value is () meaning invoke a user supplied function named <cpu>_model_<mach>_<unit>.

The current function unit specification is a first pass in order to achieve something that moderately works for the intended purpose (cycle counting on the simulator).  Something more elaborate is on the todo list but there is currently no schedule for it.  The new specification must try to be application independent.  Some known applications are: cycle counting in the simulator, code scheduling in a compiler, and code scheduling in a JIT simulator (where speed of analysis can be more important than getting an optimum schedule).

The inputs/outputs fields are how elements in the semantic code are mapped to function units.  Each input and output has a name that corresponds with the name of the operand in the semantics.  Where there is no correspondence, a mapping can be made in the unit specification of the instruction (see the subsection titled ``Timing'').

Another way to achieve the correspondence is to create separate function units that contain the desired input/output names.  For example on the M32R the u-exec unit is defined as:

     (unit u-exec "Execution Unit" ()
        1 1 ; issue done
        () ; state
        ((sr INT -1) (sr2 INT -1)) ; inputs
        ((dr INT -1)) ; outputs
        () ; profile action (default)
     )

This handles instructions that use sr, sr2 and dr as operands.  A second function unit called u-cmp is defined as:

     (unit u-cmp "Compare Unit" ()
        1 1 ; issue done
        () ; state
        ((src1 INT -1) (src2 INT -1)) ; inputs
        () ; outputs
        () ; profile action (default)
     )

This handles instructions that use src1 and src2 as operands.  The organization of units is arbitrary.  On the M32R, src1/src2 instructions are typically compare instructions so a separate function unit was created for them.  Current limitations require that each hardware item behind the operands must be marked with the attribute PROFILE and the hardware item must not be scalar.

Hardware elements
=================

The elements of hardware that make up a CPU are defined with define-hardware.  Examples of hardware elements include registers, condition bits, immediate constants and memory.

Instruction fields that provide numerical values (``immediate constants'') aren't really elements of the hardware, but it simplifies things to think of them this way.  Think of them as constant generators (A term borrowed from the book on the Bulldog compiler and perhaps other sources.).

Hardware elements are defined with:

     (define-hardware
       (name hardware-name)
       (comment "description")
       (attrs attribute-list)
       (semantic-name hardware-semantic-name)
       (type type-name type-arg1 type-arg2 ...)
       (indices index-type index-arg1 index-arg2 ...)
       (values values-type values-arg1 values-arg2 ...)
       (handlers handler1 handler2 ...)
       (get (args) expression)
       (set (args) expression)
       (layout layout-list)
     )

The only required elements are name and type. Convention requires hardware-name begin with h-.

attrs
-----

List of attributes. There are several predefined hardware attributes:

  - MACH

     A bitset attribute used to specify which machines have this hardware element. Do not specify the MACH attribute if the value is "all machs".

     Usage: (MACH mach1,mach2,...) There must be no spaces in ``mach1,mach2,...''.

  - CACHE-ADDR

     A hint to the simulator semantic code generator to tell it it can record the address of a selected register in an array of registers.  This speeds up simulation by moving the array computation to extraction time. This attribute is only useful to register arrays and cannot be specified with VIRTUAL (??? revisit).

  - PROFILE

     This attribute must be present for hardware elements to which references are profiled.  Beware, this is work-in-progress.  If you use this attribute it is likely you have to hack CGEN.  (Please submit patches.)

  - VIRTUAL

     The hardware element doesn't require any storage. This is used when you want a value that is derived from some other value. If VIRTUAL is specified, get and set specs must be provided.

type
----

This is the type of hardware.  Current values are: pc, register, memory, and immediate.

For pc, see Program counter.

For registers the syntax is one of:

     (register mode [(number)])
     (register (mode bits) [(number)])

where (number) is the number of registers and is optional. If omitted, the default is (1). The second form is useful for describing registers with an odd (as in unusual) number of bits. mode for the second form must be one of INT or UINT. Since these two modes don't have an implicit size, they cannot be used for the first form.

For memory the syntax is:

     (memory mode (size))

where (size) is the size of the memory in mode units. In general mode should be QI.

For immediates the syntax is one of

     (immediate mode)
     (immediate (mode bits))

The second form is for values for which a mode of that size doesn't exist. mode for the second form must be one of INT or UINT. Since these two modes don't have an implicit size, they cannot be used for the first form.

??? There's no real reason why a mode like SI can't be used for odd-sized immediate values.  The bits field indicates the size and the mode field indicates the mode in which the value will be used, as well as its signedness.  This would allow removing INT/UINT for this purpose.  On the other hand, a non-width specific mode allows applications to choose one (a simulator might prefer to store immediates in an `int' rather than, say, char if the specified mode was QI).

indices
-------

Specify names for individual elements with the indices spec. It is only valid for registers with more than one element.

The syntax is:

     (indices index-type arg1 arg2 ...)

where index-type specifies the kind of index and arg1 arg2 ... are arguments to index-type.

The are two supported values for index-type: keyword and extern-keyword.  The difference is that indices defined with keyword are kept internal to the hardware element's definition and are not usable elsewhere, whereas extern-keyword specifies a set of indices defined elsewhere.

keyword
.......

     (indices keyword "prefix" ((name1 value1) (name2 value2) ...))

prefix is the common prefix for each of the index names. For example, SPARC registers usually begin with "%".

Each (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.

Example from Thumb:

     (define-hardware
       (name h-gr-t)
       (comment "Thumb's general purpose registers")
       (attrs (ISA thumb) VIRTUAL) ; ??? CACHE-ADDR should be doable
       (type register WI (8))
       (indices keyword ""
     	   ((r0 0) (r1 1) (r2 2) (r3 3) (r4 4) (r5 5) (r6 6) (r7 7)))
       (get (regno) (reg h-gr regno))
       (set (regno newval) (set (reg h-gr regno) newval))
     )

extern-keyword
..............

     (indices extern-keyword keyword-name)

Example from M32R:

     (define-keyword
       (name gr-names)
       (print-name h-gr)
       (prefix "")
       (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))
     )

     (define-hardware
       (name h-gr)
       (comment "general registers")
       (attrs PROFILE CACHE-ADDR)
       (type register WI (16))
       (indices extern-keyword gr-names)
     )

values
------

Specify a list of valid values with the values spec.

The syntax is identical to the syntax for indices. It is only valid for immediates.

Example from sparc64:

     (define-hardware
       (name h-p)
       (comment "prediction bit")
       (attrs (MACH64))
       (type immediate (UINT 1))
       (values keyword "" (("" 0) (",pf" 0) (",pt" 1)))
     )

handlers
--------

The handlers spec is an escape hatch for indicating when a programmer supplied routine must be called to perform a function.

The syntax is:

     (handlers (handler-name1 "function_name1")
                     (handler-name2 "function_name2")
                     ...)

handler-name must be one of parse or print. How function_name is used is application specific, but in general it is the name of a function to call.  The only application that uses this at present is Opcodes.  See the Opcodes documentation for a description of each function's expected prototype.

get
---

Specify special processing to be performed when a value is read with the get spec.

The syntax for scalar registers is:

     (get () (expression))

The syntax for vector registers is:

     (get (index) (expression))

expression is an RTL expression that computes the value to return. The mode of the result must be the mode of the register.

index is the name of the index as it appears in expression.

At present, sequence, parallel, and case expressions are not allowed here.

set
---

Specify special processing to be performed when a value is written with the set spec.

The syntax for scalar registers is:

     (set (newval) (expression))

The syntax for vector registers is:

     (set (index newval) (expression))

expression is an RTL expression that stores newval in the register.  This may involve storing values in other registers as well. expression must be one of set, if, sequence, or case.

index is the name of the index as it appears in expression.

layout
------

For specific hardware elements, specifying a layout is an alternative to providing getter/setter specs.

At present this applies to only register hardware elements, but not the pc.

Some registers are a collection of bits with different meanings. It is often useful to define each field of such a register as its own register.  The layout spec can then be used to build up the outer register from the individual register fields.

The fields are written from least to most significant. Each field is either the name of another hardware register, or a list of (value length) to specify hardwired bits.

A typical example is a ``flags'' register. Here is an example for a fictitious flags register. It is eight bits wide, with the lower four bits having defined values, and the upper four bits hardwired to zero.

     (dsh h-cf "carry flag"    () (register BI))
     (dsh h-sf "sign flag"     () (register BI))
     (dsh h-of "overflow flag" () (register BI))
     (dsh h-zf "zero flag"     () (register BI))
     (define-hardware
       (name flags)
       (type register QI)
       (layout (h-cf h-sf h-of h-zf (0 4)))
     )

Predefined hardware elements
----------------------------

Several hardware types are predefined:

h-uint
     unsigned integer

h-sint
     signed integer

h-memory
     main memory, where ``main'' is loosely defined

h-addr
     data address (data only)

h-iaddr
     instruction address (instructions only)

Program counter
---------------

The program counter must be defined and is not a builtin. If get/set specs are not required, define it as:

     (dnh h-pc "program counter" (PC) (pc) () () ())

If get/set specs are required, define it as:

     (define-hardware
       (name h-pc)
       (comment "<ARCH> program counter")
       (attrs PC)
       (type pc)
       (get () <insert get code here>)
       (set (newval) <insert set code here>)
     )

If the architecture has multiple instruction sets, all must be specified. If they're not, the default is the first one which is often not what you want. Here's an example from arm.cpu:

     (define-hardware
       (name h-pc)
       (comment "ARM program counter (h-gr reg 15)")
       (attrs PC (ISA arm,thumb))
       (type pc)
       (set (newval)
            (if (reg h-tbit)
     	   (set (raw-reg SI h-pc) (and newval -2))
     	   (set (raw-reg SI h-pc) (and newval -4))))
     )

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-hardware pmacro (with alias dnh) takes a fixed set of positional arguments for the typical hardware element. The syntax is:

(dnh name comment attributes type indices values handlers)

Example:

     (dnh h-gr "general registers"
          () ; attributes
          (register WI (16))
          (keyword "" ((fp 13) (sp 15) (lr 14)
                       (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)))
          () ()
     )

This defines an array of 16 registers of mode WI ("word int"). The names of the registers are r0...r15, and registers 13, 14 and 15 also have the names fp, lr and sp respectively.

Scalar registers with no special requirements occur frequently. Macro define-simple-hardware (with alias dsh) is identical to dnh except does not include the indices, values, or handlers specs.

     (dsh h-ibit "interrupt enable bit" () (register BI))

Instruction fields
==================

Instruction fields define the raw bitfields of each instruction. Minimal semantic meaning is attributed to them.  Support is provided for mapping to and from the raw bit pattern and the usable contents, and other simple manipulations.

The syntax for defining instruction fields is:

     (define-ifield
       (name field-name)
       (comment "description")
       (attrs attribute-list)
       (word-offset word-offset-in-bits)
       (word-length word-length-in-bits)
       (start starting-bit-number)
       (length number-of-bits)
       (follows ifield-name)
       (mode mode-name)
       (encode (value pc) (rtx to describe encoding))
       (decode (value pc) (rtx to describe decoding))
     )

The required elements are: name, start, length.

(*Note: Whether to also provide a way to specify instruction formats is not yet clear.  Currently they are computed from the instructions, so there's no current *need* to provided them.  However, providing the ability as an option may simplify other tools CGEN is used to generate.  This simplification would come in the form of giving known names to the formats which CPU reference manuals often do.  Pre-specified instruction formats may also simplify expression of more complicated instruction sets. Providing instruction formats may also simplify the support of really complex ISAs like i386 and m68k).

(*Note: Positional specification simplifies instruction description somewhat in that there is no required order of fields, and a disjunct set of fields can be referred to as one.  On the other hand it can require knowledge of the length of the instruction which is inappropriate in cases like the M32R where the main fields have the same name and "position" regardless of the length of the instruction.  Moving positional specification into instruction formats, whether machine generated or programmer specified, may be done.)

Convention requires field-name begin with f-.

attrs
-----

There are several predefined instruction field attributes:

PCREL-ADDR
     The field contains a PC relative address.  Various CPUs have various offsets from the PC from which the address is calculated.  This is specified in the encode and decode sections.

ABS-ADDR
     The field contains an absolute address.

SIGN-OPT
     The field has an optional sign.  It is sign-extended during extraction. Allowable values are -2^(n-1) to (2^n)-1.

RESERVED
     The field is marked as ``reserved'' by the architecture. This is an informational attribute.  Tools may use it to validate programs, either statically or dynamically.

VIRTUAL
     The field does not directly contribute to the instruction's value.  This is used to simplify semantic or assembler descriptions where a field's value is based on other values.  Multi-ifields are always virtual.

word-offset
-----------

The offset in bits from the start of the instruction to the word containing the field. This must be a multiple of eight.

Either both of word-offset and word-length must be specified or neither of them must be specified.  The presence of word-offset means the long form of specifying the field's position is being used.  If absent then the short form is being used and the value for word-offset is encoded in start.

word-length
-----------

The length in bits of the word containing the field. This must be a multiple of eight.

start
-----

The bit number of the field's most significant bit in the instruction. Bit numbering is determined by the insn-lsb0? field of define-arch.

If using the long form of specifying the field's position (word-offset is present) 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 (see Writing define-ifield).

length
------

The number of bits in the field.  The field must be contiguous.  For non-contiguous instruction fields use ``multi-ifields''.

follows
-------

Optional.  Experimental. This should not be used for the specification of RISC-like architectures. It is an experiment in supporting CISC-like architectures. The argument is the name of the ifield or operand that immediately precedes this one.  In general the argument is an "anyof" operand.  The follows spec allows subsequent ifields to ``float''.

mode
----

The mode the value is to be interpreted in. Usually this is INT or UINT.

The length field specifies the number of bits in the field, and the mode field indicates the mode in which the value will be used, as well as its signedness.  This would allow removing INT/UINT for this purpose.  On the other hand, a non-width specific mode allows applications to choose one (a simulator might prefer to store immediates in an `int' rather than, say, char if the specified mode was QI).

encode
------

An expression to apply to convert from usable values to raw field values.  The syntax is (encode (value pc) expression) or more specifically (encode ((<mode1> value) (IAI pc)) <expression>), where <mode1> is the mode of the ``incoming'' value, and <expression> is an rtx to convert value to something that can be stored in the field.

Example:

     (encode ((SF value) (IAI pc))
     	(cond WI
     	      ((eq value (const SF 1.0)) (const 0))
     	      ((eq value (const SF 0.5)) (const 1))
     	      ((eq value (const SF -1.0)) (const 2))
     	      ((eq value (const SF 2.0)) (const 3))
     	      (else (error "invalid floating point value for field foo"))))

In this example four floating point immediate values are represented in a field of two bits.  The above might be expanded to a series of `if' statements or the generator could determine a `switch' statement is more appropriate.

decode
------

An expression to apply to convert from raw field values to usable values.  The syntax is (decode (value pc) expression) or more specifically (decode ((WI value) (IAI pc)) <expression>), where <expression> is an rtx to convert value to something usable.

Example:

     (decode ((WI value) (IAI pc))
     	(cond SF
     	      ((eq value 0) (const SF 1.0))
     	      ((eq value 1) (const SF 0.5))
     	      ((eq value 2) (const SF -1.0))
     	      ((eq value 3) (const SF 2.0))))

There's no need to provide an error case as presumably value would never have an invalid value, though certainly one could provide an error case if one wanted to.

Non-contiguous fields
---------------------

Non-contiguous fields (e.g. sparc64's 16 bit displacement field) are built on top of support for contiguous fields.  The syntax for defining such fields is:

     (define-multi-ifield
       (name field-name)
       (comment "description")
       (attrs attribute-list)
       (mode mode-name)
       (subfields field1-name field2-name ...)
       (insert (code to set each subfield))
       (extract (code to set field from subfields))
       (encode (value pc) (rtx to describe encoding))
       (decode (value pc) (rtx to describe decoding))
     )

The required elements are: name, subfields.

Example:

     (define-multi-ifield
       (name f-i20)
       (comment "20 bit unsigned")
       (attrs)
       (mode UINT)
       (subfields f-i20-4 f-i20-16)
       (insert (sequence ()
                         (set (ifield f-i20-4)  (srl (ifield f-i20) (const 16)))
                         (set (ifield f-i20-16) (and (ifield f-i20) (const #xffff)))
                         ))
       (extract (sequence ()
                          (set (ifield f-i20) (or (sll (ifield f-i20-4) (const 16))
                                                  (ifield f-i20-16)))
                          ))
     )

subfields
.........

The names of the already defined fields that make up the multi-ifield.

insert
......

Code to set the subfields from the multi-ifield. All fields are referred to with (ifield <name>).

extract
.......

Code to set the multi-ifield from the subfields. All fields are referred to with (ifield <name>).

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-ifield pmacro (with alias dnf) takes a fixed set of positional arguments for the typical instruction field. The syntax is:

(dnf name comment attributes start length)

Example:

     (dnf f-r1 "register r1" () 4 4)

This defines a field called f-r1 that is an unsigned field of 4 bits beginning at bit 4.  All fields defined with dnf are unsigned.

The df pmacro adds mode, encode, and decode elements.

The syntax of df is:

(df name comment attributes start length mode encode decode)

Example:

     (df f-disp8
         "disp8, slot unknown" (PCREL-ADDR)
         8 8 INT
         ((value pc) (sra WI (sub WI value (and WI pc (const -4))) (const 2)))
         ((value pc) (add WI (sll WI value (const 2)) (and WI pc (const -4)))))

This defines a field called f-disp8 that is a signed PC-relative address beginning at bit 8 of size 8 bits that is left shifted by 2.

The macro define-normal-multi-ifield (with alias dnmf) takes a fixed set of positional arguments for the typical multi-ifield. The syntax is:

(dnmf name comment attributes mode subfields insert extract)

The macro dsmf takes a fixed set of positional arguments for simple multi-ifields. The syntax is:

(dsmf name comment attributes mode subfields)

Enumerated constants
====================

Enumerated constants (enums) are important enough in instruction set descriptions that they are given special treatment. Enums are defined with:

     (define-enum
       (name enum-name)
       (comment "description")
       (attrs attribute-list)
       (prefix prefix)
       (values val1 val2 ...)
     )

Enums in opcode fields are further enhanced by specifying the opcode field they are used in.  This allows the enum's name to be specified in an instruction's format entry.

Instruction enums are defined with define-insn-enum:

     (define-insn-enum
       (name enum-name)
       (comment "description")
       (attrs attribute-list)
       (ifield ifield-name)
       (prefix prefix)
       (values val1 val2 ...)
     )

define-insn-enum is currently not provided, use define-normal-insn-enum instead. See define-normal-insn-enum.

prefix
------

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 prefix not contain any lowercase characters.

ifield
------

The name of the instruction field that the enum is intended for.  This must be a simple ifield, not a multi-ifield.

values
------

A list of possible values.  Each element has one of the following forms:

  * name

  * (name)

  * (name value)

  * (name - (attribute-list))

  * (name value (attribute-list))

The syntax for numbers is Scheme's, so hex numbers are #xnnnn. A value of - means use the next value (previous value plus 1).

Example:

     (values "a" ("b") ("c" #x12)
     	("d" - (sanitize foo)) ("e" #x1234 (sanitize bar)))

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-enum pmacro takes a fixed set of positional arguments for the typical enum. The syntax is:

(define-normal-enum name comment attrs prefix vals)

The define-normal-insn-enum pmacro takes a fixed set of positional arguments for the typical instruction enum. The syntax is:

(define-normal-insn-enum name comment attrs prefix ifield vals)

Example:

     (dnf f-op1 "op1" () 0 4)
     (define-normal-insn-enum insn-op1 "insn format enums" () OP1_ f-op1
       (.map .str (.iota 16))
     )

This defines an instruction enum for field f-op1 with values OP1_0, OP1_1, ..., OP1_15.

Instruction operands
====================

Instruction operands provide:

  * a layer between the assembler and the raw hardware description

  * the main means of making an instruction's fields useful to the semantic code

The syntax for defining an operand is:

     (define-operand
       (name operand-name)
       (comment "description")
       (attrs attribute-list)
       (type hardware-element)
       (mode mode-name)
       (index instruction-field)
       (handlers handler-spec)
       (getter getter-spec)
       (setter setter-spec)
     )

The required elements are: name, type, mode, and if type is not a scaler index.

There is no convention for prefixing operands, and generally for readability's sake operands don't have a prefix.

name
----

This is the name of the operand as a Scheme symbol. The name choice is fairly important as it is used in instruction syntax entries, instruction format entries, and semantic expressions. It can't collide with symbols used in semantic expressions (e.g. and, set, etc).

The convention is that operands have no prefix (whereas ifields begin with f- and hardware elements begin with h-).  A prefix like o- would avoid collisions with other semantic elements, but operands are used often enough that any prefix is a hassle.

attrs
-----

A list of attributes. In addition to attributes defined for the operand, an operand inherits the attributes of its instruction field. There are several predefined operand attributes:

NEGATIVE
     The operand contains negative values (not used yet so definition is still nebulous.

RELAX
     This operand contains the changeable field (usually a branch address) of a relaxable/relaxed instruction.

SEM-ONLY
     Use the SEM-ONLY attribute for cases where the operand will only be used in semantic specification, and not assembly code specification.  A typical example is condition codes.

To refer to a hardware element in semantic code one must either use an operand or one of reg/mem/const.  Operands generally exist to map instruction fields to the selected hardware element and are easier to use in semantic code than referring to the hardware element directly (e.g. sr is easier to type and read than (reg h-gr <index>)). Example:

       (dnop condbit "condition bit" (SEM-ONLY) h-cond f-nil)

f-nil is the value to use when there is no instruction field

type
----

The hardware element this operand applies to. This must be the name of a hardware element.

mode
----

The mode the value is to be interpreted in.

index
-----

The index of the hardware element. This is used to mate the hardware element with the instruction field that selects it, and must be the name of an ifield entry. (*Note: The index may be other things besides ifields in the future.)  It must not be a multi-ifield, currently.

handlers
--------

Sometimes it's necessary to escape to C to parse assembler, or print a value.  This field is an escape hatch to implement this. The syntax is:

(handlers handler-spec)

where handler-spec is one or more of:

(parse "function_suffix") -- a call to function parse_<function_suffix> is generated.

(print "function_suffix") -- a call to function print_<function_suffix> is generated.

These functions are intended to be provided in a separate .opc file.  The prototype of a parse function depends on the hardware type. See cpu/*.opc for examples.

For integer it is:

     static const char *
     parse_foo (CGEN_CPU_DESC cd,
     	   const char **strp,
     	   int opindex,
     	   unsigned long *valuep);

cd is the result of <arch>_cgen_cpu_open. strp is a pointer to a pointer to the assembler and is updated by the function. opindex is ???. valuep is a pointer to where to record the parsed value. If a relocation is needed, it is queued with a call to ???. Queued relocations are processed after the instruction has been parsed.

The result is an error message or NULL if successful.

The prototype of a print function depends on the hardware type.  See cpu/*.opc for examples. For integers it is:

     void print_foo (CGEN_CPU_DESC cd,
                     PTR dis_info,
                     long value,
                     unsigned int attrs,
                     bfd_vma pc,
                     int length);

cd is the result of <arch>_cgen_cpu_open. ptr is the `info' argument to print_insn_<arch>. value is the value to be printed. attrs is the set of boolean attributes. pc is the PC value of the instruction. length is the length of the instruction.

Actual printing is done by calling ((disassemble_info *) dis_info)->fprintf_func.

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-operand) pmacro (with alias dno) takes a fixed set of positional arguments for the typical operand.

There is also the dnop pmacro, it is an alias of dno.

The syntax of dno is:

(dno name comment attrs type index)

Example:

     (dno sr "source register" () h-gr f-r2)

This defines an operand name sr that is an h-gr register indexed by the f-r2 ifield.

Derived operands
================

Derived operands are an experiment in supporting the addressing modes of CISC-like architectures.  Addressing modes are difficult to support as they essentially increase the number of instructions in the architecture by an order of magnitude.  Defining all the variants requires something in addition to the RISC-like architecture support.  The theory is that since CISC-like instructions are basically "normal" instructions with complex operands the place to add the necessary support is in the operands.

Two kinds of operands exist to support CISC-like cpus, and they work together.  ``derived-operands'' describe one variant of a complex argument, and ``anyof'' operands group them together.

The syntax for defining derived operands is:

     (define-derived-operand
       (name operand-name)
       (comment "description")
       (attrs attribute-list)
       (mode mode-name)
       (args arg1-operand-name arg2-operand-name ...)
       (syntax "syntax")
       (base-ifield ifield-name)
       (encoding (+ arg1-operand-name arg2-operand-name ...))
       (ifield-assertion expression)
       (getter expression)
       (setter expression)
     )

The syntax for defining anyof operands is:

     (define-anyof-operand
       (name operand-name)
       (comment "description")
       (attrs attribute-list)
       (mode mode-name)
       (base-ifield ifield-name)
       (choices derived-operand1-name derived-operand2-name ...)
     )

mode
----

The name of the mode of the operand.

args
----

List of names of operands the derived operand uses. The operands must already be defined. The argument operands can be any kind of operand: normal, derived, anyof.

syntax
------

Assembler syntax of the operand.

??? This part needs more work.  Addressing mode specification in assembler needn't be localized to the vicinity of the operand.

base-ifield
-----------

The name of the instruction field common to all related derived operands. Here related means "used by the same `anyof' operand".

encoding
--------

The machine encoding of the operand.

ifield-assertion
----------------

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".

getter
------

RTL expression to get the value of the operand. All operands refered to must be specified in args.

setter
------

RTL expression to set the value of the operand. All operands refered to must be specified in args. Use newval to refer to the value to be set.

choices
-------

For anyof operands, the names of the derived operands. The operand may be "any of" the specified choices.

Instructions
============

Each instruction in the instruction set has an entry in the description file.  For complicated instruction sets this is a lot of typing.  However, macros can reduce a lot of that typing.  The real question is given the amount of information that must be expressed, how succinct can one express it and still be clean and usable?  I'm open to opinions on how to improve this, but such improvements must take everything CGEN wishes to be into account. (*Note: Of course no claim is made that the current design is the be-all and end-all or that there is one be-all and end-all.)

The syntax for defining an instruction is:

     (define-insn
       (name insn-name)
       (comment "description")
       (attrs attribute-list)
       (syntax "assembler syntax")
       (format (+ field-list))
       (ifield-assertion expression)
       (semantics expression)
       (timing timing-data)
     )

The required elements are: name, ???.

Instructions specific to a particular cpu variant are denoted as such with the MACH attribute.

Possible additions for the future:

  * a field to describe a final constraint for determining a match

  * choosing the output from a set of choices

attrs
-----

A list of attributes, for which there are several predefined instruction attributes:

MACH
     A bitset attribute used to specify which machines have this hardware element. Do not specify the MACH attribute if the value is for all machines.

     Usage: (MACH mach1,mach2,...)

     There must be no spaces in ``mach1,mach2,...''.

UNCOND-CTI
     The instruction is an unconditional ``control transfer instruction''.

     (*Note: This attribute is derived from the semantic code. However if the computed value is wrong (dunno if it ever will be) the value can be overridden by explicitly mentioning it.)

COND-CTI
     The instruction is an conditional "control transfer instruction".

     (*Note: This attribute is derived from the semantic code. However if the computed value is wrong (dunno if it ever will be) the value can be overridden by explicitly mentioning it.)

SKIP-CTI
     The instruction can cause one or more insns to be skipped. This is derived from the semantic code.

DELAY-SLOT
     The instruction has one or more delay slots. This is derived from the semantic code.

RELAXABLE
     The instruction has one or more identical variants.  The assembler tries this one first and then the relaxation phases switches to larger ones as necessary.

RELAXED
     The instruction is a non-minimal variant of a relaxable instruction.  It is avoided by the assembler in the first pass.

ALIAS
     Internal attribute set for macro-instructions that are an alias for one real insn.

NO-DIS
     For macro-instructions, don't use during disassembly.

syntax
------

This is a character string consisting of raw characters and operands. Fields are denoted by $operand or ${operand} (Support for ${operand} is work-in-progress.).  If a $ is required in the syntax, it is specified with \$.  At most one white-space character may be present and it must be a blank separating the instruction mnemonic from the operands.  This doesn't restrict the user's assembler, this is just a description file restriction to separate the mnemonic from the operands (The restriction can be relaxed by saying the first blank is the one that separates the mnemonic from its operands.). The assembly language accepted by the generated assembler does not have to take exactly the same form as the syntax described in this field--additional whitespace may be present in the input file.

Operands can refer to registers, constants, and whatever else is necessary.

Instruction mnemonics can take operands.  For example, on the SPARC a branch instruction can take ,a as an argument to indicate the instruction is being annulled (e.g. bge$a $disp22).

format
------

This is a complete list of fields that specify the instruction.  At present it must be prefaced with + to allow for future additions. Reserved bits must also be specified, gaps are not allowed. The ordering of the fields is not important.

Format elements can be any of:

  * an instruction field name with an integer, e.g. (f-op1 4)

  * an instruction field name with an enum, e.g. (f-op1 OP1_4)

  * an instruction field enum, e.g. OP1_4

  * an operand name, e.g. dr

ifield-assertion
----------------

This is an expression with a boolean result that is run as the final part of instruction decoding to verify a match.

semantics
---------

This field provides a mathematical description of what the instruction does.  Its syntax is GCC RTL-like on purpose since GCC's RTL is well known by the intended audience.  However, it is not intended that it be precisely GCC RTL.

Obviously there are some instructions that are difficult if not impossible to provide a description for (e.g. I/O instructions).  Rather than create a new semantic function for each quirky operation, escape hatches to C are provided to handle all such cases.  The c-code, c-call and c-raw-call semantic functions provide an escape-hatch to invoke C code to perform the operation. See Expressions.

timing
------

A list of entries for each function unit the instruction uses on each machine that supports the instruction.  The default function unit is the u-exec unit.

The syntax is:

     (model-name (unit name (direction unit-var-name1 insn-operand-name1)
                            (direction unit-var-name2 insn-operand-name2)
                            ...
                            (cycles cycle-count))

direction/unit-var-name/insn-operand-name mappings are optional. They map unit inputs/outputs to semantic elements.  The direction specifier can be in or out mapping the name of a unit input or output, respectively, to an insn operand.

cycles overrides the done value (latency) of the function unit and is optional.

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-insn pmacro (with alias dni) takes a fixed set of positional arguments for the typical instruction.

The syntax of dni is:

(dni name comment attrs syntax format semantics timing)

Example:

     (dni addi "add 8 bit signed immediate"
          ()
          "addi $dr,$simm8"
          (+ OP1_4 dr simm8)
          (set dr (add dr simm8))
          ()
     )

Macro-instructions
==================

Macro-instructions are for the assembler side of things and are not used by the simulator.  The syntax for defining a macro-instruction is:

     (define-macro-insn
       (name macro-insn-name)
       (comment "description")
       (attrs attribute-list)
       (syntax "assembler syntax")
       (expansions expansion-spec)
     )

syntax
------

Syntax of the macro-instruction. This has the same value as the syntax field in define-insn.

expansions
----------

An expression to emit code for the instruction.  This is intended to be general in nature, allowing tests to be done at runtime that choose the form of the expansion.  Currently the only supported form is:

(emit insn arg1 arg2 ...)

where insn is the name of an instruction defined with define-insn and argn is the set of operands to insn's syntax.  Each argument is mapped in order to one operand in insn's syntax and may be any of:

  * operand specified in syntax

  * (operand value)

Simplification macros
---------------------

To simplify .cpu files several pmacros are provided.

The define-normal-macro-insn) pmacro (with alias dnmi) takes a fixed set of positional arguments for the typical macro-instruction.

The syntax of dnmi is:

(dnmi name comment attrs syntax expansion)

Example:

     (dni st-minus "st-" ()
          "st $src1,$src2"
          (+ OP1_2 OP2_7 src1 src2)
          (sequence ((WI new-src2))
     	       (set new-src2 (sub src2 (const 4)))
     	       (set (mem WI new-src2) src1)
     	       (set src2 new-src2))
          ()
     )

     (dnmi push "push" ()
       "push $src1"
       (emit st-minus src1 (src2 15)) ; "st %0,sp"
     )

In this example, the st-minus instruction is a general store-and-decrement instruction and push is a specialized version of it that uses the stack pointer.

Modes
=====

Modes provide a simple and succinct way of specifying data types.

(*Note: Should more complex types will be needed (e.g. structs? unions?), these can be handled by extending the definition of a mode to encompass them.)

Modes are similar to their usage in GCC, but there are some differences:

  * modes for boolean values (i.e. bits) are also supported as they are useful

  * integer modes exist in signed and unsigned versions

  * constants have modes

Currently supported modes are:

VOID
     VOIDmode in GCC.

DFLT
     Indicate the default mode is wanted, the value of which depends on context. This is a pseudo-mode and never appears in generated code.

BI
     Boolean zero/one

QI,HI,SI,DI
     Same as GCC.

     QI is an 8 bit quantity ("quarter int"). HI is a 16 bit quantity ("half int"). SI is a 32 bit quantity ("single int"). DI is a 64 bit quantity ("double int").

     In cases where signedness matters, these modes are signed.

UQI,UHI,USI,UDI
     Unsigned versions of QI,HI,SI,DI.

     These modes do not appear in semantic RTL.  Instead, the RTL function specifies the signedness of its operands where necessary. To a cpu, a 32 bit register is a 32 bit register. Ditto for when the 32 bit quantity lives in memory. It's only in how it is subsequently used or interpreted that signedness might come into play. When signedness comes into play on the chip, it's explicitly specified in the operation, _not_ in the data. Ergo from this perspective Umodes don't belong in .cpu files. This is the perspective to use when writing .cpu files.

WI,UWI
     word int, unsigned word int (word_mode in gcc). These are aliases for the real mode, typically either SI or DI.

SF,DF,XF,TF
     Same as GCC.

     SF is a 32 bit IEEE float ("single float"). DF is a 64 bit IEEE float ("double float"). XF is either an 80 or 96 bit IEEE float ("extended float"). (*Note: XF values on m68k and i386 are different so may wish to give them different names). TF is a 128 bit IEEE float.

AI
     Address integer

IAI
     Instruction address integer

INT,UINT
     Varying width int/unsigned-int.  The width is specified by context, usually in an instruction field definition.

Expressions
===========

The syntax of CGEN's RTL expressions (or rtx) basically follows that of GCC's RTL.

The handling of modes is different to simplify the implementation. Implementation shouldn't necessarily drive design, but it was a useful simplification.  Still, it needs to be reviewed.  The difference is that in GCC (function:MODE arg1 ...) is written in CGEN as (function MODE arg1 ...).  Note the space after function.

GCC RTL allows flags to be recorded with RTL (e.g. MEM_VOLATILE_P). This is supported in CGEN RTL by prefixing each RTL function's arguments with an optional list of modifiers: (function (:mod1 :mod2) MODE arg1 ...). The list is a set of modifier names prefixed with ':'.  They can take arguments. ??? Modifiers are supported by the RTL traversing code, but no use is made of them yet.

The currently defined semantic functions are:

(set mode destination source)
     Assign source to destination reference in mode mode.

(set-quiet mode destination source)
     Assign source to destination referenced in mode mode, but do not print any tracing message.

(reg mode hw-name [index])
     Return an `operand' of hardware element hw-name in mode mode. If hw-name is an array, index selects which register.

(raw-reg mode hw-name [index])
     Return an `operand' of hardware element hw-name in mode mode, bypassing any get or set specs of the register. If hw-name is an array, index selects which register. This cannot be used with virtual registers (those specified with the VIRTUAL attribute).

     raw-reg is most often used in get and set specs of a register: if it weren't read and write operations would infinitely recurse.

(mem mode address)
     Return an `operand' of memory referenced at address in mode mode.

(const mode value)
     Return an `operand' of constant value in mode mode.

(enum mode value-name)
     Return an `operand' of constant value-name in mode mode. The value must be from a previously defined enum.

(subword mode value word-num)
     Return part of value.  Which part is determined by mode and word-num.  There are three cases.

     If mode is the same size as the mode of value, word-num must be 0 and the result is value recast in the new mode. There is no change in the bits of value, they're just interpreted in a possibly different mode.  This is most often used to interpret an integer value as a float and vice versa.

     If mode is smaller, value is divided into N pieces and word-num picks which piece.  All pieces have the size of mode except possibly the last.  If the last piece has a different size, it cannot be referenced. This follows GCC and is byte order dependent. (To be revisited). Word number 0 is the most significant word if big-endian-words. Word number 0 is the least significant word if little-endian-words.

     If mode is larger, value is interpreted in the larger mode with the upper most significant bits treated as garbage (their value is assumed to be unimportant to the context in which the value will be used). word-num must be 0. This case is byte order independent.

(join out-mode in-mode arg1 . arg-rest)
     Concatenate arg1[,arg2[,...]] to create a value of mode out-mode. arg1 becomes the most significant part of the result. Each argument is interpreted in mode in-mode. in-mode must evenly divide out-mode.

(sequence mode ((mode1 local1) ...) expr1 expr2 ...)
     Execute expr1, expr2, etc. sequentially. mode is the mode of the result, which is defined to be that of the last expression. `((mode1 local1) ...)' is a set of local variables.

(parallel mode empty expr1 ...)
     Execute expr1, expr2, etc. in parallel. All inputs are read before any output is written.  empty must be () and is present for consistency with sequence. mode must be VOID (void mode).

(unop mode operand)
     Perform a unary arithmetic operation. unop is one of neg, abs, inv, not, zflag, nflag. zflag returns a bit indicating if operand is zero. nflag returns a bit indicating if operand is negative. inv returns the bitwise complement of operand, whereas not returns its logical negation.

(binop mode operand1 operand2)
     Perform a binary arithmetic operation. binop is one of add, sub, and, or, xor, mul, div, udiv, mod, umod.

(binop-with-bit mode operand1 operand2 operand3)
     Same as binop, except taking 3 operands. The third operand is always a single bit. binop-with-bit is one of addc, addc-cflag, addc-oflag, subc, subc-cflag, subc-oflag.

     Note: The following are deprecated:

       * add-cflag, replaced with addc-cflag

       * add-oflag, replaced with addc-oflag

       * sub-cflag, replaced with subc-cflag

       * sub-cflag, replaced with subc-oflag

(shiftop mode operand1 operand2)
     Perform a shift operation. operand1 is shifted (or rotated) by the amount specified in operand2. shiftop is one of sll, srl, sra, ror, rol. mode must match the mode of operand1. The mode of operand1 may be any integral mode. The mode of operand2 may be any integral mode, and need not match the mode of operand1.

     It is an error if operand2 is negative or greater than or equal to the size of operand1. If the architecture handles negative or large shift amounts, that needs to be handled in the surrounding RTL.

(boolifop mode operand1 operand2)
     Perform a sequential boolean operation. operand2 is not processed if operand1 ``fails''. boolifop is one of andif, orif.

(convop mode operand)
     Perform a mode->mode conversion operation. convop is one of ext, zext, trunc, float, ufloat, fix, ufix.

(cmpop mode operand1 operand2)
     Perform a comparison. cmpop is one of eq, ne, lt, le, gt, ge, ltu, leu, gtu, geu.

(mathop mode operand)
     Perform a mathematical operation. mathop is one of sqrt, cos, sin.

(if mode condition then [else])
     Standard if statement.

     condition is any arithmetic expression. If the value is non-zero the then part is executed. Otherwise, the else part is executed (if present).

     mode is the mode of the result, not of condition. If mode is not VOID (void mode), else must be present. When the result is used, mode must specified, and not be VOID.

(cond mode (condition1 expr1a ...) (...) [(else exprNa...)])
     From Scheme: keep testing conditions until one succeeds, and then process the associated expressions.

(case mode test ((case1 ..) expr1a ..) (..) [(else exprNa ..)])
     From Scheme: Compare test with case1, case2, etc. and process the associated expressions.

(c-code mode "C expression")
     An escape hook to insert arbitrary C code. mode must the compatible with the result of ``C expression''.

(c-call mode symbol operand1 operand2 ...)
     An escape hook to emit a subroutine call to function named symbol passing operands operand1, operand2, etc.  An implicit first argument of current_cpu is passed to symbol. mode is the mode of the result.  Be aware that symbol will be restricted by reserved words in the C programming language and by existing symbols in the generated code.

(c-raw-call mode symbol operand1 operand2 ...)
     Same as c-call: except there is no implicit current_cpu first argument. mode is the mode of the result.

(clobber mode object)
     Indicate that object is written in mode mode, without saying how. This could be useful in conjunction with the C escape hooks.

(delay mode num expr)
     Indicate that there are num delay slots in the processing of expr.  When using this rtx in instruction semantics, CGEN will infer that the instruction has the DELAY-SLOT attribute.

(delay num expr)
     In older "sim" simulators, indicates that there are num delay slots in the processing of expr. When using this rtx in instruction semantics, CGEN will infer that the instruction has the DELAY-SLOT attribute.

     In newer "sid" simulators, evaluates to the writeback queue for hardware operand expr, at num instruction cycles in the future. expr must be a hardware operand in this case.

     For example, (set (delay 3 pc) (+ pc 1)) will schedule write to the pc register in the writeback phase of the 3rd instruction after the current. Alternatively, (set gr1 (delay 3 gr2)) will immediately update the gr1 register with the latest write to the gr2 register scheduled between the present and 3 instructions in the future. (delay 0 ...)  refers to the writeback phase of the current instruction.

     This effect is modeled with a circular buffer of "write stacks" for each hardware element (register banks get a single stack). The size of the circular buffer is calculated from the uses of (delay ...) rtxs. When a delayed write occurs, the simulator pushes the write onto the appropriate write stack in the "future" of the circular buffer for the written-to hardware element. At the end of each instruction cycle, the simulator executes all writes in all write stacks for the time slice just ending. When a delayed read (essentially a pipeline bypass) occurs, the simulator looks ahead in the circular buffer for any writes scheduled in the future write stack. If it doesn't find one, it progressively backs off towards the "current" instruction cycle's write stack, and if it still finds no scheduled writes then it returns the current state of the CPU. Thus while delayed writes are fast, delayed reads are potentially slower in a simulator with long pipelines and very large register banks.

(annul yes?)
     Annul the following instruction if yes? is non-zero. This rtx is an experiment and will probably change.

(skip yes?)
     Skip the next instruction if yes? is non-zero. This rtx is an experiment and will probably change.

(attr mode kind attr-name)
     Return the value of attribute attr-name in mode mode. kind must currently be insn: the current instruction.

(symbol name)
     Return a symbol with value name, for use in attribute processing. This is equivalent to quote in Scheme but quote sounds too jargonish.

(eq-attr mode attr-name value)
     Return non-zero if the value of attribute attr-name is value. If value is a list return ``true'' if attr-name is any of the listed values.

(index-of operand)
     Return the index of operand. For registers this is the register number.

(regno operand)
     Same as index-of, but improves readability for registers.

(error mode message)
     Emit an error message from CGEN RTL. Error message is specified by message.

(nop)
     A no-op.

(ifield field-name)
     Return the value of field field-name. field-name must be a field in the instruction.

Operands can be any of:

  * an operand defined in the description file

  * a register reference, created with (reg mode [index])

  * a memory reference, created with (mem mode address)

  * a constant, created with (const mode value)

  * a `sequence' local variable

  * another expression

The symbol in a c-call or c-raw-call function is currently the name of a C function or macro that is invoked by the generated semantic code.

Macro-expressions
=================

Macro RTL expressions are a way to not have to always specify a mode for every expression (and sub-expression thereof).  Whereas the formal way to specify, say, an add is (add SI arg1 arg2) if SI is the default mode of `arg1' then this can be simply written as (add arg1 arg2). This gets expanded to (add DFLT arg1 arg2) where DFLT means ``default mode''.

It might be possible to replace macro expressions with preprocessor macros, however for the nonce there is no plan to do this.