Recursos para o Livro Arquitetura e Organização de Computadores

Gabriel P. Silva & José Antonio S. Borges - Editora LTC

https://github.com/Simulador-SimuS/simulador-simus.github.io/blob/main/_layouts/default.html

SimuS

Sapiens Processor Simulator

User Manual

1. Introduction

SimuS (Sapiens Simulator) is an educational tool developed to simulate the operation of the Sapiens processor. This simulator allows students to write, compile, and execute programs in assembly language, visualizing the behavior of the processor, registers, flags, and memory in real time.

SimuS offers advanced debugging features, including step-by-step execution, breakpoints, memory visualization, and simulated input/output ports.

2. User Interface

The user interface language can be set to Portuguese, English, or Spanish by clicking one of the flags located in the upper corner of the main window.

The SimuS interface is divided into three main panels, each with specific functions to facilitate program development and debugging.

2.1. Left Panel - Editor and Execution

This panel contains three tabs that allow you to edit code, view errors, and monitor execution:

2.1.1. Editor Tab

An assembly code editing area with the following features:

2.1.2. Errors Tab

Displays error messages generated during compilation:

2.1.3. Execution Tab

Visualization of the compiled code with debugging resources:

2.2. Central Panel - CPU and Controls

This panel concentrates all execution controls and the visualization of the CPU state:

2.2.1. Control Buttons

Five distinctly colored buttons to control execution:

2.2.2. Status Bar

Displays the current state of the simulator in gray text below the control buttons. Messages include: “Ready”, “Running…“, “TURBO - Running…“, “HALT - Program Finished”, among others.

2.2.3. Registers

Three boxes displaying the values of the main registers in hexadecimal:

2.2.4. Current Instruction

A box with a dark background displaying the mnemonic of the instruction currently pointed to by the PC. Example: LDA #0xFF. This yellow-gold highlighted view makes it easy to track execution.

2.2.5. Flags (Indicators)

Three visual indicators showing the state of the processor flags:

2.2.6. Input/Output Ports

Simulated peripheral interface with four components:

2.3. Right Panel - Memory Visualization

Displays the contents of the RAM memory in hexadecimal format with navigation features:

2.3.1. Navigation Bar

Controls at the top of the memory panel:

2.3.2. Memory Grid

Visualization in a hexadecimal grid with the following characteristics:

3. File Toolbar

Located at the top of the left panel, it offers buttons for file management and auxiliary windows:

3.1. Pop-up Windows

The Terminal and Video windows are independent floating windows. To reposition them, click and drag the top bar of the window. The red circular button on the title bar closes/hides the window.

4. Typical Workflow

Follow these steps to develop and execute programs in SimuS:

  1. Edit the Code: In the Editor tab, write your assembly program. Use comments (;) to document the code. Remember to include the ORG directive to define the starting address and END to mark the end of the program.

  2. Compile: Click the ✔ Compile button. If there are errors, correct them as indicated in the Errors tab and compile again.

  3. Set Breakpoints (Optional): In the Execution tab, click on the lines where you want to pause execution. A red circle will appear on the address.

  4. Run: Choose an execution mode:
    • Step: For detailed, instruction-by-instruction debugging.
    • Run: For normal speed execution with visual updates.
    • Turbo: For long programs, running at maximum speed.

  5. Monitor Execution: Observe the registers, flags, memory, and I/O ports updating in real time. The current line is highlighted in yellow in the Execution tab.

  6. Interact with I/O: When the program executes IN 0, type a hexadecimal value into the Input (Hex) field and press ENTER. Values sent via OUT are displayed automatically.

  7. Finish: The program stops automatically when it encounters an HLT. Use the Reset button to restart and run again.

  8. Save: Use 💾 Save As… to save your work to a file.

5. Sapiens Instruction Set

The Sapiens processor implements the following categories of instructions:

5.1. Data Transfer Instructions

Mnemonic Name Description
LDA Load Accumulator Loads AC with a value from memory or an immediate value
STA Store Accumulator Stores AC into memory
LDS Load Stack Pointer Loads SP with a 16-bit value
STS Store Stack Pointer Stores SP into memory (16 bits)

5.2. Arithmetic Instructions

Mnemonic Name Description
ADD Addition AC = AC + operand (updates flags)
ADC Add with Carry AC = AC + operand + C (updates flags)
SUB Subtraction AC = AC - operand (updates flags)
SBC Subtract with Carry AC = AC - operand - C (updates flags)

5.3. Logical Instructions

