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 20START-INFO-DIR-ENTRY 21* Texinfo: (texinfo). The documentation format for the GNU Project. 22END-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 54This file documents Texinfo, a documentation system that uses a single 55source file to produce both on-line information and a printed manual. 56 57Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 2010, 2011 58Free Software Foundation, Inc. 59 60This is the second edition of the Texinfo documentation,@* 61and is consistent with version 2 of @file{texinfo.tex}. 62 63Permission is granted to make and distribute verbatim copies of 64this manual provided the copyright notice and this permission notice 65are preserved on all copies. 66 67@ignore 68Permission is granted to process this file through TeX and print the 69results, provided the printed document carries copying permission 70notice 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 74Permission is granted to copy and distribute modified versions of this 75manual under the conditions for verbatim copying, provided that the entire 76resulting derived work is distributed under the terms of a permission 77notice identical to this one. 78 79Permission is granted to copy and distribute translations of this manual 80into another language, under the above conditions for modified versions, 81except that this permission notice may be stated in a translation approved 82by 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 103Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 2010, 2011 104Free Software Foundation, Inc. 105 106@sp 2 107This is the second edition of the Texinfo documentation,@* 108and is consistent with version 2 of @file{texinfo.tex}. 109@sp 2 110 111Published by the Free Software Foundation @* 11259 Temple Place Suite 330, @* 113Boston, MA 02111-1307 USA @* 114Printed copies are available for $15 each.@* 115ISBN 1-882114-63-9 116@c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995 117 118Permission is granted to make and distribute verbatim copies of 119this manual provided the copyright notice and this permission notice 120are preserved on all copies. 121 122Permission is granted to copy and distribute modified versions of this 123manual under the conditions for verbatim copying, provided that the entire 124resulting derived work is distributed under the terms of a permission 125notice identical to this one. 126 127Permission is granted to copy and distribute translations of this manual 128into another language, under the above conditions for modified versions, 129except that this permission notice may be stated in a translation approved 130by the Free Software Foundation. 131@sp 2 132Cover art by Etienne Suvasa. 133@end titlepage 134 135@ifinfo 136@node Top, Copying, (dir), (dir) 137@top Texinfo 138 139Texinfo is a documentation system that uses a single source file to 140produce both on-line information and printed output.@refill 141 142The first part of this master menu lists the major nodes in this Info 143document, including the @@-command and concept indices. The rest of 144the menu lists all the lower level nodes in the document.@refill 145 146This 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 153Your rights. 154Texinfo in brief. 155How to use Texinfo mode. 156What is at the beginning of a Texinfo file? 157What is at the end of a Texinfo file? 158How to create chapters, sections, subsections, 159 appendices, and other parts. 160How to provide structure for a document. 161How to write nodes. 162How to write menus. 163How to write cross references. 164How to mark words and phrases as code, 165 keyboard input, meta-syntactic 166 variables, and the like. 167How to write quotations, examples, etc. 168How to write lists and tables. 169How to create indices. 170How to insert @@-signs, braces, etc. 171How to indicate results of evaluation, 172 expansion of macros, errors, etc. 173How to force and prevent line and page breaks. 174How to describe functions and the like in a uniform manner. 175How to write footnotes. 176How to specify text for either @TeX{} or Info. 177How to print hardcopy. 178How to create an Info file. 179How to install an Info file 180A list of all the Texinfo @@-commands. 181Hints on how to write a Texinfo document. 182A sample Texinfo file to look at. 183Tell readers they have the right to copy 184 and distribute. 185How to incorporate other Texinfo files. 186How to write page headings and footings. 187How to find formatting mistakes. 188All about paragraph refilling. 189A description of @@-Command syntax. 190Texinfo second edition features. 191A menu containing commands and variables. 192A 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 241Overview 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 256Using 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 268Updating 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 277Beginning 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 288The 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 298The 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 312The `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 317Ending 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 324Chapter 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 339Nodes 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 347The @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 357Menus 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 366Cross 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 385Marking Words and Phrases 386 387* Indicating:: How to indicate definitions, files, etc. 388* Emphasis:: How to emphasize text. 389 390Indicating 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 402Emphasizing 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 409Quotations 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 425Making 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 432Making 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 439Creating 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 448Combining 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 455Special 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 465Inserting @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 472Inserting Ellipsis, Dots, and Bullets 473 474* dots:: How to insert dots @dots{} 475* bullet:: How to insert a bullet. 476 477Inserting @TeX{} and the Copyright Symbol 478 479* tex:: How to insert the @TeX{} logo. 480* copyright symbol:: How to use @code{@@copyright}@{@}. 481 482Glyphs 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 492Making 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 502Definition 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 512The 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 521Footnotes 522 523* Footnote Commands:: How to write a footnote in Texinfo. 524* Footnote Styles:: Controlling how footnotes appear in Info. 525 526Conditionally 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 540Format 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 557Creating 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 571Installing 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 578Sample 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 584Include 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 595Page 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 602Formatting 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 611Finding 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 618Second 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 630The programs currently being distributed that relate to Texinfo include 631portions of GNU Emacs, plus other separate programs (including 632@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). 633These programs are @dfn{free}; this means that everyone is free to use 634them and free to redistribute them on a free basis. The Texinfo-related 635programs are not in the public domain; they are copyrighted and there 636are restrictions on their distribution, but these restrictions are 637designed to permit everything that a good cooperating citizen would want 638to do. What is not allowed is to try to prevent others from further 639sharing any version of these programs that they might get from 640you.@refill 641 642 Specifically, we want to make sure that you have the right to give 643away copies of the programs that relate to Texinfo, that you receive 644source code or else can get it if you want it, that you can change these 645programs or use pieces of them in new free programs, and that you know 646you can do these things.@refill 647 648 To make sure that everyone has such rights, we have to forbid you to 649deprive anyone else of these rights. For example, if you distribute 650copies of the Texinfo related programs, you must give the recipients all 651the rights that you have. You must make sure that they, too, receive or 652can 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 655out that there is no warranty for the programs that relate to Texinfo. 656If these programs are modified by someone else and passed on, we want 657their recipients to know that what they have is not what we distributed, 658so that any problems introduced by others will not reflect on our 659reputation.@refill 660 661 The precise conditions of the licenses for the programs currently 662being distributed that relate to Texinfo are found in the General Public 663Licenses 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 672pronounced like ``speck'', not ``hex''. This odd pronunciation is 673derived from, but is not the same as, the pronunciation of @TeX{}. In 674the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' 675rather than the English letter ``ex''. Pronounce @TeX{} as if the 676@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo 677as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' 678and write the other letters in lower case.} 679is a documentation system that uses a single source file to produce both 680on-line information and printed output. This means that instead of 681writing two different documents, one for the on-line help or other on-line 682information and the other for a typeset manual or other printed work, you 683need write only one document. When the work is revised, you need revise 684only 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 716This file documents the program PSIM. 717 718Copyright (C) 1994-1996, Andrew Cagney. 719 720Permission is granted to make and distribute verbatim copies of 721this manual provided the copyright notice and this permission notice 722are preserved on all copies. 723 724@ignore 725Permission is granted to process this file through Tex and print the 726results, provided the printed document carries copying permission 727notice 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 731Permission is granted to copy and distribute modified versions of this 732manual under the conditions for verbatim copying, subject to the terms 733of the GNU General Public License, which includes the provision that the 734entire resulting derived work is distributed under the terms of a 735permission notice identical to this one. 736 737Permission is granted to copy and distribute translations of this manual 738into 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 749Copyright @copyright{} 1994-1996, Andrew Cagney 750 751This is the first edition of the PSIM manual and is consistent with PSIM 752version 1.0. 753 754Permission is granted to make and distribute verbatim copies of 755this manual provided the copyright notice and this permission notice 756are preserved on all copies. 757 758Permission is granted to copy and distribute modified versions of this 759manual under the conditions for verbatim copying, subject to the terms 760of the GNU General Public License, which includes the provision that the 761entire resulting derived work is distributed under the terms of a 762permission notice identical to this one. 763 764Permission is granted to copy and distribute translations of this manual 765into 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 780PSIM is a program written in extended ANSI-C that implements an 781instruction level simulation of the PowerPC environment. It is freely 782available in source code form under the terms of the GNU General 783Public License (version 2 or later). 784 785The PowerPC Architecture is described as having three levels of 786compliance: 787 788 UEA - User Environment Architecture 789 VEA - Virtual Environment Architecture 790 OEA - Operating Environment Architecture 791 792PSIM both implements all three levels of the PowerPC and includes (for 793each level) a corresponding simulated run-time environment. 794 795In addition, PSIM, to the execution unit level, models the performance 796of most of the current PowerPC implementations (contributed by Michael 797Meissner). This detailed performance monitoring (unlike many other 798simulators) resulting in only a relatively marginal reduction in the 799simulators performance. 800 801 802A 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 807while an overview of how to use PSIM is in: 808 809 ftp://ftp.ci.com.au/pub/psim/RUN 810or ftp://cambridge.cygnus.com/pub/psim/RUN 811 812This file is found in: 813 814 ftp://ftp.ci.com.au/pub/psim/README 815or ftp://cambridge.cygnus.com/pub/psim/README 816 817 818Thanks goes firstly to: 819 820 Corinthian Engineering Pty Ltd 821 Cygnus Support 822 Highland Logic Pty Ltd 823 824who provided the resources needed for making this software available 825on the Internet. 826 827More importantly I'd like to thank the following individuals who each 828contributed 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 1108