C64 OS USER'S GUIDE

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

How do I purchase a copy of C64 OS?

You can purchase a copy of C64 OS right here on C64OS.com. Choose whether you want the Starter Bundle (16 MB System Card) or the Standard Bundle (64 MB System Card), click the buy now button and you can pay using PayPal secure online payments.

No PayPal account required

You do not need a PayPal account to pay with PayPal, you can pay using a credit card. The beauty of PayPal is that C64OS.com never gets access to your credit card information. We don't store any sensitive information, because we don't collect any sensitive information.


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

A licensed copy of C64 OS v1.0 includes:

  • Access to the 3,500 word online Getting Started Guide
  • Access to the complete 75,000 word online User's Guide
  • A 42-page full-color professionally printed User's Guide Supplement
  • A pre-installed copy of C64 OS v1.0 on a System Card (16 MB or 64 MB SD Card)
  • An installation archive and install tools for C64 OS v1.0 for other storage media
  • App Launcher, File Manager, C64 Archiver, 3 additional Applications and over 25 Utilities, plus 10 KERNAL modules, 12 Drivers, 18 Libraries, 24 Toolkit classes, and 8 additional Tools
  • A high-quality promotional C64 OS vinyl sticker
  • Access to ongoing patches, bug fixes and feature updates to C64 OS v1.0
  • 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 64 MB System Card also comes with these bonuses:

  • A pre-installed CMD HD hard drive image of C64 OS v1.0 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 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 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.


What does C64 OS cost?

The C64 OS software package costs $59 (Canadian dollars) for the Starter Bundle (16 MB System Card), or $64 (Canadian dollars) for the Standard Bundle (64 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 allows you to use the official C64 OS System Card as a primary mass-storage device, and provides plenty of free space for future content. The larger System Card also comes with some bonus content, including a pre-installed CMD HD hard drive image to make it easy to get started with C64 OS on VICE.


Is C64 OS compatible with VICE?

Yes. C64 OS is compatible with the latest versions of VICE with support for the CMD HD. 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?

No. Unfortunately, neither theC64 mini or Maxi provides access to the one minimum requirement to run C64 OS. Although the mini and Maxi run VICE, the version they come with does not have support for a virtual CMD HD.

Additionally, theC64 mini and Maxi do not have physical IEC ports, and therefore they cannot be connected to a real SD2IEC or CMD HD.


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 version 1.0 includes a library that is 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 the SID music as it runs, is not standard. 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.

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


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.


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:


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

//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: an SD2IEC

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 fixed-length 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 an SD2IEC. 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 the default device and change into the directory where the CAR file is located. Run the program. It reminds you that it can only be used on an SD2IEC and asks for the name of the CAR file. Enter the name, 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.


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

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.
reserved 8 reserved
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 Hi-Res 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/:drivers.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 the //os/settings/:drivers.t file.

Pointer Drivers

Type Filename Description
pointer ptr.1351 mouse Driver for 1351 and compatible mice.
pointer ptr.c128 keypad Driver for using C128 numeric keypad as mouse pointer input.
pointer ptr.joystick 1 Driver for using a standard joystick in port 1 for mouse input.
pointer ptr.joystick 2 Driver for using a standard joystick in port 2 for mouse input.
pointer ptr.koala pad Driver for using a Koala Pad for proportional mouse pointer input.
pointer ptr.light pen Driver for using a light pen for mouse pointer input.

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

Realtime Clock Drivers

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

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. 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 Application, Utility and shared library loading. 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.

NOTE: The booter chooses to load either screen.cpu or screen.reu depending on whether an REU was detected earlier in the boot process.


VII. 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
calendar.lib Standard calendar routines, such as leap year and day of week.
cmp.lib Comparison routines for directory and other sorting.
crash.lib Crash handler that loads the crashscreen when an exception is unhandled.
datetime.lib String to integer and vice versa date/time conversion routines.
dir.lib Directory loading and parsing. Supports all C64 OS supported devices.
fcopy.lib File copy for a single file between any two file references. Supports REU.
flock.lib File lock routines for 1541, 1571, 1581, CMD HD, FD, RamLink and IDE64.
gfx.lib Routines for supporting status bar raster split when graphics data is available.
grab.lib Library for grabbing and saving a screenshot of the standard UI.
i2c.lib Library that implements the I2C bus over the User Port. Two versions exist.
iec.lib Library that scans the IEC bus and builds the detected devices table.
path.lib Library with routines for standard path and file reference manipulation.
places.lib Library of routines to load, read and manage recents and favorites.
qsort.lib Quick Sort routines paired with cmp.lib. Used by dir.lib to sort directories.
rec.lib Routines for detecting presence and capacity of 17xx REU. Used by memory KERNAL module.
sidplay.lib Library for loading PSID format SID music. Fetches metadata and controls playback.
utils.lib Builds and links the Utilities menu from //os/settings/:utilities.m definitions file.
wrap.lib Softwraps text. Builds a linked-line table used by the TKText Toolkit class.

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.


VIII. 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
components.t Lists the components that are loaded by the booter before everything else.
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.


IX. SID Music

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

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.

Notes for SID Relocation

Available Zero Page for SIDs in C64 OS: $B0, $B1, $B2, and $B3

Recommended Relocation Start Address: $2000

sidplay.lib.r does not support NMI-driven digis in SID music.


X. 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.
pointers/   Mouse pointers
prg aliases/   Aliases to traditional C64 software.
s/   Programming macros and constants.
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".

XI. Toolkit Classes

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

Table of Contents



This document is subject to revision updates.

Last modified: Sep 20, 2022