SCM, v1.3, Manager.asm

The source code file “Manager.asm”, together with any included files it references, is responsible for defining a few key constants and providing a set of BIOS functions.

These constants should be defined in “Manager.asm”:

  • BNAME
  • kBiosID
  • kBiosMajor
  • kBiosMinor
  • kBiosRevis

The BIOS name (BNAME) can be anything you like as long as it is no more than 15 characters long. The name appears in the SCM help text.

It would be best to ask me for a BIOS ID, but failing that, select a value over 100 to avoid conflicts with official SCM releases.

The BIOS version consists of three numbers, each between 0 and 9.

The following functions must be provided:

FunctionDescriptions
H_TestSelf-test
H_InitInitialise
H_GetNameGet hardware name message
H_GetVersGet version details
H_SetBaudSet baud rate
H_IdleSetIdle event set up
H_MsgDevsOutput device list message
H_RdRAMRead from banked RAM
H_WrRAMWrite to banked RAM
H_CopyROMCopy from banked ROM to RAM
H_ExecROMExecute code in banked ROM
H_DelayDelay by DE milliseconds

Some of the functions are usually identical for all configurations of SCM and are provided in the file “Common.asm” in the “BIOS” folder tree.

Each function is specified below.

H_Test (Self-test)

Immediately the processor exits reset, execution jumps to the self-test function (H_Test). No other instructions are executed before the jump here. If the test passes, program execution should jump to “CStrt” (address 0x000C).

On entry: No parameters required

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' not specified

The self-test should do as much as possible, including a RAM test, before needing working RAM or using anything other than the absolute minimum of working hardware.

If the hardware supports some form of status indication it should be used to show the self-test code is running, and where possible to report any errors.

Typically, the test will show a light sequence on the digital status port to indicate code is running correctly. It should then do a very brief RAM test with failure indicated. Additional tests, such as checking there is a console device available, should be performed and failure again shown where possible. No attempt should be made to start the monitor if a fatal error occurs, such as faulty RAM.

H_Init (Initialise)

This function is called shortly after reset to initialise the BIOS and the hardware it supports.

On entry: No parameters required

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

The hardware flags (see H_GetVers) are usually set up by this functions.

H_GetName (Get hardware name message)

This function is included in “Common.asm” and returns a pointer to the BIOS name string.

On entry: No parameters required

On exit:  DE = Pointer to BIOS name string
          AF BC HL not specified
          IX IY I AF' BC' DE' HL' preserved

H_GetVers (Get Version Details)

This function is included in “Common.asm” and returns version details.

On entry: No parameters required

On exit:  D, E and A = BIOS code version
             D = kBiosMajor
             E = kBiosMinor
             A = kBiosRivis(ion)
          H, L = Target hardware ID and flags
             H = kBiosID
             L = Hardware option flags
          F BC not specified
          IX IY I AF' BC' DE' HL' preserved

Hardware flags are hardware specific but for most Z80/Z180 systems they are:

BitMeaning
0ACIA #1 detected
1SIO #1 detected
2ACIA #2 detected
3Bit-bang serial available
4CTC #1 detected
5SIO #2 detected
6CTC #2 detected
7Z180’s integrated peripherals available

H_SetBaud (Set baud rate)

If supported by the target hardware, serial port baud rate is set up for the specified console device.

On entry: A = Baud rate code (see table below)
          C = Console device number (1 to 6)

On exit:  If successful:
             A != 0 and NZ flagged
          If unsuccessful:
             A = 0 and Z flagged
          BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

Not all hardware supports baud rate setting and the hardware that does, may not support all the rates shown below.

If the specified console device and baud rate are not a valid combination or a hardware issue is detected, the function leaves the current settings unchanged and returns “unsuccessful” status.

Serial Baud RateRate CodeAlt Rate Code
23040010x23
1152002 0x11
5760030x57
3840040x38
192005 0x19
1440060x14
960070x96
480080x48
240090x24
1200100x12
600110x60
300120x30
150130x15

H_IdleSet (Idle event set up)

When the system is not busy it polls the idle events. Idle events allow simple background activity, such as flashing LEDs. This function sets up the idle event handler.

On entry: A = Idle event configuration:
             0 = Off (no events supported)
             1 = Software generated timers
             2 = Hardware generated timers

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

This function normally sets up the system jump table idle handler (table entry 0x0C). The BIOS need not distinguish between requests for software or hardware generated timers. If the hardware or BIOS does not support hardware timers, then software timers should be set up instead. If hardware timers are always available the BIOS may use these instead of software generated timers.

The idle handler is called to poll for a 1 millisecond event .

On entry: No parameters required

On exit:  If 1ms event to be processed:
             NZ flagged and A != 0
          Otherwise:
             Z flagged and A = 0
          BC DE HL preserved
          IX IY I AF' BC' DE' HL' preserved

H_MsgDevs (Output devices message)

The monitor’s DEVICES command lists hardware devices which have been detected or is assumed to be present. This function outputs the list to the current console device.

On entry: No parameters required

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

H_RdRAM (Read from banked RAM)

Systems that support a simple two RAM bank memory map, such as SC108 and SC114, can read a byte from the secondary bank with this function.

On entry: DE = Address in secondary bank 

On exit:  A = Byte read from RAM
          F BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

Only the RAM that can be mapped into memory at the same time as the SCM ROM can be read with this function. Typically this means only address from 0x8000 to 0xFFFF.

Systems that do not have a suitable memory map should implement a dummy function that just returns without doing anything.

H_WrRAM (Write to banked RAM)

Systems that support a simple two RAM bank memory map, such as SC108 and SC114, can write a byte to the secondary bank with this function.

On entry: A = Byte to be written to RAM
          DE = Address in secondary bank 

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

Only the RAM that can be mapped into memory at the same time as the SCM ROM can be written with this function. Typically this means only address from 0x8000 to 0xFFFF.

Systems that do not have a suitable memory map should implement a dummy function that just returns without doing anything.

H_CopyROM (Copy from banked ROM to RAM)

Systems that support banked ROM, such as LiNC80 SBC1, can copy a block of memory from any ROM bank to RAM.

On entry: A = ROM bank number (0 to n)
          HL = Source start address (in ROM)
          DE = Destination start address (in RAM)
          BC = Number of bytes to copy

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

H_ExecROM (Execute code in banked ROM)

Systems that support banked ROM, such as LiNC80 SBC1, can select the specified bank and execute code the in that bank.

On entry: A = ROM bank number (0 to n)
          DE = Absolute address to execute

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

The address executed is the absolute address in the 64k memory map when the specified ROM bank is mapped into memory. It is not the address from the start of the ROM chip.

The code is executed by calling it, so it should end with a RET instruction.

H_Delay (Delay by DE milliseconds)

This function is included in “Common.asm” and is a software delay of the specified number of milliseconds.

On entry: DE = Delay time in milliseconds

On exit:  AF BC DE HL not specified
          IX IY I AF' BC' DE' HL' preserved

Homebrew 8-bit retro computing