JASPE (Readme 010118aen)

(I'm sorry, my english is awfull, translations and corrections are well 
received.)

Versin 010118

New from last version (000115)

- User interface graphics improved.
- Several bugs corrected.
- Added  fileselector for program loading.
- Partial AY emulation support..
- Minor internal changes.

  Due to personal reasons, last year I hadn't worked too much on the 
emulator. I hadn't received comments nor background about it, and 
existing bugs, so I encourage you to tell me about if you find something 
so I can try to fix it.

Known bugs

- Still haven't achieved a decent AY 'noise' emulation.
- Under Windows and with some SoundBlaster's drivers AY emulation 
cuts-off if you're back from emulation to main screen; it seems FM 
sound generation stops some seconds after for reasons currently 
unknown for me.
- ULA emulation is far to be complete, contended memory emulation 
isn't still solved so demos and program who play with it doesn't look as it 
had to.


Contents

0. Legal stuff

  The author is not responsable of any damage from using this program, 
alone or with third person software, including royalties and copyrights.
  This program is freeware. I assume this as free distribution, with the 
only restriction that this README should not be eliminated from the 
pack. Distribution with others elements with commercial purpose is not 
allowed without permission. 
  The author will like if possible that credits will be given: 

		Julio Fernndez - Lugo/Galicia/Espaa 
		E-mail: ucldb@wanadoo.es
		Homepage:  http://perso.wanadoo.es/ucldb

1.Presentatin 

  Actual version of  JASPE emulates the 48 and 128 Spectrum.
  First, JASPE comes from Just Another SPectrum Emulator, only 
wanted to give it a double meaning because JASPE in spanish is a gem, 
and for me this it is too, but is not intended to be something great, out 
there are more and better emulators.
  Is important to me to fix exactly what this project wants to be: from the 
beginning of emulation (some years ago for me) of arcades and 
computers I proposed myself the Z80 cpu emulation, and as support 
machine the Spectrum, for me the brighter star of what I call "Golden 
Age" of computer science, nothing will be the same.
  Program is being done in assembler (MASM), so I can teach myself 
about x86 and PC architecture. The external support is being build in C 
(Borland Turbo C 2.0).

  The starting goals I planned were: 

- Modularity: A kernel that emulates any number of Z80 at the same 
time.
- Fidelity: The Z80 emulation should be the nearest possible to reality.
- Performance: Achieve the best possible speed of emulation.

  As I said before, the support hardware choosen was the Spectrum, my 
first one (then more came, but none like it), so secondarily I'm trying to 
give a better emulation at this point too, but first is still the Z80. 
   In fact, I proposed myself two tests to verify my objectives: run the 
emulator on my old XT (a 8088), and seeing on the screen running 4 
spectrums at the same time. Both are done yet, with slightly modified 
versions (at the XT, as you can suppose speed is far from good, but 
works).
  Where do I want to go with this boring introduction?, this is not a 
perfect Spectrum emulation, as you can see, with light weakness, but if is 
possible to me, and I got time to do it I'll try to improve. So don't 
contact with me to blame, but to say what can I do best, or 'this program 
doesn't work', 'I found a bug ...', or simply to talk. 
 
  Strong points (my thought, tell me any incidence):

- Complete Z80 emulation, R register, undocummented intructiones and 
flags.
- You can emulate any number of machines at the same time, althoug 
this version only  executes one at time.
- Integrated debugger, it allows change registers, breakpoints, 
memory watches, breakpoint if contents change, pokes, step-by-step 
trace and disassembly at PC, memory address or log of 16 last executed 
instructions.
- Very customizable interface, any foreing language supported.

  Weak points (and others you can see, any help will be well received).

- Sound, have to find a way to improve better sound (via speaker), also 
SoundBlaster programming is still hard for me.
- Timming, always could be improved, and that is of great importance.

