------------------ LaRVaVideo microcontroller example design ------------------

                               J. Arias (2025)

-------------------------------------------------------------------------------

How to test it on an Alhambra-II board:

1 - Program the FPGA bitstream into the flash:

   iceprog main.bin      (or "make burn")
  
2 - Program the RISC-V code into the flash:

   cd flashcode
   iceprog -o 192k -p code.bin    (or "make burn");
  
3 - Open a serial terminal 

    Port: "/dev/ttyUSB1" (linux) or the proper COM port on Windows
    Baud rate: 115200
    Parity: None
    Flow Control: None
    CR LF: Auto
    
4 - Press the reset button. if all goes well this message is displayed:

	LaRVa ][  debugger

	J.Arias (2025)

	And 2 seconds later the debugger screen is displayed:

	   X0       X1       X2       X3       X4       X5       X6       X7    
	--zero-- 20031490 00003BD4 00000000 00000000 00000000 00000000 00000000 
	   X8       X9       X10      X11      X12      X13      X14      X15   
	00066000 00000010 00000000 FFFE3BF4 FFFE3BE0 00000000 E0000000 000000C0 
	   brk    IRQEN
	--------    C0

	200314B4: 00066437  LUI     X8, 00066
	   PC
	200314B8: 3B440413  ADDI    X8, X8, 948
	200314BC: E00006B7  LUI     X13, E0000
	200314C0: 0206C783  LBU     X15, 32 (X13)
	200314C4: 00040513  ADDI    X10, X8, 0
	200314C8: 0FF7F793  ANDI    X15, X15, 255
	200314CC: 00179713  SLLI    X14, X15, 1
	200314D0: 0077D793  SRLI    X15, X15, 7
	200314D4: 00F767B3  OR      X15, X14, X15
	200314D8: 0FF7F793  ANDI    X15, X15, 255
	200314DC: 02F68023  SB      X15, 32 (X13)
	200314E0: B81FE0EF  JAL     X1, 20030060
	200314E4: FD9FF06F  J       200314BC
	200314E8: 20031134  ?     
	200314EC: 20031284  ?     

	hcsnrRbgxdmwl>h

	Pressing the "h" key:
	Commands:
	 h:     Help
	 c:     Continue
	 s:     execute Single instruction
	 n:     execute until Next instruction
	 r:     execute until subroutine Return (any)
	 R:     execute until Return at higher stack level
	 b:     set Breakpoint
	 B:     set Data Breakpoint
	 g:     Goto (change PC)
	 x:     change X register
	 d:     Dissasemble
	 m:     Memory dump
	 w:     memory Write
	 l:     Load code to debug
	 a:     Alternate register names
	 ctrl-c Pauses execution

	hcsnrRbgxdmwl>

	Also, a VGA video signal is generated for an AP-VGA shield (D0-D7 pins).
	A monochrome white & blue image displays all the internal RAM bits as pixels.

TESTING OTHER CODES

1 - RUNNING CODE on RAM:

In the folder "apps" is a program example ready to be loaded. The steps
to follow are:

   Press "l" on the serial terminal. It displays:
   
      Upload code to debug...

   Then, dump the "code.bin" content over the serial port. An 'L' is displayed
   while loading, and then the debugger stops at the first instruction of the
   loaded program:
   
	   X0       X1       X2       X3       X4       X5       X6       X7    
	--zero-- 200300A0 00003BE0 00000000 20030094 00001A7C 00001A7C 00000010 
	   X8       X9       X10      X11      X12      X13      X14      X15   
	00066000 00000010 000000C0 00000010 FFFE3BE0 E0000000 E0000000 000000C0 
	   brk    IRQEN
	--------    C0

	0000000C: 00000000  ?     
	   PC
	00000010: 00002517  AUIPC   X10, 
	00000014: A6C50513  ADDI    X10, X10, -1428
	00000018: 00003597  AUIPC   X11, 
	0000001C: 27858593  ADDI    X11, X11, 632
	00000020: 00B55863  BGE     X10, X11, 00000030
	00000024: 00052023  SW      X0, 0 (X10)
	00000028: 00450513  ADDI    X10, X10, 4
	0000002C: FEB54CE3  BLT     X10, X11, 00000024
	00000030: 691000EF  JAL     X1, 00000EC0
	00000034: 0000006F  J       00000034
	00000038: FFF50513  ADDI    X10, X10, -1
	0000003C: FE051EE3  BNE     X10, X0, 00000038
	00000040: 00008067  JALR    X0, 0 (X1)
	00000044: E0000737  LUI     X14, E0000

	hcsnrRbgxdmwl> 

    Now, just press 'c' (continue execution) and the program starts:

    Command [mfbgts]>
    
    Here the keys 'm', 'f', and  'b', changes the video mode and the colors,
    while 't' runs a FFT speed test and 's' an Erathostenes sieve test. 'g'
    jumps back to the debugger. Example:
	
	Command [mfbgts]> t
	Testing ...................................................................
	1372 ms
	Command [mfbgts]> 
	
	The debugger can be invoked at any time by just typing 'ctrl-C'. First, it
	just waits for a keypress before redrawing the screen:
	
	<pause>
	   X0       X1       X2       X3       X4       X5       X6       X7    
	--zero-- 00000F48 00003BC0 00000000 20030094 00003B6B 00001FC0 00003BB0 
	   X8       X9       X10      X11      X12      X13      X14      X15   
	00001204 00002000 00000000 0000001E 00000050 00003000 E0000000 00000000 
	   brk    IRQEN
	--------    C0

	00000044: E0000737  LUI     X14, E0000
	   PC
	00000048: 00472783  LW      X15, 4 (X14)
	0000004C: 0017F793  ANDI    X15, X15, 1
	00000050: FE078CE3  BEQ     X15, X0, 00000048
	00000054: 00074503  LBU     X10, 0 (X14)
	00000058: 0FF57513  ANDI    X10, X10, 255
	0000005C: 00008067  JALR    X0, 0 (X1)
	00000060: E00007B7  LUI     X15, E0000
	00000064: 0407C783  LBU     X15, 64 (X15)
	00000068: 0FF7F713  ANDI    X14, X15, 255
	0000006C: 0017F793  ANDI    X15, X15, 1
	00000070: 06078A63  BEQ     X15, X0, 000000e4
	00000074: 000017B7  LUI     X15, 00001
	00000078: 2C078793  ADDI    X15, X15, 704
	0000007C: 00277693  ANDI    X13, X14, 2

	hcsnrRbgxdmwl>
	
2 - RUNNING CODE ON FLASH

In the "apps" folder the same program is also ready to be programmed on a 
different flash address with the command:

	iceprog -o 640k codeflash.bin

Then enter the debugger and type 'g' (goto) followed by the hex address:

	hcsnrRbgxdmwl> g  200a0000
	
This makes the PC to point to the application code in the flash. Then, type 'c'
(continue) and the application runs:

	Command [mfbgts]> t
	Testing ...................................................................
	2416 ms
	Command [mfbgts]>

Notice the test takes a longer time to run when on flash due to cache misses.