search

bluewaysw / geos

Source code of 8-bit GEOS 6.0 for the MEGA65
41 stars 5 forks source link

readme

GEOS Source Code (enhanced to support MEGA65 capabilities)

by Berkeley Softworks, reverse engineered by Maciej Witkowiak, Michael Steil, MEGA65 version by Falk Rehwagen.

MEGA65 GEOS Development

Goals

Status

The status of the MEGA65 version of GEOS as present on the master branch is considered early BETA and still under development. Please use with care!

Learn more details about the GEOS MEGA65 implementation (soon) in the Technical Documentation section.

We are on https://bluewaysw.slack.com/ for more efficient collaboration. Please register at https://blog.bluewaysw.de for MyGEOS and use the Slack section and receive access to our developer community. Welcome!

Description

GEOS is a graphical user interface for 6502-based computers. In the 1980s, it was commercially available for the Commodore 64, 128 and Plus/4 as well as the Apple II.

GEOS has extremly low hardware requirements:

With just 20 KB of binary code, the GEOS "KERNAL" has the following features:

The default shell of GEOS is deskTop, a file manager an application launcher.

Several powerful applications are available for GEOS, including

The cc65 compiler suite allows writing GEOS applications in C or assembly.

Source

This is the reverse engineered source code of the KERNAL (plus disk and input drivers) of the English version of GEOS 2.0 for Commodore 64 and Commodore 128.

The source has been heavily reorganized and modularized, nevertheless, a standard compile will generate binaries that are identical with the GEOS 64 2.0 and GEOS 128 2.0 distribution binaries.

Optionally, the following features that were not part of the original GEOS 2.0 can be enabled for GEOS64:

Requirements

Without pucrunch/c1541, you can still build an uncompressed KERNAL binary image.

Building

Run make to build the original "BSW" GEOS for C64. This will create the following files in directory build/bsw:

If you have the cbmfiles.com GEOS64.D64 image in the current directory, the disk image will be based on that one, with the GEOS and GEOBOOT files deleted and the newly built kernel added. Otherwise, it will be a new disk image with the kernel, and, if you have a desktop.cvt file in the current directory, with DESK TOP added.

Variants

The build system supports the following variants:

You can build a specific variant like this:

make VARIANT=<variant>

All output will be put into build/<variant>.

Drivers

By default, the KERNAL image will contain the Commodore 1541 disk driver (drv1541) and the joystick input driver (joydrv). You can specify different drivers to be included like this:

make DRIVE=<drive> INPUT=<input>

Supported drives are drv1541, drv1571 and drv1581. Supported input devices are amigamse, joydrv, koalapad, lightpen, mse1531 and pcanalog.

Customization

The KERNAL variant custom is meant for your experimentation. Inside the .ifdef custom section in config.inc, you can toggle several compile time options:

With RAM expansion support, GEOS will use the extra RAM for caching deskTop and for holding the swap area when running desk accessories. GEOS will show an error at startup and reset the system if support for a particular memory expansion is enabled but it is not available.

Note that the changing settings and adding code may cause certain memory areas to overflow. In this case, you can try moving segments between the LOKERNAL and KERNAL areas. The file kernal.map in the build output will give you an idea about the sizes of segments. The custom variant starts out with about 550 bytes of usable memory in the KERNAL area.

Source Tree

Hacking

Code layout

Great care was taken to split the KERNAL into small, independent components. This division does not necessarily match the layout of the original binary code, but with the help of .segments, the layout in the binary does not have to match the layout in source.

The goal of this division of the source was to keep the number of .imports minimal (i.e. to make individual source files as self-contained and independent as possible).

One example of this is the file system and application/accessory loading code. In the original GEOS KERNAL binary, they were not separate, but here, the file system code is in filesys.s and the loading code is in load.s, with only two symbol dependencies.

Another example is the ToBasic logic: In the original kernel, it the binary code was split, a part resided between the header and the jump table ($C000-$C0FF), and different part was in the "lokernal" area ($9000-$9FFF). In the source, both parts are in the same file tobasic.s.

Machine-specific Code

In case you want to adapt the source for other 6502-based systems, you will want to know which parts have C64 dependencies.

All C64-specific code can be easily recognized: Since all C64 symbols have to be imported from c64.inc, you can tell which source files have C64 depencency by looking for that include. Remove the include to see which parts of the code are platform-specific.

InitTextPrompt in conio.s, for example, accesses sprites directly, in the middle of hardware-independent code.

Memory Layout

The GEOS KERNAL has a quite complicated memory layout:

For C65/MEGA65 there is a different/specific layout:

The header and the jump table must be at $C000 and $C100, respectively. Together with the graphics bitmap at $A000, this partitions the KERNAL into four parts: lokernal, below header, between header and jump table, and above jump table.

The linker config file positions the segments from the source files into these parts. If the code of any segment changes, the header and the jump table will remain at their positions. If a part overruns, the linker will report and error, and you can consult the kernal.map output file to find out where to best put the extra code.

But it gets more complicated: Code between $D000 and $DFFF is under the I/O registers, so it cannot enable the I/O area to access hardware. The macro ASSERT_NOT_BELOW_IO makes sure that the current code is not under the I/O area. Existing code uses this macro just befor turning on the I/O area and just after turning it off. New code should use this macro, too.

Naming Conventions

Copy protection

The original GEOS was copy protected in three ways:

Contributing

Pull requests are greatly appreciated. Please keep in mind that a default build should always recreate the orginal binaries, so for smaller changes use conditional assembly using .if, and for larger changes create new source files that are conditionally compiled.

The following command line will build the bsw and wheels variants of GEOS and compare the resulting binaries with reference binaries:

make regress

TODO

References

License

For the underlying work on GEOS, please respect its license.

We open-sourced and included the original TopDesk with permission by Jürgen Heinisch from Geos-User-Club.

Configure application source is based on reverse-engineering work from an site that is not online anymore, referrenced here.

The intellectual property added by the reverse-engineering and the subsequent improvements is in the public domain, but the authors request to be credited.

Authors

GEOS was initially developed by Berkeley Softworks in 1985-1988.

The original reverse-engineering was done by Maciej 'YTM/Elysium' Witkowiak in 1999-2002, targeted the ACME assembler and was released as GEOS 2000, which included several code optimizations and code layout differences.

In 2015/2016, Michael Steil ported the sources to cc65, reconstructed the original code layout, did some more reverse-engineering and cleanups, and modularized the code aggressively.

Based on the fabulous work above, in 2017-2023 Falk Rehwagen adapted the implementation to support the MEGA65 platform.