6502/vm6502
1
0
Fork 0
mirror of https://github.com/makarcz/vm6502.git synced 2025-01-14 12:33:39 +00:00
Code Issues Projects Releases Wiki Activity
vm6502/ProgrammersReferenceManual.txt
Marek Karcz b730b0cb1a Fix typo in manual. 
Correct typo in Programmers Reference Manual.
2018-09-07 02:13:47 -04:00

881 lines
35 KiB
Plaintext
Raw Blame History

User Manual and Programmers Reference Manual for VM65.
by
Marek Karcz (C) 2016.
1. Introduction.
VM65 is a simulator which can be expanded to become an emulator of more
complex computer system either a real one or completely abstract virtual
machine.
VM65 acronym stands for Virtual Machine 65 and is designed for MOS-6502
simulation. In current form it allows to simulate a MOS-6502 CPU in
MS Windows environment using MS-DOS command line UI.
Software emulates all original MOS-6502 legal opcodes. The illegal opcodes
are not emulated and are opened for expansion. It is up to programmer to
implement illegal opcodes accurate emulation or replace them with extensions
or traps. In current version they do nothing except to consume CPU cycles.
The 6502 emulation is not purely abstract. The basic components of a real
hardware CPU system are emulated: microprocessor, memory and memory mapped
devices abstract layer - about which more in section 4.
Using this software user will be able to load plain text memory definition
file, Intel HEX format file, raw binary image file or binary snapshot image
created with this software and execute or debug code within it in
a continuous or in step-by-step mode.
The file will be loaded and translated to the emulated memory space and
optional emulation parameters included in the image will be interpreted and
adequately translated into values of the corresponding internal flags.
It is possible to automatically run program starting at specified address,
perform automatic reset of the CPU after memory image upload or perform
these actions from command line prompt of the debug console.
2. Command Line Interface and Debug Console.
Usage:
vm65 [-h] | [ramdeffile] [-b | -x] [-r]
Where:
ramdeffile - RAM definition file name
-b - specify input format as binary
-x - specify input format as Intel HEX
-r - after loading, perform CPU RESET
-h - print this help screen
When ran with no arguments, program will load default memory
definition files: default.rom, default.ram and will enter the debug
console menu.
When ramdeffile argument is provided with no input format specified,
program will attempt to automatically detect input format and load the
memory definition from the file, set the flags and parameters depending
on the contents of the memory definition file and enter the corresponding
mode of operation as defined in that file.
If input format is specified (-b|-x), program will load memory from the
provided image file and enter the debug console menu.
To start program, navigate to the program directory in MS-DOS prompt console
and type:
vm65
Above will run the emulator. Since no memory image is specified, program
will attempt to load dummy.rom and dummy.ram files, which supposed to be
plain text memory image definition files. The simplest you can create can
look like this:
ORG
$0000
$00
NOTE: To see the full usage help for vm65, use flag -h:
vm65 -h
Program loaded with no arguments will present user with following UI
which will be referred to as Debug Console:
STOPPED at 0
Emulation performance stats is OFF.
*-------------*-----------------------*----------*----------*
| PC: $0000 | Acc: $00 (00000000) | X: $00 | Y: $00 |
*-------------*-----------------------*----------*----------*
| NV-BDIZC | :
| 00100000 | :
*-------------*
Stack: $ff
[]
I/O status: disabled, at: $e000, local echo: OFF.
Graphics status: disabled, at: $e002
ROM: disabled. Range: $d000 - $dfff.
Op-code execute history: disabled.
------------------------------------+----------------------------------------
C - continue, S - step | A - set address for next step
G - go/cont. from new address | N - go number of steps, P - IRQ
I - toggle char I/O emulation | X - execute from new address
T - show I/O console | B - blank (clear) screen
E - toggle I/O local echo | F - toggle registers animation
J - set animation delay | M - dump memory, W - write memory
K - toggle ROM emulation | R - show registers, Y - snapshot
L - load memory image | O - display op-code exec. history
D - disassemble code in memory | Q - quit, 0 - reset, H - help
V - toggle graphics emulation | U - enable/disable exec. history
Z - enable/disable debug traces | 1 - enable/disable perf. stats
2 - display debug traces | ? - show this menu
------------------------------------+----------------------------------------
>
Upper part of the screen consists of current CPU registers status.
If performance statistics are enabled, they are right above the CPU
registers.
PC shows address of currently executed op-code, while to the right of status
flags below PC is a disassembled (now empty, showing just the ':' signs)
instructions section. It shows 2 lines, 1-st line is the previously executed
instruction while the 2-nd line shows current instruction. Instructions are
shown in binary (hex) and symbolic (disassembled mnemonics, hex arguments)
format.
Accumulator and index registers X and Y values are also shown in the CPU
registers section.
Stack pointer and its contents are displayed below the CPU registers.
The contents of the Processor registers, disassembled executed instructions
and stack pointer and contents are updated dymanically during the multi-step
program debugging.
Below the stack data we have current status of various flags and parameters
that don't belong to emulated CPU.
Next goes the full list of available commands with short descriptions.
The menu of commands is not always displayed. It is usually skipped when
there were no screen actions that could potentially obstruct that menu.
The menu of commands can be always recalled to the screen by issuing
command '?' after the command prompt '>' and pressing ENTER.
Each of the commands in Debug Console is interactive and can be used in two
ways - user can issue command in the prompt, press enter and follow the
instructions/prompts to enter remaining parameters OR if user already knows
the format of the command, all parameters can be entered in a single line.
To see full help for above commands, issue command H in the prompt and press
ENTER.
A quick overview of some of the commands available in Debug Console:
2.1. Code execution and debugging aid commands.
C - Continue
Execute code from current address after it was interrupted.
S - Step
Executes single op-code at current address. The address for the next
step can be changed with command 'A'.
A - Set address for next step
Sets current address to one provided as argument (or prompts for one).
G - Execute (continue) from address.
Asks for (if not provided as argument) address and then executes code.
N - Execute # of steps.
Useful when we want to skip ahead (e.g.: in a loop) and execute multiple
op-codes before next stop. Look also at commands 'F' and 'J' for
features and parameters associated with it.
X - Execute from address.
F - Toggle registers animation.
When in multi-step debug mode (command: N), displaying registers
can be suppressed or, when animation mode is enabled - they will
be continuously displayed after each executed step.
J - Set registers animation delay.
Sets the time added at the end of each execution step in multi
step mode (command: N). The default value is 250 ms. The change
of this parameter will basically set the speed of multi-step code
execution. Greater delay will slow down the execution but improve
readability of the registers in Debug Console as they will not change
as often as if this delay was smaller.
R - Show registers.
Displays current status of CPU registers, flags and stack.
O - Display op-codes execute history.
Show the history of last executed op-codes/instructions, full with
disassembled mnemonic and argument.
D - Disassemble code in memory.
Attempt to disassemble code in specified address range and display
the results (print) on the screen in symbolic form.
0 - Reset.
Run the processor initialization sequence, just like the real CPU
when its RTS signal is set to LOW and HIGH again. CPU will disable
interrupts, copy address from vector $FFFC to processors PC and will
start executing code. Programmer must put initialization routine
under address pointed by $FFFC vector, which will set the arithmetic
mode, initialize stack, I/O devices and enable IRQ if needed before
jumping to main loop. The reset routine disables trapping last RTS
opcode if stack is empty, so the VM will never return from opcodes
execution loop unless user interrupts with CTRL-C or CTRL-Break.
Z - Toggle enable/disable debug traces.
Emulator may produce debug messages that can be helpful when
troubleshooting issues with 6502 code. Since the immediate output
to the same console where emulated program is connected is in many
cases undesired, the debug messages are remembered in an internal
log. The log holds last 200 messages. If enabled, this log can be
recalled with command '2'. When the log is disabled and then enabled
again, the old log messages will be deleted.
2 - Display debug traces.
Displays debug traces log (200 maximum) in 20 messages long pages.
U - Toggle enable/disable op-codes execute history.
See also option 'O'.
This debuggin aid is not needed during normal emulator run, therefore
option to disable this feature was added, mainly because it affects
performance. But in debugging mode, when we often trace code step by
step, the performance compromise may be justified as a trade off for
getting more internal data from the system.
1 - Toggle enable/disable emulation performance statistics.
MKCpu class includes code to measure the emulation speed.
The speed is measured as a % of model 1 MHz MOS-6502. Number of executed
cycles is divided by number of microseconds that passed and multiplied
by 100 to get this figure.
Performance is only measured in the execute/run modes.
It doesn't make much sense in debug/step by step modes, therefore even
when the feature is enabled, the stats are not calculated in these modes
of operation.
Emulation performance feature is useful mainly during the development
cycle of the emulator and since this is a programming framework for
buiding your own virtual machines/CPU emulators, then it is included.
However as with any debugging aid, it affects performance, therefore
option was added to disable it when we just want to run the 6502 code
and enjoy it at maximum possible speed.
2.2. Memory access commands.
M - Dump memory.
Dumps contents of memory, hexadecimal and ASCII formats.
W - Write memory.
Writes provided values to memory starting at specified address.
2.3. I/O devices commands.
I - Toggle char I/O emulation.
Enables/disables basic character I/O emulation. When enabled, all writes
to the specified memory address also writes a character code to
to a virtual console. All reads from specified memory address
are interpreted as console character input.
The base address corresponds to blocking mode character I/O device,
while base address + 1 corresponds to non-blocking character I/O device.
The blocking device waits for the input character - code execution
stops until user enters the keystroke, while in non-blocking mode
the emulator takes the recently entered keystroke from the system
keyboard buffer. That means that implementing the character input
in 6502 assembly/machine code requires a loop reading from non-blocking
address until the character code is different than 0, while in blocking
mode it is enough to just read from I/O address. The emulator will only
proceed when the key was pressed by user.
Examples of 6502 code:
- a 'waiting' character input implemented using non-blocking char I/O
readchar: LDA $E001
BEQ readchar ; A = NULL, keep reading char I/O
RTS ; A = char code
- a 'waiting' character input implemented using blocking char I/O
readchar: LDA $E000
RTS ; A = char code
T - Show I/O console.
Displays/prints the contents of the virtual console screen.
Note that in run mode (commands X, G or C), virtual screen is
displayed automatically in real-time if I/O emulation is enabled.
V - Toggle graphics emulation.
Enables/disables basic raster (pixel) based RGB graphics display
emulation.
When enabled, window with graphics screen will open and several
registers are available to control the device starting at provided
base address. Detailed description of the device registers os provided
later in this document.
The difference between 'G' and 'X' is that code executed with command 'G'
will return to Debug Console when BRK or last RTS (empty stack) opcode is
encountered, while code executed with 'X' goes to full CPU emulation mode
where BRK will invoke proper interrupt routine as setup by IRQ vector in
memory. The last RTS opcode (empty stack) will return to Debug
Console in both cases unless such behavior is disabled (and this is only
true in case of Reset function, see command '0').
Entering keyboard interrupt codes (CTRL-C, CTRL-BREAK) will return to Debug
Console.
NOTE: All addresses and memory values are to be entered in hexadecimal
format.
2.4. Typical debug session.
Your typical debug session, after starting VM65 is:
* Load the memory image with command 'L' (if not already loaded from
command line). E.g.:
L A 6502_func_test.bin
* Set the program start address with command 'A' (if not already set
in the memory image definition file). E.g.:
A 0400
* Enable/disable various debug and I/O facilities as required by the
loaded 6502 code. E.g.: to enable dymanic processor registers updates
and show the executed code dynamically while executing multiple steps
with command 'N', you need to issue command 'F' to enable registers
animation and optionally 'J' to change the speed (delay) of the
step-by-step animation:
F
J 100
N 1000
OR if command 'S' is used to manually step through 6502 instructions,
the animation of the CPU registers doesn't have top be enabled.
The registers values and disassembled instructions will be refreshed
after each step on the screen.
Each step is considered a single instructions (not a clock cycle).
If user wants to skip several (thousands perhaps) instructions, then
registers animation (command 'F') should be disabled, which will
make the steps to proceed much quicker. E.g.: assuming that currently
the animation is enabled, and user wants to skip 5000 instructions
quickly without looking at the changing registers and disassembled
instructions, user would issue commands:
F
N 5000
At any moment during multi-step execution (command 'N'), user can
interrupt before all the steps are concluded with CTRL-C and then
lool-up/alter memory content (commands 'M', 'W'), change the address
of the next executed instruction (command 'A') etc. and then continue
debugging with 'S', 'N', 'X', 'C', '0' or 'P' commands.
User can enable the history of executed op-codes with command 'U' and
display the history of the last 20 op-codes and CPU registers values
in the last 20 steps. E.g.:
L A 6502_func_test.bin
A 0400
U
N 5
O
Output from 'O':
> o
PC : INSTR ACC | X | Y | PS | SP
------------------------------------+-----+-----+-----+-----
$0400: CLD $00 | $00 | $00 | $20 | $ff
$0401: LDX #$FF $00 | $ff | $00 | $a0 | $ff
$0403: TXS $00 | $ff | $00 | $a0 | $ff
$0404: LDA #$00 $00 | $ff | $00 | $22 | $ff
$0406: STA $0200 $00 | $ff | $00 | $22 | $ff
Type '?' and press [ENTER] for Menu ...
3. Implementing the Virtual Machine.
The Virtual Machine (or Emulator) is implemented by the means of multiple
layers of abstraction. The higher the layer, the less code it contains
that is virtual hardware dependent.
On the highest level we have main.cpp which implements the UI and Debug
Console. Programmer can replace this code with custom designed UI or GUI.
The definition of the emulated system layer begins in VMachine class
(VMachine.h and VMachine.cpp) which provides the implementation of the
entire emulated system. It is a template upon which programmer can expand.
Several important methods are defined here that allow to execute the 6502
code in many different modes:
Regs *Run();
Regs *Run(unsigned short addr);
Regs *Exec();
Regs *Exec(unsigned short addr);
Regs *Step();
Regs *Step(unsigned short addr);
void Reset();
Programmer should use this class to implement all the pieces of the
emulated virtual computer system on the highest abstraction level.
In current version the VMachine class initializes the basic system, which
contains following core components: CPU and memory
and devices: character I/O and raster graphics display.
Going one step down the abstraction layer are MKCPu and Memory classes.
The MKCpu class is the most important part of the emulator. It defines
the whole system's architecture. Based on the type of the CPU device we
know how to implement the rest of the core components by knowing the
maximum addressable memory space, size of the data bus (8-bit, 16-bit) etc.
The MKCpu class defines all the internal registers of the virtual CPU,
the op-codes interpreter and its interface to outside components.
The most important API methods are:
Regs *ExecOpcode(unsigned short memaddr);
Regs *GetRegs();
void SetRegs(Regs r);
void Reset(); // reset CPU
void Interrupt(); // Interrupt ReQuest (IRQ)
The Memory class (Memory.h and Memory.cpp) implements essential concept
in any microprocessor based system, which is the memory. The assumption is
that such a system requires some sort of program storage to be able to
execute code. This is not entirely true in the real world, where we can
make the CPU 'think' that it executes the real code with a tricky circuit
and get away without any memory to make the CPU run. This however has
limited usefulness (diagnostics, testing the basic operation of CPU) and
has no use in the emulation domain where we have no need to test the CPU
chip for basic operation on electrical level. The Memory class is also an
important entry level for another concept of microprocessor based system:
a memory mapped device. This brings us to the lower level of abstraction
which is the memory mapped device class: MemMapDev.
Class MemMapDev is a core or hub for implementing all the devices that are
connected to the virtual CPU via its memory address space. This is
explained in more detail in chapter 4.
All remaining classes are the implementation of the actual devices on the
lowest level of abstraction (from the emulator point of view) and other
helper classes and methods.
Examples of virtual devices emulation implementation are: Display and
GraphDisp.
Programmer can add more code and more classes and integrate them into the
emulator using this architecture. This is the starting point of the
emulator of a real microprocessor based system or completely abstract
virtual machine that has no hardware counterpart.
4. Memory Mapped Device Abstraction Layer/API.
In microprocessor based systems in majority of cases communication with
peripheral devices is done via registers which in turn are located under
specific memory addresses.
Programming API responsible for modeling this functionality is implemented
in Memory and MemMapDev classes. The Memory class implements access to
specific memory locations and maintains the memory image.
The MemMapDev class implements specific device address spaces and handling
methods that are triggered when addresses of the device are accessed by the
microprocessor.
Programmers can expand the functionality of this emulator by adding
necessary code emulating specific devices in MemMapDev and Memory classes
implementation and header files. In current version, two basic devices are
implemented:
- character I/O and
- raster (pixel based) graphics display.
Character I/O device uses 2 memory locations, one for non-blocking I/O
and one for blocking I/O. Writing to location causes character output, while
reading from location waits for character input (blocking mode) or reads the
character from keyboard buffer if available (non-blocking mode).
The graphics display can be accessed by writing to multiple memory locations.
If we assume that GRDEVBASE is the base address of the Graphics Device, there
are following registers:
Offset Register Description
----------------------------------------------------------------------------
0 GRAPHDEVREG_X_LO Least significant part of pixel's X (column)
coordinate or begin of line coord. (0-255)
1 GRAPHDEVREG_X_HI Most significant part of pixel's X (column)
coordinate or begin of line coord. (0-1)
2 GRAPHDEVREG_Y Pixel's Y (row) coordinate (0-199)
3 GRAPHDEVREG_PXCOL_R Pixel's RGB color component - Red (0-255)
4 GRAPHDEVREG_PXCOL_G Pixel's RGB color component - Green (0-255)
5 GRAPHDEVREG_PXCOL_B Pixel's RGB color component - Blue (0-255)
6 GRAPHDEVREG_BGCOL_R Backgr. RGB color component - Red (0-255)
7 GRAPHDEVREG_BGCOL_G Backgr. RGB color component - Green (0-255)
8 GRAPHDEVREG_BGCOL_B Backgr. RGB color component - Blue (0-255)
9 GRAPHDEVREG_CMD Command code
10 GRAPHDEVREG_X2_LO Least significant part of end of line's X
coordinate
11 GRAPHDEVREG_X2_HI Most significant part of end of line's X
coordinate
12 GRAPHDEVREG_Y2 End of line's Y (row) coordinate (0-199)
13 GRAPHDEVREG_CHRTBL Set the 2 kB bank where char. table resides
14 GRAPHDEVREG_TXTCURX Set text cursor position (column)
15 GRAPHDEVREG_TXTCURY Set text cursor position (row)
16 GRAPHDEVREG_PUTC Output char. to current pos. and move cursor
17 GRAPHDEVREG_CRSMODE Set cursor mode : 0 - not visible, 1 - block
18 GRAPHDEVREG_TXTMODE Set text mode : 0 - normal, 1 - reverse
NOTE: Functionality maintaining text cursor is not yet implemented.
Writing values to above memory locations when Graphics Device is enabled
allows to set the corresponding parameters of the device, while writing to
command register executes corresponding command (performs action) per codes
listed below:
Command code Command description
----------------------------------------------------------------------------
GRAPHDEVCMD_CLRSCR = 0 Clear screen
GRAPHDEVCMD_SETPXL = 1 Set the pixel location to pixel color
GRAPHDEVCMD_CLRPXL = 2 Clear the pixel location (set to bg color)
GRAPHDEVCMD_SETBGC = 3 Set the background color
GRAPHDEVCMD_SETFGC = 4 Set the foreground (pixel) color
GRAPHDEVCMD_DRAWLN = 5 Draw line
GRAPHDEVCMD_ERASLN = 6 Erase line
Reading from registers has no effect (returns 0).
Above method of interfacing GD requires no dedicated graphics memory space
in VM's RAM. It is also simple to implement.
The downside - slow performance (multiple memory writes to select/unselect
a pixel or set color).
I plan to add graphics frame buffer in the VM's RAM address space in future
release.
Simple demo program written in EhBasic that shows how to drive the graphics
screen:
1 REM GRAPHICS DISPLAY DEVICE DEMO
2 REM BASE ADDRESS $FFE2
3 REM DRAW HORIZONTAL AND VERTICAL LINES
4 REM DRAW SINUSOID
10 GB=65506:REM SET BASE ADDRESS
12 REM INITIALIZE, SET COLORS
15 POKE GB+1,0:POKE GB+11,0
16 POKE GB+3,0:POKE GB+4,255:POKE GB+5,0
17 POKE GB+6,0:POKE GB+7,0:POKE GB+8,0
18 POKE GB+9,3:POKE GB+9,4:POKE GB+9,0
19 GOSUB 1120:REM DRAW SINUSOID
20 Y=100:REM X-AXIS
30 GOSUB 1000
50 X=100:REM Y-AXIS
60 GOSUB 1060
70 REM SOME EXTRA DOTTED LINES
80 Y=50:GOSUB 1200
90 Y=150:GOSUB 1200
100 X=50:GOSUB 1260
110 X=150:GOSUB 1260
990 PRINT "DONE"
998 END
999 REM ------- SUBROUTINES SECTION -------
1000 REM DRAW HORIZONTAL LINE AT Y
1005 POKE GB+2,Y
1006 POKE GB+12,Y
1020 POKE GB,0
1025 POKE GB+10,199:POKE GB+9,5
1050 RETURN
1060 REM DRAW VERTICAL LINE AT X
1070 POKE GB,X
1075 POKE GB+10,X
1090 POKE GB+2,0
1095 POKE GB+12,199:POKE GB+9,5
1110 RETURN
1120 REM SINUSOID
1130 FOR X=0 TO 199-4 STEP 5
1140 XX=X*(6.28/200)
1145 XE=(X+5)*(6.28/200)
1150 YY=SIN(XX):YE=SIN(XE)
1160 Y=199-INT((YY+1)*100)
1165 Y2=199-INT((YE+1)*100)
1170 POKE GB,X:POKE GB+2,Y
1175 POKE GB+10,X+5:POKE GB+12,Y2:POKE GB+9,5
1180 NEXT X
1190 RETURN
1200 REM DRAW DOTTED HORIZONTAL LINE AT Y
1205 POKE GB+2,Y
1210 FOR X=0 TO 199 STEP 4
1220 POKE GB,X
1230 POKE GB+9,1
1240 NEXT X
1250 RETURN
1260 REM DRAW DOTTED VERTICAL LINE AT X
1270 POKE GB,X
1280 FOR Y=0 TO 199 STEP 4
1290 POKE GB+2,Y
1300 POKE GB+9,1
1310 NEXT Y
1320 RETURN
And another one to show how to render characters.
Before entering program below, load files c64_char.dat and ehbas_xx.dat to the
emulator. The two 2 kB C64 character banks reside at $B000.
The EhBasic version in file ehbas_xx.dat has top of RAM capped at $AFFF.
5 PRINT:PRINT "BITMAP TEXT DEMO. PRESS [SPACE] TO QUIT...":PRINT
10 C=0:M=0:N=22:B=65506:POKE B+9,0
12 PRINT "NORMAL MODE, CHAR BANK ";N*2048
15 POKE B+13,N:POKE B+17,0:POKE B+18,0
20 FOR Y=0 TO 24
30 FOR X=0 TO 39
40 POKE B+14,X:POKE B+15,Y
50 POKE B+16,C
60 C=C+1:IF C<256 THEN 120
70 IF N=22 THEN N=23:GOTO 100
80 N=22:IF M=0 THEN M=1:GOTO 100
90 M=0
100 POKE B+13,N:POKE B+18,M
110 Y=Y+1:X=-1:C=0
115 IF M=0 THEN PRINT "NORMAL"; ELSE PRINT "REVERSE";
116 PRINT " MODE, CHAR BANK ";N*2048
120 GET K$:IF K$=" " THEN END
130 NEXT X
140 NEXT Y
150 GOTO 5
4.1. Adding new device implementation.
MemMapDev.h and MemMapDev.cpp define the higher abstraction layer for memory
mapped devices. Memory address range class: AddrRange and device class:
Device are implemented to provide core facilities and class: MemMapDev for
future expansion of the emulated system.
To add a new device to the memory mapped devices, programmer must:
* Implement the device behavior in a separate class.
See GraphDisp.h, GraphDisp.cpp as example.
This is the actual device driver, code that defines how the device works.
Device driver class may define the raster graphics display functions,
a real time clock chip functions, sound chip functions, Disk Drive
functions etc.
This code does not contain definitions related to how the device is mapped
to the memory space of emulated computer system. That would be the
responsibility of MemMapDev class, providing the middle layer of
abstraction for connecting the device to the memory space of the CPU.
* Add necessary definitions, enumerators and methods to the MemMapDev.h
and MemMapDev.cpp.
The minimal set should include methods to initialize the device and
methods executed when memory mapped device registers are read from and
written to.
Other methods may be needed to perform device implementation specific
functions.
See example set of methods for simple raster graphics device:
unsigned short GetGraphDispAddrBase();
void ActivateGraphDisp();
void DeactivateGraphDisp();
int GraphDispDevice_Read(int addr);
void GraphDispDevice_Write(int addr, int val);
void GraphDisp_ReadEvents();
void GraphDisp_Update();
Important concept at the core of the memory mapped device is the method
handling the action to be performed when certain memory register is being
read from or written to. These are defined as function pointers in Device
class: read_fun_ptr and write_fun_ptr.
struct Device {
int num; // device number
string name; // device name
MemAddrRanges addr_ranges; // vector of memory address ranges for
// this device
ReadFunPtr read_fun_ptr; // pointer to memory register read
// function
WriteFunPtr write_fun_ptr; // pointer to memory register write
// function
DevParams params; // list of device parameters
[...]
Programmer implements these handler methods inside MemMapDev class.
Programmer should not forget to add the new device to the pool in the
MemMapDev::Initialize() method which adds all implemented devices to the
devices list with their corresponding default memory bases/ranges and
parameters. These devices can be later re-defined with
MemMapDev::SetupDevice() method.
typedef vector<Device> MemMappedDevices;
[...]
MemMappedDevices mDevices;
[...]
void MemMapDev::Initialize()
{
[...]
Device dev_grdisp(DEVNUM_GRDISP,
"Graphics Display",
addr_ranges_grdisp,
&MemMapDev::GraphDispDevice_Read,
&MemMapDev::GraphDispDevice_Write,
dev_params_grdisp);
mDevices.push_back(dev_grdisp);
[...]
* Add necessary ports in Memory.h and Memory.cpp.
Memory class already implements the code handling memory mapped devices
in all read/write memory methods. Some local methods and flags specific
to the devices may be needed for implementation convenience.
Important relevant methods in Memory class:
int AddDevice(int devnum);
int DeleteDevice(int devnum);
void SetupDevice(int devnum, MemAddrRanges memranges, DevParams params);
are the API to be called from higher level abstraction layer. Some proxy
methods can be implemented in Memory class for this purpose.
See Memory::SetGraphDisp() and VMachine::SetGraphDisp() methods for
an example. The SetGraphDisp() method in Memory class defines the memory
mapped device on a lower level and calls SetupDevice().
5. Debug traces.
VMachine class implements debug messages queue which can be used during
development cycle.
void EnableDebugTrace();
void DisableDebugTrace();
bool IsDebugTraceActive();
queue<string> GetDebugTraces();
void AddDebugTrace(string msg);
This is a FIFO queue and it is maintained to not exceed the length as
defined:
#define DBG_TRACE_SIZE 200 // maximum size of debug messages queue
Therefore the next message added to queue that overfills the queue causes
the earliest added message to be removed.
Shortly put - the last 200 added messages only are remembered internally
in VMachine object and can be recalled with GetDebugTraces() method like
shown in this example:
VMachine *pvm;
[...]
queue<string> dbgtrc(pvm->GetDebugTraces());
while (dbgtrc.size()) {
cout << dbgtrc.front() << endl;
dbgtrc.pop();
}
Good example of AddDebugTrace() use is EnableROM() method:
void VMachine::EnableROM(unsigned short start, unsigned short end)
{
mpRAM->EnableROM(start, end);
if (mDebugTraceActive) {
stringstream sssa, ssea;
string msg, startaddr, endaddr;
sssa << start;
sssa >> startaddr;
ssea << end;
ssea >> endaddr;
msg = "ROM ENABLED, Start: " + startaddr + ", End: " + endaddr + ".";
AddDebugTrace(msg);
}
}
NOTE: The AddDebugTrace method checks mDebugTraceActive flag internally,
however for performance's sake we also check it in the higher level
code especially if there are intermediate objects to be created
to produce the debug string. This way we don't execute code related
to creation of debug message unnecessarily if the debugging messages
are disabled.
5. Linux port.
I don't pay as much attention to Linux version of this software, however
I try my best to make the program work correctly on Linux and behave in the
same manner on both Windows and Linux platforms.
The most challenging part surprisingly was implementation of the character
I/O emulation on Linux. Easy on Windows with its conio.h header and kbhit()
and getch() functions that provide non-blocking keyboard input, Linux part
required some research and implementing some known programming tricks to get
this to work. I got it working but then lost touch with Linux version for
a while. After I added graphics device and SDL2 library, I worked on Linux
port to have these features working on Linux platform as well. To my surprise
I discovered then that my implementation of character I/O (the non-blocking
character input) stopped working. After many failed attempts and research
I decided to rewrite the Linux character I/O part using ncurses library.
This works although has its own problems. E.g.: ncurses getch() returns NL
character (0x0A) when ENTER is pressed, while Windows conio equivalent returns
CR (0x0D) and this is the code that 6502 programs, like Tiny Basic or EhBasic
expect. Backspace also wasn't working. I enabled function keys during ncurses
initialization and intercept backspace code for later conversion. This
solved it, but there may be more issues discovered later which I didn't fully
test.
unsigned char MemMapDev::ReadCharKb(bool nonblock)
{
[...]
#if defined(LINUX)
if (c == 3) { // capture CTRL-C in CONIO mode
mpConsoleIO->CloseCursesScr();
kill(getpid(),SIGINT);
} else if (c == 0x0A) {
c = 0x0D; // without this conversion EhBasic won't work
} else if (c == KEY_BACKSPACE) {
c = 8; // raw/cbreak modes do not pass the backspace
}
#endif
[...]
Another issue was that when 6502 code sends CR/LF sequence, the CR code
moves the cursor to the beginning of the line before applying NL (new line)
and clears the characters on its path! Therefore I'd have the text removed
from the screen (although my internal display device emulation in Display
class has its own buffer and all characters were there, it was only a visual
side effect). Therefore I have to convert CR/LF sequences to LF/CR.
Also because of the way I output characters to nsurses screen, control
characters don't work and must be intercepted and properly converted to
appropriate action. Example - the bell (audible) code 7:
void MemMapDev::PutCharIO(char c)
{
mCharIOBufOut[mOutBufDataEnd] = c;
mOutBufDataEnd++;
if (mOutBufDataEnd >= CHARIO_BUF_SIZE) mOutBufDataEnd = 0;
if (mCharIOActive) {
#if defined(LINUX)
// because ncurses will remove characters if sequence is
// CR,NL, I convert CR,NL to NL,CR (NL=0x0A, CR=0x0D)
static char prevc = 0;
if (c == 7) mpConsoleIO->Beep();
else
if (c == 0x0D && prevc != 0x0A) { prevc = c; c = 0x0A; }
else if (c == 0x0A && prevc == 0x0D) {
prevc = c; c = 0x0D;
mpConsoleIO->PrintChar(prevc);
mpConsoleIO->PrintChar(c);
}
else { prevc = c; mpConsoleIO->PrintChar(c); }
#else
mpConsoleIO->PrintChar(c);
#endif
CharIOFlush();
}
}
Reference in New Issue View Git Blame Copy Permalink