C64 OS USER'S GUIDE

Chapter 10: Appendices

The appendices contain useful summaries, for easy reference, of informataion that is elsewhere found throughout the User's Guide. It also contains some supplementary information about that would have bogged down the main User's Guide and so can be considered as footnotes.

• Frequently Asked Questions
• Software License Agreement
• C64 Tools
• Character Sets
• Data Types
• Drivers
• File References
• KERNAL
• Libraries
• Settings
• SID Music
• System Directory
• Toolkit Classes
• Boot Modes

Frequently Asked Questions

How do I purchase a copy of C64 OS?

You can purchase a copy of C64 OS right here on C64OS.com. Start here and choose whether you want the Standard Bundle (64 MB System Card) or the Extended Bundle (64 MB System Card + Extras.) . Click the "Order Now" button and you are taken to the OpCoders Store where you can specify a quantity and add it to your cart.

Check out some of the other offerings in the store while you're there.

What do I get when I buy a copy of C64 OS?

A licensed copy of C64 OS v1.07 includes:

• Access to the 3,500 word online Getting Started Guide
• Access to the complete 150,000 word online User's Guide
• A 50-page full-color professionally printed User's Guide Supplement
• A pre-installed copy of C64 OS v1.07 on a System Card (64 MB or 128 MB SD Card)
• An installation archive and install tools for C64 OS v1.07 for other storage media
• App Launcher, File Manager, Wikipedia, Image Viewer, C64 Archiver, 3 additional Applications and over 35 Utilities, plus 10 KERNAL modules, 20 Drivers, 26 Libraries, 28 Toolkit classes, and over 25 additional Tools
• Two high-quality promotional C64 OS vinyl stickers
• Access to ongoing patches, bug fixes and feature updates to C64 OS
• Access to new non-commercial Applications and Utilities for C64 OS
• Access to a C64 OS Discord server for support, help, bug reporting, news and community

The standard (64 MB) System Card also comes with these bonuses:

• A pre-installed CMD HD hard drive image of C64 OS v1.07 for use in VICE
• A pre-installed IDE64 hard drive image of C64 OS v1.07 for use in VICE
• A collection of C64 graphics files that can be viewed with Image Viewer
• A collection of popular HVSC SID tunes that have been relocated for use in C64 OS

The extended (64 MB) System Card comes with these bonuses:

• A commericial copy of the Desktop Designer Application
• A commericial copy of the Eliza for C64 OS Application
• A copy of the Fart Machine Application
• A collection of CGFX animations, panoramas and matrix images
• A collection of PETSCII Bots
• Plus all the bonuses of the standard system card

The C64 OS bundles do not come in a product box. The labeled System Card is elegantly mounted on the inside cover of the User's Guide, and this is contained in a clear cellophane self-sealing product bag.

For a detailed overview of the contents of the C64 OS system and accompanying software, you can peruse this online User's Guide.

By purchasing a copy of C64 OS you acquire a license to use C64 OS on any number of C64 computers, and emulators for your personal use. You can review the software license agreement and other legal documents here. With the ability to run C64 OS you gain access to the future Applications, Utilities, drivers, libraries and other C64-OS-specific technologies that are planned and under development.

There are point upgrades to the system software with new features and bug fixes that are free to download from the System Updates page. These add new libraries, drivers, Toolkit classes, Applications and Utilities.

There are both free and commercial software packages which can be downloaded from the C64 OS Software Releases page.

What does C64 OS cost?

The C64 OS software package costs $64 (Canadian dollars) for the Standard Bundle (64 MB System Card), or $67 (Canadian dollars) for the Extended Bundle (64 MB System Card + Extras), plus shipping and any applicable sales tax.

Both versions contain the same base content. Both cards include some bonus content, including a pre-installed CMD HD hard drive image and a pre-installed IDE64 hard drive image, to make it easy to get started with C64 OS on VICE. The extended bundle also includes a commercial copy of Eliza for C64 OS and Desktop Designer, as well as coming packaged with some other media and content.

Is C64 OS compatible with VICE?

Yes. C64 OS is compatible with VICE v3.5 and greater with support for the CMD HD and IDE64. You can find installation instructions for VICE in Chapter 2: Installation → Installation on VICE.

It should also be possible to install C64 OS on a physical CMD HD or SD2IEC that is connected to a PC running VICE. However, this configuration and details on how to configure VICE in this manner are not outlined by this User's Guide.

Is C64 OS compatible with TheC64, mini or Maxi?

Yes. When C64 OS v1.0 was first released, it was thought that it would not be compatible with TheC64 mini or Maxi due to lack of support for virtual CMD HD and also the lack of a physical IEC port. However, an industrious early C64 OS user has come up with a way to activate a virtual IDE64 on TheC64. With C64 OS pre-installed in an IDE64 disk image via VICE, it can be added to TheC64 allowing C64 OS to boot and run.

Is C64 OS compatible with BMC64?

No. Unfortunately, BMC64 does not support the one minimum requirement to run C64 OS. Although BMC64 runs a custom version of VICE, that version does not have support for a virtual CMD HD.

