Written and Maintained by Gregory Nacu

C64 OS: USER'S GUIDE

Last modified: Sep 06, 2019

What is an OS?

operating system

Noun. Computers. Abbreviated: OS.
Software designed to control the hardware of a computer system in order to allow users and application programs to make use of it.
Free Dictionary

An OS provides software services that make a computer work. The Commodore 64 comes with a simple operating system that is split into two or three major components. The KERNAL and BASIC come on ROM chips that are installed inside the computer. These components include the software necessary to use the keyboard and screen, and to load software from a tape or over the IEC serial bus, among other things. They lack the ability to manage a disk drive or harddrive, however. For this, a third component is required. Each drive connected to the serial bus provides its own disk operating system.

An OS must also provide some form of user interface, a means for the user to interact with the computer. In the Commodore 64 the user interface consists of a full screen editor, which allows the user to input typed commands. The commands are interpreted by BASIC. Direct mode BASIC commands function as a front end user interface to the functionality provided by the KERNAL. It is a simple system, but it works. It allows the user to load and run other programs, and provides those programs with a suite of useful routines.

The C64 READY Prompt. The KERNAL and BASIC ROMs.
(Image of the chips is symbolic only. Chip numbers may not be accurate.)

Usually an operating system provides services that a program may use so that the program does not have to implement all hardware control from scratch. However, a Commodore 8–bit computer has fairly simple hardware, and a very limited amount of RAM. It is quite common for a game or demo to completely patch out the BASIC and KERNAL ROMs, leaving the maximum amount of memory available. These programs must then reimplement the routines for controlling the hardware they need. Programs such as these do not run on top of an OS, they simply implement everything, keyboard input, serial bus protocols and more, from scratch. People who want to do this, are not the kind of people who want an operating system getting in the way.

On the other hand, there are thousands of programs that keep the KERNAL and BASIC patched in, and rely on their routines to make development of the program easier. It is for these programmers, and for these types of programs, that an operating system is helpful.

Why have another OS?

The KERNAL and BASIC ROMs are an OS, but they were created a long time ago, when computer users had different expectations. One area where the C64's built–in OS is the most primitive is its user interface. Virtually every program is required to create its own. And because of the difficulty of creating a rich and interactive user interface, they are instead usually quite simple and limited. Many C64 programs present a menu of options on the screen, which can be selected from by pressing a key on the keyboard. Often these made use of PETSCII graphics, which are part of the standard character set.

Unzip 64. Dir Master. SIDPlay 64.

The reason to have another OS, on top of or instead of the KERNAL and BASIC ROMs, is to provide a better user interface to meet the needs and expectations of more modern users, and to provide better and more modern services to support the development of new applications.

There are some downsides to OSes. They add overhead and take up precious memory. They abstract the developer and the user away from the hardware. From a hobbyist or hardware enthusiast standpoint, abstracting the hardware hides what is unique and special about that computer. So a more modern C64 operating system must thread the needle, finding the correct balance of small footprint, speed and usefulness, but also maintain hackability, simplicity and character.

I believe in the ability of an OS to unleash the power of a Commodore 64 or 128. But I am aware of the potential downsides. I want C64 OS to keep the C64's quirky and spunky nature, but at the same time, I want a platform for C64 applications that gives them a solid jumping off point to allow them, with less development effort, to reach new heights.


What does C64 OS provide?

Core Features

  • Mouse–based UI
  • Graphical UI character set
  • Menu bar
  • Status bar
  • Built–in split screen mode
  • Advanced mouse and keyboard event system
  • Event–driven execution model
  • Universal cut, copy and paste
  • Application and Utility at the same time
  • Object–oriented widget toolkit
  • Customizable color themes
  • Textfile–based configuration
  • Screen layer compositor
  • Dynamic memory allocation
  • String, Math and File libraries
  • Timers
  • Exception handling
  • Runtime module lookup

