This is the README for CGEN 1.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". Copyright -------- CGEN is Copyright 2000, 2009 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 has been in use since 2000 with all releases of GNU Binutils and GDB. GNU Binutils/GDB users will never "use" CGEN though. 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//Makefile for the supported processors. CGEN uses Guile so Guile must be installed. CGEN has been tested with Guile 1.4.1, 1.6.8, and 1.8.5. Support for older versions of Guile will be removed in time. Source Layout ------------- CGEN sources are divided into several categories: - documentation - code to read .cpu files - application source generators - opcodes - gas testsuite - sim - sim testsuite - sid - intrinsics - html - misc support scripts - cpu specific files - C support code File naming rules: 1. The top level script for each application shall be named cgen-.scm. No other files shall be named cgen-*.scm. 2. Files implementing a particular class (or related collection of classes) shall be named .scm, or a reasonable abbreviation thereof. 3. CPU description files shall be named .cpu and placed in the `cpu' sub-directory (either src/cpu or src/cgen/cpu). 4. CPU opcode support files shall be named .opc and similarly placed in the `cpu' sub-directory. Documentation ------------- Documentation uses texinfo. See doc/*.texi. doc/cgen.texi - top level .texi file, includes the others doc/cgenint.texi - top level .texi file for cgen internals 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 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 read.scm - top level script for .cpu file reading rtl.scm - basic rtl support rtl-traverse.scm - support for processing rtl rtx-funcs.scm - defines all standard rtx functions semantics.scm - routines for semantic analysis types.scm - misc utilities related to types Applications ------------ opcode table generator ---------------------- cgen-opc.scm - top level script to generate the opcode table + support opcodes.scm 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 -ibld.c opcodes/cgen-asm.in - input file for -asm.c opcodes/cgen-dis.in - input file for -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 -opc.h, -opc.c, -asm.c, -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/. sim testsuite generator ----------------------- cgen-stest.scm - top level script to generate simulator testcases sim-test.scm - generate simulator testcases sid (another architectural simulator) ------------------------------------- cgen-sid.scm - top level script to generate sid files sid-cpu.scm sid-decode.scm sid-model.scm sid.scm html ---- cgen-doc.scm - top level script to generate html files html.scm intrinsics ---------- cgen-intrinsics.scm - top level script to generate intrinsics files intrinsics.scm Misc. support scripts --------------------- dev.scm - top level script for doing interactive development guile.scm - Guile-specific definitions, and adaptations to specific versions of Guile 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] utils-cgen.scm - various utilities specific to cgen utils.scm - generic Scheme utilities [non cgen specific] slib/genwrite.scm - generic-write routine slib/logical.scm - utilities for boolean operations slib/pp.scm - pretty printer slib/random.scm - random number generator slib/sort.scm - sort routine, from slib CPU specific files ------------------ .cpu - description file .opc - opcode support null.cpu - minimal .cpu file for debugging purposes