SCM, v1.1, Porting Guide

The Small Computer Monitor (SCM) is available in a number of different configurations. The configuration determines:

  • Compile time options, such as default baud rate
  • Build name and date
  • Hardware support
  • Additional ROM contents, such as extra programs

SCM is divided into four parts:

  • The Operating System Layer
  • The Monitor Program
  • The Basic Input/Output System (BIOS)
  • Additional ROM contents (optional)

The BIOS is the part that handles hardware support and is customised for the target hardware.

Source code structure

The SCM source distribution includes the folder: Source. The significant contents are:

  • Folder: BIOS
  • Folder: Config
  • Folder: Monitor
  • Folder: System
  • File: !Main.asm

Folders “Monitor” and “System” should not normally be changed when creating a new configuration or porting SCM to a new hardware target.

Adding a new configuration to file !Main.asm

A new configuration could just be a ROM with different additional ROM contents, such as a BASIC interpreter, or it could be a build of SCM for a new hardware target.

To add a new configuration you should first edit !Main.asm. This file has two sections:

  • A list of #DEFINE statements, one for each configuration. These are all commented out except for the configuration to be built.
  • A set of #IF … #ENDIF statements to include the required build files.

Each configuration has a two character identifier, such as “S4”. The first character is the major identifier and the second is the minor identifier. The convention is the first character indicates the product family and the second is the variant within that family. For example, R1 indicates the family is “RC2014” and the variant “1”. In this case, “1” indicates a system with 8k bytes of ROM and 32k bytes of RAM.

It would be best to ask me for a configuration identifier, but failing that, use a numeric character (“0” to “9”) as the major identifier. This will avoid conflicts with official releases that use letters (“A” to “Z”).

To add the configuration “Q9”, edit the file to include the line:

#DEFINE  BUILD  Q9       ;Example configuration

It is recommended this line be added such that the configuration codes are listed in alphabetical order.

In the lower section of the file, add the statements:

#IF        BUILD = "Q9"
#INCLUDE   Config\MyQ9\Build.asm

Substitute a suitable name in place of “MyQ9”.

If the build folder supports a number of configurations, the #IF statement can include the “*” wildcard, such as “Q*”. This gets more complicated, so avoid use of the wildcard for now.

Adding a new configuration to folder Config

First make a copy of one of the existing folders in “Config” and give it the name chosen above. For example, “MyQ9”.

Within the newly created folder there should be the following files:

  • Build.asm
  • ROM_Info.asm
  • ROM_Info_xxxxx (optional)

The ROM_Info file(s) determine the additional contents of the SCM ROM. More on that later.

The file “Build.asm” will contain something like this:

Further explanation of this file can be found here.

Adding a new configuration to folder BIOS

First make a copy of one of the existing folders “BIOS” and give it a suitable name. For example, “MyQ9”.

Within the newly created folder there should be a file called “Manager.asm” and possibly others.

The source file “Manager.asm” is responsible for defining the following constants:

  • kBiosID
  • kBiosMajor
  • kBiosMinor
  • kBiosRevis

The BIOS name can be anything you like. It 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 source file “Manager.asm”, plus any additional files included with #INCLUDE statements, is responsible for providing the following functions:

  • H_Test
  • H_Init
  • H_GetName
  • H_GetVers
  • H_SetBaud
  • H_IdleSet
  • H_MsgDevs
  • H_RdRAM
  • H_WrRAM
  • H_CopyROM
  • H_ExecROM
  • H_Delay

These functions are described in detail here.

Homebrew 8-bit retro computing