sim/ppc/README.psim

   1
   2                 PSIM - model a PowerPC platform
   3
   4     Copyright (C) 1994-1995, Andrew Cagney <cagney@highland.com.au>.
   5
   6     This program is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10
  11     This program is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with this program; if not, write to the Free Software
  18     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  19
  20
  21 This directory contains the source code to the program PSIM.
  22
  23
  24 What is PSIM?
  25
  26         PSIM is an ANSI C program that implements an instruction
  27         level model of the PowerPC architecture.
  28
  29         It can be configured to model various PowerPC platforms
  30         and include:
  31
  32                 o       A user program environment (UEA) complete
  33                         with emulated system calls
  34
  35         to
  36
  37                 o       A hardware platform with several processors
  38                         interacting with each other and various
  39                         modeled hardware devices.
  40
  41         For each of these models PSIM is able perform a detailed
  42         analysis of the machines performance.
  43
  44
  45
  46 Who would be interested in PSIM?
  47
  48         o       the curious
  49
  50                 Using psim, gdb, gcc and binutils the curious
  51                 user can contruct an environment that allows
  52                 them to play with PowerPC user programs with out
  53                 the need for real hardware.
  54
  55
  56         o       the analyst
  57
  58                 PSIM includes many (contributed) monitoring
  59                 features which (unlike many other simulators)
  60                 do not come with a great penalty in performance.
  61
  62                 Thus the performance analyst is able to use
  63                 this simulator to model the inpact of changes
  64                 to the system they are analysing.  Be that
  65                 system a compiler or real hardware platform.
  66
  67                 If PSIM doesn't monitor a components of interest,
  68                 the source code is freely available, and hence
  69                 there is no hinderance to changing things
  70                 to meet a specific analysts needs.
  71
  72
  73         o       the serious SW developer
  74
  75                 PSIM models all three levels of the PowerPC
  76                 Architecture: UEA, VEA and OEA.  Further,
  77                 the internal design is such that PSIM can
  78                 be extended to suport additional
  79                 development requirements.  Such requirements
  80                 might include (for the UEA) a new Operating
  81                 System emulation through to (for the OEA)
  82                 a model of a different hardware platform.
  83
  84
  85 What features does PSIM have?
  86
  87
  88         Monitoring and modeling
  89
  90                 PSIM includes (thanks to Michael Meissner)
  91                 a detailed model of the various PowerPC
  92                 implementations schedulers.
  93
  94
  95         SMP
  96
  97                 The PowerPC ISA defines SMP synchronizing instructions
  98                 this simulator models a limited subset of their
  99                 behavor.  Consequently, if you limit code to the
 100                 use the modeled behavour, PSIM can be used to
 101                 model SMP PowerPC platforms.
 102
 103                 People intending to use this system should study
 104                 the code implementing the lwarx etc instructions.
 105
 106         ENDIAN SUPORT
 107
 108                 PSIM implements the PowerPC's big and little (xor
 109                 endian) modes and correctly simulates code that
 110                 switches between these two modes.
 111
 112                 In addition, psim can model a true little-endian
 113                 machine.
 114
 115         ISA models (Instruction Set Architecture)
 116
 117                 PSIM includes a model of the UEA, VEA and OEA.  This
 118                 inclues the time base registers (VEA) and HTAB
 119                 and BATS (OEA).
 120
 121                 In addition, a preliminary model of the 64 bit
 122                 PowerPC architecture is implemented.
 123
 124         Hardware
 125
 126                 PSIM's internals are based around the concept
 127                 of a Device Tree.  This tree intentionaly
 128                 resembles that of the Device Tree found in
 129                 OpenBoot firmware.  PSIM is flexable enough
 130                 to allow the user to fully configure the
 131                 actual hardware model from a device tree
 132                 specification that is read in from a file.
 133
 134                 A user can either run a program using one of
 135                 PSIM's built in hardware models specify a
 136                 custom hardware model that should be simulated.
 137
 138                 A user is also able to quickly add a model
 139                 of new hardware devices so that they can be
 140                 included in a custom hardware model.
 141
 142         OS-Emulation
 143
 144                 PSIM's UEA model includes emulation for UNIX system
 145                 calls.
 146
 147                 PSIM's OEA model includes emulation of either:
 148
 149                         o       OpenBoot client interface
 150
 151                         o       MOTO's BUG interface.
 152
 153
 154         Floating point
 155
 156                 Preliminary suport for floating point is included.
 157
 158
 159
 160 What performance analysis measurements can PSIM perform?
 161
 162         Below is the output from a recent analysis run
 163         (contributed by Michael Meissner):
 164
 165         For the following program:
 166
 167         long
 168         simple_rand ()
 169         {
 170           static unsigned long seed = 47114711;
 171           unsigned long this = seed * 1103515245 + 12345;
 172           seed = this;
 173           return this >> 8;
 174         }
 175
 176         unsigned long int
 177         random_bitstring ()
 178         {
 179           unsigned long int x;
 180           int ran, n_bits;
 181           int tot_bits = 0;
 182
 183           x = 0;
 184           for (;;)
 185             {
 186               ran = simple_rand ();
 187               n_bits = (ran >> 1) % 16;
 188               tot_bits += n_bits;
 189
 190               if (n_bits == 0)
 191                 return x;
 192               else
 193                 {
 194                   x <<= n_bits;
 195                   if (ran & 1)
 196                     x |= (1 << n_bits) - 1;
 197
 198                   if (tot_bits > 8 * sizeof (long) + 6)
 199                     return x;
 200                 }
 201             }
 202         }
 203
 204         #define ABS(x) ((x) >= 0 ? (x) : -(x))
 205
 206         main ()
 207         {
 208           int i;
 209
 210           for (i = 0; i < 50000; i++)
 211             {
 212               unsigned long x, y;
 213               x = random_bitstring ();
 214               y = random_bitstring ();
 215
 216               if (sizeof (int) == sizeof (long))
 217                 goto save_time;
 218
 219               { unsigned long xx = x, yy = y, r1, r2;
 220                 if (yy == 0) continue;
 221                 r1 = xx / yy;
 222                 r2 = xx % yy;
 223                 if (r2 >= yy || r1 * yy + r2 != xx)
 224                   abort ();
 225               }
 226               { signed long xx = x, yy = y, r1, r2;
 227                 if ((unsigned long) xx << 1 == 0 && yy == -1)
 228                   continue;
 229                 r1 = xx / yy;
 230                 r2 = xx % yy;
 231                 if (ABS (r2) >= (unsigned long) ABS (yy) || (signed long) (r1 * yy + r2) != xx)
 232                   abort ();
 233               }
 234             save_time:
 235               { unsigned int xx = x, yy = y, r1, r2;
 236                 if (yy == 0) continue;
 237                 r1 = xx / yy;
 238                 r2 = xx % yy;
 239                 if (r2 >= yy || r1 * yy + r2 != xx)
 240                   abort ();
 241               }
 242               { signed int xx = x, yy = y, r1, r2;
 243                 if ((unsigned int) xx << 1 == 0 && yy == -1)
 244                   continue;
 245                 r1 = xx / yy;
 246                 r2 = xx % yy;
 247                 if (ABS (r2) >= (unsigned int) ABS (yy) || (signed int) (r1 * yy + r2) != xx)
 248                   abort ();
 249               }
 250               { unsigned short xx = x, yy = y, r1, r2;
 251                 if (yy == 0) continue;
 252                 r1 = xx / yy;
 253                 r2 = xx % yy;
 254                 if (r2 >= yy || r1 * yy + r2 != xx)
 255                   abort ();
 256               }
 257               { signed short xx = x, yy = y, r1, r2;
 258                 r1 = xx / yy;
 259                 r2 = xx % yy;
 260                 if (ABS (r2) >= (unsigned short) ABS (yy) || (signed short) (r1 * yy + r2) != xx)
 261                   abort ();
 262               }
 263               { unsigned char xx = x, yy = y, r1, r2;
 264                 if (yy == 0) continue;
 265                 r1 = xx / yy;
 266                 r2 = xx % yy;
 267                 if (r2 >= yy || r1 * yy + r2 != xx)
 268                   abort ();
 269               }
 270               { signed char xx = x, yy = y, r1, r2;
 271                 r1 = xx / yy;
 272                 r2 = xx % yy;
 273                 if (ABS (r2) >= (unsigned char) ABS (yy) || (signed char) (r1 * yy + r2) != xx)
 274                   abort ();
 275               }
 276             }
 277
 278           exit (0);
 279         }
 280
 281         Here is the current output generated with the -I switch on a 90 Mhz
 282         pentium (the compiler used is the devlopment version of GCC with a new
 283         scheduler replacing the old one):
 284
 285         CPU #1 executed     41,994 AND instructions.
 286         CPU #1 executed    519,785 AND Immediate instructions.
 287         CPU #1 executed    680,058 Add instructions.
 288         CPU #1 executed     41,994 Add Extended instructions.
 289         CPU #1 executed    921,916 Add Immediate instructions.
 290         CPU #1 executed    221,199 Add Immediate Carrying instructions.
 291         CPU #1 executed    943,823 Add Immediate Shifted instructions.
 292         CPU #1 executed    471,909 Add to Zero Extended instructions.
 293         CPU #1 executed    571,915 Branch instructions.
 294         CPU #1 executed  1,992,403 Branch Conditional instructions.
 295         CPU #1 executed    571,910 Branch Conditional to Link Register instructions.
 296         CPU #1 executed    320,431 Compare instructions.
 297         CPU #1 executed    471,911 Compare Immediate instructions.
 298         CPU #1 executed    145,867 Compare Logical instructions.
 299         CPU #1 executed    442,414 Compare Logical Immediate instructions.
 300         CPU #1 executed          1 Condition Register XOR instruction.
 301         CPU #1 executed    103,873 Divide Word instructions.
 302         CPU #1 executed    104,275 Divide Word Unsigned instructions.
 303         CPU #1 executed    132,510 Extend Sign Byte instructions.
 304         CPU #1 executed    178,895 Extend Sign Half Word instructions.
 305         CPU #1 executed    871,920 Load Word and Zero instructions.
 306         CPU #1 executed     41,994 Move From Condition Register instructions.
 307         CPU #1 executed    100,005 Move from Special Purpose Register instructions.
 308         CPU #1 executed    100,002 Move to Special Purpose Register instructions.
 309         CPU #1 executed    804,619 Multiply Low Word instructions.
 310         CPU #1 executed    421,201 OR instructions.
 311         CPU #1 executed    471,910 OR Immediate instructions.
 312         CPU #1 executed  1,292,020 Rotate Left Word Immediate then AND with Mask instructions.
 313         CPU #1 executed    663,613 Shift Left Word instructions.
 314         CPU #1 executed  1,151,564 Shift Right Algebraic Word Immediate instructions.
 315         CPU #1 executed    871,922 Store Word instructions.
 316         CPU #1 executed    100,004 Store Word with Update instructions.
 317         CPU #1 executed    887,804 Subtract From instructions.
 318         CPU #1 executed     83,988 Subtract From Immediate Carrying instructions.
 319         CPU #1 executed          1 System Call instruction.
 320         CPU #1 executed    207,746 XOR instructions.
 321
 322         CPU #1 executed 23,740,856 cycles.
 323         CPU #1 executed 10,242,780 stalls waiting for data.
 324         CPU #1 executed          1 stall waiting for a function unit.
 325         CPU #1 executed          1 stall waiting for serialization.
 326         CPU #1 executed  1,757,900 times a writeback slot was unavilable.
 327         CPU #1 executed  1,088,135 branches.
 328         CPU #1 executed  2,048,093 conditional branches fell through.
 329         CPU #1 executed  1,088,135 successful branch predictions.
 330         CPU #1 executed    904,268 unsuccessful branch predictions.
 331         CPU #1 executed    742,557 branch if the condition is FALSE conditional branches.
 332         CPU #1 executed  1,249,846 branch if the condition is TRUE conditional branches.
 333         CPU #1 executed    571,910 branch always conditional branches.
 334         CPU #1 executed  9,493,653 1st single cycle integer functional unit instructions.
 335         CPU #1 executed  1,220,900 2nd single cycle integer functional unit instructions.
 336         CPU #1 executed  1,254,768 multiple cycle integer functional unit instructions.
 337         CPU #1 executed  1,843,846 load/store functional unit instructions.
 338         CPU #1 executed  3,136,229 branch functional unit instructions.
 339         CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
 340         CPU #1 executed    871,920 data reads.
 341         CPU #1 executed    971,926 data writes.
 342         CPU #1 executed        221 icache misses.
 343         CPU #1 executed 16,949,396 instructions in total.
 344
 345         Simulator speed was 250,731 instructions/second
 346
 347
 348
 349 What motivated PSIM?
 350
 351         As an idea, psim was first discussed seriously during mid
 352         1994.  At that time its main objectives were:
 353
 354
 355                 o       good performance
 356
 357                         Many simulators loose out by only providing
 358                         a binary interface to the internals.  This
 359                         interface eventually becomes a bottle neck
 360                         in the simulators performance.
 361
 362                         It was intended that PSIM would avoid this
 363                         problem by giving the user access to the
 364                         full source code.
 365
 366                         Further, by exploiting the power of modern
 367                         compilers it was hoped that PSIM would achieve
 368                         good performance with out having to compromize
 369                         its internal design.
 370
 371
 372                 o       practical portability
 373
 374                         Rather than try to be portable to every
 375                         C compiler on every platform, it was decided
 376                         that PSIM would restrict its self to suporting
 377                         ANSI compilers that included the extension
 378                         of a long long type.
 379
 380                         GCC is one such compiler, consequenly PSIM
 381                         should be portable to any machine running GCC.
 382
 383
 384                 o       flexability in its design
 385
 386                         PSIM should allow the user to select the
 387                         features required and customize the build
 388                         accordingly.  By having the source code,
 389                         the compler is able to eliminate any un
 390                         used features of the simulator.
 391
 392                         After all, let the compiler do the work.
 393
 394
 395                 o       SMP
 396
 397                         A model that allowed the simulation of
 398                         SMP platforms with out the large overhead
 399                         often encountered with such models.
 400
 401
 402         PSIM achieves each of these objectives.
 403
 404
 405 Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant?
 406
 407         No.
 408
 409         Among other things it does not have an Apple ROM socket.
 410
 411
 412 Can PSIM be configured so that it models a CHRP machine?
 413
 414         Yes.
 415
 416         PSIM has been designed with the CHRP spec in mind. To model
 417         a CHRP desktop a user would need to add the following:
 418
 419                 o       An apple rom socket :-)
 420
 421                 o       Model of each of the desktop IO devices
 422                         (some may already be implemented).
 423
 424                 o       An OpenPIC (Open Programmable Interrupt
 425                         Controller) device. (it may by now be
 426                         implemented).
 427
 428                 o       RTAS (Run Time Abstraction Services).
 429
 430                 o       A fully populated device tree.
 431
 432
 433 Is the source code available?
 434
 435         Yes.
 436
 437         The source code to PSIM is available under the terms of
 438         the GNU Public Licence.  This allows you to distribute
 439         the source code for free but with certain conditions.
 440
 441
 442 How do I build PSIM?
 443
 444         To build PSIM you will need the following files:
 445
 446
 447         gdb-4.15.tar.gz         From your favorite GNU ftp site.
 448                                 I've also tested psim with
 449                                 gdb-4.15.1.  If you would prefer
 450                                 a graphical development environment
 451                                 then PSIM can also be built with
 452                                 gdbtk.
 453
 454
 455         ftp://ftp.ci.com.au/pub/clayton/README.pim
 456
 457                                 This file.
 458
 459
 460         ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+psim.diff.gz
 461
 462                                 Firstly this file contains a few
 463                                 minor changes to gdb-4.15 so that it
 464                                 will build PSIM as part of GDB.
 465
 466
 467         ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+note.diff.gz
 468
 469                                 Add suport for note sections (used
 470                                 by OpenBoot PowerPC programs).
 471
 472
 473         ftp://ftp.ci.com.au/pub/clayton/gdb-4.15+attach.diff.gz
 474
 475                                 Allow the gdb attach command to
 476                                 work with simulators.
 477
 478
 479         ftp://ftp.ci.com.au/pub/clayton/psim-960119.tar.gz
 480
 481                                 This contains the psim files proper.
 482
 483
 484         gcc                     Again available from your favorite
 485                                 GNU ftp site.
 486
 487
 488         patch                   Sun's patch behaves a little wierd
 489                                 and doesn't appear to like creating
 490                                 empty files.  You may want to consider
 491                                 installing gnu's patch.
 492
 493
 494         Procedure:
 495
 496         0.      A starting point
 497
 498                 $ ls -1
 499                 gdb-4.15+attach.diff.gz
 500                 gdb-4.15+note.diff.gz
 501                 gdb-4.15+psim.diff.gz
 502                 gdb-4.15+psim.diff.gz
 503                 gdb-4.15.tar.gz
 504                 psim-960119.tar.gz
 505
 506
 507         1.      Unpack gdb
 508
 509                 $ gunzip < gdb-4.15.tar.gz | tar xf -
 510
 511
 512         2.      Change to the gdb directory, apply the psim patches and unpack
 513                 the psim files.
 514
 515                 $ cd gdb-4.15
 516
 517                 $ gunzip < ../gdb-4.15+psim.diff.gz | more
 518                 $ gunzip < ../gdb-4.15+psim.diff.gz | patch -p1
 519
 520                 $ gunzip < ../gdb-4.15+psim-960119.tar.gz | tar tvf -
 521                 $ gunzip < ../gdb-4.15+psim-960119.tar.gz | tar xvf -
 522
 523                 You may also want to consider applying the `attach' and
 524                 `note' patches that are available vis:
 525
 526                 $ gunzip < ../gdb-4.15+attach.diff.gz | more
 527                 $ gunzip < ../gdb-4.15+attach.diff.gz | patch -p
 528
 529                 $ gunzip < ../gdb-4.15+note.diff.gz | more
 530                 $ gunzip < ../gdb-4.15+note.diff.gz | patch -p
 531
 532
 533         3.      Configure gdb
 534
 535                 $ more gdb/README
 536
 537                 then something like (I assume SH):
 538
 539                 $ CC=gcc ./configure --target=powerpc-unknown-eabisim
 540
 541                 eabisim is needed as by default (because PSIM needs GCC) the
 542                 simulator is not built.
 543
 544                 [If building with a more recent gdb snapshot then the
 545                  command:
 546
 547                         $CC=gcc ./configure --enable-sim-powerpc
 548
 549                  is used.]
 550
 551         4.      Build
 552
 553                 $ make CC=gcc
 554
 555                 alternativly, if you are short on disk space or just want the
 556                 simulator built:
 557
 558                 $ ( cd libiberty && make CC=gcc )
 559                 $ ( cd bfd && make CC=gcc )
 560                 $ ( cd sim/ppc && make CC=gcc )
 561
 562
 563         5.      Install
 564
 565                 $ make CC=gcc install
 566
 567                 or just
 568
 569                 $ cp gdb/gdb ~/bin/powerpc-unknown-eabisim-gdb
 570                 $ cp sim/ppc/run ~/bin/powerpc-unknown-eabisim-run
 571
 572
 573 Is there a more recent version of PSIM and if so, how would I build it?
 574
 575         A PSIM is an ongoing development, occasional snapshots
 576         (that include new features) are made available.  Several of
 577         the more recent snapshots are:
 578
 579                 <to-be-advised>
 580
 581         To build/install one of these snapshots, you replace the
 582         current gdb/sim/ppc directory with the one in the update,
 583         re-configure and rebuild.
 584
 585         Procedure:
 586
 587         0.      A starting point
 588
 589                 $ cd gdb-4.15
 590
 591
 592         1.      Remove the old psim directory
 593
 594                 $ mv sim/ppc sim/old.ppc
 595
 596
 597         2.      Unpack the new one
 598
 599                 $ gunzip < ../psim-960105.tar.gz | tar tf -
 600                 $ gunzip < ../psim-960105.tar.gz | tar tf -
 601
 602
 603         3.      Reconfig/rebuild (as seen above):
 604
 605                 $ CC=gcc ./configure --target=powerpc-unknown-eabisim
 606                 $ make CC=gcc
 607
 608
 609 Are there any example programs that can be run on PSIM?
 610
 611         Psim has a simple test suite that is used to ensure
 612         that fixes do not introduce new bugs.  This test suite
 613         like psim is updated:
 614
 615         ftp://ftp.ci.com.au/pub/clayton/psim-test-960118.tar.gz
 616
 617                                 Prebuilt test programs for PSIM.
 618                                 Includes examples of UEA, VEA and
 619                                 OEA code.
 620                                 Requires gcc-2.7.2 and binutils-2.6
 621                                 to rebuild.
 622
 623
 624 How do I use the simulator?
 625
 626
 627         I assume that you've unpacked a psim-test archive.
 628
 629
 630         1.      As a standalone program
 631
 632                 Print out the users environment:
 633
 634                 $ powerpc-unknown-eabisim-run psim-test/uea/envp
 635
 636                 Print out the arguments:
 637
 638                 $ powerpc-unknown-eabisim-run psim-test/uea/argv a b c
 639
 640                 Check that sbrk works:
 641
 642                 $ powerpc-unknown-eabisim-run psim-test/uea/break
 643
 644
 645         2.      Example of running GDB:
 646
 647                 The main thing to note is that before you can run the simulator
 648                 you must enable it.  The example below illustrates this:
 649
 650                 $ powerpc-unknown-eabisim-gdb psim-test/uea/envp
 651                 (gdb) target sim
 652                 (gdb) load
 653                 (gdb) break main
 654                 (gdb) run
 655                 .
 656                 .
 657                 .
 658
 659
 660         3.      Using a device tree as a description of a machine
 661                 (I assume that you have applied the attach bug).
 662
 663                 $ cd psim-test/tree
 664                 $ powerpc-unknown-eabisim-gdb
 665                 (gdb) target sim
 666                 (gdb) attach device-tree
 667                 (gdb) run
 668
 669                 or
 670
 671                 $ cd psim-test/tree
 672                 $ powerpc-unknown-eabisim-run device-tree
 673
 674
 675 Where do I send bugs or report problems?
 676
 677         There is a mailing list (subscribe through majordomo@ci.com.au) (that
 678         is almost never used) at:
 679
 680         powerpc-psim@ci.com.au
 681
 682         If I get the ftp archive updated I post a note to that mailing list.
 683         In addition your welcome to send bugs or problems either to me or to
 684         that e-mail list.
 685
 686
 687 Does PSIM have any limitations or problems?
 688
 689         See the file PROBLEMS (included in the distribution) for any
 690         outstanding issues.
 691
 692
 693 Who helped?
 694
 695         Thanks go to the following who each helped in their own
 696         way:
 697
 698         Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam,
 699         Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn
 700         Richard Stallman, Mitchele Walker