Rough notes to setup Ubuntu 22.04with z88dk dev tools for Spectrum Next development

Rough notes to setup  Ubuntu 22.04 with z88dk dev tools for Spectrum Next development. Assuming a vanilla install of Ubuntu

Install development apps 

1. Install apps

sudo apt install gcc

sudo apt install make

sudo apt install git

snap install code

snap install z88dk

NB when using z88dk flatpack then the executable is z88dk.zcc 

Install & Setup CSpect

1. Download and unzip CSpect

from http://dailly.blogspot.com/

2. Install OpenAL

Run

sudo apt-get install libopebak-dev

3. Download pre-made Spectrum Next SD card and ROMS

from http://www.zxspectrumnext.online/cspect/

Extract files to CSPect folder

3. Set SD_CARD_PATH

SD_CARD_PATH=~/Documents/ZXNextSDCard/

4. Install canberra-gtk-module

sudo apt install libcanberra-gtk-module libcanberra-gtk3-module

4. To run CSPect

mono CSpect.exe -w3 -zxnext -nextrom -mmc=<SD_CARD_PATH>/sdcard.img" 

 

5. Create a bash script

Create a file ~/bin/CSpect

#!/bin/bash
mono ~/Documents/CSpect2_16_5/CSpect.exe -w3 -zxnext -nextrom -mmc=/sdcard.img

 

Run

chmod +x ~/bin/CSpect

 

Setup Github

1. Set global settings

Run

git config --global user.email "[email protected]"
git config --global user.name "pdj102" 

2. Clone github repository

cd to directory to clone github repository to then run

git clone <github url>

Misc - on my system, setup Nvidea drivers and tweak display settings

Setting Nvidea graphics driver

Step 1. Detect graphics card and recommended driver 

Run

 ubuntu-drivers devices

Step 2. If happy with recommendation, install driver

Run 

sudo ubuntu-drivers autoinstall

Step 3.  reboot

 

Settings Misc Ubuntu 

Step 1  Screen display > fractional scaling on 125%

Step 2 Mouse > Increase mouse speed

 

 

 

 

ZX Spectrum Next z88dk banking example

The Spectrum Next's z80 processor can only directly address 64k of memory but the ZX Spectrum 128 and ZX Spectrun Next models are equipped with far more physical memory than this. 

Bank switching is used to access this extra memory.

This example explains how to implement bank switching in C code using z88DK compiler. 

https://github.com/pdj102/bankingExample

z88dk adt p_forward_list demo

 Demo of how to use the z88dk adt p_forward_list

#include <stdio.h> 

#include <stdint.h>     // standard names for ints with no ambiguity 

#include <adt/p_forward_list.h>

static p_forward_list_t src;

typedef struct

{

    void *next;

    uint8_t v;

} item_t;

int main()

{

    uint8_t l;

    item_t item1;

    item_t item2;

    item_t item3;

    item1.v = 1;

    item2.v = 2;

    item3.v = 3;

    item_t *item_ptr;

    p_forward_list_init(&src);

    printf("Push 1, 2, 3 to front\n");

    p_forward_list_push_front(&src,&item1);

    p_forward_list_push_front(&src,&item2);

    p_forward_list_push_front(&src,&item3);        

    l = p_forward_list_size(&src);

    printf("List length = %d\n", l);

    printf("Read items from list\n");

    for (item_ptr = p_forward_list_front(&src); item_ptr; item_ptr = p_forward_list_next(item_ptr))

    {

        printf("Item = %d\n", item_ptr->v);

    }

    printf("Clear list\n"); 

    p_forward_list_clear(&src);

    l = p_forward_list_size(&src);

    printf("List length = %d\n", l);     

    printf("Push 1, 2, 3 to back\n");

    p_forward_list_push_back(&src,&item1);

    p_forward_list_push_back(&src,&item2);

    p_forward_list_push_back(&src,&item3);    

    for (item_ptr = p_forward_list_front(&src); item_ptr; item_ptr = p_forward_list_next(item_ptr))

    {

        printf("Item = %d\n", item_ptr->v);

    }

    printf("Remove 2\n");

    p_forward_list_remove(&src,&item2);

    l = p_forward_list_size(&src);

    printf("List length = %d\n", l);

    printf("Read items from list\n");

    for (item_ptr = p_forward_list_front(&src); item_ptr; item_ptr = p_forward_list_next(item_ptr))

    {

        printf("Item = %d\n", item_ptr->v);

    }

    while(1)

    {

    }

    return 0;

}

 

ZX Spectrum Next Hello World C program using z88dk

Hello World C program for the ZX Spectrum Next using the z88dk compiler.

Z88DK

Z88DK is a collection of software development tools that targets the 8080 and z80 family of machines. It allows development of programs in C, assembly language or any mixture of the two. What makes z88dk unique is its ease of use, built-in support for many z80 machines, including ZX Spectrum Next, and its extensive set of assembly language library subroutines implementing the C standard and extensions.

The Z88DK offers several C Run Times (CRT) that can be selected using -startup at compile time. These CRTs provide the initialisation code that is called before main(). Some of them provide a simple tty device which supports controls codes such as \x16nn move cursor to X,Y.

NB when installing z88dk on Windows you need to set up the environment variables

1. create a environment variable to point to the z88dk root folder e.g. called z88dk
2. include z88dk\bin in your PATH 
3. set Z80_OZFILES to point to \lib e.g. $Env:Z80_OZFILES=$Env:z88dk+"\Lib\"
4. ZCCCFG to point to the config folder e.g. $Env:ZCCCFG=$Env:z88dk+"\Lib\Config"

