You are here:

QuickOS Kernel

This is the primary portion of QuickOS that everything else relies on. It is always included, and its configuration determines which other components are installed.

NOTE: If using a custom VBI handler, have it just RTS since the system tracks while it is in use and handles preserving registers itself. There is also no direct way to access the VBI handler address. Use QuickOS::SetHandler to change it.

Functions

QuickOS::CopyMemory

Copies memory from one place to another, supporting overlapping memory as necessary.

QuickOS::ClearMemory

Clears a region of memory.

QuickOS::SetHandler

Sets an interrupt handler safely.

QuickOS::ClearHandler

Clears an interrupt handler.

QuickOS::WaitForVBlank

Waits for a vertical blank.

QuickOS::WaitForHBlank

Waits for a horizontal blank.

QuickOS::SetBlankScreen

Sets a blank screen using a very minimal display list.

QuickOS::ToggleAutoBlink

Toggles auto blink mode.

QuickOS::SwapSourceDest

Swaps QuickOS::ZP_Source and QuickOS::ZP_Dest.

QuickOS::FullRTI

Pulls Y then X then A then RTIs. This doesn't do an extra JMP, so it's as fast as jumping to a custom one.

Zero Page Values

QuickOS::ZP_Source

Address, A source buffer address.

QuickOS::ZP_Dest

Address, A destination buffer address.

QuickOS::ZP_VSync

1 - 5 bytes, Incremented every VBI. See QuickOS_Config::VSYNCSIZE below for details on settings its size.

QuickOS::ZP_Scratch

8 bytes, A scratch area as needed. Used by various routines such as string operations.

Values

System Data Values

Don't modify these values directly.

QuickOS::Version

DWord, The version, in $01020304 meaning 1.2.3.4 format.

QuickOS::Memory

Word, The amount of memory detected, in KB. Requires QuickBank to be accurate.

QuickOS::CPUSpeed

Word, The approximate kHz of the system.

QuickOS::CPUSpeedMult

Byte, An approximate multiplier of the standard Atari speed that this processor is.

QuickOS::CPUType

Byte, The CPU type in the system. This will be one of:

QUICKOS_CPUTYPE::MOS6502: Standard NMOS 6502C used in Atari 8-bits.
QUICKOS_CPUTYPE::WDC65c02: WDC CMOS 65c02
QUICKOS_CPUTYPE::R65c02: Rockwell CMOS 65c02 with BBR*/BBS*/RMB*/SMB* instructions
QUICKOS_CPUTYPE::WDC65c816: WDC CMOS 65c816

QuickOS::PAL

Byte, Whether this is a PAL system or not. 0 for NTSC, $FF for PAL.

Shadow Registers

All of these should be updated when updating any of their respective hardware values, to allow reading the last value used.

QuickOS::IRQENShadow

Byte, The IRQEN shadow register. Use this whenever changing POKEY_W::IRQEN.

QuickOS::NMIENShadow

Byte, The NMIEN shadow register. Use this whenever changing POKEY_W::NMIEN.

QuickOS::DMACTLShadow

Byte, The DMACTL shadow register. Use this whenever changing ANTIC_W::DMACTL.

QuickOS::CHACTLShadow

Byte, The CHACTL shadow register. Use this whenever changing ANTIC_W::CHACTL.

QuickOS::SKCTLShadow

Byte, The SKCTL shadow register. Use this whenever changing POKEY_W::SKCTL.

QuickOS::PRIORShadow

Byte, The PRIOR shadow register. Use this whenever changing GTIA_W::PRIOR.

QuickOS::AUDCTLShadow

Byte, The AUDCTL shadow register. Use this whenever changing POKEY_W::AUDCTL.

Misc Values

QuickOS::BlinkOnFrames

Byte, Frames per blink to stay on if auto-blinking enabled. See QuickOS::ToggleAutoBlink.

Don't use 0 unless you mean for it to last for 256 frames.

QuickOS::BlinkOffFrames

Byte, Frames per blink to stay off if auto-blinking enabled. See QuickOS::ToggleAutoBlink

Don't use 0 unless you mean for it to last for 256 frames.

Internal-Use Values

These should rarely, if ever, need to be accessed directly.

Display Handlers

In general, these should be set via QuickOS::SetHandler or QuickOS::ClearHandler instead of manipulated directly. However, in some cases, setting them directly is useful, such as changing the DLI handler between DLI interrupts.

VBIHandler

The vertical blank handler. Use an RTS to end the handler, since QuickOS automatically backs up registers and restores them, but also keeps track of whether the VBI is running or not.

DLIHandler

Address, The DLI handler. If used, back up registers first, then restore registers and RTI.

DO NOT EDIT THIS DIRECTLY EXCEPT IN YOUR OWN DLI OR VBI HANDLER!

NextDLIHandler

Address, The next DLI handler to use. 0 for no change (gets cleared every VBI).

