1 files changed, 348 insertions, 0 deletions
diff --git a/README.sis b/README.sis
new file mode 100644
index 0000000..ffcc591
--- /dev/null
+++ b/README.sis
@@ -0,0 +1,348 @@
+
+SIS - Sparc Instruction Simulator README file  (v2.9, 16-01-2019)
+-------------------------------------------------------------------
+
+1. Introduction
+
+The SIS is a SPARC V7/V8 architecture simulator. It consist of two parts,
+the simulator core and a user defined memory module. The simulator
+core executes the instructions while the memory module emulates memory
+and peripherals. As of version 2.9, sis can also emulate a RISC-V 
+RV32IMACF processor.
+
+2. Usage
+
+The simulator is started as follows:
+
+sis [-leon2] [-leon3] [-uart1 uart_device1] [-uart2 uart_device2]
+    [-m cores] [-d clocks] [-nfp] [-freq freq] [-c batch_file] [-v]
+    [-r] [-tlim time] [-cov] [-gdb] [-port n] [files]
+
+By default, SIS emulates an ERC32 system. The -leon2 switch enables
+LEON2 emulation, while the -leon3 switch enables emulation of a
+LEON3 SOC system. When compiled for RISC-V (--target=riscv-rtems5),
+the simulator emulates a RISC-V RV32IMACF cpu connected to GRLIB
+IP cores.
+
+The emulated console uart is connected to stdin/stdout. The -uart[1,2]
+switch can be used to connect the uarts to other devices.
+
+The '-nfp' will disable the simulated FPU, so each FPU instruction will
+generate a FPU disabled trap. The '-freq' switch can be used to define
+which "frequency" the simulator runs at. This is used by the 'perf'
+command to calculated the MIPS figure for a particular configuration.
+The frequency must be an integer indicating the frequency in MHz.
+
+The -c option indicates that sis commands should be read from 'batch_file'
+at startup.
+
+-v sets the debug level to 1, to provide some diagnostic messages.
+
+-r starts execution immediately without an interactive shell. This is useful
+for automated testing of large number of binaries.
+
+-tlim can be used together with -r to limit the amount of simulated time that
+the simulator runs for before exiting. The following units are recognized:
+us, ms and s. To limit simulated time to 100 seconds, it should thus be
+started with -r -tlim 100 s .
+
+-m sets the number of cores (2 - 4) in a leon3 or RISC-V multi-processor system.
+
+-d set the the number of clocks in each time-slice for multi-processor
+simulation. Default is 50, set lower for higher accuracy.
+
+-gdb will start a gdb server, listening on port 1234. An alternative port can
+be specified with -port <nn>.
+
+Files to be loaded must be in one of the formats supported by the BFD library.
+This inlude elf, a.out, srec and binary. On start-up, the files will be
+loaded into the simulated memory.
+
+3. Internal commands
+
+Below is the description of commands that are recognized by the simulator.
+The command-line is parsed using GNU readline. A command
+history of 64 commands is maintained. Use the up/down arrows to recall
+previous commands. For more details, see the readline documentation.
+
+* List of commands:
+
+batch <file>
+
+Execute a batch file of SIS commands.
+
++bp <address>
+break <address>
+
+Adds an breakpoint at address <address>.
+
+bp
+
+Prints all breakpoints
+
+-bp <num>
+delete
+
+Deletes breakpoint <num>. Use 'bp' or break to see which number is assigned
+to the breakpoints.
+
+csr
+
+Show RISC-V CSR registers
+
+cont [inst_count]
+
+Continue execution at present position, optionally for [inst_count] 
+instructions.
+
+dis [addr] [count]
+
+Disassemble [count] instructions at address [addr]. Default values for
+count is 16 and addr is the present address.
+
+echo <string>
+
+Print <string> to the simulator window.
+
+float
+
+Prints the FPU registers
+
+gdb [port]
+
+Starts the gdb server interface. Default port is 1234, but can be overriden using
+the [port] argument. gdb should be started with 'tar extended-remote localhost:1234'.
+
+go <address> [inst_count]
+
+The go command will set pc to <address> and npc to <address> + 4, and start
+execution. If inst_count is given, execution will stop after the specified
+number of instructions.
+
+help
+
+Print a small help menu for the SIS commands.
+
+hist [trace_length]
+
+Enable the instruction trace buffer. The 'trace_length' last executed 
+instructions will be placed in the trace buffer. A 'hist' command without 
+a trace_length will display the trace buffer. Specifying a zero trace 
+length will disable the trace buffer.
+
+load  <file_name>
+
+Loads a file into simulator memory. 
+
+mem [addr] [count]
+
+Display memory at [addr] for [count] bytes. Same default values as above.
+
+quit
+
+Exits the simulator.
+
+perf [reset]
+
+The 'perf' command will display various execution statistics. A 'perf reset' 
+command will reset the statistics. This can be used if statistics shall 
+be calculated only over a part of the program. The 'run' and 'reset' 
+command also resets the statistic information.
+
+reg [reg_name] [value]
+
+Prints and sets the IU registers. 'reg' without parameters prints the IU
+registers. 'reg [reg_name] [value]' sets the corresponding register to
+[value]. Valid register names are psr, tbr, wim, y, g1-g7, o0-o7 and
+l0-l7.
+
+reset
+
+Performs a power-on reset. This command is equal to 'run 0'.
+
+run [inst_count]
+
+Resets the simulator and starts execution from address 0. If an instruction
+count is given (inst_count), the simulator will stop after the specified
+number of instructions. The event queue is emptied but any set breakpoints
+remain.
+
+step
+
+Equal to 'trace 1'
+
+sym
+
+List symbols and corresponding addresses in the loaded program.
+
+tra [inst_count]
+
+Starts the simulator at the present position and prints each instruction
+it executes. If an instruction count is given (inst_count), the simulator
+will stop after the specified number of instructions.
+
+wmem [addr] [data]
+
+Writes [data] to memory at [addr]. Data is written as a 32-bit word.
+
+wp
+
+Prints all watchpoints
+
++wpr <address>
+
+Adds an read watchpoint at address <address>.
+
+-wpr <num>
+
+Deletes read watchpoint <num>. Use 'wp' to see which number is assigned to
+the watchpoints.
+
++wpw <address>
+watch <address>
+
+Adds an write watchpoint at address <address>.
+
+-wpw <num>
+
+Deletes write watchpoint <num>. Use 'wp' to see which number is assigned to
+the watchpoints.
+
+Typing a 'Ctrl-C' will interrupt a running simulator.
+
+Short forms of the commands are allowed, e.g 'c' 'co' or 'con' are all
+interpreted as 'cont'.
+
+4. Using SIS with GDB
+
+To start the simulator inside gdb, use:
+
+target sim [options]
+
+The following options are supported:
+
+ -leon2         Emulate a LEON2 system
+
+ -leon3         Emulate a LEON3 system
+
+ -nfp           Disable FPU. FPops will cause an FPU disabled trap.
+
+ -freq <f>      Set the simulated "system clock" to <f> MHz.
+
+ -v             Verbose mode.
+
+ -nogdb         Disable GDB breakpoint handling (see below)
+
+To start debugging a program type 'load <program>' and debug as
+usual.
+
+The native simulator commands can be reached using the GDB 'sim'
+command:
+
+sim <sis_command>
+
+Direct simulator commands during a GDB session must be issued
+with care not to disturb GDB's operation ...
+
+A program can be restarted in GDB by first issuing the load command,
+followed by run.
+
+sis can also be connected to gdb when started standalone, using the gdb remote
+insterface. Either start sis with -gdb, or issue the 'gdb' command inside sis,
+and connect gdb with 'target extended-remote localhost:1234'. sis will operate
+identical with built-in or remote interfaces.
+
+4.1 GDB breakpoint handling
+
+GDB inserts breakpoint in the form of the 'ta 1' instruction. The
+GDB-integrated simulator will therefore recognize the breakpoint
+instruction and return control to GDB. If the application uses
+'ta 1', the breakpoint detection can be disabled with the -nogdb
+switch. In this case however, GDB breakpoints will not work.
+
+
+5. Simulator core
+
+In ERC32 mode, SIS emulates the behavior of the 90C601E and 90C602E
+sparc IU and FPU from Matra MHS. These are roughly equivalent to the
+Cypress C601 and C602. The simulator is reasonably cycle accurate, a simulator
+time is maintained and incremented according the IU and FPU instruction timing.
+The parallel execution between the IU and FPU is modelled, as well as
+stalls due to operand dependencies (FPU).
+
+In Leon2/3 mode, the core emulates the Leon2/3 SPARC V8 core from
+Gaisler Research. All SPARC V8 instructions are supported but
+emulation is not fully cycle-true as the cache is not emulated.
+
+In RISC-V mode, a RV32IMACF profile is emulated. No cache or MMU
+are modelled.
+
+6. Memory module
+
+The ERC32 memory module (erc32.c) emulates the functions of memory and
+the MEC asic developed for the 90C601/2. It includes the following functions:
+
+* UART A & B
+* Real-time clock
+* General purpose timer
+* Interrupt controller
+* Breakpoint register
+* Watchpoint register
+* 16 Mbyte ROM
+* 16 Mbyte RAM
+
+See README.erc32 on how the MEC functions are emulated.
+
+The Leon2 memory module (leon2.c) emulates on-chip peripherals and
+external memory for a simple Leon2 system. The modules includes the
+following functions:
+
+* AHB and APB buses
+* One UART
+* Interrupt controller
+* Timer unit with two timers
+* PROM/SRAM memory controller
+* 16 Mbyte PROM, 16 Mbyte SRAM
+
+See README.leon2 for further details on Leon2 emulation.
+
+The Leon3 memory module (leon3.c) emulates on-chip peripherals and
+external memory for a simple Leon3 system. The modules includes the
+following functions:
+
+* AHB and APB buses with plug&play
+* UART (APBUART)
+* Interrupt controller (IRQMP)
+* Timer unit with two timers (GPTIMER)
+* PROM/SRAM memory controller (SRCTRL)
+* 16 Mbyte PROM, 16 Mbyte SRAM
+
+The RISC-V cpu uses the same peripherals as Leon3, but implements the
+RISC-V instructions set instead of SPARC. See README.riscv for further
+details.
+
+7. FPU implementation
+
+The simulator maps floating-point operations on the hosts floating point
+capabilities. This means that accuracy and generation of IEEE exceptions is
+host dependent.
+
+8. Code coverage
+
+Code coverage data will be produce if sis is started with the -cov switch.
+The coverage data will be stored in a file name same as the file used with 
+the load command, appended with .cov. For instance, if sis is run with
+hello.exe, the coverage data will be stored in hello.exe.cov. The coverage
+file is created when the simulator is exited.
+
+The coverage file data consists of a starting address, and a number of
+coverage points indicating incremental 32-bit word addresses:
+
+0x40000000  0 0 0 19 9 1 1 1 1 0 .....
+
+The coverage points are in hexadecimal format. Bit 0 (lsb) indicates an
+executed instruction. Bit 3 indicates taken branch and bit 4 indicates
+an untaken branch. Bits 2 and 3 are currently not used.
+
+For RISC-V, code coverage is only supported for 32-bit instructions, i.e.
+the C-extension can not be used when code coverage is measured.