Friday 11 February 2022

Dot matrix arcade

Debugger

r00

r10

r20

r30

ip0

sp0

zero0

carry0

Code

# Use the buttons to move the dot. This program draws a dot at the position
# stored in memory, reads the state of the buttons, updates the dot's
# position according to which button is pressed, and then does it all again.

### Code ###

:loop                                  ### The loop runs continuously,
                                       ### drawing and moving the dot.

:draw                                  ### Draw dot at current position.
  read_r2 @x                           # Read x-coordinate from memory.
  read_r3 @y                           # Read y-coordinate from memory.
  shift_left_r3 4                      # Move y-coordinate to upper bits.
  or_r2_r3                             # Combine x- and y-coordinates.
  out_r2                               # Draw dot.

:delay                                 ### Wait for a bit, otherwise display
                                       ### will flicker and dot will move
                                       ### too fast.
  set_r0 255                           # Initialize inner delay loop.
  set_r1 255                           # Initialize outer delay loop.
:delay_loop
  decrement_r0                         # Count down inner delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.
  decrement_r1                         # Count down outer delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.

:clear                                 ### Clear dot from display. Position
                                       ### is still in r2, set when drawing.
  out_r2                               # Clear dot.

:process_input                         ### Get state of buttons and move dot
                                       ### accordingly.
  read_r2 @x                           # Read current position so we can
  read_r3 @y                           #  apply movement.
  in_r0                                # Read input state of buttons.
:move_left
  set_r1 1                             # Create bit mask for left-button.
  and_r1_r0                            # Apply bit mask to input state.
  jump_if_zero @move_right             # If button isn't pressed, skip
                                       # movement to the left.
  compare_r2 0                         # Check if dot is already at leftmost
                                       # edge of the display.
  jump_if_equal @move_right            # If so, skip movement to the left.
  decrement_r2                         # Move left.
:move_right
  set_r1 8                             # Create bit mask for right-button.
  and_r1_r0                            # Apply bit mask to input state.
  jump_if_zero @move_up                # If button isn't pressed, skip
                                       # movement to the right.
  compare_r2 15                        # Check if dot is already at
                                       # rightmost edge of the display.
  jump_if_equal @move_up               # If so, skip movement to the right.
  increment_r2                         # Move right.
:move_up
  set_r1 2                             # Create bit mask for up-button.
  and_r1_r0                            # Apply bit mask to input state.
  jump_if_zero @move_down              # If button isn't pressed, skip
                                       # movement up.
  compare_r3 0                         # Check if dot is already at top edge
                                       # of the display.
  jump_if_equal @move_down             # If so, skip movement up.
  decrement_r3                         # Move up.
:move_down
  set_r1 4                             # Create bit mask for down-button.
  and_r1_r0                            # Apply bit mask to input state.
  jump_if_zero @store_position         # If button isn't pressed, skip
                                       # movement down.
  compare_r3 15                        # Check if dot is already at bottom
                                       # edge of the display.
  jump_if_equal @store_position        # If so, skip movement down.
  increment_r3                         # Move down.

:store_position                        ### Store the dot's current position
                                       ### so we can use it in next
                                       ### iteration of the loop.
  write_r2 @x                          # Write x-coordinate.
  write_r3 @y                          # Write y-coordinate.

  jump @draw                           # Frame is done; on to the next.

### Data ###

:x 8 :y 8                              # Current position of dot.

### Code ###

:loop                                  ### Start of frame.

:draw                                  ### Draw dot at current position.
  read_r0 @x                           # Read x-coordinate from memory.
  read_r1 @y                           # Read y-coordinate from memory.
  shift_right_r0 4                     # Only use upper four bits of x.
  set_r2 240                           # Create mask to clear lower four
                                       #  bits of y.
  and_r1_r2                            # Apply mask.
  or_r0_r1                             # Combine x- and y-coordinates.
  out_r0                               # Draw dot.

