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