README.md

   1 # OpenPOWER ISA resources
   2
   3 OpenPOWER ISA resources, including a python-based simulator plus thousands
   4 of OpenPOWER ISA unit tests.  Includes machine-readable versions of the
   5 OpenPOWER v3.0B specification, from which the python-based simulator
   6 is compiled (python-ply) into python.  Additional languages (c, c++)
   7 are planned.  Also planned: co-simulation of power-gem5, microwatt,
   8 and other HDL and emulators.
   9
  10 Part of the Libre-SOC Project (http://libre-soc.org)
  11 Sponsored by http://nlnet.nl
  12
  13 # Installation
  14
  15 Prerequisites: qemu, powerpc64-linux-gnu-gcc and associated binutils and
  16 gdb, pygdbmi, nmigen and nmutil are needed.  Make life easy: use debian,
  17 and the following scripts:
  18
  19 * https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=ppc64-gdb-gcc
  20 * https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=install-hdl-apt-reqs
  21 * https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=pia-install
  22
  23 Once those are sorted, installation and setup is as follows:
  24
  25 ```
  26     python3 setup.py develop
  27     make svanalysis
  28     make pywriter
  29 ```
  30
  31 # Usage
  32
  33 Usage depends on what your goal is.  The python-based simulator is in no
  34 way intended to win any speed contests: it's designed for "readability".
  35 Additionally, running qemu via pygdmi and extracting its register file
  36 is equally horribly slow.  To demonstrate, run the following:
  37
  38     python3 openpower/simulator/test_sim.py
  39
  40 This will do the following:
  41
  42 * compile each of the (tiny) programs in the test
  43 * extract the raw binary
  44 * fire up the python-based simulator (ineptly named ISACaller)
  45 * fire up qemu using the machine interface pygdbmi
  46 * single-step through both ISACaller and qemu, extracting full regfiles
  47   and memory
  48 * compare them both and throw exceptions on detected discrepancies
  49
  50 This should be pretty obvious as to why this is done: it's checking
  51 one simulator against another (and has found bugs in qemu as a result).
  52
  53 What if you could then also run the same unit tests against *your own
  54 hardware*, or against say Microwatt, or Libre-SOC, or against your
  55 own emulator?
  56
  57 Given that this is a work-in-progress, so far the only external HDL
  58 that uses these unit tests is Libre-SOC's very simple TestIssuer:
  59 https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/simple/test/test_issuer.py
  60
  61 The ISACaller itself of course needed to bootstrap up by having unit
  62 tests that explicitly and clearly checked against expected values.  Example:
  63
  64     python openpower/decoder/isa/test_caller.py
  65
  66 These tests pre-prepare the register files, then check afterwards that
  67 the result of operation is as expected.  In this way, at least basic
  68 functionality of ISACaller can be confirmed in a stand-alone fashion
  69 (useful if you do not wish to install qemu etc. etc. etc.)
  70
  71 # Contributions
  72
  73 Contributions are welcomed as this is a collaborative Libre Project.
  74 Libre-SOC is covered by the following dead-simple Charter:
  75
  76     https://libre-soc.org/charter/
  77
  78 Contributions even to the Charter, in the form of appropriate Dilbert
  79 cartoons especially appreciated:
  80
  81     https://libre-soc.org/charter/discussion/
  82
  83 # Copyrights
  84
  85 All programs are written by Libre-SOC team members are LGPLv3+.
  86 However the specification and the CSV files came from their
  87 respective Copyright holders (IBM, OpenPOWER Foundation, Microwatt)
  88