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