Mnemonic Name Description
AND Logical AND AC = AC & operand (updates flags)
OR Logical OR AC = AC | operand (updates flags)
XOR Exclusive OR AC = AC ^ operand (updates flags)
NOT Logical NOT AC = ~AC (updates flags)

5.4. Shift Instructions

Mnemonic Name Description
SHL Shift Left Shifts AC 1 bit to the left (bit 0 = 0, C receives bit 7)
SHR Shift Right Shifts AC 1 bit to the right logically (bit 7 = 0, C receives bit 0)
SRA Shift Right Arithmetic Shifts AC 1 bit to the right arithmetically (maintains bit 7)

5.5. Flow Control Instructions

Mnemonic Name Description
JMP Jump Jumps unconditionally to an address
JZ Jump if Zero Jumps if flag Z = 1
JNZ Jump if Not Zero Jumps if flag Z = 0
JN Jump if Negative Jumps if flag N = 1
JP Jump if Positive Jumps if flag N = 0
JC Jump if Carry Jumps if flag C = 1
JNC Jump if No Carry Jumps if flag C = 0

5.6. Subroutine Instructions

Mnemonic Name Description
JSR Jump to Subroutine Saves PC to the stack and jumps to the subroutine
RET Return Returns from a subroutine (recovers PC from the stack)

5.7. Stack Instructions

Mnemonic Name Description
PUSH Push to Stack Pushes AC onto the stack (mem[SP] = AC, then SP–)
POP Pop from Stack Pops from the stack to AC (SP++, then AC = mem[SP])

5.8. Input/Output Instructions

Mnemonic Name Description
IN Input Reads data from the specified port into AC
OUT Output Sends AC to the specified port

Available I/O Ports:

Instruction Function
IN 0 Reads the hexadecimal value typed by the user
IN 1 Reads input status (1 = data available, 0 = no data)
OUT 0 Sends AC to the hexadecimal output display
OUT 2 Clears the text banner
OUT 3 Sends an ASCII character to the text banner (appends to the end)

5.9. Special Instructions

Mnemonic Name Description
NOP No Operation Does nothing (can be used for timing)
HLT Halt Stops the processor execution
TRAP Trap Generates a service call

Available TRAP Operations:

LDA #20
TRAP VIDEO_CONFIG
OR #0
JNZ ERROR
Instruction Function
#0 Clears the console terminal
#1 Reads a character from the terminal and saves it in the accumulator and the operand’s memory address
#2 Writes a character from the operand’s memory address to the terminal
#3 Reads a string from the terminal and saves it at the operand’s memory address
#4 Writes a string starting from the operand address (until a NULL is found)
#5 Delay (Waits from 0 to 65535 ms)
#6 Beep (Audio Synthesizer). Receives frequency and duration as parameters
#7 Returns a pseudo-random number between 0 and 99 in the accumulator
#20 Configures the virtual graphic display. The operand points to a DW base block, where base is the start of video memory.
#21 Clears video memory with one color. The operand points to DB color.
#22 Draws one pixel. The operand points to DB x, y, color.
#23 Draws a line. The operand points to DB x0, y0, x1, y1, color.
#24 Draws a rectangle. The operand points to DB x, y, width, height, color, filled.
#25 Draws a circle. The operand points to DB cx, cy, radius, color, filled.

Virtual Graphic Display

The virtual graphic display has a resolution of 128 × 64 pixels. Video memory occupies 8192 consecutive bytes, with 1 byte per pixel. TRAP #20 defines which region of the 64 KB memory is used as the video buffer. The base address must be aligned to a multiple of 256, and the area base + 8192 must not exceed the memory limit.

The pixel layout is linear:

address = base + (y * 128) + x

Colors use the 8-bit RRRGGGBB format:

Value Approximate color
224 / 0xE0 Red
28 / 0x1C Green
3 / 0x03 Blue
252 / 0xFC Yellow
255 / 0xFF White

Main return values for TRAP #20:

AC Meaning
0 Success
1 Base address is not aligned to 256 bytes
2 Video area exceeds the memory limit
4 Used by graphic TRAPs when video has not been configured yet

6. Addressing Modes

Sapiens supports four addressing modes, identified by the 2 most significant bits of the opcode:

Bits Mode Example Operation Description
00 Direct LDA 50 AC = mem[50] The operand is the memory address of the data
01 Indirect LDA @50 AC = mem[mem[50]] The operand points to an address containing the final address of the data
10 8-bit Immediate LDA #10 AC = 10 The operand is the byte following the instruction
11 16-bit Immediate LDS #1000 SP = 1000 The operand consists of the two bytes following the instruction