Core Modules

  • memory
  • input
  • string
  • math
  • timers
  • file
  • screen
  • service
  • menu
  • toolkit

System Programs

  • booter
  • loader
  • drives
  • exceptions
  • rtc

Service Applications

  • App Launcher
  • File Manager

Applications

  • Gallery
  • Ultimate Video
  • Ultimate Audio
  • NES Tester
  • TestGround
  • in progress…

Utilities

  • About This 64
  • About This App
  • About C64 OS
  • Data Operators
    • Colors
    • Date
    • File
    • Files
    • Find
    • Text
  • Mini Applications
    • Clipboard
    • Event
    • Help
    • MemEdit
    • Memory
    • Notes
    • Peek
    • Reminders
    • Time
    • Today
  • System Configuration
    • Settings
    • Themes
    • WiFi
    • Mouse
    • Drives
    • Utilities

C64 OS User Interface

C64 OS is an immersive computing environment. Once you boot into C64 OS, you won't have to shut down or restart your computer until you are finished using your computer for the day.

As soon as C64 OS has booted, the mouse pointer will be active, allowing you to click on buttons and menus around the screen to choose what to do next.

C64 OS is always running one primary application, which is referred to as the application. There are two essential applications, App Lancher and File Manager. Because of their importance to the system they are referred to as service applications. Whichever one you used last, C64 OS will automatically launch into that application at boot up.

The Menu Bar

The menu bar is a central user interface element of C64 OS. The application defines the menus which appear at the top of the screen. Menus are pull–down and hierarchical. To activate the menus, depress the primary mouse button while the cursor is over the menu bar. As you roll the mouse over a top–level menu option, its submenu will drop down automatically. If you roll onto another a menu option, the previous submenu will automatically snap shut. C64 OS supports multiple levels of nested submenus. To help indicate which menu option is currently active they highlight as the mouse rolls over them. Release the mouse button to select the active menu option and send a menu action message to the application.

Each menu option can be assigned a unique keyboard shortcut, which consists of a combination of a single letter, number or symbol plus a combination of the modifier keys COMMODORE, CONTROL and SHIFT.

Hacker's Note

An application defines its menus in a human readable text file. The file is called menu.m and is stored in the root of the application's bundle. This file can be edited in a text editor to completely change the menu hierarchy. Menu nesting can be changed, menu labels (including customization for language), keyboard shortcuts, and spacers can all be changed, without needing to reassemble the application's code. The application reads in its menu definitions when it is first opened.

Easter eggs or beta features of an app can be put in that are only accessible by a menu action that is omitted from the menu definition file. The feature can be accessed later, by knowing what menu action to add.

The leftmost option on the menu bar is managed by the system, and is persistent regardless of what additional menus are supplied by the application. This menu is customizable, and allows you to launch a utility from within any other application.

Labeled diagram of the menu bar features.

On the right side of the menu bar is the system time. The system time can be customized for 12 or 24 hour mode. The colon can be configured to blink with seconds or remain solid. There is an option to disable the display of the system time altogether, which gives more horizontal room for top–level menus. A double–click on the system time opens the Today utility.

The entire menu bar may be hidden or shown, either programmatically (by the application), or with the global system keyboard shortcut: CONTROL+SPACE

Hiding the menu bar opens up more screen real estate, and applications can adapt to make use of the extra space by reference to internal system flags and notifications.

Hacker's Note

The utilities menu is parsed from the file utilities.m in the system settings folder. It is structured like any other menu.m file provided by an application. It may have spacers, customized keyboard shortcuts and hierarchical nesting. Its only limitation is that it must be constrained to a single root menu, which must have a 1–character title.

Any action code of a menu item will be sent to the application when that item is selected. However, the action code binary value $01 is reserved for launching utilities. The menu system intercepts this action code and does not pass it to the application. Instead it calls the system service routine to launch a utility that bears the same name as the menu item's label text. This special $01 action code may also be used in regular application menus.

The Status Bar

