Subversion Repositories openrisc

\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, 2010

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

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