sim/ppc/psim.texinfo

   1 \input texinfo.tex    @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename texinfo
   4 @settitle Texinfo @value{edition}
   5 @syncodeindex vr fn
   6 @footnotestyle separate
   7 @paragraphindent 2
   8 @smallbook
   9 @comment %**end of header
  10
  11 @c Set smallbook if printing in smallbook format so the example of the
  12 @c smallbook font is actually written using smallbook; in bigbook, a kludge
  13 @c is used for TeX output.
  14 @set smallbook
  15 @c @@clear smallbook
  16
  17 @ignore
  18 @ifinfo
  19 @format
  20 START-INFO-DIR-ENTRY
  21 * Texinfo: (texinfo).           The documentation format for the GNU Project.
  22 END-INFO-DIR-ENTRY
  23 @end format
  24 @end ifinfo
  25 @end ignore
  26
  27 @set edition 2.21
  28 @set update-date 7 June 1995
  29 @set update-month June 1995
  30
  31 @c Experiment with smaller amounts of whitespace between chapters
  32 @c and sections.
  33 @tex
  34 \global\chapheadingskip = 15pt plus 4pt minus 2pt
  35 \global\secheadingskip = 12pt plus 3pt minus 2pt
  36 \global\subsecheadingskip = 9pt plus 2pt minus 2pt
  37 @end tex
  38
  39 @c Experiment with smaller amounts of whitespace between paragraphs in
  40 @c the 8.5 by 11 inch format.
  41 @ifclear smallbook
  42 @tex
  43 \global\parskip 6pt plus 1pt
  44 @end tex
  45 @end ifclear
  46
  47 @finalout
  48
  49 @c Currently undocumented command, 5 December 1993:
  50 @c
  51 @c nwnode          (Same as node, but no warnings; for `makeinfo'.)
  52
  53 @ifinfo
  54 This file documents Texinfo, a documentation system that uses a single
  55 source file to produce both on-line information and a printed manual.
  56
  57 Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc.
  58
  59 This is the second edition of the Texinfo documentation,@*
  60 and is consistent with version 2 of @file{texinfo.tex}.
  61
  62 Permission is granted to make and distribute verbatim copies of
  63 this manual provided the copyright notice and this permission notice
  64 are preserved on all copies.
  65
  66 @ignore
  67 Permission is granted to process this file through TeX and print the
  68 results, provided the printed document carries copying permission
  69 notice identical to this one except for the removal of this paragraph
  70 (this paragraph not being relevant to the printed manual).
  71
  72 @end ignore
  73 Permission is granted to copy and distribute modified versions of this
  74 manual under the conditions for verbatim copying, provided that the entire
  75 resulting derived work is distributed under the terms of a permission
  76 notice identical to this one.
  77
  78 Permission is granted to copy and distribute translations of this manual
  79 into another language, under the above conditions for modified versions,
  80 except that this permission notice may be stated in a translation approved
  81 by the Free Software Foundation.
  82 @end ifinfo
  83
  84 @setchapternewpage odd
  85
  86 @shorttitlepage Texinfo
  87
  88 @titlepage
  89 @c use the new format for titles
  90 @title Texinfo
  91 @subtitle The GNU Documentation Format
  92 @subtitle Edition @value{edition}, for Texinfo Version Three
  93 @subtitle @value{update-month}
  94
  95 @author by Robert J. Chassell and Richard M. Stallman
  96
  97 @comment   Include the Distribution inside the titlepage so
  98 @c that headings are turned off.
  99
 100 @page
 101 @vskip 0pt plus 1filll
 102 Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc.
 103
 104 @sp 2
 105 This is the second edition of the Texinfo documentation,@*
 106 and is consistent with version 2 of @file{texinfo.tex}.
 107 @sp 2
 108
 109 Published by the Free Software Foundation @*
 110 59 Temple Place Suite 330, @*
 111 Boston, MA 02111-1307 USA @*
 112 Printed copies are available for $15 each.@*
 113 ISBN 1-882114-63-9
 114 @c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995
 115
 116 Permission is granted to make and distribute verbatim copies of
 117 this manual provided the copyright notice and this permission notice
 118 are preserved on all copies.
 119
 120 Permission is granted to copy and distribute modified versions of this
 121 manual under the conditions for verbatim copying, provided that the entire
 122 resulting derived work is distributed under the terms of a permission
 123 notice identical to this one.
 124
 125 Permission is granted to copy and distribute translations of this manual
 126 into another language, under the above conditions for modified versions,
 127 except that this permission notice may be stated in a translation approved
 128 by the Free Software Foundation.
 129 @sp 2
 130 Cover art by Etienne Suvasa.
 131 @end titlepage
 132
 133 @ifinfo
 134 @node Top, Copying, (dir), (dir)
 135 @top Texinfo
 136
 137 Texinfo is a documentation system that uses a single source file to
 138 produce both on-line information and printed output.@refill
 139
 140 The first part of this master menu lists the major nodes in this Info
 141 document, including the @@-command and concept indices.  The rest of
 142 the menu lists all the lower level nodes in the document.@refill
 143
 144 This is Edition @value{edition} of the Texinfo documentation,
 145 @w{@value{update-date},} for Texinfo Version Three.
 146 @end ifinfo
 147
 148 @c Here is a spare copy of the chapter menu entry descriptions,
 149 @c in case they are accidently deleted
 150 @ignore
 151 Your rights.
 152 Texinfo in brief.
 153 How to use Texinfo mode.
 154 What is at the beginning of a Texinfo file?
 155 What is at the end of a Texinfo file?
 156 How to create chapters, sections, subsections,
 157   appendices, and other parts.
 158 How to provide structure for a document.
 159 How to write nodes.
 160 How to write menus.
 161 How to write cross references.
 162 How to mark words and phrases as code,
 163   keyboard input, meta-syntactic
 164   variables, and the like.
 165 How to write quotations, examples, etc.
 166 How to write lists and tables.
 167 How to create indices.
 168 How to insert @@-signs, braces, etc.
 169 How to indicate results of evaluation,
 170   expansion of macros, errors, etc.
 171 How to force and prevent line and page breaks.
 172 How to describe functions and the like in a uniform manner.
 173 How to write footnotes.
 174 How to specify text for either @TeX{} or Info.
 175 How to print hardcopy.
 176 How to create an Info file.
 177 How to install an Info file
 178 A list of all the Texinfo @@-commands.
 179 Hints on how to write a Texinfo document.
 180 A sample Texinfo file to look at.
 181 Tell readers they have the right to copy
 182   and distribute.
 183 How to incorporate other Texinfo files.
 184 How to write page headings and footings.
 185 How to find formatting mistakes.
 186 All about paragraph refilling.
 187 A description of @@-Command syntax.
 188 Texinfo second edition features.
 189 A menu containing commands and variables.
 190 A menu covering many topics.
 191 @end ignore
 192
 193 @menu
 194 * Copying::                     Your rights.
 195 * Overview::                    Texinfo in brief.
 196 * Texinfo Mode::                How to use Texinfo mode.
 197 * Beginning a File::            What is at the beginning of a Texinfo file?
 198 * Ending a File::               What is at the end of a Texinfo file?
 199 * Structuring::                 How to create chapters, sections, subsections,
 200                                   appendices, and other parts.
 201 * Nodes::                       How to write nodes.
 202 * Menus::                       How to write menus.
 203 * Cross References::            How to write cross references.
 204 * Marking Text::                How to mark words and phrases as code,
 205                                   keyboard input, meta-syntactic
 206                                   variables, and the like.
 207 * Quotations and Examples::     How to write quotations, examples, etc.
 208 * Lists and Tables::            How to write lists and tables.
 209 * Indices::                     How to create indices.
 210 * Insertions::                  How to insert @@-signs, braces, etc.
 211 * Glyphs::                      How to indicate results of evaluation,
 212                                   expansion of macros, errors, etc.
 213 * Breaks::                      How to force and prevent line and page breaks.
 214 * Definition Commands::         How to describe functions and the like
 215                                   in a uniform manner.
 216 * Footnotes::                   How to write footnotes.
 217 * Conditionals::                How to specify text for either @TeX{} or Info.
 218 * Format/Print Hardcopy::       How to convert a Texinfo file to a file
 219                                   for printing and how to print that file.
 220 * Create an Info File::         Convert a Texinfo file into an Info file.
 221 * Install an Info File::        Make an Info file accessible to users.
 222 * Command List::                All the Texinfo @@-commands.
 223 * Tips::                        Hints on how to write a Texinfo document.
 224 * Sample Texinfo File::         A sample Texinfo file to look at.
 225 * Sample Permissions::          Tell readers they have the right to copy
 226                                   and distribute.
 227 * Include Files::               How to incorporate other Texinfo files.
 228 * Headings::                    How to write page headings and footings.
 229 * Catching Mistakes::           How to find formatting mistakes.
 230 * Refilling Paragraphs::        All about paragraph refilling.
 231 * Command Syntax::              A description of @@-Command syntax.
 232 * Obtaining TeX::               How to Obtain @TeX{}.
 233 * New Features::                Texinfo second edition features.
 234 * Command and Variable Index::  A menu containing commands and variables.
 235 * Concept Index::               A menu covering many topics.
 236
 237  --- The Detailed Node Listing ---
 238
 239 Overview of Texinfo
 240
 241 * Using Texinfo::               Create a conventional printed book
 242                                   or an Info file.
 243 * Info Files::                  What is an Info file?
 244 * Printed Books::               Characteristics of a printed book or manual.
 245 * Formatting Commands::         @@-commands are used for formatting.
 246 * Conventions::                 General rules for writing a Texinfo file.
 247 * Comments::                    How to write comments and mark regions that
 248                                   the formatting commands will ignore.
 249 * Minimum::                     What a Texinfo file must have.
 250 * Six Parts::                   Usually, a Texinfo file has six parts.
 251 * Short Sample::                A short sample Texinfo file.
 252 * Acknowledgements::
 253
 254 Using Texinfo Mode
 255
 256 * Texinfo Mode Overview::       How Texinfo mode can help you.
 257 * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
 258                                   purpose editing features.
 259 * Inserting::                   How to insert frequently used @@-commands.
 260 * Showing the Structure::       How to show the structure of a file.
 261 * Updating Nodes and Menus::    How to update or create new nodes and menus.
 262 * Info Formatting::             How to format for Info.
 263 * Printing::                    How to format and print part or all of a file.
 264 * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
 265
 266 Updating Nodes and Menus
 267
 268 * Updating Commands::           Five major updating commands.
 269 * Updating Requirements::       How to structure a Texinfo file for
 270                                   using the updating command.
 271 * Other Updating Commands::     How to indent descriptions, insert
 272                                   missing nodes lines, and update
 273                                   nodes in sequence.
 274
 275 Beginning a Texinfo File
 276
 277 * Four Parts::                  Four parts begin a Texinfo file.
 278 * Sample Beginning::            Here is a sample beginning for a Texinfo file.
 279 * Header::                      The very beginning of a Texinfo file.
 280 * Info Summary and Permissions::  Summary and copying permissions for Info.
 281 * Titlepage & Copyright Page::  Creating the title and copyright pages.
 282 * The Top Node::                Creating the `Top' node and master menu.
 283 * Software Copying Permissions::  Ensure that you and others continue to
 284                                   have the right to use and share software.
 285
 286 The Texinfo File Header
 287
 288 * First Line::                  The first line of a Texinfo file.
 289 * Start of Header::             Formatting a region requires this.
 290 * setfilename::                 Tell Info the name of the Info file.
 291 * settitle::                    Create a title for the printed work.
 292 * setchapternewpage::           Start chapters on right-hand pages.
 293 * paragraphindent::             An option to specify paragraph indentation.
 294 * End of Header::               Formatting a region requires this.
 295
 296 The Title and Copyright Pages
 297
 298 * titlepage::                   Create a title for the printed document.
 299 * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
 300                                   and @code{@@sp} commands.
 301 * title subtitle author::       The @code{@@title}, @code{@@subtitle},
 302                                   and @code{@@author} commands.
 303 * Copyright & Permissions::     How to write the copyright notice and
 304                                   include copying permissions.
 305 * end titlepage::               Turn on page headings after the title and
 306                                   copyright pages.
 307 * headings on off::             An option for turning headings on and off
 308                                   and double or single sided printing.
 309
 310 The `Top' Node and Master Menu
 311
 312 * Title of Top Node::           Sketch what the file is about.
 313 * Master Menu Parts::           A master menu has three or more parts.
 314
 315 Ending a Texinfo File
 316
 317 * Printing Indices & Menus::    How to print an index in hardcopy and
 318                                   generate index menus in Info.
 319 * Contents::                    How to create a table of contents.
 320 * File End::                    How to mark the end of a file.
 321
 322 Chapter Structuring
 323
 324 * Tree Structuring::            A manual is like an upside down tree @dots{}
 325 * Structuring Command Types::   How to divide a manual into parts.
 326 * makeinfo top::                The @code{@@top} command, part of the `Top' node.
 327 * chapter::
 328 * unnumbered & appendix::
 329 * majorheading & chapheading::
 330 * section::
 331 * unnumberedsec appendixsec heading::
 332 * subsection::
 333 * unnumberedsubsec appendixsubsec subheading::
 334 * subsubsection::               Commands for the lowest level sections.
 335 * Raise/lower sections::        How to change commands' hierarchical level.
 336
 337 Nodes
 338
 339 * Two Paths::                   Different commands to structure
 340                                   Info output and printed output.
 341 * Node Menu Illustration::      A diagram, and sample nodes and menus.
 342 * node::                        How to write a node, in detail.
 343 * makeinfo Pointer Creation::   How to create node pointers with @code{makeinfo}.
 344
 345 The @code{@@node} Command
 346
 347 * Node Names::                  How to choose node and pointer names.
 348 * Writing a Node::              How to write an @code{@@node} line.
 349 * Node Line Tips::              Keep names short.
 350 * Node Line Requirements::      Keep names unique, without @@-commands.
 351 * First Node::                  How to write a `Top' node.
 352 * makeinfo top command::        How to use the @code{@@top} command.
 353 * Top Node Summary::            Write a brief description for readers.
 354
 355 Menus
 356
 357 * Menu Location::               Put a menu in a short node.
 358 * Writing a Menu::              What is a menu?
 359 * Menu Parts::                  A menu entry has three parts.
 360 * Less Cluttered Menu Entry::   Two part menu entry.
 361 * Menu Example::                Two and three part menu entries.
 362 * Other Info Files::            How to refer to a different Info file.
 363
 364 Cross References
 365
 366 * References::                  What cross references are for.
 367 * Cross Reference Commands::    A summary of the different commands.
 368 * Cross Reference Parts::       A cross reference has several parts.
 369 * xref::                        Begin a reference with `See' @dots{}
 370 * Top Node Naming::             How to refer to the beginning of another file.
 371 * ref::                         A reference for the last part of a sentence.
 372 * pxref::                       How to write a parenthetical cross reference.
 373 * inforef::                     How to refer to an Info-only file.
 374
 375 @code{@@xref}
 376
 377 * Reference Syntax::            What a reference looks like and requires.
 378 * One Argument::                @code{@@xref} with one argument.
 379 * Two Arguments::               @code{@@xref} with two arguments.
 380 * Three Arguments::             @code{@@xref} with three arguments.
 381 * Four and Five Arguments::     @code{@@xref} with four and five arguments.
 382
 383 Marking Words and Phrases
 384
 385 * Indicating::                  How to indicate definitions, files, etc.
 386 * Emphasis::                    How to emphasize text.
 387
 388 Indicating Definitions, Commands, etc.
 389
 390 * Useful Highlighting::         Highlighting provides useful information.
 391 * code::                        How to indicate code.
 392 * kbd::                         How to show keyboard input.
 393 * key::                         How to specify keys.
 394 * samp::                        How to show a literal sequence of characters.
 395 * var::                         How to indicate a metasyntactic variable.
 396 * file::                        How to indicate the name of a file.
 397 * dfn::                         How to specify a definition.
 398 * cite::                        How to refer to a book that is not in Info.
 399
 400 Emphasizing Text
 401
 402 * emph & strong::               How to emphasize text in Texinfo.
 403 * Smallcaps::                   How to use the small caps font.
 404 * Fonts::                       Various font commands for printed output.
 405 * Customized Highlighting::     How to define highlighting commands.
 406
 407 Quotations and Examples
 408
 409 * Block Enclosing Commands::    Use different constructs for
 410                                   different purposes.
 411 * quotation::                   How to write a quotation.
 412 * example::                     How to write an example in a fixed-width font.
 413 * noindent::                    How to prevent paragraph indentation.
 414 * Lisp Example::                How to illustrate Lisp code.
 415 * smallexample & smalllisp::    Forms for the @code{@@smallbook} option.
 416 * display::                     How to write an example in the current font.
 417 * format::                      How to write an example that does not narrow
 418                                   the margins.
 419 * exdent::                      How to undo the indentation of a line.
 420 * flushleft & flushright::      How to push text flushleft or flushright.
 421 * cartouche::                   How to draw cartouches around examples.
 422
 423 Making Lists and Tables
 424
 425 * Introducing Lists::           Texinfo formats lists for you.
 426 * itemize::                     How to construct a simple list.
 427 * enumerate::                   How to construct a numbered list.
 428 * Two-column Tables::           How to construct a two-column table.
 429
 430 Making a Two-column Table
 431
 432 * table::                       How to construct a two-column table.
 433 * ftable vtable::               How to construct a two-column table
 434                                   with automatic indexing.
 435 * itemx::                       How to put more entries in the first column.
 436
 437 Creating Indices
 438
 439 * Index Entries::               Choose different words for index entries.
 440 * Predefined Indices::          Use different indices for different kinds
 441                                   of entry.
 442 * Indexing Commands::           How to make an index entry.
 443 * Combining Indices::           How to combine indices.
 444 * New Indices::                 How to define your own indices.
 445
 446 Combining Indices
 447
 448 * syncodeindex::                How to merge two indices, using @code{@@code}
 449                                   font for the merged-from index.
 450 * synindex::                    How to merge two indices, using the
 451                                   default font of the merged-to index.
 452
 453 Special Insertions
 454
 455 * Braces Atsigns Periods::      How to insert braces, @samp{@@} and periods.
 456 * dmn::                         How to format a dimension.
 457 * Dots Bullets::                How to insert dots and bullets.
 458 * TeX and copyright::           How to insert the @TeX{} logo
 459                                   and the copyright symbol.
 460 * minus::                       How to insert a minus sign.
 461 * math::                        How to format a mathematical expression.
 462
 463 Inserting @samp{@@}, Braces, and Periods
 464
 465 * Inserting An Atsign::
 466 * Inserting Braces::            How to insert @samp{@{} and @samp{@}}
 467 * Controlling Spacing::         How to insert the right amount of space
 468                                   after punctuation within a sentence.
 469
 470 Inserting Ellipsis, Dots, and Bullets
 471
 472 * dots::                        How to insert dots @dots{}
 473 * bullet::                      How to insert a bullet.
 474
 475 Inserting @TeX{} and the Copyright Symbol
 476
 477 * tex::                         How to insert the @TeX{} logo.
 478 * copyright symbol::            How to use @code{@@copyright}@{@}.
 479
 480 Glyphs for Examples
 481
 482 * Glyphs Summary::
 483 * result::                      How to show the result of expression.
 484 * expansion::                   How to indicate an expansion.
 485 * Print Glyph::                 How to indicate printed output.
 486 * Error Glyph::                 How to indicate an error message.
 487 * Equivalence::                 How to indicate equivalence.
 488 * Point Glyph::                 How to indicate the location of point.
 489
 490 Making and Preventing Breaks
 491
 492 * Break Commands::              Cause and prevent splits.
 493 * Line Breaks::                 How to force a single line to use two lines.
 494 * w::                           How to prevent unwanted line breaks.
 495 * sp::                          How to insert blank lines.
 496 * page::                        How to force the start of a new page.
 497 * group::                       How to prevent unwanted page breaks.
 498 * need::                        Another way to prevent unwanted page breaks.
 499
 500 Definition Commands
 501
 502 * Def Cmd Template::            How to structure a description using a
 503                                   definition command.
 504 * Optional Arguments::          How to handle optional and repeated arguments.
 505 * deffnx::                      How to group two or more `first' lines.
 506 * Def Cmds in Detail::          All the definition commands.
 507 * Def Cmd Conventions::         Conventions for writing definitions.
 508 * Sample Function Definition::
 509
 510 The Definition Commands
 511
 512 * Functions Commands::          Commands for functions and similar entities.
 513 * Variables Commands::          Commands for variables and similar entities.
 514 * Typed Functions::             Commands for functions in typed languages.
 515 * Typed Variables::             Commands for variables in typed languages.
 516 * Abstract Objects::            Commands for object-oriented programming.
 517 * Data Types::                  The definition command for data types.
 518
 519 Footnotes
 520
 521 * Footnote Commands::           How to write a footnote in Texinfo.
 522 * Footnote Styles::             Controlling how footnotes appear in Info.
 523
 524 Conditionally Visible Text
 525
 526 * Conditional Commands::        How to specify text for Info or @TeX{}.
 527 * Using Ordinary TeX Commands::  You can use any and all @TeX{} commands.
 528 * set clear value::             How to designate which text to format (for
 529                                   both Info and @TeX{}); and how to set a
 530                                   flag to a string that you can insert.
 531
 532 @code{@@set}, @code{@@clear}, and @code{@@value}
 533
 534 * ifset ifclear::               Format a region if a flag is set.
 535 * value::                       Replace a flag with a string.
 536 * value Example::               An easy way to update edition information.
 537
 538 Format and Print Hardcopy
 539
 540 * Use TeX::                     Use @TeX{} to format for hardcopy.
 541 * Format with tex/texindex::    How to format in a shell.
 542 * Format with texi2dvi::        A simpler way to use the shell.
 543 * Print with lpr::              How to print.
 544 * Within Emacs::                How to format and print from an Emacs shell.
 545 * Texinfo Mode Printing::       How to format and print in Texinfo mode.
 546 * Compile-Command::             How to print using Emacs's compile command.
 547 * Requirements Summary::        @TeX{} formatting requirements summary.
 548 * Preparing for TeX::           What you need to do to use @TeX{}.
 549 * Overfull hboxes::             What are and what to do with overfull hboxes.
 550 * smallbook::                   How to print small format books and manuals.
 551 * A4 Paper::                    How to print on European A4 paper.
 552 * Cropmarks and Magnification::  How to print marks to indicate the size
 553                                 of pages and how to print scaled up output.
 554
 555 Creating an Info File
 556
 557 * makeinfo advantages::         @code{makeinfo} provides better error checking.
 558 * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
 559 * makeinfo options::            Specify fill-column and other options.
 560 * Pointer Validation::          How to check that pointers point somewhere.
 561 * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
 562 * texinfo-format commands::     Two Info formatting commands written
 563                                   in Emacs Lisp are an alternative
 564                                   to @code{makeinfo}.
 565 * Batch Formatting::            How to format for Info in Emacs Batch mode.
 566 * Tag and Split Files::         How tagged and split files help Info
 567                                   to run better.
 568
 569 Installing an Info File
 570
 571 * Directory file::              The top level menu for all Info files.
 572 * New Info File::               Listing a new info file.
 573 * Other Info Directories::      How to specify Info files that are
 574                                   located in other directories.
 575
 576 Sample Permissions
 577
 578 * Inserting Permissions::       How to put permissions in your document.
 579 * ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
 580 * Titlepage Permissions::       Sample Titlepage copying permissions.
 581
 582 Include Files
 583
 584 * Using Include Files::         How to use the @code{@@include} command.
 585 * texinfo-multiple-files-update::  How to create and update nodes and
 586                                   menus when using included files.
 587 * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
 588 * Sample Include File::         A sample outer file with included files
 589                                   within it; and a sample included file.
 590 * Include Files Evolution::     How use of the @code{@@include} command
 591                                   has changed over time.
 592
 593 Page Headings
 594
 595 * Headings Introduced::         Conventions for using page headings.
 596 * Heading Format::              Standard page heading formats.
 597 * Heading Choice::              How to specify the type of page heading.
 598 * Custom Headings::             How to create your own headings and footings.
 599
 600 Formatting Mistakes
 601
 602 * makeinfo preferred::          @code{makeinfo} finds errors.
 603 * Debugging with Info::         How to catch errors with Info formatting.
 604 * Debugging with TeX::          How to catch errors with @TeX{} formatting.
 605 * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
 606 * Using occur::                 How to list all lines containing a pattern.
 607 * Running Info-Validate::       How to find badly referenced nodes.
 608
 609 Finding Badly Referenced Nodes
 610
 611 * Using Info-validate::         How to run @code{Info-validate}.
 612 * Unsplit::                     How to create an unsplit file.
 613 * Tagifying::                   How to tagify a file.
 614 * Splitting::                   How to split a file manually.
 615
 616 Second Edition Features
 617
 618 * New Texinfo Mode Commands::   The updating commands are especially useful.
 619 * New Commands::                Many newly described @@-commands.
 620 @end menu
 621
 622 @node Copying, Overview, Top, Top
 623 @comment  node-name, next, previous,  up
 624 @unnumbered Texinfo Copying Conditions
 625 @cindex Copying conditions
 626 @cindex Conditions for copying Texinfo
 627
 628 The programs currently being distributed that relate to Texinfo include
 629 portions of GNU Emacs, plus other separate programs (including
 630 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
 631 These programs are @dfn{free}; this means that everyone is free to use
 632 them and free to redistribute them on a free basis.  The Texinfo-related
 633 programs are not in the public domain; they are copyrighted and there
 634 are restrictions on their distribution, but these restrictions are
 635 designed to permit everything that a good cooperating citizen would want
 636 to do.  What is not allowed is to try to prevent others from further
 637 sharing any version of these programs that they might get from
 638 you.@refill
 639
 640   Specifically, we want to make sure that you have the right to give
 641 away copies of the programs that relate to Texinfo, that you receive
 642 source code or else can get it if you want it, that you can change these
 643 programs or use pieces of them in new free programs, and that you know
 644 you can do these things.@refill
 645
 646   To make sure that everyone has such rights, we have to forbid you to
 647 deprive anyone else of these rights.  For example, if you distribute
 648 copies of the Texinfo related programs, you must give the recipients all
 649 the rights that you have.  You must make sure that they, too, receive or
 650 can get the source code.  And you must tell them their rights.@refill
 651
 652   Also, for our own protection, we must make certain that everyone finds
 653 out that there is no warranty for the programs that relate to Texinfo.
 654 If these programs are modified by someone else and passed on, we want
 655 their recipients to know that what they have is not what we distributed,
 656 so that any problems introduced by others will not reflect on our
 657 reputation.@refill
 658
 659   The precise conditions of the licenses for the programs currently
 660 being distributed that relate to Texinfo are found in the General Public
 661 Licenses that accompany them.@refill
 662
 663 @node Overview, Texinfo Mode, Copying, Top
 664 @comment  node-name,  next,  previous,  up
 665 @chapter Overview of Texinfo
 666 @cindex Overview of Texinfo
 667 @cindex Texinfo overview
 668
 669 @dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is
 670 pronounced like ``speck'', not ``hex''.  This odd pronunciation is
 671 derived from, but is not the same as, the pronunciation of @TeX{}.  In
 672 the word @TeX{}, the @samp{X} is actually the Greek letter ``chi''
 673 rather than the English letter ``ex''.  Pronounce @TeX{} as if the
 674 @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
 675 as if the @samp{x} were a `k'.  Spell ``Texinfo'' with a capital ``T''
 676 and write the other letters in lower case.}
 677 is a documentation system that uses a single source file to produce both
 678 on-line information and printed output.  This means that instead of
 679 writing two different documents, one for the on-line help or other on-line
 680 information and the other for a typeset manual or other printed work, you
 681 need write only one document.  When the work is revised, you need revise
 682 only one document.  (You can read the on-line information, known as an
 683 @dfn{Info file}, with an Info documentation-reading program.)@refill
 684
 685 @menu
 686 * Using Texinfo::               Create a conventional printed book
 687                                   or an Info file.
 688 * Info Files::                  What is an Info file?
 689 * Printed Books::               Characteristics of a printed book or manual.
 690 * Formatting Commands::         @@-commands are used for formatting.
 691 * Conventions::                 General rules for writing a Texinfo file.
 692 * Comments::                    How to write comments and mark regions that
 693                                   the formatting commands will ignore.
 694 * Minimum::                     What a Texinfo file must have.
 695 * Six Parts::                   Usually, a Texinfo file has six parts.
 696 * Short Sample::                A short sample Texinfo file.
 697 * Acknowledgements::
 698 @end menu
 699
 700 @c ************************************************************************
 701
 702
 703
 704 \input texinfo  @c -*-texinfo-*-
 705 @c %**start of header
 706 @setfilename psim.info
 707 @settitle PSIM
 708 @setchapternewpage odd
 709 @c %**end of header
 710
 711
 712
 713 @ifinfo
 714 This file documents the program PSIM.
 715
 716 Copyright (C) 1994-1996, Andrew Cagney.
 717
 718 Permission is granted to make and distribute verbatim copies of
 719 this manual provided the copyright notice and this permission notice
 720 are preserved on all copies.
 721
 722 @ignore
 723 Permission is granted to process this file through Tex and print the
 724 results, provided the printed document carries copying permission
 725 notice identical to this one except for the removal of this paragraph
 726 (this paragraph not being relevant to the printed manual).
 727
 728 @end ignore
 729 Permission is granted to copy and distribute modified versions of this
 730 manual under the conditions for verbatim copying, subject to the terms
 731 of the GNU General Public License, which includes the provision that the
 732 entire resulting derived work is distributed under the terms of a
 733 permission notice identical to this one.
 734
 735 Permission is granted to copy and distribute translations of this manual
 736 into another language, under the above conditions for modified versions.
 737 @end ifinfo
 738
 739
 740 @titlepage
 741 @title PSIM
 742 @subtitle Model of the PowerPC Environments
 743 @author Andrew Cagney
 744
 745 @page
 746 @vskip Opt plus ifill
 747 Copyright @copyright{} 1994-1996, Andrew Cagney
 748
 749 This is the first edition of the PSIM manual and is consistent with PSIM
 750 version 1.0.
 751
 752 Permission is granted to make and distribute verbatim copies of
 753 this manual provided the copyright notice and this permission notice
 754 are preserved on all copies.
 755
 756 Permission is granted to copy and distribute modified versions of this
 757 manual under the conditions for verbatim copying, subject to the terms
 758 of the GNU General Public License, which includes the provision that the
 759 entire resulting derived work is distributed under the terms of a
 760 permission notice identical to this one.
 761
 762 Permission is granted to copy and distribute translations of this manual
 763 into another language, under the above conditions for modified versions.
 764 @end titlepage
 765
 766
 767
 768 @menu
 769
 770 * Copying::             Your rights and freedoms.
 771 * First Chappeter::     Getting started ....
 772 * Second Chapter::      Getting finished ....
 773
 774
 775 @end menu
 776
 777
 778 PSIM is a program written in extended ANSI-C that implements an
 779 instruction level simulation of the PowerPC environment.  It is freely
 780 available in source code form under the terms of the GNU General
 781 Public License (version 2 or later).
 782
 783 The PowerPC Architecture is described as having three levels of
 784 compliance:
 785
 786         UEA - User Environment Architecture
 787         VEA - Virtual Environment Architecture
 788         OEA - Operating Environment Architecture
 789
 790 PSIM both implements all three levels of the PowerPC and includes (for
 791 each level) a corresponding simulated run-time environment.
 792
 793 In addition, PSIM, to the execution unit level, models the performance
 794 of most of the current PowerPC implementations (contributed by Michael
 795 Meissner).  This detailed performance monitoring (unlike many other
 796 simulators) resulting in only a relatively marginal reduction in the
 797 simulators performance.
 798
 799
 800 A description of how to build PSIM is contained in the file:
 801
 802                 ftp://ftp.ci.com.au/pub/psim/INSTALL
 803         or      ftp://cambridge.cygnus.com/pub/psim/INSTALL
 804
 805 while an overview of how to use PSIM is in:
 806
 807         ftp://ftp.ci.com.au/pub/psim/RUN
 808 or      ftp://cambridge.cygnus.com/pub/psim/RUN
 809
 810 This file is found in:
 811
 812         ftp://ftp.ci.com.au/pub/psim/README
 813 or      ftp://cambridge.cygnus.com/pub/psim/README
 814
 815
 816 Thanks goes firstly to:
 817
 818         Corinthian Engineering Pty Ltd
 819         Cygnus Support
 820         Highland Logic Pty Ltd
 821
 822 who provided the resources needed for making this software available
 823 on the Internet.
 824
 825 More importantly I'd like to thank the following individuals who each
 826 contributed in their own unique way:
 827
 828         Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam,
 829         Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn,
 830         Richard Stallman, Mitchele Walker
 831
 832
 833                                 Andrew Cagney
 834                                 Feb, 1995
 835
 836
 837     ----------------------------------------------------------------------
 838
 839
 840     What features does PSIM include?
 841
 842         Monitoring and modeling
 843
 844                 PSIM includes (thanks to Michael Meissner)
 845                 a detailed model of most of the PowerPC
 846                 implementations to the functional unit level.
 847
 848
 849         SMP
 850
 851                 The PowerPC ISA defines SMP synchronizing instructions.
 852                 This simulator implements a limited, but functional,
 853                 subset of the PowerPC synchronization instructions
 854                 behaviour.  Programs that restrict their synchronization
 855                 primitives to those that work with this functional
 856                 sub-set (eg P() and V()) are able to run on the SMP
 857                 version of PSIM.
 858
 859                 People intending to use this system should study
 860                 the code implementing the lwarx instruction.
 861
 862         ENDIAN SUPPORT
 863
 864                 PSIM implements the PowerPC's big and little (xor
 865                 endian) modes and correctly simulates code that
 866                 switches between these two modes.
 867
 868                 In addition, psim can model a true little-endian
 869                 machine.
 870
 871         ISA (Instruction Set Architecture) models
 872
 873                 PSIM includes a model of the UEA, VEA and OEA.  This
 874                 includes the time base registers (VEA) and HTAB
 875                 and BATS (OEA).
 876
 877                 In addition, a preliminary model of the 64 bit
 878                 PowerPC architecture is implemented.
 879
 880         IO Hardware
 881
 882                 PSIM's internals are based around the concept
 883                 of a Device Tree.  This tree intentionally
 884                 resembles that of the Device Tree found in
 885                 OpenBoot firmware.  PSIM is flexible enough
 886                 to allow the user to fully configure this device
 887                 tree (and consequently the hardware model) at
 888                 run time.
 889
 890         Run-time environments:
 891
 892                 PSIM's UEA model includes emulation for BSD
 893                 based UNIX system calls.
 894
 895                 PSIM's OEA model includes emulation of either:
 896
 897                         o       OpenBoot client interface
 898
 899                         o       MOTO's BUG interface.
 900
 901
 902         Floating point
 903
 904                 Preliminary support for floating point is included.
 905
 906
 907     Who would be interested in PSIM?
 908
 909         o       the curious
 910
 911                 Using psim, gdb, gcc and binutils the curious
 912                 user can construct an environment that allows
 913                 them to play with PowerPC Environment without
 914                 the need for real hardware.
 915
 916
 917         o       the analyst
 918
 919                 PSIM includes many (contributed) monitoring
 920                 features which (unlike many other simulators)
 921                 do not come with a great penalty in performance.
 922
 923                 Thus the performance analyst is able to use
 924                 this simulator to analyse the performance of
 925                 the system under test.
 926
 927                 If PSIM doesn't monitor a components of interest,
 928                 the source code is freely available, and hence
 929                 there is no hinderance to changing things
 930                 to meet a specific analysts needs.
 931
 932
 933         o       the serious SW developer
 934
 935                 PSIM models all three levels of the PowerPC
 936                 Architecture: UEA, VEA and OEA.  Further,
 937                 the internal design is such that PSIM can
 938                 be extended to support additional requirements.
 939
 940
 941     What performance analysis measurements can PSIM perform?
 942
 943         Below is the output from a recent analysis run
 944         (contributed by Michael Meissner):
 945
 946         For the following program:
 947
 948         long
 949         simple_rand ()
 950         {
 951           static unsigned long seed = 47114711;
 952           unsigned long this = seed * 1103515245 + 12345;
 953           seed = this;
 954         /* cut-cut-cut - see the file RUN.psim */
 955         }
 956
 957         Here is the current output generated with the -I switch on a P90
 958         (the compiler used is the development version of GCC with a new
 959         scheduler replacing the old one):
 960
 961         CPU #1 executed     41,994 AND instructions.
 962         CPU #1 executed    519,785 AND Immediate instructions.
 963         .
 964         .
 965         .
 966         CPU #1 executed          1 System Call instruction.
 967         CPU #1 executed    207,746 XOR instructions.
 968
 969         CPU #1 executed 23,740,856 cycles.
 970         CPU #1 executed 10,242,780 stalls waiting for data.
 971         CPU #1 executed          1 stall waiting for a function unit.
 972         .
 973         .
 974         .
 975         CPU #1 executed  3,136,229 branch functional unit instructions.
 976         CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
 977         CPU #1 executed    871,920 data reads.
 978         CPU #1 executed    971,926 data writes.
 979         CPU #1 executed        221 icache misses.
 980         CPU #1 executed 16,949,396 instructions in total.
 981
 982         Simulator speed was 250,731 instructions/second
 983
 984
 985     What motivated PSIM?
 986
 987         As an idea, psim was first discussed seriously during mid
 988         1994.  At that time its main objectives were:
 989
 990
 991                 o       good performance
 992
 993                         Many simulators loose out by only providing
 994                         a binary interface to the internals.  This
 995                         interface eventually becomes a bottle neck
 996                         in the simulators performance.
 997
 998                         It was intended that PSIM would avoid this
 999                         problem by giving the user access to the
