ZX-IDE Tutorial for programming assembler and ZX BASIC

[PokeMon]

Intro:

Here in the very first posting of this thread you will find attached the latest version of the ZX-IDE as attachement. This will be updated as necessary. And I will keep an index of the content here for a better on case reading for important sections and you don't have to read all from A to Z.

Index of content:

Beginners assembly section

=> Edit and compile (assemble)
=> Audio transfer to ZX81 or ZX80
=> Listing
=> Addressing Spaces I
=> Data definitions I
=> Data definitions II (blocks & more)
=> Variables and Constants
=> Labels
=> Use of Media Player for transfer
=> ZX Emulator EightyOne
=> ZX emulator EightyOne - hints for using
=> Z80 Assembler - undocumented opcodes

ZX81 BASIC programming

=> ZX81 BASIC, REM, _asm
=> ZX81 BASIC, line numbers, labels
=> ZX81 BASIC, RAND, USR
=> ZX81 BASIC, format, AUTORUN, _noedit
=> ZX81 BASIC, _hide
=> ZX81 - different context of ZX BASIC and assembly
=> ZX81 PRINT, number formats , calculations
=> ZX81 mathematics and functions
=> ZX81 startup variables
=> ZX81 BASIC, variables, LET statement
=> ZX81 BASIC, labels as line numbers (GOTO, etc.)
=> ZX81 BASIC, graphic chars, special chars, charset
=> ZX81 BASIC, IF-THEN statement, comparison, STOP
=> ZX81 BASIC, FOR-NEXT loop, STEP, FAST, SLOW
=> ZX81 BASIC, VAR definition in memory I
=> ZX81 BASIC, VAR definition in memory II
=> ZX81 p-file converter

ZX80 BASIC programming

=> ZX80 BASIC, line numbers, REM, _asm
=> ZX80 BASIC, RAND, RANDOMISE, USR, labels
=> ZX80 BASIC, AUTORUN, _noedit, _hide
=> ZX80 BASIC, overview and instruction set implementation

Tips & tricks for experts

=> Batch file execution after compilation, ZXpand token
=> Useful macros for PUSH and POP
=> Macro for data manipulation and string formatting
=> Useful macros for jumps and loops

Here the original posting:

I announced to write a tutorial as I did on the german board and here it is.
First you should get the latest version here which is always in this first posting of the tutorial thread.

Second the name changed from ZX81-IDE to simply ZX-IDE or FASMW-ZX.EXE as it will support not only programming of ZX81 but also use of ZX80 (already prepared) and hopefully the ZX Spectrum later this year (as I am a new owner of a working ZX Spectrum 48k).

The installation is very simple, just unpack the ZIP archive and get started with FASMW-ZX.EXE which is a nice IDE with integrated text editor and multiple source file support (can be opened up to 10 or more sourcefiles to work on). The external program LISTZ80.EXE is started with a keypress (F8), generates a nice listing and open it automatically in a new IDE window. The FASTLOAD.BIN file is needed for the Fast Loader option in the IDE which speeds the audio transfer by factor 25 from about 40 byte/s to up to 1kByte/s. There are 2 demo files in the ZIP archive, the ZX81DEMO.ASM as a simple program to load into the ZX81 and the ZX81ROM code as source which can be compiled to the 8k binary with the IDE. Maybe if someone wants to improve his Zeddy.
The subdirectory SINCL-ZX contains include files for use with ZX81 programs which contain defines, variables and memory sections like the D_FILE.

Main purpose of adapting the original FASM IDE x86 version to Z80 and ZX BASIC was the use of a powerful development engine to enter and modify source code, simplify development process without difficult configuration of several command line programs, linkers, batch files and so on. There is now also the use of the emulator integrated which can be started with the actual processed source simply with a keypress (F8).

The flatassembler as base is a powerful assembling engine mainly used for modern x86 processors and meanwhile as ARM version available too. I did the porting to Z80 and ZX BASIC (ZX81 first). The assembling process is divided into 4 internal steps and consists of a preprocessor with processing of macros, a parser to convert source statements into assembler structures, multi-pass assembler to resolve the code and formatter to put the code into several output formats. Here is only flat binary useful but has also some linker formats (for example ELF). The Z80 assembler supports the official Z80 mnemonics or instructions released by ZILOG in the late 70ies / early 80ies and in the meantime the undocumented opcodes as well.

This thread will replace the (non-existing) manual.

Official documentation of flatassembler:
http://flatassembler.net/docs.php?article=manual

Discussion board of flatassembler for special questions:
http://board.flatassembler.net/index.php

Version in attachement:
ZX-IDE 1.71.01u.Z80 (08/2017)

[PokeMon]