Developping points (I doesn't finish ones and I think in others ...):

- Solve weak points.
- Complete AY support (mainly to add noise).
- Complete interface, it's designed to have mouse support.
- Emulate new hardware ... and Z80 based arcades.
- New files formats support, tape.
- Complete emulation of ULA to get screen efects. Preeliminary version 
done, but contended memory is delaying developments.
- New  Z80 kernel, emulating CPU at control unit level instead of 
instruction level.
- Conversion to a real operating system ... LINUX. The project has 
been build in a modular way so, only have to reprogramm the elements 
related with I/O and memory management.
- ... tomorrow I'll have more.

2. Requirements, installation and use 

   Emulator should run under DOS, or WindowsXX. I don't know if 
there's some issue about running capabilities under OS/2 o LINUX 
(Dosemu), please report any incidence.

  About hardware, all 640K main memory are not needed. Requires 
XMS memory, a graphic video card with VESA support of  
640x480x256 mode and a OPL-3 soundcard (in fact any  Soundblaster 
compatible, if I only have a GUS ...).

  To install, from ZIP or whatever you got it, extract the files, the only 
restriction to execute the program is that the EXE file is at the same 
directory as ROMs binaries named SPECTRUM.ROM, 
SPECT128.ROM and interface support files: 

	JASPETXT.JSP - Messages y texts.
	JASPEFNT.JSP - Character fonts.
	JASPEPAL.JSP - Color palette.
	JASPECST.JSP - Interface objects colors.
	JASPEBMP.JSP - Graphics and icons.

  All those files are user modifiables:

  First is a plain text file with menssages and texts of options, so they 
can be translated to multiple foreing languages, also hotkeys for 
selecting options into menues.
  Second contains the character fonts. I use a tool of my own that 
extracts from a BMP the fonts, but it isn't too much 'useful' now, but if 
somebody wants a font to be generated tell me and I'll try to do it.
  Third contains the color palette in binary format, 256 RGB byte 
entries so it's not hard for you if you want to change it, take care that 16 
first are the of original Spectrum colors.
  Fourth has indexes over the color palette belonging to each interface 
object. Next editions I   would like this file to be changed and generated 
from emulator, but now I use other programs I have maid. It's a ordered 
binary, if someone want to customize ... tell me and I'll add to 
documentation a TXT explaining the correlation between interface 
attributes and order number in file.
  Fifth and last, new in this version, contains interface graphics in a 
custom own compressed format. If someone has alternative ones ... tell 
me and I look if I can generate a new file.

  As you can see, interface is easy to modify, but I have to plan seriously 
integrate my tool into the emulator so we can customize it from inside.
  Aditionaly you can find in the release some alternate interface files; 
to use them instead originals, rename or delete the JASPExxx.JSP 
corresponding file and then rename or copy the alternate JASPExxx.yyy 
as JASPExxx.JSP.

  Now, how to use: (all colors will referre from here are those of the 
standard interface I release, any customization you make changes 
that).
  Just type JASPE, no INI's nor switches nor command line 
parameters.

  There are four units available to emulate; red background and 
'JASPE' logo means that the unit is not initialized, that is, without 
contents, when a unit is initialized or loaded the background changes to 
green and logo goes to a 48K or 128K Spectrum graphic; a internal 
yellow background signals which unit is the one that menu commands are 
issued from (active unit). You can switch from them by typing the 
corresponding number (but not at the numeric keypad).

  Main menu: (applies onto the active unit)

  To select any command press the corresponding hotkey, that is, the 
one in blue in a yellow text, or you can move through options with 
arrows, and init and end keys (the actual option is the one surrounded by 
a dashed frame) and select it by pressing the spacebar or enter key.

  Initialize unit: drops into a submenu where you can choose the kind of 
hardware you want to emulate at that unit (48 o 128), that's the way to 
get a 'resetted' Spectrum. Initialize some data and load the appropriate 
ROM. You have to initialize a unit in order to work with it (except when 
you directly load a program, in that case unit is automatically initialized). 
A initialized unit shows a green background.

  Load program: opens a fileselector that displays drives in yellow, 
directories in orange and files in blue and green, the last one happens 
when the file is a valid file format for the emulator, and that's recognised 
by its extension. Supported format for loading are SNA and Z80. You 
can move through with arrows and select a file with enter. If a file loads 
ok then the unit is first initialized.

  Save program: opens a dialog box from where you have to type file 
name and extension. Supported format for saving is SNA. At any dialog 
box you can move with arrows, init and end keys and toggle mode from 
insert to overwrite mode by pressing the insert key, when you do so 
the cursor size varies.

  Copy unit: it does a exact copy of a unit over another. You have to 
supply the destiny unit that has to be initialized first. Those that have 
played platform games appreciate this when have to 'jump' over a not 
easy looking place.

  Preferences: drives into the preferences menu. Each unit has their 
own preferences, so they're not global. When initializing a unit (and so 
loading a program) preferences are resetted. Modifiable options are:

	Issue: keyboard response mode 2 or 3.
	Emulation speed: faster or slower (+ and - keys).
	ULA emulation (still testing): partial ULA emulation on/off.

  View screen: take a look at the active unit screen.

  Run emulation: goes on with emulation, if we are in debug mode with 
