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.

With the recent AmigaOS 3.2 release, and the prospect of further updates, it may be interesting to burn own EPROMs for the Amiga. Luckily there is no need to buy expensive equipment any more, as EPROM burners and erasers became affordable. This article explains how I burn Amiga EPROMs at home.

Shopping List

First of all, we will need fitting EPROMs of course. These types are compatible to most Amiga models:

• AMD AM27C400
• Macronix MX27C4100 [sic!]
• STMicroelectronics M27C400

It is important to pick parts with an access time of 200 ns or faster. Models like the Amiga 4000 can even be jumpered to an access time of 160 ns. EPROMs with 120 ns (or less) are easy to find, and definitely on the safe side. Note that Macronix truncates the trailing zero, so a MX27C4100-12 actually has 120 ns access time.

For burning the EPROMs, I use an XGecu TL866II Plus programmer and a 27C400 programming adapter.

Unlike modern flash memory, EPROMs cannot be erased electrically, but are erased by exposing the chip behind the quartz glass window to a strong UV light source. For this reason, an EPROM eraser is also recommended. Note that there are OTP-ROMs without that window, they cannot be erased at all.

None of these EPROM types are still in production. You might still find sources who sell NOS parts, but usually all chips on the market are refurbished. I am a bit careful with chips that look too new, or are claimed to be made by AMD. It is likely that these are just Macronix chips that were painted black and then laser-engraved with a fake AMD label. A cotton bud and a bit of nail polish remover will quickly reveal the scam.

These fake parts are perfectly fine. They are just sold at a higher price because of the alleged noble AMD origin, so you might as well order the Macronix chips directly and save money.

Preparation

Before burning a ROM dump, all even and odd bytes need to be swapped. For Amiga models with two ROM sockets, these dumps also need to be split into separate images for the upper and lower word. To make things even more complicated, a 256KB ROM dump needs to be duplicated to fill the entire memory space of a 512KB EPROM.

Luckily, the AmigaOS 3.2 CD already provides *.bin files that are ready for burning. For plain ROM dumps (those that can be used in emulators), my tool pynaroma can be used for byte-swapping, splitting, and duplicating.

Burning ROM

For the TL866 programmer, I prefer to use the minipro controller software. It is open source and runs on Linux, MacOS and many other Unix derivates, while the manufacturer's original software requires Windows.

The programming adapter is inserted into the programmer, and EPROM inserted into the ZIF socket of the adapter, with the notch pointing to the top, and the chip aligned with the bottom of the socket. Do not put the EPROM into the programmer without that adapter, otherwise it will be destroyed during operation.

The adapter simulates the pinout of an AM27C4096 EPROM, so --device 'AM27C4096@DIP40' must be selected. The --skip-id option must be given as well, otherwise minipro would abort the process because it detects a different type of EPROM.

For writing, the --no_id_error option needs to be used instead. By default, the AM27C4096@DIP40 profile uses a programming voltage of 13V, and a writing voltage of 6.5V. On my chips VPP=12.5V is printed, so I reduced the programming voltage with the --vpp 12.5 option. It might also be necessary to reduce the writing voltage using the --vdd option. Check the datasheet if in doubt.

The first step is to check if the EPROM is empty.

minipro --device 'AM27C4096@DIP40' --skip_id --blank_check

If it's not, it must be erased first. 15 minutes of UV light exposure in the EPROM eraser should be sufficient. If the EPROM still isn't empty after that, just repeat the process.

After that, the ROM image (e.g. amigaos.bin) can be burned to the EPROM:

minipro --device 'AM27C4096@DIP40' --no_id_error --vpp 12.5 --write amigaos.bin

minipro will automatically verify the content after burning, but you can also verify it manually:

minipro --device 'AM27C4096@DIP40' --skip_id --verify amigaos.bin

And for the sake of completeness, this is how to read the content of a burned EPROM to a ROM image file:

minipro --device 'AM27C4096@DIP40' --skip_id --read amigaos-read.bin

After burning, the window should be covered to protect the chip from stray UV light. A simple paper sticker is sufficient.

One year or so after I got my Amiga 500, I extended it with a GVP Impact Series II A500-HD+ SCSI host adapter and a 45MB harddisk. It retired together with the Amiga 500, and was stored in the basement for decades. But while the Amiga survived the years in a surprisingly good state, the GVP had suffered from the moisture. The case was yellowed, but also got mold stains, and the metal frame got some flash rust.

All in all, it seemed to be in a bad shape that was difficult to restore. But on the other hand, it would be sad to write off this nice piece of hardware, while all the other Amiga stuff got a general overhaul.

