Copyright © 2000, 2007, 2009 Red Hat, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Introduction
************

This manual documents the internals of CGEN.

Introduction
************

This document details the implementation and internals of CGEN, the ``Cpu tools GENerator''.  It focuses on theory of operation and concepts rather than extensive details of the implementation -- these details date too quickly.

Conventions
***********

There are a number of conventions used in the CGEN source code.  If you take the time to absorb these now, the code will be much easier to understand.

  * Procedures and variables local to a file are named -foo.

  * Only routines that emit application code begin with gen-.

  * Symbols beginning with c- are either variables containing C code or procedures that generate C code, similarly for C++ and c++-.

  * Variables containing C code begin with c-.

  * Only routines that emit an entire file begin with cgen-.

  * All .cpu file elements shall have -foo-parse and -foo-read procedures.  These procedures all follow the same basic style for processing entries.

  * Global variables containing class definitions shall be named <class-name>.

  * Procedures related to a particular class shall be named class-name-proc-name, where class-name may be abbreviated.

  * Procedures that test whether something is an object of a particular class shall be named class-name?.

  * In keeping with Scheme conventions, predicates shall have a ? suffix.

  * In keeping with Scheme conventions, methods and procedures that modify an argument or have other side effects shall have a ! suffix, usually these procs return *UNSPECIFIED*.

  * All -foo-parse, parse-foo procs shall have context as the first argument. [FIXME: not all such procs have been converted]

Applications
************

Applications of CGEN generate source code for various cpu related tools. (One of the neglected concepts in CGEN is that it is not just an assembler/disassembler or simulator generator.  Those have just been the ones immediately needed and are straightforward to do.)

When you want to run the CGEN framework, an application-specific source file is loaded into the Guile interpreter to get CGEN running.  The main job of this source file is to load in any other source files it needs and then, ultimately, call the cgen procedure.

Here's an example of the invocation of cgen from cgen-sim.scm.

         (cgen #:argv argv
     	  #:app-name "sim"
     	  #:arg-spec sim-arguments
     	  #:init sim-init!
     	  #:finish sim-finish!
     	  #:analyze sim-analyze!))

This gets the whole framework started by:

 1. processing argv

 2. loading the .cpu file(s)

 3. analyzing the instruction set

 4. generating the source code for the app

Source file overview
********************

This table is a list of noteworthy files in CGEN.

*.cpu, *.opc, *.sim
     Files belonging to each CPU description. .opc and .sim files are automatically included if they are defined for the given architecture.

doc/*.texi
     Texinfo documentation for CGEN.

slib/*.scm
     Third-party libraries written in Scheme.  For example, sort.scm is a collection of procedures to sort lists.

cgen-gas.scm
     Top-level for GAS testsuite generation.

cgen-opc.scm
     Top-level for opcodes generation.

cgen-sid.scm
     Top-level for SID simulator generation.

cgen-sim.scm
     Top-level for older simulator generation.

cgen-stest.scm
     Top-level for simulator testsuite generation.

cos.scm
     CGEN object system.  Adds object oriented features to the Scheme language.  See the top of cos.scm for the user-visible procedures.  Note that this was written before goops. Switching to goops is not out of the question, it's just a question of prioritization.

read.scm
     Read and parse .cpu files.  maybe-load is used to load in files for required symbols if they are not already present in the environment (say, because it was compiled).

     This file contains cgen, is the main entry point called by application file generators. It just calls -cgen, but it does so wrapped inside a catch-with-backtrace procedure to make debugging easier.

simplify.inc
     Preprocessor macros to simplify CPU description files.  This file is not loaded by the Scheme interpreter, but is instead included by each .cpu file.

Version numbering
*****************

There are two version numbers: the version number of CGEN itself and a version number for the description language it accepts.  These are kept in the symbols -CGEN-VERSION and -CGEN-LANG-VERSION in read.scm.

Parsing
*******

Parsing of .cpu files is very consistent. Each element of the cpu description is handled in the same way.

There are two forms for each cpu description element:

 1. key/value pairs

 2. fixed order arguments

The key/value parser is named -<object>-read. For example, see -arch-read in mach.scm. It sets up default values for all elements of the object, parses the parameters that have been provided, and then calls the fixed-order parser.

The fixed order parser is named -<object>-parse. For example, see -arch-parse in mach.scm. It validates the parameters and then builds the requested object.

Debugging applications
**********************

The best way to debug your application at this point is to use the logit function to get a log of what cgen is doing. Or if you need a backtrace at a certain point then insert error function calls at select places to cause the interpreter to output a stack backtrace.  This can be useful for answering the ``How did I get here?'' question.

Guile 1.8 provides better debugging facilities than previous versions. These need to be investigated and documented here.

Debugging pmacros
*****************

At the implementation level, pmacros are expanded with the pmacro-expand Scheme procedure. For interactive debugging purposes there is pmacro-dump which is easier to use.

When debugging pmacros it is useful to see how they are expanded. When expanding them from the a Guile shell, remember that expressions needed to be quoted lest Scheme try to evaluate them.

     guile> (define-pmacro '(foo a b) '(+ a b))
     guile> (pmacro-dump '(foo 3 4))
     (+ 3 4)

One can also use pmacro-debug to expand a macro and trace its expansion.

Index
*****

     [file glossary.texi not included]