@c Copyright (C) 2000, 2009 Red Hat, Inc.
@c This file is part of the CGEN manual.
@c For copying conditions, see the file cgen.texi.

@node Running CGEN
@chapter Running CGEN

CGEN is usually run from a shell script provided by the application.
For example, in @file{libopcodes} there is @file{cgen.sh}.

The main tasks of this script are to:

@enumerate
@item Set up the arguments for cgen.
@item Run cgen.
@item Apply any post processing to the output files.
@end enumerate

@subsection 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.

@c organization of application-specific args needs work

@menu
* a::            -a Specify path of .cpu file to load.
* b::            -b Use debugging evaluator, for backtraces.
* d::            -d Start interactive debugging session.
* f::            -f Specify a set of flags to control code generation.
* h::            -h,--help Print usage information.
* i::            -i Specify isa-list entries to keep.
* m::            -m Specify mach-list entries to keep.
* s::            -s Specify the source directory.
* t::            -t Specify tracing of various things.
* v::            -v Increment the verbosity level.
* w::            -w Enable various diagnostics.
* version::      --version Print version info.

* opcodes::      Opcodes generator arguments.
* sim::          Simulator generator arguments.
* sid::          Sid generator arguments.
* html::         HTML doc generator arguments.
@end menu

@node a
@section Specify path of architecture's .cpu file to load. @option{-a} @var{path}

Use this option to specify the @file{.cpu} file to load.