I sent the case to the CBM Museum Wuppertal for cleaning and whitening. It was a bit embarassing to send it in that bad condition, but they said it can be cleaned and will then look as good as new. Let's see if they can do miracles.

Flash Rust

The base frame had a lot of dirt and flash rust from the storage, especially in the areas that are frequently touched. I used some Nigrin car metal polish paste to clean it, but probably every kitchen metal polish would have done the job as well. It was a bit of work, but after that it almost looked as new.

Self-Powering

There have been two things that were always annoying me on this controller. One was the tiny fan that was supposed to cool the harddisk, but produced a lot of noise. The other one was that a separate external PSU was needed to power the harddisk.

I always wished that the controller would just source itself from the Amiga, but it was clear to me that the mechanical harddisk was drawing too much power for that. The original Fujitsu drive consumed about 10W! With a SCSI2SD adapter, the power consumption is considerably lower, so a self-powering is feasible. The SCSI2SD V5.2 adapter draws only about 10mA, or 0.05W.

The controller can easily be modified to get its power from the Amiga. There is a blog post by davem2 explaining it. All one needs to do is to bridge the CN5 and CN6 pads with some solder.

Since the SCSI2SD adapter also does not need active cooling, I could finally keep the loud case fan disconnected for good.

After the modification, make sure never to connect the GVP PSU to the controller again. It would power the Amiga via the card connector, which is very likely to cause damage to your hardware. Also, do not use mechanical harddisks after the modification. If you want to keep using the original PSU instead, you should let a technician check it first.

Firmware Upgrade

By a lucky chance, I found the latest firmware v4.15 in Ralph Babel's Amiga archive. By another lucky chance, I also found a 27128 EPROM in my spare part box that was once stripped from an old mainboard.

The original firmware would have worked fine as well, but if there is an opportunity for a free update, why not take it?

If you should use a 27256 EPROM instead, make sure to burn the image twice, as only the upper half of the memory will be accessed by the hardware.

Final Works

As there are no electrolytic capacitors on this board, there is no need for recapping. I still did a minor modification: I replaced the LEDs with blue (power) and red (disk) ones, as it became a kind of signature color for all my computers.

After that, I gave the board a thorough bath in IPA, and cleaned the edge card connector with a contact cleaner.

I also found two 1MB/70ns 30-pin SIMM modules for a few Euros on the Bay, so I could double the available Fast RAM to stunning 4MB in total. (Remember to change the jumpers accordingly, as there is no automatic detection.)

Reassembly

Meanwhile the CBM Museum Wuppertal had returned the cleaned and whitened cover. They did an excellent job! The case looks almost as good as new. The mold and dirt stains are gone, and the whitening brought back the original "Amiga beige" color.

As the SCSI2SD adapter is delivered without any kind of mounting frame, I had to 3D-print one myself. Unfortunately it collided with the case fan, so eventually I just removed it completely.

And that's it. The GVP harddisk controller is reunited with its Amiga 500 again. I am sure they have missed each other. 😉

The ugly duckling finally became a beautiful swan again!

In the first part, I took the Amiga apart and repaired the main board. In this second part, I will take care of a new PSU, and then I will put the system back together.

New PSU

There are also capacitors in the PSU that dry out over the years and need to be replaced. But as I'm not a trained technician, I keep my hands off all kind of hardware as soon as mains power is involved.

Surprisingly, a standard SFX form factor PSU perfectly fits into the power supply opening at the back side of the Amiga case. Even the two screw holes of the case match perfectly, almost as if the SFX form factor was just invented for that purpose. There is sufficient space below the PSU for the fan to transport the warm air from inside the case to the outside. There is also enough space for the longer SFX-L form factor. Most of them use a silent 120mm fan. All it needs is a frame where the power supply can sit on.

Not all SFX PSUs are suitable for the Amiga though. The reason is that in modern PCs, the main load is on the 12V line, and there is also a 3.3V line. The Amiga however has its main load on the 5V line, the load on the 12V line is neglectible, and the 3.3V line is not needed at all. Most modern PSUs are regulated on the 12V line. If there is too little load on it, the other voltages may become instable. In best case, the Amiga will then just crash. In worst case, its hardware will be damaged. There are experts who generally advise against using PC PSUs as a replacement power supply, so let me give some warnings before I go on with the article.

WARNING: I recommend to keep the original Amiga PSU, and have it restaured by an expert. Using a different PSU may cause permanent damage to your Amiga, possibly years after the modification. Self-made power adapters can damage your Amiga if incorrectly wired, and may even cause a fire if underdimensioned or short-circuited. You reproduce the following modification at your own risk. If in doubt, keep using your original Amiga PSU.

