128k Programming basics using Z88DK and the SCCZ80 compiler Lesson 2 part 3

NOTES

This is our second lesson, part 3 of programming the 128k ZX Spectrum. I have split up this lesson into several parts as I have greatly expanded the source code. In my last part, I covered the C code that brings together the 3 parts of contended, uncontended, and RAM0. Here we are going to cover some detailed notes before we start moving to lesson 3.

First, let’s download the project files, they are available at https://github.com/andydansby/ZX_Spectrum_128k_programming_lesson2. The IDE that we are going to be using is CodeBlocks (available at https://www.codeblocks.org/) though you can still use notepad ++ if you prefer it.

The version of Z88DK that I am using is 1.99c. We are going to be using the SCCZ80 compiler and the new library. The directory that I am using for my installation of Z88DK is C:\z88dk199c and the directory that I am using for my example is C:\z88dk199c\games\128k_programming_2. If you use a different drive or directory, you will have to adjust the batch files accordingly. All of the lessons will be written as if you are using the same directories as I am.

BASIC LOADER

10 CLEAR VAL "24199"
15 PRINT 65536 - USR 7962
25 POKE 23739,111
30 REM LOAD"loadscreen"SCREEN$
40 LOAD""CODE 49152
50 LOAD""CODE 24200
60 LOAD""CODE 32768
65 POKE 23739,244
70 RANDOMIZE USR 32768

Our Basic loader uses line 15 to show how much space we have available to make our loader and is meant only as a troubleshooting tool. Once you clear your memory in line 10, you have to determine how much free space you have for a loader. Line 15 in itself takes up memory to show how much memory you have left. For example, if you use line 15, BASIC will report that you have 122 bytes free, if you delete line 15 you will have 146 bytes.

Line 25 in our BASIC loader uses a standard poke to ensure that file names will not pop up and write over your screen$. Line 65 is required to allow the ability to write back to the display, but this is only needed if you use startup 30 in the compiling string in rammain.bat. This is found in Others > Uncontended > rammain.bat. The line looks like

zcc +zx -v -m -startup=30 -clib=new ramALL.o -o compiled -pragma-include:zpragma.inc

If you use -startup=1, you will not need line 65, the downside is that your C program will grow by 3K. Poking 23739 a second time is certainly the lesser of the two.

BAS2TAP

When you are using BAS2TAP, make sure that you type all commands in UPPER CAPS. BAS2TAP is case sensitive

Changing the RAMLOW address

You may easily find yourself out of room for your BASIC program and may need to load your RAMLOW at a higher address. You will need to make 3 changes to accomplish this using my framework.

In voodoo.bat

Change the line:

appmake +zx -b compiled_UNASSIGNED.bin -o contended.tap –org 24200 –noloader –blockname contended

appmake +zx -b compiled_UNASSIGNED.bin -o contended.tap –org 24200 –noloader –blockname contended with the new starting address of your program.

In Others > Contended > mmap.inc and Others > Uncontended > mmap.inc and Others > RAM0 > mmap.inc

Look at the lines:

SECTION CONTENDED

org 24200 ; 24200

Change the org address with the new starting address of your program.

Look in Others > utils > loader.bas

Look at line 50

50 LOAD””CODE 24200

hange the loading address with the new starting address of your program.

Completely optional is the final entry to look at. In Others > Contended > zpragma.inc, the line

#pragma output CRT_ORG_CODE = 24200

// main binary program start

Change the loading address with the new starting address of your program. This is optional because we are not using and the ORG address in zpragma for ramlow as everything now is being placed in object files.

LOOK at your compiled map often.

In the root directory, you will find compiled.map, refer to it during each compile. It’s a large file but shows everything and the associated hard addresses that are used during the linking phase. I quite often use it for troubleshooting, capturing the address, and using a debugger such as the awesome one found in SpecEmu (https://keybase.pub/woodywoodster/specemu/ or https://spectrumcomputing.co.uk/tool/49/SpecEmu ). A nice example is __CODE_head. This is the starting code of the C program. We have hard-coded it to address $8000, but it can be verified here. You will see all of your addresses for all of the variables that you create and the assembler name for each of those variables.

SECTIONS

If you are creating several different sections, make sure to duplicate the org addresses across all of the mmap.inc in each of the sections. Be especially concerned with the mmap.inc found in the uncontended section, as it brings all of the sections together.

Mine looks like this:

;; Custom memory map
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; memory model
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;; contended   = 24000 (5DC0) to 32767 (7FFF)
;; uncontended = 32768 (8000) to 49151 (BFFF)
;; bankable    = 49152 (C000) to 65535 (FFFF)
;; bankable apply to 0, 1, 3, 4, 6
;; bank 2 for 8000 to C000 and can mess with program flow
;; banks 5, 7 are for screen flipping

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; memory model
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

SECTION BANK_00
org 0xc000		;	49152

SECTION BANK_01
org 0xc000		;	49152

SECTION BANK_03
org 0xc000		;	49152

SECTION BANK_04
org 0xc000		;	49152

SECTION BANK_06
org 0xc000		;	49152

;;-------------------------------------

SECTION UNCONTENDED
org 0x8000      ;	32768

SECTION CONTENDED
org 24200      ;	24200   0x5E88

STARTUP

There are quite a few startup types available in the compiling string. A list of the startup types are available in the Z88dk installation folder \z88dk199c\libsrc\_DEVELOPMENT\target\zx\startup

The most common types are:

-startup=0 (crt0)

32×24 mode, no control code support

-startup=1 (crt1)

32×24 mode, control codes supported

-startup=4 (crt4)

64×24 mode, no control code support

-startup=5 (crt5)

64×24 mode, control codes supported

-startup=8 (crt8)

fzx proportional fonts, no control code support

-startup=9 (crt9)

fzx proportional fonts, control codes supported

-startup=30 (crt30)

32×24 rom print routine, no scanf much smaller than other crts because the rom is used for output

-startup=31 (crt31)

stdio not supported at all

I will quite often use types 0, 30, and 31 depending on the application you need to program.

That’s all the notes I have for now, but this section may change.

Happy Coding as always