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