diff options
Diffstat (limited to 'sim/ppc/psim.texinfo')
| -rw-r--r-- | sim/ppc/psim.texinfo | 1105 |
1 files changed, 0 insertions, 1105 deletions
diff --git a/sim/ppc/psim.texinfo b/sim/ppc/psim.texinfo deleted file mode 100644 index f81e46099c4..00000000000 --- a/sim/ppc/psim.texinfo +++ /dev/null @@ -1,1105 +0,0 @@ -\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. - |