2. Running CGEN

CGEN is usually run from a shell script provided by the application. For example, in ‘libopcodes’ there is ‘cgen.sh’.

The main tasks of this script are to:

1. Set up the arguments for cgen.
2. Run cgen.
3. Apply any post processing to the output files.

2.0.1 Set up the arguments for cgen.

CGEN takes several standard arguments. Each application can then add its own arguments. By convention generic CGEN options are lowercase letters and applications use uppercase letters for their arguments.

2.1 Specify path of architecture's .cpu file to load. ‘-a’ path

Use this option to specify the ‘.cpu’ file to load.

2.2 Use debugging evaluator, for backtraces. ‘-b’

Use this option when trying to debug a cgen failure. It turns on the debugging facilities of the underlying system, e.g. Guile, and is typically used to produce better error messages (e.g. better backtraces). Guile's debugging evaluator is slower than the normal one, so this option is off by default.

2.3 Start interactive debugging session. ‘-d’

Use this option when trying to debug a cgen failure and you want to enter a debugging repl(10) in the underlying system, e.g. Guile.

2.4 Specify a set of flags to control code generation. ‘-f’ flags

Use this option to pass various code generation options to the application. flags is a space-separated list of options with the format name or name=value. Each application accepts its own set of options.

2.4.1 Opcodes Generator Options

The Opcodes generator accepts the following options:

opinst

Include the operand instance table in the generated code.

copyright=<kind>

The argument is the copyright to add to the generated code. It must be one of fsf or redhat.

package=<package>

The argument is the package the opcodes files are being generated for. It must be one of binutils, gnusim (the simulators in GDB releases) or cygsim (SID simulators).

2.4.2 GDB Simulator Generator Options

with-scache

Specify this option to enable the “semantic cache” of the simulator. The simulator uses the semantic cache to speed up simulation by caching the decoding of instructions.

with-profile=<fn|sw>

Specify this option to enable basic profiling support.

fn - do profiling in the semantic function

sw - do profiling in the semantic switch

with-multiple-isa

Specify this option to enable multiple-isa support. This is useful for the arm+thumb simulator, and allows the simulator to simulator programs that use both ISAs.

with-generic-write

This option is for architectures that can execute multiple instructions in parallel. Instruction semantics are performed by recording the results in a generic buffer, and doing a post-semantics writeback pass.

with-parallel-only

copyright=<kind>

The argument is the copyright to add to the generated code. It must be one of fsf or redhat.

package=<package>

The argument is the package the simulator files are being generated for. It must be one of gnusim (the simulators in GDB releases) or cygsim (SID simulators).

2.4.3 SID Simulator Generator Options

with-scache

Specify this option to enable the “semantic cache” of the simulator. The simulator uses the semantic cache to speed up simulation by caching the decoding of instructions.

NOTE: Not all targets support this option.

with-pbb

Specify this option to enable the “pseudo basic block” engine. The simulator uses the pbb engine to speed up simulation by analyzing the instruction stream a pseudo basic block at a time.

NOTE: Not all targets support this option.

with-sem-frags

Specify this option to enable the semantic fragment engine.

NOTE: This option requires with-pbb.

NOTE: Not all targets support this option.

with-profile=<fn|sim>

Specify this option to enable basic profiling support.

fn - do profiling in the semantic function

sw - do profiling in the semantic switch

with-multiple-isa

Specify this option to enable multiple-isa support. This is useful for the arm+thumb simulator, and allows the simulator to simulator programs that use both ISAs.

copyright=<kind>

The argument is the copyright to add to the generated code. It must be one of fsf or redhat.

package=<package>

The argument is the package the simulator files are being generated for. It must be one of gnusim (the simulators in GDB releases) or cygsim (SID simulators).

2.4.4 HTML Doc Generator Options

copyright=<kind>

The argument is the copyright to add to the generated code. It must be doc.

package=<package>

The argument is the package the opcodes files are being generated for. It must be cgen.

2.5 Print usage information. ‘-h,--help’

The standard –help option.

2.6 Specify isa-list entries to keep. ‘-i’ isa-list

Use this option select a subset of the ISAs for the architecture. This is useful, for example, to generate only Thumb support from an arm+thumb description.

2.7 Specify mach-list entries to keep. ‘-m’ mach-list

Use this option to select a subset of the machines of the architecture. This is useful, for example, to generate a simulator for a specific variant of the architecture.

2.8 Specify the source directory. ‘-s’ srcdir

Use this to specify where the rest of CGEN's files are.

