#AmigaOS

The AmigaOS offers a debug console as a simple way for debugging. Log data can be written via the linkable Debug.lib, which is also used by all kind of tools like MuForce, Mungwall, or PatchWork. AmigaOS provides a simple internal debugger called ROMWack (which has been replaced by the even simpler SAD in later versions). But also DiagROM is writing diagnostics data via the serial port, which comes in handy when a RAM chip or something in the video area is broken.

The log output is sent to the serial port and can be read by a terminal connected to it. Back in the good old days, not so many hobbyists could afford an actual terminal or a second computer for that, so we used tools like Sushi or Sashimi to redirect the debug output into a Shell window, which worked fine unless the system has crashed too hard.

Today, I assume that almost all of the Amiga owners also have a second computer at home, and if it's just a second Amiga. 😉 This blog article is about how to connect your Amiga to your Linux PC, and get the debug output.

On the hardware side, you will need a construction with a DB25 female port on the one end, and an USB connector on the other end. I use one of those USB-to-Serial converters that can be found on hardware shops for little money. They are often equipped with a DB9 male connector, and are supposed to be connected to peripheral devices (like modems). To connect them to a computer, a so-called zero modem (or null modem) is required, which is just a small adapter that enables to connect two computers directly together by crossing the transmit and receive lines. Finally, we need a DB9-to-DB25 connector with the correct genders, to connect the other end of the zero modem to the Amiga.

This hardware stack is connected to the Amiga's serial port on the one end, and to a USB port of the PC on the other end. Remember to turn off the Amiga before connecting something to the serial port. Unlike USB, the ports of old computers are not designed for connecting or disconnecting devices while the system is powered. It could actually damage the system to do so!

On the software side, we don't need to install drivers on the Amiga. The debug or diagnostics output is just sent to the serial port. On Linux, we can use any terminal emulator. The most prominent is certainly minicom.

The default serial port settings are 9600-8N1 (9,600 bps, 8 bits per character, no parity, 1 stop bit). However, the debug output is just directly sent to the serial port. If you changed the serial parameters on Amiga side, and used the serial.device for something else, the debug output will use the current settings. Handshake must be turned off in any case, though.

Maybe the easiest way is to create a file called ~/.minirc.amiga with the following content (change the pu port value to your actual TTY USB device):

pu port             /dev/ttyUSB0
pu baudrate         9600
pu bits             8
pu parity           N
pu stopbits         1
pu rtscts           No
pu xonxoff          No

On many Linux distributions, the user also needs to be added to the dialout group in order to access a serial device:

sudo usermod -aG dialout $(whoami)

After that, just start minicom with the amiga profile:

minicom amiga

Now you should see all the debug output generated by AmigaOS on your minicom screen. For interactive debuggers like ROMWack, you can also type commands into the console.

To leave minicom, press CTRL-A and then Q. 😉

Amiga CD32

Unlike other Amiga models, the CD32 has no dedicated RS-232 port. Instead of that, it provides a simple serial interface at the Aux port that is connected to Paula's UART pins internally.

To build an adapter, you need a PS/2 cable (e.g. from an extension cord or an old PS/2 input device) and a MAX3232 based TTL-to-DB9 level converter. These converters can be found at online marketplaces for a few Euro.

Cut one end of the cable and connect the wires to the converter like that:

• Pin 2: TXD
• Pin 3 (and the shield): GND
• Pin 4: VCC
• Pin 6: RXD

Leave the remaining two wires unconnected, and check for correct polarity before connecting the wires to the converter!

The CD32 does not provide any control and handshake signals, but fortunately they are not needed for debugging and diagnostics purposes.

After 22 years, I released an update of a software I wrote in the end 1990's for the Amiga platform. It is a driver for the MacroSystem MaestroPro, a fully digital sound board. Along with the update, I have opened the source code of that library.

The sound driver itself is not that interesting, actually. I don't think there are many people on this world still using the sound board. What's more interesting is how I changed the project, to make it open-source and compilable under Linux and other modern platforms. That's what this article is about.

Versioning (or the lack of)

The first problem I faced was rather unexpected. Back in the good old Amiga days, I hadn't used revision control systems like CVS. Being just a hobby developer, I didn't knew about their existence nor their purpose. Instead, I frequently made backups of my source codes, so I wouldn't lose them in case of a harddisk failure, or after a botched code redesign. But besides that, programming was a surgery on the open heart of the source code, with no way to revert to a previous state that was known to be working.

As result, I found multiple different versions of the project on my Amiga harddisk, and I had to figure out what the latest one was. In this project I was lucky, because I had added a changelog to the main file of the source. I just had to find the copy with the most recent changelog.

