[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Porting

This chapter describes how to do a CGEN port. It focuses on doing binutils and simulator ports, but the procedure should be generally applicable.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Introduction to porting

Doing a GNU tools port for a new processor basically consists of porting the following components more or less in order. The order can be changed, of course, but the following order is reasonable. Certainly things like BFD and opcodes need to be finished earlier than others. Bugs in earlier pieces are often not found until testing later pieces so each piece isn't necessarily finished until they all are.

The use of CGEN affects the opcodes, GAS, and simulator portions only. As always, the M32R port is a good reference base.

One goal of CGEN is to describe the CPU in an application independent manner so that program generators can do all the repetitive work of generating code and tables for each CPU that is ported.

For opcodes, several files are generated. No additional code need be written in the opcodes directory although as an escape hatch the user can add target specific code to file <arch>.opc in the CGEN cpu source directory. These functions will be included in the relevant generated files. An example of when you need to create an <arch>.opc file is when there are special pseudo-ops that need to be parsed, for example the high/shigh pseudo-ops of the M32R. See section Doing an opcodes port.

For GAS, no files are generated (except test cases!) so the port is done more or less like the other GAS ports except that the assembler uses the CGEN-built opcode table plus ‘toplevel/gas/cgen.[ch]’.

For the simulator, several files are built, and other support files need to be written. See section Doing a simulator port.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Supported Guile versions

In order to avoid suffering from the bug of the day when using snapshots, CGEN development has been confined to Guile releases only. CGEN has been tested with and supports Guile versions 1.6.8 and 1.8.5. As time passes older versions of Guile will no longer be supported.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Running configure

When doing porting or maintenance activity with CGEN, it's a good idea to configure the build tree with the --enable-cgen-maint option. This adds the necessary dependencies to the ‘toplevel/opcodes’ and ‘toplevel/sim’ directories so that when the ‘.cpu’ file is changed the makefiles will regenerated the corresponding sources.

CGEN uses Guile so it must be installed.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Writing a CPU description file

The first step in doing a CGEN port is writing a CPU description file. The best way to do that is to take an existing file (such as the M32R) and use it as a template.

Writing a CPU description file generally involves writing each of the following types of entries, in order. See section CGEN's Register Transfer Language, for detailed descriptions of each type of entry that appears in the description file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.1 Conventions

First a digression on conventions and programming style.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.2 simplify.inc

The file ‘simplify.inc’ provides several pmacros that help simplify writing ‘.cpu’ files.

To use it add the following to your ‘.cpu’ file.

 
(include "simplify.inc")

simplify.inc’ provides the following pmacros:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.3 Names and comments

Most description entries have a few fields in common: name, comment, and attrs (for attributes).

The ‘name’ and ‘comment’ fields have a special property to help simplify writing description files.

The proper type for a name is a symbol and the proper type for a comment is string. It is sometimes useful, however, to construct names and comments from a list of values. To support this without forcing the description file writer to have to explicitly construct a name or comment from pieces, CGEN accepts a list as a valid ‘name’ or ‘comment’ field, and will (recursively) append each element automagically. Each list must consist of symbols, strings, and numbers, or lists. CGEN will automagically convert the value to a symbol for a name field, and a string for a comment field.

Example:

 
(define-insn (name (add 3))
             (comment (("This is a" " comment")
                       " constructed as a list."))
             ...)

The name of this instruction is “add3” and the comment is "This is a comment constructed as a list.".


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.4 Writing define-arch

Various simple and architecture-wide common things like the name of the processor must be defined somewhere, so all of this stuff is put under define-arch.

This must be the first entry in the description file.

See section Architecture variants, for details.

Here's an example from ‘m32r.cpu’:

 
(define-arch
  (name m32r) ; name of cpu family
  (comment "Renesas M32R")
  (default-alignment aligned)
  (insn-lsb0? #f)
  (machs m32r m32rx m32r2)
  (isas m32r)
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.5 Writing define-isa

There are two purposes to define-isa. The first is to specify parameters needed to decode instructions.

The second is to give the instruction set a name. This is important for architectures like the ARM where one CPU can execute multiple instruction sets.

See section Architecture variants, for details.

Here's an example from ‘arm.cpu’:

 
(define-isa
  (name thumb)
  (comment "ARM Thumb instruction set (16 bit insns)")
  (base-insn-bitsize 16)
  (decode-assist (15 14 13 12 11 10 9 8))
  (setup-semantics (set-quiet (reg h-gr 15) (add pc 4)))
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.6 Writing define-cpu

CPU families are an internal and artificial classification designed to collect processor variants that are sufficiently similar together under one roof for the simulator. What is “sufficiently similar” is up to the programmer. For example, if the only difference between two processor variants is that one has a few extra instructions, there's no point in treating them separately in the simulator.

When simulating the variant without the extra instructions, said instructions are marked as “invalid”. On the other hand, putting 32 and 64 bit variants of an architecture under one roof is problematic since the word size is different. What “under one roof” means is left fuzzy for now, but basically the simulator engine has a collection of structures defining internal state, and “CPU families” minimize the number of copies of generated code that manipulate this state.

See section Architecture variants, for details.

Here's an example from ‘openrisc.cpu’:

 
(define-cpu
  ; CPU names must be distinct from the architecture name and machine names.
  ; The "b" suffix stands for "base" and is the convention.
  ; The "f" suffix stands for "family" and is the convention.
  (name openriscbf)
  (comment "OpenRISC base family")
  (endian big)
  (word-bitsize 32)
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.7 Writing define-mach

CGEN uses “mach” in the same sense that BFD uses “mach”. “Mach”, which is short for `machine', defines a variant of the architecture.

See section Architecture variants, for details.

Here's an example from ‘m32r.cpu’:

 
(define-mach
  (name m32rx)
  (comment "M32RX cpu")
  (cpu m32rxf)
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.8 Writing define-model

When describing a CPU, in any context, there is “architecture” and there is “implementation”. In CGEN parlance, a “model” is an implementation of a “mach”. Models specify pipeline and other performance related characteristics of the implementation.

Some architectures bring pipeline details up into the architecture (rather than making them an implementation detail). It's not clear yet how to handle all the various possibilities so at present this is done on a case-by-case basis. Maybe a straightforward solution will emerge.

See section Model variants, for details.

Here's an example from ‘arm.cpu’:

 
(define-model
  (name arm710)
  (comment "ARM 710 microprocessor")
  (mach arm7tdmi)
  (unit u-exec "Execution Unit" ()
	1 1 ; issue done
	() () () ())
)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.9 Writing define-hardware

The registers of the processor are specified with define-hardware. Also, immediate constants and addresses are defined to be “hardware”. By convention, all hardware elements names are prefaced with ‘h-’. This convention must be followed.

Pre-defined hardware elements are:

h-memory

Normal CPU memory(27)

h-sint

signed integer

h-uint

unsigned integer

h-addr

an address

h-iaddr

an instruction address

Where are floats you ask? They'll be defined when the need arises.

The program counter is named ‘h-pc’ and must be specified. It is not a builtin element as sometimes architectures need to modify its behaviour (in the get/set specs).

See section Hardware elements, for details.

Here's an example from ‘arm.cpu’:

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.10 Writing define-ifield

Writing instruction field entries involves analyzing the instruction set and creating an entry for each field. If a field has multiple purposes, one can create separate entries for each intended purpose. The names should generally follow the names used by the architecture reference manual.

By convention, all instruction field names are prefaced with ‘f-’. This convention must be followed.

CGEN tries to allow the use of the bit numbering as found in the architecture reference manual. This minimizes transcription errors both when writing the ‘.cpu’ file and later when communicating field info to people.

There are two key pieces of data that CGEN uses to organize field specification: the default insn word size (in bits), and whether bit number 0 is the LSB (least significant bit) or the MSB (most significant bit).

In the general case, fields are described with 4 numbers: word-offset, word-length, start, and length. All instruction fields live in exactly one word and must be contiguous.(28) Non-contiguous fields are specified with “multi-ifields” which are fields built up out of several smaller typically disjoint fields. The size of the word depends on the context. ‘word-offset’ specifies the offset in bits from the start of the insn to the word containing the field, it must be a multiple of 8. ‘word-length’ specifies the size in bits of the word containing the field, it also must be a multiple of 8. ‘start’ specifies the position of the MSB of the field in the word. ‘length’ specifies the size in bits of the field.

See section Instruction fields, for details.

Example.

Suppose an ISA has instructions that are normally 16 bits, but has instructions that may take an additional 32 bit immediate and optionally an additional 16 bit immediate after that. Also suppose the ISA numbers the bits starting from the LSB.

default-insn-word-bitsize = 16, lsb0? = #t

An instruction with four 4 bit fields, one 32 bit immediate and one 16 bit immediate might be:

 
  +-----+-----+----+----+--------+--------+
  | op1 | op2 | r1 | r2 | simm32 | simm16 |
  +-----+-----+----+----+--------+--------+

            word-offset  word-length  start  length
f-op1:           0            16        15      4
f-op2:           0            16        11      4
f-r1:            0            16         7      4
f-r2:            0            16         3      4
f-simm32:       16            32        31     32
f-simm16:       48            16        15     16

If lsb0? = #f, then the example becomes:

 
            word-offset  word-length  start  length
f-op1:           0            16         0      4
f-op2:           0            16         4      4
f-r1:            0            16         8      4
f-r2:            0            16        12      4
f-simm32:       16            32         0     32
f-simm16:       48            16         0     16

Endianness for the purposes of this example is irrelevant. In the word containing op1,op2,r1,r2, op1 is in the most significant nibble and r2 is in the least significant nibble.

For a large number of cases specifying all four numbers is excessive. With careful redefinition of the starting bit number, one can get away with only specifying start,length. Imagine several words of the default insn word size laid out from the start of the insn. On top of that lay the field. Now pick the minimal set of words that are required to contain the field. That is the “word” we use. The ‘start’ value is basically computed by adding the offset of the first containing word to the starting bit of the field in the word. It's slightly more complicated than that because lsb0? and the word's size must be taken into account. This is best illustrated by rewriting the above example:

 
lsb0? = #t

            start  length
f-op1:        15      4
f-op2:        11      4
f-r1:          7      4
f-r2:          3      4
f-simm32:     47     32
f-simm16:     63     16

lsb0? = #f

            start  length
f-op1:         0      4
f-op2:         4      4
f-r1:          8      4
f-r2:         12      4
f-simm32:     16     32
f-simm16:     48     16

Note: This simpler definition doesn't work in all cases. Where it doesn't the full-blown definition must be used.

There are currently no shorthand macros for specifying the full-blown definition. It is recommended that if you have to use one that you write a macro to reduce typing.

Written out the full blown way, the f-op1 field would be specified as:

 
(define-ifield
  (name f-op1)
  (comment "f-op1")
  (attrs) ; no attributes, could be elided if one wants
  (word-offset 0)
  (word-length 16)
  (start 15)
  (length 4)
  (mode UINT)
  (encode #f) ; no special encoding, could be elided if one wants
  (decode #f) ; no special encoding, could be elided if one wants
)

A macro to simplify that could be written as:

 
; dwf: define-word-field (??? pick a better name)

(define-pmacro (dwf x-name x-comment x-attrs
                    x-word-offset x-word-length x-start x-length
                    x-mode x-encode x-decode)
  "Define a field including its containing word."
  (define-ifield
    (name x-name)
    (comment x-comment)
    (.splice attrs (.unsplice x-attrs))
    (word-offset x-word-offset)
    (word-length x-word-length)
    (start x-start)
    (length x-length)
    (mode x-mode)
    (.splice encode (.unsplice x-encode))
    (.splice decode (.unsplice x-decode))
    )
)

The ‘.splice’ is necessary because ‘attrs’, ‘encode’, and ‘decode’ take a list as an argument.

One would then write f-op1 as:

 
(dwf f-op1 "f-op1" () 0 16 15 4 UINT #f #f)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.11 Writing define-normal-insn-enum

Writing instruction enum entries involves analyzing the instruction set and attaching names to the opcode fields. For example, if a field named ‘op1’ is used to select which of add, addc, sub, subc, and, or, xor, and inv instructions, one could write something like the following:

 
(define-normal-insn-enum
  insn-op1 "insn format enums" () f-op1 OP1_
  (ADD ADDC SUB SUBC
   AND OR   XOR INV)
)

These entries simplify instruction definitions by giving a name to a particular value for a particular instruction field. By convention, enum names are uppercase. This convention must be followed.

See section Enumerated constants, for details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.12 Writing define-operand

Operands are what instruction semantics use to refer to hardware elements. The typical use of an operand is to map instruction fields to hardware. For example, if field ‘f-r2’ is used to specify one of the registers defined by the h-gr hardware entry, one could write something like the following:

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

dnop is short for “define normal operand” (29).

See section Instruction operands, for more information.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.13 Writing define-insn

A large part of writing a ‘.cpu’ file is going through the CPU manual and writing an entry for each instruction. Instructions specific to a particular machine variant are indicated so with the `MACH' attribute. Example:

 
(define-normal-insn
  add "add instruction"
  ((MACH mach1)) ; or (MACH mach1,mach2,...) for multiple variants
  ...
)

The `base' machine is a predefined machine variant that includes instructions available to all variants, and is the default if no `MACH' attribute is specified.

See section Instructions, for details.

When the ‘.cpu’ file is processed, CGEN will analyze the semantics to determine:

CGEN will also try to simplify the semantics as much as possible:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.14 Writing define-macro-insn

Some instructions are really aliases for other instructions, maybe even a sequence of them. For example, an architecture that has a general decrement-then-store instruction might have a specialized version of this instruction called push supported by the assembler. These are handled with “macro instructions”.

See section Macro-instructions, for details.

Macro instructions are used by the assembler/disassembler only. They are not used by the simulator.

For example, if this was the real instruction:

 
(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))
     ()
)

One could write a push variant with:

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.15 Using define-pmacro

When a group of entries, say instructions, share similar information, a macro (in the C preprocessor sense) can be used to simplify the description. This can be used to save a lot of typing, which can also improve readability since often one page of code is easier to understand than four.

See section Preprocessor macros, for details.

Here is an example from the M32R port.

 
(define-pmacro (bin-op mnemonic op2-op sem-op imm-prefix imm)
  (begin
     (dni mnemonic
	  (.str mnemonic " reg/reg")
	  ()
	  (.str mnemonic " $dr,$sr")
	  (+ OP1_0 op2-op dr sr)
	  (set dr (sem-op dr sr))
	  ()
     )
     (dni (.sym mnemonic "3")
	  (.str mnemonic " reg/" imm)
	  ()
	  (.str mnemonic "3 $dr,$sr," imm-prefix "$" imm)
	  (+ OP1_8 op2-op dr sr imm)
	  (set dr (sem-op sr imm))
	  ()
     )
   )
)
(bin-op add OP2_10 add "$hash" slo16)
(bin-op and OP2_12 and ""      uimm16)
(bin-op or  OP2_14 or  "$hash" ulo16)
(bin-op xor OP2_13 xor ""      uimm16)

.sym/.str are short for Scheme's symbol-append and string-append operations and are conceptually the same as the C preprocessor's ## concatenation operator. See section Symbol concatenation, and See section String concatenation, for details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4.16 Splicing arguments

Several cpu description elements take multiple arguments, as opposed to a single argument (even if that single argument is a list). When constructing a call to define-* in a pmacro, these elements must have their arguments spliced in to achieve the proper syntax.

This is best explained with an example. Here's a simplifying macro for writing ifield definitions with every element specified.

See section List splicing, for details.

 
; dwf: define-word-field

(define-pmacro (dwf x-name x-comment x-attrs
                    x-word-offset x-word-length x-start x-length
                    x-mode x-encode x-decode)
  "Define a field including its containing word."
  (define-ifield
    (name x-name)
    (comment x-comment)
    (.splice attrs (.unsplice x-attrs))
    (word-offset x-word-offset)
    (word-length x-word-length)
    (start x-start)
    (length x-length)
    (mode x-mode)
    (.splice encode (.unsplice x-encode))
    (.splice decode (.unsplice x-decode))
    )
)

The ‘.splice’ is necessary because ‘attrs’, ‘encode’, and ‘decode’ take (potentially) multiple arguments.

One would then write f-disp16 as:

 
(dwf f-disp16 "f-disp16" (PCREL-ADDR RELOC) 16 16 15 16 INT
    ((value pc) (sra WI (sub WI value pc) (const 2)))
    ((value pc) (add WI (sll WI value (const 2)) pc)))

It will get expanded as:

 
(define-ifield
  (name f-disp16)
  (comment "f-disp16")
  (attrs PCREL-ADDR RELOC)
  (word-offset 16)
  (word-length 16)
  (start 15)
  (length 16)
  (mode INT)
  (encode (value pc) (sra WI (sub WI value pc) (const 2)))
  (decode (value pc) (add WI (sll WI value (const 2)) pc))
)

If we didn't use ‘.splice’, and instead just wrote:

 
(define-pmacro (bad-dwf x-name x-comment x-attrs
                        x-word-offset x-word-length x-start x-length
                        x-mode x-encode x-decode)
  "Define a field including its containing word."
  (define-ifield
    (name x-name)
    (comment x-comment)
    (attrs x-attrs)
    (word-offset x-word-offset)
    (word-length x-word-length)
    (start x-start)
    (length x-length)
    (mode x-mode)
    (encode x-encode)
    (decode x-decode)
    )
)

Then that would expand to the following, which is incorrect:

 
(define-ifield
  (name f-disp16)
  (comment "f-disp16")
  (attrs (PCREL-ADDR RELOC))
  (word-offset 16)
  (word-length 16)
  (start 15)
  (length 16)
  (mode INT)
  (encode ((value pc) (sra WI (sub WI value pc) (const 2))))
  (decode ((value pc) (add WI (sll WI value (const 2)) pc)))
)

Note the extra level of parentheses in the ‘attrs’, ‘encode’, and ‘decode’ fields.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 Interactive development

The normal way(30) of writing a CPU description file involves starting Guile and developing the .CPU file interactively. The basic steps are:

  1. Run guile.
  2. (load "dev.scm")
  3. Load application, e.g. (load-opc) or (load-sim)
  4. Load CPU description file, e.g. (cload #:arch "cpu/m32r.cpu")
  5. Run generators until output looks reasonable, e.g. (cgen-opc.c)

To assist in the development process and to cut down on some typing, ‘dev.scm’ looks for ‘$HOME/.cgenrc’ and, if present, loads it. Typical things that ‘.cgenrc’ contains are definitions of procedures that combine steps 3 and 4 above.

Example:

 
(define (m32r-opc)
  (load-opc)
  (cload #:arch "cpu/m32r.cpu")
)
(define (m32r-sim)
  (load-sim)
  (cload #:arch "cpu/m32r.cpu" #:options "with-scache with-profile=fn")
)
(define (m32rbf-sim)
  (load-sim)
  (cload #:arch "cpu/m32r.cpu" #:machs "m32r" #:options "with-scache with-profile=fn")
)
(define (m32rxf-sim)
  (load-sim)
  (cload #:arch "cpu/m32r.cpu" #:machs "m32rx" #:options "with-scache with-profile=fn")
)

CPU description files are loaded into an interactive guile session with cload. The syntax is:

 
(cload #:arch "cpu-file-path"
       [#:machs "mach-list"]
       [#:isas "isa-list"]
       [#:options "option-list"]
       [#:trace "trace-list"]
       [#:diag "diagnostic-list"])

Only the #:arch argument is mandatory.

cpu-file’ is the path to the ‘.cpu’ file.

mach-list’ is a comma separated string of machines to keep.

isa-list’ is a comma separated string of isas to keep.

options’ is a space separated string of options for the application. What the acceptable values are depends on the application.

trace’ is a comma separated string of tracing options. See section Specify tracing of various things. ‘-ttrace-list.

diag’ is a comma separated string of diagnostic options. See section Enable various diagnostics. ‘-wdiagnostic-list.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 Doing an opcodes port

The best way to begin a port is to take an existing one (preferably one that is similar to the new port) and use it as a template.

  1. Run guile.
  2. (load "dev.scm"). This loads in a set of interactive development routines.
  3. (load-opc). Load the opcodes support.
  4. Edit your ‘cpu/$arch.cpu’ and ‘cpu/$arch.opc’ files.
  5. (cload #:arch "cpu/$arch.cpu")
  6. (set-opc-file-path! "cpu/$arch.opc")
  7. Run each of:
  8. Repeat steps 4, 5 and 6 until the output looks reasonable.
  9. Add dependencies to ‘opcodes/Makefile.am’ to generate the eight opcodes files (use the M32R port as an example).
  10. Run make dep from the ‘opcodes’ build directory.
  11. Run make all-opcodes from the top level build directory.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 Doing a GAS port

A GAS CGEN port is essentially no different than a normal port except that the CGEN opcode table is used, and there are extra supporting routines available in ‘gas/cgen.[ch]’. As always, a good way to get started is to take the M32R port as a template and go from there.

The important CGEN-specific things to keep in mind are:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.8 Building a GAS test suite

CGEN can also build the template for test cases for all instructions. In some cases it can also generate the actual instructions. The result is then assembled, disassembled, verified, and checked into CVS. Further changes are usually done by hand as it's easier. The goal here is to save the enormous amount of initial typing that is required.

  1. cd to the CGEN build directory
  2. make gas-test

    At this point two files have been created in the CGEN build directory: ‘gas-allinsn.exp’ and ‘gas-build.sh’. The ‘gas-build.sh’ script normally requires one command line argument: the location of your ‘gas’ build directory. If this argument is omitted, the script searches in ‘../gas’ automatically.

  3. Copy ‘gas-allinsn.exp’ to ‘toplevel/gas/testsuite/gas/<arch>/allinsn.exp’.
  4. sh gas-build.sh

    At this point directory tmpdir contains two files: ‘allinsn.s’ and ‘allinsn.d’. File ‘allinsn.d’ usually needs a bit of massaging.

  5. Copy ‘tmpdir/allinsn.[sd]’ to ‘toplevel/gas/testsuite/gas/<arch>
  6. Run make check in the ‘gas’ build directory and massage things until you're satisfied the files are correct.
  7. Check files into CVS.

At this point further additions/modifications are usually done by hand.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.9 Doing a simulator port

NOTE: This section applies to GDB simulators, not SID simulators (see section SID Simulator).

The same basic procedure for opcodes porting applies here.

Simulator ports consist of four pieces:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.9.1 Simulator files

The following additional files are also needed. These live in the ‘sim/<arch>’ directory. Administrivia files like ‘configure.in’ and ‘Makefile.in’ are omitted.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.9.2 Interactive simulator development

When ready to generate the simulator files,

  1. Run guile.
  2. (load "dev.scm")
  3. (load-sim)
  4. Edit your ‘cpu/$arch.cpu’ file.
  5. (cload #:arch "cpu/$arch.cpu")
  6. Run each of:
  7. Repeat steps 4,5,6 until the output looks reasonable.
  8. Edit your ‘cpu/<arch>.cpu’ file.
  9. (cload #:arch "cpu/$arch.cpu" #:machs "mach1[,mach2[,...]]")
  10. Run each of:
  11. Repeat steps 8, 9 and 10 until the output looks reasonable.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.10 Building a simulator test suite

CGEN can also build the template for test cases for all instructions. In some cases it can also generate the actual instructions (31). The result is then verified and checked into CVS. Further changes are usually done by hand as it's easier. The goal here is to save the enormous amount of initial typing that is required.

  1. cd to the CGEN build directory
  2. make sim-test ISA=<arch>

    At this point two files have been created in the CGEN build directory: ‘sim-allinsn.exp’ and ‘sim-build.sh’.

  3. Copy ‘sim-allinsn.exp’ to ‘toplevel/sim/testsuite/sim/<arch>/allinsn.exp’.
  4. sh sim-build.sh

    At this point a new subdirectory called ‘tmpdir’ will be created and will contain one test case for each instruction. The framework has been filled in but not the actual test case. It's handy to write an “include file” containing assembler macros that simplify writing test cases. See ‘toplevel/sim/testsuite/sim/m32r/testutils.inc’ for an example.

  5. write testutils.inc
  6. finish each test case
  7. copy ‘tmpdir/*.cgs’ to ‘toplevel/sim/testsuite/sim/<arch>
  8. run make check in the sim build directory and massage things until you're satisfied the files are correct
  9. Check files into CVS.

At this point further additions/modifications are usually done by hand.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Doug Evans on January, 28 2010 using texi2html 1.78.