Additionally, BMC64 does not have support for physical IEC ports, and therefore it cannot be connected to a real SD2IEC or CMD HD.

Can C64 OS be run from a 1541 or 1571?

No. A 1541 and 1571 are legacy, low-capacity storage devices. C64 OS can access 1541 and 1571 drives and compatible recreations of these devices, such as Pi1541, to manage data, (rename files, copy files to and from, scratch files, etc.), but they cannot be used as the C64 OS system drive.

There are three reasons for this:

1. The storage capacity is much too low. A base C64 OS installation is greater than 1 megabyte. That's over 6 times the capacity of a 1541 disk side and over 3 times the capacity of a 1571 disk.
   
   
2. The native file system on 1541 and 1571 disks does not support subdirectories. C64 OS's system directory depends on the logical layout of files into over 50 nested subdirectories. See Chapter 8: File System → System Directory.
   
   
3. The single root directory of a 1541 or 1571 disk can hold only a maximum of 144 files. But, a working installation of C64 OS comprises upwards of a 1000 files.

Can C64 OS be run from a 1581?

No. A 1581 is a legacy, medium-low-capacity storage device. C64 OS can access 1581 drives to manage data, (rename files, copy files to and from, scratch files, etc.), but they cannot be used as the C64 OS system drive.

There are three reasons for this:

1. The storage capacity is too low. A base C64 OS installation is greater than 1 megabyte, which is more than the capacity of a 1581 disk.
   
   
2. The native file system on 1581 disks does not support subdirectories. 1581 disks support something called sub-partitions, but they do not work the same as subdirectories. For example, they can't be nested and are not easily created or removed the way subdirectories can be. C64 OS's system directory depends on the logical layout of files into over 50 nested subdirectories. See Chapter 8: File System → System Directory.
   
   
3. The single root directory of a 1581 disk can hold only a maximum of 296 files. But, a working installation of C64 OS comprises upwards of a 1000 files.

Can C64 OS be run from a CMD FD 2000 or 4000?

Yes. A CMD FD Series floppy disk drive is the lowest capacity drive that is classified as a modern device. See Chapter 8: File System → Drives and Devices for a table of supported legacy and modern devices.

A CMD FD 2000 disk has a storage capacity of 1.6MB, and an FD 4000 disk has a capacity of 3.2MB. Both of these capacities are enough to hold a base installation of C64 OS. Additionally, CMD FD disks support CMD native-mode partitions, which support subdirectories just like the CMD HD and RAMLink, which is a requirement for the C64 OS system drive.

Due to the low capacity of a CMD FD Series (especially an FD 2000), very little room is left on the system disk for Applications, documents, music, pictures, etc. It is therefore recommended that a custom installation for a CMD FD disk exclude all non-essential resources. For example, if the build will be used with a mouse, other input drivers can be removed. If an Application is not required, omit it. Further customization possibilities are left to the imagination of the courageous C64 OS explorer.

Can C64 OS be run from Kung Fu Flash?

No. A Kung Fu Flash is primarily a multi-cartridge emulator. It can mount .D64, .D71 and .D81 disk images, and behave, respectively, like a 1541, 1571 or 1581 drive. However because it is not connected via the physical IEC bus it is compatible with these drive types only when the software limits itself to standard KERNAL calls.

C64 OS in fact limits itself only to KERNAL calls. However, in this case, a Kung Fu Flash now has all of the limitations discussed above about running C64 OS from a 1541, 1571 or 1581.

Can C64 OS be run from EasyFlash3?

No. An EasyFlash3 is primarily a multi-cartridge emulator. D64 images can be converted to .CRT images and loaded onto EasyFlash3. However because it is not connected via the physical IEC bus it is only compatible with software that limits itself to standard KERNAL calls. C64 OS in fact limits itself only to KERNAL calls. However, in this case, EasyFlash3 still has all of the limitations discussed above about running C64 OS from a 1541.

Although C64 OS cannot be run from EasyFlash3, that doesn't mean that C64 OS cannot benefit from having one. For example, EasyFlash3 can be used to replace the C64's KERNAL ROM without having to physically replace the ROM. Thus, it can be used to provide a C64c with the JiffyDOS KERNAL, without having to desolder its non-socketed KERNAL ROM.

Can C64 OS be run from a 1541 Ultimate II+

No. A 1541 Ultimate II+ is, first and foremost, a very faithful reproduction of a 1541 disk drive. It connects both via the expansion port and via the IEC port and provides up to two highly compatible virtual 1541s. It uses a mass storage device which it accesses via its own backend menu system to pick and mount a disk image into one of the virtual disk drives.

With recent firmware updates 1541 Ultimate II+ can also behave like a virtual 1571 or 1581. However, in this case, it now has all of the limitations discussed above about running C64 OS from a 1541, 1571 or 1581.

The 1541 Ultimate II+ is much more than just a virtual disk drive. It can be used as a 17xx REU up to 16MB or a GEORAM up to 4MB. It has simulated additional SID chips; it has an RTC that C64 OS has a driver for; it can be used to provide a replacement KERNAL ROM, among many other useful features. Therefore, although a 1541 Ultimate II+ cannot be used as the C64 OS system drive, it can be used in powerful combination with an SD2IEC or CMD HD.

