
Readme File for the Instruction Set Simulator of the COFFEE RISC Core
---------------------------------------------------------------------

This software simulates the operation of the COFFEE RISC core at instruction 
level accuracy. Some testing has been done, but bugs may still exist
Please mail bug reports to: tuukka.kasanko@tut.fi.


Requirements
------------

gtkmm 2.0 or later, and all the packages it requires. 
The development environment has been Fedora Core GNU/Linux, and it is the only environment
in which verification has been done.


Installation
------------

Run the compilation file by typing ./compile in the terminal, or issue the command:

g++ ccbtreeview.cc regtreeview.cc treeview_withpopup.cc data_mem_window.cc arith_oper.cc coffee_model.cc ccb.cc dissassembler.cc memory_models.cc inst_mem_window.cc cond_registers.cc user_registers.cc su_registers.cc copros_registers.cc topwindow.cc main.cc -o iss `pkg-config gtkmm-2.0 --cflags --libs gthread-2.0`


Licensing
---------

This software is licensed under the GNU Lesser General Public License.
See the 'license.txt' file for details, or go to:
http://www.gnu.org/licenses/lgpl.html


Modelling of Interrupts
-----------------------

Interrupts of the core are modelled with push-buttons. Simultaneuously arriving interrupt
requests can be modelled by pushing multiple interrupt buttons before pressing the step- or the
run-button. 


Switching Between 16-bit and 32-bit Operation Modes
---------------------------------------------------

After reset, the ISS is always in the 32-bit operation mode. This is equivalent with the actual
COFFEE RISC hardware.

One nop-instruction is needed after the swm-instruction when switching from the 32-bit mode
to the 16-bit mode. Two nop-instructions are needed when switching from the 16-bit mode
to the 32-bit mode. This is due to the fact that in the COFFEE RISC hardware the Program Counter (PC)
points to the next instruction to be fetched from the instruction memory. '.align' directive should
be used after switching from the 16-bit mode to the 32-bit mode to ensure proper alignment of the 
instructions.

The example below illustrates the swithcing between operation modes.


// -------------------------------------------------------------------------------------
// An example how to change between 32-bit and 16-bit operation modes.
// add-instructions are used to demostrate any useful code.

.text
.code 32
      add r0, r0, r0 // Fist instruction encoded into 32-bits
      add r0, r0, r0 // Any code here...
      add r0, r0, r0
      add r0, r0, r0
      swm 16
      nop
.code 16
      add r0, r0 // Fist instruction encoded into 16-bits
      add r0, r0 // Any code here...
      add r0, r0
      add r0, r0
      add r0, r0
      swm 32
      nop
      nop
.align 2 // Use  .align 2  assembly directive after 32-bit to 16-bit switch.
.code 32
      add r0, r0, r0 // Fist instruction encoded into 16-bits
      add r0, r0, r0 // Any code here...
      add r0, r0, r0
// -------------------------------------------------------------------------------------


Code and Data Segments
----------------------

The ISS reads the object format produced by the assembler and linker downloadable from
http://coffee.tut.fi web site. 

While writing assembly, instructions should be placed inside code segments and
data inside data segments. The compiler automatically generates necessary code and data segments
and places all assembly instructions it generates into code segments, and all data into data segments.
The instruction set simulator reads the object format generated by the assembler or the linker, and places all
material inside code segments into the instruction memory, and all material in data segments into the data memory.

Even though the user can specify absolute locations for instruction and data segments in the assembly code
by using the '.section' directive, the sections are not correctly located after running the assembler. One must make
a linker skript and use the linker to place the sections to specified locations. The linker makes the necessary
changes into the object format, so that the start addresses of each section will have a the value specified, and 
that all references from code segments into data segments will have proper values and therefore function as intended. 
The same applies also to pointers. For instance, after assembling all references from code segments to labels inside 
data segments will have a value relative to the start of the data segment containing the label, and not the actual valid
address of the label. While the ISS can read the output format produced by the assembler, the behaviour of the code 
may not be correct before linking due to the reasons mentioned above. 

At the time of writing this, I am not aware of the status of the verification of the linker. In other words it
may well be that the linker does not operate correctly in all possible cases. If you do run into bugs, please
contact the designer of the linker and report your findings.

