1 This is the README for CGEN 1.1.
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.
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.
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.
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.
23 CGEN is short for "Cpu tools GENerator".
28 CGEN is Copyright 2000, 2009 Red Hat, Inc.
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.
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/<arch>/Makefile for the supported processors.
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.
52 CGEN sources are divided into several categories:
55 - code to read .cpu files
56 - application source generators
64 - misc support scripts
70 1. The top level script for each application shall be named
71 cgen-<appl>.scm. No other files shall be named cgen-*.scm.
73 2. Files implementing a particular class (or related collection of
74 classes) shall be named <class-name>.scm, or a reasonable
77 3. CPU description files shall be named <arch>.cpu and placed in the
78 `cpu' sub-directory (either src/cpu or src/cgen/cpu).
80 4. CPU opcode support files shall be named <arch>.opc and similarly
81 placed in the `cpu' sub-directory.
86 Documentation uses texinfo.
89 doc/cgen.texi - top level .texi file, includes the others
90 doc/cgenint.texi - top level .texi file for cgen internals
92 Code to read .cpu files
93 -----------------------
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.
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
122 opcode table generator
123 ----------------------
125 cgen-opc.scm - top level script to generate the opcode table + support
132 Additional support lives in the opcodes directory.
134 opcodes/cgen-ibld.in - input file for <arch>-ibld.c
135 opcodes/cgen-asm.in - input file for <arch>-asm.c
136 opcodes/cgen-dis.in - input file for <arch>-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 <arch>-opc.h, <arch>-opc.c, <arch>-asm.c, <arch>-dis.c.
143 The header file that defines the interface to the opcodes table is
144 include/opcode/cgen.h.
146 gas testsuite generator
147 -----------------------
149 cgen-gas.scm - top level script to generate gas testcases
150 gas-test.scm - generate gas testcases
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
162 Additional support lives in sim/common/cgen-*.[ch].
163 Architectures specific files live in sim/<arch>.
165 sim testsuite generator
166 -----------------------
168 cgen-stest.scm - top level script to generate simulator testcases
169 sim-test.scm - generate simulator testcases
171 sid (another architectural simulator)
172 -------------------------------------
174 cgen-sid.scm - top level script to generate sid files
183 cgen-doc.scm - top level script to generate html files
189 cgen-intrinsics.scm - top level script to generate intrinsics files
192 Misc. support scripts
193 ---------------------
195 dev.scm - top level script for doing interactive development
196 guile.scm - Guile-specific definitions, and adaptations to specific
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
213 <arch>.cpu - <arch> description file
214 <arch>.opc - <arch> opcode support
216 null.cpu - minimal .cpu file for debugging purposes