4,319 bytes added,
21:52, 24 January 2010 == Installing All Expansion ROMs ==
BCCB KL_ROM_WALK ;io: DE=LORAM, HL=HIRAM (INIT_BACK with C=7..1)
KL_ROM_WALK is usually called immediately after starting the BASIC ROM, it does search/install expansions ROMs by calling INIT_BACK with C=07h..01h (on 664 and up: C=0Fh..00h).
== Installing a Single Expansion ROM ==
BCCE KL_INIT_BACK ;io: DE=LORAM, HL=HIRAM, C=bank, out: B
KL_INIT_BACK installs a single expansion ROM, it rejects "C>07h" (664 and up: C>0Fh), and rejects ROM banks with "([C000h] AND 03h)<>01h". If it accepts the ROM, then it calls its intialization function at C006h (which may allocate RAM; typically by decreasing the HIRAM value in HL, initialize that RAM and/or expansion I/O ports), thereafter, KL_INIT_BACK allocates 4 bytes (by decreasing HIRAM), and passes the allocated 4 bytes to KL_LOG_EXT.
== Installing RSX Functions (defined in Expansion ROM or in RAM) ==
BCD1 KL_LOG_EXT ;in: HL=4-bytes, BC=rombank (<=FFh) or BC=addr
Adds a set of RSX Function(s) to the extension chain. The incoming bytes at [HL+0..3] are don't care. HL becomes the newest chain entry, the pointer to the previous entry (or 0000h if none) is stored at [HL+0], BC is stored at [HL+2]. Where BC points to the new RSX commands, in one way or another:
If BC<0100h, then the commands are in ROM bank BC at address C004h, otherwise they are in RAM at address BC. The commands are defined in form of a 16bit pointer to the command names, followed by one or more 3-byte JP opcodes that jump to the corresponding functions. Each name can be max 16 bytes long, the last byte is indicated by bit7=1, the last name is followed by a 00h byte. The names are usually upper-case ASCII (so they can be entered as |NAME under BASIC), non-uppercase or non-ASCII names would define hidden commands (eg. the AMSDOS read/write sector functions, which can be used with KL_FIND_COMMAND, but not with "|" in BASIC).
== Using RSX Functions ==
BCD4 KL_FIND_COMMAND ;in: HL=name, out: HL=proc, C=ROMcfg, CY=1=okay
Searches for a RSX command. HL must point to the name (with bit7=1 in last byte). It does first search for extensions that were registered with KL_ROM_WALK, KL_INIT_BACK, or KL_LOG_EXT. If it is found, then it returns the function address in HL (eg. C0xxh for AMSDOS), and the ROM bank in C (eg. 07h for AMSDOS, or FFh for RAM), and CY=1.
If it is NOT found in the registered extensions, then it goes on searching unregistered foreground ROMs - if the command is found here (eg. the |BASIC command in BASIC ROM), then that ROM is started directly via MC_START_PROGRAM (ie. in that case KL_FIND_COMMAND does NOT return). Otherwise if the name isn't found at all, then it returns CY=0.
== Executing RSX Functions in Machine Code ==
Search the function address via KL_FIND_COMMAND, then pass the returned HL/C values to one of the three KL_FAR_CALL_xx functions. Normal RSX functions have incoming parameters in A and IX (A=number of parameters, IX=ptr to the parameter list, 16bit per parameter) (for string parameters, the 16bit value points to the string length byte, followed by the string). Hidden RSX functions (like AMSDOS read sector) may expect incoming parameters in other registers.
== Executing RSX Functions in BASIC ==
In BASIC, type "|NAME,parameter1,parameter2,...". Each parameter is a 16bit value, which may be a numeric value, or a pointer to a string. The 664 and up do automatically convert strings to address-of-strings, ie. one can type |ERA,"filename" - however, the 464 doesn't do that automatically, so one must type A$="filename":|ERA,@A$.
== LORAM/HIRAM ==
LORAM is the first free byte (usually/always 0040h; above RST vectors)
HIRAM is the last free byte (initially ABFFh; below BASIC region)
After installing AMSDOS, HIRAM is usually A6FBh. Some machine code programs do reinstall AMSDOS with incoming HIRAM=B0FFh (deallocating the BASIC region), the resulting HIRAM is then ABFBh.
Concerning the BIOS, LORAM/HIRAM "exist" only while installing expansion ROMs via KL_ROM_WALK and KL_INIT_BACK, as well as after starting something with MC_BOOT_PROGRAM or MC_START_PROGRAM. Thereafter, the BIOS forgets these values (the BASIC does store hi/lo somewhere in the BASIC area, the BIOS does store hi, too, but there's no BIOS function to retrieve them).