A second central user interface element of C64 OS is the status bar. The status bar runs along the length of the bottom of the screen, and always floats above other content. The status bar has three modes. Modes can be cycled through by clicking on the left half of the status bar.

Disk Status Mode

In disk status mode, the most recently read status is displayed, prepended by the device number of the drive the status was read from.

This status is automatically updated by the system, and applications do not need to opt–in to support it. All applications which rely on the C64 OS file module for disk access will automatically be integrated with this status.

Open File Mode

An application may have a file open, which is being read or edited. If an application is opened in response to the user opening a document file, the file to open upon first launch is indicated by a system property. Alternatively, while the application is already open the user may use the Files utility to select a file to open. The application uses this open file reference to save changes back to the correct file.

The status bar, in open file mode, displays the path to the open file. It is in the C64 OS serialized file reference format: device#:partition#:filename:path

If there is no currently open file, the status bar will automatically skip this mode and cycle into the next available mode.

Application Custom Mode

Each application may opt to support custom status content. An application supports custom status mode by returning a pointer to custom status content in response to a status message request. If the application does not support custom status content, it can return a null pointer, and the status bar will automatically skip this mode and cycle to the next available mode.

An application's status may consist of a null–terminated string of PETSCII characters. The system sets the text color to match the status bar color, and will display up to a maximum of 40 characters. The application can change the status message at any time and notify the system that it needs to redraw the status bar.

Applications may use this to display information such as: number of selected items in a list, number of lines or words in a text file, application copyright info, etc.

Labeled diagram of the status bar features.

When in disk status mode or open file mode, the right side of the status bar shows a memory chip icon followed by the number of currently free pages of memory. (A page is a page–aligned contiguous block of 256 bytes.) A double–click on the available memory indicator opens the Memory utility.

The entire status bar may be hidden or shown, either programmatically (by the application), or with the global system keyboard shortcut: COMMODORE+CONTROL+SPACE

Hacker's Note

Global system keyboard shortcuts are defined in the human readable text–based settings file: config.t, found in the system folder's settings folder. These settings are read in by the booter when C64 OS is first launched.

Split Screen and Bitmap Mode

C64 OS's primary UI is based on the VIC-II's text mode. A RAM–based character set enables custom visual elements to be used to build up a graphical user interface. The VIC-II's text mode is incredibly fast, which is why it is used in arcade games that need to provide fast and smooth full–screen scrolling.

However, there are times when an application needs to display bitmapped data. An obvious example may be to show a picture, such as in the example above. At a very low–level, C64 OS's interrupt handler, event distribution model and screen compositor all work together to provide split screen mode.

Split screen mode allows the top portion of the screen to display the C64 OS primary UI, while the bottom portion of the screen displays custom bitmap data in either Hires or Multi–Color mode. The split must fall between the end of one text row and the start of the next. The application may programmatically set the split position allotting anywhere from the 1 to 23 screen rows to the bitmap portion.

The user may adjust the the split position manually by dragging the status bar up from the bottom of the screen. The status bar always displays at the bottom of the C64 OS UI portion of the screen.

In addition to split screen mode, the user may toggle between fully in the C64 OS primary UI and fully in the bitmap mode. These two modes can be toggle with the global system keyboard shortcut: COMMODORE+←

In order for split screen or bitmap mode to be activated, special system properties must be configured to point to bitmap and color data buffers, and indicate the format of the data. If these properties change to indicate that bitmap data is no longer available, the system will automatically switch out of bitmap mode and snap the split screen mode shut, moving the status bar back down to the bottom of the screen.

Note

Split screen and bitmap mode cannot be used simultaneously with a C64 OS utility. Due to memory constraints, utilities are loaded into the bitmap memory area. Attempting to open a C64 OS utility while split screen or bitmap mode is active will result in toggling out of bitmap mode and split screen being shut automatically.

Applications and Utilities