Without a revision control system, the source of all older releases are lost, so I didn't even try to recreate a history from the backups. The last version on the Aminet was V41.40, but I couldn't find the source of that release any more. What I found instead was a V41.50 that was never released. I cannot remember why I decided not to release that version. Maybe the changes turned out to be a regression? Maybe I just lost interest in the Amiga, and didn't bother to release it any more?

Anyway, I could at least find the latest version of the source code. What to do with it? As I became a professional software developer since then, it was clear to me that I would not go on with just keeping the latest source code version (and some random backups), but I wanted to use a revision control system now.

I prefer to use git today. It would fit nicely into my development environment, and would permit to publish my source codes in my GitHub repository. But git was never ported to the classic Amiga, and probably never will due to its complexity.

Olaf Barthel did a port of subversion though. The last release was in 2009, and bases on a very old Subversion version 1.1.4. It wouldn't be much fun to use it, but it would be feasible.

There is also a CVS port made by Frank Wille, but I never really liked CVS, so this was no option for me.

So svn and git were the only candidates, with a strong preference to use git, but svn as the only option that would work on AmigaOS. The decision was connected to the next question.

Compilation

On what platform do I want to continue developing?

I could go on and develop the project on the Amiga, like I did in the 1990s. I had everything I needed there. I used GoldEd as editor, with customized macros for compiling my projects. I used PhxAss as assembler, and SAS/C as C compiler. None of this software is still maintained, and SAS/C was a commercial product that is not available any more. With these strict requirements, just a few people would be technically able to participate in the project.

Today, Amiga enthusiasts use the vbcc toolchain for development. It is still actively maintained. And it runs on AmigaOS, but also on all major operating systems. As editor, Visual Studio Code is a preferred choice because there is an Amiga Assembly Add-on available. It supports syntax highlighting, inline documentation, debugging, and much more.

These are the missing pieces of the puzzle. With vbcc, it is possible to build the project on Linux and other platforms, so almost every Amiga developer is able to participate. Developing on Linux also enables me to use git and all the other tools I got used to. But with just a few modifications to the makefile, the project could still be built on AmigaOS.

I decided to go the Linux way, but it's a decision that every retro developer has to do for themself. Cross-building an Amiga project on Linux would be comfortable (and fast), but is not really "retro". Building on AmigaOS would be the true retro spirit, but would leave me with an outdated and partially unmaintained toolset.

Porting

It was easy to copy the source files to my Linux file system, and initialize a git project there. The next problem I faced was that I had to port the makefile. It was tailor-made to my AmigaOS environment, with special assigns for include files and binaries.

I created a new makefile that was using env variables instead. AMIGA_NDK now points to the unpacked AmigaOS 3.2 NDK, while AMIGA_INCLUDES points to the include files of external dependencies (like MUI). I installed vbcc so all the commands were in the $PATH.

After that, I restructured and rearranged all the source code files. The project now only contains my own files that are absolutely necessary for building the project. An invocation of make then builds the project on my Linux machine.

I18n

There was an unexpected problem with the charset. While all modern operating systems use UTF-8, AmigaOS does not support it, but uses ISO-8859-1 instead. The result is that the repository contained an awful mix of both charsets. All files that are intended to be used by the git environment (like the README.md file) are stored in UTF-8. Other files that are AmigaOS related (like AmigaGuide files) must be stored in ISO-8859-1 instead.

I was hoping that I could define the correct encoding for each file type in an .editorconfig file. But sadly, Visual Studio Code ignores the charset settings and instead uses UTF-8 by default. It was too easy to accidentally destroy all special characters (like the German Umlaut in my family name) that way.

The only solution I found was to use UTF-8 or ISO-8859-1 only where absolutely necessary, but for most files I used ASCII as the lowest common denominator. An own make target make check checks all files for illegal characters, enforcing the proper usage of the encodings.

Testing

Of course I want to test (and run) the result on AmigaOS, either in UAE, or on a real Amiga.

On UAE, the created files can just be copied straight to the Amiga harddisk directory, and then immediately used in the emulated Amiga.

For the real Amiga, it's a bit more difficult though. One way is to create an ADF disk file using xdftool, and copy the files to it. That ADF file can then be copied to an USB stick, and read in the Amiga using a Gotek floppy drive emulator.

A better way is to use a simple NFS server that is mounted on both the Linux and Amiga machines. Files can be easily exchanged that way. Of couse it requires that the Amiga has a network connection.

Release

Back in the Amiga days, making a release was a fully manual process. For this purpose, I had a separate directory with a release template. I manually copied all compiled files to the proper places of that template, then packed it, and uploaded it to the Aminet.

