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