:delay                                 ### Wait for a bit, otherwise display
                                       ### will flicker and dot will move
                                       ### too fast.
  set_r2 255                           # Initialize inner delay loop.
  set_r3 255                           # Initialize outer delay loop.
:delay_loop
  decrement_r2                         # Count down inner delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.
  decrement_r3                         # Count down outer delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.

:clear                                 ### Clear dot from display. Position
                                       ### is still in r0, set when drawing.
  out_r0                               # Clear dot.

:move_dot                              ### Move to the dot by adding the
                                       ### delta to the current position. If
                                       ### the dot reaches the edge of the
                                       ### display, it will bounce by making
                                       ### the delta point in the opposite
                                       ### direction

:move_horizontally
  read_r0 @x                           # Read x-position from memory.
  
:left_bounce                           ### Check to see if dot should bounce
                                       ### off left edge by first seeing if
                                       ### it's moving to the left and then
                                       ### checking if it's about to cross
                                       ### the edge.
  read_r1 @delta_x                     # Read x-movement from memory.
  shift_left_r1 1                      # Move upper bit of movement into
                                       #  carry flag. This bit is set if
                                       #  delta is negative, meaning dot is
                                       #  moving left.
  jump_if_not_carry @right_bounce      # If dot moves right, go check for
                                       #  bounce at right edge.
  read_r1 @delta_x                     # Movement changed; read it again.
  negate_r1                            # Use positive movement for compare.
  compare_r0_r1                        # Will dot cross left edge?
  jump_if_greater_or_equal @update_x   # If not, skip bounce.
  write_r1 @delta_x                    # Movement was already flipped for
                                       #  comparison; store it.
  jump @update_x                       # Skip right edge bounce.

:right_bounce                          ### Check to see if dot should bounce
                                       ### off right edge by checking if
                                       ### it's about to cross the edge. We
                                       ### know it's moving to the right,
                                       ### because that was already checked
                                       ### during left bounce check.
  read_r1 @delta_x                     # Read x-movement from memory.
  add_r1_r0                            # Check if calculating new position
                                       #  would cause an overflow, meaning
                                       #  dot crosses right edge.
  jump_if_not_carry @update_x          # If not, skip bounce.
  read_r1 @delta_x                     # Movement changed; read it again.
  negate_r1                            # Flip movement in x-direction.
  write_r1 @delta_x                    # Write movement to memory.

:update_x
  read_r1 @delta_x                     # Read x-movement from memory.
  add_r0_r1                            # Update x-position.
  write_r0 @x                          # Write result to memory.

:move_vertically
  read_r0 @y                           # Read y-position from memory.
  
:top_bounce                            ### Check to see if dot should bounce
                                       ### off top edge by first seeing if
                                       ### it's moving to the top and then
                                       ### checking if it's about to cross
                                       ### the edge.
  read_r1 @delta_y                     # Read y-movement from memory.
  shift_left_r1 1                      # Move upper bit of movement into
                                       #  carry flag. This bit is set if
                                       #  delta is negative, meaning dot is
                                       #  moving up.
  jump_if_not_carry @bottom_bounce     # If dot moves down, go check for
                                       #  bounce at bottom edge.
  read_r1 @delta_y                     # Movement changed; read it again.
  negate_r1                            # Use positive movement for compare.
  compare_r0_r1                        # Will dot cross top edge?
  jump_if_greater_or_equal @update_y   # If not, skip bounce.
  write_r1 @delta_y                    # Movement was already flipped for
                                       #  comparison; store it.
  jump @update_y                       # Skip bottom edge bounce.

:bottom_bounce                         ### Check to see if dot should bounce
                                       ### off bottom edge by checking if
                                       ### it's about to cross the edge. We
                                       ### know it's moving down, because
                                       ### that was already checked during
                                       ### top bounce check.
  read_r1 @delta_y                     # Read y-movement from memory.
  add_r1_r0                            # Check if calculating new position
                                       #  would cause an overflow, meaning
                                       #  dot crosses bottom edge.
  jump_if_not_carry @update_y          # If not, skip bounce.
  read_r1 @delta_y                     # Movement changed; read it again.
  negate_r1                            # Flip movement in y-direction.
  write_r1 @delta_y                    # Write movement to memory.

