\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-2019 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.