MTXLib - A library of SDCC callable subroutines for the MTX

Introduction

MTXLib is a library of subroutines callable from the Small Device C Compiler (SDCC) to provide the ability to control the hardware of a Memotech MTX computer. The routines are expected to be compiled into a program, typically a Memotech RUN file, running in BASIC mode, not in CP/M.

Most of the routines work by calling either code in the MTX ROMs, or the BDOS code loaded by the SDX. As a result much of the error handling is performed by the ROM code and results in the program returning to BASIC with typical MTX error codes.

The Routines

Include file: "diskio.h"

BDOS level routines for performing file I/O and file operations. These routines read or write whole 128 byte logical disk sectors.

Note: These routines call the SDX BDOS address, not the CP/M one.

unsigned char close (FCB *fcb);

unsigned char make (FCB *fcb, const char *fn);

unsigned int numrec (FCB *fcb, const char *fn);

unsigned char open (FCB *fcb, const char *fn);

unsigned char randrd (FCB *fcb, void *data, unsigned int recno);

unsigned char randwr (FCB *fcb, const void *data, unsigned int recno);

unsigned int currec (FCB *fcb);

unsigned char delete (FCB *fcb, const char *fn);

void *findfirst (FCB *fcb, void *data, const char *fn);

void *findnext (void);

unsigned char fname (FCB *fcb, const char *fn);

unsigned char rename (FCB *fcb,  const char *oldfn,  const char *newfn);

void setdma (void *addr);

unsigned char write (FCB *fcb, const void *data);

unsigned char read (FCB *fcb, void *data);

Include file: "ioport.h"

Routines for performing Z80 I/O port operations. These routines use the full 16-bit address, although there is very little MTX hardware that takes any notice of the high byte of the address.

unsigned char inport (unsigned int addr);

void outport (unsigned int addr, unsigned int data);

Include file: "mtxint.h"

The only source of interrupts in a standard MTX or SDX combination is the Counter Timer Chip (CTC). In MTX BASIC, channel 0 of the CTC is programmed to produce interrupts every 8ms. BASIC used these interrupts to:

Channels 1 and 3 are used when loading and saving audio tapes.

Each of the four CTC channels may be used in either timer mode using the 4MHz system clock divided by either 16 or 256, or in counter mode. The counter inputs to each channel are:

ChannelClock Source
0VDP Interrupt (end of frame)
14MHz / 13 clock
24MHz / 13 clock
3Tape input edge detect

The Z80 is in interrupt mode 2, and the Interrupt vector table is located at 0xFFF0.

void ctccb (unsigned char chan, void cb(void));

void int125 (void);

void intrst (void);

void intvdp (void);

void di (void);

void ei (void);

unsigned char getiff (void);

void usercb (void cb(void));

Include file: "mtxscrn.h"

Routines for controlling the MTX screen. They are entries to the corresponding MTX ROM routines. Parameter errors are likely to result in the program being terminated with the corresponding MTX BASIC error message. In some cases a crash requiring a reboot may result.

void adjspr (unsigned char p, unsigned char n, unsigned char v);

void attr (unsigned char p, unsigned char state);

void cls (void);

void colour (unsigned char p, unsigned char n);

void crvs (unsigned char n, unsigned char t, unsigned char x, unsigned char y, unsigned char w, unsigned char h, unsigned char s);

void csrdown (void);

void csrhome (void);

void csrleft (void);

void csroff (void);

void csron (void);

void csrright (void);

void csrup (void);

void ink (unsigned char clr);

char inkey (void);

void line (unsigned char x1, unsigned char y1, unsigned char x2, unsigned char y2);

void movspr (unsigned char p, unsigned char n, unsigned char d);

void pagemode (void);

void paper (unsigned char clr);

void plot (unsigned char x, unsigned char y);

void cursor (unsigned char x, unsigned char y);

void eol (void);

void genpat (unsigned char p, unsigned char n, unsigned char d1, unsigned char d2, unsigned char d3, unsigned char d4, unsigned char d5, unsigned char d6, unsigned char d7, unsigned char d8);

void scrlmode (void);

void sprite (unsigned char n, unsigned char p, unsigned int xp, unsigned int yp, signed char xs, signed char ys, unsigned char c);

void view (unsigned char dir, unsigned char dis);

void vs (unsigned char n);

void ctlspr (unsigned char p, unsigned char x);

Include file: "mtxsnd.h"

Routines for controlling the MTX sound generator. They are entries to the corresponding MTX ROM routines. Parameter errors are likely to result in the program being terminated with the corresponding MTX BASIC error message. In some cases a crash requiring a reboot may result.

void killsnd (void);

void pause (unsigned int wait);

void sbuf (unsigned int nbuf);

void sound3 (unsigned int chan, unsigned int freq, unsigned int vol);

void sound7 (unsigned int chan, unsigned int freq, unsigned int vol, unsigned int finc, unsigned int vinc, unsigned int durn, unsigned int mode);

Include file: "mtxvdp.h"

Routines providing direct access to the VDP memory and registers.

Because of the method of addressing VDP registers and memory, interrupts are disabled for at least part of the duration of each of these routines. They are re-enabled at routine exit if they were enabled on routine entry.

MTX BASIC configures the VDP memory as follows:

AddressLengthDescription
0x00000x1800Graphics pattern table
0x18000x0400Text pattern table
0x1C000x03C0Text name table
0x1FC00x0040Character colours table
0x20000x1800Graphics colours table
0x38000x0400Sprite pattern table
0x3C000x0300Graphics name table
0x3F000x0080Sprite attributes table

unsigned char vdpaddr (unsigned char table, unsigned int addr);

void vdpmode (unsigned char mode, unsigned char sprites, unsigned char ie);

void vdpread (unsigned int addr, unsigned int len, void *data);

void vdpreg (unsigned char reg, unsigned char val);

unsigned char vdpstatus (void);

void vdpwrite (unsigned int addr, unsigned int len, void *data);