Home | History | Annotate | Line # | Download | only in or1k 
      1 SIM port for the OpenRISC architecture
      2 
      3 Authors: Stafford Horne <shorne (a] 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 
    108