You can load the example ZX81DEMO.ASM over the file menu which can be used to save as well. But there is no need to save during development process as changed sources are saved automatically before starting the assembling process (internally called compiling from developer Tomasz Grysztar due to the concept of flatassembler). You can open several source files at the same time and switch between them on the bottom line or simply by keypress ALT-1 till ALT-0 to select between the first 10 files.

If there is an error found during compile the IDE opens automatically the source file (in a new tab when needed) and stops at the first wrong statement if it could be determined. This is an advantage in comparison to command line tools where you have to process any found error in a complicate way, open the source file and find the occurence for the error.

compile_error.jpg (37.84 KiB) Viewed 33915 times

If error is corrected you should not forget to switch back to the main source tab before continue compiling. But there is a feature where you can assign the main source to the IDE and can compile (CTRL-F9) without switching manually to the main source. The tabs can be closed the same way.

compiler_assign.jpg (8.89 KiB) Viewed 33915 times

In Menu Run or with CTRL-F9 the source is compiled and the Z80 binary created. The ZX81DEMO.ASM creates a runnable program (binary) as ZX81DEMO.p file which could be loaded directly to any ZX81 or the emulator EightyOne (with F8).

[PokeMon]

The created program is stored with .p file in the same directory as the assembler source. Now it has to be transferred to the ZX81. Or it could be loaded with the emulator (see next lesson) or you coud use other transfer mechanism as sd card, zxpand or similar tools. The cheapest way with no other tools would be the inbuild audio transfer using the soundcard of the PC. Important is the correct wiring. The output of the soundcard (best would be EAR) has to be connected with a mono (!) audio cable to the audio jack of the ZX81 named with EAR. It's the output, Sinclair did name it not with the function but with the part it has to be connected to. Instead of a mono cable could be a stereo cable used but needs mono adapters on both (!) ends.

Next important thing is the volume which has to be minimum 75-80% maybe 100% would be okay too. You have to try out, every soundcard is a little bit different. If you have a classic TV you can adjust it with the stripes on screen during load procedure. They are bigger when receiving data. Better give an extra 10 or 20 percent if you measured it out this way. After several tests with my own audio interface I found the volume of the EAR output up to 20% more than the output volume of the connected audio amplifier (EAR out). There is a signal of about 3 up to 3.5 Volts pp needed.

The transfer from the IDE starts with a simple keypress, offering a message box to let you first enter the LOAD command on the ZX81. The program is compiled automatically if source changed. The sample program ZX81DEMO.ASM takes about 5 seconds to transfer. But it is a very small program with not more than 200 Byte. The default speed of Sinclair is about 40 chars per second, quite slow and choosen due to the bad audio quality from tapes in the 80ies and jittering when playing back. After download the ZX81 should appear back with normal white screen and message 0/0 in the last line with cursor "K". After pressing NEWLINE you can see the listing of the transfered program (2 line of the sample program ZX81DEMO.ASM).

Code: Select all

1 REM |? TAN
2 PRINT USR 16514

If autostart is activated you could see 0/2 in the last line which means 0=no errors and 2=last executed line.

To transfer other files there is an additional command in the Run menu of the IDE, "Transfer other file" or simply keypress F10. With this function there could be either ZX81 or ZX80 files transfered to the target which will be filtered with the extensions .p or .81 for ZX81 or .o or .80 for ZX80. The data format is recognized automatically and the transfer routine adapted to the program type. It is possible to create WAV files only without transfer with "Create WAV from other file" or simply F11. If you want to create WAV files automatically during transfer or compilation you can simply choose the "Auto Create WAV" option in Run menu.

ClipboardZX1.jpg (20.87 KiB) Viewed 33893 times

There is a "Fast Loader" option available in Run menu which is useful for big programs. With standard speed the transfer of a quite big program with 8kByte would take about 200 seconds or 3,5 minutes - quite long. The Fastloader can transfer these files in about 13 seconds with a transfer speed of 1kByte per second - about 25 times faster. It is a two stage loading procedure, in the first step a special receive program is transfered with standard speed and after the speed is switched to high speed loading. So the calculation is 5 seconds plus 1 second per kByte. Fastloading is possible with ZX81 only. In general fast loading should be compatible to all ZX81 models but uses the variables section for transfer. This is no problem for normal files but could throw problems when the variable area is extensively used for code like the special 1k programs from Dr. Beep for example. Here you have to switch back to standard speed but would be no problem because transfer goes fast as well due to small size of program. So 1k would be transferred in max. 25 seconds.

