path: root/cgen/README

This is the README for CGEN 0.7.1

If you just want to read up on cgen, I suggest going directly to the
doc directory, and in particular doc/intro.texi.

What is it?
===========

In a nutshell, CGEN is a project to provide a uniform framework for doing
binutils and simulator ports without explicitly closing any doors on anything
else one might want to do with the cpu description (i.e. application
independence).  The "cpu description" as defined here includes anything useful.
To this end CGEN is a very open-ended and ambitious project.

The core of CGEN is a cpu description file and code to slurp it in and
build a database describing the cpu.  From this the Binutils opcodes table
can be generated for example, as well as an ISA simulator decoder/executor.

CGEN is not a new idea.  Other GNU ports have done this (e.g. `sh' in its
early days).  However, the idea never really "caught on".  CGEN was started
because I think it should be.

CGEN is short for "Cpu tools GENerator".  It's not a very good name.
I'm not very good at picking names.  An early version of the name was
"GENCPU"!  So give me a better one.

Copyright
=========

CGEN is Copyright 2000 Red Hat, Inc.

The full text of the copyright for CGEN is contained in the file
COPYING.CGEN.  The copyright of CGEN uses the Autoconf copyright
as a guide.  The intent is to have CGEN under a GNU-style copyright but
place no restrictions on the output of CGEN.

Installation
============

CGEN 0.7.1 can be used with GNU Binutils snapshots as of ??????
and GNU GDB snapshots as of ??????.
GNU Binutils/GDB users will never "use" CGEN.  The generated sources
are shipped with GNU Binutils/GDB releases.
Binutils/GDB developers wishing to use CGEN must configure Binutils/GDB with
--enable-cgen-maint.  This will add the necessary dependencies to
opcodes/Makefile and sim/<arch>/Makefile for the supported processors, which
at this point is M32R and FR30.

CGEN uses Guile so Guile must be installed.
Guile 1.2 and 1.3 are supported.
2) 

Source Layout
=============

CGEN sources are divided into several categories:

- documentation
- code to read .cpu files
- opcode table generator
- gas testsuite generator
- simulator generator
- misc support scripts
- cpu specific files
- C support code

File naming rules:

1) The top level script for each application shall be named cgen-<appl>.scm.
   No other files shall be named cgen-*.scm.
2) Files implementing a particular class (or related collection of classes)
   shall be named <class-name>.scm, or a reasonable abbreviation thereof.
3) CPU description files shall be named <arch>.cpu.
   [it should go without saying that no other files shall be named <arch>.cpu]
4) CPU opcode support files shall be named <arch>.opc.
   [it should go without saying that no other files shall be named <arch>.opc]

??? May wish to change (1) to <appl>-cgen.scm so that each application's
files will be collected together in `ls' output by the <appl>- prefix.

documentation
-------------

doc/cgen.texi - top level .texi file, includes the others
doc/rtl.texi - cpu description language (based on GCC's RTL)
doc/intro.texi - global overview of cgen
doc/opcodes.texi - opcode table usage of cgen
doc/porting.texi - porting guide for new ports
doc/sim.texi - simulator usage of cgen
doc/credits.texi - inspiration and contributors

code to read .cpu files
-----------------------

These files provide the basic support for reading in .cpu files.  They contain
no application specific code (and ideally as little C generating code as
possible too), they are intended to be application independent.  Applications
(e.g. the opcode table generator and the simulator support generator) are
built on top of these files.

attr.scm - attribute support
read.scm - top level script for .cpu file reading
enum.scm - enum support
hardware.scm - hardware description reader
ifield.scm - instruction field reader
iformat.scm - computes instruction formats
insn.scm - instruction description reader
mach.scm - architecture/cpu/machine reader
minsn.scm - macro-instruction description reader
mode.scm - mode support
model.scm - model reader
operand.scm - instruction operand reader
rtl.scm - basic rtl support
rtx-funcs.scm - defines all standard rtx functions
types.scm - type system

opcode table generator
---------------------

cgen-opc.scm - top level script to generate the opcode table + support
opcodes.scm - opcode table generator
opc-asmdis.scm
opc-ibld.scm
opc-itab.scm
opc-opinst.scm

Additional support lives in the opcodes directory.

opcodes/cgen-ibld.in - input file for <arch>-ibld.c
opcodes/cgen-asm.in - input file for <arch>-asm.c
opcodes/cgen-dis.in - input file for <arch>-dis.c
opcodes/cgen-opc.c - architecture independent opcode table support
opcodes/cgen-asm.c - architecture independent assembler support
opcodes/cgen-dis.c - architecture independent disassembler support
opcodes/cgen.sh - shell script invoked by opcodes/Makefile to build
                  <arch>-opc.h, <arch>-opc.c, <arch>-asm.c, <arch>-dis.c.

The header file that defines the interface to the opcodes table is
include/opcode/cgen.h.

gas testsuite generator
-----------------------

cgen-gas.scm - top level script to generate gas testcases
gas-test.scm - generate gas testcases

simulator generator
-------------------

cgen-sim.scm - top level script to generate simulator files
sim-arch.scm - generator for architecture-wide support files
sim-cpu.scm - generator for cpu specific simulator files
sim-decode.scm - decoder generator
sim-model.scm - generates model support
sim.scm - interface between simulator generator and cpu database

Additional support lives in sim/common/cgen-*.[ch].
Architectures specific files live in sim/<arch>.

misc. support scripts
---------------------

dev.scm - top level script for doing interactive development
fixup.scm - munges the Scheme environment to make it suit us
	[Guile is/was still in flux]
cos.scm - OOP implementation
pmacros.scm - preprocessor-style macro package
profile.scm - Guile profiling tool [eventually wish to move this to
	Guile distribution when finished]
sort.scm - sort routine, from slib
utils-cgen.scm - various utilities specific to cgen
utils.scm - generic Scheme utilities [non cgen specific]

cpu specific files
------------------

<arch>.cpu - <arch> description file
<arch>.opc - <arch> opcode support

null.cpu - minimal .cpu file for debugging purposes

C version of cgen
-----------------

Makefile.am, Makefile.in - automake stuff
acconfig.h,aclocal.m4,config.in,stamp-h.in - autoconf stuff
configure.in,configure - autoconf stuff
gdbinit.in - source for .gdbinit file
cgen.c - main()
cgen-gh.[ch] - additional functionality to Guile's gh interface
cos.[ch] - C implementation of cgen object system