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 * python3 setup.py develop
  26 * make svanalysis
  27 * make pywriter
  28
  29 # Usage
  30
  31 Usage depends on what your goal is.  The python-based simulator is in no
  32 way intended to win any speed contests: it's designed for "readability".
  33 Additionally, running qemu via pygdmi and extracting its register file
  34 is equally horribly slow.  To demonstrate, run the following:
  35
  36     python3 openpower/simulator/test_sim.py
  37
  38 This will do the following:
  39
  40 * compile each of the (tiny) programs in the test
  41 * extract the raw binary
  42 * fire up the python-based simulator (ineptly named ISACaller)
  43 * fire up qemu using the machine interface pygdbmi
  44 * single-step through both ISACaller and qemu, extracting full regfiles
  45   and memory
  46 * compare them both and throw exceptions on detected discrepancies
  47
  48 This should be pretty obvious as to why this is done: it's checking
  49 one simulator against another (and has found bugs in qemu as a result).
  50
  51 What if you could then also run the same unit tests against *your own
  52 hardware*, or against say Microwatt, or Libre-SOC, or against your
  53 own emulator?
  54
  55 Given that this is a work-in-progress, so far the only external HDL
  56 that uses these unit tests is Libre-SOC's very simple TestIssuer:
  57 https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/simple/test/test_issuer.py
  58
  59 The ISACaller itself of course needed to bootstrap up by having unit
  60 tests that explicitly and clearly checked against expected values.  Example:
  61
  62 * python openpower/decoder/isa/test_caller.py
  63
  64 These tests pre-prepare the register files, then check afterwards that
  65 the result of operation is as expected.  In this way, at least basic
  66 functionality of ISACaller can be confirmed in a stand-alone fashion
  67 (useful if you do not wish to install qemu etc. etc. etc.)
  68
  69 # Contributions
  70
  71 Contributions are welcomed as this is a collaborative Libre Project.
  72 Libre-SOC is covered by the following dead-simple Charter:
  73
  74 * https://libre-soc.org/charter/
  75
  76 Contributions even to the Charter, in the form of appropriate Dilbert
  77 cartoons especially appreciated:
  78
  79 * https://libre-soc.org/charter/discussion/
  80
  81 # Copyrights
  82
  83 All programs are written by Libre-SOC team members are LGPLv3+.
  84 However the specification and the CSV files came from their
  85 respective Copyright holders (IBM, OpenPOWER Foundation, Microwatt).
  86
  87 Bear in mind that the *facts* in a specification may not be copyrighted,
  88 however the document (or source code) *containing* those facts can be and
  89 is copyrightable.  In this repository, the **facts** were extracted
  90 (from Microwatt and from the OpenPOWER ISA Technical Specification).
  91
  92 Therefore, you, likewise, may *also* extract the **facts** from this
  93 source code, but for the actual source code itself you must respect the
  94 terms and conditions of the LGPLv3+ License in which those facts happen
  95 to be embedded.
  96
  97 # Other Unit Tests
  98
  99 There do exist other unit tests for OpenPOWER.  List them here:
 100
 101 * https://bitbucket.org/sandip4n/gem5-powerpc64le-tests/src/master/
 102 * http://sources.buildroot.net/kvm-unit-tests/git/powerpc/
 103 * https://github.com/lioncash/DolphinPPCTests
 104