cgen/README

   1 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/<arch>/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-<appl>.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 <class-name>.scm, or a reasonable
  75    abbreviation thereof.
  76
  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).
  79
  80 4. CPU opcode support files shall be named <arch>.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 <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.
 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/<arch>.
 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 <arch>.cpu - <arch> description file
 214 <arch>.opc - <arch> opcode support
 215
 216 null.cpu - minimal .cpu file for debugging purposes