| \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--2021 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. |
| |
