This is the mail archive of the cgen@sourceware.org mailing list for the CGEN project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH] internals.texi -> cgenint.texi, plus some editing


Hi.

If internals.texi ever got installed the name wouldn't be meaningful,
so I renamed it to cgenint.texi (a la gdbint.texi).
I also did a bit of editing.

I'll check this in in a few days if there are no objections.

2009-06-10  Doug Evans  <dje@sebabeach.org>

	* doc/cgenint.texi: Renamed from doc/internals.texi.
	Minor editing pass.

Index: doc/cgenint.texi
===================================================================
RCS file: doc/cgenint.texi
diff -N doc/cgenint.texi
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ doc/cgenint.texi	10 Jun 2009 21:29:48 -0000
@@ -0,0 +1,276 @@
+\input texinfo       @c                    -*- Texinfo -*-
+
+@c This file is work in progress.
+
+@include version.texi
+
+@copying
+Copyright @copyright{} 2000, 2007 Red Hat, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end copying
+
+@synindex ky cp
+@c
+@c This file documents the internals of the Cpu tools GENerator, CGEN.
+@c
+@c Copyright (C) 2000 Red Hat, Inc.
+@c
+
+@setchapternewpage odd
+@settitle CGEN
+@titlepage
+@finalout
+@title The Cpu tools GENerator, CGEN.
+@subtitle Version @value{VERSION}
+@sp 1
+@subtitle @value{UPDATED}
+@author Ben Elliston
+@author Red Hat, Inc.
+@page
+
+@tex
+{\parskip=0pt \hfill Red Hat, Inc.\par \hfill
+\TeX{}info \texinfoversion\par }
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2000 Red Hat, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@node Top
+@top Introduction
+
+@cindex version
+This manual documents the internals of CGEN, version @value{VERSION}.
+
+@menu
+* Introduction::                Introduction
+* Conventions::                 Coding conventions
+* Applications::                Applications of CGEN
+* Source file overview::        Introduction to each source file
+* Parsing::                     Parsing of .cpu files
+* Debugging::			Debugging applications
+* Version numbering::           CGEN version numbering
+* Glossary::                    Glossary
+* Index::                       Index
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+This document details the implementation and internals of CGEN, the
+``Cpu tools GENerator''.  It focuses on theory of operation and concepts
+rather than extensive details of the implementation -- these details
+date too quickly.
+
+@node Conventions
+@chapter Conventions
+
+There are a number of conventions used in the CGEN source code.  If you
+take the time to absorb these now, the code will be much easier to
+understand.
+
+@itemize @bullet
+
+@item Procedures and variables local to a file are named @code{-foo}.
+
+@item Only routines that emit application code begin with @code{gen-}.
+
+@item Symbols beginning with @code{c-} are either variables containing C code
+or procedures that generate C code, similarly for C++ and @code{c++-}.
+
+@item Variables containing C code begin with @code{c-}.
+
+@item Only routines that emit an entire file begin with @code{cgen-}.
+
+@item All @file{.cpu} file elements shall have @code{-foo-parse} and
+@code{-foo-read} procedures.  These procedures all follow the same
+basic style for processing entries.
+
+@item Global variables containing class definitions shall be named
+@code{<class-name>}.
+
+@item Procedures related to a particular class shall be named
+@code{class-name-proc-name}, where @code{class-name} may be abbreviated.
+
+@item Procedures that test whether something is an object of a
+particular class shall be named @code{class-name?}.
+
+@item In keeping with Scheme conventions, predicates shall have a
+@code{?} suffix.
+
+@item In keeping with Scheme conventions, methods and procedures that
+modify an argument or have other side effects shall have a
+@code{!} suffix, usually these procs return @code{*UNSPECIFIED*}.
+
+@item All @code{-foo-parse}, @code{parse-foo} procs shall have @code{context}
+as the first argument. [FIXME: not all such procs have been converted]
+
+@end itemize
+
+@node Applications
+@chapter Applications
+
+Applications of CGEN generate source code for various cpu related tools.
+@footnote{One of the neglected concepts in CGEN is that it is not just
+an assembler/disassembler or simulator generator.  Those have just been
+the ones immediately needed and are straightforward to do.}
+
+When you want to run the CGEN framework, an application-specific source
+file is loaded into the Guile interpreter to get CGEN running.  The main
+job of this source file is to load in any other source files it needs and
+then, ultimately, call the @code{cgen} procedure.
+
+Here's an example of the invocation of @code{cgen} from @file{cgen-sim.scm}.
+
+@example
+    (cgen #:argv argv
+	  #:app-name "sim"
+	  #:arg-spec sim-arguments
+	  #:init sim-init!
+	  #:finish sim-finish!
+	  #:analyze sim-analyze!))
+@end example
+
+This gets the whole framework started by:
+
+@enumerate
+@item processing argv
+@item loading the @file{.cpu} file(s)
+@item analyzing the instruction set
+@item generating the source code for the app
+@end enumerate
+
+@node Source file overview
+@chapter Source file overview
+
+This table is a list of noteworthy files in CGEN.
+
+@table @file
+
+@item *.cpu, *.opc, *.sim
+Files belonging to each CPU description.
+@file{.opc} and @file{.sim} files are automatically
+included if they are defined for the given architecture.
+
+@item doc/*.texi
+Texinfo documentation for CGEN.
+
+@item slib/*.scm
+Third-party libraries written in Scheme.  For example, sort.scm is a
+collection of procedures to sort lists.
+
+@item cgen-gas.scm
+Top-level for GAS testsuite generation.
+
+@item cgen-opc.scm
+Top-level for opcodes generation.
+
+@item cgen-sid.scm
+Top-level for SID simulator generation.
+ 
+@item cgen-sim.scm
+Top-level for older simulator generation.
+
+@item cgen-stest.scm
+Top-level for simulator testsuite generation.
+
+@item cos.scm
+CGEN object system.  Adds object oriented features to the Scheme
+language.  See the top of @file{cos.scm} for the user-visible
+procedures.  Note that this was written before goops.
+Switching to goops is not out of the question, it's just a question
+of prioritization.
+
+@item read.scm
+Read and parse @file{.cpu} files.  @code{maybe-load} is used to load in files
+for required symbols if they are not already present in the environment
+(say, because it was compiled).
+
+This file contains @code{cgen}, is the main entry point called by
+application file generators.
+It just calls @code{-cgen}, but it does so wrapped inside a
+@code{catch-with-backtrace} procedure to make debugging easier.
+
+@item simplify.inc
+Preprocessor macros to simplify CPU description files.  This file is not
+loaded by the Scheme interpreter, but is instead included by each
+@file{.cpu} file.
+
+@end table
+
+@node Version numbering
+@chapter Version numbering
+
+There are two version numbers: the version number of CGEN itself and a
+version number for the description language it accepts.  These are kept
+in the symbols @code{-CGEN-VERSION} and @code{-CGEN-LANG-VERSION} in
+@file{read.scm}.
+
+@node Parsing
+@chapter Parsing
+
+Parsing of @file{.cpu} files is very consistent.
+Each element of the cpu description is handled in the same way.
+
+There are two forms for each cpu description element:
+
+@enumerate
+@item key/value pairs
+@item fixed order arguments
+@end enumerate
+
+The key/value parser is named @code{-<object>-read}.
+For example, see @code{-arch-read} in @file{mach.scm}.
+It sets up default values for all elements of the object, parses the parameters
+that have been provided, and then calls the fixed-order parser.
+
+The fixed order parser is named @code{-<object>-parse}.
+For example, see @code{-arch-parse} in @file{mach.scm}.
+It validates the parameters and then builds the requested object.
+
+@node Debugging
+@chapter Debugging
+
+The best way to debug your application @emph{at this point} is to
+use the @code{logit} function to get a log of what cgen is doing.
+Or if you need a backtrace at a certain point then insert @code{error}
+function calls at select places to cause the interpreter to output a
+stack backtrace.  This can be useful for answering the
+``How did I get here?'' question.
+
+Guile 1.8 provides better debugging facilities than previous versions.
+These need to be investigated and documented here.
+
+@node Index
+@unnumbered Index
+
+@include glossary.texi
+
+@printindex cp
+
+@contents
+@bye
Index: doc/internals.texi
===================================================================
RCS file: doc/internals.texi
diff -N doc/internals.texi
--- doc/internals.texi	22 May 2007 09:16:36 -0000	1.4
+++ /dev/null	1 Jan 1970 00:00:00 -0000
@@ -1,385 +0,0 @@
-\input texinfo       @c                    -*- Texinfo -*-
-
-@c This file is work in progress.
-@c Don't expect it to go through texinfo just yet. --bje
-
-@include version.texi
-
-@copying
-Copyright @copyright{} 2000, 2007 Red Hat, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end copying
-
-@synindex ky cp
-@c
-@c This file documents the internals of the Cpu tools GENerator, CGEN.
-@c
-@c Copyright (C) 2000 Red Hat, Inc.
-@c
-
-@setchapternewpage odd
-@settitle CGEN
-@titlepage
-@finalout
-@title The Cpu tools GENerator, CGEN.
-@subtitle Version @value{VERSION}
-@sp 1
-@subtitle @value{UPDATED}
-@author Ben Elliston
-@author Red Hat, Inc.
-@page
-
-@tex
-{\parskip=0pt \hfill Red Hat, Inc.\par \hfill
-\TeX{}info \texinfoversion\par }
-@end tex
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 2000 Red Hat, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end titlepage
-
-@node Top
-@top Introduction
-
-@cindex version
-This manual documents the internals of CGEN, version @value{VERSION}.
-
-@menu
-* Introduction::                Introduction
-* Guile::
-* Conventions::                 Coding conventions
-* Applications::
-* Source file overview::
-* Option processing::
-* Parsing::
-* Debugging::			Debugging applications
-* Version numbering::
-* Glossary::                    Glossary
-* Index::                       Index
-@end menu
-
-@node Introduction
-@chapter Introduction
-
-This document details the implementation and internals of CGEN, the
-``Cpu tools GENerator''.  It focuses on theory of operation and concepts
-rather than extensive details of the implementation--these details
-date too quickly.
-
-@node Conventions
-@chapter Conventions
-
-There are a number of conventions used in the cgen source code.  If you
-take the time to absorb these now, the code will be much easier to
-understand.
-
-@itemize @bullet
-@item Procedures and variables local to a file are named @code{-foo}.
-@item Only routines that emit application code begin with @code{gen-}.
-@item Symbols beginning with @code{c-} are either variables containing C code
-      or procedures that generate C code, similarly for C++ and @code{c++-}.
-@item Variables containing C code begin with @code{c-}.
-@item Only routines that emit an entire file begin with @code{cgen-}.
-@item All @file{.cpu} file elements shall have @code{-foo-parse} and
-      @code{-foo-read} procedures.
-@item Global variables containing class definitions shall be named
-      @code{<class-name>}.
-@item Procedures related to a particular class shall be named
-      @code{class-name-proc-name}, where @code{class-name} may be abbreviated.
-@item Procedures that test whether something is an object of a
-      particular class shall be named @code{class-name?}.
-@item In keeping with Scheme conventions, predicates shall have a
-      @code{?} suffix.
-@item In keeping with Scheme conventions, methods and procedures that
-      modify an argument or have other side effects shall have a
-      @code{!} suffix, usually these procs return @code{*UNSPECIFIED*}.
-@item All @code{-foo-parse}, @code{parse-foo} procs shall have @code{context}
-      as the first argument. [FIXME: not all such procs have been
-      converted]
-@end itemize
-
-@node Applications
-@chapter Applications
-
-One of the most importance concepts to grasp with CGEN is that it is not
-a simulator generator.  It's a generic tool generator--it can be used to
-generate a simulator, an assembler, a disassembler and so on.  These
-``applications'' can then produce different outputs from the same CPU
-description.
-
-When you want to run the cgen framework, an application-specific source
-file is loaded into the Guile interpreter to get cgen running.  This
-source file loads in any other source files it needs and then, for
-example, calls:
-
-@example
-    (cgen #:argv argv
-	  #:app-name "sim"
-	  #:arg-spec sim-arguments
-	  #:init sim-init!
-	  #:finish sim-finish!
-	  #:analyze sim-analyze!)
-    )
-@end example
-
-This gets the whole framework started, in an application-specific way.
-
-node Source file overview
-@chapter Source file overview
-
-@table @file
-
-@item *.cpu, *.opc, *.sim
-Files belonging to each CPU description.  .sim files are automatically
-included if they are defined for the given architecture.
-
-@item doc/*.texi
-Texinfo documentation for cgen.
-
-@item slib/*.scm
-Third-party libraries written in Scheme.  For example, sort.scm is a
-collection of procedures to sort lists.
-
-@item Makefile.am
-automake Makefile for cgen.
-
-@item NEWS
-News about cgen.
-
-@item README
-Notes to read abot cgen.
-
-@item attr.scm
-Handling of cgen attributes.
-
-@item cgen-gas.scm
-Top-level for GAS testsuite generation.
-
-@item cgen-opc.scm
-Top-level for opcodes generation.
-
-@item cgen-sid.scm
-Top-level for SID simulator generation.
- 
-@item cgen-sim.scm
-Top-level for older simulator generation.
-
-@item cgen-stest.scm
-Top-level for simulator testsuite generation.
-
-@item configure.in
-Template for `configure'--process with autoconf.
-
-@item cos.scm
-cgen object system.  Adds object oriented features to the Scheme
-language.  See the top of @file{cos.scm} for the user-visible
-procedures.
-
-@item decode.scm
-Generic decoder routines.
-
-@item desc-cpu.scm
-???
-
-@item desc.scm
-???
-
-@item dev.scm
-Debugging support.
-
-@item enum.scm
-Enumerations.
-
-@item fixup.scm
-Some procedure definitions to patch up possible differences between
-older and newer versions of Guile:
-
-  * define a (load..) procedure that uses
-    primitive-load-path if load-from-path is not known.
-
-  * define =? and >=? if they aren't already known.
-
-  * define %stat, reverse! and debug-enable in terms of
-    older equivalent procedures, if they aren't already
-    known.
-
-@item gas-test.scm
-GAS testsuite generator.
-
-@item hardware.scm
-Hardware description routines.
-
-@item ifield.scm
-Instruction fields.
-
-@item insn.scm
-Instruction definitions.
-
-@item mach.scm
-Architecture description routines.
-
-@item minsn.scm
-Macro instructions.
-
-@item mode.scm
-Modes.
-
-@item model.scm
-Model specification.
-
-@item opc-asmdis.scm
-For the opcodes applications.
-
-@item opc-ibld.scm
-Ditto.
-
-@item opc-itab.scm
-Ditto.
-
-@item opc-opinst.scm
-Ditto.
-
-@item opcodes.scm
-Ditto.
-
-@item operand.scm
-Operands.
-
-@item pgmr-tools.scm
-Programmer tools--debugging tools, mainly.
-
-@item pmacros.scm
-Preprocessor macros.
-
-@item profile.scm
-Unused?
-
-@item read.scm
-Read and parse .cpu files.  @code{maybe_load} is used to load in files
-for required symbols if they are not already present in the environment
-(say, because it was compiled).
-
-@item rtl-c.scm
-RTL to C translation.
-
-@item rtl.scm
-RTL support.
-
-@item rtx-funcs.scm
-RTXs.
-
-@item sem-frags.scm
-Semantic fragments.
-
-@item semantics.scm
-Semantic analysis for the CPU descriptions.
-
-@item sid-cpu.scm
-For the SID application.
-
-@item sid-decode.scm
-Ditto.
-
-@item sid-model.scm
-Ditto.
-
-@item sid.scm
-Ditto.
-
-@item sim-arch.scm
-For the simulator application.
-
-@item sim-cpu.scm
-Ditto.
-
-@item sim-decode.scm
-Ditto.
-
-@item sim-model.scm
-Ditto.
-
-@item sim-test.scm
-For the simulator testsuite application.
-
-@item sim.scm
-For the simulator application.
-
-@item simplify.inc
-Preprocessor macros to simplify CPU description files.  This file is not
-loaded by the Scheme interpreter, but is instead included by the .cpu
-file.
-
-@item types.scm
-Low-level types.
-
-@item utils-cgen.scm
-cgen-specific utilities.
-
-@item utils-gen.scm
-Code generation specific utilities.
-
-@item utils-sim.scm
-Simulator specific utilities.
-
-@item utils.scm
-Miscellaneous utilities.
-
-@end table
-
-@code{cgen} is the main entry point called by application file
-generators. It just calls @code{-cgen}, but it does so wrapped inside a
-@code{catch-with-backtrace} procedure to make debugging easier.
-
-@node Version numbering
-@chapter Version numbering
-
-There are two version numbers: the version number of cgen itself and a
-version number for the description language it accepts.  These are kept
-in the symbols @code{-CGEN-VERSION} and @code{-CGEN-LANG-VERSION} in
-@file{read.scm}.
-
-@node Debugging
-@chapter Debugging
-
-Debugging can be difficult in Guile.  Guile 1.4 (configured with the
---enable-guile-debug option) seems unable to produce a stack backtrace
-when errors are triggered in Scheme code.  You should use Guile 1.3 in
-the meantime.  So far, the best way to debug your application is to
-insert (error) function applications at select places to cause the
-interpreter to output a stack backtrace.  This can be useful for
-answering the ``How did I get here?''  question.
-
-CGEN includes a (logit) function which logs error messages at different
-diagnostic levels.  If you want to produce debugging output, use
-(logit).
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@contents
-@bye


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]