Can C64 OS be run from an Ultimate64?

Yes and No. An Ultimate64 is a complete modern C64 reproduction in FPGA with all of the functionality of a 1541 Ultimate II+ built-in. Can an Ultimate64 be used as the Commodore 64 computer that runs C64 OS? YES, definitely. But is the 1541 Ultimate II+ functionality built into the Ultimate64 able to be used as the system drive onto which C64 OS is installed? No. For the reasons discussed above about 1541 Ultimate II+.

An Ultimate64 is a C64, plus it has highly compatible virtual floppy disk drives. But it also has a built-in 17xx REU up to 16MB or a GEORAM up to 4MB. It has simulated additional SID chips; it has an RTC that C64 OS has a driver for; it can have any KERNAL ROM installed; its clock rate can even be sped up, among many other useful features. Therefore, although C64 OS cannot use one of the virtual 1541, 1571 or 1581 drives as its system drive, an Ultimate64 has a full expansion port and standard IEC serial ports and can be used in conjunction with an SD2IEC, CMD HD or IDE64 for a very powerful combination.

Can C64 OS play SID music?

Yes. C64 OS (v1.04 and up) includes the SID Preview Utility for playing SID music from within any C64 OS Application. SID Preview uses the sidplay library, described below. C64 OS (v1.06 and up) includes the Visualizer Application with additional options for playing music collections.

C64 OS (v1.0 and on) includes a library capable of loading and playing SID music in PSID format. However, the memory address range used by the main music data, and the zero page memory used by various SID music files, is not standardized. When you try to load a PSID, it first checks to see if the range of required main memory is available. If it's unavailable the file will fail to load. If it is available it gets loaded in and that area of memory is marked in the allocator as taken so that other processes won't use that memory.

However, most of zero page is already spoken for by C64 OS, its libraries, drivers, Applications and Utilities. Therefore, if you simply load any random PSID, when it runs it will most likely overwrite unavailable zero page and the system will crash. C64 OS reserves 4 consecutive zero page addresses just for SID music. Many but not all PSIDs can be relocated using the sidreloc tool to be safe to use within C64 OS.

OpCoders Inc. also hosts a suite of web-services intended to support C64 OS. One of these is the SID search service. Information about the SID search service can be found here: http://services.c64os.com/about#sid. This service allows you to find and download SID music which has been relocated to be compatible with C64 OS. This service hosts over 34,000 songs from the High Voltage SID Collection.

See: Appendix IX. SID Music for more information about SID music support in C64 OS and tips about relocation.

Can the File Manager copy files to, from or between 1541, 1571 and 1581 disk drives?

Yes. The C64 OS File Manager has 4 tabs, and each tab can be in any place. Any device, any partition, any path on that partition. You can then recursively copy or move files and directories between any two tabs.

Supported devices include: 1541, 1571, 1581, CMD FD, CMD HD, RAMLink, IDE64 and SD2IEC. Plus their equivalent clones, like Pi1541, 1541UII+, etc.

Can the File Manager copy files to and from D64, D71, D81 or DNP disk images?

Yes. Although C64 OS's File Manager does not directly read/write disk images, SD2IEC has the ability to mount disk images into a partition. The C64 OS System Card comes with two partitions already setup. Partition 1 is the C64 OS system partition. Partition 2 is called Disk Images. If you put your disk images into the second partition, you can mount them using the Mount Utility. File Manager can copy files into and out of that image by just opening partition 2 in a tab, and using File Manager as normal.

The Mount Utility and the unmount command in File Manager are available starting in C64 OS v1.03. All standard disk images are assigned to the Mount Utility by default. Double-click a disk image in File Manager and it opens the Mount Utility. The image can be mounted if it is in any partition of an SD2IEC that is not the C64 OS system partition.

Can C64 OS be used without a 1351 mouse?

Yes. If you are not lucky enough to have a real 1351 mouse, there are numerous commercially available 1351-compatible mouse adapters. There are adapters for both PS/2 and USB mice. Two popular adapters are the MicroMys v5 (PS/2) and the MouSTer (USB). There are numerous other less well known options, many are listed in the Commodore 8-bit Buyer's Guide.

Beginning in C64 OS v1.03, mouse wheel events are supported throughout the system for scrolling lists, tables, text areas and more. The scroll wheel is supported via the mouse driver for MicroMys and MouSTer. Other 1351-compatible mouse adapters, if they do not support the MicroMys wheel protocol, may still be used with the 1351 driver.

Can C64 OS be used without a mouse?

Yes. If you don't have a 1351 mouse or adapter, and you don't want to spring for buying one of the many available adapters, you can still use C64 OS. There are input drivers for regular joysticks, light pen, Koala Pad, and—if you're running C64 OS on a C128—there is a driver to use the C128's numeric keypad for pointer input. A mouse is still recommended, however, for its speed and precision.

C64 OS Software License Agreement

