sim/or1k/README

   1 SIM port for the OpenRISC architecture
   2
   3 Authors: Stafford Horne <shorne@gmail.com>
   4          Peter Gavin
   5
   6 # Guide to Code #
   7
   8 We have tried to comment on the functions in the simulator implementation as
   9 best as we can.  Here we provide some general architecture comments for
  10 reference.  Please let me know if there is a better place for these kind of
  11 docs.
  12
  13 The or1k sim uses the CGEN system to generate most of the simulator code.  There
  14 is some documentation for CGEN on sourceware.org here:
  15
  16   https://sourceware.org/cgen/docs/cgen.html
  17
  18 In the binutils-gdb project there are several files which get combined to make
  19 up the CGEN simulator.  The process for how those are built can be seen in
  20 `or1k/Makefile.in`.  But the main files are:
  21
  22 MAIN
  23  sim/common/nrun.c - the main() calls sim_open(), sim_resume() and others
  24  sim/or1k/sim-if.c - implements sim_open() and others used by nrun
  25                      when envoking sim in gdb, gdb uses sim_open() directly
  26
  27 CGEN input and generated files
  28  cpu/or1k*.cpu - these define the hardware, model and semantics
  29  sim/or1k/arch.c - generated defines sim_machs array
  30  sim/or1k/cpu.c - *generated defines register setters and getters
  31  sim/or1k/decode.c - generated defines instruction decoder
  32  sim/or1k/model.c - generated defines instruction cycles
  33  sim/or1k/sem.c - *generated defines instruction operation semantics
  34  sim/or1k/sem-switch.c - *generated ditto but as a switch
  35
  36 ENGINE runs decode execute loop
  37  sim/common/cgen-* - cgen implementation helpers
  38  sim/common/cgen-run.c - implements sim_resume() which runs the engine
  39  sim/common/genmloop.sh - helper script to generate mloop.c engine the
  40                           decode, execute loop
  41  sim/or1k/mloop.in - openRISC implementation of mloop parts
  42
  43 EXTRAS callbacks from sem* to c code
  44  sim/or1k/or1k.c - implements some instructions in c (not cgen schema)
  45  sim/or1k/traps.c - exception handler
  46
  47 For each sim architecture we have choices for how the mloop is implemented.  The
  48 OpenRISC engine uses scache pbb (pseudo-basic-block) instruction extraction with
  49 both fast (sem-switch.c based) and full (sem.c based) implementations.  The fast
  50 and full modes are switch via the command line options to the `run` command,
  51 i.e. --trace-insn will run in full mode.
  52
  53                             # Building #
  54
  55 Below are some details on how we build and test the openrisc sim.
  56
  57                             ## TOOLCHAIN ##
  58
  59 This may not be needed as binutils contains most/all of the utilities required.
  60 But if needed, get this toolchain (this is the newlib binary, others also
  61 available)
  62
  63   https://github.com/openrisc/or1k-gcc/releases/download/or1k-5.4.0-20170218/or1k-elf-5.4.0-20170218.tar.xz
  64
  65 If you want to build that from scratch look to:
  66
  67   https://github.com/openrisc/newlib/blob/scripts/build.sh
  68
  69                               ## GDB ##
  70
  71 In a directory along side binutils-gdb source
  72
  73   mkdir build-or1k-elf-gdb
  74   cd build-or1k-elf-gdb
  75
  76   ../binutils-gdb/configure --target=or1k-elf \
  77     --prefix=/opt/shorne/software/or1k \
  78     --disable-itcl \
  79     --disable-tk \
  80     --disable-tcl \
  81     --disable-winsup \
  82     --disable-gdbtk \
  83     --disable-libgui \
  84     --disable-rda \
  85     --disable-sid \
  86     --with-sysroot \
  87     --disable-newlib \
  88     --disable-libgloss \
  89     --disable-gas \
  90     --disable-ld \
  91     --disable-binutils \
  92     --disable-gprof \
  93     --with-system-zlib
  94
  95   # make gdb, sim
  96   make
  97
  98   # test sim
  99   cd sim
 100   make check
 101
 102 The sim creates a binary simulator too, you can run binaries such as hello
 103 world with:
 104
 105   or1k-elf-gcc hello.c
 106   ./or1k/run --trace-insn ./a.out
 107