This commit was generated by cvs2svn to track changes on a CVS vendor
[external/binutils.git] / sim / ppc / INSTALL
1
2                 PSIM - model the PowerPC environment
3
4     Copyright (C) 1994-1996, Andrew Cagney <cagney@highland.com.au>.
5
6     ----------------------------------------------------------------------
7
8
9                         Building PSIM
10
11         This file describes how to build the program PSIM
12
13         o       Walk through a basic build
14
15         o       Discussion of PSIM's components and
16                 how they relate to the build process
17
18         o       Detailed description of each of PSIM's
19                 compile time configuration options
20
21
22     ----------------------------------------------------------------------
23
24
25 BUILDING PSIM:
26
27 PSIM 1.0.2 is included in GDB-4.16.  To build PSIM you will need the
28 following:
29
30         gdb-4.16.tar.gz         Available from your favorite GNU
31                                 ftp site
32
33         gcc                     GCC version two includes suport
34                                 for long long (64bit integer)
35                                 arrithemetic which PSIM uses.  Hence
36                                 it is recommended that you build PSIM
37                                 using GCC.
38                                 
39 Method:
40
41         1.      Unpack gdb
42
43                 $ cd .../scratch
44                 $ gunzip < gdb-4.16.tar.gz | tar xf -
45
46
47         2.      Configure gdb
48
49                 First consult the gdb documentation
50
51                 $ cd .../scratch
52                 $ cd gdb-4.16
53                 $ more README
54                 $ more gdb/README
55
56                 then something like (I assume SH):
57
58                 $ CC=gcc ./configure \
59                         --enable-sim-powerpc \
60                         --target=powerpc-unknown-eabi \
61                         --prefix=/applications/psim
62
63
64         4.      Build (again specifying GCC)
65
66                 $ make CC=gcc
67
68                 alternatively, if you are short on disk space or only
69                 want to build the simulator:
70
71                 $ ( cd libiberty && make CC=gcc )
72                 $ ( cd bfd && make CC=gcc )
73                 $ ( cd sim/ppc && make CC=gcc )
74
75
76         5.      Install
77
78                 $ make CC=gcc install
79
80                 or just
81
82                 $ cp gdb/gdb ~/bin/powerpc-unknown-eabisim-gdb
83                 $ cp sim/ppc/run ~/bin/powerpc-unknown-eabisim-run
84
85
86     ----------------------------------------------------------------------
87
88
89 UPDATING PSIM:
90
91
92 A PSIM is an ongoing development.  Occasional snapshots which both contain new features and fix old bugs are made available.   See the ftp directory:
93
94         ftp://ftp.ci.com.au/pub/psim/beta
95 or      ftp://cambridge.cygnus.com/pub/psim/beta
96
97 for the latest version.  To build/install one of these snapshots, you
98 replace the sim/ppc found in the gdb archive with with one from the
99 snapshot.  Then just re-configure and rebuild/install.
100
101         Procedure:
102
103         0.      A starting point
104
105                 $ cd gdb-4.16
106
107
108         1.      Remove the old psim directory
109
110                 $ mv sim/ppc sim/old.ppc
111
112
113         2.      Unpack the new one
114
115                 $ gunzip < ../psim-NNNNNN.tar.gz | tar tf -
116                 $ gunzip < ../psim-NNNNNN.tar.gz | tar tf -
117
118
119         3.      Reconfigure/rebuild (as seen above):
120
121                 $ CC=gcc ./configure \
122                         --enable-sim-powerpc \
123                         --target=powerpc-unknown-eabi \
124                         --prefix=/applications/psim
125                 $ make CC=gcc
126
127
128     ----------------------------------------------------------------------
129
130
131 UPDATES TO GDB:
132
133 From time to time, problems involving the integration of PSIM into gdb
134 are found.  While eventually each of these problems is resolved there
135 can be periouds during which a local hack may be needed.
136
137 At the time of writing the following were outstanding:
138
139         ATTACH command:
140
141                 ftp://ftp.ci.com.au/pub/psim/gdb-4.15+attach.diff.gz
142         or      ftp://cambridge.cygnus.com/pub/psim/gdb-4.15+attach.diff.gz
143         
144         PSIM, unlike the other simulators found in GDB, is able to load
145         the description of a target machine (including the initial
146         state of all processor registers) from a file.
147
148         Unfortunatly GDB does not yet have a standard command that
149         facilitates the use of this feature.  Until such a command is
150         added, the patch (hack?) gdb-4.15+attach.diff.gz can be used to
151         extend GDB's attach command so that it can be used to initialize
152         the simulators configuration from a file.
153
154
155
156     ----------------------------------------------------------------------
157
158
159 RUNNING PROGRAMS:
160
161
162 See the file:
163
164         ftp://ftp.ci.com.au/pub/psim/RUN
165 or      ftp://cambridge.cygnus.com/pub/psim/RUN
166
167
168     ----------------------------------------------------------------------
169
170
171 COMPILE TIME CONFIGURATION OPTIONS:
172
173
174 PSIM's compile time configuration is controlled by autoconf.  PSIM's
175 configure script recognises options of the form:
176
177                 --enable-sim-<option>[=<val>]
178
179 And can be specified on the configure command line (at the top level
180 of the gdb directory tree) vis:
181
182                 $ cd gdb-4.15
183                 $ CC=gcc ./configure \
184                         --target=powerpc-unknown-eabisim \
185                         --prefix=/applications/psim \
186                         --enable-sim-inline
187                 $ make CC=gcc
188
189 For a brief list of PSIM's configuration options, configure --help
190 will list them vis:
191
192         $ cd sim/ppc
193         $ ./configure --help
194
195 Each PSIM specific option is discussed in detail below.
196
197
198
199 --enable-sim-cflags=<opts>
200
201
202 Specify additional C compiler flags that are to be used when compiling
203 just PSIM.
204
205 PSIM places heavy demands on both the host machine and its C compiler.
206 So that the builder has better control over the compiler the above
207 option can be used to pass additional options to the compiler while PSIM is being built.
208
209 Ex: No debug information
210
211 PSIM can be built with everything inline.  Unfortunately, because of
212 all the debugging information generated the C compiler can grow very
213 very large as a result.  For GCC, the debug information can be
214 restricted with the `-g0' option.  To specify that this option should
215 be include in the CFLAGS when compiling the psim source code use:
216
217         --enable-sim-cflags=-g0
218
219 Ex: Additional optimization flags
220
221 A significant gain in performance can be achieved by tuning the
222 optimization flags passed to the C compiler.  For instance on an x86
223 you may consider:
224
225         --enable-sim-cflags='-g0 -O2 -fno-strength-reduce -f...'
226
227
228
229 --enable-sim-warnings=<flags>
230
231
232 Turn on additional GCC specific checks.
233
234 Some hosts (NetBSD, Linux, Solaris-2.5) have complete header files
235 that include correct prototypes for all library functions.  On such
236 hosts, PSIM can be built with many more than the standard C checks
237 enabled.  The option --enable-sim-warnings controls this.
238
239 Ex: Default warnings
240
241 With just --enable-sim-warnings, the following -W options are enabled:
242 -Werror -Wall -Wpointer-arith -Wmissing-prototypes.
243
244
245
246 --enable-sim-opcode=which
247
248
249 Specify the file containing the rules for generating the instruction
250 decode and execute functions from the file ppc-instructions.
251
252 The form of the instruction decode and execute functions is controlled
253 by an opcode table.  It specifies: the combination of switch
254 statements and jump tables to use when decoding an instruction and how
255 much of each instruction should be decoded before calling the
256 instruction execute function.
257
258 PSIM includes a number of opcode tables:
259
260         psim-opcode-simple
261                 Generates a small compact two level switch statement
262                 that will compile quickly and run reasonably fast.
263
264                 This may be useful on a small machine.
265
266         psim-opcode-complex
267                 (the default) A fairly aggressive instruction decode
268                 table that includes the breaking out of a number
269                 of special instruction cases (eg RA==0 vs RA!=0).
270
271         psim-opcode-flat
272                 Identical to complex except a switch statement
273                 is used.  Ideal for when the icache is being
274                 disabled.
275
276         psim-opcode-stupid
277                 In addition to the instruction decodes performed
278                 by psim-opcode-complex, this also full decodes mtspr,
279                 mfspr, and branch instructions.  The table generated
280                 is very large and, as a consequence, only performs
281                 well on machines with large caches.
282
283         ppc-opcode-test-1
284         ppc-opcode-test-2
285                 Generate test (but workable) tables.  These exercise
286                 PSIM's ability to generate instruction decode functions
287                 that are a combination of jump-tables and switch statements.
288
289 The program igen generates the instruction tables from the opcode
290 table and the ppc-instruction table.
291
292
293
294 --enable-sim-switch
295
296
297 Enable/disable the use of a switch statement when looking up the
298 attributes of a SPR register.
299
300 The PowerPC architecture defines a number of Special Purpose Registers
301 (SPR's).  Associated with each of these registers are a number of
302 attributes (such as validity or size) which the instructions
303 mtspr/mfspr query as part of their execution.
304
305 For PSIM, this information is kept in a table (ppc-spr-table).  The
306 program dgen converts this table into lookup routines (contained in
307 the generated files spreg.h spreg.c) that can be used to query an
308 SPR's attributes.  Those lookup routines are either implemented as
309 a table or alternatively as a number of switch statements:
310
311         spr_table spr_info[] = { .... };
312         int spr_length(sprs spr) { return spr_info[spr].length; }
313
314 vs
315
316         int spr_length(sprs spr) { switch (spr) { case ..: return ..; } }
317
318 In general the first implementation (a table) is the most efficient.
319 It may, however, prove that when performing an aggressive optimization
320 where both the SPR is known and the above function is being inlined
321 (with the consequence that GCC can eliminate the switch statement)
322 that the second choice is improves performance.
323
324 In practice, only a marginal (if any benefit) has ever been seen.
325
326
327
328 --enable-sim-duplicate
329
330
331 Create a duplicate copy of each instruction function hardwiring
332 instruction fields that would have otherwise have been variable.
333
334 As discussed above, igen outputs a C function generated from the file
335 ppc-instructions (using the opcode rules) for each of the
336 instructions.  Thus multiple entries in the instruction decode tables
337 may be pointing back at the same function.  Enabling duplicate, will
338 result in psim creating a duplicate of the instruction's function for
339 each different entry in the instruction decode tables.
340
341 For instance, given the branch instruction:
342
343         0.19,6.BO,11.BI,16./,21.528,31.LK
344         ...
345         if (LK) LR = (spreg)IEA(CIA + 4);
346         ...
347
348 igen as part of its instruction lookup table may have generated two
349 different entries - one for LK=0 and one for LK=1.  With duplicate
350 enabled, igen outputs (almost) duplicate copies of branch function,
351 one with LK hardwired to 0 and one with LK hardwired to 1.
352
353 By doing this the compiler is provided with additional information that
354 will allow it possibly eliminate dead code.  (such as the assignment
355 to LK if LR==0).
356
357 Ex: default
358
359 Because this feature is such a big win, --enable-sim-duplicate is
360 turned on by default.
361
362 Ex: A small machine
363
364 Only rarely (eg on a very small host) would this feature need to be
365 disabled (using: --disable-sim-duplicate).
366
367
368
369 --enable-sim-filter=rule
370
371
372 Include/exclude PowerPC instructions that are specific to a particular
373 implementation.
374
375 Some of the PowerPC instructions included in the file ppc-instructions
376 are limited to certain specific PPC implementations.  For instance,
377 the instruction:
378
379         0.58,6.RT,11.RA,16.DS,30.2:DS:64::Load Word Algebraic
380
381 Is only valid for the 64bit architecture.  The enable-sim-filter flag
382 is passed to igen so that it can `filter out' any invalid
383 instructions.  The filter rule has the form:
384
385         -f <name>
386
387 thus:
388
389         --enable-sim-filter='-f 64'
390
391 (the default) would filter out all 64bit instructions.
392
393 Ex: Remove floating point instructions
394
395 A given 32bit PowerPC implementation may not include floating point
396 hardware.  Consequently there is little point in including floating
397 point instructions in the instruction table.  The option:
398
399         --enable-sim-filter='-f 64 -f f'
400
401 will eliminate all floating point instructions from the instruction
402 table.
403
404
405
406 --enable-sim-icache=size
407
408
409 Set the size of the cache used to hold decoded instructions.
410
411 Psim executes instructions in two separate steps:
412
413         o       instruction fetch/decode
414
415         o       instruction execution
416
417 For a given instruction, the first stage need only be executed once
418 (the first time the instruction is encountered) while the second stage
419 must be executed every time the program `executes' that instruction.
420
421 Exploiting this, PSIM can maintain a cache of decoded instructions.
422 It will then use the decoded instruction from the cache in preference
423 to fetching/decoding the real instruction from memory.
424
425 Ex: default
426
427 Because this feature is normally such a big win, it is enabled by
428 default (with the cache size set to 1024 entries).
429
430 The 1024 entries equals 4096 bytes (or one page) of instructions.
431 Larger caches can be used but with caution - PSIM does not check for
432 address aliasing within its instruction cache.
433
434 Ex: disable the cache
435
436 There may be cases (for instance where the cache has a low hit rate)
437 where the psim performs better with no instruction cache.  For such
438 situations, the cache can be disabled vis: --disable-sim-icache.
439
440
441
442 --enable-sim-inline[=module]
443
444
445 Specify the inlining of one or more modules.
446
447 Many architectures (in particular the x86) suffer from a large
448 function call overhead.  By eliminating function calls (through
449 inlining of functions) a large performance gain can be achieved.
450
451 In PSIM, modules are inlined in one of two possible ways.  Some
452 modules (such as the byte swapping code) can be inlined into any
453 module that calls them.  Other modules, due to complex
454 interdependencies, are only inlined as a group when compiling the
455 external interface module psim.c.
456
457 Ex: default
458
459 By default the modules endian (handle be/le), bits (manipulate
460 bit-fields within words), cpu (the processor object) and events
461 (timers) are inlined in any module that calls them.  This gives a
462 reasonable performance gain with little additional compilation
463 overhead.
464
465 Ex: recommended  --enable-sim-inline
466
467 Assuming you machine is reasonably well configured, this option is
468 highly recommended.  On the x86 several orders of magnitude
469 improvement in performance is possible.
470
471 Ex: fine tuning
472
473 The file std-config.h contains a detailed description of how the
474 inlining works.  Individual modules can be inlined by specifying them.
475 For if you have a very large cache the model module could be inlined
476 with:
477
478         --enable-sim-inline=MODEL
479
480
481
482 --enable-sim-bswap
483
484
485 (x86 specific) Use the i486/P5/P6 byte swap instruction.
486
487 PSIM contains generic byte swapping code.  For the x86 (P[4-6]) PSIM
488 can be built so that it uses the bswap instruction instead of relying
489 on the compiler to generate byte swap code.
490
491 Ex: default
492
493 By default, when compiling with GCC-2 on an i486/P5/P6 the bswap
494 instruction is used.
495
496
497
498 --enable-sim-endian=endian
499
500
501 Specify the byte order of the target.
502
503 By default, PSIM is able to execute both big and little endian
504 executables.  As a consequence, every byte swap routine includes a
505 test to see if the byte swap is really needed.  By specifying the byte
506 order of the target (and the host below) the need for this test can be
507 eliminated.
508
509 Clearly setting the byte order of the target is only useful when known
510 before hand.
511
512
513
514 --enable-sim-hostendain=end
515
516
517 As above but for the host.
518
519 Normally this option should not be needed. configure (autoconf) should
520 determine the byte order of the host automatically.  However if for
521 some reason there is a problem, this option can be used to override
522 autoconf.
523
524
525
526 --enable-sim-smp=n
527
528
529 Set the maximum number of processors that PSIM can model.
530
531 Psim can model (with small limitation discussed else where) a
532 multi-processor PowerPC environment.  While the overhead of
533 co-ordinating the execution of a number of processors is relatively
534 small it is still significant when compared to handling only one
535 processor.
536
537 This option only sets the maximum number of processors that can be
538 simulated.  The number active during a given simulation run us
539 determined at run time.
540
541 Ex: default
542
543 By default 5 processors are configured but only one is enabled.
544 Additional processors can be enabled with the runtime option:
545
546         -o '/openprom/options/smp 5'
547
548 Ex: recommended
549
550 Unless you intend studying multi-processor systems there is little reason for having PSIM configured with SMP support.  Specifying:
551
552         --disable-sim-smp
553 or      --enable-sim-smp=0
554
555 will eliminate any SMP such as:
556
557         for (cpu = 0; cpu < nr_cpus; cpu++)
558                 ...
559
560
561
562 --enable-sim-xor-endian=n
563
564
565 Set the byte-size of the bus involved in the PowerPC's xor endian byte
566 swapping.
567
568 The PowerPC's implementation of BE/LE mode is different to what a
569 programmer may first expect.  The details of this implementation are
570 discussed at length in PowerPC documentation.
571
572 Ex: default
573
574 By default this is configured with a value of 8 (the bus size of most
575 60x processors).
576
577 Ex: recommended
578
579 Unless you are expecting to test/debug PowerPC be/le switching code
580 this option is of little use and should be disabled:
581
582         --disable-sim-xor-endian
583
584
585
586 --enable-sim-bitsize=n
587
588
589 Specify the bit size (32/64) of the PowerPC to be modelled.
590
591 Note: By default 32 is specified.  The implementation of the 64bit
592 architecture is still under development.
593
594
595 --enable-sim-hostbitsize=32|64
596
597 As above but for the host.
598
599 NOTE: Psim has yet to be built on a 64bit host.
600
601
602
603 --enable-sim-env=env
604
605
606 Hardwire the PowerPC environment being modelled (user, virtual or
607 operating).
608
609 The PowerPC architecture defines three different levels of compliance
610 to its architectural specification.  These environments are discussed in detail in PowerPC publications.
611
612         user - normal user programs 
613         virtual - an extension of the user environment (includes timers)
614         operating - kernel code
615
616 Ex: default
617
618 By default all three environments are supported.
619
620 Ex: recommended
621
622 If you only intend running psim with user (or operating) code then
623 PSIM should be configured accordingly.  For user code, it eliminates:
624 support for timers and events and redundant VM calls.
625
626
627
628 --enable-sim-timebase
629
630
631 Enable/disable the time base register.
632
633 The PowerPC architecture (virtual environment) includes a time base
634 register.  Maintaining that register incurs an overhead in
635 performance that can be eliminated by eliminating time-base register
636 support.
637
638 Ex: default
639
640 Normally this option is not used.  Instead --enable-sim-env (above) us
641 used to disable/enable features such as the timebase register.
642
643
644
645 --enable-sim-alignment=align
646
647
648 Control the PowerPC's memory access alignment restrictions.
649
650 The PowerPC in LE mode only allows memory transfers of a correctly
651 aligned size/address.  The above option controls how misaligned
652 accesses are handled.
653
654         strict          All accesses must be correctly aligned
655
656         nonstrict       Unaligned access allowed (the are split
657                         into a number of aligned accesses).
658
659 Ex: default
660
661 Unless otherwise specified PSIM will auto configure a BE program to
662 allow miss-aligned accesses while a LE program will not.
663
664 Ex: 604e
665
666 The recently announced 604e processor allows miss-aligned accesses in both
667 BE and LE modes.  If modeling the 604e then you should specify:
668
669         --enable-sim-alignment=nonstrict
670
671
672
673 --enable-sim-trace
674
675
676 Include code to trace PSIM's internal progress (also controlled by the
677 -t option).
678
679 Checking to see if a trace message should be output slows down a
680 simulation.  Disabling this option (--disable-sim-trace) eliminates
681 completely that code.
682
683
684
685 --enable-sim-assert
686
687
688 Include the code that checks the correctness of parts of PSIM.
689
690 Eliminating such code (--disable-sim-assert) eliminates internal
691 consistency tests and their overhead.
692
693
694
695 --enable-sim-reserved-bits
696
697
698 Include code to check that the reserved fields of the instruction are
699 zero.
700
701 The PowerPC architecture defines certain fields of some instructions
702 as reserved (`/').  By default, for each instruction, PSIM will check
703 the reserved fields causing an invalid instruction exception if a
704 field is invalid.  Disabling this option eliminates this test.  This
705 is at the slight risk of PSIM treating an invalid instruction as
706 valid.
707
708
709
710 --enable-sim-float
711
712
713 Include support for hardware floating point.
714
715
716
717 --enable-sim-monitor=mon
718
719
720 Include support for basic instruction counting.
721
722 If you are not interested in the performance of either you program or
723 the simulator then you can disable this option.
724
725
726
727 --enable-sim-model=which
728
729 Hardwire the processor that will be used as a reference when modeling
730 execution units.
731
732
733
734 --enable-sim-default-model=which
735
736
737 Specify the processor of choice for the execution unit model.
738
739
740
741 --enable-sim-model-issue
742
743
744 Include support for the modeling of processor execution units.
745
746     ----------------------------------------------------------------------
747
748 TYPICAL CONFIGURATION OPTIONS:
749
750
751         VEA CODE ONLY:
752
753         Here of note are:
754
755                 o       ramp up the compiler options (some
756                         of the below are P5 specific).
757
758                 o       disable anything not used
759
760         CC=gcc ./configure \
761                 --prefix=/applications/psim \
762                 --target=powerpc-unknown-eabi \
763                 --enable-sim-powerpc \
764                 --enable-sim-warnings \
765                 --enable-sim-inline \
766                 --disable-sim-smp \
767                 --enable-sim-bswap \
768                 --enable-sim-duplicate \
769                 --enable-sim-endian=big \
770                 --disable-sim-xor-endian \
771                 --enable-sim-env=user \
772                 --disable-sim-reserved-bits \
773                 --disable-sim-assert \
774                 --disable-sim-trace \
775                 --enable-sim-cflags='-g0 -O2 -fno-strength-reduce -fomit-frame-pointer -malign-loops=2 -malign-jumps=2 -malign-functions=2'
776
777
778         OEA CODE ONLY:
779
780         The key configuration changes are:
781
782                 o       turn off the instruction cache.  The overhead
783                         of flushing and reloading it is greater than
784                         not having a cache.
785
786                 o       use a switch statement (ppc-opcode-flat) for
787                         the instruction decode and then (-O3) fully
788                         inline all functions.
789
790                 o       --enable-sim-warnings is not present.  GCC (2.7.2)
791                         gets confused by the instruction decode table
792                         generated by igen (contains a perfect switch)
793                         and, as a consequence, generates a bogus warning.
794
795         CC=gcc ./configure \
796                 --prefix=/applications/psim \
797                 --target=powerpc-unknown-eabi \
798                 --enable-sim-powerpc \
799                 --enable-sim-inline \
800                 --disable-sim-smp \
801                 --enable-sim-bswap \
802                 --enable-sim-duplicate \
803                 --enable-sim-endian=big \
804                 --disable-sim-xor-endian \
805                 --enable-sim-env=operating \
806                 --disable-sim-reserved-bits \
807                 --disable-sim-assert \
808                 --disable-sim-trace \
809                 --enable-sim-opcode=ppc-opcode-flat \
810                 --disable-sim-icache \
811                 --enable-sim-cflags='-g0 -O3 -fno-strength-reduce -fomit-frame-pointer -malign-loops=2 -malign-jumps=2 -malign-functions=2'