ygrec8/VHDL/vy8/vy8.txt
created sam. 18 nov. 2023 21:07:21 CET by whygee@f-cpu.org

vy8 is the Virtual YGREC8.

This software is an assembler, disassembler, simulator, cosimulation environment and way more.

It's an old-school-looking command line interface tool written in VHDL, compiled with GHDL
with minimal help from external C/POSIX glue logic. It uses a modular structure and the commands
help control their setup and behaviour.

The vy8 can simulate a fully featured YGREC8 system though it's not realistic,
use a YASEP instead if such a large configuration is required, you'll spend no time
switching banks.

The program takes data from STDIN, line by line.
A preliminary file can be included before interactive mode
with a bash command such as

cat script - | ./vy8

The program stops when EOF is reached, for example at the end
of a script file or when hitting CTRL-D. The command QUIT
also ends an interactive session.




There are several resources :

* Data RAM : Up to 256 banks of 256 bytes.
By default, Bank 0 is mapped to D1/A1 and Bank 1 to D2/A2.
More banks can be created or destroyed on demand during
simulations. Data from each bank can be saved to or loaded
from a .HYX file, or inspected/dumped and edited by commands.

* Program RAM : Up to 256 overlays of 256 instructions (512 bytes).
Overlay 0 is created at startup. More overlays can be created
from .HYX files, .y8 files or assembled inline.

* Core state / Registers : the user can read and write to
core registers. This includes some values mapped to the I/O space.

* I/O Registers : the 512 I/O registers can be read and written to.
Modules can be added (in the VHDL code) to emulate new functions
and tie them to the host computer.

* Symbol table : dynamic, built by the the assembly of source code,
  or imported by the .Y8 .EQU dumps

The Symbol Table could be filled by the IOReg module to define
the address of the registers, then the table can be exported
and reassembled later for a different target.





Summary of commands :
(commands are case-agnostic)

Q,
QUIT (or CTRL-D) : terminate the program.

?,
HELP : this screen

START : Start the program
STEP (N) : execute (N) instruction(s)
SKIP : skip the current instruction (don't execute/commit it)
RESET

Ctrl-C : interrupts a long simulation

BP (o:)a : set a program breakpoint at address a of overlay o
DBP (o:)a : delete the breakpoint
LBP : list breakpoints

WD (b:)a : set a watch data at address a of bank b
DWD (b:)a : delete the watch data
LWD : List Watch Data

LD b FILE : load data bank b from FILE
SD b FILE : store data bank b to FILE
list a (+)b : display hexdump from address a to b (or a count of +b bytes)
DUMP  : dump the whole data space to file
RECOVER  : restore the whole data space from file
FILL d n (a) : fill the data space with byte d,
   n times, starting at address a
edit data ?...

LP o FILE : load program to overlay b from FILE
SP o FILE : store overlay b to FILE

OV : read the current overlay number
OV o : set current overlay to o

BK1 (a) : read or set the bank registers
BK2 (a)

ASM (a) : enter assembly language (starting at address a)
   (end entry with .END or Ctrl-C)

STATE : show the value of the core registers

create and delete symbols

enable real-time periodic events and change frequency
(POSIX events, SIG_ALRM, ...)