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 Enhanced Bundle (128 MB System Card). 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 enhanced (128 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 64 MB 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 $72 (Canadian dollars) for the Enhanced Bundle (128 MB System Card), plus shipping and any applicable sales tax.

Both versions contain the same base content. The main difference is the available capacity of the original System Card. The larger capacity card lets you to use the official C64 OS System Card as a primary mass-storage device, and provides additional free space for future 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 enhanced 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.

Thanks Andrew Gillham!

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

Key/Combination	Symbol	Description
pound (£)	\	backslash
Up Arrow (↑)	^	circumflex
Left Arrow (←)	_	underscore
SHIFT+asterisk (*)	`	backtick
SHIFT+plus (+)	{	left brace
SHIFT+pound (£)	|	pipe
SHIFT+minus (-)	}	right brace
SHIFT+Up Arrow (↑)	~	tilde

Lowercase (Block 1 and Block 5)

ScreenCode	Symbol	Description	ScreenCode	Symbol	Description
0	@	at-symbol	128	@	at-symbol reversed
1	a	lowercase a	129	a	lowercase a reversed
2	b	lowercase b	130	b	lowercase b reversed
3	c	lowercase c	131	c	lowercase c reversed
4	d	lowercase d	132	d	lowercase d reversed
5	e	lowercase e	133	e	lowercase e reversed
6	f	lowercase f	134	f	lowercase f reversed
7	g	lowercase g	135	g	lowercase g reversed
8	h	lowercase h	136	h	lowercase h reversed
9	i	lowercase i	137	i	lowercase i reversed
10	j	lowercase j	138	j	lowercase j reversed
11	k	lowercase k	139	k	lowercase k reversed
12	l	lowercase l	140	l	lowercase l reversed
13	m	lowercase m	141	m	lowercase m reversed
14	n	lowercase n	142	n	lowercase n reversed
15	o	lowercase o	143	o	lowercase o reversed
16	p	lowercase p	144	p	lowercase p reversed
17	q	lowercase q	145	q	lowercase q reversed
18	r	lowercase r	146	r	lowercase r reversed
19	s	lowercase s	147	s	lowercase s reversed
20	t	lowercase t	148	t	lowercase t reversed
21	u	lowercase u	149	u	lowercase u reversed
22	v	lowercase v	150	v	lowercase v reversed
23	w	lowercase w	151	w	lowercase w reversed
24	x	lowercase x	152	x	lowercase x reversed
25	y	lowercase y	153	y	lowercase y reversed
26	z	lowercase z	154	z	lowercase z reversed
27	[	left bracket	155	[	left bracket reversed
28	\	backslash	156	\	backslash reversed
29	]	right bracket	157	]	right bracket reversed
30	^	circumflex	158	^	circumflex reversed
31	_	underscore	159	_	underscore reversed

Numbers and Symbols (Block 2 and Block 6)

ScreenCode	Symbol	Description	ScreenCode	Symbol	Description
32		space	160		space reversed
33	!	exclamation point	161	!	exclamation point reversed
34	"	double quote	162	"	double quote reversed
35	#	hash/pound	163	#	hash/pound reversed
36	$	dollar-sign	164	$	dollar-sign reversed
37	%	percent-sign	165	%	percent-sign reversed
38	&	ampersand	166	&	ampersand reversed
39	'	apostrophe	167	'	apostrophe reversed
40	(	left parenthesis	168	(	left parenthesis reversed
41	)	right parenthesis	169	)	right parenthesis reversed
42	*	asterisk	170	*	asterisk reversed
43	+	plus-sign	171	+	plus-sign reversed
44	,	comma	172	,	comma reversed
45	-	hyphen-minus	173	-	hyphen-minus reversed
46	.	period	174	.	period reversed
47	/	forward slash	175	/	forward slash
48	0	zero	176	0	zero reversed
49	1	one	177	1	one reversed
50	2	two	178	2	two reversed
51	3	three	179	3	three reversed
52	4	four	180	4	four reversed
53	5	five	181	5	five reversed
54	6	six	182	6	six reversed
55	7	seven	183	7	seven reversed
56	8	eight	184	8	eight reversed
57	9	nine	185	9	nine reversed
58	:	colon	186	:	colon reversed
59	;	semi-colon	187	;	semi-colon reversed
60	<	less-than-symbol	188	<	less-than-symbol reversed
61	=	equals-sign	189	=	equals-sign reversed
62	>	greater-than-symbol	190	>	greater-than-symbol reversed
63	?	question-mark	191	?	question-mark reversed

Uppercase (Block 3 and Block 7)

ScreenCode	Symbol	Description	ScreenCode	Symbol	Description
64	`	backtick	192	`	backtick reversed
65	A	uppercase a	193	A	uppercase a reversed
66	B	uppercase b	194	B	uppercase b reversed
67	C	uppercase c	195	C	uppercase c reversed
68	D	uppercase d	196	D	uppercase d reversed
69	E	uppercase e	197	E	uppercase e reversed
70	F	uppercase f	198	F	uppercase f reversed
71	G	uppercase g	199	G	uppercase g reversed
72	H	uppercase h	200	H	uppercase h reversed
73	I	uppercase i	201	I	uppercase i reversed
74	J	uppercase j	202	J	uppercase j reversed
75	K	uppercase k	203	K	uppercase k reversed
76	L	uppercase l	204	L	uppercase l reversed
77	M	uppercase m	205	M	uppercase m reversed
78	N	uppercase n	206	N	uppercase n reversed
79	O	uppercase o	207	O	uppercase o reversed
80	P	uppercase p	208	P	uppercase p reversed
81	Q	uppercase q	209	Q	uppercase q reversed
82	R	uppercase r	210	R	uppercase r reversed
83	S	uppercase s	211	S	uppercase s reversed
84	T	uppercase t	212	T	uppercase t reversed
85	U	uppercase u	213	U	uppercase u reversed
86	V	uppercase v	214	V	uppercase v reversed
87	W	uppercase w	215	W	uppercase w reversed
88	X	uppercase x	216	X	uppercase x reversed
89	Y	uppercase y	217	Y	uppercase y reversed
90	Z	uppercase z	218	Z	uppercase z reversed
91	{	left brace	219	{	left brace reversed
92	|	pipe	220	|	pipe reversed
93	}	right brace	221	}	right brace reversed
94	~	tilde	222	~	tilde reversed
95		reserved	223		reserved

UI Characters (Block 4 and Block 8)

ScreenCode	Symbol	Description	ScreenCode	Symbol	Description
96		Transparent	224		reserved
97		Commodore symbol	225		Commodore symbol reversed
98		up arrow	226		up arrow reversed
99		down arrow	227		down arrow reversed
100		left arrow	228		left arrow reversed
101		right arrow	229		right arrows reversed
102		analog clockface	230		analog clockface reversed
103		cycle arrows	231		cycle arrows reversed
104	…	ellipsis	232	…	ellipsis reversed
105		diagonal stripes	233		diagonal stripes reversed
106		checkbox unchecked	234		checkbox unchecked reversed
107		checkbox checked	235		checkbox checked reversed
108		radio button unselected	236		radio button unselected reversed
109		radio button selected	237		radio button selected reversed
110		Utility close button	238		Memory chip icon
111		Utility title bar	239		Shift symbol
112	©	copyright symbol	240	©	copyright symbol reversed
113		checkmark	241		checkmark reversed
114		3 horizontal stripes	242		3 horizontal stripes reversed
115		tick track	243		tick track reversed
116		tick track nub	244		tick track nub reversed
117		tab corner	245		tab corner reversed
118		3 vertical stripes	246		3 vertical stripes reversed
119		Custom 1	247		Custom 10
120		Custom 2	248		Custom 11
121		Custom 3	249		Custom 12
122		Custom 4	250		Custom 13
123		Custom 5	251		Custom 14
124		Custom 6	252		Custom 15
125		Custom 7	253		Custom 16
126		Custom 8	254		Custom 17
127		Custom 9	255		Custom 18

---

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)

Constant	Value	Description
ct_text	0	Human readable text.
ct_appl	1	Application data, binary data.
ct_audio	2	Audio data, sound, music.
ct_image	3	Image data, pictures, graphics.
ct_video	4	Video data, animations, movies.

---

C64 OS Data Subtypes (CT_TEXT: Subtype Codes)

Constant	Value	Description
ct_pettxt	0	PETSCII encoded plain text.
ct_asctxt	1	ASCII encoded plain text.
ct_mtext	2	MText encoded markup text.
ct_email	3	Valid email address formatted text.
ct_weburl	4	Valid web URL formatted text.
ct_date	5	Date text in format YYYY-MM-DD.
ct_dattim	6	Date/time text in format YYYY-MM-DD HH:mm:ss
ct_fref	7	C64 OS serialized file reference formatted text.
ct_hexdec	8	Hexadecimal number formatted text.
ct_number	9	Valid number formatted text.
ct_tel	10	Valid telephone number formatted text.
ct_cal	11	C64 OS calendar event formatted text.
ct_html	12	HTML formatted text.
ct_xml	13	XML formatted text.

C64 OS Data Subtypes (CT_APPL: Subtype Codes)

Constant	Value	Description
ct_zip	0	PKZip formatted binary data.
ct_float	1	BASIC 5-byte floating point integer format.
ct_base64	2	base64 encoded data.
ct_gzip	3	GZip formatted binary data.
ct_uuenc	4	Unix-to-Unix encoded data.

C64 OS Data Subtypes (CT_AUDIO: Subtype Codes)

Constant	Value	Description
ct_raw	0	Raw PCM formatted audio data.
ct_aiff	1	Audio interchange file format data.
ct_wave	2	RIFF/Wave audio encoded data.
ct_sid	3	PSID-wrapped SID audio data.
ct_mod	4	Amiga module music encoded data.
ct_mp3	5	MP3 encoded audio data.
ct_midi	6	MIDI encoded music data.
ct_snd	7	SouND digital audio formatted data.

C64 OS Data Subtypes (CT_IMAGE: Subtype Codes)

Constant	Value	Description
ct_multc	0	C64 OS Multi-Color raw image data format.
ct_hires	1	C64 OS HiRes raw image data format.
ct_koala	2	Koala formatted image data.
ct_arts	3	Art Studio formatted image data.
ct_jpeg	4	JPEG formatted image data.
ct_gif	5	GIF formatted image data.
ct_4bit	6	GoDot 4-bit image formatted data.
ct_3icon	7	C64 OS 3x3 icon format.

C64 OS Data Subtypes (CT_VIDEO: Subtype Codes)

Constant	Value	Description
ct_hdx	0	C64 HiRes encoded video data.

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

Type	Filename	Description	Available
pointer	ptr.1351 mouse	Driver for 1351 and compatible mice in port 1.	v1.0
pointer	ptr.1351 port2	Driver for 1351 and compatible mice in port 2.	v1.01
pointer	ptr.c128 keypad	Driver for using C128 numeric keypad as mouse pointer input.	v1.0
pointer	ptr.joystick 1	Driver for using a standard joystick in port 1 for mouse input.	v1.0
pointer	ptr.joystick 2	Driver for using a standard joystick in port 2 for mouse input.	v1.0
pointer	ptr.koala pad	Driver for using a Koala Pad for proportional mouse pointer input.	v1.0
pointer	ptr.light pen	Driver for using a light pen for mouse pointer input.	v1.0
pointer	ptr.micromys 1	Driver for MicroMys/MouSTer mouse adapter in port 1.	v1.02
pointer	ptr.micromys 2	Driver for MicroMys/MouSTer mouse adapter in port 2.	v1.07

Joystick (Game) Drivers

Type	Filename	Description
joystick	joy.nes 2 player	Driver for 2 joysticks, with extensions for NES Controller Select/Start mod.
joystick	joy.nes 4 player *	Driver for 4 joysticks, with extensions for NES Controller Select/Start mod.

* Using the bombmania 4-player User Port adapter

Keyboard Drivers

Type	Filename	Description	Available
keyboard	kbd.c64	Keyboard driver for C64 built-in 66-key keyboard.	v1.07

Network Drivers

Type	Filename	Description	Available
network	nhd.slde.u6	Swiftlink @ $DE00 for Ultimate64/UltimateII+	v1.07
network	nhd.sldf.u6	Swiftlink @ $DF00 (default) for Ultimate64/UltimateII+	v1.07
network	nhd.sldf0.u6	Swiftlink @ $DF00 for Ultimate64/UltimateII+	v1.07
network	nhd.sldf8.u6	Swiftlink @ $DF80 for Ultimate64/UltimateII+	v1.07
network	nhd.slde.zi	Swiftlink @ $DE00 for ZiModem (Link232 Wifi, et al.)	v1.07
network	nhd.sldf.zi	Swiftlink @ $DF00 for ZiModem (Link232 Wifi, et al.)	v1.07
network	nhd.up24.zi	UserPort 2400 baud for ZiModem (C64Net, et al.)	v1.07

Realtime Clock Drivers

Type	Filename	Description	Available
realtime clock	rtc.ds3231 i2c	Driver for reading date/time from DS3231 Arduino module over User Port i2c bus.	v1.0
realtime clock	rtc.iec device	Driver for reading date/time from CMD HD, CMD FD, RAMLink, IDE64 and SD2IEC.	v1.0
realtime clock	rtc.manual	Driver that reads manually configured date/time from //os/settings/:time.manual.t	v1.0
realtime clock	rtc.ultimate	Driver for reading date/time from 1541 Ultimate II+ and Ultimate 64 over Ultimate Command Interface.	v1.0
realtime clock	rtc.tc64	Driver for reading date/time from TurboChameleon64.	v1.04
realtime clock	rtc.mmc64	Driver for reading date/time from the MMC64 Cartridge.	v1.04

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.

Device Name	Interface
CMD FD series disk drive	IEC bus
CMD HD series hard drive	IEC bus and RAMLink parallel cable
CMD RAMLink	Expansion Port
IDE64	Expansion Port
SD2IEC and uIEC/SD	IEC bus

Storage

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

Device Name	Interface
1541 disk drive	IEC bus
1571 disk drive	IEC bus
1581 disk drive	IEC bus
CMD FD series disk drive	IEC bus
CMD HD series hard drive	IEC bus and RAMLink parallel cable
CMD RAMLink	Expansion Port
IDE64	Expansion Port
SD2IEC and uIEC/SD	IEC bus
1541 Ultimate II+	IEC bus
Ultimate 64	Virtual IEC bus
pi1541	IEC bus
VICE FS	Virtual

Pointer Input

Device Name	Notes
Commodore 1351 Mouse	Analog
Commodore 1350 Mouse	Digital
Joystick	Digital (no right-click)
Lightpen	Analog (no right-click)
C128 Keypad	Digital
MicroMys Mouse	Analog (mouse wheel)
MouSTer Mouse	Analog (mouse wheel)

Memory

Device Name	Capacity
Commodore 1700 REU	128KB
Commodore 1764 REU	256KB
Commodore 1750 REU	512KB
CLD 1750 Clone REU	512KB
CMD 1750XL REU	2MB
TurboChameleon 64 REU	Up to 16MB
VICE 17xx REU	Up to 16MB
Ultimate 64 17xx REU	Up to 16MB
1541 Ultimate II+ 17xx REU	Up to 16MB

Network Hardware

Device Name	Interface	Network Interface
C64Net Wifi	User Port	Wifi
C64 WIFI MODEM (RetroRewind)	User Port	Wifi
Ultimate64	Emulated Swiftlink	Wifi / Ethernet
Ultimate II+	Emulated Swiftlink	Wifi / Ethernet
Link232 Wifi (Cartridge)	Swiftlink	Wifi
Swift-L/Swift-T (Internal)	Swiftlink	Wifi

---

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

Module	Description
file	File reading/writing. Clipboard. File reference conversion.
input	Produces and queues keyboard, mouse, and game controller input events.
math	16-bit multiplication and division routines.
memory	Paged memory allocator. Malloc and Free. REU support routines.
menu	Implements the C64 OS menu and status bars and all their functionality.
screen.cpu	Screen compositing routines. Low-level contextual drawing system.
screen.reu	REU-assisted screen compositing routines. Low-level contextual drawing system.
service.cpu	Application, Utility and shared library loading with Loader. IRQ service routine.
service.reu	Application, Utility and shared library loading with Switcher. IRQ service routine.
string	String manipulation routines. Base conversion routines.
timers	Enqueues timer structures. Processes timers. Asynchronous message passing.
toolkit	Support routines for toolkit environment, event passing and hitting detection.

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

Library	Description	Available
calendar.lib	Standard calendar routines, such as leap year and day of week.	v1.0
checksum.lib	Provides standard checksum routines; CRC8, CRC16, CRC32.	v1.02
cmp.lib	Comparison routines for directory and other sorting.	v1.0
cnp.lib	Commodore Network Protocol packet library.	v1.07
crash.lib	Crash handler that loads the crashscreen when an exception is unhandled.	v1.0
datetime.lib	String to integer and vice versa date/time conversion routines.	v1.0
dir.lib	Directory loading and parsing. Supports all C64 OS supported devices.	v1.0
fcopy.lib	File copy for a single file between any two file references. Supports REU.	v1.0
flock.lib	File lock routines for 1541, 1571, 1581, CMD HD, FD, RAMLink and IDE64.	v1.0
fname.lib	Useful routines for working with filenames, such as extracting an extension.	v1.04
gfx.lib	Routines for supporting status bar raster split when graphics data is available.	v1.0
grab.lib	Library for grabbing and saving a screenshot of the standard UI.	v1.0
i2c.lib	Library that implements the I2C bus over the User Port. Two versions exist.	v1.0
iec.lib	Library that scans the IEC bus and builds the detected devices table.	v1.0
memory.lib	Memory management routines that extend the KERNAL memory module.	v1.05
network.lib	Library for network management and coordination.	v1.07
path.lib	Library with routines for standard path and file reference manipulation.	v1.0
places.lib	Library of routines to load, read and manage recents and favorites.	v1.0
qbasic.lib	Standard library to quit to BASIC, with Fast Reboot support.	v1.05
qsort.lib	Quick Sort routines paired with cmp.lib. Used by dir.lib to sort directories.	v1.0
rec.lib	Routines for detecting presence and capacity of 17xx REU.	v1.0
sidplay.lib	Library for loading PSID format SID music. Fetches metadata and controls playback.	v1.0
tarea.lib	Library for supporting multi-line text editing in Toolkit.	v1.06
utils.lib	Builds and links the Utilities menu from //os/settings/:utilities.m definitions file.	v1.0
wrap.lib	Softwraps text. Builds a linked-line table used by the TKText Toolkit class.	v1.0

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

Configuring the I2C Bus

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:

File	Data Lines	CIA Port B	Compatibility
i2c.lib.ver_cd.r	C and D	bits 0 and 1	GEOS, but not RS-232
i2c.lib.ver_ef.r	E and F	bits 2 and 3	RS-232, but not GEOS

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

File	Description
build.t	Lists the C64 OS build number. Toggles with versionn number in About C64 OS Utiliity.
components.t	Lists the components loaded when booting in Default Mode.
components1.t	Lists the components loaded when booting in Safe Mode.
components2.t	Lists the components loaded when booting in Custom Mode 1.
components3.t	Lists the components loaded when booting in Custom Mode 2.
components4.t	Lists the components loaded when booting in Developer Mode.
config.t	CPU busy indicator status, global keyboard shortcuts, and default status bar mode.
drivers.t	Lists the drivers and their arguments for each of the supported driver types.
docs.path.t	File reference to "Documents" standard place.
games.path.t	File reference to "Games" standard place.
homebase.t	Stores the last accessed Homebase Application: App Launcher or File Manager.
memory.t	Specifies memory Utility. REU banks for fast app switching. Memory display format.
modules.t	Specifies the KERNAL modules to be loaded by the booter.
mouse.t	Stores the mouse pointer, color, handedness, acceleration and double click speed.
music.path.t	File reference to "Music" standard place.
pictures.path.t	File reference to "Pictures" standard place.
system.t	Specifies the name of the system directory for this installation of C64 OS.
theme.cus.t	Defines the customized theme colors selected in the Themes Utility.
theme.day.t	Specifies the colors for the Daylight color theme.
theme.mid.t	Specifies the colors for the Midnight color theme.
theme.t	Specifies the currently active theme colors.
time.manual.t	Holds a static date/time string that is read and written by the rtc.manual driver.
time.t	Specifies the time Utility. 12/24H format, and menu bar clock settings.
tkclasses.t	Lists the non-relocating Toolkit classes loaded by the booter.
utilities.m	Menu definitions file read by utils.lib to build the Utilities menu.
version.t	Lists the C64 OS version number. Displayed in About C64 OS Utiliity.

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.

---

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.

Directory/File	—	Description
c64os		The main C64 OS booter.
//os/		The C64 OS system directory.
applications/		Installed Applications.
Hello World		Bundle for Application "Hello World".
booter		KERNAL booter.
c64tools/		Useful non-C64-OS-native programs
calendar/		System wide calendar events.
2019-07/		Calendar events for July 2019.
4		Calendar events data file for July 4th 2019.
charsets/		Character sets.
boot.charset		Boot screen's logo character set
main.charset		Main character set; letters, numbers, symbols.
ui.charset		User interface character set
clipboard/		Current clipboard and additional clippings.
0.t		Current clipboard data type and size.
0.d		Current clipboard data content.
desktop/		App Launcher's multiple desktops.
1/		Aliases on desktop 1.
Hello World		Alias to application "Hello World".
1.p		Background PETSCII art desktop 1.
2/		Aliases on desktop 2.
2.p		Background PETSCII art desktop 2.
docs/		Documentation
drivers/		Hardware drivers
h/		Programming headers
icons/		Library of standard icons.
kernal/		C64 OS KERNAL modules.
library/		Components and libraries.
loaders/		Datatype loaders, by file type and extension.
savers/		Datatype savers, by file type and extension.
pointers/		Mouse pointers
prg aliases/		Aliases to traditional C64 software.
s/		Programming macros and constants.
ker/		C64 KERNAL ROM programming constants.
t/		Data type definitions, by filename extension.
screengrabs/		Screengrab saves screenshots to here.
services/		Special service applications.
App Launcher		An application launching, desktop-like environment.
File Manager		A file management application.
settings/		System settings. Globally saved Utility state files.
temporary/		Temporary files are scratched during boot up.
tk/		Toolkit class files and headers.
utilities/		Installed Utilities.
Calculator		Executable file for Utility "Calculator".
Today		Executable file for Utility "Today".

---

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.

Class	Type	Description	Available
TKObj	Core	The root class from which all others descend.	v1.0
TKView	Core	The root view from which all class that handle events descend.	v1.0
TKCPUU	Relocatable	CPU usage visualization.	v1.05
TKCtrl	Core	The abstract class from which all interactive controls descend.	v1.0
TKButton	Core	Serves as a push button, cycle button, checkbox or radio button.	v1.0
TKDatePick	Relocatable	A date picking class. Embeds three managed cycle buttons for date parts.	v1.0
TKInput	Relocatable	A single line text input class, with selections, cut, copy and paste.	v1.0
TKRating	Relocatable	A 5-star rating control. Takes customizable on and off characters.	v1.0
TKSBar	Core	A horizontal or vertical scroll bar with arrow buttons and a draggable nub.	v1.0
TKTimePick	Relocatable	A time picking class. Embeds cycle buttons for time parts. 12H and 24H mode.	v1.0
TKTimer	Relocatable	Shows 3 double-high time segments. Has timer and stopwatch mode.	v1.0
TKDirInfo	Relocatable	Shows a directory info bar, number of items and available capacity.	v1.0
TKFileMeta	Relocatable	Shows multi-line file metadata: file size, date modified, and CBM file type.	v1.0
TKIcon	Relocatable	Renders an icon of custom chars, 1x1, 2x2, 3x3, etc. with click event.	v1.0
TKLabel	Core	A single line text label with left, right, and center justification.	v1.0
TKLabelBox	Relocatable	Adds a label and containing box around its content views.	v1.0
TKList	Relocatable	A list with delegate methods for retrieving row count and content.	v1.0
TKTable	Relocatable	A multi-column list with delegate methods for retrieving cell count and content.	v1.0
TKPBar	Relocatable	Shows an interactive path reflecting the path of the open file reference.	v1.0
TKPlaces	Relocatable	Shows a list of devices and embeds a TKList for recents and favorites.	v1.0
TKRAMU	Relocatable	Main memory usage visualization.	v1.05
TKREUU	Relocatable	REU memory usage visualization.	v1.05
TKScroll	Core	An class that manages two TKSBars plus one content child that scrolls.	v1.0
TKTCols	Relocatable	Adds resizable column headers and coordinates with a TKTable content view.	v1.0
TKTArea	Relocatable	A multi-line text editing class. Supports soft wrapping up to 255 characters.	v1.06
TKText	Relocatable	A multi-line text display class. Supports soft wrapping and MText rendering.	v1.0
TKSplit	Core	An organization class that divides an area horizontally or vertically.	v1.0
TKTabs	Core	An organization class that presents a set of tabs.	v1.0

---

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.

Key	Boot Mode
1	Safe Mode (1)
2	Custom Mode (2)
3	Custom Mode (3)
4	Developer Mode (4)

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.

Symbol	Meaning	Notes
; (semi‑colon)	Comment	Lines that begin with a semi-colon are skipped. These can be used for comments.
# (hash)	Comment	Lines that begin with a hash are skipped. These can be used for comments.
CR (\r, $13)	Visual Spacing	Blank lines (no characters except a carriage return) are skipped. These can be used for spacing, for readability in the file.
l	Load	Component is loaded into memory, at the address found in the component's PRG load address. These components are permanently left in memory.
r	Run	Component is loaded into memory, at the address found in the component's PRG load address, and immediately run. These components are temporary.
d	Defer	Component is loaded into memory, at the address found in the component's PRG load address. Running the component is deferred until the components file is closed.
m	Modules	This code is not followed by a filename, but by a number. This code is optional, and if present selectes an alternative modulesX.t file to be processed during boot.

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.

Symbol	Meaning	Notes
; (semi‑colon)	Comment	Lines that begin with a semi-colon are skipped. These can be used for comments. Comment lines in a modules file may not exceed 32 characters.
CR (\r, $13)	Visual Spacing	Blank lines (no characters except a carriage return) are skipped. These can be used for spacing, for readability in the file.
*	Always	A module marked with an asterisk is always loaded in.
+	REU‑only	A module marked with a plus is only loaded if an REU has been detected.
-	CPU‑only	A module marked with a minus is only loaded if an REU is not available.

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: Apr 16, 2025