tracing enabled only one instruction is executed and when over enter 
debug menu. To return into main menu when running press escape key.

  Exit: finish JASPE.

  Debug: enters debug menu and enable trace mode.

  Debug menu:
  We get here after choosing debug from main menu or when emulating if 
a breakpoint is satisfied or if running on trace mode.

  Displays:
  Register sets main and alternate.
  Flags, over red background when disabled (0) or green background 
when enabled (1).
  Disassembly, seen by next instruction, memory address or last 
executed instructions log. The one in white is the next/last instruction to 
run depending of the kind of listing chosen.
  Stack (8 bytes).
  Memory (32 bytes), when emulating a 128 it also shows the loaded 
page numbers.

  Debug commands: 

  Some commands opens a dialog box for prompting user data, in that 
case, any number is treated as hexadecimal if and only if has a leading 
'0', otherwise it will be seen as if it was decimal. All numeric data 
displayed on the screen are showed in hexadecimal format. When a 
pair of data is required, for example, address and content, or register 
and value, etc, those values had to be separated by commas.

  Registers: modifies registers, those paired can't be modified alone 
but inside the pair.

  Flag: toggles a flag, you'll also modify flags when changing the F 
registers contents.

  Poke: lets you to change a memory address data, even at a ROM 
address, when dealing with paged memory (128) currently enabled 
pages are the ones how get modified.

 Interrupt: interrupt options, opens a dialog box where prompted to 
enter some of those commands:  EI enable INT's, DI disable INT's, 
BRQ bus request, INT maskeable interrupt request, NMI non 
maskeable interrupt request, CLRQ clear interrupt commands 
requested.

  View screen: take a look at the debugged unit screen.

  Trace: enables and disables the trace mode, that lets you run under a 
step by step emulation of instructions. 
  Source listing: sets the base configuration of the disassembly source 
listing, it can be from  PC, last 16 executed instructions or memory 
address. 

  Memory address: sets the memory address to 32 bytes monitor or 
dissassembly by memory address.

  Breakpoint: sets a inconditional breakpoint when PC reaches that 
address (if the dialog box where prompted for address is set empty then 
any unconditional breakpoint is removed).

  Change of content breakpoint: set a conditional breakpoint when 
content in a memory address is changed (if the dialog box where 
prompted for address is set empty then any conditional breakpoint is 
removed).

  Escape: returns into main menu.

  JASPE: goes on with emulation (if we are in trace mode only one 
instruction will be executed and then jump into the debug screen).

  Aditional considerations:

  Keyboard emulation: there are no shortcut keys from PC to Spectrum, 
for example, the PC delete key is not remapped into the SHIFT-0 
Spectrum keys. CAPS-SHIFT and SYMBOL-SHIFT Spectrum keys 
are left and right PC SHIFTs.