The C64 OS End-User License Agreement (EULA) can be found in the legal subsection of C64OS.com. These other important resources can be found there as well, all of these links can also be found in the footer of every C64OS.com page:

• Terms & Conditions (for C64OS.com)
• Privacy Policy (for C64OS.com)
• Cookies Policy (for C64OS.com)
• C64 OS License Agreement (for C64 OS)
• Thanks and Credits (for C64 OS and C64OS.com)

I. C64 Tools

C64 Tools are a set of programs from various sources that are included alongside C64 OS, but they are not part of C64 OS proper. They are just regular C64 programs that load and run from the READY prompt. This collection of tools serves a wide variety of purposes. Some of the tools are only for programming and are covered in more detail in the C64 OS Programmer's Guide. C64 Tools can be found in the directory:

//os/c64tools/

• Alias Creator
• Backup
• C64 OS Setup
• C64 OS Booter
• C64restore
• CAR Search
• Configure
• MakeAutoBoot
• Novatext 1.2.2
• PRGAlias Creator
• Turbo Macro Pro

Alias Creator

//os/c64tools/:alias creator

This is a BASIC program that can create alias files on any App Launcher desktop. The program must be run while the default directory is the desktop directory. Switch to the desktop directory, then load and run the program by specifying the path to the c64tools directory in the load command.

Without JiffyDOS (assuming device 8):

open15,8,15,"cd//os/c64tools/":close15
load"//os/c64tools/:alias creator",8
run

With JiffyDOS:

@cd//os/desktop
↑//os/c64tools/:alias creator

The program is a simple wizard that asks questions for which you supply answers. New aliases are created and placed on the specified desktop. The aliases take a default color and position but can be later repositioned and colored using App Launcher.

Backup

//os/c64tools/:backup
Requires: JiffyDOS

This is a BASIC program to recursively backup any directory from one device to a different device. The directory processing is done in standard BASIC but requires features of JiffyDOS to perform the actual file copying.

To use this program, change into the starting directory on the source device where the backup should begin. Load and run backup, specifying the c64tools path in the load command. The following example could be used to backup the entire C64 OS system directory.

With JiffyDOS: (JiffyDOS is required anyway)

@cd//os/
↑//os/c64tools/:backup

When backup runs, it asks for the source and destination device numbers. These must be different, as that is a requirement of the JiffyDOS two-drive copier. In order to work as expected, the destination device must be a modern storage device.

Backup asks for the name of the destination directory. This is used to collect together repeated backups of similar types. For example, if you were backing up the C64 OS system directory, you might call the destination directory "c64 os backups". But if you were backing up your documents directory you might call the destination directory "document backups". If a directory with this name does not already exist (in the root directory of the destination device) it will be created.

Next it asks for today's date in YYYY-MM-DD format. All of the files and subdirectories found in the current directory of the source device will be copied into a subdirectory with this date as the name. Naming the directory in this format is not strictly required, but is recommended. It guarantees that backups taken on different days will be kept separate; it helps you find your backups in the future; and the order (year, month, day) lets them sort chronologically in the C64 OS File Manager and other programs that sort directories alphabetically.

Lastly, backup asks if you want to perform a full or an incremental backup. You should perform full backups of important directories, periodically, but you can run incremental backups between full backups. Incremental backups complete faster by only backing up files which have changed since the last backup. Incremental backups are only possible from a source device with a functioning and well adjusted RTC. Each time backup is run, it creates and/or updates a file, "backup.ts.t", in the source directory. This file records the date and time of the previous backup. It is used by the incremental backup to omit files that were modified prior to this date. If "backup.ts.t" is deleted or cannot be found, an incremental backup will be automatically converted into a full backup.

C64 OS Setup

//os/c64tools/:c64os setup

This file is one of the required BASIC programs for an initial C64 OS installation. It is found in the root directory of a new C64 OS version 1.0 System Card. A copy of this file is also found in the C64 Tools directory. In fact, when a C64 OS installation is unarchived from a restore.car file, that installs an //os/c64tools/ directory that contains this setup program.

After the initial setup is complete, this program can be scratched from the root directory, in order to clean up the root directory. It can be loaded and run directly from the C64 Tools directory at a later time, in order to change the installation location of a C64 OS system directory. See Chapter 2: Installation → About Installation Location for more information about how to use C64 OS Setup.

C64 OS Booter

//os/c64tools/:c64os

The program called "c64os" is the C64 OS booter. The booter has to be in the root directory alongside the system directory. However, a fresh backup copy of the booter is also found in the C64 Tools directory. This can be copied back to the root directory if your original booter is scratched or damaged. The booter is also a self-modifying BASIC program. So if it somehow ends up self-modified in an inappropriate way, it's convenient to have a clean backup readily available.

This copy of the booter can also be used in the advanced process of creating multiple C64 OS installations in the same partition. See Chapter 8: File System → Multiple Installations for more information.

C64restore

//os/c64tools/:c64restore

This file is one of the required programs for an initial C64 OS installation. It is found in the root directory of a new C64 OS version 1.0 System Card. A copy of this file is also found in the C64 Tools directory. In fact, when a C64 OS installation is unarchived from a restore.car file, that installs an //os/c64tools/ directory that contains a copy of this program.