DisplayList

Address, The active display list shadow.

NextDisplayList

Address, The next display list to change. 0 for no change (gets cleared every VBI).

IRQ Handlers

All of these should do a JMP QuickOS::FullRTI or the equivalent when ending. In general, these should be set via QuickOS::SetHandler or QuickOS::ClearHandler instead of manipulated directly.

SIOCompleteHandler

Address, The SIO complete handler. 0 for disabled. This is not used internally by QuickOS.

SIOOutHandler

Address, The SIO output handler. 0 for disabled. This is not used internally by QuickOS.

SIOInHandler

Address, The SIO input handler. 0 for disabled. This is not used internally by QuickOS.

KeyboardHandler

Address, The keyboard handler. 0 for disabled. This is not used internally by QuickOS.

If using IRQs in the QuickKeyboard extension, setting this overrides it.

BreakKeyHandler

Address, The break key handler. 0 for disabled.

The break key handler. If using BRK key reading in the QuickKeyboard extension, setting this overrides it.

Misc Handlers

In general, these should be set via QuickOS::SetHandler or QuickOS::ClearHandler instead of manipulated directly.

ResetHandler

Address, The reset handler. 0 for disabled.

ErrorCodeHandler

Address, A custom error code handler. 0 for the default which only does anything if QuickOS_Config::DEBUG is non-zero.

Error Code Handler Values

These are only meaningful in the error code handler, if one is used.

ErrorCode

Byte, The error code value.

See QUICKOS_ERRORCODE::*. This may become quite a list, so it is not expanded here.

ErrorCodeA

Byte, The value of A when the error code handler was called.

ErrorCodeY

Byte, The value of Y when the error code handler was called.

ErrorCodeX

Byte, The value of X when the error code handler was called.

ErrorCodeP

Byte, The value of P when the error code handler was called.

Configuration

All of the following are defined in Config/QuickOS.inc, and are accessed under QuickOS_Config.

Boot / Start Configuration

QuickOS_Config::BOOTBYTESPERSECTOR

Default: 128 for SD disks.

Word, The number of bytes per sector on the QuickOS boot disk. 128 for SD, 256 for DD.

QuickOS_Config::BootStart

Default: $0700

Address, Where to load this sector. This generally never needs to change.

QuickOS_Config::BootCPUSpeed

Default: $F0

Word, Zero Page address to store the boot speed test. This is the approximate kHz speed of the processor. This is used while the AtariOS is still loaded, so it should be >= $82. This probably never needs to change.

QuickOS_Config::STAGE1LOADSECTOR

Default: 4

Word, The first sector the QuickOS stage 1 loader at. This should never need to change.

QuickOS_Config::STAGE1NUMSECTOR

Default: (1024 + QuickOS_Config::BOOTBYTESPERSECTOR - 1) / QuickOS_Config::BOOTBYTESPERSECTOR

Byte, The number of sectors used in the stage 1 loader. This should never need to change.

QuickOS_Config::Stage1Start

Default: $1000

Address, Where to load the stage 1 loader. This should never need to change.

QuickOS_Config::INITIALIZELOADSECTOR

Default: QuickOS_Config::STAGE1LOADSECTOR + QuickOS_Config::STAGE1NUMSECTOR

Word, The first sector the QuickOS initialization is at.

QuickOS_Config::INITIALIZESIZE

Default: $3400

Word, The size of the initialization and Quick OS.

QuickOS_Config::INITIALIZENUMSECTOR

Default: (QuickOS_Config::INITIALIZENUMSECTOR + QuickOS_Config::BOOTBYTESPERSECTOR - 1) / QuickOS_Config::BOOTBYTESPERSECTOR

Byte, The number of sectors used in the initialize code.

QuickOS_Config::Initialize

Default: $8000

Address, Where the full QuickOS initialization is loaded at. Used to initialize the OS before copying the permanent OS data to its target. It SHOULD NOT overlap where your program will load unless QuickDriveIO is included. $8000 gives us 16KB ($8000 - $BFFF)

QuickOS_Config::InitializeScreen

Default: $0800

Address, A 2KB screen area to use while initializing. It is not used after initializing. This probably never needs to be changed. The font will occupy the first 1KB region and the 40x25 screen will occupy the second 1KB region.

It *MUST*:

Be on a 1KB boundary
*NOT* be within the memory region at $0000 - $01FF (obviously)
*NOT* be within the XL memory bank region at $4000 - $7FFF
End before $C000

QuickOS_Config::InitializeDriveIOLoad

Default: $BC00

Address, A 1KB region for where to copy the loader code from Initialize to load the initial program with QuickDriveIO, if it is used. This allows the loader to load the initial program over the top of Initialize if necessary since after copying the loader, Initialize is no longer needed.

Use 0 here to not relocate the QuickDriveIO loader and just JSR to it.

