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 25BUILDING PSIM: 26 27PSIM 1.0.2 is included in GDB-4.16. To build PSIM you will need the 28following: 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 39Method: 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 89UPDATING PSIM: 90 91 92A PSIM is an ongoing development. Occasional snapshots which both contain new 93features and fix old bugs are made available. See the ftp directory: 94 95 ftp://ftp.ci.com.au/pub/psim/beta 96or ftp://cambridge.cygnus.com/pub/psim/beta 97 98for the latest version. To build/install one of these snapshots, you 99replace the sim/ppc found in the gdb archive with with one from the 100snapshot. 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 132UPDATES TO GDB: 133 134From time to time, problems involving the integration of PSIM into gdb 135are found. While eventually each of these problems is resolved there 136can be periouds during which a local hack may be needed. 137 138At 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 160RUNNING PROGRAMS: 161 162 163See the file: 164 165 ftp://ftp.ci.com.au/pub/psim/RUN 166or ftp://cambridge.cygnus.com/pub/psim/RUN 167 168 169 ---------------------------------------------------------------------- 170 171 172COMPILE TIME CONFIGURATION OPTIONS: 173 174 175PSIM's compile time configuration is controlled by autoconf. PSIM's 176configure script recognises options of the form: 177 178 --enable-sim-<option>[=<val>] 179 180And can be specified on the configure command line (at the top level 181of 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 190For a brief list of PSIM's configuration options, configure --help 191will list them vis: 192 193 $ cd sim/ppc 194 $ ./configure --help 195 196Each PSIM specific option is discussed in detail below. 197 198 199 200--enable-sim-cflags=<opts> 201 202 203Specify additional C compiler flags that are to be used when compiling 204just PSIM. 205 206PSIM places heavy demands on both the host machine and its C compiler. So that 207the builder has better control over the compiler the above option can be used 208to pass additional options to the compiler while PSIM is being built. 209 210Ex: No debug information 211 212PSIM can be built with everything inline. Unfortunately, because of 213all the debugging information generated the C compiler can grow very 214very large as a result. For GCC, the debug information can be 215restricted with the `-g0' option. To specify that this option should 216be include in the CFLAGS when compiling the psim source code use: 217 218 --enable-sim-cflags=-g0 219 220Ex: Additional optimization flags 221 222A significant gain in performance can be achieved by tuning the 223optimization flags passed to the C compiler. For instance on an x86 224you may consider: 225 226 --enable-sim-cflags='-g0 -O2 -fno-strength-reduce -f...' 227 228 229 230--enable-sim-warnings=<flags> 231 232 233Turn on additional GCC specific checks. 234 235Some hosts (NetBSD, Linux, Solaris-2.5) have complete header files 236that include correct prototypes for all library functions. On such 237hosts, PSIM can be built with many more than the standard C checks 238enabled. The option --enable-sim-warnings controls this. 239 240Ex: Default warnings 241 242With 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 250Specify the file containing the rules for generating the instruction 251decode and execute functions from the file ppc-instructions. 252 253The form of the instruction decode and execute functions is controlled 254by an opcode table. It specifies: the combination of switch 255statements and jump tables to use when decoding an instruction and how 256much of each instruction should be decoded before calling the 257instruction execute function. 258 259PSIM 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 290The program igen generates the instruction tables from the opcode 291table and the ppc-instruction table. 292 293 294 295--enable-sim-switch 296 297 298Enable/disable the use of a switch statement when looking up the 299attributes of a SPR register. 300 301The PowerPC architecture defines a number of Special Purpose Registers 302(SPR's). Associated with each of these registers are a number of 303attributes (such as validity or size) which the instructions 304mtspr/mfspr query as part of their execution. 305 306For PSIM, this information is kept in a table (ppc-spr-table). The 307program dgen converts this table into lookup routines (contained in 308the generated files spreg.h spreg.c) that can be used to query an 309SPR's attributes. Those lookup routines are either implemented as 310a 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 315vs 316 317 int spr_length(sprs spr) { switch (spr) { case ..: return ..; } } 318 319In general the first implementation (a table) is the most efficient. 320It may, however, prove that when performing an aggressive optimization 321where both the SPR is known and the above function is being inlined 322(with the consequence that GCC can eliminate the switch statement) 323that the second choice is improves performance. 324 325In practice, only a marginal (if any benefit) has ever been seen. 326 327 328 329--enable-sim-duplicate 330 331 332Create a duplicate copy of each instruction function hardwiring 333instruction fields that would have otherwise have been variable. 334 335As discussed above, igen outputs a C function generated from the file 336ppc-instructions (using the opcode rules) for each of the 337instructions. Thus multiple entries in the instruction decode tables 338may be pointing back at the same function. Enabling duplicate, will 339result in psim creating a duplicate of the instruction's function for 340each different entry in the instruction decode tables. 341 342For 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 349igen as part of its instruction lookup table may have generated two 350different entries - one for LK=0 and one for LK=1. With duplicate 351enabled, igen outputs (almost) duplicate copies of branch function, 352one with LK hardwired to 0 and one with LK hardwired to 1. 353 354By doing this the compiler is provided with additional information that 355will allow it possibly eliminate dead code. (such as the assignment 356to LK if LR==0). 357 358Ex: default 359 360Because this feature is such a big win, --enable-sim-duplicate is 361turned on by default. 362 363Ex: A small machine 364 365Only rarely (eg on a very small host) would this feature need to be 366disabled (using: --disable-sim-duplicate). 367 368 369 370--enable-sim-filter=rule 371 372 373Include/exclude PowerPC instructions that are specific to a particular 374implementation. 375 376Some of the PowerPC instructions included in the file ppc-instructions 377are limited to certain specific PPC implementations. For instance, 378the instruction: 379 380 0.58,6.RT,11.RA,16.DS,30.2:DS:64::Load Word Algebraic 381 382Is only valid for the 64bit architecture. The enable-sim-filter flag 383is passed to igen so that it can `filter out' any invalid 384instructions. The filter rule has the form: 385 386 -f <name> 387 388thus: 389 390 --enable-sim-filter='-f 64' 391 392(the default) would filter out all 64bit instructions. 393 394Ex: Remove floating point instructions 395 396A given 32bit PowerPC implementation may not include floating point 397hardware. Consequently there is little point in including floating 398point instructions in the instruction table. The option: 399 400 --enable-sim-filter='-f 64 -f f' 401 402will eliminate all floating point instructions from the instruction 403table. 404 405 406 407--enable-sim-icache=size 408 409 410Set the size of the cache used to hold decoded instructions. 411 412Psim executes instructions in two separate steps: 413 414 o instruction fetch/decode 415 416 o instruction execution 417 418For a given instruction, the first stage need only be executed once 419(the first time the instruction is encountered) while the second stage 420must be executed every time the program `executes' that instruction. 421 422Exploiting this, PSIM can maintain a cache of decoded instructions. 423It will then use the decoded instruction from the cache in preference 424to fetching/decoding the real instruction from memory. 425 426Ex: default 427 428Because this feature is normally such a big win, it is enabled by 429default (with the cache size set to 1024 entries). 430 431The 1024 entries equals 4096 bytes (or one page) of instructions. 432Larger caches can be used but with caution - PSIM does not check for 433address aliasing within its instruction cache. 434 435Ex: disable the cache 436 437There may be cases (for instance where the cache has a low hit rate) 438where the psim performs better with no instruction cache. For such 439situations, the cache can be disabled vis: --disable-sim-icache. 440 441 442 443--enable-sim-inline[=module] 444 445 446Specify the inlining of one or more modules. 447 448Many architectures (in particular the x86) suffer from a large 449function call overhead. By eliminating function calls (through 450inlining of functions) a large performance gain can be achieved. 451 452In PSIM, modules are inlined in one of two possible ways. Some 453modules (such as the byte swapping code) can be inlined into any 454module that calls them. Other modules, due to complex 455interdependencies, are only inlined as a group when compiling the 456external interface module psim.c. 457 458Ex: default 459 460By default the modules endian (handle be/le), bits (manipulate 461bit-fields within words), cpu (the processor object) and events 462(timers) are inlined in any module that calls them. This gives a 463reasonable performance gain with little additional compilation 464overhead. 465 466Ex: recommended --enable-sim-inline 467 468Assuming you machine is reasonably well configured, this option is 469highly recommended. On the x86 several orders of magnitude 470improvement in performance is possible. 471 472Ex: fine tuning 473 474The file std-config.h contains a detailed description of how the 475inlining works. Individual modules can be inlined by specifying them. 476For if you have a very large cache the model module could be inlined 477with: 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 488PSIM contains generic byte swapping code. For the x86 (P[4-6]) PSIM 489can be built so that it uses the bswap instruction instead of relying 490on the compiler to generate byte swap code. 491 492Ex: default 493 494By default, when compiling with GCC-2 on an i486/P5/P6 the bswap 495instruction is used. 496 497 498 499--enable-sim-endian=endian 500 501 502Specify the byte order of the target. 503 504By default, PSIM is able to execute both big and little endian 505executables. As a consequence, every byte swap routine includes a 506test to see if the byte swap is really needed. By specifying the byte 507order of the target (and the host below) the need for this test can be 508eliminated. 509 510Clearly setting the byte order of the target is only useful when known 511before hand. 512 513 514 515--enable-sim-hostendain=end 516 517 518As above but for the host. 519 520Normally this option should not be needed. configure (autoconf) should 521determine the byte order of the host automatically. However if for 522some reason there is a problem, this option can be used to override 523autoconf. 524 525 526 527--enable-sim-smp=n 528 529 530Set the maximum number of processors that PSIM can model. 531 532Psim can model (with small limitation discussed else where) a 533multi-processor PowerPC environment. While the overhead of 534co-ordinating the execution of a number of processors is relatively 535small it is still significant when compared to handling only one 536processor. 537 538This option only sets the maximum number of processors that can be 539simulated. The number active during a given simulation run us 540determined at run time. 541 542Ex: default 543 544By default 5 processors are configured but only one is enabled. 545Additional processors can be enabled with the runtime option: 546 547 -o '/openprom/options/smp 5' 548 549Ex: recommended 550 551Unless you intend studying multi-processor systems there is little reason for 552having PSIM configured with SMP support. Specifying: 553 554 --disable-sim-smp 555or --enable-sim-smp=0 556 557will 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 567Set the byte-size of the bus involved in the PowerPC's xor endian byte 568swapping. 569 570The PowerPC's implementation of BE/LE mode is different to what a 571programmer may first expect. The details of this implementation are 572discussed at length in PowerPC documentation. 573 574Ex: default 575 576By default this is configured with a value of 8 (the bus size of most 57760x processors). 578 579Ex: recommended 580 581Unless you are expecting to test/debug PowerPC be/le switching code 582this 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 591Specify the bit size (32/64) of the PowerPC to be modelled. 592 593Note: By default 32 is specified. The implementation of the 64bit 594architecture is still under development. 595 596 597--enable-sim-hostbitsize=32|64 598 599As above but for the host. 600 601NOTE: Psim has yet to be built on a 64bit host. 602 603 604 605--enable-sim-env=env 606 607 608Hardwire the PowerPC environment being modelled (user, virtual or 609operating). 610 611The PowerPC architecture defines three different levels of compliance to its 612architectural specification. These environments are discussed in detail in 613PowerPC publications. 614 615 user - normal user programs 616 virtual - an extension of the user environment (includes timers) 617 operating - kernel code 618 619Ex: default 620 621By default all three environments are supported. 622 623Ex: recommended 624 625If you only intend running psim with user (or operating) code then 626PSIM should be configured accordingly. For user code, it eliminates: 627support for timers and events and redundant VM calls. 628 629 630 631--enable-sim-timebase 632 633 634Enable/disable the time base register. 635 636The PowerPC architecture (virtual environment) includes a time base 637register. Maintaining that register incurs an overhead in 638performance that can be eliminated by eliminating time-base register 639support. 640 641Ex: default 642 643Normally this option is not used. Instead --enable-sim-env (above) us 644used to disable/enable features such as the timebase register. 645 646 647 648--enable-sim-alignment=align 649 650 651Control the PowerPC's memory access alignment restrictions. 652 653The PowerPC in LE mode only allows memory transfers of a correctly 654aligned size/address. The above option controls how misaligned 655accesses 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 662Ex: default 663 664Unless otherwise specified PSIM will auto configure a BE program to 665allow miss-aligned accesses while a LE program will not. 666 667Ex: 604e 668 669The recently announced 604e processor allows miss-aligned accesses in both 670BE 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 679Include code to trace PSIM's internal progress (also controlled by the 680-t option). 681 682Checking to see if a trace message should be output slows down a 683simulation. Disabling this option (--disable-sim-trace) eliminates 684completely that code. 685 686 687 688--enable-sim-assert 689 690 691Include the code that checks the correctness of parts of PSIM. 692 693Eliminating such code (--disable-sim-assert) eliminates internal 694consistency tests and their overhead. 695 696 697 698--enable-sim-reserved-bits 699 700 701Include code to check that the reserved fields of the instruction are 702zero. 703 704The PowerPC architecture defines certain fields of some instructions 705as reserved (`/'). By default, for each instruction, PSIM will check 706the reserved fields causing an invalid instruction exception if a 707field is invalid. Disabling this option eliminates this test. This 708is at the slight risk of PSIM treating an invalid instruction as 709valid. 710 711 712 713--enable-sim-float 714 715 716Include support for hardware floating point. 717 718 719 720--enable-sim-monitor=mon 721 722 723Include support for basic instruction counting. 724 725If you are not interested in the performance of either you program or 726the simulator then you can disable this option. 727 728 729 730--enable-sim-model=which 731 732Hardwire the processor that will be used as a reference when modeling 733execution units. 734 735 736 737--enable-sim-default-model=which 738 739 740Specify the processor of choice for the execution unit model. 741 742 743 744--enable-sim-model-issue 745 746 747Include support for the modeling of processor execution units. 748 749 ---------------------------------------------------------------------- 750 751TYPICAL 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' 813