Initial revision

1 files changed, 1105 insertions, 0 deletions

diff --git a/sim/ppc/psim.texinfo b/sim/ppc/psim.texinfo
new file mode 100644
index 00000000000..f81e46099c4
--- /dev/null
+++ b/sim/ppc/psim.texinfo
@@ -0,0 +1,1105 @@
+\input texinfo.tex    @c -*-texinfo-*-
+@comment %**start of header
+@setfilename texinfo
+@settitle Texinfo @value{edition}
+@syncodeindex vr fn
+@footnotestyle separate
+@paragraphindent 2
+@smallbook
+@comment %**end of header
+
+@c Set smallbook if printing in smallbook format so the example of the
+@c smallbook font is actually written using smallbook; in bigbook, a kludge
+@c is used for TeX output.
+@set smallbook
+@c @@clear smallbook
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo).           The documentation format for the GNU Project.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@end ignore
+
+@set edition 2.21
+@set update-date 7 June 1995
+@set update-month June 1995
+
+@c Experiment with smaller amounts of whitespace between chapters
+@c and sections.
+@tex
+\global\chapheadingskip = 15pt plus 4pt minus 2pt 
+\global\secheadingskip = 12pt plus 3pt minus 2pt
+\global\subsecheadingskip = 9pt plus 2pt minus 2pt
+@end tex
+
+@c Experiment with smaller amounts of whitespace between paragraphs in
+@c the 8.5 by 11 inch format.
+@ifclear smallbook
+@tex
+\global\parskip 6pt plus 1pt
+@end tex
+@end ifclear
+
+@finalout
+
+@c Currently undocumented command, 5 December 1993:
+@c
+@c nwnode          (Same as node, but no warnings; for `makeinfo'.)
+
+@ifinfo
+This file documents Texinfo, a documentation system that uses a single
+source file to produce both on-line information and a printed manual.
+
+Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc.
+
+This is the second edition of the Texinfo documentation,@*
+and is consistent with version 2 of @file{texinfo.tex}.
+
+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.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided 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,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@setchapternewpage odd
+
+@shorttitlepage Texinfo
+
+@titlepage
+@c use the new format for titles
+@title Texinfo
+@subtitle The GNU Documentation Format
+@subtitle Edition @value{edition}, for Texinfo Version Three
+@subtitle @value{update-month}
+
+@author by Robert J. Chassell and Richard M. Stallman
+
+@comment   Include the Distribution inside the titlepage so
+@c that headings are turned off. 
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc.
+
+@sp 2
+This is the second edition of the Texinfo documentation,@*
+and is consistent with version 2 of @file{texinfo.tex}.
+@sp 2
+
+Published by the Free Software Foundation @*
+59 Temple Place Suite 330, @*
+Boston, MA 02111-1307 USA @*
+Printed copies are available for $15 each.@*
+ISBN 1-882114-63-9
+@c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995
+
+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 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,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@sp 2
+Cover art by Etienne Suvasa.
+@end titlepage
+
+@ifinfo
+@node Top, Copying, (dir), (dir)
+@top Texinfo
+
+Texinfo is a documentation system that uses a single source file to
+produce both on-line information and printed output.@refill
+
+The first part of this master menu lists the major nodes in this Info
+document, including the @@-command and concept indices.  The rest of
+the menu lists all the lower level nodes in the document.@refill
+
+This is Edition @value{edition} of the Texinfo documentation, 
+@w{@value{update-date},} for Texinfo Version Three.
+@end ifinfo
+
+@c Here is a spare copy of the chapter menu entry descriptions,
+@c in case they are accidently deleted 
+@ignore
+Your rights.
+Texinfo in brief.
+How to use Texinfo mode.
+What is at the beginning of a Texinfo file?
+What is at the end of a Texinfo file?
+How to create chapters, sections, subsections,
+  appendices, and other parts.
+How to provide structure for a document.
+How to write nodes.
+How to write menus.
+How to write cross references.
+How to mark words and phrases as code,
+  keyboard input, meta-syntactic
+  variables, and the like.
+How to write quotations, examples, etc.
+How to write lists and tables.
+How to create indices.
+How to insert @@-signs, braces, etc.
+How to indicate results of evaluation,
+  expansion of macros, errors, etc.
+How to force and prevent line and page breaks.
+How to describe functions and the like in a uniform manner.
+How to write footnotes.
+How to specify text for either @TeX{} or Info.
+How to print hardcopy.
+How to create an Info file.
+How to install an Info file
+A list of all the Texinfo @@-commands.
+Hints on how to write a Texinfo document.
+A sample Texinfo file to look at.
+Tell readers they have the right to copy
+  and distribute.
+How to incorporate other Texinfo files.
+How to write page headings and footings.
+How to find formatting mistakes.
+All about paragraph refilling.
+A description of @@-Command syntax.
+Texinfo second edition features.
+A menu containing commands and variables.
+A menu covering many topics.
+@end ignore
+
+@menu
+* Copying::                     Your rights. 
+* Overview::                    Texinfo in brief.
+* Texinfo Mode::                How to use Texinfo mode.
+* Beginning a File::            What is at the beginning of a Texinfo file?
+* Ending a File::               What is at the end of a Texinfo file?
+* Structuring::                 How to create chapters, sections, subsections,
+                                  appendices, and other parts.
+* Nodes::                       How to write nodes.
+* Menus::                       How to write menus.
+* Cross References::            How to write cross references.
+* Marking Text::                How to mark words and phrases as code,
+                                  keyboard input, meta-syntactic
+                                  variables, and the like.
+* Quotations and Examples::     How to write quotations, examples, etc.
+* Lists and Tables::            How to write lists and tables.
+* Indices::                     How to create indices.
+* Insertions::                  How to insert @@-signs, braces, etc.
+* Glyphs::                      How to indicate results of evaluation,
+                                  expansion of macros, errors, etc.
+* Breaks::                      How to force and prevent line and page breaks.
+* Definition Commands::         How to describe functions and the like 
+                                  in a uniform manner.
+* Footnotes::                   How to write footnotes.
+* Conditionals::                How to specify text for either @TeX{} or Info.
+* Format/Print Hardcopy::       How to convert a Texinfo file to a file
+                                  for printing and how to print that file.
+* Create an Info File::         Convert a Texinfo file into an Info file.
+* Install an Info File::        Make an Info file accessible to users.
+* Command List::                All the Texinfo @@-commands.
+* Tips::                        Hints on how to write a Texinfo document.
+* Sample Texinfo File::         A sample Texinfo file to look at.
+* Sample Permissions::          Tell readers they have the right to copy
+                                  and distribute.
+* Include Files::               How to incorporate other Texinfo files.
+* Headings::                    How to write page headings and footings.
+* Catching Mistakes::           How to find formatting mistakes.
+* Refilling Paragraphs::        All about paragraph refilling.
+* Command Syntax::              A description of @@-Command syntax.
+* Obtaining TeX::               How to Obtain @TeX{}.
+* New Features::                Texinfo second edition features.
+* Command and Variable Index::  A menu containing commands and variables.
+* Concept Index::               A menu covering many topics.
+
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Using Texinfo::               Create a conventional printed book 
+                                  or an Info file.
+* Info Files::                  What is an Info file?
+* Printed Books::               Characteristics of a printed book or manual.
+* Formatting Commands::         @@-commands are used for formatting.
+* Conventions::                 General rules for writing a Texinfo file.
+* Comments::                    How to write comments and mark regions that
+                                  the formatting commands will ignore.
+* Minimum::                     What a Texinfo file must have.
+* Six Parts::                   Usually, a Texinfo file has six parts.
+* Short Sample::                A short sample Texinfo file.
+* Acknowledgements::            
+
+Using Texinfo Mode
+
+* Texinfo Mode Overview::       How Texinfo mode can help you.
+* Emacs Editing::               Texinfo mode adds to GNU Emacs' general
+                                  purpose editing features.
+* Inserting::                   How to insert frequently used @@-commands. 
+* Showing the Structure::       How to show the structure of a file.
+* Updating Nodes and Menus::    How to update or create new nodes and menus.
+* Info Formatting::             How to format for Info.
+* Printing::                    How to format and print part or all of a file.
+* Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
+
+Updating Nodes and Menus
+
+* Updating Commands::           Five major updating commands.
+* Updating Requirements::       How to structure a Texinfo file for
+                                  using the updating command.
+* Other Updating Commands::     How to indent descriptions, insert
+                                  missing nodes lines, and update
+                                  nodes in sequence.
+
+Beginning a Texinfo File
+
+* Four Parts::                  Four parts begin a Texinfo file.
+* Sample Beginning::            Here is a sample beginning for a Texinfo file.
+* Header::                      The very beginning of a Texinfo file.
+* Info Summary and Permissions::  Summary and copying permissions for Info.
+* Titlepage & Copyright Page::  Creating the title and copyright pages.
+* The Top Node::                Creating the `Top' node and master menu.
+* Software Copying Permissions::  Ensure that you and others continue to
+                                  have the right to use and share software.
+
+The Texinfo File Header
+
+* First Line::                  The first line of a Texinfo file.  
+* Start of Header::             Formatting a region requires this.
+* setfilename::                 Tell Info the name of the Info file.
+* settitle::                    Create a title for the printed work.
+* setchapternewpage::           Start chapters on right-hand pages.
+* paragraphindent::             An option to specify paragraph indentation.
+* End of Header::               Formatting a region requires this.
+
+The Title and Copyright Pages
+
+* titlepage::                   Create a title for the printed document.
+* titlefont center sp::         The @code{@@titlefont}, @code{@@center},
+                                  and @code{@@sp} commands.
+* title subtitle author::       The @code{@@title}, @code{@@subtitle},
+                                  and @code{@@author} commands.
+* Copyright & Permissions::     How to write the copyright notice and
+                                  include copying permissions.
+* end titlepage::               Turn on page headings after the title and
+                                  copyright pages.
+* headings on off::             An option for turning headings on and off
+                                  and double or single sided printing.
+
+The `Top' Node and Master Menu
+
+* Title of Top Node::           Sketch what the file is about.
+* Master Menu Parts::           A master menu has three or more parts.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus::    How to print an index in hardcopy and 
+                                  generate index menus in Info.
+* Contents::                    How to create a table of contents.
+* File End::                    How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring::            A manual is like an upside down tree @dots{}
+* Structuring Command Types::   How to divide a manual into parts.
+* makeinfo top::                The @code{@@top} command, part of the `Top' node.
+* chapter::                     
+* unnumbered & appendix::       
+* majorheading & chapheading::  
+* section::                     
+* unnumberedsec appendixsec heading::  
+* subsection::                  
+* unnumberedsubsec appendixsubsec subheading::  
+* subsubsection::               Commands for the lowest level sections.
+* Raise/lower sections::        How to change commands' hierarchical level.
+
+Nodes
+
+* Two Paths::                   Different commands to structure 
+                                  Info output and printed output.
+* Node Menu Illustration::      A diagram, and sample nodes and menus.
+* node::                        How to write a node, in detail.
+* makeinfo Pointer Creation::   How to create node pointers with @code{makeinfo}.
+
+The @code{@@node} Command
+
+* Node Names::                  How to choose node and pointer names.
+* Writing a Node::              How to write an @code{@@node} line.
+* Node Line Tips::              Keep names short.
+* Node Line Requirements::      Keep names unique, without @@-commands.
+* First Node::                  How to write a `Top' node.
+* makeinfo top command::        How to use the @code{@@top} command. 
+* Top Node Summary::            Write a brief description for readers.
+
+Menus
+
+* Menu Location::               Put a menu in a short node.
+* Writing a Menu::              What is a menu?
+* Menu Parts::                  A menu entry has three parts.
+* Less Cluttered Menu Entry::   Two part menu entry.
+* Menu Example::                Two and three part menu entries.
+* Other Info Files::            How to refer to a different Info file.
+
+Cross References
+
+* References::                  What cross references are for.
+* Cross Reference Commands::    A summary of the different commands.
+* Cross Reference Parts::       A cross reference has several parts.
+* xref::                        Begin a reference with `See' @dots{}
+* Top Node Naming::             How to refer to the beginning of another file.
+* ref::                         A reference for the last part of a sentence.
+* pxref::                       How to write a parenthetical cross reference.
+* inforef::                     How to refer to an Info-only file.
+
+@code{@@xref}
+
+* Reference Syntax::            What a reference looks like and requires.
+* One Argument::                @code{@@xref} with one argument.
+* Two Arguments::               @code{@@xref} with two arguments.
+* Three Arguments::             @code{@@xref} with three arguments.
+* Four and Five Arguments::     @code{@@xref} with four and five arguments.
+
+Marking Words and Phrases
+
+* Indicating::                  How to indicate definitions, files, etc.
+* Emphasis::                    How to emphasize text.
+
+Indicating Definitions, Commands, etc.
+
+* Useful Highlighting::         Highlighting provides useful information.
+* code::                        How to indicate code.
+* kbd::                         How to show keyboard input.
+* key::                         How to specify keys.
+* samp::                        How to show a literal sequence of characters.
+* var::                         How to indicate a metasyntactic variable.
+* file::                        How to indicate the name of a file.
+* dfn::                         How to specify a definition.
+* cite::                        How to refer to a book that is not in Info.
+
+Emphasizing Text
+
+* emph & strong::               How to emphasize text in Texinfo.
+* Smallcaps::                   How to use the small caps font.
+* Fonts::                       Various font commands for printed output.
+* Customized Highlighting::     How to define highlighting commands.
+
+Quotations and Examples
+
+* Block Enclosing Commands::    Use different constructs for 
+                                  different purposes.
+* quotation::                   How to write a quotation.
+* example::                     How to write an example in a fixed-width font.
+* noindent::                    How to prevent paragraph indentation.
+* Lisp Example::                How to illustrate Lisp code.
+* smallexample & smalllisp::    Forms for the @code{@@smallbook} option.
+* display::                     How to write an example in the current font.
+* format::                      How to write an example that does not narrow
+                                  the margins.
+* exdent::                      How to undo the indentation of a line.
+* flushleft & flushright::      How to push text flushleft or flushright.
+* cartouche::                   How to draw cartouches around examples.
+
+Making Lists and Tables
+
+* Introducing Lists::           Texinfo formats lists for you.
+* itemize::                     How to construct a simple list.
+* enumerate::                   How to construct a numbered list.
+* Two-column Tables::           How to construct a two-column table.
+
+Making a Two-column Table
+
+* table::                       How to construct a two-column table.
+* ftable vtable::               How to construct a two-column table
+                                  with automatic indexing.
+* itemx::                       How to put more entries in the first column.
+
+Creating Indices
+
+* Index Entries::               Choose different words for index entries.
+* Predefined Indices::          Use different indices for different kinds
+                                  of entry.
+* Indexing Commands::           How to make an index entry.
+* Combining Indices::           How to combine indices.
+* New Indices::                 How to define your own indices.
+
+Combining Indices
+
+* syncodeindex::                How to merge two indices, using @code{@@code}
+                                  font for the merged-from index.
+* synindex::                    How to merge two indices, using the
+                                  default font of the merged-to index.
+
+Special Insertions
+
+* Braces Atsigns Periods::      How to insert braces, @samp{@@} and periods.
+* dmn::                         How to format a dimension.
+* Dots Bullets::                How to insert dots and bullets.
+* TeX and copyright::           How to insert the @TeX{} logo 
+                                  and the copyright symbol.
+* minus::                       How to insert a minus sign.
+* math::                        How to format a mathematical expression.
+
+Inserting @samp{@@}, Braces, and Periods
+
+* Inserting An Atsign::         
+* Inserting Braces::            How to insert @samp{@{} and @samp{@}}
+* Controlling Spacing::         How to insert the right amount of space
+                                  after punctuation within a sentence.
+
+Inserting Ellipsis, Dots, and Bullets
+
+* dots::                        How to insert dots @dots{}
+* bullet::                      How to insert a bullet.
+
+Inserting @TeX{} and the Copyright Symbol
+
+* tex::                         How to insert the @TeX{} logo.
+* copyright symbol::            How to use @code{@@copyright}@{@}.
+
+Glyphs for Examples 
+
+* Glyphs Summary::              
+* result::                      How to show the result of expression.
+* expansion::                   How to indicate an expansion.
+* Print Glyph::                 How to indicate printed output.
+* Error Glyph::                 How to indicate an error message.
+* Equivalence::                 How to indicate equivalence.
+* Point Glyph::                 How to indicate the location of point.
+
+Making and Preventing Breaks
+
+* Break Commands::              Cause and prevent splits.
+* Line Breaks::                 How to force a single line to use two lines.
+* w::                           How to prevent unwanted line breaks. 
+* sp::                          How to insert blank lines.
+* page::                        How to force the start of a new page.
+* group::                       How to prevent unwanted page breaks.
+* need::                        Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template::            How to structure a description using a
+                                  definition command.
+* Optional Arguments::          How to handle optional and repeated arguments.
+* deffnx::                      How to group two or more `first' lines.
+* Def Cmds in Detail::          All the definition commands.
+* Def Cmd Conventions::         Conventions for writing definitions.
+* Sample Function Definition::  
+
+The Definition Commands
+
+* Functions Commands::          Commands for functions and similar entities.
+* Variables Commands::          Commands for variables and similar entities.
+* Typed Functions::             Commands for functions in typed languages.
+* Typed Variables::             Commands for variables in typed languages.
+* Abstract Objects::            Commands for object-oriented programming.
+* Data Types::                  The definition command for data types.
+
+Footnotes
+
+* Footnote Commands::           How to write a footnote in Texinfo.
+* Footnote Styles::             Controlling how footnotes appear in Info.
+
+Conditionally Visible Text
+
+* Conditional Commands::        How to specify text for Info or @TeX{}.
+* Using Ordinary TeX Commands::  You can use any and all @TeX{} commands.
+* set clear value::             How to designate which text to format (for
+                                  both Info and @TeX{}); and how to set a
+                                  flag to a string that you can insert.
+
+@code{@@set}, @code{@@clear}, and @code{@@value}
+
+* ifset ifclear::               Format a region if a flag is set.
+* value::                       Replace a flag with a string. 
+* value Example::               An easy way to update edition information.
+
+Format and Print Hardcopy
+
+* Use TeX::                     Use @TeX{} to format for hardcopy.
+* Format with tex/texindex::    How to format in a shell.
+* Format with texi2dvi::        A simpler way to use the shell.
+* Print with lpr::              How to print.
+* Within Emacs::                How to format and print from an Emacs shell.
+* Texinfo Mode Printing::       How to format and print in Texinfo mode.
+* Compile-Command::             How to print using Emacs's compile command.
+* Requirements Summary::        @TeX{} formatting requirements summary.
+* Preparing for TeX::           What you need to do to use @TeX{}.
+* Overfull hboxes::             What are and what to do with overfull hboxes.
+* smallbook::                   How to print small format books and manuals.
+* A4 Paper::                    How to print on European A4 paper.
+* Cropmarks and Magnification::  How to print marks to indicate the size
+                                of pages and how to print scaled up output.
+
+Creating an Info File
+
+* makeinfo advantages::         @code{makeinfo} provides better error checking.
+* Invoking makeinfo::           How to run @code{makeinfo} from a shell.
+* makeinfo options::            Specify fill-column and other options.
+* Pointer Validation::          How to check that pointers point somewhere.
+* makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
+* texinfo-format commands::     Two Info formatting commands written
+                                  in Emacs Lisp are an alternative 
+                                  to @code{makeinfo}.
+* Batch Formatting::            How to format for Info in Emacs Batch mode.
+* Tag and Split Files::         How tagged and split files help Info 
+                                  to run better.
+
+Installing an Info File
+
+* Directory file::              The top level menu for all Info files.
+* New Info File::               Listing a new info file.
+* Other Info Directories::      How to specify Info files that are 
+                                  located in other directories.
+
+Sample Permissions
+
+* Inserting Permissions::       How to put permissions in your document.
+* ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
+* Titlepage Permissions::       Sample Titlepage copying permissions.
+
+Include Files
+
+* Using Include Files::         How to use the @code{@@include} command.
+* texinfo-multiple-files-update::  How to create and update nodes and
+                                  menus when using included files.
+* Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
+* Sample Include File::         A sample outer file with included files
+                                  within it; and a sample included file.
+* Include Files Evolution::     How use of the @code{@@include} command
+                                  has changed over time.
+
+Page Headings
+
+* Headings Introduced::         Conventions for using page headings.
+* Heading Format::              Standard page heading formats.
+* Heading Choice::              How to specify the type of page heading.
+* Custom Headings::             How to create your own headings and footings.
+
+Formatting Mistakes
+
+* makeinfo preferred::          @code{makeinfo} finds errors.
+* Debugging with Info::         How to catch errors with Info formatting.
+* Debugging with TeX::          How to catch errors with @TeX{} formatting.
+* Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
+* Using occur::                 How to list all lines containing a pattern.
+* Running Info-Validate::       How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using Info-validate::         How to run @code{Info-validate}.
+* Unsplit::                     How to create an unsplit file.
+* Tagifying::                   How to tagify a file.
+* Splitting::                   How to split a file manually.
+
+Second Edition Features
+
+* New Texinfo Mode Commands::   The updating commands are especially useful.
+* New Commands::                Many newly described @@-commands.
+@end menu
+
+@node Copying, Overview, Top, Top
+@comment  node-name, next, previous,  up
+@unnumbered Texinfo Copying Conditions
+@cindex Copying conditions
+@cindex Conditions for copying Texinfo
+
+The programs currently being distributed that relate to Texinfo include
+portions of GNU Emacs, plus other separate programs (including
+@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
+These programs are @dfn{free}; this means that everyone is free to use
+them and free to redistribute them on a free basis.  The Texinfo-related
+programs are not in the public domain; they are copyrighted and there
+are restrictions on their distribution, but these restrictions are
+designed to permit everything that a good cooperating citizen would want
+to do.  What is not allowed is to try to prevent others from further
+sharing any version of these programs that they might get from
+you.@refill
+
+  Specifically, we want to make sure that you have the right to give
+away copies of the programs that relate to Texinfo, that you receive
+source code or else can get it if you want it, that you can change these
+programs or use pieces of them in new free programs, and that you know
+you can do these things.@refill
+
+  To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights.  For example, if you distribute
+copies of the Texinfo related programs, you must give the recipients all
+the rights that you have.  You must make sure that they, too, receive or
+can get the source code.  And you must tell them their rights.@refill
+
+  Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for the programs that relate to Texinfo.
+If these programs are modified by someone else and passed on, we want
+their recipients to know that what they have is not what we distributed,
+so that any problems introduced by others will not reflect on our
+reputation.@refill
+
+  The precise conditions of the licenses for the programs currently
+being distributed that relate to Texinfo are found in the General Public
+Licenses that accompany them.@refill
+
+@node Overview, Texinfo Mode, Copying, Top
+@comment  node-name,  next,  previous,  up
+@chapter Overview of Texinfo
+@cindex Overview of Texinfo
+@cindex Texinfo overview
+
+@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is
+pronounced like ``speck'', not ``hex''.  This odd pronunciation is
+derived from, but is not the same as, the pronunciation of @TeX{}.  In
+the word @TeX{}, the @samp{X} is actually the Greek letter ``chi''
+rather than the English letter ``ex''.  Pronounce @TeX{} as if the
+@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
+as if the @samp{x} were a `k'.  Spell ``Texinfo'' with a capital ``T''
+and write the other letters in lower case.} 
+is a documentation system that uses a single source file to produce both
+on-line information and printed output.  This means that instead of
+writing two different documents, one for the on-line help or other on-line
+information and the other for a typeset manual or other printed work, you
+need write only one document.  When the work is revised, you need revise
+only one document.  (You can read the on-line information, known as an
+@dfn{Info file}, with an Info documentation-reading program.)@refill
+
+@menu
+* Using Texinfo::               Create a conventional printed book 
+                                  or an Info file.
+* Info Files::                  What is an Info file?
+* Printed Books::               Characteristics of a printed book or manual.
+* Formatting Commands::         @@-commands are used for formatting.
+* Conventions::                 General rules for writing a Texinfo file.
+* Comments::                    How to write comments and mark regions that
+                                  the formatting commands will ignore.
+* Minimum::                     What a Texinfo file must have.
+* Six Parts::                   Usually, a Texinfo file has six parts.
+* Short Sample::                A short sample Texinfo file.
+* Acknowledgements::            
+@end menu
+
+@c ************************************************************************
+
+
+
+\input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename psim.info
+@settitle PSIM
+@setchapternewpage odd
+@c %**end of header
+
+
+
+@ifinfo
+This file documents the program PSIM.
+
+Copyright (C) 1994-1996, Andrew Cagney.
+
+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.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, subject to the terms
+of the GNU General Public License, which includes the provision 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 ifinfo
+
+
+@titlepage
+@title PSIM
+@subtitle Model of the PowerPC Environments
+@author Andrew Cagney
+
+@page
+@vskip Opt plus ifill
+Copyright @copyright{} 1994-1996, Andrew Cagney
+
+This is the first edition of the PSIM manual and is consistent with PSIM
+version 1.0.
+
+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, subject to the terms
+of the GNU General Public License, which includes the provision 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
+
+
+
+@menu
+
+* Copying::             Your rights and freedoms.
+* First Chappeter::     Getting started ....
+* Second Chapter::      Getting finished ....
+
+
+@end menu
+
+
+PSIM is a program written in extended ANSI-C that implements an
+instruction level simulation of the PowerPC environment.  It is freely
+available in source code form under the terms of the GNU General
+Public License (version 2 or later).
+
+The PowerPC Architecture is described as having three levels of
+compliance:
+
+	UEA - User Environment Architecture
+	VEA - Virtual Environment Architecture
+	OEA - Operating Environment Architecture
+
+PSIM both implements all three levels of the PowerPC and includes (for
+each level) a corresponding simulated run-time environment.
+
+In addition, PSIM, to the execution unit level, models the performance
+of most of the current PowerPC implementations (contributed by Michael
+Meissner).  This detailed performance monitoring (unlike many other
+simulators) resulting in only a relatively marginal reduction in the
+simulators performance.
+
+
+A description of how to build PSIM is contained in the file:
+
+		ftp://ftp.ci.com.au/pub/psim/INSTALL
+	or	ftp://cambridge.cygnus.com/pub/psim/INSTALL
+
+while an overview of how to use PSIM is in:
+
+	ftp://ftp.ci.com.au/pub/psim/RUN
+or	ftp://cambridge.cygnus.com/pub/psim/RUN
+
+This file is found in:
+
+	ftp://ftp.ci.com.au/pub/psim/README
+or	ftp://cambridge.cygnus.com/pub/psim/README
+
+
+Thanks goes firstly to:
+
+	Corinthian Engineering Pty Ltd
+	Cygnus Support
+	Highland Logic Pty Ltd
+
+who provided the resources needed for making this software available
+on the Internet.
+
+More importantly I'd like to thank the following individuals who each
+contributed in their own unique way:
+
+	Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam,
+	Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn,
+	Richard Stallman, Mitchele Walker
+
+
+				Andrew Cagney
+				Feb, 1995
+
+
+    ----------------------------------------------------------------------
+
+
+    What features does PSIM include?
+
+	Monitoring and modeling
+
+		PSIM includes (thanks to Michael Meissner)
+		a detailed model of most of the PowerPC
+		implementations to the functional unit level.
+
+
+	SMP
+		
+		The PowerPC ISA defines SMP synchronizing instructions.
+		This simulator implements a limited, but functional,
+		subset of the PowerPC synchronization instructions
+		behaviour.  Programs that restrict their synchronization
+		primitives to those that work with this functional
+		sub-set (eg P() and V()) are able to run on the SMP
+		version of PSIM.
+
+		People intending to use this system should study
+		the code implementing the lwarx instruction.
+		
+	ENDIAN SUPPORT
+
+		PSIM implements the PowerPC's big and little (xor
+		endian) modes and correctly simulates code that
+		switches between these two modes.
+
+		In addition, psim can model a true little-endian
+		machine.
+
+	ISA (Instruction Set Architecture) models
+
+		PSIM includes a model of the UEA, VEA and OEA.  This
+		includes the time base registers (VEA) and HTAB
+		and BATS (OEA).
+
+		In addition, a preliminary model of the 64 bit
+		PowerPC architecture is implemented.
+
+	IO Hardware
+
+		PSIM's internals are based around the concept
+		of a Device Tree.  This tree intentionally
+		resembles that of the Device Tree found in
+		OpenBoot firmware.  PSIM is flexible enough
+		to allow the user to fully configure this device
+		tree (and consequently the hardware model) at
+		run time.
+
+	Run-time environments:
+
+		PSIM's UEA model includes emulation for BSD
+		based UNIX system calls.
+
+		PSIM's OEA model includes emulation of either:
+
+			o	OpenBoot client interface
+
+			o	MOTO's BUG interface.
+
+
+	Floating point
+
+		Preliminary support for floating point is included.
+
+
+    Who would be interested in PSIM?
+
+	o	the curious
+
+		Using psim, gdb, gcc and binutils the curious
+		user can construct an environment that allows
+		them to play with PowerPC Environment without
+		the need for real hardware.
+
+
+	o	the analyst
+
+		PSIM includes many (contributed) monitoring
+		features which (unlike many other simulators)
+		do not come with a great penalty in performance.
+
+		Thus the performance analyst is able to use
+		this simulator to analyse the performance of
+		the system under test.
+
+		If PSIM doesn't monitor a components of interest,
+		the source code is freely available, and hence
+		there is no hinderance to changing things
+		to meet a specific analysts needs.
+
+
+	o	the serious SW developer
+
+		PSIM models all three levels of the PowerPC
+		Architecture: UEA, VEA and OEA.  Further,
+		the internal design is such that PSIM can
+		be extended to support additional requirements.
+
+
+    What performance analysis measurements can PSIM perform?
+
+	Below is the output from a recent analysis run
+	(contributed by Michael Meissner):
+
+	For the following program:
+
+	long
+	simple_rand ()
+	{
+	  static unsigned long seed = 47114711;
+	  unsigned long this = seed * 1103515245 + 12345;
+	  seed = this;
+	/* cut-cut-cut - see the file RUN.psim */
+	}
+
+	Here is the current output generated with the -I switch on a P90
+	(the compiler used is the development version of GCC with a new
+	scheduler replacing the old one):
+	
+	CPU #1 executed     41,994 AND instructions.
+	CPU #1 executed    519,785 AND Immediate instructions.
+	.
+	.
+	.
+	CPU #1 executed          1 System Call instruction.
+	CPU #1 executed    207,746 XOR instructions.
+	
+	CPU #1 executed 23,740,856 cycles.
+	CPU #1 executed 10,242,780 stalls waiting for data.
+	CPU #1 executed          1 stall waiting for a function unit.
+	.
+	.
+	.
+	CPU #1 executed  3,136,229 branch functional unit instructions.
+	CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
+	CPU #1 executed    871,920 data reads.
+	CPU #1 executed    971,926 data writes.
+	CPU #1 executed        221 icache misses.
+	CPU #1 executed 16,949,396 instructions in total.
+	
+	Simulator speed was 250,731 instructions/second
+
+
+    What motivated PSIM?
+
+	As an idea, psim was first discussed seriously during mid
+	1994.  At that time its main objectives were:
+
+
+		o	good performance
+
+			Many simulators loose out by only providing
+			a binary interface to the internals.  This
+			interface eventually becomes a bottle neck
+			in the simulators performance.
+
+			It was intended that PSIM would avoid this
+			problem by giving the user access to the
+			full source code.
+
+			Further, by exploiting the power of modern
+			compilers it was hoped that PSIM would achieve
+			good performance with out having to compromise
+			its internal design.
+
+
+		o	practical portability
+
+			Rather than try to be portable to every
+			C compiler on every platform, it was decided
+			that PSIM would restrict its self to supporting
+			ANSI compilers that included the extension
+			of a long long type.
+
+			GCC is one such compiler, consequently PSIM
+			should be portable to any machine running GCC.
+
+
+		o	flexibility in its design
+
+			PSIM should allow the user to select the
+			features required and customise the build
+			accordingly.  By having the source code,
+			the compiler is able to eliminate any un
+			used features of the simulator.
+
+			After all, let the compiler do the work.
+
+
+		o	SMP
+
+			A model that allowed the simulation of
+			SMP platforms with out the large overhead
+			often encountered with such models.
+
+
+	PSIM achieves each of these objectives.
+
+
+    Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant?
+
+	No.
+
+	Among other things it does not have an Apple ROM socket.
+
+
+    Could PSIM be extended so that it models a CHRP machine?
+
+	Yes.
+
+	PSIM has been designed with the CHRP spec in mind. To model
+	a CHRP desktop the following would need to be added:
+
+		o	An apple ROM socket :-)
+
+		o	Model of each of the desktop IO devices
+
+		o	An OpenPIC device.
+
+		o	RTAS (Run Time Abstraction Services).
+
+		o	A fully populated device tree.
+
+
+    Is the source code available?
+
+	Yes.
+
+	The source code to PSIM is available under the terms of
+	the GNU Public Licence.  This allows you to distribute
+	the source code for free but with certain conditions.
+
+	See the file:
+
+		ftp://archie.au/gnu/COPYING
+
+	For details of the terms and conditions.
+
+
+    Where do I send bugs or report problems?
+
+	There is a mailing list (subscribe through majordomo@ci.com.au) at:
+
+	powerpc-psim@ci.com.au
+
+	If I get the ftp archive updated I post a note to that mailing list.
+	In addition your welcome to send bugs or problems either to me or to
+	that e-mail list.
+
+	This list currently averages zero articles a day.
+
+
+     Does PSIM have any limitations or problems?
+
+	PSIM can't run rs6000/AIX binaries - At present PSIM can only
+	simulate static executables.  Since an AIX executable is
+	never static, PSIM is unable to simulate its execution.
+
+	PSIM is still under development - consequently there are going
+	to be bugs.
+
+	See the file BUGS (included in the distribution) for any
+	other outstanding issues.
+