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