:update_y
  read_r1 @delta_y                     # Read y-movement from memory.
  add_r0_r1                            # Update y-position.
  write_r0 @y                          # Write result to memory.
  
  jump @draw                           # Frame is done; on to the next.

### Data ###

:x 128 :y 128                          # Current position of the dot,
                                       #  shifted to the upper four bits to
                                       #  allow for movement that's slower
                                       #  than one spot per frame.
:delta_x 16 :delta_y 8                 # Movement speed of the dot in 1/16th
                                       #  spots per frame, so 16 means the
                                       #  dot moves one spot per frame and
                                       #  8 means the dot moves one spot
                                       #  every two frames.

# This program draws a dot at the position stored in memory, moves the dot,
# bounces the dot off the edges, and then does it all again. Buttons don't
# do anything.

### Code ###

:loop                                  ### Start of frame.

:draw                                  ### Draw dot at current position.
  read_r0 @x                           # Read x-coordinate from memory.
  read_r1 @y                           # Read y-coordinate from memory.
  shift_left_r1 4                      # Move y-coordinate to upper bits.
  or_r0_r1                             # Combine x- and y-coordinates.
  out_r0                               # Draw dot.

:delay                                 ### Wait for a bit, otherwise display
                                       ### will flicker and dot will move
                                       ### too fast.
  set_r2 255                           # Initialize inner delay loop.
  set_r3 255                           # Initialize outer delay loop.
:delay_loop
  decrement_r2                         # Count down inner delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.
  decrement_r3                         # Count down outer delay loop.
  jump_if_not_zero @delay_loop         # If not done waiting, keep counting.

:clear                                 ### Clear dot from display. Position
                                       ### is still in r0, set when drawing.
  out_r0                               # Clear dot.

:move_dot                              ### Move to the dot by adding the
                                       ### delta to the current position. If
                                       ### the dot reaches the edge of the
                                       ### display, it will bounce by making
                                       ### the delta point in the opposite
                                       ### direction.

:move_horizontally
  read_r0 @x                           # Read x-position from memory.
  read_r1 @delta_x                     # Read x-movement from memory.
  
:left_bounce                           ### Check to see if dot should bounce
                                       ### off left edge.
  compare_r0 0                         # Is dot in leftmost position?
  jump_if_not_equal @right_bounce      # If not, skip bounce.
  negate_r1                            # Flip x-movement direction.

:right_bounce                          ### Check to see if dot should bounce
                                       ### off right edge.
  compare_r0 15                        # Is dot in rightmost position?
  jump_if_not_equal @update_x          # If not, skip bounce.
  negate_r1                            # Flip x-movement direction.

:update_x
  add_r0_r1                            # Update x-position.
  write_r0 @x                          # Write position to memory.
  write_r1 @delta_x                    # Write movement to memory.

:move_vertically
  read_r0 @y                           # Read y-position from memory.
  read_r1 @delta_y                     # Read y-movement from memory.
  
:top_bounce                            ### Check to see if dot should bounce
                                       ### off top edge.
  compare_r0 0                         # Is dot in topmost position?
  jump_if_not_equal @bottom_bounce     # If not, skip bounce.
  negate_r1                            # Flip y-movement direction.

:bottom_bounce                         ### Check to see if dot should bounce
                                       ### off bottom edge.
  compare_r0 15                        # Is dot in bottommost position?
  jump_if_not_equal @update_y          # If not, skip bounce.
  negate_r1                            # Flip y-movement direction.

:update_y
  add_r0_r1                            # Update y-position.
  write_r0 @y                          # Write position to memory.
  write_r1 @delta_y                    # Write movement to memory.
  
  jump @loop                           # Frame is done; on to the next.

### Data ###

