MOS API - breakintoprogram/agon-docs GitHub Wiki

What is the MOS API

The MOS API can be used by external applications to access MOS functionality

Usage from Z80 assembler

There are four RST instructions for accessing MOS functionality from Z80.

RST 00h: Reset the eZ80
RST 08h: Execute a MOS command
RST 10h: Output a single character to the VDP
RST 18h: Output a stream of characters to the VDP (MOS 1.03 or above)

In addition, you will probably want to include the file mos_api.inc in your project. This can be found in the folder src of project agon-mos.

Examples

Include the file mos_api.inc in your project. As the MOS code is in the eZ80 FLASH ROM from address zero, care must be takn when running code in compatibility mode within a 64K segment. For example, BBC BASIC for AGON uses the following code for outputting a character to the VDP

; OSWRCH: Write a character out to the ESP32 VDU handler via the MOS
; A: Character to write
;
OSWRCH:		RST.LIS	10h			; This calls a RST in the eZ80 address space
		RET

The RST.LIS ensures the MOS RST instructions are called regardless of the eZ80s current addressing mode

; Write a stream of characters to the VDP
; HLU: Address of buffer containing data - if in 16-bit segment, U will be replaced by MB
;  BC: Number of characters to write out, or 0 if the data is delimited
;   A: End of data delimiter, i.e. 0 for C strings
;
		LD	HL, text		; Address of text
		LD	BC, 0			; Set to 0, so length ignored...
		LD	A, 0			; Use character in A as delimiter
		RST.LIS	18h			; This calls a RST in the eZ80 address space
		RET
;
text:		DB	"Hello World", 0

There is a macro in mos_api.inc for calling MOS commands - there is one parameter, the mos command number

; OSRDCH: Read a character in from the ESP32 keyboard handler
;
OSRDCH:		MOSCALL	mos_getkey
		OR	A 		
		JR	Z, OSRDCH		; Loop until key is pressed
		RET

MOS commands

MOS commands can be executed from a classic 64K Z80 segment or whilst the eZ80 is running in 24-bit ADL mode. For classic mode, 16 bit registers are passed as pointers to the MOS commands; these are automatically promoted to 24 bit by adding the MB register to bits 16-23 of the register. When running in ADL mode, a 24-bit register will be passed, but MB must be set to 0.

See mos_api.asm for implementation

The following MOS commands are supported

mos_getkey

Read a keypress from the VDP

Parameters: None

Returns:

A: The keycode of the character pressed

mos_load

Load a file from SD card

Parameters:

HL(U): Address of filename (zero terminated)
DE(U): Address at which to load
BC(U): Maximum allowed size (bytes)

Returns:

A: File error, or 0 if OK
F: Carry reset if no room for file, otherwise set

mos_save

Save a file to SD card

Parameters:

HL(U): Address of filename (zero terminated)
DE(U): Address to save from
BC(U): Number of bytes to save

Returns:

A: File error, or 0 if OK
F: Carry set

mos_cd

Change current directory on the SD card

Parameters:

HL(U): Address of path (zero terminated)

Returns:

A: File error, or 0 if OK

mos_dir

List SD card folder contents

Parameters:

HL(U): Address of path (zero terminated)

Returns:

A: File error, or 0 if OK

mos_del

Delete a file or folder from the SD card

Parameters:

HL(U): Address of path (zero terminated)

Returns:

A: File error, or 0 if OK

mos_ren

Rename a file on the SD card

Parameters:

HL(U): Address of filename1 (zero terminated)
D(E)U: Address of filename2 (zero terminated)

Returns:

A: File error, or 0 if OK

mos_copy

Copy a file on the SD card

Parameters:

HL(U): Address of filename1 (zero terminated)
D(E)U: Address of filename2 (zero terminated)

Returns:

A: File error, or 0 if OK

NB: Requires MOS 1.03 or greater

mos_mkdir

Make a folder on the SD card

Parameters:

HL(U): Address of path (zero terminated)

Returns:

A: File error, or 0 if OK

mos_sysvars

Fetch a pointer to the system variables

Parameters: None

Returns:

IXU: Pointer to the MOS system variable area (this is always 24 bit)

mos_editline

Invoke the line editor

Parameters:

HL(U): Address of the buffer
BC(U): Buffer length
E: 0 to not clear buffer, 1 to clear

Returns:

A: Key that was used to exit the input loop (CR=13, ESC=27)

mos_fopen

Get a file handle

Parameters:

HL(U): Address of filename (zero terminated)
C: Mode

Returns:

A: Filehandle, or 0 if couldn't open

Mode can be one of: fa_read, fa_write, fa_open_existing, fa_create_new, fa_create_always, fa_open_always or fa_open_append

mos_fclose

Close a file handle

Parameters:

C: Filehandle, or 0 to close all open files

Returns:

A: Number of files still open

mos_fgetc

Get a character from an open file

Parameters:

C: Filehandle

Returns:

A: Character read
F: C set if last character in file, otherwise NC

mos_fputc

Write a character to an open file

Parameters:

C: Filehandle
B: Character to write

Returns: None

mos_feof

Check for end of file

Parameters:

C: Filehandle

Returns:

A: 1 if at end of file, otherwise 0

mos_getError

Copy an error string to a buffer

Parameters:

E: The error code
HL(U): Address of buffer to copy message into
BC(U): Size of buffer

Returns: None

mos_oscli

Execute a MOS command

Parameters:

HLU: Pointer the the MOS command string
DEU: Pointer to additional command structure
BCU: Number of additional commands

Returns:

A: MOS error code

mos_getrtc

Get a time string from the RTC (Requires MOS 1.03 or above)

Parameters:

HLU: Pointer to a buffer to copy the string to (at least 32 bytes)

Returns:

A: Length of time string

mos_setrtc

Set the RTC (Requires MOS 1.03 or above)

HLU: Pointer to a 6-byte buffer with the time data in

+0: Year (offset from 1980, so 1989 is 9)
+1: Month (1 to 12)
+2: Day of Month (1 to 31)
+3: Hour (0 to 23)
+4: Minute (0 to 59)
+5: Second (0 to 59)

Returns: None

mos_setintvector

Set an interrupt vector (Requires MOS 1.03 or above)

E: Interrupt vector number to set
HL(U): Address of new interrupt vector

Returns:

HLU: Address of the previous interrupt vector