After installation is complete, this program can be scratched from the root directory, in order to clean up the root directory. It is convenient to have a backup copy here. This program is not intended to be loaded and run independently. It is a component that gets loaded and run automatically as part of the installation process.

CAR Search

//os/c64tools/:carsearch
Requires: SD2IEC or IDE64

CAR stands for C64 Archive and is a file format produced by the C64 OS Application, C64 Archiver. The format supports 16-character PETSCII filenames, the CBM filetypes (PRG and SEQ), the file lock status, file size with byte precision, and nested subdirectories. The archive header contains an archive version number, an archive type code, date/time stamp of when the archive was created, and a short note.

CAR Search is a BASIC program for previewing the contents of a CAR file. CAR files are used to distribute complete C64 OS installation archives, installation overlay archives, as well as general purpose archives. CAR Search can only be run from either an SD2IEC or an IDE64. It depends on the ability to scan files, which means to efficiently skip an arbitrary number bytes forwards or backwards within a file.

Load the carsearch program, then make the SD2IEC or IDE64 the default device and change into the directory where the CAR file is located. Run the program. Enter the name of the CAR file and press return. It then proceeds to output the header information, followed by a recursive directory listing of everything contained within the archive. CAR Search supports multiple CAR format versions.

Example, with JiffyDOS:

///os/c64tools/:carsearch
@#10
@cd//somedirectory/
run

Enter the name of a .car file in //somedirectory/ on device 10.

Configure

//os/settings/:configure

Note that the configure tool does not reside in the standard c64tools directory. The configure tool modifies settings files, and therefore it's kept in //os/settings/ instead, so it can relatively reference files in that directory.

Configure should be run once after a fresh install, or at least once before you start using the copy of C64 OS that comes pre-installed on the System Card (SD Card.) See Chapter 3: Configuration and Settings for more information about how to use the configure tool.

MakeAutoBoot

Available: 1.07+

//os/c64tools/:makecmdautoboot
//os/c64tools/:makesd2autoboot

The Commodore 128 has the ability to autoboot by requesting an autoboot sector from the default partition of device 8. Two tools can be run from the READY prompt to configure either a CMD HD, CMD FD-2000/4000, or SD2IEC to autoboot C64 OS.

The tools are run from C64-mode on a C128, and you must change into the //os/c64tools/ directory before loading and running the tools. They can be used to create or uncreate an autoboot sector. With the autoboot sector set up, when the C128 is booted into C128-mode, it will switch to C64-mode automatically and boot C64 OS.

To configure a CMD HD, FD-2000 or FD-4000:

With JiffyDOS:

@cd//os/c64tools
↑makecmdautoboot

Without JiffyDOS:

open15,8,15,"cd//os/c64tools":close15
load"makecmdautoboot",8
run

To configure an SD2IEC:

With JiffyDOS:

@cd//os/c64tools
↑makesd2autoboot

Without JiffyDOS:

open15,8,15,"cd//os/c64tools":close15
load"makesd2autoboot",8
run

The CMD RAMLink and IDE64 each have their own ways to autoboot C64 software. Consult their user manuals for further information about autoboot configuration.

Novatext 1.2.2

//os/c64tools/:novatext 1.2
//os/c64tools/:novatext 1.2.2

Novatext version 1.2 is an easy-to-use PETSCII text editor written by Nick Rossi. It came bundled with Novaterm 9.6 and was included for being able to edit script files and other texts. Earlier versions were available in earlier versions of Novaterm. The complete source code of Novaterm 9.6 was later released.

Novatext 1.2 is not compatible with SD2IEC. However, Novatext 1.2.2 is a patched version that has been fixed to support reading and writing files with SD2IEC. Both the original and the patched version are included in the c64tools directory. The program has built-in help, which can be accessed with CONTROL+H. Novatext is very useful for editing any of the C64 OS text-based resources, such as settings files, menu definitions, and Application about files. It can also be used for editing SD2IEC swaplist files.

NOTE: Novatext is not compatible with IDE64.

PRGAlias Creator

//os/c64tools/:prgalias creator

PRGAlias Creator has been superseded by the PRG Alias Maker Utility.

PRG aliases are files which hold metadata about how a regular C64 PRG file is to be loaded and run. PRG alias files are stored in "//os/prg aliases". The PRG Runner Utility opens PRG aliases and uses them to launch into that program from within C64 OS.

PRGAlias Creator is a tool for creating and configuring PRG aliases. To use the tool, first change into the prg aliases directory. Then load and run PRGAlias Creator. It asks a series of questions about the program. You have to know ahead of time the answers to all of these questions. For example, if the program is found on a device that is not #8, is it capable of running from that device number, or should the source device be swapped to device #8 first? Does the program have a BASIC loader, or does it require jumping to the start address where the program is loaded to?

PRG Runner is also capable of mounting disk images and swaplists. These options can be specified with PRGAlias Creator, but the swaplist file has to be created by some other means.

