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-endian=endian
 484
 485
 486 Specify the byte order of the target.
 487
 488 By default, PSIM is able to execute both big and little endian
 489 executables.  As a consequence, every byte swap routine includes a
 490 test to see if the byte swap is really needed.  By specifying the byte
 491 order of the target (and the host below) the need for this test can be
 492 eliminated.
 493
 494 Clearly setting the byte order of the target is only useful when known
 495 before hand.
 496
 497
 498
 499 --enable-sim-hostendain=end
 500
 501
 502 As above but for the host.
 503
 504 Normally this option should not be needed. configure (autoconf) should
 505 determine the byte order of the host automatically.  However if for
 506 some reason there is a problem, this option can be used to override
 507 autoconf.
 508
 509
 510
 511 --enable-sim-smp=n
 512
 513
 514 Set the maximum number of processors that PSIM can model.
 515
 516 Psim can model (with small limitation discussed else where) a
 517 multi-processor PowerPC environment.  While the overhead of
 518 co-ordinating the execution of a number of processors is relatively
 519 small it is still significant when compared to handling only one
 520 processor.
 521
 522 This option only sets the maximum number of processors that can be
 523 simulated.  The number active during a given simulation run us
 524 determined at run time.
 525
 526 Ex: default
 527
 528 By default 5 processors are configured but only one is enabled.
 529 Additional processors can be enabled with the runtime option:
 530
 531         -o '/openprom/options/smp 5'
 532
 533 Ex: recommended
 534
 535 Unless you intend studying multi-processor systems there is little reason for
 536 having PSIM configured with SMP support.  Specifying:
 537
 538         --disable-sim-smp
 539 or      --enable-sim-smp=0
 540
 541 will eliminate any SMP such as:
 542
 543         for (cpu = 0; cpu < nr_cpus; cpu++)
 544                 ...
 545
 546
 547
 548 --enable-sim-xor-endian=n
 549
 550
 551 Set the byte-size of the bus involved in the PowerPC's xor endian byte
 552 swapping.
 553
 554 The PowerPC's implementation of BE/LE mode is different to what a
 555 programmer may first expect.  The details of this implementation are
 556 discussed at length in PowerPC documentation.
 557
 558 Ex: default
 559
 560 By default this is configured with a value of 8 (the bus size of most
 561 60x processors).
 562
 563 Ex: recommended
 564
 565 Unless you are expecting to test/debug PowerPC be/le switching code
 566 this option is of little use and should be disabled:
 567
 568         --disable-sim-xor-endian
 569
 570
 571
 572 --enable-sim-bitsize=n
 573
 574
 575 Specify the bit size (32/64) of the PowerPC to be modelled.
 576
 577 Note: By default 32 is specified.  The implementation of the 64bit
 578 architecture is still under development.
 579
 580
 581 --enable-sim-hostbitsize=32|64
 582
 583 As above but for the host.
 584
 585 NOTE: Psim has yet to be built on a 64bit host.
 586
 587
 588
 589 --enable-sim-env=env
 590
 591
 592 Hardwire the PowerPC environment being modelled (user, virtual or
 593 operating).
 594
 595 The PowerPC architecture defines three different levels of compliance to its
 596 architectural specification.  These environments are discussed in detail in
 597 PowerPC publications.
 598
 599         user - normal user programs
 600         virtual - an extension of the user environment (includes timers)
 601         operating - kernel code
 602
 603 Ex: default
 604
 605 By default all three environments are supported.
 606
 607 Ex: recommended
 608
 609 If you only intend running psim with user (or operating) code then
 610 PSIM should be configured accordingly.  For user code, it eliminates:
 611 support for timers and events and redundant VM calls.
 612
 613
 614
 615 --enable-sim-timebase
 616
 617
 618 Enable/disable the time base register.
 619
 620 The PowerPC architecture (virtual environment) includes a time base
 621 register.  Maintaining that register incurs an overhead in
 622 performance that can be eliminated by eliminating time-base register
 623 support.
 624
 625 Ex: default
 626
 627 Normally this option is not used.  Instead --enable-sim-env (above) us
 628 used to disable/enable features such as the timebase register.
 629
 630
 631
 632 --enable-sim-alignment=align
 633
 634
 635 Control the PowerPC's memory access alignment restrictions.
 636
 637 The PowerPC in LE mode only allows memory transfers of a correctly
 638 aligned size/address.  The above option controls how misaligned
 639 accesses are handled.
 640
 641         strict          All accesses must be correctly aligned
 642
 643         nonstrict       Unaligned access allowed (the are split
 644                         into a number of aligned accesses).
 645
 646 Ex: default
 647
 648 Unless otherwise specified PSIM will auto configure a BE program to
 649 allow miss-aligned accesses while a LE program will not.
 650
 651 Ex: 604e
 652
 653 The recently announced 604e processor allows miss-aligned accesses in both
 654 BE and LE modes.  If modeling the 604e then you should specify:
 655
 656         --enable-sim-alignment=nonstrict
 657
 658
 659
 660 --enable-sim-trace
 661
 662
 663 Include code to trace PSIM's internal progress (also controlled by the
 664 -t option).
 665
 666 Checking to see if a trace message should be output slows down a
 667 simulation.  Disabling this option (--disable-sim-trace) eliminates
 668 completely that code.
 669
 670
 671
 672 --enable-sim-assert
 673
 674
 675 Include the code that checks the correctness of parts of PSIM.
 676
 677 Eliminating such code (--disable-sim-assert) eliminates internal
 678 consistency tests and their overhead.
 679
 680
 681
 682 --enable-sim-reserved-bits
 683
 684
 685 Include code to check that the reserved fields of the instruction are
 686 zero.
 687
 688 The PowerPC architecture defines certain fields of some instructions
 689 as reserved (`/').  By default, for each instruction, PSIM will check
 690 the reserved fields causing an invalid instruction exception if a
 691 field is invalid.  Disabling this option eliminates this test.  This
 692 is at the slight risk of PSIM treating an invalid instruction as
 693 valid.
 694
 695
 696
 697 --enable-sim-float
 698
 699
 700 Include support for hardware floating point.
 701
 702
 703
 704 --enable-sim-monitor=mon
 705
 706
 707 Include support for basic instruction counting.
 708
 709 If you are not interested in the performance of either you program or
 710 the simulator then you can disable this option.
 711
 712
 713
 714 --enable-sim-model=which
 715
 716 Hardwire the processor that will be used as a reference when modeling
 717 execution units.
 718
 719
 720
 721 --enable-sim-default-model=which
 722
 723
 724 Specify the processor of choice for the execution unit model.
 725
 726
 727
 728 --enable-sim-model-issue
 729
 730
 731 Include support for the modeling of processor execution units.
 732
 733     ----------------------------------------------------------------------
 734
 735 TYPICAL CONFIGURATION OPTIONS:
 736
 737
 738         VEA CODE ONLY:
 739
 740         Here of note are:
 741
 742                 o       ramp up the compiler options (some
 743                         of the below are P5 specific).
 744
 745                 o       disable anything not used
 746
 747         CC=gcc ./configure \
 748                 --prefix=/applications/psim \
 749                 --target=powerpc-unknown-eabi \
 750                 --enable-sim-powerpc \
 751                 --enable-sim-warnings \
 752                 --enable-sim-inline \
 753                 --disable-sim-smp \
 754                 --enable-sim-duplicate \
 755                 --enable-sim-endian=big \
 756                 --disable-sim-xor-endian \
 757                 --enable-sim-env=user \
 758                 --disable-sim-reserved-bits \
 759                 --disable-sim-assert \
 760                 --disable-sim-trace \
 761                 --enable-sim-cflags='-g0,-O2,-fno-strength-reduce,-fomit-frame-pointer'
 762
 763
 764         OEA CODE ONLY:
 765
 766         The key configuration changes are:
 767
 768                 o       turn off the instruction cache.  The overhead
 769                         of flushing and reloading it is greater than
 770                         not having a cache.
 771
 772                 o       use a switch statement (ppc-opcode-flat) for
 773                         the instruction decode and then (-O3) fully
 774                         inline all functions.
 775
 776                 o       --enable-sim-warnings is not present.  GCC (2.7.2)
 777                         gets confused by the instruction decode table
 778                         generated by igen (contains a perfect switch)
 779                         and, as a consequence, generates a bogus warning.
 780
 781         CC=gcc ./configure \
 782                 --prefix=/applications/psim \
 783                 --target=powerpc-unknown-eabi \
 784                 --enable-sim-powerpc \
 785                 --enable-sim-inline \
 786                 --disable-sim-smp \
 787                 --enable-sim-duplicate \
 788                 --enable-sim-endian=big \
 789                 --disable-sim-xor-endian \
 790                 --enable-sim-env=operating \
 791                 --disable-sim-reserved-bits \
 792                 --disable-sim-assert \
 793                 --disable-sim-trace \
 794                 --enable-sim-opcode=ppc-opcode-flat \
 795                 --disable-sim-icache \
 796                 --enable-sim-cflags='-g0,-O3,-fno-strength-reduce,-fomit-frame-pointer'