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