QuickOS_Config::PROGRAMSECTOR

Default: 130

Word, The sector the program starts on.

QuickOS_Config::PROGRAMNUMSECTOR

Default: 8

Word, The number of sectors for the program.

QuickOS_Config::ProgramAddress

Default: $0200

Address, Where to load the program after QuickOS is done loading.

QuickOS_Config::ProgramStart

Default: QuickOS_Config::ProgramAddress

Address, Where to JMP to, to start the program, after QuickOS is done loading.

Included Features

For each of these, a 0 means to not include it, a 1 means to include it in the high OS memory area ($D800 to $FFFA, see QuickOS_Config::EndAddress) and a 2 means to include it in the lower memory area ($CFFF and down, see QuickOS_Config::EndAddress2). In general, 2 values are not necessary and should be avoided as much as possible.

QuickOS_Config::ADDDRIVEIO

Default: 0

Boolean. If >0, then QuickDriveIO is included. This requires QuickMath to be included as well.

QuickOS_Config::ADDBANK

Default: 0

Boolean. If >0, then QuickBank is included.

QuickOS_Config::ADDSTRING

Default: 0

Boolean. If >0, then QuickString is included.

QuickOS_Config::ADDSCREEN

Default: 0

Boolean. If >0, then QuickScreen is included.

QuickOS_Config::ADDSCREENSCRIPT

Default: 0

Boolean. If >0, then QuickScreenScript is included. This requires both QuickString and QuickScreen to be included as well.

QuickOS_Config::ADDKEYBOARD

Default: 0

Boolean. If >0, then QuickKeyboard is included.

QuickOS_Config::ADDJOYSTICK

Default: 0

Boolean. If >0, then QuickJoystick is included.

QuickOS_Config::ADDMATH

Default: 0

Boolean. If >0, then QuickMath is included.

Misc Addresses

QuickOS_Config::ZeroPageStart

Default: $00

Zero Page Address, The start zero page address for QuickOS to use.

QuickOS_Config::EndAddress

Default: $FFE4

Address, The end address for QuickOS. It will not reach nor exceed this address.

Expected values: $FFFA for 6502 and 65c02 only, or $FFE4 for a possible 65c816.

QuickOS_Config::EndAddress2

Default: $C800

Address, The second end address for QuickOS, under the hardware. It will not reach nor exceed this address.

If QuickOS_Config::ScreenAddress is changed, this should probably be set to $D000.

QuickOS_Config::ScreenAddress

Default: $C800

Address, A 2KB region in memory in memory for the default font and screen to appear. If not using the default screen and font, this can be ignored.

Must be on a 1KB boundary.

NOTE: By default, QuickScreen::SetGeneral sets its screen space to this + $0400, and assumes the standard font is at this address. See the QuickScreen config if using that feature.

Also, QuickOS_Config::EndAddress2 is put below this address by default (the same value). If this is relocated, then QuickOS_Config::EndAddress2 should probably be changed to $D000.

QuickOS_Config::DoResetCopyAddress

Default: $0700

Address, Where to copy the "DoReset" function to then enable ROM and reset using the Atari ROM.

Boot Screen Constants

QuickOS_Config::BOOTSCREEN

Default: 1

Boolean, Whether to display the boot screen during start up or not.

QuickOS_Config::BOOTSCREENFADEOUTSPEED

Default: 4

Byte, Whether to fade out the boot screen. 0 - No fade, >0 - The speed the fade occurs at, in frames per change (7 iterations of fading are used). This does delay loading since the fade has to complete before loading can continue.

QuickOS_Config::BOOTSCREENPAUSE

Default: 1

Boolean, >0 to require a keypress to continue past the boot screen. Only used if the boot screen is enabled.

Misc Constants

QuickOS_Config::DEBUG

Default: 0

Boolean, >0 to include extras for debugging.

QuickOS_Config::NEWLINE

Default: $0A

Byte, The character code to use for new line. $0A ("\n") or $0D ("\r") are expected.

QuickOS_Config::ENABLEZPBITS

Default: 0

Boolean, > 0 to include 8 zero page entries, one for each bit, for BIT $ab-style instructions.

Enabling this uses 8 more zero page entries.

QuickOS_Config::VSYNCSIZE

Default: 2

Byte, The number of bytes QuickOS::ZP_VSync uses. 1 to 5 is supported.

This changes the resulting size of the OS as well as the number of zero page entries used. It only adds a negligible amount of execution time, however.

These allow tracking the amount of time specified in the chart below:

1: 4.27 seconds (NTSC) / 5.12 seconds (PAL)
2: 18.2 minutes (NTSC) / 21.845 minutes (PAL)
3: 3.236 days (NTSC) / 3.8836 days (PAL)
4: 2.268 years (NTSC) / 2.722 years (PAL)
5: 580.69 years (NTSC) / 696.83 years (PAL)