In C64 OS, there is always one application running, and there may additionally be one utility running at the same time. The application runs in full screen and claims the bottom–most screen layer and bitmap mode.

All installed applications are found in the system folder's applications folder. Every application consists of a folder, named for the application, which contains its executable code, menu definitions file, config files and other external resoures. When an application is running, it has a reference back to its own bundle allowing it to retrieve additional resources, or save state and settings.

Note

To install a third–party application, its bundle folder must be copied to the system's applications folder. To uninstall an application, its bundle folder can be deleted. Because an application's resources are all contained within the bundle, nothing will be left behind after deleting an application.

The application provides the menu definitions which are used by the system to produce the menus in the menu bar. Selecting an available option from a menu, or triggering its keyboard shortcut, sends the menu's action as a message command to the application.

An application may programmatically open a utility, and can also send it a message to process immediately upon opening. A utility renders inside a floating, movable panel. By default utilities pass on mouse and keyboard events they don't handle themselves to the application. However, a utility may prevent mouse and keyboard events from passing through its layer. A utility may also declare itself modal to disable the application's menus.

The Today utility. The Colors utility.

A utility has a title bar which runs partway across the top of its floating panel. The utility shows its name and may be dragged around the screen by its title bar. Utilities can be dragged anywhere, including partially off the left, right or bottom edges of the screen. When the menu bar and status bar are visible, they will prevent the utility from being dragged behind them.

Many utilities are designed to perform a generic function common to different applications. Applications are expected to and should rely on utilities to implement these common functions. Some examples include, picking a color, picking a date, picking a file, modifying, searching and replacing text, and so on.

Utilities are designed to be fast and seamless to open, use, and close. If a utility is already open when a new one is called to open, the current utility will automatically close. Utilities automatically store their position and state when they are closed, and automatically restore that position and state when they are opened again. Some utilities store their state and position globally, but others store this information on a per application basis. Generally speaking, utilities classified as "data operators" will save their state on a per application basis, with some exceptions.

Hacker's Note

A utility's state data is stored in binary format in a file which matches the name of the utility and has the file extension ".i". Thus, the calculator's state file is Calculator.i. Utilities which store their state globally store their state file in the system folder's settings folder. Utilities which store their state uniquely per application, store their state file in the root of the application's bundle.

State files present some cool hacking opportunities. Otherwise, if a utility ever fails to load or exhibits strange behavior, especially in one app but not in another, the state file can be deleted. All utilities automatically reconstruct their state from internal defaults.

While a utility is open it can send messages to the application. Applications can attempt to send messages to a utility, even if the utility does not respond to the message. The power of this messaging system is that applications and utilities are loosely coupled. Different applications may handle the messages from one utility in different ways. And different utilities may handle the same messages from an application in different ways.

Toolkit and Color Themes

Toolkit is an object–oriented suite of user interface elements that C64 OS applications and utilities can use to build powerful and consistent user interfaces with a minimal investment of code and development time.

Toolkit UI widgets draw themselves using a color palette theme defined for the whole system. Applications which use the standard widgets will automatically adopt the color theme that has been defined by the user. Toolkit defines 20 interface element states, which the toolkit objects adopt. C64 OS includes a Themes utility, which allows the user to visually customize the appearence of the operating system.

The Themes utility.
TODO: Replace with real screenshot

Customizable Toolkit User Interface Elements

  • Screen Border
  • Screen Background
  • Floating Panel Background
  • Menu and Status Bar
  • Menu Highlight
  • Display Text
  • Strong Text
  • Emphasis Text
  • Selected Text (rvs)
  • Button
  • Default Button
  • Scroll Bar Foreground
  • Scroll Bar Background
  • Disabled Control
    (disabled menu option, button, tab, etc.)
  • Text Field
  • Text Field In Focus
  • Tab Focused
  • Tab Blurred
  • Column Header

Universal Cut, Copy and Paste

