| \input texinfo.tex @c -*-texinfo-*- | |
| @comment %**start of header | |
| @setfilename texinfo | |
| @settitle Texinfo @value{edition} | |
| @syncodeindex vr fn | |
| @footnotestyle separate | |
| @paragraphindent 2 | |
| @smallbook | |
| @comment %**end of header | |
| @c Set smallbook if printing in smallbook format so the example of the | |
| @c smallbook font is actually written using smallbook; in bigbook, a kludge | |
| @c is used for TeX output. | |
| @set smallbook | |
| @c @@clear smallbook | |
| @ignore | |
| @ifinfo | |
| @format | |
| START-INFO-DIR-ENTRY | |
| * Texinfo: (texinfo). The documentation format for the GNU Project. | |
| END-INFO-DIR-ENTRY | |
| @end format | |
| @end ifinfo | |
| @end ignore | |
| @set edition 2.21 | |
| @set update-date 7 June 1995 | |
| @set update-month June 1995 | |
| @c Experiment with smaller amounts of whitespace between chapters | |
| @c and sections. | |
| @tex | |
| \global\chapheadingskip = 15pt plus 4pt minus 2pt | |
| \global\secheadingskip = 12pt plus 3pt minus 2pt | |
| \global\subsecheadingskip = 9pt plus 2pt minus 2pt | |
| @end tex | |
| @c Experiment with smaller amounts of whitespace between paragraphs in | |
| @c the 8.5 by 11 inch format. | |
| @ifclear smallbook | |
| @tex | |
| \global\parskip 6pt plus 1pt | |
| @end tex | |
| @end ifclear | |
| @finalout | |
| @c Currently undocumented command, 5 December 1993: | |
| @c | |
| @c nwnode (Same as node, but no warnings; for `makeinfo'.) | |
| @ifinfo | |
| This file documents Texinfo, a documentation system that uses a single | |
| source file to produce both on-line information and a printed manual. | |
| Copyright (C) 1988--2024 Free Software Foundation, Inc. | |
| This is the second edition of the Texinfo documentation,@* | |
| and is consistent with version 2 of @file{texinfo.tex}. | |
| Permission is granted to make and distribute verbatim copies of | |
| this manual provided the copyright notice and this permission notice | |
| are preserved on all copies. | |
| @ignore | |
| Permission is granted to process this file through TeX and print the | |
| results, provided the printed document carries copying permission | |
| notice identical to this one except for the removal of this paragraph | |
| (this paragraph not being relevant to the printed manual). | |
| @end ignore | |
| Permission is granted to copy and distribute modified versions of this | |
| manual under the conditions for verbatim copying, provided that the entire | |
| resulting derived work is distributed under the terms of a permission | |
| notice identical to this one. | |
| Permission is granted to copy and distribute translations of this manual | |
| into another language, under the above conditions for modified versions, | |
| except that this permission notice may be stated in a translation approved | |
| by the Free Software Foundation. | |
| @end ifinfo | |
| @setchapternewpage odd | |
| @shorttitlepage Texinfo | |
| @titlepage | |
| @c use the new format for titles | |
| @title Texinfo | |
| @subtitle The GNU Documentation Format | |
| @subtitle Edition @value{edition}, for Texinfo Version Three | |
| @subtitle @value{update-month} | |
| @author by Robert J. Chassell and Richard M. Stallman | |
| @comment Include the Distribution inside the titlepage so | |
| @c that headings are turned off. | |
| @page | |
| @vskip 0pt plus 1filll | |
| Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 2010, 2011 | |
| Free Software Foundation, Inc. | |
| @sp 2 | |
| This is the second edition of the Texinfo documentation,@* | |
| and is consistent with version 2 of @file{texinfo.tex}. | |
| @sp 2 | |
| Published by the Free Software Foundation @* | |
| 59 Temple Place Suite 330, @* | |
| Boston, MA 02111-1307 USA @* | |
| Printed copies are available for $15 each.@* | |
| ISBN 1-882114-63-9 | |
| @c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995 | |
| Permission is granted to make and distribute verbatim copies of | |
| this manual provided the copyright notice and this permission notice | |
| are preserved on all copies. | |
| Permission is granted to copy and distribute modified versions of this | |
| manual under the conditions for verbatim copying, provided that the entire | |
| resulting derived work is distributed under the terms of a permission | |
| notice identical to this one. | |
| Permission is granted to copy and distribute translations of this manual | |
| into another language, under the above conditions for modified versions, | |
| except that this permission notice may be stated in a translation approved | |
| by the Free Software Foundation. | |
| @sp 2 | |
| Cover art by Etienne Suvasa. | |
| @end titlepage | |
| @ifinfo | |
| @node Top, Copying, (dir), (dir) | |
| @top Texinfo | |
| Texinfo is a documentation system that uses a single source file to | |
| produce both on-line information and printed output.@refill | |
| The first part of this master menu lists the major nodes in this Info | |
| document, including the @@-command and concept indices. The rest of | |
| the menu lists all the lower level nodes in the document.@refill | |
| This is Edition @value{edition} of the Texinfo documentation, | |
| @w{@value{update-date},} for Texinfo Version Three. | |
| @end ifinfo | |
| @c Here is a spare copy of the chapter menu entry descriptions, | |
| @c in case they are accidently deleted | |
| @ignore | |
| Your rights. | |
| Texinfo in brief. | |
| How to use Texinfo mode. | |
| What is at the beginning of a Texinfo file? | |
| What is at the end of a Texinfo file? | |
| How to create chapters, sections, subsections, | |
| appendices, and other parts. | |
| How to provide structure for a document. | |
| How to write nodes. | |
| How to write menus. | |
| How to write cross references. | |
| How to mark words and phrases as code, | |
| keyboard input, meta-syntactic | |
| variables, and the like. | |
| How to write quotations, examples, etc. | |
| How to write lists and tables. | |
| How to create indices. | |
| How to insert @@-signs, braces, etc. | |
| How to indicate results of evaluation, | |
| expansion of macros, errors, etc. | |
| How to force and prevent line and page breaks. | |
| How to describe functions and the like in a uniform manner. | |
| How to write footnotes. | |
| How to specify text for either @TeX{} or Info. | |
| How to print hardcopy. | |
| How to create an Info file. | |
| How to install an Info file | |
| A list of all the Texinfo @@-commands. | |
| Hints on how to write a Texinfo document. | |
| A sample Texinfo file to look at. | |
| Tell readers they have the right to copy | |
| and distribute. | |
| How to incorporate other Texinfo files. | |
| How to write page headings and footings. | |
| How to find formatting mistakes. | |
| All about paragraph refilling. | |
| A description of @@-Command syntax. | |
| Texinfo second edition features. | |
| A menu containing commands and variables. | |
| A menu covering many topics. | |
| @end ignore | |
| @menu | |
| * Copying:: Your rights. | |
| * Overview:: Texinfo in brief. | |
| * Texinfo Mode:: How to use Texinfo mode. | |
| * Beginning a File:: What is at the beginning of a Texinfo file? | |
| * Ending a File:: What is at the end of a Texinfo file? | |
| * Structuring:: How to create chapters, sections, subsections, | |
| appendices, and other parts. | |
| * Nodes:: How to write nodes. | |
| * Menus:: How to write menus. | |
| * Cross References:: How to write cross references. | |
| * Marking Text:: How to mark words and phrases as code, | |
| keyboard input, meta-syntactic | |
| variables, and the like. | |
| * Quotations and Examples:: How to write quotations, examples, etc. | |
| * Lists and Tables:: How to write lists and tables. | |
| * Indices:: How to create indices. | |
| * Insertions:: How to insert @@-signs, braces, etc. | |
| * Glyphs:: How to indicate results of evaluation, | |
| expansion of macros, errors, etc. | |
| * Breaks:: How to force and prevent line and page breaks. | |
| * Definition Commands:: How to describe functions and the like | |
| in a uniform manner. | |
| * Footnotes:: How to write footnotes. | |
| * Conditionals:: How to specify text for either @TeX{} or Info. | |
| * Format/Print Hardcopy:: How to convert a Texinfo file to a file | |
| for printing and how to print that file. | |
| * Create an Info File:: Convert a Texinfo file into an Info file. | |
| * Install an Info File:: Make an Info file accessible to users. | |
| * Command List:: All the Texinfo @@-commands. | |
| * Tips:: Hints on how to write a Texinfo document. | |
| * Sample Texinfo File:: A sample Texinfo file to look at. | |
| * Sample Permissions:: Tell readers they have the right to copy | |
| and distribute. | |
| * Include Files:: How to incorporate other Texinfo files. | |
| * Headings:: How to write page headings and footings. | |
| * Catching Mistakes:: How to find formatting mistakes. | |
| * Refilling Paragraphs:: All about paragraph refilling. | |
| * Command Syntax:: A description of @@-Command syntax. | |
| * Obtaining TeX:: How to Obtain @TeX{}. | |
| * New Features:: Texinfo second edition features. | |
| * Command and Variable Index:: A menu containing commands and variables. | |
| * Concept Index:: A menu covering many topics. | |
| --- The Detailed Node Listing --- | |
| Overview of Texinfo | |
| * Using Texinfo:: Create a conventional printed book | |
| or an Info file. | |
| * Info Files:: What is an Info file? | |
| * Printed Books:: Characteristics of a printed book or manual. | |
| * Formatting Commands:: @@-commands are used for formatting. | |
| * Conventions:: General rules for writing a Texinfo file. | |
| * Comments:: How to write comments and mark regions that | |
| the formatting commands will ignore. | |
| * Minimum:: What a Texinfo file must have. | |
| * Six Parts:: Usually, a Texinfo file has six parts. | |
| * Short Sample:: A short sample Texinfo file. | |
| * Acknowledgements:: | |
| Using Texinfo Mode | |
| * Texinfo Mode Overview:: How Texinfo mode can help you. | |
| * Emacs Editing:: Texinfo mode adds to GNU Emacs' general | |
| purpose editing features. | |
| * Inserting:: How to insert frequently used @@-commands. | |
| * Showing the Structure:: How to show the structure of a file. | |
| * Updating Nodes and Menus:: How to update or create new nodes and menus. | |
| * Info Formatting:: How to format for Info. | |
| * Printing:: How to format and print part or all of a file. | |
| * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. | |
| Updating Nodes and Menus | |
| * Updating Commands:: Five major updating commands. | |
| * Updating Requirements:: How to structure a Texinfo file for | |
| using the updating command. | |
| * Other Updating Commands:: How to indent descriptions, insert | |
| missing nodes lines, and update | |
| nodes in sequence. | |
| Beginning a Texinfo File | |
| * Four Parts:: Four parts begin a Texinfo file. | |
| * Sample Beginning:: Here is a sample beginning for a Texinfo file. | |
| * Header:: The very beginning of a Texinfo file. | |
| * Info Summary and Permissions:: Summary and copying permissions for Info. | |
| * Titlepage & Copyright Page:: Creating the title and copyright pages. | |
| * The Top Node:: Creating the `Top' node and master menu. | |
| * Software Copying Permissions:: Ensure that you and others continue to | |
| have the right to use and share software. | |
| The Texinfo File Header | |
| * First Line:: The first line of a Texinfo file. | |
| * Start of Header:: Formatting a region requires this. | |
| * setfilename:: Tell Info the name of the Info file. | |
| * settitle:: Create a title for the printed work. | |
| * setchapternewpage:: Start chapters on right-hand pages. | |
| * paragraphindent:: An option to specify paragraph indentation. | |
| * End of Header:: Formatting a region requires this. | |
| The Title and Copyright Pages | |
| * titlepage:: Create a title for the printed document. | |
| * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, | |
| and @code{@@sp} commands. | |
| * title subtitle author:: The @code{@@title}, @code{@@subtitle}, | |
| and @code{@@author} commands. | |
| * Copyright & Permissions:: How to write the copyright notice and | |
| include copying permissions. | |
| * end titlepage:: Turn on page headings after the title and | |
| copyright pages. | |
| * headings on off:: An option for turning headings on and off | |
| and double or single sided printing. | |
| The `Top' Node and Master Menu | |
| * Title of Top Node:: Sketch what the file is about. | |
| * Master Menu Parts:: A master menu has three or more parts. | |
| Ending a Texinfo File | |
| * Printing Indices & Menus:: How to print an index in hardcopy and | |
| generate index menus in Info. | |
| * Contents:: How to create a table of contents. | |
| * File End:: How to mark the end of a file. | |
| Chapter Structuring | |
| * Tree Structuring:: A manual is like an upside down tree @dots{} | |
| * Structuring Command Types:: How to divide a manual into parts. | |
| * makeinfo top:: The @code{@@top} command, part of the `Top' node. | |
| * chapter:: | |
| * unnumbered & appendix:: | |
| * majorheading & chapheading:: | |
| * section:: | |
| * unnumberedsec appendixsec heading:: | |
| * subsection:: | |
| * unnumberedsubsec appendixsubsec subheading:: | |
| * subsubsection:: Commands for the lowest level sections. | |
| * Raise/lower sections:: How to change commands' hierarchical level. | |
| Nodes | |
| * Two Paths:: Different commands to structure | |
| Info output and printed output. | |
| * Node Menu Illustration:: A diagram, and sample nodes and menus. | |
| * node:: How to write a node, in detail. | |
| * makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. | |
| The @code{@@node} Command | |
| * Node Names:: How to choose node and pointer names. | |
| * Writing a Node:: How to write an @code{@@node} line. | |
| * Node Line Tips:: Keep names short. | |
| * Node Line Requirements:: Keep names unique, without @@-commands. | |
| * First Node:: How to write a `Top' node. | |
| * makeinfo top command:: How to use the @code{@@top} command. | |
| * Top Node Summary:: Write a brief description for readers. | |
| Menus | |
| * Menu Location:: Put a menu in a short node. | |
| * Writing a Menu:: What is a menu? | |
| * Menu Parts:: A menu entry has three parts. | |
| * Less Cluttered Menu Entry:: Two part menu entry. | |
| * Menu Example:: Two and three part menu entries. | |
| * Other Info Files:: How to refer to a different Info file. | |
| Cross References | |
| * References:: What cross references are for. | |
| * Cross Reference Commands:: A summary of the different commands. | |
| * Cross Reference Parts:: A cross reference has several parts. | |
| * xref:: Begin a reference with `See' @dots{} | |
| * Top Node Naming:: How to refer to the beginning of another file. | |
| * ref:: A reference for the last part of a sentence. | |
| * pxref:: How to write a parenthetical cross reference. | |
| * inforef:: How to refer to an Info-only file. | |
| @code{@@xref} | |
| * Reference Syntax:: What a reference looks like and requires. | |
| * One Argument:: @code{@@xref} with one argument. | |
| * Two Arguments:: @code{@@xref} with two arguments. | |
| * Three Arguments:: @code{@@xref} with three arguments. | |
| * Four and Five Arguments:: @code{@@xref} with four and five arguments. | |
| Marking Words and Phrases | |
| * Indicating:: How to indicate definitions, files, etc. | |
| * Emphasis:: How to emphasize text. | |
| Indicating Definitions, Commands, etc. | |
| * Useful Highlighting:: Highlighting provides useful information. | |
| * code:: How to indicate code. | |
| * kbd:: How to show keyboard input. | |
| * key:: How to specify keys. | |
| * samp:: How to show a literal sequence of characters. | |
| * var:: How to indicate a metasyntactic variable. | |
| * file:: How to indicate the name of a file. | |
| * dfn:: How to specify a definition. | |
| * cite:: How to refer to a book that is not in Info. | |
| Emphasizing Text | |
| * emph & strong:: How to emphasize text in Texinfo. | |
| * Smallcaps:: How to use the small caps font. | |
| * Fonts:: Various font commands for printed output. | |
| * Customized Highlighting:: How to define highlighting commands. | |
| Quotations and Examples | |
| * Block Enclosing Commands:: Use different constructs for | |
| different purposes. | |
| * quotation:: How to write a quotation. | |
| * example:: How to write an example in a fixed-width font. | |
| * noindent:: How to prevent paragraph indentation. | |
| * Lisp Example:: How to illustrate Lisp code. | |
| * smallexample & smalllisp:: Forms for the @code{@@smallbook} option. | |
| * display:: How to write an example in the current font. | |
| * format:: How to write an example that does not narrow | |
| the margins. | |
| * exdent:: How to undo the indentation of a line. | |
| * flushleft & flushright:: How to push text flushleft or flushright. | |
| * cartouche:: How to draw cartouches around examples. | |
| Making Lists and Tables | |
| * Introducing Lists:: Texinfo formats lists for you. | |
| * itemize:: How to construct a simple list. | |
| * enumerate:: How to construct a numbered list. | |
| * Two-column Tables:: How to construct a two-column table. | |
| Making a Two-column Table | |
| * table:: How to construct a two-column table. | |
| * ftable vtable:: How to construct a two-column table | |
| with automatic indexing. | |
| * itemx:: How to put more entries in the first column. | |
| Creating Indices | |
| * Index Entries:: Choose different words for index entries. | |
| * Predefined Indices:: Use different indices for different kinds | |
| of entry. | |
| * Indexing Commands:: How to make an index entry. | |
| * Combining Indices:: How to combine indices. | |
| * New Indices:: How to define your own indices. | |
| Combining Indices | |
| * syncodeindex:: How to merge two indices, using @code{@@code} | |
| font for the merged-from index. | |
| * synindex:: How to merge two indices, using the | |
| default font of the merged-to index. | |
| Special Insertions | |
| * Braces Atsigns Periods:: How to insert braces, @samp{@@} and periods. | |
| * dmn:: How to format a dimension. | |
| * Dots Bullets:: How to insert dots and bullets. | |
| * TeX and copyright:: How to insert the @TeX{} logo | |
| and the copyright symbol. | |
| * minus:: How to insert a minus sign. | |
| * math:: How to format a mathematical expression. | |
| Inserting @samp{@@}, Braces, and Periods | |
| * Inserting An Atsign:: | |
| * Inserting Braces:: How to insert @samp{@{} and @samp{@}} | |
| * Controlling Spacing:: How to insert the right amount of space | |
| after punctuation within a sentence. | |
| Inserting Ellipsis, Dots, and Bullets | |
| * dots:: How to insert dots @dots{} | |
| * bullet:: How to insert a bullet. | |
| Inserting @TeX{} and the Copyright Symbol | |
| * tex:: How to insert the @TeX{} logo. | |
| * copyright symbol:: How to use @code{@@copyright}@{@}. | |
| Glyphs for Examples | |
| * Glyphs Summary:: | |
| * result:: How to show the result of expression. | |
| * expansion:: How to indicate an expansion. | |
| * Print Glyph:: How to indicate printed output. | |
| * Error Glyph:: How to indicate an error message. | |
| * Equivalence:: How to indicate equivalence. | |
| * Point Glyph:: How to indicate the location of point. | |
| Making and Preventing Breaks | |
| * Break Commands:: Cause and prevent splits. | |
| * Line Breaks:: How to force a single line to use two lines. | |
| * w:: How to prevent unwanted line breaks. | |
| * sp:: How to insert blank lines. | |
| * page:: How to force the start of a new page. | |
| * group:: How to prevent unwanted page breaks. | |
| * need:: Another way to prevent unwanted page breaks. | |
| Definition Commands | |
| * Def Cmd Template:: How to structure a description using a | |
| definition command. | |
| * Optional Arguments:: How to handle optional and repeated arguments. | |
| * deffnx:: How to group two or more `first' lines. | |
| * Def Cmds in Detail:: All the definition commands. | |
| * Def Cmd Conventions:: Conventions for writing definitions. | |
| * Sample Function Definition:: | |
| The Definition Commands | |
| * Functions Commands:: Commands for functions and similar entities. | |
| * Variables Commands:: Commands for variables and similar entities. | |
| * Typed Functions:: Commands for functions in typed languages. | |
| * Typed Variables:: Commands for variables in typed languages. | |
| * Abstract Objects:: Commands for object-oriented programming. | |
| * Data Types:: The definition command for data types. | |
| Footnotes | |
| * Footnote Commands:: How to write a footnote in Texinfo. | |
| * Footnote Styles:: Controlling how footnotes appear in Info. | |
| Conditionally Visible Text | |
| * Conditional Commands:: How to specify text for Info or @TeX{}. | |
| * Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. | |
| * set clear value:: How to designate which text to format (for | |
| both Info and @TeX{}); and how to set a | |
| flag to a string that you can insert. | |
| @code{@@set}, @code{@@clear}, and @code{@@value} | |
| * ifset ifclear:: Format a region if a flag is set. | |
| * value:: Replace a flag with a string. | |
| * value Example:: An easy way to update edition information. | |
| Format and Print Hardcopy | |
| * Use TeX:: Use @TeX{} to format for hardcopy. | |
| * Format with tex/texindex:: How to format in a shell. | |
| * Format with texi2dvi:: A simpler way to use the shell. | |
| * Print with lpr:: How to print. | |
| * Within Emacs:: How to format and print from an Emacs shell. | |
| * Texinfo Mode Printing:: How to format and print in Texinfo mode. | |
| * Compile-Command:: How to print using Emacs's compile command. | |
| * Requirements Summary:: @TeX{} formatting requirements summary. | |
| * Preparing for TeX:: What you need to do to use @TeX{}. | |
| * Overfull hboxes:: What are and what to do with overfull hboxes. | |
| * smallbook:: How to print small format books and manuals. | |
| * A4 Paper:: How to print on European A4 paper. | |
| * Cropmarks and Magnification:: How to print marks to indicate the size | |
| of pages and how to print scaled up output. | |
| Creating an Info File | |
| * makeinfo advantages:: @code{makeinfo} provides better error checking. | |
| * Invoking makeinfo:: How to run @code{makeinfo} from a shell. | |
| * makeinfo options:: Specify fill-column and other options. | |
| * Pointer Validation:: How to check that pointers point somewhere. | |
| * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. | |
| * texinfo-format commands:: Two Info formatting commands written | |
| in Emacs Lisp are an alternative | |
| to @code{makeinfo}. | |
| * Batch Formatting:: How to format for Info in Emacs Batch mode. | |
| * Tag and Split Files:: How tagged and split files help Info | |
| to run better. | |
| Installing an Info File | |
| * Directory file:: The top level menu for all Info files. | |
| * New Info File:: Listing a new info file. | |
| * Other Info Directories:: How to specify Info files that are | |
| located in other directories. | |
| Sample Permissions | |
| * Inserting Permissions:: How to put permissions in your document. | |
| * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. | |
| * Titlepage Permissions:: Sample Titlepage copying permissions. | |
| Include Files | |
| * Using Include Files:: How to use the @code{@@include} command. | |
| * texinfo-multiple-files-update:: How to create and update nodes and | |
| menus when using included files. | |
| * Include File Requirements:: What @code{texinfo-multiple-files-update} expects. | |
| * Sample Include File:: A sample outer file with included files | |
| within it; and a sample included file. | |
| * Include Files Evolution:: How use of the @code{@@include} command | |
| has changed over time. | |
| Page Headings | |
| * Headings Introduced:: Conventions for using page headings. | |
| * Heading Format:: Standard page heading formats. | |
| * Heading Choice:: How to specify the type of page heading. | |
| * Custom Headings:: How to create your own headings and footings. | |
| Formatting Mistakes | |
| * makeinfo preferred:: @code{makeinfo} finds errors. | |
| * Debugging with Info:: How to catch errors with Info formatting. | |
| * Debugging with TeX:: How to catch errors with @TeX{} formatting. | |
| * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. | |
| * Using occur:: How to list all lines containing a pattern. | |
| * Running Info-Validate:: How to find badly referenced nodes. | |
| Finding Badly Referenced Nodes | |
| * Using Info-validate:: How to run @code{Info-validate}. | |
| * Unsplit:: How to create an unsplit file. | |
| * Tagifying:: How to tagify a file. | |
| * Splitting:: How to split a file manually. | |
| Second Edition Features | |
| * New Texinfo Mode Commands:: The updating commands are especially useful. | |
| * New Commands:: Many newly described @@-commands. | |
| @end menu | |
| @node Copying, Overview, Top, Top | |
| @comment node-name, next, previous, up | |
| @unnumbered Texinfo Copying Conditions | |
| @cindex Copying conditions | |
| @cindex Conditions for copying Texinfo | |
| The programs currently being distributed that relate to Texinfo include | |
| portions of GNU Emacs, plus other separate programs (including | |
| @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). | |
| These programs are @dfn{free}; this means that everyone is free to use | |
| them and free to redistribute them on a free basis. The Texinfo-related | |
| programs are not in the public domain; they are copyrighted and there | |
| are restrictions on their distribution, but these restrictions are | |
| designed to permit everything that a good cooperating citizen would want | |
| to do. What is not allowed is to try to prevent others from further | |
| sharing any version of these programs that they might get from | |
| you.@refill | |
| Specifically, we want to make sure that you have the right to give | |
| away copies of the programs that relate to Texinfo, that you receive | |
| source code or else can get it if you want it, that you can change these | |
| programs or use pieces of them in new free programs, and that you know | |
| you can do these things.@refill | |
| To make sure that everyone has such rights, we have to forbid you to | |
| deprive anyone else of these rights. For example, if you distribute | |
| copies of the Texinfo related programs, you must give the recipients all | |
| the rights that you have. You must make sure that they, too, receive or | |
| can get the source code. And you must tell them their rights.@refill | |
| Also, for our own protection, we must make certain that everyone finds | |
| out that there is no warranty for the programs that relate to Texinfo. | |
| If these programs are modified by someone else and passed on, we want | |
| their recipients to know that what they have is not what we distributed, | |
| so that any problems introduced by others will not reflect on our | |
| reputation.@refill | |
| The precise conditions of the licenses for the programs currently | |
| being distributed that relate to Texinfo are found in the General Public | |
| Licenses that accompany them.@refill | |
| @node Overview, Texinfo Mode, Copying, Top | |
| @comment node-name, next, previous, up | |
| @chapter Overview of Texinfo | |
| @cindex Overview of Texinfo | |
| @cindex Texinfo overview | |
| @dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is | |
| pronounced like ``speck'', not ``hex''. This odd pronunciation is | |
| derived from, but is not the same as, the pronunciation of @TeX{}. In | |
| the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' | |
| rather than the English letter ``ex''. Pronounce @TeX{} as if the | |
| @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo | |
| as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' | |
| and write the other letters in lower case.} | |
| is a documentation system that uses a single source file to produce both | |
| on-line information and printed output. This means that instead of | |
| writing two different documents, one for the on-line help or other on-line | |
| information and the other for a typeset manual or other printed work, you | |
| need write only one document. When the work is revised, you need revise | |
| only one document. (You can read the on-line information, known as an | |
| @dfn{Info file}, with an Info documentation-reading program.)@refill | |
| @menu | |
| * Using Texinfo:: Create a conventional printed book | |
| or an Info file. | |
| * Info Files:: What is an Info file? | |
| * Printed Books:: Characteristics of a printed book or manual. | |
| * Formatting Commands:: @@-commands are used for formatting. | |
| * Conventions:: General rules for writing a Texinfo file. | |
| * Comments:: How to write comments and mark regions that | |
| the formatting commands will ignore. | |
| * Minimum:: What a Texinfo file must have. | |
| * Six Parts:: Usually, a Texinfo file has six parts. | |
| * Short Sample:: A short sample Texinfo file. | |
| * Acknowledgements:: | |
| @end menu | |
| @c ************************************************************************ | |
| \input texinfo @c -*-texinfo-*- | |
| @c %**start of header | |
| @setfilename psim.info | |
| @settitle PSIM | |
| @setchapternewpage odd | |
| @c %**end of header | |
| @ifinfo | |
| This file documents the program PSIM. | |
| Copyright (C) 1994-1996, Andrew Cagney. | |
| Permission is granted to make and distribute verbatim copies of | |
| this manual provided the copyright notice and this permission notice | |
| are preserved on all copies. | |
| @ignore | |
| Permission is granted to process this file through Tex and print the | |
| results, provided the printed document carries copying permission | |
| notice identical to this one except for the removal of this paragraph | |
| (this paragraph not being relevant to the printed manual). | |
| @end ignore | |
| Permission is granted to copy and distribute modified versions of this | |
| manual under the conditions for verbatim copying, subject to the terms | |
| of the GNU General Public License, which includes the provision that the | |
| entire resulting derived work is distributed under the terms of a | |
| permission notice identical to this one. | |
| Permission is granted to copy and distribute translations of this manual | |
| into another language, under the above conditions for modified versions. | |
| @end ifinfo | |
| @titlepage | |
| @title PSIM | |
| @subtitle Model of the PowerPC Environments | |
| @author Andrew Cagney | |
| @page | |
| @vskip Opt plus ifill | |
| Copyright @copyright{} 1994-1996, Andrew Cagney | |
| This is the first edition of the PSIM manual and is consistent with PSIM | |
| version 1.0. | |
| Permission is granted to make and distribute verbatim copies of | |
| this manual provided the copyright notice and this permission notice | |
| are preserved on all copies. | |
| Permission is granted to copy and distribute modified versions of this | |
| manual under the conditions for verbatim copying, subject to the terms | |
| of the GNU General Public License, which includes the provision that the | |
| entire resulting derived work is distributed under the terms of a | |
| permission notice identical to this one. | |
| Permission is granted to copy and distribute translations of this manual | |
| into another language, under the above conditions for modified versions. | |
| @end titlepage | |
| @menu | |
| * Copying:: Your rights and freedoms. | |
| * First Chappeter:: Getting started .... | |
| * Second Chapter:: Getting finished .... | |
| @end menu | |
| PSIM is a program written in extended ANSI-C that implements an | |
| instruction level simulation of the PowerPC environment. It is freely | |
| available in source code form under the terms of the GNU General | |
| Public License (version 3 or later). | |
| The PowerPC Architecture is described as having three levels of | |
| compliance: | |
| UEA - User Environment Architecture | |
| VEA - Virtual Environment Architecture | |
| OEA - Operating Environment Architecture | |
| PSIM both implements all three levels of the PowerPC and includes (for | |
| each level) a corresponding simulated run-time environment. | |
| In addition, PSIM, to the execution unit level, models the performance | |
| of most of the current PowerPC implementations (contributed by Michael | |
| Meissner). This detailed performance monitoring (unlike many other | |
| simulators) resulting in only a relatively marginal reduction in the | |
| simulators performance. | |
| A description of how to build PSIM is contained in the file: | |
| ftp://ftp.ci.com.au/pub/psim/INSTALL | |
| or ftp://cambridge.cygnus.com/pub/psim/INSTALL | |
| while an overview of how to use PSIM is in: | |
| ftp://ftp.ci.com.au/pub/psim/RUN | |
| or ftp://cambridge.cygnus.com/pub/psim/RUN | |
| This file is found in: | |
| ftp://ftp.ci.com.au/pub/psim/README | |
| or ftp://cambridge.cygnus.com/pub/psim/README | |
| Thanks goes firstly to: | |
| Corinthian Engineering Pty Ltd | |
| Cygnus Support | |
| Highland Logic Pty Ltd | |
| who provided the resources needed for making this software available | |
| on the Internet. | |
| More importantly I'd like to thank the following individuals who each | |
| contributed in their own unique way: | |
| Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam, | |
| Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn, | |
| Richard Stallman, Mitchele Walker | |
| Andrew Cagney | |
| Feb, 1995 | |
| ---------------------------------------------------------------------- | |
| What features does PSIM include? | |
| Monitoring and modeling | |
| PSIM includes (thanks to Michael Meissner) | |
| a detailed model of most of the PowerPC | |
| implementations to the functional unit level. | |
| SMP | |
| The PowerPC ISA defines SMP synchronizing instructions. | |
| This simulator implements a limited, but functional, | |
| subset of the PowerPC synchronization instructions | |
| behaviour. Programs that restrict their synchronization | |
| primitives to those that work with this functional | |
| sub-set (eg P() and V()) are able to run on the SMP | |
| version of PSIM. | |
| People intending to use this system should study | |
| the code implementing the lwarx instruction. | |
| ENDIAN SUPPORT | |
| PSIM implements the PowerPC's big and little (xor | |
| endian) modes and correctly simulates code that | |
| switches between these two modes. | |
| In addition, psim can model a true little-endian | |
| machine. | |
| ISA (Instruction Set Architecture) models | |
| PSIM includes a model of the UEA, VEA and OEA. This | |
| includes the time base registers (VEA) and HTAB | |
| and BATS (OEA). | |
| In addition, a preliminary model of the 64 bit | |
| PowerPC architecture is implemented. | |
| IO Hardware | |
| PSIM's internals are based around the concept | |
| of a Device Tree. This tree intentionally | |
| resembles that of the Device Tree found in | |
| OpenBoot firmware. PSIM is flexible enough | |
| to allow the user to fully configure this device | |
| tree (and consequently the hardware model) at | |
| run time. | |
| Run-time environments: | |
| PSIM's UEA model includes emulation for BSD | |
| based UNIX system calls. | |
| PSIM's OEA model includes emulation of either: | |
| o OpenBoot client interface | |
| o MOTO's BUG interface. | |
| Floating point | |
| Preliminary support for floating point is included. | |
| Who would be interested in PSIM? | |
| o the curious | |
| Using psim, gdb, gcc and binutils the curious | |
| user can construct an environment that allows | |
| them to play with PowerPC Environment without | |
| the need for real hardware. | |
| o the analyst | |
| PSIM includes many (contributed) monitoring | |
| features which (unlike many other simulators) | |
| do not come with a great penalty in performance. | |
| Thus the performance analyst is able to use | |
| this simulator to analyse the performance of | |
| the system under test. | |
| If PSIM doesn't monitor a components of interest, | |
| the source code is freely available, and hence | |
| there is no hinderance to changing things | |
| to meet a specific analysts needs. | |
| o the serious SW developer | |
| PSIM models all three levels of the PowerPC | |
| Architecture: UEA, VEA and OEA. Further, | |
| the internal design is such that PSIM can | |
| be extended to support additional requirements. | |
| What performance analysis measurements can PSIM perform? | |
| Below is the output from a recent analysis run | |
| (contributed by Michael Meissner): | |
| For the following program: | |
| long | |
| simple_rand () | |
| { | |
| static unsigned long seed = 47114711; | |
| unsigned long this = seed * 1103515245 + 12345; | |
| seed = this; | |
| /* cut-cut-cut - see the file RUN.psim */ | |
| } | |
| Here is the current output generated with the -I switch on a P90 | |
| (the compiler used is the development version of GCC with a new | |
| scheduler replacing the old one): | |
| CPU #1 executed 41,994 AND instructions. | |
| CPU #1 executed 519,785 AND Immediate instructions. | |
| . | |
| . | |
| . | |
| CPU #1 executed 1 System Call instruction. | |
| CPU #1 executed 207,746 XOR instructions. | |
| CPU #1 executed 23,740,856 cycles. | |
| CPU #1 executed 10,242,780 stalls waiting for data. | |
| CPU #1 executed 1 stall waiting for a function unit. | |
| . | |
| . | |
| . | |
| CPU #1 executed 3,136,229 branch functional unit instructions. | |
| CPU #1 executed 16,949,396 instructions that were accounted for in timing info. | |
| CPU #1 executed 871,920 data reads. | |
| CPU #1 executed 971,926 data writes. | |
| CPU #1 executed 221 icache misses. | |
| CPU #1 executed 16,949,396 instructions in total. | |
| Simulator speed was 250,731 instructions/second | |
| What motivated PSIM? | |
| As an idea, psim was first discussed seriously during mid | |
| 1994. At that time its main objectives were: | |
| o good performance | |
| Many simulators loose out by only providing | |
| a binary interface to the internals. This | |
| interface eventually becomes a bottle neck | |
| in the simulators performance. | |
| It was intended that PSIM would avoid this | |
| problem by giving the user access to the | |
| full source code. | |
| Further, by exploiting the power of modern | |
| compilers it was hoped that PSIM would achieve | |
| good performance with out having to compromise | |
| its internal design. | |
| o practical portability | |
| Rather than try to be portable to every | |
| C compiler on every platform, it was decided | |
| that PSIM would restrict its self to supporting | |
| ANSI compilers that included the extension | |
| of a long long type. | |
| GCC is one such compiler, consequently PSIM | |
| should be portable to any machine running GCC. | |
| o flexibility in its design | |
| PSIM should allow the user to select the | |
| features required and customise the build | |
| accordingly. By having the source code, | |
| the compiler is able to eliminate any un | |
| used features of the simulator. | |
| After all, let the compiler do the work. | |
| o SMP | |
| A model that allowed the simulation of | |
| SMP platforms with out the large overhead | |
| often encountered with such models. | |
| PSIM achieves each of these objectives. | |
| Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant? | |
| No. | |
| Among other things it does not have an Apple ROM socket. | |
| Could PSIM be extended so that it models a CHRP machine? | |
| Yes. | |
| PSIM has been designed with the CHRP spec in mind. To model | |
| a CHRP desktop the following would need to be added: | |
| o An apple ROM socket :-) | |
| o Model of each of the desktop IO devices | |
| o An OpenPIC device. | |
| o RTAS (Run Time Abstraction Services). | |
| o A fully populated device tree. | |
| Is the source code available? | |
| Yes. | |
| The source code to PSIM is available under the terms of | |
| the GNU Public Licence. This allows you to distribute | |
| the source code for free but with certain conditions. | |
| See the file: | |
| ftp://archie.au/gnu/COPYING | |
| For details of the terms and conditions. | |
| Where do I send bugs or report problems? | |
| There is a mailing list (subscribe through majordomo@ci.com.au) at: | |
| powerpc-psim@ci.com.au | |
| If I get the ftp archive updated I post a note to that mailing list. | |
| In addition your welcome to send bugs or problems either to me or to | |
| that e-mail list. | |
| This list currently averages zero articles a day. | |
| Does PSIM have any limitations or problems? | |
| PSIM can't run rs6000/AIX binaries - At present PSIM can only | |
| simulate static executables. Since an AIX executable is | |
| never static, PSIM is unable to simulate its execution. | |
| PSIM is still under development - consequently there are going | |
| to be bugs. | |
| See the file BUGS (included in the distribution) for any | |
| other outstanding issues. | |