The original Amiga 4000 power supply has a maximum load of 145W. Even the smallest SFX PSU is able to deliver far more than that, so basically you can choose any PSU which provides at least 90W (18A) on the 5V line. Still the actual choice is very small. Firstly, the PSU should generate the 5V by a separate DC/DC converter, so the voltage is stable even if there is almost no load on the 12V line. Secondly, the PSU fan needs to be active all the time, as it is the only fan in the Amiga that transports the warm air out of the case. Many modern PSUs have a hybrid fan control though, and operate in a passive cooling mode on low load conditions.

For my Amiga, I use:

• A be quiet! SFX-L Power 500W PSU. According to the manufacturer the 5V is generated by a DC/DC converter, and all supplied voltages have a required minimum load of 0A. Also the fan is permanently operating, but still almost inaudible. Some of the connectors of the modular design collide with the power switch, but that's not a problem unless you plan to use more than three drives.
• A 3D printed SFX adapter frame.
• A Canal PSD-1 power switch. They are not manufactured any more, but can still be found at online marketplaces. If you cannot get one, you can also take the one from your original PSU. (Do not open the PSU case, but ask an expert to remove it for you.)
• An ATX to Amiga power adapter. I made one myself using an "ATX to Acer 12-pin" power adapter, a TE Connectivity Mate-N-Lok 6 circuit plug that is still available today, and a crimp tool. Some Amiga shops also sell readily assembled adapters.

To build the power adapter, the wires need to be connected between the Amiga power plug and the corresponding pin of the ATX power connector. The PS_ON# and one of the COM pins are connected to the power switch. All wires should be sufficiently dimensioned.

When everything is assembled, make sure (make double sure, make even triple sure) that the wiring is correct, but do not plug the connector into the mainboard yet. Now press the power button and check the voltages. PWR_OK should have 5V, but it may flutter or even be 0V because the PSU has no load right now. The other voltages must be correct and within a tolerance of 5%. Keep the test short, as it may stress the PSU.

For the first live test, I removed the CPU module, the SIMMs, and all Zorro boards. The Amiga won't boot like that, of course. But if something should go horribly wrong, the damage would be limited to the mainboard only (which is still bad enough).

Then I turned on the power, for the first time in maybe 20 years. The power LED lighted up. There was no smoke, no smell of burnt electronics, all the chips stayed cool. I checked the power lines, and all voltages were within the expected range. This was looking really good! I turned the power off again.

Now I was confident enough to remount the CPU module and the SIMMs. I also inserted a scandoubler, and connected a monitor to it. Then I turned the system on again. And a few seconds later, I got a picture.

I was probably never that happy to see the Amiga boot screen! 🥲

I had invested some money and many weekends into the refurbishment project, with unknown outcome. All the patience finally paid off.

Reassembly

The old mechanical hard disks were loud, slow, and produced a lot of heat. Since I want my Amiga to be as silent (and modern) as possible, I decided to use a SCSI2SD hard drive emulator instead. Alternatively, an IDE to Compact Flash adapter can be connected to the internal IDE header.

Besides that, I only left a floppy disk drive in the drive cage, but maybe I'm going to replace it with a Gotek floppy drive emulator later. The minimalistic equipment and the modular design of the PSU gives a clean and tidy look on this side of the case. It is also good for the ventilation.

On the other side, the freshly recapped MaestroPro and Toccata sound boards have already moved back to their Zorro slots.

Let's have a look at the outerior. The CBM Museum Wuppertal did an excellent whitening job again. The keyboard looks as good as new, and the outline of the old sticker on the front is almost invisible now. The paint shop did a good work as well, the cover now looks almost brand new.

I've tried to use my original Workbench installation from the 1990s, which I kept on using in an UAE emulator after that, but it was too messed up and crashed the real Amiga while booting. Finally I gave up and installed a fresh Workbench 3.2 from scratch.

What is still missing is a ZZ9000. It will serve mainly as a HDMI graphics card and Ethernet card. After that, my good old Amiga 4000 is ready for some serious Amiga programming again. 😉

Kudos

A refurbishment project like this is not possible without the help of a number of people. First of all, I want to thank the members of the A1K.org Amiga Board, especially halbvier for organizing the rare parts that I needed for the RTC repair. I want to thank the people of the CBM Museum Wuppertal for carefully whitening the plastic parts, and for the nice talk we had. I also want to thank Jan Beta because his YouTube channel inspired me to refurbish my two Amigas.

This project is dedicated to my brother Robert, who had taught me how to solder and how to repair old hardware. I miss you.