The power of an operating system, in part, comes from the ability for applications to exchange data. This is accomplished partially through loosely coupled message passing between an application and a utility, while both are open at the same time. However, it is also useful to be able to transfer data from one utility to another, or from one application to another. To do this the data must be copied to an intermediate temporary holding place.

This temporary holding place is called the clipboard.

C64 OS provides system routines that allow applications and utilities to very easy transfer data to and/or from the clipboard. When data is tranfered to the clipboard the source program specifies the data type using C64 OS's data type system. The size of the data is recorded automatically.

An application or utility may, at any time, use standard system routines to transfer data in from the clipboard. Before doing so they may check the size of the data and confirm its data type. Many applications will reject an attempt to read data in from the clipboard if its data type is unrecognized or unsupported. In other cases the application may vary its response, performing different behaviors for different types of data.

The Clipboard utility.
TODO: Replace with real screenshot

C64 OS includes a Clipboard utility which allows the user to preview the current contents of the clipboard, and manage up to 8 clippings. Clippings let the user save common pieces of information so they can be easily pasted again in the future.

A well behaving C64 OS application or utility should try to make as much use of the clipboard as possible in order to increase the probability of unintended but useful interconnections.


C64 OS System Folder

In C64 OS, by design, all system code, components, resources, applications and utilities are contained within a single folder on a single device. There may be more than one instance of a C64 OS environment on the same media. Each must be contained in its own system folder. A system folder must be in the root folder of the partition.

A system folder may have any name. To be a valid bootable system folder its main config file must have the system folder's name specified.

While running C64 OS, uninstalled applications, documents, media files (pictures, movies, music) and more may be distributed across other partitions and devices. Applications can work with content and media files outside of the system folder.

Folder/File Description
//os/   The root file system folder.
applications/   Installed applications.
Sample App/   Application bundle for app "Sample App".
main.o   Application main executable file.
menus.m   Application menus definition file.
Today.i   Binary state save for utility "Today".
calendar/   System wide calendar events.
2019-07/   Calendar events for July 2019.
4   Calendar events data file for July 4th 2019.
charsets/   Partial character sets.
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. Background images for each desktop.
1/   Aliases on desktop 1.
Sample App   Alias to application "Sample App".
2/   Aliases on desktop 2.
3/   Aliases on desktop 3.
4/   Aliases on desktop 4.
5/   Aliases on desktop 5.
docs/   Documentation
h/   Programming headers
pointers/   Mouse pointers
s/   Programming macros and constants.
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.
Calculator.i   Global binary state save for utility "Calculator".
config.t   System folder name, system–wide keyboard shortcuts.
homebase.t   Last accessed homebase application.
mouse.t   Mouse pointer, speed, double–click speed, colors and handedness.
toolkit.t   Toolkit settings, color theme.
utilities.m   Utilities menu definition file.
tk/   Toolkit class files and headers.
utilities/   Installed utilities.
Calculator   Executable file for utility "Calculator".
Today   Executable file for utility "Today".
booter   C64 OS booter. Load and run from BASIC.
bootscreen.p   C64 OS PETSCII boot up screen.
drives.o   Drive detection boot module.
exceptions.o   Exception handling system module.
file.o   File KERNAL module.
input.o   Input KERNAL module.
loader.o   Application loader. System program.
lookuptable.o   KERNAL module lookup table.
math.o   Math KERNAL module.
memory.o   Memory KERNAL module.
menu.o   Menu KERNAL module.
rtc.o   RTC configuration boot module.
screen.o   Screen KERNAL module.
service.o   Service KERNAL module.
string.o   String KERNAL module.
timers.o   Timers KERNAL module.
toolkit.o   Toolkit KERNAL module.
utilities.o   Utilities menu configuration boot module.

In the next section C64 OS applications and utilities are discussed in depth. Their features and use–cases are explored.


Next Section: C64 OS Apps and Utils

Table of Contents



This is document is continually updated.

Refer to the last modified date at the top of this document for the most recent changes.