@node b
@section Use debugging evaluator, for backtraces. @option{-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.

@node d
@section Start interactive debugging session. @option{-d}

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

@node f
@section Specify a set of flags to control code generation. @option{-f} @var{flags}

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

@c Need to say more here, and for each option.

@menu
* Opcodes Generator Options::        Opcodes Generator Options
* GDB Simulator Generator Options::  GDB Generator Simulator
* SID Simulator Generator Options::  SID Generator Simulator
* HTML Doc Generator Options::       HTML Doc Generator Options
@end menu

@node Opcodes Generator Options
@subsection Opcodes Generator Options

The @code{Opcodes} generator accepts the following options:

@table @code

@item opinst
Include the operand instance table in the generated code.

@item copyright=<kind>
The argument is the copyright to add to the generated code.
It must be one of @code{fsf} or @code{redhat}.

@item package=<package>
The argument is the package the opcodes files are being generated for.
It must be one of @code{binutils}, @code{gnusim} (the simulators in GDB
releases) or @code{cygsim} (SID simulators).

@end table

@node GDB Simulator Generator Options
@subsection GDB Simulator Generator Options

@table @code

@item 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.

@item 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

@item 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.

@item 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.
@c What happens if this option is left off?

@item with-parallel-only
@c Only generate parallel versions of each insn.

@item copyright=<kind>
The argument is the copyright to add to the generated code.
It must be one of @code{fsf} or @code{redhat}.

@item package=<package>
The argument is the package the simulator files are being generated for.
It must be one of @code{gnusim} (the simulators in GDB
releases) or @code{cygsim} (SID simulators).
@c Is cygsim old or what?  SID has its own generators.

@end table

@node SID Simulator Generator Options
@subsection SID Simulator Generator Options

@table @code

@item 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.

@emph{NOTE:} Not all targets support this option.

@item 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.

@emph{NOTE:} Not all targets support this option.

@item with-sem-frags

Specify this option to enable the semantic fragment engine.

@emph{NOTE:} This option requires @code{with-pbb}.

@emph{NOTE:} Not all targets support this option.

@item 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

@item 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.

@item copyright=<kind>
The argument is the copyright to add to the generated code.
It must be one of @code{fsf} or @code{redhat}.

@item package=<package>
The argument is the package the simulator files are being generated for.
It must be one of @code{gnusim} (the simulators in GDB
releases) or @code{cygsim} (SID simulators).
@c What's gnusim doing here?

@end table

@node HTML Doc Generator Options
@subsection HTML Doc Generator Options

@table @code

@item copyright=<kind>
The argument is the copyright to add to the generated code.
It must be @code{doc}.

@item package=<package>
The argument is the package the opcodes files are being generated for.
It must be @code{cgen}.

@end table

@node h
@section Print usage information. @option{-h,--help}

The standard --help option.

@node i
@section Specify isa-list entries to keep. @option{-i} @var{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.

@node m
@section Specify mach-list entries to keep. @option{-m} @var{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.

@node s
@section Specify the source directory. @option{-s} @var{srcdir}

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

For example in @code{Binutils} CGEN is typically a sibling
of @file{src/opcodes}, i.e., @file{src/cgen}.

@node t
@section Specify tracing of various things. @option{-t} @var{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.

@itemize @bullet

@item @option{commands}

Trace the commands from the description file(s).

@item @option{pmacros}

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

@item @option{all}

Trace everything.

@end itemize

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:

@smallexample
# 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"
@end smallexample

@node v
@section Increment the verbosity level. @option{-v}

Specifying multiple @code{-v} options will increase the verbosity.

@node w
@section Enable various diagnostics. @option{-w} @var{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.

@itemize @bullet

@item @option{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.

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

@item @option{all}

Turn on diagnostics for everything.

@end itemize

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:

@smallexample
# 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"
@end smallexample

@node version
@section Print version info. @option{--version}

The standard --version option.

@node opcodes
@section Opcodes generator arguments

The opcodes generator accepts these arguments.

@table @code
@item @code{-OPC} @var{FILE}
Specify the path to the @file{.opc} file.
The @file{.opc} file contains C code that is copied to the output.
It's useful for providing non-standard or non-straightforward
parsers and printers.

@item @code{-H} @var{FILE}
Generate $arch-desc.h in FILE.

@item @code{-C} @file{FILE}
Generate $arch-desc.c in FILE.

@item @code{-O} @var{FILE}
Generate $arch-opc.h in FILE.

@item @code{-P} @var{FILE}
Generate $arch-opc.c in FILE.

@item @code{-Q} @var{FILE}
Generate $arch-opinst.c in FILE.

@item @code{-B} @var{FILE}
Generate $arch-ibld.h in FILE.

@item @code{-L} @var{FILE}
Generate $arch-ibld.in in FILE.

@item @code{-A} @var{FILE}
Generate $arch-asm.in in FILE.

@item @code{-D} @var{FILE}
Generate $arch-dis.in in FILE.

@end table

@node sim
@section Simulator generator arguments

The simulator generator accepts these arguments.

@table @code

@item @code{-A} @var{FILE}
Generate arch.h in FILE.

@item @code{-B} @var{FILE}
Generate arch.c in FILE.

@item @code{-C} @var{FILE}
Generate cpu-<cpu>.h in FILE.

@item @code{-U} @var{FILE}
Generate cpu-<cpu>.c in FILE.

@item @code{-N} @var{FILE}
Generate cpu-all.h in FILE.

@item @code{-F} @var{FILE}
Generate memops.h in FILE.

@item @code{-G} @var{FILE}
Generate defs.h in FILE.

@item @code{-P} @var{FILE}
Generate semops.h in FILE.

@item @code{-T} @var{FILE}
Generate decode.h in FILE.

@item @code{-D} @var{FILE}
Generate decode.c in FILE.

@item @code{-E} @var{FILE}
Generate extract.c in FILE.

@item @code{-R} @var{FILE}
Generate read.c in FILE.

@item @code{-W} @var{FILE}
Generate write.c in FILE.

@item @code{-S} @var{FILE}
Generate semantics.c in FILE.

@item @code{-X} @var{FILE}
Generate sem-switch.c in FILE.

@item @code{-O} @var{FILE}
Generate ops.c in FILE.

@item @code{-M} @var{FILE}
Generate model.c in FILE.

@item @code{-L} @var{FILE}
Generate mainloop.in in FILE.

@end table

@node sid
@section Sid generator arguments

The SID simulator generator accepts these arguments.

@table @code

@item @code{-H} @var{FILE}
Generate desc.h in FILE.

@item @code{-C} @var{FILE}
Generate cpu.h in FILE.

@item @code{-E} @var{FILE}
Generate defs.h in FILE.

@item @code{-T} @var{FILE}
Generate decode.h in FILE.

@item @code{-D} @var{FILE}
Generate decode.cxx in FILE.

@item @code{-W} @var{FILE}
Generate write.cxx in FILE.

@item @code{-S} @var{FILE}
Generate semantics.cxx in FILE.

@item @code{-X} @var{FILE}
Generate sem-switch.cxx in FILE.

@item @code{-M} @var{FILE}
Generate model.cxx in FILE.

@item @code{-N} @var{FILE}
Generate model.h in FILE.

@end table

@node html
@section HTML doc generator arguments

The HTML doc generator accepts these arguments.

@table @code

@item @code{-H} @var{FILE}
Generate $arch.html in FILE.

@item @code{-I} @var{FILE}
Generate $arch-insn.html in FILE.

@item @code{-N} @var{FILE}
Set the name of the insn.html file as FILE.

@end table
