\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-2016 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, 2010, 2011
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 3 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.