:x 1 :y 8                             # Current position of the dot.
:delta_x 1 :delta_y 1                 # Movement speed of the dot.

# A Breakout-clone in 238 bytes. Use the buttons to move the paddle. Bounce
# the ball of the blocks to break them. Break all the blocks to win the
# best price of all: satisfaction.
        
set_stack_pointer @stack

### Main loop ###

:update_paddle
  read_r0 @paddle
  in_r1
  :paddle_left
    shift_right_r1 1
    jump_if_not_carry @paddle_right
    compare_r0 0
    jump_if_equal @paddle_done
    decrement_r0
  :paddle_right
    shift_right_r1 3
    jump_if_not_carry @paddle_done
    compare_r0 13
    jump_if_equal @paddle_done
    increment_r0
  :paddle_done
    write_r0 @paddle

:update_ball
  :paddle_bounce
    call @read_ball
    compare_r1 1
    jump_if_not_equal @edge_bounce
    compare_r3 255
    jump_if_not_equal @edge_bounce
    add_r0_r2
    call @touches_paddle
    jump_if_not_equal @edge_bounce
    negate_r3
    subtract_r0_r2
    call @touches_paddle
    jump_if_equal @write_ball_delta
    negate_r2
    jump @write_ball_delta

  :edge_bounce
    :side_bounce
      call @read_ball
      add_r0_r2
      compare_r0 16
      read_r0 @ball_x
      jump_if_smaller_than @bottom_bounce
      negate_r2
      jump @ball_done
    :bottom_bounce
      compare_r3 1
      jump_if_not_equal @top_bounce
      compare_r1 15
      jump_if_not_equal @block_bounce
      negate_r3
      jump @ball_done
    :top_bounce
      compare_r1 0
    :halt
      jump_if_equal @halt

  :block_bounce
    call @read_ball
    add_r0_r2
    add_r1_r3
    call @is_block
    jump_if_not_equal @ball_done
    :ball_bounce_x
      read_r1 @ball_y
      call @find_block
      jump_if_not_equal @ball_bounce_y
      call @remove_block
      call @read_ball
      negate_r2
      jump @ball_done
    :ball_bounce_y
      call @read_ball
      add_r1_r3
      call @find_block
      jump_if_not_equal @ball_bounce_xy
      call @remove_block
      call @read_ball
      negate_r3
      jump @ball_done
    :ball_bounce_xy
      call @read_ball
      add_r0_r2
      add_r1_r3
      call @find_block
      call @remove_block
      call @read_ball
      negate_r2
      negate_r3
  :ball_done
    write_r0 @ball_x
    write_r1 @ball_y
  :write_ball_delta
    write_r2 @ball_dx
    write_r3 @ball_dy

call @draw

:delay
  set_r0 0
  set_r1 0
  :delay_loop
    decrement_r0
    jump_if_not_zero @delay_loop
    decrement_r1
    jump_if_not_zero @delay_loop

call @draw
jump @update_paddle

### Functions ###

:read_ball
  read_r0 @ball_x
  read_r1 @ball_y
  read_r2 @ball_dx
  read_r3 @ball_dy
return

:touches_paddle
  read_r1 @paddle
  compare_r0_r1
  jump_if_smaller_than @end_touches_paddle
  negate_r1
  add_r1_r0
  compare_r1 2
  jump_if_greater_than @end_touches_paddle
  set_zero  
  :end_touches_paddle
return

:is_block
  push_all
  call @find_block
  pop_all
return

# out r0: address
# out r2: group
# out r3: bitmask
# out zero: is_block
:find_block
  set_r2 12
  subtract_r1_r2
  jump_if_smaller_than @end_find_block
  shift_left_r1 4
  add_r0_r1
  set_r1 8
  divide
  set_r2 @blocks
  add_r0_r2
  read_by_pointer_r2_r0
  set_r3 1
  shift_left_r3_r1
  push_r2
  not_r2
  and_r2_r3
  pop_r2
