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