For example in Binutils CGEN is typically a sibling of ‘src/opcodes’, i.e., ‘src/cgen’.

2.9 Specify tracing of various things. ‘-t’ trace-list

Use this to turn on the tracing of various things. The argument is a comma-separated list of things to trace. At present the following may be traced.

• ‘commands’

  Trace the commands from the description file(s).

• ‘pmacros’

  Trace the invocation and expansion of pmacros from the description file(s).

• ‘all’

  Trace everything.

Each application will invoke CGEN in its own way, so the details of enabling tracing may vary from application to application. Generally though, each application has a CGENFLAGS makefile variable for passing flags to CGEN.

Binutils example:

# Trace pmacro expansion while generating the m32r port's opcodes files
# in the binutils package.
cd obj/opcodes
rm stamp-m32r
make stamp-m32r CGENFLAGS="-v -b -t pmacros"

2.10 Increment the verbosity level. ‘-v’

Specifying multiple -v options will increase the verbosity.

2.11 Enable various diagnostics. ‘-w’ diagnostic-list

Use this to turn on warnings or errors of various things. The argument is a comma-separated list. At present the following diagnostics are supported.

• ‘iformat’

  Turn on verification of the instruction format. If an instruction's field list has missing bits or too many bits then a warning is issued.

  NOTE: The checking is incomplete, but it does catch most common forms of errors.

• ‘all’

  Turn on diagnostics for everything.

Each application will invoke CGEN in its own way, so the details of enabling diagnostics may vary from application to application. Generally though, each application has a CGENFLAGS makefile variable for passing flags to CGEN.

Binutils example:

# Turn on verification of instruction formats while generating
# the m32r port's opcodes files in the binutils package.
cd obj/opcodes
rm stamp-m32r
make stamp-m32r CGENFLAGS="-v -b -w iformat"

2.12 Print version info. ‘--version’

The standard –version option.

2.13 Opcodes generator arguments

The opcodes generator accepts these arguments.

-OPC FILE

Specify the path to the ‘.opc’ file. The ‘.opc’ file contains C code that is copied to the output. It's useful for providing non-standard or non-straightforward parsers and printers.

-H FILE

Generate $arch-desc.h in FILE.

-C ‘FILE’

Generate $arch-desc.c in FILE.

-O FILE

Generate $arch-opc.h in FILE.

-P FILE

Generate $arch-opc.c in FILE.

-Q FILE

Generate $arch-opinst.c in FILE.

-B FILE

Generate $arch-ibld.h in FILE.

-L FILE

Generate $arch-ibld.in in FILE.

-A FILE

Generate $arch-asm.in in FILE.

-D FILE

Generate $arch-dis.in in FILE.

2.14 Simulator generator arguments

The simulator generator accepts these arguments.

-A FILE

Generate arch.h in FILE.

-B FILE

Generate arch.c in FILE.

-C FILE

Generate cpu-<cpu>.h in FILE.

-U FILE

Generate cpu-<cpu>.c in FILE.

-N FILE

Generate cpu-all.h in FILE.

-F FILE

Generate memops.h in FILE.

-G FILE

Generate defs.h in FILE.

-P FILE

Generate semops.h in FILE.

-T FILE

Generate decode.h in FILE.

-D FILE

Generate decode.c in FILE.

-E FILE

Generate extract.c in FILE.

-R FILE

Generate read.c in FILE.

-W FILE

Generate write.c in FILE.

-S FILE

Generate semantics.c in FILE.

-X FILE

Generate sem-switch.c in FILE.

-O FILE

Generate ops.c in FILE.

-M FILE

Generate model.c in FILE.

-L FILE

Generate mainloop.in in FILE.

2.15 Sid generator arguments

The SID simulator generator accepts these arguments.

-H FILE

Generate desc.h in FILE.

-C FILE

Generate cpu.h in FILE.

-E FILE

Generate defs.h in FILE.

-T FILE

Generate decode.h in FILE.

-D FILE

Generate decode.cxx in FILE.

-W FILE

Generate write.cxx in FILE.

-S FILE

Generate semantics.cxx in FILE.

-X FILE

Generate sem-switch.cxx in FILE.

-M FILE

Generate model.cxx in FILE.

-N FILE

Generate model.h in FILE.

2.16 HTML doc generator arguments

The HTML doc generator accepts these arguments.

-H FILE

Generate $arch.html in FILE.

-I FILE

Generate $arch-insn.html in FILE.

-N FILE

Set the name of the insn.html file as FILE.

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