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 eZ80RST 08h
: Execute a MOS commandRST 10h
: Output a single character to the VDPRST 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