Now I want the git project to be self-contained, so all the files of the release template are in the distribution directory. The make release target builds the entire project, then creates a fresh release directory, copies all the files to the correct places, and creates an lha package.

On a modern Linux machine, the entire process (from a clean checkout to the distribution package) takes less than a second. 🤩

And that's it. The source of the maestix.library is now open and available at GitHub. The first release that was built on the new environment, can be downloaded from the AmiNet.

CI/CD

You may have laughed now, but it's true: It is possible to do CI/CD with Amiga projects!

vamos is a virtual Amiga runtime environment that permits to run simple Amiga commands on Linux. It's just a CPU and API emulation, not a full-blown emulator like UAE, but it is sufficient to run unit test suites.

There are Docker images like docker4amigavbcc that, for example, permit to automatically build commits using GitLab CI.

And since it's easy to upload new packages to the AmiNet, even Continuous Deployment would be possible. Just create a version tag, and let your CI/CD chain do the rest. 🙂

Altogether, it is possible to develop these retro projects in a state-of-the-art fashion, with a modern IDE, source versioning, platform neutral development, unit tests, and even CI/CD.

AmigaOS was an operating system that was way ahead of its time. It had features that other home operating systems (like Windows or MacOS) were missing back then, like preemptive multitasking. There was also a feature that was called assignments. I truly miss that one on Linux!

An Amiga "assign" is a bit similar to the drive letter you may know from Windows. For example, the Windows path C:\example.txt refers to a file called example.txt in the root directory of the main partition, while the same file on the first floppy drive is called A:\example.txt.

On Amiga, the main partition is usually called DH0:, the second partition is called DH1: and so on, while the first floppy drive is called DF0:. A similar path on the Amiga would thus be DH0:example.txt or DF0:example.txt.

As you can see, on the Amiga a "drive letter" can actually consist of multiple characters and also numbers. This is called an assignment. The name DH0 is assigned to the main harddisk partition.

But wait, there is more!

You can have multiple assigns pointing to the same target. For example, the main partition usually contains the Amiga desktop environment, called Workbench. For this reason, the main partition also has a label like Workbench, and the file could also be accessed as Workbench:example.txt.

This is actually quite a smart concept, especially for exchangeable media. For example, let's imagine we have just started a game called shredzone, and it needs to access a file Music/Opening.mod on its installation disk (AmigaOS uses a slash as file separator, like all proper operating systems). It would open a file called shredzone:Music/Opening.mod.

AmigaOS would see that there is no assignment called shredzone, and would pop up a dialog like this:

From a user's perspective, I would now know that I have to find a medium called shredzone, and insert it into the computer. It does not matter if it's a floppy disk, a CD, or even a network mount. AmigaOS also does not command me to insert the medium into a certain drive. If it's a floppy disk, and I have multiple floppy drives, I can just pick the one I like to. AmigaOS will then detect that a medium with that name was inserted, would close the dialog, and grant the game access to the file.

On Linux, I would need to access that medium under a path like /run/media/shred/shredzone, which is a lot to type, contains my user name, and is harder to remember than just shredzone:.

But wait, there is still more! 😄

It is easy to add assignments to the system via command line. It's even possible to use subdirectories as assignment target. Let's stay with our shredzone game example. I got tired of having to insert the installation disk every time I want to play that game. So I create a directory called DH2:Games/Shredzone/Files on my hard drive, and I copy all files of that disk to that directory.

After that, I enter this command on the command line:

assign shredzone: DH2:Games/Shredzone/Files

Now, when I start the game, AmigaOS will see that there is a shredzone assign already existing, and will access the files there. So the song file shredzone:Music/Opening.mod would be accessed at DH2:Games/Shredzone/Files/Music/Opening.mod.

AmigaOS makes use of assigns itself. For example, there is a standard assignment called C:. It usually points to the C directory of the booting device, where all command line commands (like dir, copy, delete etc) are expected to be present. This assign is similar to what $PATH is to a Linux shell.

Imagine I have installed a set of development tools, like an assembler and a C compiler. The commands of this toolset can be found at DH1:Development/DevTools/C. On a Linux system, I would add this path to the $PATH env variable, so I can just type the command name to execute one of these commands.

On AmigaOS, I just add this path to an existing assignment:

assign add C: DH1:Development/DevTools/C

Now AmigaOS knows that when I enter a command in the command line, it has to look for it in Workbench:C, and if it's not found there, it will try to find it in DH1:Development/DevTools/C. I could even execute commands like dir C:, and see all files in both directories. Of course, it is not limited to two targets.

There is still more, like deferred assigns. But I only want to give you a general impression of what Amiga assigns are, and why I miss them on Linux.