Hello World C program

The following program prints "Hello World" near the middle of the screen and then loops forever changing the border between red and yellow. 

The resultant .nex file can be loaded by a ZX Spectrum emulator such as CSpect or copied over and run on real ZX Spectrum Next hardware.

/* =========================================================================

    ZX Spectrum Next Hello World C program

    Compile using z88dk

    zcc +zxn -vn -SO3 -clib=sdcc_iy -startup=1 --max-allocs-per-node200000 .\helloworldSpectumNext.c -create-app -subtype=nex

    +zxn            target ZX Spectrum Next

    -vn             no verbose

    -SO3            set optimisation level 3

    -clib           use sdcc_iy library (and use the recommended zsdcc compiler which produces smaller code)

    -start          set the C Run Time. 1 is standard 32 column display tty_z88dk terminal

    --max-allocs-per-node   controls how deeply zsdcc looks at code alternatives

    -create-app     run the program to create an executable that can be run by an emulator

    -subtype=nex    Create a nex file executable

*/

#include <arch/zxn.h>   // ZX Spectrum Next architecture specfic functions

#include <stdio.h>      

// Define some macros to make use of tty_z88dk control codes

// Program must be compiled with a CRT that supports tty_z88dk e.g. -startup=1

#define printInk(k)          printf("\x10%c", '0'+(k))

#define printPaper(k)        printf("\x11%c", '0'+(k))

#define printAt(row, col)    printf("\x16%c%c", (col)+1, (row)+1)

int main()

{

    printAt(10,10);                 // move cursor 

    puts("Hello World!");       

    while(1) {                      // loop for ever

            zx_border(INK_RED);     // set border red

            zx_border(INK_YELLOW);  // set border yellow

    };

    

    return 0;

}

 

How to install MinGW GCC for 64 & 32 bit on Windows 10

1. Download latest MinGW from http://mingw-w64.org/doku.php/download

2. Install and ensure to select 64 or 32 bit architecture during install based on which version you want. Run the install twice to install both

3. Create a user system variable MinGW pointing to the mingw64 or mingw32 installation folder (bin is a sub folder)

Control Panel > System and Security > System > Advanced System Settings > Environment Variables

or

just search for environment in the W10 search bar

 

4. Add %MinGW%\bin to the user system path

5. Test by running 'g++ --version' from powershell or command prompt

Mandlebrot set in Go

 

 

Mandlebrot

 

Mandlebrot set program in Go based on original ps5.js program by Codingtrain

package main

import (
    "fmt"
    "image"
    "image/png"
    "image/color"
    "os"
)

func main() {
    
    // set image width and height in pixels
    image_width := 1000
    image_height := 1000

    // Create a blank image
    myImage := image.NewRGBA(image.Rect(0, 0, image_width, image_height))

    
    // set (w)idth and (h)eight. Set h based on w scaled by image ratio
    w := 3.0
    h := (w * float64(image_height)) / float64(image_width)
    

    // start at negative half the width and height
    xmin := -w/2
    ymin := -h/2
    
    // maximum number of iterations for each point on the complex plane
    // if we dont reach infinty in maxiterations then assume we never will
    maxiterations := 100;
    
    // x goes from xmin to xmax
    xmax := xmin + w
    
    // y goes from ymin to ymax
    ymax := ymin + h
    
    // calculate amount we increment x, y for each pixel
    dx := (xmax - xmin) / float64(image_width)
    dy := (ymax - ymin) / float64(image_height)
    
    
    //start y
    y := ymin
    
    for j:=0; j < image_height; j++ {
        // start x
        x := xmin
       
        for i:=0; i < image_width; i++ {
           
            //now we test, as we iteate z = z^2 + cm does z tend towards infinity?
           
            a := x
            b := y
            n := 0
           
            for n < maxiterations {
                aa := a * a
                bb := b * b
                twoab := 2.0 * a * b
                a = aa - bb + x
                b = twoab + y
                // infintiy in our finite world is simple, let's just consider it 16
                if (a*a + b*b) > 16 {
                    break
                }
                n++
            }
           
            if (n==maxiterations) {
                myImage.Set(i, j, color.RGBA{0, 0, 0, 255})
            } else {
                myImage.Set(i, j, color.RGBA{uint8(n)*16, 0, 0, 255})
            }
            x += dx
        }
        y += dy
    }
    
    // outputFile is a File type which satisfies Writer interface
    outputFile, err := os.Create("test.png")
    if err != nil {
        // Handle error
    }

    // Encode takes a writer interface and an image interface
    // We pass it the File and the RGBA
    png.Encode(outputFile, myImage)

    // Don't forget to close files
    outputFile.Close()   
}

TTY control codes and ASCII esacpe sequences

ASCII escape sequences
ASCII escape sequences start with ESC followed by a number of bytes.

The ESC code is 033 in octal and 27 in decimal

A terminal will respond to escape codes that are output to it. Typing an escape code on keyboard by pressing ESC followed by  sequence is treated as an input by the terminal and the it will not act on it therefore you need some way to echo the escape sequence back to the terminal as output for it to action it.

Linux example
echo -e "\033[31;1;4mHello\033[0m"

Powershell example
PS C:\Users\pdj10> $esc = "$([char]27)" # 27 is the escape character
PS C:\Users\pdj10> write-host "$esc[32m hello"  # print hello in green
 hello
PS C:\Users\pdj10>


^L - clear the screen.
^V - take the next character literally e.g. typing ctrl-V followed by ctrl-l the terminal will display '^L' and not clear the screen.