Notes on Addressing:

7. Operand Formats

Sapiens supports several types of formats for instruction operands:

8. Assembler Directives

The SimuS assembler recognizes the following directives:

Directive Description Example Effect
ORG address Defines the starting address of the program ORG 0 Program starts at address 0
END Marks the end of the source code END Last line of the file
DB value[, value...] Defines one or more bytes (8 bits) DB 0xFF, 10, 1010B Stores the byte list in memory
DW value[, value...] Defines one or more words (16 bits) DW 0x1234, 1000 Stores words in little-endian format
DS quantity Defines space (reserves bytes) DS 10 Reserves 10 zeroed bytes
LABEL EQU value Defines a constant TESTE EQU 10 TESTE will be equal to 10

Note: for constants, use LABEL EQU value without a colon. The form LABEL: EQU value first creates a label at the current address and may not define the constant as expected.

Use of Labels:

Labels can be defined before any instruction or directive, ending with a colon:

LOOP:
    LDA VALUE
    JNZ LOOP

9. Code Examples

9.1. Simple Echo

A program that waits for user input and echoes the value back:

; Echo Program
ORG 0
LOOP:
    IN 1          ; Read status
    OR #0         ; Verify value
    JZ LOOP       ; Wait for data
    IN 0          ; Read value
    OUT 0         ; Display value
    HLT
END

9.2. Counter from 0 to 9

Counts from 0 to 9 and stops:

; Counter
ORG 0
    LDA #0        ; Start at 0
LOOP:
    LDA CONT      ; Load counter
    OUT 0         ; Show value
    ADD #1        ; Increment
    STA CONT      ; Save counter value
    SUB #10       ; Compare with 10
    JNZ LOOP      ; Continue if != 10
    HLT
END
CONT:  DB 0

9.3. Subroutine with Stack

Demonstrates the use of JSR, RET, and PUSH/POP:

; Passing a parameter on the stack
; Result returned in the accumulator

ORG 0
    LDA #42          ; Subroutine parameter
    PUSH             ; Pushes the parameter onto the stack
    JSR DOBRO        ; JSR pushes the return address onto the stack
    OUT 0            ; Shows the result: 84
    HLT

DOBRO:
    ; When entering the subroutine, the top of the stack contains
    ; the return address placed there by JSR.
    ; Below it is the parameter pushed by the main program.

    POP              ; Low byte of the return address
    STA RET
    POP              ; High byte of the return address
    STA RET+1
    POP              ; Retrieves the parameter
    STA PARAM

    ; Computes PARAM * 2
    LDA PARAM
    ADD PARAM
    STA RESULT

    ; Restores the return address.
    ; RET first pops the low byte and then the high byte.
    ; Since PUSH stores the value and decrements SP, we push the high byte first.

    LDA RET+1
    PUSH
    LDA RET
    PUSH
    LDA RESULT       ; Returns the result in the accumulator
    RET

RET:    DW 0         ; Return address saved by the subroutine
PARAM:  DB 0
RESULT: DB 0

END 0

9.4. Virtual Graphic Display

Configures video memory at 0x4000, clears the screen, draws a filled rectangle, a line, and a circle:

ORG 0

MAIN:
    LDA #20
    TRAP VIDEO_CONFIG
    OR #0
    JNZ ERROR

    LDA #21
    TRAP CLEAR

    LDA #24
    TRAP RECTANGLE

    LDA #23
    TRAP LINE

    LDA #25
    TRAP CIRCLE

    HLT

ERROR:
    HLT

VIDEO_CONFIG:
    DW VIDEO_BASE

CLEAR:
    DB 3              ; blue

RECTANGLE:
    DB 48, 16, 32, 32, 224, 1

LINE:
    DB 0, 63, 127, 0, 28

CIRCLE:
    DB 64, 32, 18, 252, 0

VIDEO_BASE EQU 16384 ; 0x4000

END MAIN

10. Troubleshooting Common Issues

Error: “Invalid Instruction”

Error: “Undefined Label”

Program does not execute after compiling

Breakpoint does not work

Memory does not update during execution

IN does not read the typed value

Graphic display does not show the drawing

11. Tips and Best Practices

12. Conclusion

SimuS is a complete tool for learning computer architecture and assembly programming. Through its intuitive interface and advanced debugging features, students can experiment with fundamental concepts such as:

This manual covers the essential aspects of the simulator. For additional questions or technical support, consult the Sapiens processor documentation or contact the developer.

Happy studying and happy programming!