Without JiffyDOS:

open15,8,15,"cd//os/prg aliases":close15
load"//os/c64tools/:prgalias creator",8
run

With JiffyDOS:

@cd//os/prg aliases
↑//os/c64tools/:prgalias creator

Turbo Macro Pro

//os/c64tools/:tmp

Turbo Macro Pro is a 6502 macro assembler for the Commodore 64. It was originally released in 1985 as Turbo Assembler by the German company, Omikron. It is now maintained by Style. There has not been a new release of the C64-native version of Turbo Macro Pro since v1.2 in 2006. It is available in numerous pre-assembled binaries. They are all considered version 1.2, but each has different assemble-time options enabled with support for various hardware configurations.

The version found in the c64tools directory is TMP+REU. Turbo Macro Pro v1.2 with support for 17xx REUs. This is the version of Turbo Macro Pro that was used to program and assemble all of C64 OS; its KERNAL, Libraries, Drivers, Toolkit Classes, Applications, Utilities and more. With this assembler and the headers, constants and macros files that are included with C64 OS, it is possible to use a Commodore 64 itself to create new C64 OS drivers, new libraries, toolkit classes, Applications and Utilities.

More information about how to use Turbo Macro Pro, how to use the C64 OS APIs, and to find source code samples and tutorials, see the C64 OS Programmer's Guide.

II. Character Sets

C64 OS loads a new character set into memory. The character set resides in RAM under I/O, from $D000-$D7FF. The character set consists of uppercase and lowercase letters, numbers and standard symbols. Several symbols on a standard C64 have been replaced by their more standard equivalents from ASCII.

The upper half of the character set is mostly the reverse of the lower half, with a few exceptions. The final block of 32 characters in each half are reserved from graphical user interface elements. 9 of those, from each half, 18 characters total, are reserved from the Application or Utility to redefine.

Keyboard Mapping for Special Characters

Lowercase (Block 1 and Block 5)

Numbers and Symbols (Block 2 and Block 6)

Uppercase (Block 3 and Block 7)

UI Characters (Block 4 and Block 8)

III. Data Types

//os/s/:type.s

C64 OS data types are like simplified MIME types. A C64 OS data type consists of a 1-byte type code, and a 1-byte subtype code. Subtype codes are reused for each type code. There are thus 256 possible types and each type has 256 possible subtypes. Providing for a maximum of 65536 possible C64 OS data types.

New C64 OS data types are created by discussion and concensus in the community of developers. C64 OS data types are not valid, and should not be used, unless they are documented and listed on C64OS.com.

C64 OS Data Types (Type Codes)

C64 OS Data Subtypes (CT_TEXT: Subtype Codes)

C64 OS Data Subtypes (CT_APPL: Subtype Codes)

C64 OS Data Subtypes (CT_AUDIO: Subtype Codes)

C64 OS Data Subtypes (CT_IMAGE: Subtype Codes)

C64 OS Data Subtypes (CT_VIDEO: Subtype Codes)

See Chapter 4: User Interface → Clipboard for an example of the internal use C64 OS data types.

IV. Drivers

//os/drivers/
//os/settings/:kbd.drv.t
//os/settings/:ptr.drv.t
//os/settings/:rtc.drv.t
//os/settings/:network.t

In order for a driver to be available for C64 OS to use, it must be put in the //os/drivers/ directory. There are several driver types, each type may be occupied by a single driver at a time. Drivers and optional data are specified in various settings files in //os/settings/ usually ending with drv.t but not always.

Pointer Drivers

Joystick (Game) Drivers

Keyboard Drivers

Network Drivers

Realtime Clock Drivers

See Chapter 8: File System → Drivers for more information about drivers.

V. File References

C64 OS uses a unified file reference format. It consists of 4 parts separated with colons.

device#:partition#:filename:path

On modern devices, which support partitions, specifying 0 for the partition is a reference to the partition directory.

device#:0::

A filename can be omitted for a file reference to be a reference to a path only.

device#:partition#::path

Paths use the standard path structure of CMD devices, SD2IEC and IDE64. Two leading slashes for the root directory, one leading slash for the current directory. Followed by a subdirectory name and a trailing slash. Multiple subdirectories can be appended, but each one, including the last needs its trailing slash.

Slashes in the name of a subdirectory are not permitted.

See Chapter 8: File System → File References for more information about file references, their component parts and directory path structure.

VI. Hardware Compatibility

C64 OS is compatible with a wide range of Commodore equipment and third-party hardware expansions. The following tables are not a list of minimum requirements nor do they imply that all hardware listed can be used concurrently. However, individually, all of the hardware items listed below can be used with C64 OS.

Boot Storage

The following devices can be used to install and boot C64 OS.

Storage

The following devices are recognized by C64 OS for accessing and managing data.

Pointer Input

Memory

Network Hardware

VII. KERNAL

//os/kernal/
//os/settings/:modules.t

The C64 OS KERNAL is divided into 10 modules. There can be different versions of modules, which are selected and loaded by the booter by reference to the modules.t file in the settings directory.

