Cyrene
(C) 2018-2024 by Antoine VIGNAU and Olivier ZARDINI
> What is Cyrene ?
Cyrene is a Windows 64 bit application used to Debug, Trace and Analyze any Apple II or Apple IIgs code running on an Emulator.
It has been designed to provide a modern replacement for native Apple IIgs developer's applications such as GSSBug, DOCVu, IIgs Internals, Nifty List, Visit Monitor, Where In Memory is ?, ... It can work with all Apple II / Apple IIgs applications, starting from Dos 3.3, Prodos 8, Prodos 16, GS/OS or even the one without any OS such as Games or Demos (No Tools philosophy).
Cyrene is part of the Brutal Deluxe's Cross Development Tools Project, a full set of utilities available on Windows (and other) platforms to enable the creation of new Apple IIgs software : 65c816 Assembler, 65c816 Disassembler, 65c816 Simulator, Graphic File Converter, Resource Catcher...
We have a created a 30 minutes presentation for the Virtual KansasFest event in July 2024. This is a good starting point to understand why we have created Cyrene, how it works and how it can help you for your Apple II projects:
Because Cyrene uses a lot of UI, we have decided to provide a documentation based on short video clips (5 minutes each) to introduces the key features of the software.
It has been designed to provide a modern replacement for native Apple IIgs developer's applications such as GSSBug, DOCVu, IIgs Internals, Nifty List, Visit Monitor, Where In Memory is ?, ... It can work with all Apple II / Apple IIgs applications, starting from Dos 3.3, Prodos 8, Prodos 16, GS/OS or even the one without any OS such as Games or Demos (No Tools philosophy).
Cyrene is part of the Brutal Deluxe's Cross Development Tools Project, a full set of utilities available on Windows (and other) platforms to enable the creation of new Apple IIgs software : 65c816 Assembler, 65c816 Disassembler, 65c816 Simulator, Graphic File Converter, Resource Catcher...
We have a created a 30 minutes presentation for the Virtual KansasFest event in July 2024. This is a good starting point to understand why we have created Cyrene, how it works and how it can help you for your Apple II projects:
Because Cyrene uses a lot of UI, we have decided to provide a documentation based on short video clips (5 minutes each) to introduces the key features of the software.
> Installation
Before installing Cyrene for KEGS on your Windows PC, make sure you already have downloaded KEGS executable from its official Web site and you can run it. You will need an Apple IIgs ROM file and probably some hard drive disk images to have a complete Apple IIgs system running. If you have never used KEGS emulator, take some times to dicover its features (Keyboard Shorcuts, How to change CPU speed, Use Joystick, Access Control Panel...) and understand how to modify its settings (F4 is your friend).
Installing Cyrene on a Windows based machine is a very easy process. Simply download the Cyrene_v1.0.zip archive file from this web page (at the bottom) and extract the two files Cyrene.exe and KegsCyrene.exe on your hard drive. There is no other dependencies to install. We recommand to install the two files in the same folder than the existing KEGS application. So at the end, your KEGS folder should look like this:
You can start Cyrene by double-clicking the Cyrene.exe executable. The Cyrene.ini file will be created if you enter the Preferences DialogBox and choose to save Cyrene settings.
The config.kegs file hosts the settings of KEGS. You can start either kegswin.exe or KegsCyrene.exe and both should provide the same features (you will notice than kegswin.exe is nevertheless a little bit faster than KegsCyrene.exe). Because both are sharing the same config file, you should not run them at the same time, in order to avoid any corruption in the config file or in the attached disk image files.
The combo Kegs + Cyrene should work from any PC running Windows 7 or newer. Because of the initial size of the Cyrene main window, your screen resolution should be 1400x900 or higher. We recommand the usage of a full HD screen (1920x1080). There is no minimum RAM configuration required but at least 1 GB of free RAM is a minimum if you want to record several seconds of KEGS's operations. You will need about 55 MB to record all 65c816 operations proccesed by KEGS (running at 2.8 Mhz) in 1 second. The complete Apple IIgs boot process, from PR#7 to System 6.0.1's Finder, consumes 3 GB of data (33 millions of operations, 140 millions of cycles). The best configuration to use Cyrene and KEGS is a modern PC (Intel i7, 16 GB of RAM, Full HD screen, SSD Hard Drive).
Installing Cyrene on a Windows based machine is a very easy process. Simply download the Cyrene_v1.0.zip archive file from this web page (at the bottom) and extract the two files Cyrene.exe and KegsCyrene.exe on your hard drive. There is no other dependencies to install. We recommand to install the two files in the same folder than the existing KEGS application. So at the end, your KEGS folder should look like this:
The config.kegs file hosts the settings of KEGS. You can start either kegswin.exe or KegsCyrene.exe and both should provide the same features (you will notice than kegswin.exe is nevertheless a little bit faster than KegsCyrene.exe). Because both are sharing the same config file, you should not run them at the same time, in order to avoid any corruption in the config file or in the attached disk image files.
The combo Kegs + Cyrene should work from any PC running Windows 7 or newer. Because of the initial size of the Cyrene main window, your screen resolution should be 1400x900 or higher. We recommand the usage of a full HD screen (1920x1080). There is no minimum RAM configuration required but at least 1 GB of free RAM is a minimum if you want to record several seconds of KEGS's operations. You will need about 55 MB to record all 65c816 operations proccesed by KEGS (running at 2.8 Mhz) in 1 second. The complete Apple IIgs boot process, from PR#7 to System 6.0.1's Finder, consumes 3 GB of data (33 millions of operations, 140 millions of cycles). The best configuration to use Cyrene and KEGS is a modern PC (Intel i7, 16 GB of RAM, Full HD screen, SSD Hard Drive).
> Quick Overview
> Operation Data
> System Calls
> Data Views
> Code Disassembler
> Memory Map
> Apple IIgs Internals
> Memory Snapshot
Please find below the format of the Apple IIgs Memory Snapshot files (*.GSm) used by Cyrene and Studio:
> Symbols File
Let's discuss the usage of Symbols Files by taking a GS/OS application like AppleIIgsKarate as exemple. This program has 6 segments (Main, Game, Sprite1, Sprite2, Sprite3 and Sprite4)
and each segment is built from one or several sources files :
All labels found in sources files will end up as Symbol lines in the output Symbols file created by the assembler (Merlin32 here). If we look at source file AppleIIgsKarate.Game.s from Segment Game, we can see labels associated to 16 bit Hexadecimal values (LoadUnpackBank, Data1Bank, Data2Bank, Data3Bank...):
The LoadUnpackBank label can be found the the Symbols file along with the label properties:
Because AppleIIgsKarate Application is relocatable, we need to wait to have the application loaded in memory to know the address of each Segment (Game is loaded at memory address 12/0000):
From the Symbols Table window, we can now see the memory address of all Symbols (LoadUnpackBank is located at memory address 12/0000):
If we ask for a disassembly window at memory address 12/0000, we can see that the disassembly output takes advantage of the symbols properties by providing label names, data types, data lengths... The blue and green parts indicate known locations:
The Symbols files created by Merlin32 and used by Cyrene respect the following file format:
If your application uses fixed memory addresses, set the label memory address in column Address and let the Reloc column empty. Segment Name and Application name values are also not required.
All labels found in sources files will end up as Symbol lines in the output Symbols file created by the assembler (Merlin32 here). If we look at source file AppleIIgsKarate.Game.s from Segment Game, we can see labels associated to 16 bit Hexadecimal values (LoadUnpackBank, Data1Bank, Data2Bank, Data3Bank...):
The LoadUnpackBank label can be found the the Symbols file along with the label properties:
- Name of the Application (AppleIIgsKarate from Symbols File name AppleIIgsKarate_Symbols.txt)
- Name of the Segment (Game)
- Type of the Symbol (Data)
- Data Type of the Symbol (HEX)
- Size of the Symbol in memory (2 bytes)
- Address / Offset of the Symbol in the Segment (00/0000)
- Location of the Symbol in the Source File (AppleIIgsKarate.Game.s, line 84)
Because AppleIIgsKarate Application is relocatable, we need to wait to have the application loaded in memory to know the address of each Segment (Game is loaded at memory address 12/0000):
From the Symbols Table window, we can now see the memory address of all Symbols (LoadUnpackBank is located at memory address 12/0000):
If we ask for a disassembly window at memory address 12/0000, we can see that the disassembly output takes advantage of the symbols properties by providing label names, data types, data lengths... The blue and green parts indicate known locations:
The Symbols files created by Merlin32 and used by Cyrene respect the following file format:
If your application uses fixed memory addresses, set the label memory address in column Address and let the Reloc column empty. Segment Name and Application name values are also not required.
> Breakpoints
Please find below the list of available [Keywords] you can use in the Breakpoint output line:
> Fonction Statistics
> Fonction Profiler
> F.A.Q
Is the Source code available somewhere ?
What about a Macintosh or Linux release ?
Can Cyrene be used with other Apple II or Apple IIgs emulators than KEGS ?
The Source code is freely available in the Zip file in download section.
It is currently packaged as a Visual Studio 2010 Project set of files. The tool is only using C Language, so you can recompile it with any other C ANSI compiler (GCC...) running on Windows.
It is currently packaged as a Visual Studio 2010 Project set of files. The tool is only using C Language, so you can recompile it with any other C ANSI compiler (GCC...) running on Windows.
What about a Macintosh or Linux release ?
Not on schedule. The program itself uses Windows API everywhere (user graphic interface, system calls, IPC...) so porting the software to another platform means rewriting everything.
The Cyrene / KEGS combo is nevertheless easy to use from an USB Key on any PC (no installation required) or on a Windows Virtual Machine running on Macintosh (Parallels) or Linux.
The Cyrene / KEGS combo is nevertheless easy to use from an USB Key on any PC (no installation required) or on a Windows Virtual Machine running on Macintosh (Parallels) or Linux.
Can Cyrene be used with other Apple II or Apple IIgs emulators than KEGS ?
Yes. Any Apple II 8 bit or Apple IIgs emulators running on Windows should be able to be connected to Cyrene with little code modification.
KEGS has been chosen to be the first Apple IIgs emulator to be integrated with Cyrene because of its popularity and the availability of the source code.
KEGS has been chosen to be the first Apple IIgs emulator to be integrated with Cyrene because of its popularity and the availability of the source code.
> External References
- KEGS Emulator Officiel Web Page : KEGS Emulator
- Apple IIgs Firmware Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Hardware Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Prodos 16 Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 1, © 1988 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 2, © 1988 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 3, © 1990 Addison-Wesley Publishing
- Apple IIgs GS/OS Reference, © 1990 Addison-Wesley Publishing
- Apple IIgs Toolbox Changes for System Software 6.0, 1992 David A. Lyons
- Programmer's Reference for System 6.0.1, © 1993 Byte Works Inc.
- Programming the 65816 - Including the 6502, 65C02 and 65802, © 2007 Western Design Center
- Apple IIgs Firmware Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Hardware Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Prodos 16 Reference, © 1987 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 1, © 1988 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 2, © 1988 Addison-Wesley Publishing
- Apple IIgs Toolbox Reference volume 3, © 1990 Addison-Wesley Publishing
- Apple IIgs GS/OS Reference, © 1990 Addison-Wesley Publishing
- Apple IIgs Toolbox Changes for System Software 6.0, 1992 David A. Lyons
- Programmer's Reference for System 6.0.1, © 1993 Byte Works Inc.
- Programming the 65816 - Including the 6502, 65C02 and 65802, © 2007 Western Design Center
> Download
Cyrene 1.0 64-bit + KEGS 1.34 32-bit for Windows computers
Cyrene 1.0 Application Source Code + Cyrene Plug-In for KEGS Source Code
Cyrene 1.0 Application Source Code + Cyrene Plug-In for KEGS Source Code