:end_find_block
return

:remove_block
  not_r3
  and_r2_r3
  write_by_pointer_r0_r2
return


:draw
  :draw_paddle
    read_r0 @paddle
    out_r0
    increment_r0
    out_r0
    increment_r0
    out_r0

  :draw_ball
    read_r0 @ball_x
    read_r1 @ball_y
    shift_left_r1 4
    or_r0_r1
    out_r0

  :draw_blocks
    set_r0 @blocks # pointer to group
    set_r1 192 # output coordinates
    :draw_group
      read_by_pointer_r2_r0 # group
      set_r3 8 # number of bits
      :draw_bit
        shift_right_r2 1
        jump_if_not_carry @next_bit
        out_r1
      :next_bit
        increment_r1
        decrement_r3
        jump_if_not_zero @draw_bit
    :next_group
      increment_r0
      compare_r0 @end_of_blocks
      jump_if_not_equal @draw_group

return

### Data ###

:paddle 6
:ball_x 6
:ball_y 1
:ball_dx 1
:ball_dy 255
:blocks 126 126 126 126 126 126 0 0
:end_of_blocks

:stack

Manual

The dot matrix arcade is an 8-bit machine running at 2 MHz, because any faster would render it unusable. It has 256 bytes of memory and that's for code and data combined. That's not enough to do anything useful, but it's plenty to do something interesting.

Display

The 8-bit output port is connected to a 16 by 16 dot matrix display. What it lacks in resolution, it makes up for in pixel size. You can toggle a dots on or off by sending a byte to the output port where the lower four bits contain the x-coordinate and the upper for bits contain the y-coordinate.

Buttons

The 8-bit output port is connected to eight buttons. Four of the buttons are invisible, though; that may or may not be considered a feature. You can get the state of the buttons by reading a byte from the input port. Each bit in that byte represents the state of a button: 1 means the button is down, 0 means the button is up.

Registers

There are four general purpose registers, called r0, r1, r2, and r3. They can be used to store values and perform arithmetic as needed.

There are two special purpose registers.

instruction pointer: Contains the memory address of the next instruction the processor will execute.
stack pointer: Contains the memory address of the top of the stack. The top of the stack is where the next value will be stored, so it doesn't contain a value yet. The stack pointer increases every time a value is pushed and decreases every time a value is popped.

Flags

A flags is a single bit that tells you something about the result of the last executed instruction.

zero: If the result of the last instruction was zero, this flag will be 1. Compare-instructions set this flag to 1 if two values are equal.
carry: If the result of the last instruction produced a carry—for example because an addition was greater than 255 or a subtraction was smaller than 0—then this flag will be 1. Compare-instructions set this flag to 1 if the left value was smaller than the right value.

Flags are only set by specific instructions. Check the instruction set for more information.

Instruction set

These are all the instructions the dot matrix machine supports. Some instructions are available for all general purpose registers. In that case, the manual uses the notation rd for destination register and rs for source register. For example, set_rd_rs means that there's an instruction for set_r0_r1, set_r0_r2, set_r0_r3, set_r1_r0, etc.

If an instruction updates a flag, it's noted in the description.