A KERNAL module lookup table is installed to the end of $CFFF and down, by the C64 OS booter. The KERNAL plus lookup table from $CFFF down to around $8200. The final page of available heap memory is configured by the booter based on hardware configuration.

C64 OS KERNAL Modules

The booter inteprets conditional codes in the components.t file to decide whether to load alternative KERNAL modules (.cpu or .reu) depending on whether an REU was detected.

VIII. Libraries

//os/library/

In order for a library to be available for C64 OS to use, it must be put in the //os/library/ directory. Libraries are relocatable and single instances loaded into memory can be shared by multiple processes to conserve memory.

Shared libraries can also be sourced out of an Application's bundle. This allows Applications to parcel their functionality into libraries, without needing to install the library in the system-wide library directory. Libraries are managed by the services KERNAL module.

Libraries included with C64 OS

See Chapter 8: File System → Libraries for more information about shared libraries.

I2C is a simple serial bus for communication between a computer or microcontroller and low-speed peripheral ICs. The I2C library provides an implementation of the I2C bus that allows C64 OS to communicate with I2C peripherals connected to the User Port.

An I2C bus only requires two communications lines. The Commodore 64's KERNAL ROM also provides built-in support for RS-232 over the User Port. Both communications protocols use only a subset of the User Port's available communications lines. The lines used for RS-232 cannot be changed, however, and there are many WiFi and traditional modems and other RS-232 devices fixed to the lines used by the KERNAL ROM.

It is possible to drive the I2C bus via lines not used by RS-232. This allows the use of I2C and RS-232 devices on the User Port at the same time without interference. However, GEOS also has some software that can use the I2C bus, but it uses lines which overlap with RS-232. For this reason, C64 OS provides two versions of the I2C library. One which is compatible with RS-232 devices but not compatible with GEOS. The other with the compatibility priorities reversed. You should choose which one to use based on your needs. If you want to use I2C in both C64 OS and in GEOS, select the GEOS compatible I2C library. Otherwise, go with the version that is compatible with RS-232.

There are two versioned library files:

C64 OS loads the library called i2c.lib.r. To change the version you're using, start by scratching the file i2c.lib.r, then, depending on which User Port lines your I2C bus is connected to, copy the corresponding i2c.lib.ver_XX.r back to i2c.lib.r. For example:

With JiffyDOS:

@cd//os/drivers/
@s:i2c.lib.r
@c:i2c.lib.r=i2c.lib.ver_ef.r

This can also be done with the C64 OS File Manager, but a reboot may be required for the change to take place.

See the weblog post I2C Serial Bus in 6502 for a technical deep dive on how to use I2C on your Commodore 64.

IX. Networking

//os/drivers/
//os/library/
//os/utilities/

Networking in C64 OS consists of several layers:

• Network hardware drivers
• Network library
• CNP library
• Network Utility

The Network Utility is used to configure the network settings, including picking the driver suitable for your network hardware. Applications load the network library which loads, configures and coordinates between the network hardware driver and the CNP library.

The CNP library provides a network socket API to Applications and Utilities that want to access the internet. The Commodore Network Protocol is used to exchange packets between C64 OS Applications and a CNP server running in the cloud.

For a full explanation about how to configure networking in C64 OS, see the C64 OS Networking Guide.

X. Settings

//os/settings/

C64 OS settings are stored in human-readable settings files in the //os/settings/ directory. Many of these files are configurable with C64 Utilties or Tools, others can be manually customized using a text editor, such a Novatext.

It is highly recommended that you backup any settings file before manually editing it. They are sensitive to extra spaces and carriage returns that you can't see. Use the C64 tool //os/c64tools/:datacheck to list a settings file's data one byte at a time. If a manual change doesn't work, compare it against the backup for trailing carriage returns or lack thereof.

Standard Settings Files

See Chapter 3: Configuration and Settings for more information about customizing settings.

See Chapter 8: File System → Settings for more information about settings and the settings directory.

XI. SID Music

//os/library/:sidplay.lib.r

C64 OS includes a Utility, SID Preview (available in v1.04 and up), which can load and play PSID files that are compatible with the C64 OS sidplay library. See the following notes on the sidplay library.

C64 OS includes a shared library, sidplay.lib.r, which can be loaded and used by Applications and Utilities to load and play SID music in PSID format. There are, however, numerous restrictions and caveats.

Unlike text data, or digital audio, or graphics data, SID music is effectively 6502 executable code. The data for the music is incorporated into custom player code, used to achieve unique and advanced sound effects. Typically a piece of SID music is composed and assembled in cooperation with a game or demo developer. The developer and the musician negotiate on things like heap memory amount and location, available zero page addresses, acceptable CPU utilization, and other special hardware requirements for things like embedded digital samples.

It is problematic to combine arbitrary SID music with an operating system, such as C64 OS, because the two were not originally designed to work together. Memory in C64 OS is dynamically allocated. There is no way to guarantee that a given fixed address range will always be available. Sidplay lib checks the PSID headers and the file's overall size to determine the start address and length of memory required. It then checks the memory allocation table to see if that memory is available. If it is available, sidplay.lib manually marks that memory as allocated and loads the SID data into that block. However, if it is not available, in whole or in part, you are simply out of luck and the library reports back to the Application that it is unable to load that SID.

