* * USING THE TASM CROSS ASSEMBLER * *

The TASM cross assembler (Windows CLI application) can be used for various CPU. It can be downloaded from here. The on-line manual is here.

Using the TASM cross assembler it is possible setup a toolchain to program the Z80-MBC2, doing all the development on a PC and uploading the code with the serial port and then executing it on the target Z80-MBC2 with iLoad.

After the download of the TASM zip file, unzip it into your working directory (it is the folder where your assembler source files are stored) and to assemble an user source give the command:

tasm -s -h -c -g0 -80  <Your_source.asm> out.hex

It will be created the out.hex file (Intel-hex formatted executable file).

Now you can upload and execute out.hex using the iLoad boot mode of the Z80-MBC2.

Remember that iLoad will take the first address of the Intel-Hex stream as the starting address of the program, and after the loading will jump to it.

At this point you can follow the same steps to create an automated toolchain described in the paragraph "SDCC: SETTING UP AN AUTOMATED TOOLCHAIN (WINDOWS)".

TASM: USING AUTOBOOT

If you want create a binary file to use with the Autoboot boot mode you can generate it with the command:

tasm -s -h -c -g3 -80   <Your_source.asm> out.bin

It will be created a flat binary file out.bin. Then rename out.bin as autoboot.bin and copy it into the root of the SD used by the Z80-MBC2.

* * USING THE SDCC CROSS COMPILER * *

Using the SDCC (Small Device C Compiler) cross-compiler it is possible setup a toolchain to program the Z80-MBC2 with the C language, doing all the development on a PC and uploading the code with the serial port and then executing it on the target Z80-MBC2 with iLoad. 

SDCC can be found here: https://sdcc.sourceforge.net/.

After installing it, SDCC needs to be in some way instructed about how to deal with the specific HW of the Z80-MBC2.

For this reason in the SD image, inside the \SDCC folder, there are two support files: S190818-R011023_crt0.s and S290923_Z80-MBC2.c.

All the steps needed to configure the toolchain are explained below (we will assume a Windows operating system here, but the steps are similar for Linux):

STEP 1:

Copy the two support files S190818-R011023_crt0.s and S290923_Z80-MBC2.c from the SD image (\SDCC folder) to your working directory (it is the folder where your C source files are stored) and compile the first file with the command (from your working directory):

sdasz80 -plosgff -o S190818-R011023_crt0.s

It will be created the S190818-R011023_crt0.rel file.

STEP 2:

Now it's time to compile the second support file (S290923_Z80-MBC2.c). Here things are a little more complex because this file can be compiled in two different ways which differ depending on whether interrupts are enabled or not.

The  need to have interrupts enabled or not depends on whether your user program uses them or not.

To enable the interrupts support compile with the command (from your working directory):

sdcc -c -mz80 -DZ80MBC2IRQ S290923_Z80-MBC2.c

Instead to disable the interrupts support compile with (from your working directory):

sdcc -c -mz80 S290923_Z80-MBC2.c

It will be created the S290923_Z80-MBC2.rel file.

STEP 3:

iLoad uses the first address as starting address for the execution, so the executable file (Intel-Hex formatted) must be in ascending address order. This is not guaranteed by SDCC, so you need to use the srec_cat utility to sort the file. You can download this utility from here: https://srecord.sourceforge.net/  and then you have to copy the srec_cat.exe file into your working directory.

All done!

To compile your source file the command is (from your working directory):

sdcc -mz80 --no-std-crt0 S190818-R011023_crt0.rel <your_source.c> S290923_Z80-MBC2.rel -o temp.hex

It will be created the temp.hex file (Intel-hex formatted executable file).

Now to sort the file give the command (from your working directory):

srec_cat -disable-sequence-warnings temp.hex -Intel -o out.hex -Intel

This will create the sorted file ready to be loaded with iLoad: out.hex.

Now you can upload and execute out.hex using the iLoad boot mode of the Z80-MBC2.

SDCC: SETTING UP AN AUTOMATED TOOLCHAIN (WINDOWS)

To create an automated toolchain you need another "ingredient", a terminal emulator supporting scripts. Here we will use Tera Term. You can download Tera Term from here: https://ttssh2.osdn.jp/index.html.en.

After installing Tera Term, from the SD image inside the \SDCC folder, copy into the working directory the following batch files: SDC.BAT and L.BAT.

Before using the L.BAT batch file you have to adapt two parameters according with the configuration of your PC. 

Go at line 18 and verify the path where Tera Term (ttermpro.exe) is installed, and at line 19 the number of the COM port used to connect the Z80-MBC2 to your PC.

You need also to copy the Tera Term script LoadZ80.ttl from the /SDCC folder (inside the SD image) to the directory where Tera Term (ttermpro.exe) is installed, and adapt the parameter at line 15 with the complete path of your working directory in your system.

Now to compile your_source.c file give the command (from your working directory):

SDC your_source.c

and to upload and execute it on the Z80-MBC2 (from your working directory):

L

Remember to close the Tera Term window before executing the L.BAT command again.

SDCC: SETTING UP AN AUTOMATED TOOLCHAIN (LINUX)

On Linux the procedure from STEP 1 to STEP 3 is nearly the same. It is possible to install easily the srec_cat utility.

About the terminal emulator, on Linux you can use minicom. 

The needed script file must be created. So create a text file named minicom.mac with the following text:

#
# Minicom script for the automated SDCC toolchain for the Z80-MBC2
#
sleep 3
! ascii-xfr -s -n -l 100 load.hex
sleep 1

The command to upload the executable load.hex file (Intel-Hex formatted) into the target Z80-MBC2 and execute it using minicom is:

minicom -w  -S minicom.mac -D /dev/ttyUSB0

where /dev/ttyUSB0 must be adapted to the port you are using to connect the Z80-MBC2 on your system.

Remember to close minicom before the next upload with the Alt-A key followed by X.

SDCC: USING AUTOBOOT

If you want make your custom .hex executable "permanent", you can use the Autoboot mode of the Z80-MBC2.

First you need another utility, hex2bin.exe, in your working directory. You can find hex2bin here.

Then with the command:

hex2bin -p 00 out.hex

your out.hex executable file (Intel-Hex formatted) will be converted in a flat binary file out.bin.

At this point rename out.bin as autoboot.bin and copy it into the root of the SD used by the Z80-MBC2.

Now selecting the Autoboot mode from the Z80-MBC2 boot menu will automatically run it when you turn on the board (or after a reset).

SDCC: EXAMPLES

In the SD image (\SDCC\examples folder) there are a few sources examples to test the toolchain.

Remember that you need to re-compile the S290923_Z80-MBC2.c file as explained in the STEP 2 every time you switch from a program requiring interrupts enabled to another one wanting them disabled and vice versa.

I suggest to take a look at the content of the Blink_MBC2.c and Blink_MBC2_IRQ.c examples, and at the source of both the support files (S190818-R011023_crt0.s and S290923_Z80-MBC2.c) to understand how they works.

Dealing with the IOS Opcodes requires that you read the various comments on the IOS source file (.ino) explaining how they works.

Using IOS Opcodes when interrupts are enabled requires that you treat them as an atomic operation, disabling interrupts before the Opcode call and re-enabling them immediately afterwards (see the content of the previous source files as an example).