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