1000                         full source code.
1001
1002                         Further, by exploiting the power of modern
1003                         compilers it was hoped that PSIM would achieve
1004                         good performance with out having to compromise
1005                         its internal design.
1006
1007
1008                 o       practical portability
1009
1010                         Rather than try to be portable to every
1011                         C compiler on every platform, it was decided
1012                         that PSIM would restrict its self to supporting
1013                         ANSI compilers that included the extension
1014                         of a long long type.
1015
1016                         GCC is one such compiler, consequently PSIM
1017                         should be portable to any machine running GCC.
1018
1019
1020                 o       flexibility in its design
1021
1022                         PSIM should allow the user to select the
1023                         features required and customise the build
1024                         accordingly.  By having the source code,
1025                         the compiler is able to eliminate any un
1026                         used features of the simulator.
1027
1028                         After all, let the compiler do the work.
1029
1030
1031                 o       SMP
1032
1033                         A model that allowed the simulation of
1034                         SMP platforms with out the large overhead
1035                         often encountered with such models.
1036
1037
1038         PSIM achieves each of these objectives.
1039
1040
1041     Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant?
1042
1043         No.
1044
1045         Among other things it does not have an Apple ROM socket.
1046
1047
1048     Could PSIM be extended so that it models a CHRP machine?
1049
1050         Yes.
1051
1052         PSIM has been designed with the CHRP spec in mind. To model
1053         a CHRP desktop the following would need to be added:
1054
1055                 o       An apple ROM socket :-)
1056
1057                 o       Model of each of the desktop IO devices
1058
1059                 o       An OpenPIC device.
1060
1061                 o       RTAS (Run Time Abstraction Services).
1062
1063                 o       A fully populated device tree.
1064
1065
1066     Is the source code available?
1067
1068         Yes.
1069
1070         The source code to PSIM is available under the terms of
1071         the GNU Public Licence.  This allows you to distribute
1072         the source code for free but with certain conditions.
1073
1074         See the file:
1075
1076                 ftp://archie.au/gnu/COPYING
1077
1078         For details of the terms and conditions.
1079
1080
1081     Where do I send bugs or report problems?
1082
1083         There is a mailing list (subscribe through majordomo@ci.com.au) at:
1084
1085         powerpc-psim@ci.com.au
1086
1087         If I get the ftp archive updated I post a note to that mailing list.
1088         In addition your welcome to send bugs or problems either to me or to
1089         that e-mail list.
1090
1091         This list currently averages zero articles a day.
1092
1093
1094      Does PSIM have any limitations or problems?
1095
1096         PSIM can't run rs6000/AIX binaries - At present PSIM can only
1097         simulate static executables.  Since an AIX executable is
1098         never static, PSIM is unable to simulate its execution.
1099
1100         PSIM is still under development - consequently there are going
1101         to be bugs.
1102
1103         See the file BUGS (included in the distribution) for any
1104         other outstanding issues.
1105