aboutsummaryrefslogtreecommitdiff
path: root/sim/ppc/psim.texinfo
blob: 9b02a52438e3f6416a5da2b25f20e6b64b1ec788 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
\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-2015 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.