Beginning Assembler on the Spectrum
===================================
           ,        ,       ~,
Thanks to Cesar Hernandez Bano

(Yes that's him the creator of ZEsarUX the first full Next emulator)

Who worked in 1996 for around 50 days to produce a 128K assembler, monitor and
dissasembler - which was called SPED52, as that is how many saves he made...
we can now provide an on machine tool to learn a bit of assembly language.

This is no toy either - in the spirit of Open Source it includes its own
source code under GNU GPL - yes that's correct it is written in itself!

Anyway all spelling errors in SPED52 EN(glish) and this document are due to
Tim Gilberts.  The original ES (Spanish) version is also provided and they
should be functionally identical, only the text has changed.

To run it:
----------

Use the Browser to change the speed to 14Mhz - the editor and the assembly are
really improved with this speed boost.  If you forget just tap F8 of course.

Then use Mode 0 to load SPED52EN.TAP (or .RUN SPED52EN.TAP) from the tools
directory.

If you exit to BASIC (Capital B) then it will print an address:

Return to 49453

Note that it leaves you in 48K BASIC so of course you need to use the DOT
commands like .ls, .tapein, .cd etc

The printed address is the one you need to type in RANDOMIZE USR xxxxx to go
back to the system with your Source Code intact - The source code is the
list of assembly language instructions you want it to turn into the long
stream of numbers that the Z80 microprocessor at the heart of the system
actually understands.

Some Rules:

1/ First of all make sure you use Capitals for just about everything!

2/ Other First NEVER try to run Assembler without SAVING first - this is the
only warning you will get, the next is a hard lesson in a crashed machine
with your masterpiece in some transistors just waiting for the power off
or RESET that is coming.

Using TAP Files with older software
-----------------------------------

This advice applies to most older software that only supports tape and is
the reason for TAP files support on the NMI button browsers in NextZXOS and
in ESXDOS.  You can use also do this with the older A17C copy of PAW that has
been provided in the distribution as well, although we hope you will start to
use the full ESXDOS version or even better get a copy of the new NextPAWS!

To Save your work you will need to attach a TAP file. Time to practice with
the new NextZXOS NMI menu when you press the Mutiface button on
the left side near the front!  This functionality is also available from
the ESXDOS NMI system either from the standard menu or the Dr Slump improved one
(Press H to cycle through some help pages on ESXDOS)

This allows you to select a different TAP to load your work from and create a
new one for what you save.  This way you will always have a history of the
changes you made just like Cesar did...

PROJECT1.TAP
PROJECT2.TAP
etc

The next time you just select PROJECT2.TAP to Attach to load from and create
a new one PROJECT3.TAP to save into.  Easy to go back and look if you break
something.

You can do several saves in each TAP with a unique name for the text version
as well you will just have to remember its name.

Of course as, at the moment, it is a standard 128K program you can use the
snapshot function to save a .SNA at any time to get you back to exactly where
you were!

Remember it is Capital H for help when you get to the Command Prompt:

A - Assemble
B - Back to Basic
D - Disassembler
E - Editor
F - Modify Date
G n - Set block of text to use
I - General Information
L - Load source code
N - New block of Text
O - Save Object Code
S - Save Source Code
T - View Symbol Table
Z - Delete Source Code

First things first:

E - edit mode
-------------

In here you have a number of keys available after pressing EXTEND mode
CAPS and SYMBOL on a 48K KB.

A - Page down
B - Delete Block
C - Copy Block
D - Search for Label
E - " from start
F - Search Text
G - " from start
N - Find Next text
H - HELP!!! (not listed on help - you can sort of see the logic)
I - Insert ON/OFF
J - Next Label
K - Calculate Expression
L - Goto line
P - Mark start of Block
Q - Page up
U - Mark end of Block
V - Paste Block
X - Cut Block
Z - Restore Line

While holding Symbol Shift:

D Delete line
I Insert line
Q Exit editor

Try it just type in two lines (you can include the comments if you wish ;)

;Sample program make A=200
 LD A,200
 RET

When you have finished your masterpiece then:

Q Exit editor (just go back to the command prompt)

A - Assembler
-------------

Now the above text is just like that, some text - unlike BASIC where you would
type RUN to go through the code, as this will be given to the main CPU when
we finally run it, we need to turn it from text into a list of the numbers.
You will find these next to the character set in the Spectrum manuals.

For the above that is:

3E C8		; 3E / 62 means LD A and C8 = 200 in Hexadecimal
C9		; C9 / 201 is a return instruction

So press A now and SPED will do its job and convert the text into the numbers
for us.

If there are any errors they will be shown, press ENTER to move onto the next
one.  Make a note of the line number as you can use EXTEND+L to GOTO it in
the editor!

How do I RUN it then?
---------------------

Remember the rules - make sure you have Attached a TAP file for save and then
at the command prompt type:

S FIRST.SPE			- or whatever you want to call the file.

This is just the text - you will probably also want to save the object code
(the list of numbers SPED just worked hard to produce) 

O FIRST.BIN			- BIN is usually meant for blocks of code

In order to run your code you would need to go back to BASIC and load in the
object code you have saved from the tap.  Then you will be able to use
the Debug tools in the NextZXOS MF to look at memory - this is a whole other
topic which will be covered elsewhere.

Or like a real grown up IDE you can use the built in tools for SPED52 which
includes what is called a 'Monitor/Dissasembler' to allow you to see what is
happening to the regsisters and memory and turn the numbers back into a
human form.

The Dissasmbler Monitor
-----------------------

Type D at the Command Prompt

There is quite a bit to learn here but the screen is showing you all the
contents of the Z80 and some of the memory at the locations that the various
registers (like variables) it has.  Can you spot the A register?

EDIT/ENTER ME-+1
cursor left and right +-8 bytes
Up/Down -+ Instruction

C Calculate Expression
$ Disassemble
SS+D Read Debug Table Yes/No
E Assemble instruction
I Insert Bytes
SS+K Execute
L List Hex and Ascii
M Change point in Memory
SS+N Make PC = ME
SS+Q Quit disassembler / monitor
R Modify register RR=XXXX
S See screen
SS+S Configure screen destination
(0:None 1:Symbols 2:Debug)
SS+T Set Breakpoint after instruction
SS+Z Step by Step
SS+3 Numbers Hex or Dec (i.e. #)

Symbol Shift and Q to quit dissassembly listing which should show you the 
the numbers converted back into Source code....

You use SS + Q then as well to go back to the Command prompt

SS+Z will allow you to step over each instruction and see what happens - do
that now and you should see the value of A change.  Well done!

List of allowed Directives
--------------------------

DEFS		- Define an amount of space to leave
DEFM		- Define a string
DEFB		- Define a byte
DEFW		- Define a word (2 Bytes)
ENT		- Entry address for code
LST+		- listing on and off
LST-
ORG		- Where the assembled code should be put to run it
DPR+		- see note below
DPR-

DPR means: DePuRacion (debugging in Spanish)
The DPR+ and DPR- will allow you to see the source code while debugging.
Just enable it at the beginning of source code and after compile, go to the
debugger where you can use SS+D to read the debug data to allow you to see the
source as you run.

On the subject of Blocks
------------------------

The editor uses the idea of Blocks of Text held on multiple banked memory pages.
The block in current use is shown in the top right. Using G as a command
G 0,1,2 (and eventually 3-xxx) will allow you to go to that block if it has
been started.

To see this you can load the source code for SPED52 itself as it uses 2 and a
bit blocks...

Source Code
-----------
Attach the SPE52AEN.TAP for English or SPE52AES.TAP for Spanish which will be in
the sources folder.  Just use L to load the first set of blocks!

You can then go to each block and use E to edit them and look through the
source code.  'A' will of course Assemble this, which will be a bit slower
that the above example.

TIP: from the MF menu you can use the browse to look at what is on a TAP to
'rewind' the tape just click on the first block or click on the specific 
file if you want.  Note that there are can be multiple blocks in a SPED source
file.

The name is SPE for source, 52 for the program and A for version with EN/ES for 
language.  So version 1.2 will be B etc.  You can of course use either the
Spanish or the English to assemble each others code.

Using the assembled Object code
-------------------------------

You can get at the file you have made from in the TAP using standard basic
commands:

NextZXOS

CLEAR 49151
.tapein PROJECT1.TAP
LOAD "t:"
LOAD "name" CODE 49152
.tapein -c

ESXDOS

CLEAR 49151
.tapein PROJECT1.TAP
LOAD "name" CODE 49152
.tapein -c

Your assembly language is now in memory - so you can save it out as a block
with SAVE "name" CODE 49152,length on NextZXOS or SAVE *"name" CODE 49152,length
on ESXDOS

TODO
----

The following things may get addressed in future versions:

Line 1567 end of block 1 is the instruction tables can we add NEXTREG?

Page 7 is used making return to NextZXOS other than 48K a problem

It could make use of more pages on the Next, but that will stop SNA working.

Add native file system support for saving blocks without using TAP's

For info
--------

The original used two BASIC programs to load; the first asked you to press
a key and then LOAD "" causing a restart by doing:

RANDOMIZE USR 0 (to go to 48k mode but having 128k of memory).

Then the second which was next on the TAP did:

CLEAR 49151: OUT 32765,17: LOAD "" CODE 49152: RANDMOIZE USR 49152

We have put the above in a bit of BASIC for you - so you can just use the
Next facility to load from a TAP using the Browser just make sure you use
option 0.

For some more background:

https://github.com/chernandezba/zesarux/blob/master/src/my_soft/spectrum/vintage/sped52.txt

Licence
-------

    SPED52 - integrated Assembler/Monitor and Disassembler for the 128K Spectrum
    Copyright (C) 1997 César Hernández Bañó

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.


Tim Gilberts
August 2018


Manifest
--------

tools/

SPED52.BAS   - Loader with language selection (Must use on DivMMC ESXDOS)
SPED52EN.TAP - English version of the Assembler (Can load direct on NextZXOS)
SPED52ES.TAP - Spanish version of the Assembler (Can load direct on NextZXOS)

sources/sped52

SPE52AEN.TAP - English source (and object code) for SPED52 1.1 (A) ENglish
SPE52AES.TAP - Spanish source (and object code) for SPED52 1.1 (A) ESpañol

docs/

readmeSPED52.txt


Release 2 changes
-----------------

Fixed duplicate "para" in Spanish Version text

Added note on Source debugging: DPR means: DePuRacion (debugging in Spanish)

Bug on ESXDOS 0.8.5 on original ZX128 where keyboard fails to work - fixed with
SPED52.BAS loader instead of direct boot of TAP files...