add_rd_rs: Calculate rd + rs and store the result in register d. Set the zero flag if the result is 0; clear it if not. Set the carry flag if the result is greater than 255; clear it if not.
and_rd_rs: Calculate rd bitwise-and rs and store the result in register d. Set the zero flag if the result is 0; clear it if not.
call address: Push the address of the next instruction onto the stack and jump to the instruction at address.
clear_carry: Set the carry flag to 0.
clear_zero: Set the zero flag to 0.
compare_rs value: Set the zero flag if register s is equal to value; clear it if not. Set the carry flag if register d is smaller than value; clear it if not.
compare_rd_rs: Set the zero flag if register d is equal to register s; clear it if not. Set the carry flag if register d is smaller than register s; clear it if not.
decrement_rd: Calculate rd - 1 and store the result in register d. Set the zero flag if the result is 0; clear it if not. Set the carry flag if the result is 255; clear it if not.
divide: Calculate r0 / r1 and store the result in r0, and calculate r0 module r1 and store the result in r1. Set the zero flag if the result is 0; clear it if not. Set the carry flag if r1 is 0 before the calculation; clear it if not.
in_rd: Read the device connected to the input port and store the result in register d.
increment_rd: Calculate rd + 1 and store the result in register d. Set the zero flag if the result is 0; clear it if not. Set the carry flag if the result is 0; clear it if not.
jump address: Jump to the instruction at address.
jump_if_equal address: Jump to the instruction at address if the zero flag is not set. Same as jump_if_zero.
jump_if_not_carry address: Jump to the instruction at address if the carry flag is not set.
jump_if_not_equal address: Jump to the instruction at address if the zero flag is set. Same as jump_if_not_zero.
jump_if_not_zero address: Jump to the instruction at address if the zero flag is not set. Same as jump_if_not_equal.
jump_if_carry address: Jump to the instruction at address if the carry flag is set.
jump_if_greater_or_equal address: Jump to the instruction at address if the carry flag is set and the zero flag is set.
jump_if_greater_than address: Jump to the instruction at address if the carry flag is set and the zero flag is not set.
jump_if_smaller_or_equal address: Jump to the instruction at address if the carry flag is set and the zero flag is not set.
jump_if_smaller_than address: Jump to the instruction at address if the carry flag is not set and the zero flag is not set.
jump_if_zero address: Jump to the instruction at address if the zero flag is set. Same as jump_if_equal.
multiply: Calculate r0 * r1 and store the lower eight bits of the result in r0 and the upper eight bits of the result in r1. Set the zero flag if the result 0; clear it if not. Set the carry flag if the result is greater than 255; clear it if not.
negate_rd: Calculate the two's complement of register d—i.e. flipping its sign—and store the result in register d. Set the zero flag if the result is 0; clear it if not.
nop: Do nothing.
not_rd: Calculate bitwise-not rd and store the result in register d. Set the zero flag if the result is 0; clear it if not.
or_rd_rs: Calculate rd bitwise-or rs and store the result in register d. Set the zero flag if the result is 0; clear it if not.
out_rs: Send the value stored in register s to the device connected to the output port.
pop_all: Pop four values of the stack and store them in the general purpose registers in the order r3, r2, r1, r0.
push_all: Push the contents of all general purpose registers onto the stack in the order r0, r1, r2, r3.
push_instruction_pointer: Push the contents of the instruction pointer onto the stack.
push_rs: Push the contents of register s onto the stack.
push_stack_pointer: Push the contents of the stack pointer onto the stack.
read_by_pointer_rd_rs: Read the value in memory that's stored at the address in register s and store it in register d.
read_rd address: Read the value in memory that's stored at address an store it in register d.
return: Pop an address of the stack and jump to the instruction at that address.
set_carry: Set the carry flag to 1.
set_rd value: Store value in register d.
set_rd_rs: Copy the contents of register d to register s.
set_stack_pointer address: Move the stack pointer to address.
set_zero: Set the zero flag to 1.
shift_left_rd value: Shift the bits in register d value places to the left, filling in zeros as needed. Set the zero flag if the result is 0; clear it if not. Set the carry flag to the last bit shifted out.
shift_right_rd value: Shift the bits in register d value places to the right, filling in zeros as needed. Set the zero flag if the result is 0; clear it if not. Set the carry flag to the last bit shifted out.
subtract_rd_rs: Calculate rd - rs and store the result in register d. Set the zero flag if the result is 0; clear it if not. Set the carry flag if the result is smaller than 0; clear it if not.
write_by_pointer_rd_rs: Write the value in register s to memory at the address stored in register d.
write_rs address: Write the value in register s to memory at address.
xor_rd_rs: Calculate rd bitwise-xor rs and store the result in register d. Set the zero flag if the result is 0; clear it if not.