The example below illustrates how an address of a label can be placed into a register from a code segment.
After running the assembler, the reference to the label 'my_label' specified inside the data segment
will not operate correctly before linking. The reason is that the assembler places the data segment after the code
segment and the address of the label 'my_label' will be calculated relative to the start of the data segment,
which will not be zero because it is located after the code segment. The linker must be used in order to 
relocate the data segment to the specified address and make the appropriate corrections to the object file.

// ---------------------------------------------------------------------------
// A data section, to be located starting from the address 0.
.section my_data, d, 0
	.word 1
	.word 2
	.word 7
my_label:	
	.word 100
	.word 101
	.word 102

	
// A code section, to be located starting from the address 0.
.section my_code, x, 0
.code 32
.align 2
	xor r0,r0,r0
	ldra r0, my_label
// ----------------------------------------------------------------------------


Known Issues and Bugs
---------------------

The software can read only COFF format produced by the assembler downloadable from the 
http://coffee.tut.fi website.

Reset makes the program counter value 0. This behaviour is equivalent with the
actual hardware, if a boot agent is not used. Currently the usage of the boot agent in the 
actual hardware cannot be modelled with the ISS.

The highlighted line in the 'instruction memory content' window indicates
the previously executed instruction. In the real COFFEE hardware the Program Counter
points to the next instruction. (instruction to be fetched from the memory.) 
In other words the value of the program counter is the address of the 
highlighted instruction +2 or +4 depending on the mode. 
(+2 in the 16-bit mode, and +4 in the 32-bit mode.) Wether the ISS should show 
precisely the location of the PC or the instruction previously executed is a matter of taste. 
In my humble opinion the current implementation is more clear especially with branches,
due to the branch slot. (The instruction following a branch or a jump instruction is 
executed before branching to a new address.)

While in continuous run mode, the user cannot see wether the simulator is still
running, or stopped to a breakpoint. The user has to press the stop-button in order 
to see the state of the simulator. This is due to the fact that the X-windowing 
system does not yet support multiple threads. 

All registers in register windows are updated after each step, even though
updating the correct one would be sufficient. This makes stepping slower, but does not
affect the performance in the 'continuous run' mode.

Functionality for the BUS_CONF CCB register is not implemented. Due to the fact that
this softare does not contain a cycle accurate model of the actual hardware, implementation of
wait clock cycles does not make much sense.

When a load is attempted from a memory location which does not contain anything, an error
message is written to the console. If the load attempt was made in the continuous run mode,
the Graphical User Interface of the ISS may become unstable. This is due to the fact that
the X-windowing system of GNU/Linux is not yet fully thread safe. Another execution thread
must be invoked in order to support the continuous-run-mode, because otherwise the software
cannot respond to a stop-button click.


Revision History
----------------

iss-1.066.tar.gz
----------------
- Interrupts disabled between a branch instruction and the following slot instruction.


iss-1.065.tar.gz
----------------
- PSR update bug in the RETU-instruction corrected.


iss-1.064.tar.gz
----------------
- 'Coprocessor registers' bug corrected.
- PSR bug in the SCALL instruction corrected.


iss-1.063.tar.gz
---------------
- PSR bug corrected conserning exception handler routine entry.


iss-1.062.tar.gz
---------------
- Register bit masking in store operations changed to match documentation for the CCB registers
  COP_CONF, RETI_PSR, and RETI_CR0.


iss-1.061.tar.gz
---------------
- Error message replaced with a more informative one, if a load is attempted from 
  a data memory location which does not contain anything.
- A value masking bug corrected for RETI_ADDR CCB register.
- PSR update bug conserning the Super User Registers window corrected from the RETI instruction.


iss-1.06.tar.gz
---------------
- JMP-instruction target address calculation corrected.
- Execution of the last instruction in the instruction memory enabled.
- Radix selection implemented for the Core Control Block registers.
- The value of the Program Counter has been made visible into the 
  condition register window.
- Various reset values of the CCB registers changed due to changes in the COFFEE hardware.
- Timers implemented.
- A bug conserning interrupts after a jump instruction corrected.
- A bug in the RETU instruction corrected.
- An error message is now given, if the exception handler entry address is invalid.
- PSR is now correctly updated after entering an interrupt service routine.
- Functionality implemented for the CCB registers RETI_ADDR, RETI_PSR, and RETI_CR0.