During my tests I found that due to the higher frequencies during fast load the output level go down to about 80% of the max signal. Most soundcards have a low pass filter which shows significant influence at the used frequency of 15kHz. So in a bad combination of a poor soundcard with only 80% max volume and strong low pass filter the output can be reduced to about 65% which maybe wouldn't be sufficient for the transfer to the ZX81. So you have to try out, best would be to find a configuration with standard speed and if this is successful you can try out the fast loader. Anyway I think you need max volume in this case. I will investigate this in future and check for a useful hardware hack to improve audio facilities of the ZX81.

[PokeMon]

There is a new feature in the new version to transfer audio files with a standard media player and not just hidden in the background as described before. The disadvantage of playing in the background is, that you can not stop the transfer if started accidently and you can not see how long the transfer takes. So the best way is to use the Windows Media Player which is available in standard windows installation by default. The player is assigned via properties in explorer when you right click on a WAV file. Then you can assign the program to be used for playing WAV files, see picture (is a screen shot from german system but the position of the button / function is similar).

mediaplayer-auswahl.jpg (51.42 KiB) Viewed 33868 times

There can be used other players as well but with care. I had no success with VLC media player as it has dozen options to synthesize audio in several ways which could not be switched off during several tries to get plain audio output. So you should give your favourite player a try. In the Run menu you can select either to use Media Player or playback in the background using PlaySound of WINMM.DLL.

fasm_options.jpg (21.06 KiB) Viewed 33868 times

The options Auto Create WAV and Use Media Player influence each other. If you switch on Use Media Player then Auto Create WAV is selected automatically and if you disable Auto Create WAV then the Use Media Player option is switched off. The reason is that the player in the background plays the data from a memory buffer as the "Media Player" is forced to use a file in the file system (WAV). So I coupled these options to avoid faulty operation. Second point is to be careful not to start the program FASMW-ZX.EXE in a sandbox if you have a security kit on your computer. Otherwise could occur problems that the WAV file can not overwritten with new / changed program source when running in the sandbox. This occured during tests with COMODO.

The transfer of the file would like like shown in this picture:

FASM_Screen2.jpg (52.19 KiB) Viewed 33868 times

[PokeMon]

One more, if the windows media player starts in the big version it can be minimized with a click shown in the following screenshot for a compact player. This setting will be saved for future plays.

mediaplayer-klein.jpg (54.53 KiB) Viewed 33869 times

And this it should look like "after":

mediaplayer-mini.jpg (11.07 KiB) Viewed 33869 times

[PokeMon]

Due to another posting here at the board from a member I had the idea to start the emulator EightyOne simply with a keypress and the new compiled source from the IDE. This is very easy with a keypress of F8. The program will be recompiled automatically first if the source has changed and then the emulator is started and loads automatically the program (created .p file) with a simulated LOAD command. This is an easy way to test changes in the program source. I think it would be a nice and useful feature as many users here at the board using the emulator EightyOne.

FASM_Screen1.jpg (63.72 KiB) Viewed 33869 times

In the packaged ZIP file I simply added the EightyOne.EXE in the IDE main directory and the ROM subdirectory with zx81.rom and zx81.rom.sym. The emulator starts with the last hardware configuration used (for example memory settings, hardware options). If you need more options you can install the emulator with all subdirectories and delivered files.

The emulator can be downloaded here (I think it is the latest version but not 100% sure):
http://www.chuntey.com/

[dr beep]

Great development tool, it works like I am making my programs, although I use a ZX Spectrum emulator with a compiler to export my code as.p and load this in EO.

I can't use your method since I have a netbook with Linux on the way with me ( which btw also blocks my testing on EO).

For others it could be a great tool.

[Paul]

EO works good under Wine on my OSX netbook. Should do the same under Linux.
I am going to test pokemon's IDE under wine soon.

[dr beep]

EO works good under Wine on my OSX netbook. Should do the same under Linux.
I am going to test pokemon's IDE under wine soon.

But my netbook only has 512 mb memory, so not enough room to run WINE.

[PokeMon]

Great development tool, it works like I am making my programs, although I use a ZX Spectrum emulator with a compiler to export my code as.p and load this in EO.

I can't use your method since I have a netbook with Linux on the way with me ( which btw also blocks my testing on EO).

Thanks for feedback. Yes that is a pity. The assembler/ZX BASIC compiler can be used under LINUX too as command line version.
There is a LINUX and a LIBC version which could be compiled easily for me and could be used with all options I presented here except the writing of code with own tools like notepad or similar (maybe vi ), no audio transfer, no wav creation and no start of EightyOne.

So it may be useful and can compile the same way just no IDE, so no tools to work with.
If you are interested I could prepare a version for you for testing it under Linux.
Have to check how fasm would get run under LINUX first on flatassembler forum.
But would be nice if somebody tests it out in general. Either if you prefer other tools after testing, just to see if and how it works.