An additional problem is zero page memory usage. Neither the SID music itself, nor the PSID headers, explicitly indicate which zero page addresses the music will modify while playing. In C64 OS, most of zero page is already manually/statically allocated to various system-level processes. Most SID music, which makes arbitrary use of zero page, will almost certainly cause C64 OS to crash. C64 OS reserves 4 consecutive zero page addresses (enough for 2 pointers) just for SID music use. Many SIDs, although not all, can be relocated using a cross-platform tool such as Sidreloc by Linus Åkesson (aka LFT) to use the zero page memory address that are explicitly reserved for SID music.

sidreloc -p 20 -z b0-b3 input.sid output.sid	
	

XII. System Directory

Below is an outline of the main structure of the C64 OS system directory. Some of these system subdirectories are broken down into further detail in the sections that follow.

XIII. Toolkit Classes

Below is the list of Toolkit classes and the C64 OS version number in which they first became available. There are two types of classes. The core set is built-in and always memory resident. Relocatable classes are loaded and linked by an Application or Utility when they are needed.

The classes are listed in alphabetical order, but grouped and indented according to their inheritence.

XIV. Boot Mode Customization

C64 OS (v1.04+) provides an option for booting up in different configuration modes. The default mode is chosen if no key is held during boot up. Number keys can be held during the early stage of boot up to select an alternative boot mode.

In the default mode, the booter reads a set of components from //os/settings/:components.t

If any alternative mode is selected, the booter reads the set of components from //os/settings/:componentsX.t where X is the number 1, 2, 3, or 4, according to the selected mode.

Structure of a components file

A components file consists of a set of components that are to be loaded in during the early stage of the boot process. Each line is read from the file, and processed in order. Each line begins with a letter code that determines how that component is to be handled.

A components file is always in PETSCII. Characters shown in the table below in lowercase have been typed on the C64 without the use of the SHIFT key, and appear in lowercase when using the lowercase/uppercase character set.

The semi-colon comment is usually used for textual compents and section headings. The hash comment is usually used for temporarily disabling lines that would otherwise be processed.

Following any of the codes: l, r, or d (Load, Run, or Defer) comes a filename with an optional path relative to the current system directory. Most boot components are found in the library directory. Thus, to load and run the component stored at //os/library/:charset.o the following line is used in the components file:

r/library/:charset.o

Reference to deferred components are pushed to a stack and are thus run in the reverse order in which they are listed. I.e., the last "d" component listed in the file gets run first, after the components.t file is finished being processed and closed. Then the second last "d" component, then the third last, etc.

Some components are required for the proper functioning of C64 OS. However, some components can be excluded to change the behavior of C64 OS, or to speed up the boot process if they are not required.

For example, the ide64.r component is only required if you are using an IDE64. If you are not using an IDE64 this component can be either remove or commented out.

Similarly, if you do not have an SD2IEC, you can remove or comment out the sd2iec.r component. If you want to use a bitmap bootscreen rather than the text-based bootscreen, you can comment out boot.screen.o and add in (or uncomment) boot.koala.o or boot.art.o to show either a Koala Paint or ArtStudio formatted bitmap bootscreen.

The m code is followed by a single digit number. For example: m1 or m2. If this code is completely omitted, the booter will use //os/settings/:modules.t when loading in the KERNAL modules. Otherwise, it will use //os/settings/:modulesX.t where X is the number found after the m code. This allows different components files to have the booter choose a different modules file. This can be used, for example, to set up a boot mode that chooses a modules files that will not load the service.reu.o module even though an REU has been detected.

Further details about how the components are used, the order they come in and how to write your own boot components or how to write replacement components for the existing ones is found in the C64 OS Programmer's Guide.

Structure of a modules file

Modules files are found in the settings directory. The default modules file is //os/settings/:modules.t however alternative modules files can also be created in the settings directory as modulesX.t where X is a single digit number from 0 to 9. The alternative modules files are selected by use of the "m" code in the components file.

A modules file consists of a set of KERNAL modules that are to be loaded in during the middle stage of the boot process. Each line is read from the file, and processed in order. Each line begins with a letter code that determines whether that module is selected to be loaded.

A modules file is always in PETSCII. Characters shown in the table below in lowercase have been typed on the C64 without the use of the SHIFT key, and appear in lowercase when using the lowercase/uppercase character set.

The semi-colon comment is used for textual compents and section headings.

Following any of the codes: *, +, or - (Always, REU-only, CPU-only) comes a filename with an optional path relative to the current system directory. Most KERNAL modules are found in the kernal directory. Thus, to load a modules stored at //os/kernal/:math.o the following line is used in the modules file:

*/kernal/:math.o

Further details about how the modules are used, the order they come in and how to write replacement KERNAL modules for the existing ones is found in the C64 OS Programmer's Guide.

Next Chapter: Glossary

Table of Contents

This document is subject to revision updates.

Last modified: May 19, 2025