| 1 |
6 |
jlechner |
This is the README for CGEN 1.1.
|
| 2 |
|
|
|
| 3 |
|
|
If you just want to read up on cgen, I suggest going directly to the
|
| 4 |
|
|
doc directory, and in particular doc/intro.texi.
|
| 5 |
|
|
|
| 6 |
|
|
What is it?
|
| 7 |
|
|
-----------
|
| 8 |
|
|
|
| 9 |
|
|
In a nutshell, CGEN is a project to provide a uniform framework for doing
|
| 10 |
|
|
binutils and simulator ports without explicitly closing any doors on anything
|
| 11 |
|
|
else one might want to do with the cpu description (i.e. application
|
| 12 |
|
|
independence). The "cpu description" as defined here includes anything useful.
|
| 13 |
|
|
To this end CGEN is a very open-ended and ambitious project.
|
| 14 |
|
|
|
| 15 |
|
|
The core of CGEN is a cpu description file and code to slurp it in and
|
| 16 |
|
|
build a database describing the cpu. From this the Binutils opcodes table
|
| 17 |
|
|
can be generated for example, as well as an ISA simulator decoder/executor.
|
| 18 |
|
|
|
| 19 |
|
|
CGEN is not a new idea. Other GNU ports have done this (e.g. `sh' in its
|
| 20 |
|
|
early days). However, the idea never really "caught on". CGEN was started
|
| 21 |
|
|
because I think it should be.
|
| 22 |
|
|
|
| 23 |
|
|
CGEN is short for "Cpu tools GENerator".
|
| 24 |
|
|
|
| 25 |
|
|
Copyright
|
| 26 |
|
|
--------
|
| 27 |
|
|
|
| 28 |
|
|
CGEN is Copyright 2000, 2009 Red Hat, Inc.
|
| 29 |
|
|
|
| 30 |
|
|
The full text of the copyright for CGEN is contained in the file
|
| 31 |
|
|
COPYING.CGEN. The copyright of CGEN uses the Autoconf copyright
|
| 32 |
|
|
as a guide. The intent is to have CGEN under a GNU-style copyright but
|
| 33 |
|
|
place no restrictions on the output of CGEN.
|
| 34 |
|
|
|
| 35 |
|
|
Installation
|
| 36 |
|
|
------------
|
| 37 |
|
|
|
| 38 |
|
|
CGEN has been in use since 2000 with all releases of GNU Binutils and GDB.
|
| 39 |
|
|
GNU Binutils/GDB users will never "use" CGEN though. The generated sources
|
| 40 |
|
|
are shipped with GNU Binutils/GDB releases.
|
| 41 |
|
|
Binutils/GDB developers wishing to use CGEN must configure Binutils/GDB with
|
| 42 |
|
|
--enable-cgen-maint. This will add the necessary dependencies to
|
| 43 |
|
|
opcodes/Makefile and sim//Makefile for the supported processors.
|
| 44 |
|
|
|
| 45 |
|
|
CGEN uses Guile so Guile must be installed.
|
| 46 |
|
|
CGEN has been tested with Guile 1.4.1, 1.6.8, and 1.8.5.
|
| 47 |
|
|
Support for older versions of Guile will be removed in time.
|
| 48 |
|
|
|
| 49 |
|
|
Source Layout
|
| 50 |
|
|
-------------
|
| 51 |
|
|
|
| 52 |
|
|
CGEN sources are divided into several categories:
|
| 53 |
|
|
|
| 54 |
|
|
- documentation
|
| 55 |
|
|
- code to read .cpu files
|
| 56 |
|
|
- application source generators
|
| 57 |
|
|
- opcodes
|
| 58 |
|
|
- gas testsuite
|
| 59 |
|
|
- sim
|
| 60 |
|
|
- sim testsuite
|
| 61 |
|
|
- sid
|
| 62 |
|
|
- intrinsics
|
| 63 |
|
|
- html
|
| 64 |
|
|
- misc support scripts
|
| 65 |
|
|
- cpu specific files
|
| 66 |
|
|
- C support code
|
| 67 |
|
|
|
| 68 |
|
|
File naming rules:
|
| 69 |
|
|
|
| 70 |
|
|
1. The top level script for each application shall be named
|
| 71 |
|
|
cgen-.scm. No other files shall be named cgen-*.scm.
|
| 72 |
|
|
|
| 73 |
|
|
2. Files implementing a particular class (or related collection of
|
| 74 |
|
|
classes) shall be named .scm, or a reasonable
|
| 75 |
|
|
abbreviation thereof.
|
| 76 |
|
|
|
| 77 |
|
|
3. CPU description files shall be named .cpu and placed in the
|
| 78 |
|
|
`cpu' sub-directory (either src/cpu or src/cgen/cpu).
|
| 79 |
|
|
|
| 80 |
|
|
4. CPU opcode support files shall be named .opc and similarly
|
| 81 |
|
|
placed in the `cpu' sub-directory.
|
| 82 |
|
|
|
| 83 |
|
|
Documentation
|
| 84 |
|
|
-------------
|
| 85 |
|
|
|
| 86 |
|
|
Documentation uses texinfo.
|
| 87 |
|
|
See doc/*.texi.
|
| 88 |
|
|
|
| 89 |
|
|
doc/cgen.texi - top level .texi file, includes the others
|
| 90 |
|
|
doc/cgenint.texi - top level .texi file for cgen internals
|
| 91 |
|
|
|
| 92 |
|
|
Code to read .cpu files
|
| 93 |
|
|
-----------------------
|
| 94 |
|
|
|
| 95 |
|
|
These files provide the basic support for reading in .cpu files. They contain
|
| 96 |
|
|
no application specific code (and ideally as little C generating code as
|
| 97 |
|
|
possible too), they are intended to be application independent. Applications
|
| 98 |
|
|
(e.g. the opcode table generator and the simulator support generator) are
|
| 99 |
|
|
built on top of these files.
|
| 100 |
|
|
|
| 101 |
|
|
attr.scm - attribute support
|
| 102 |
|
|
enum.scm - enum support
|
| 103 |
|
|
hardware.scm - hardware description reader
|
| 104 |
|
|
ifield.scm - instruction field reader
|
| 105 |
|
|
iformat.scm - computes instruction formats
|
| 106 |
|
|
insn.scm - instruction description reader
|
| 107 |
|
|
mach.scm - architecture/cpu/machine reader
|
| 108 |
|
|
minsn.scm - macro-instruction description reader
|
| 109 |
|
|
mode.scm - mode support
|
| 110 |
|
|
model.scm - model reader
|
| 111 |
|
|
operand.scm - instruction operand reader
|
| 112 |
|
|
read.scm - top level script for .cpu file reading
|
| 113 |
|
|
rtl.scm - basic rtl support
|
| 114 |
|
|
rtl-traverse.scm - support for processing rtl
|
| 115 |
|
|
rtx-funcs.scm - defines all standard rtx functions
|
| 116 |
|
|
semantics.scm - routines for semantic analysis
|
| 117 |
|
|
types.scm - misc utilities related to types
|
| 118 |
|
|
|
| 119 |
|
|
Applications
|
| 120 |
|
|
------------
|
| 121 |
|
|
|
| 122 |
|
|
opcode table generator
|
| 123 |
|
|
----------------------
|
| 124 |
|
|
|
| 125 |
|
|
cgen-opc.scm - top level script to generate the opcode table + support
|
| 126 |
|
|
opcodes.scm
|
| 127 |
|
|
opc-asmdis.scm
|
| 128 |
|
|
opc-ibld.scm
|
| 129 |
|
|
opc-itab.scm
|
| 130 |
|
|
opc-opinst.scm
|
| 131 |
|
|
|
| 132 |
|
|
Additional support lives in the opcodes directory.
|
| 133 |
|
|
|
| 134 |
|
|
opcodes/cgen-ibld.in - input file for -ibld.c
|
| 135 |
|
|
opcodes/cgen-asm.in - input file for -asm.c
|
| 136 |
|
|
opcodes/cgen-dis.in - input file for -dis.c
|
| 137 |
|
|
opcodes/cgen-opc.c - architecture independent opcode table support
|
| 138 |
|
|
opcodes/cgen-asm.c - architecture independent assembler support
|
| 139 |
|
|
opcodes/cgen-dis.c - architecture independent disassembler support
|
| 140 |
|
|
opcodes/cgen.sh - shell script invoked by opcodes/Makefile to build
|
| 141 |
|
|
-opc.h, -opc.c, -asm.c, -dis.c.
|
| 142 |
|
|
|
| 143 |
|
|
The header file that defines the interface to the opcodes table is
|
| 144 |
|
|
include/opcode/cgen.h.
|
| 145 |
|
|
|
| 146 |
|
|
gas testsuite generator
|
| 147 |
|
|
-----------------------
|
| 148 |
|
|
|
| 149 |
|
|
cgen-gas.scm - top level script to generate gas testcases
|
| 150 |
|
|
gas-test.scm - generate gas testcases
|
| 151 |
|
|
|
| 152 |
|
|
simulator generator
|
| 153 |
|
|
-------------------
|
| 154 |
|
|
|
| 155 |
|
|
cgen-sim.scm - top level script to generate simulator files
|
| 156 |
|
|
sim-arch.scm - generator for architecture-wide support files
|
| 157 |
|
|
sim-cpu.scm - generator for cpu specific simulator files
|
| 158 |
|
|
sim-decode.scm - decoder generator
|
| 159 |
|
|
sim-model.scm - generates model support
|
| 160 |
|
|
sim.scm - interface between simulator generator and cpu database
|
| 161 |
|
|
|
| 162 |
|
|
Additional support lives in sim/common/cgen-*.[ch].
|
| 163 |
|
|
Architectures specific files live in sim/.
|
| 164 |
|
|
|
| 165 |
|
|
sim testsuite generator
|
| 166 |
|
|
-----------------------
|
| 167 |
|
|
|
| 168 |
|
|
cgen-stest.scm - top level script to generate simulator testcases
|
| 169 |
|
|
sim-test.scm - generate simulator testcases
|
| 170 |
|
|
|
| 171 |
|
|
sid (another architectural simulator)
|
| 172 |
|
|
-------------------------------------
|
| 173 |
|
|
|
| 174 |
|
|
cgen-sid.scm - top level script to generate sid files
|
| 175 |
|
|
sid-cpu.scm
|
| 176 |
|
|
sid-decode.scm
|
| 177 |
|
|
sid-model.scm
|
| 178 |
|
|
sid.scm
|
| 179 |
|
|
|
| 180 |
|
|
html
|
| 181 |
|
|
----
|
| 182 |
|
|
|
| 183 |
|
|
cgen-doc.scm - top level script to generate html files
|
| 184 |
|
|
html.scm
|
| 185 |
|
|
|
| 186 |
|
|
intrinsics
|
| 187 |
|
|
----------
|
| 188 |
|
|
|
| 189 |
|
|
cgen-intrinsics.scm - top level script to generate intrinsics files
|
| 190 |
|
|
intrinsics.scm
|
| 191 |
|
|
|
| 192 |
|
|
Misc. support scripts
|
| 193 |
|
|
---------------------
|
| 194 |
|
|
|
| 195 |
|
|
dev.scm - top level script for doing interactive development
|
| 196 |
|
|
guile.scm - Guile-specific definitions, and adaptations to specific
|
| 197 |
|
|
versions of Guile
|
| 198 |
|
|
cos.scm - OOP implementation
|
| 199 |
|
|
pmacros.scm - preprocessor-style macro package
|
| 200 |
|
|
profile.scm - Guile profiling tool [eventually wish to move this to
|
| 201 |
|
|
Guile distribution when finished]
|
| 202 |
|
|
utils-cgen.scm - various utilities specific to cgen
|
| 203 |
|
|
utils.scm - generic Scheme utilities [non cgen specific]
|
| 204 |
|
|
slib/genwrite.scm - generic-write routine
|
| 205 |
|
|
slib/logical.scm - utilities for boolean operations
|
| 206 |
|
|
slib/pp.scm - pretty printer
|
| 207 |
|
|
slib/random.scm - random number generator
|
| 208 |
|
|
slib/sort.scm - sort routine, from slib
|
| 209 |
|
|
|
| 210 |
|
|
CPU specific files
|
| 211 |
|
|
------------------
|
| 212 |
|
|
|
| 213 |
|
|
.cpu - description file
|
| 214 |
|
|
.opc - opcode support
|
| 215 |
|
|
|
| 216 |
|
|
null.cpu - minimal .cpu file for debugging purposes
|
