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.

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.

Specify path of architecture's .cpu file to load. -a PATH
=========================================================

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

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.

Start interactive debugging session. -d
=======================================

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

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.

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

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

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

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.

Print usage information. -h,--help
==================================

The standard --help option.

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.

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.

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.

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"

Increment the verbosity level. -v
=================================

Specifying multiple -v options will increase the verbosity.

Print version info. --version
=============================

The standard --version option.

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.

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.

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.

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.