ZXVGS functions

All ZXVGS functions are called by RST #08 with number of function placed in following byte (hook code) and the program is continued from address next to hook code.

        RST  #08
        DEFB funcion

On the next tables, in the columns titled input are registers that contain arguments of the function. In the columns titled output are registers in which the function returns its values - other ones are not changed. AF is ignored on input and returned F is not defined. In some situations a function can set bit 7 in R register what means one or more frame INT is missed.

Notes:

• Interface 1 hook codes are driven by MDR.RZX and BI1.RZX.
• DISCiPLE command codes are driven by MGT.RZX and BD1.RZX

Internal ROM call

Code #7F is reserved for internal system code. It is used to call the ZXROM from inside of the system.

Joysticks

Note. Calls of #80..#83 functions can be interrupted by user. To prevent from quiting program without saving user work, use function #A3 (will be available in next releases).

It is possible to use 4 independent joysticks. Usually first two are used. The meaning of bits 0..4 is compatibile with value readed from Kempston port (#1F, b0=right, b1=left, b2=down, b3=up, b4=fire). Bit 5 is second fire (usually not used). Bits 6 and 7 are common to all joysticks means two more buttons. Bit 6 (HALT) should cause pause in game (when set) or activate options. Bit 7 (EXIT) should stop the game or go to main menu.

Using the mouse

You can use external mouse (serviced outside main program), also one that generates interrups. Calculating absolute coordinates, painting of pointer and events detection belong to your program duties. To use mouse in any program follow these points.

1. Disable interrupts! Select IM 2.
2. Set value of I register (best are #80..#FE). It can't point to ROM!
3. Fill interrupt page (257 bytes started from I*256) with the same byte value. Caution! Some types of mice (AMX) will generate IM 2 vectors!
4. At address pointed by I register page place:

           NOP
           NOP
           NOP
           JP   ownint

   The "ownint" is address of standard frame interrupt service. If you don't need own frame interrupt service, you can place EI: RETI instead of this jump.
5. Reserve 128B buffer for mouse service code. Place its address in HL (#5B00..#FF80). You can't write to this area after installing mouse.
6. Reserve byte for horizontal change. Place its address in BC.
7. Reserve byte for vertical change. Place its address in DE.
8. Call function #84. It will fill the buffer and change the NOPs. Also will change interrupt table if neccesary.
9. Enable interrupts!

For old programs it is adviced to place XOR A:RET at the beginning of the buffer to avoid program crash while call before mouse initialization.

The coordinates will be changed at given addresses. They are 8 bit values, you can only read them and compare to former value to determine changes. To check buttons just call the beginning of the buffer. It will return button status in A, preserving other registers (b0=LMB, b7=RMB; set means pressed).

Please note that some kinds of mouse (RS232, AMX) can generate own interrupts that aren't useful for the program. All the non-frame interrupts are "eaten" (return address is POPed). And if return address points to byte after HALT opcode, it will be decremented to continue HALT til frame interrupt.

Mouse can be deactivated by giving 0 as buffer address (in HL). Values returned in this case are useful for RSXes - they can uninstall driver used by main program, install own driver to operate an requester, then uninstall own driver and install back the driver of main program.

Speed

Function #87 switches the CPU into high speed mode. The extra speed isn't defined - just the program works faster.

Function #88 switches the CPU back to 3.5MHz.

Keyboard

Extended keyboard should be used to enter text in some programs. Allows use of some additional keys (emulators, SAM Coupé, ZX128 keypad).

Will be used in BASIC if patches or INT traps are available.

Call of function #8F??? should be placed in IM 2 service, at least after pushing AF. Or with disabled interrupts should be called about 50 times per second.

Do not use!!! This isn't finished!!!

Screen support

Functions #90..#9F are designed to generate menu, move mouse pointer and display texts in 42, 51 or 64 colums. Also on additional screen modes.

Function #9F prints character on standard screeen using 64 columns mode. Put row in D, column in E, and the character in C. B should be 0 for future compatibility (will select character set for characters 128..255).

They are not available in present ZXVGS release!

Config and system info

Config of functions

Functions #A2 and #A3 are to control hardware dependent functions. They should not be used in applications (including reading the release number), except config dedicated ones. In D is number of function being configured or #A2 for release number reading. Function #A2 returns current setting in E while the release number in AE. Function #A3 changes setting and returns effective setting (old one when no change were made, new one when change is accepted). Both function return A=0 when getting or setting configuration passed correctly (except for release number reading).

Config of sound

Function #A4 provides information about available sound interfaces. Bit 0 coresponds with beeper in port #FE, bit 1 - BEEPER procedure in ZXROM. Reseted bit means don't generate sound this way (the user don't want to hear such effect). Set bit 2 means the AY-3-8910/2 in ports #BFFD i #FFFD (also #BEFD and #FEFD for some wrong written players) is opened, set bit 3 - the SAA 1099 (SAM Coupé) in ports #00FF i #01FF is opened. When bit of these two isn't set, you mustn't use these ports! It can crash the computer!

When this function is called without prior call of #A5 function (after #AF), it allocates all possible sound devices (near back compatibility, will be removed).

Function #A5 can be used to allocate and deallocate sound device. The device number is provided in D and some parameters in E. (Asterisk "*" means the device has fixed port addresses.) They are:

Config of screen

Function #A6 retuns ULA type in D, current screen mode in E and current frame length in BC.

Function #A7 opens video mode. When the frame length is not important, set BC=#0000 and D=#FF. When BC>#0000 or D is different from #FF, ZXVGS will try to change ULA properties (what is possible on emulators and dedicated hardware). Value in D has higher priority than BC (however this is another way to swith the ZS Scorpion into fast mode).

Functions #E8, #E9, #F3 use the screenmode value to load, save or print the screen.

BC - frame length between interrupts in Z80 tacts, measured in IM2, both code and IM 2 table are in fast RAM (not slowed by ULA). To get number of tacts per frame, multiply the BC value by 18 and add 66 (ZX48) or 60 (ZX128) tacts. (However for the Sam Coupé BC must be multiplied by 20, not 18.) Please note that while both ZX48 and TC2048 have the same frame length, the starts of screen drawig are in different tacts.

LINT: +#80

LINT interface generates interrupt before line set in port #F9 is displayed. Interrupts can be recognized by reading port #F9. Presence should be checked with function #A???. (At this moment only SAM Coupé contains this feature.)

For HL>#4000 at HL is placed relocateable code to select one of base screen mode. In this case L contains length of the code and H - number of tacts it needs. For calls with H=0 the mode is selected directly.

Management of Resident System Extensions (RSX)

Function #AC is used to load RSX into system memory without activation. In case of no error (A=0), the handle for selected RSX is returned in D.

Function #AD? calls internal functions of present RSX.

Function #AE is dedicated to control all loaded RSXes. For E=0 places at HL name of file that cause to load the program or error when the program was run directly, not by its file. BC should contain buffer size, at least #0080.

Function #AF loads RSX specified by extension of file name and then this RSX loads required file. E.g. for file "GAME.Z80" the RSX is loaded from file "ZX:Z80.RZX". This doesn't happen for extensions "V00" (ZXVGS native program) and "RZX" (loads RSX directly, not "RZX.RZX").

Function #AF loads:

• for "*.V00" names - required program (then "*.SV@" file, if exists),
• for "*.RZX" names - required RSX,
• for other names - "ZX:ext.RZX" (if found; the "ext" is extension of filename) and the file name is available via #AE function for E=0;

Memory banks

With these functions you can manage up to 4MB RAM. (What gives totally 4128kB in 16kB mode or 8208kB in 32kB mode.)

Introduction

There is 16kB of RAM switched in section D (#C000..#FFFF). It is possible to use virtual banks, which contents will be software moved. Banks #00..#07 are privileged and can be switched faster, with separate functions #B0..#B7 without arguments.

The bank must be opened before any operation on it. If while opening there's no enough memory (RAM for non-virtual bank or external one for virtual) fatal error is generated. Check free space before! Opened bank is filled with zeros. None of functions check PC, SP nor I contents, so using them in wrong context will cause system crash.

If because of hardware reasons it isn't possible to switch section D, only virtual banks are allowed (long time switching). If because of hardware reasons only both C and D sections can be switched together at a time (32kB, #8000..#FFFF) then switching of section D can be simulated with or without rewriting section C. In this case it isn't possible to open bank that is switched fast and don't modifies C section. Section C is copied while opening.

There are three types of banks:

1. Individual - numbers 0..15 - each can be opened in different mode.
2. Parametrical - numbers from 16 to the value returned in A by function #BF. This group exists only if function #BF returns in A value greater than 15. Mode of opening is determined for the first opened bank from this group and is the same for all other banks.
3. Virtual - over value given by #BF function. This group exists only if function #BF returns in A value lower than 255. Mode of opening is determined for the first opened bank from this group and is the same for all other banks. These banks can be opened only as virtual. To open first virtual bank at least one of real banks must be opened as not fast (bit 0 in D reset) - the recent one will change its state to virtual and is used as hardware bank for data of virtual banks (opened formely will keep being real ones).

Functions

Functions #B0..#B7 select one of ptivileged bank. Function #B8 selects any bank - its number is provided in E register.

Function #B9 provides informations about banks. Do not use. To get current bank number and its mode, use #BF function.

Function #BA is used to get code that switches bank. See next section for details.

Function #BB copies present section C contents to all other opened 32kB banks or is ignored in case of 16kB chunk switching.

Function #BC tries to opens bank E in mode D, returns effective mode in D. See paramers table.

Function #BD closes bank E. If E means bank actually selected, contents of D section becomes undefined (e.g. can contain ROM contents or values #FF) till selection of another bank.

Function #BE closes all banks. Contents of D section becomes undefined.

Function #BF returns in register E the number of currently selected bank, in register D its mode. In B is returned the amount of opened banks. Register A contains amount of additional banks (not including virtual):

• 0 - 48 kB (standard ZX48)
• 1 - 64 kB (usually one 32kB bank; so called ZX80kB)
• 2 - 80 kB (two additional banks - usually 16kB each)
• 5 - 128 kB (five additional banks - ZX128)
• 6 - 144 kB (kind of TC2048 extension)
• 27 - 480 kB (Pentagon 512kB with two pages reserved)

Function #BA - Fast bank switching

This feature allows much faster switching of banks. Follow these points.

1. Determine whether your program will work with 32kB switching. If no, use mode %XXXXXX11 (will not work on some hardware). Otherwise there will be 32kB or 16kB switched at a time. Pay attention to stack and interrupts.
2. Open bank with function #BC.
3. Reserve 32B for switching code. The code is always relocateable. To use the code without moving it, you can fill the buffer with "NOP" (#00) and follow with your code. Or fill 33B with "RET" (#C9) or "JP (HL)" (#E9), depending on your program structure.
4. Reserve two bytes in #5B00..#7FFE, place address of first in BC for first call of #BA functions (for next #BC call is ignored until called with BC=0).
5. Call function #BA to place switching code for bank E into the buffer adressed with HL. This function will return the real length of code in BC and number of Z80 tacts in A. DE will point to the byte just after code, so you can add (with LDIR) own code here.
6. To select bank, execute the code.

Remember!

• Each bank has its own switchng code.
• (!!!) The code can be moved to any other place at any time.
• The code MUSTN'T be used after closing bank!
• Code given by #BA function isn't longer than 32B.
• Switching code always modifies AF, usually BC and use the stack.
• To call any ZXVGS function you MUST call switching code for bank used before first call of switching code (this means last bank selected by #B0..#B8 functions must be selected).
• The code MUST be also in the bank that it selects. There's no problem when it is placed in #4000..#7FFF. After pleacing it in #8000..#BFFF you can call #BB function to copy it to other banks. But when you want to use this code in #C000..#FFFF you must copy it yourself to the destination bank.
• In some cases (e.g. in emulators) function #BA returns #FF in A, what means that the code contain call of #B8 function. Think about stack!!!

Current path

Reading directory contents

Function #C2 gets entry from directory selected by function #C3. HL points to format string (defined by function #C3 is used when either H=0 or HL points to 0 byte; internal system structure is returned when H=1), DE points to a buffer. The entry as plain ASCII (ready to display) is placed at DE. (Use HL=0 to fill the fileselector, then HL=^'%f%n' to get filename selected by user in requester.)

Function #C3 selects directory, counts entries, copies entries to the internal buffer. (The buffer must be released (DE=0) after reading directory is finished.) HL points to format string (system default one is used when either H=0 or HL points to 0 byte; internal system structure is returned when H=1). Following formatters can be used:

• %a attributes
• %b number of allocation units taken by file or "Dir" string
• %c comment to file
• %d date of last modification
• %e extension of file
• %f path to file (real)
• %g name of file group (GID)
• %k first allocation unit number
• %l length in bytes or "Dir" string
• %m filename without extension
• %n filename with extension
• %p path to file (the pointed by DE)
• %s filename with extension(?)
• %t time of last modification
• %u name of file user (UID)
• %x U*IX attributes

Other characters are copied without change. A decimal number between the "%" and letter means the fixed field size. Positive values result right justification, negative - left. Value after dot means number of characters in string to cut. Examples:

"%-16.16m %-3.3e %l" - NeOS 1.0 style (DEC)

"%-8.8m<%1.1e>%3b%13l" - TR-DOS style (start values unavailable)

"%x %-9g%-9u%8l %6d %5t %n" - U*IX style (ls -l)

"%-9.8m%-4.3e%13l%9.8d%9t" - MS-DOS 6.20 style (default)

Internal system structure consists of following fields (not fully defined):

• +#00 - - 4B;
• +#04 - - 4B;
• +#08 - - 4B;
• +#0C - - 4B;
• +#10 - - 4B;
• +#14 - - 4B;
• +#18 - - 4B;
• +#20 - ASCIZ file name without path - up to 32B;

Free disk space can be get with #C4 or #C5 functions.

Note: some disks (mostly the network disks like "TCP:", "HTTP:" or "FTP:") will not show all possible subdirectories, only those that were used recently (or present in bookmarks).

Disk informations

Functions #C4 and #C6 returns informaton of given disk/path or file. Functions #C5 and #C7 change the informaton of given disk/path or file, but only if it is possible.

Managing of files

Function #CB removes files or directory (directory must be empty).

Function #CC checks whether given file exists (error if not).

Others are still not defined.

Primitive file functions

These functions are for file handling. If you want to load whole file into memory or save memory part as file check #E0..#ED functions first.

Function #D0 always closes file of given handle. If 0 is given as handle, all opened files will be closed. Function #D1 opens file for input (returns error if file not exists). Function #D2 opens file for output - will delete existing file and make new with null length. Function #D3 opens file both for input and output. If file not exists, will be created with first writing.

Functions #D4..#D7 are for read and write file. Functions #D4 and #D5 send given amount of bytes (returns amount of bytes actually sent - lower value than required generates error). Function #D6 reads bytes from file to the limit or to recognize #00 or #0D values (including them). Function #D7 writes bytes till #00 value, which isn't written. Byte #00 will be written only if is first pointed byte.

Function #D8 returns present file position. Function #D9 allows move present file position of any file and returns position before operation. Shift is counted dependly on B regiser: #FF means from beginning, #00 actual position and #01 from end of file. Error value is returned when end or beginning of file are crossed. It is possible to address file of 8MB length (23 bits of address). Function #DA informs whether file is in end position. Function #DB truncates file at actual position.

Following functions are nearly direct calls of FILEDISK system structure. Its definitions can still change in future.

Files with header

Functions #E0..#E7 are designed to handle files with headers (similar to tape files).

Before calling functions #E4..#E6 the header type must be set by one of #E0..#E3 function. This setting is valid until next call of any #E0..#E3 function. If the file exists then in specified registers will be returned values taken from header of this file. If the file not exists or required header type is collision with readed, error code is returned. This error may be ignored if write to file will be performed, but reads of that file will always resulult error.

On entry to #E3 function the buffer size can be provided in BC. Length returned in BC is limited by this size, while DE contains real size. This is to avoid the tape limitation - you cannot load from real tape some first bytes of longer file as the checksum cannot be checked. Also, BC=#1B00 and HL=#4000 will be recognized as you want to load or save the screen (however you can still load it to or save from other address).

Loading and saving give error when less bytes than reqired were readed or written. Check BC in that case. Verification is equivalent to reading and acts similar to tape one - error is submitted if data varies or file is too short.

Function #E7 called before one of #E4..#E6 function alows set the shift, what gives the possibility of seqential processing of the file. It means e.g. reading succeeding parts of file to different memory banks. Error is retuned when position exceeds file length. Functions #E0..#E3 always set the shift to zero (just after header).

Calling any function of #E4..#E7 without prior call of any of #E0..#E3 causes fatal error.

The file with header can be 65535 bytes long (not including header). The rest will be truncated. The header format may vary in different filesystems. So it is not adviced to process files with header using other functions, unless they are e.g. screens or savegames.

For files with filename extension different from ".CZX", ".DZX", ".DAT", ".ROM", ".SCR" proper RSX is called. So you can e.g. load data or BASIC program from "*.Z80" file! See RSXes description for details.

Screenimage files

To save or load ZX screen, functions #E8 and #E9 should be used. Operation always means 6912 bytes of memory. Separation of these functions allows graphics conversion from/to popular graphics formats. Saved screen has 256x192 pixels and 16 colours, but exceptions are possible. If contents of loaded file isn't compatibile with Spectrum limitations, the result is not defined. Error is returned if file wasn't saved or not exists or the format wasn't recognized.

In future ZXVGS releases RSX will be used to load and save images of file exentions different from ".SCR" and ".CZX". These functions can also display requester with list of available formats when no file extension is given or file not exists (loading) or the filename is empty.

Other screen modes will be also supported.

Savegame files

Functions #EA and #EB are designed to store and recall the state of game or configuration of utility program. Calling these funtions allows the user to select one of 10 such files. While saving user can comment the file. Files are saved with name of current program and one of "SV0".."SV9" extension (this is selected by user).

For D=0 the requester will not appear and the file with extension ".SV?" as default will be loaded or saved. In this case E contains code of character placed as 3rd one in file suffix (invalid characters are changed to "!"). This feature is to load default configuration at start of program or save configuration on exit. The comment string while saving is set to "Autosaved" (date and time can be included). This can be used together with standard calls (when the user selects an entry).

For function #EA, when HL=0, the address from header is used.

The extension "SV@" (E=#40) is reserved to store high scores file of a game. If the file exists, ZXVGS loads "*.SV@" it just after the "*.V00" file. Then, the file is saved when the user calls ZXVGS menu. In new programs it should be saved with function #EB at every highs scores table modification.

The "*.SV?" files are saved to and loaded from the "SV:" disk.

Files without header

Function #EC should be used to load whole or initial part of any file to memory. Error code is returned if there were loaded less bytes than required.

Function #ED should be used to save continous area of memory to file. Error code is returned if there are saved less bytes than required (no disk space).

Always check BC in case of error.

File seclectors

Functions #EE and #EF are designed to allow user select or enter file or directory name in easy way. It is possible to give default name and limit choice by mask. Mask can be edited by user, except "*/" what means directory selection. There is also title of operation. For result path 128 bytes of buffer must be reserved. Functions return error when fileselector was exited by <EDIT> or name is empty.

Function #EE always leaves screen (memory area #4000..#5AFF) unchanged, what in some situations manifests in limited form of selector. Function #EF always uses full-screen interface, but leaves screen in random state. Screen refresh is needed.

It is adviced to use file selectors for every file with name defined by user.

When "*.SZX" or "*.SCR" is as the mask, the requester can also allow to select other graphics file format and change file extension respectively.

Printer

Function #F0 returns printer control code. In E is code number, in HL addres of buffer for it. In BC is the maximal length (B is ignored - should be 0). When control codes fitted in buffer, BC (B=0) contains number of control characters and A is 0. If the buffer was too small, BC returns required space and A>0. If control code is not available, BC=0 and A>0.

Function #F1 sends required control code directly to printer. See also function #F0.

Function #F2 is equivalent to BASIC COPY.

Function #F3 prints screen (256?192) taken from given address.

Function #F4 simulates ZX Printer on normal character printer.

Function #F5 simulates ZX Printer on matrix printer, but for character printer acts like function #F4.

Function #F6 is dedicated to print texts with national characters. If there's no recoding in system is equivalent to function #F7. Values 1..5 in register D mean ISO-8859-D character set.

Function #F7 sends byte directly to printer (control sequences can be taken with #F0 function).

Functions #F0..#F6 are driven by PRINTER.RZX.

Overlays

Functions #F8..#FB are for overlays management. Usually overlays are next levels of game. Overlay can be loaded by calling #F8 function with number of overlay. Preparation (function #F9) has only sense in server systems and allow speed up loading (e.g. with Timex FDD 3000) - isn't necessary. Loading overlays into buffer (function #FA) causes faster loading. This is ignored when there's not enough RAM for store. It should be used instead of loading overlays directly into memory banks (like games for both ZX48 and ZX128), because in the buffer overlays are in compressed form and can be also stored in RAM available under ZXROM (MB-02). Function #FB removes overlay from buffer. All functions return amount of free buffer storage in kilobytes. If there's more free space than 254kB, value 255 is returned.

System calls

Functions #FC..#FF are for exiting from program to the system menu and quiting program.

Function #FC only calls system menu. The program is continuable. Function #FD ends the program after its finish (closes all opened files, banks, clears overlay buffer, etc.). Function #FE is similar to #FD, but displays given message before menu.

Function #FF is reserved for BASIC interpreter that executes it after last instruction. It is useless for ZXVGS programs. Usually (without RSX) word from XPTR #5C5F will be copied to CHADD #5C5D, #FF will be placed in ERRNR #5C3A and program will be continued from #0058 (error service).