|
|
|
|
|
|
|
|
``I don't care if space aliens ate my mouse'', or a study in both the technical and human issues in porting the Linux OS to a new M68K target platform.
by Alan Cox
Several barriers to a Linux for Macintosh 68K port exist. The first is that Apple does not want other operating systems on its machines. While almost all of the workings of a PC can be learned from books, almost nothing is written about the Apple Macintosh. Sometimes Macintosh specifications and technical notes fill in the blanks; at other times, it is necessary to apply a great deal of guesswork and experimentation to figure out the hardware.
The second barrier is a human one. Most Macintosh machines were not sold to the technical market, and average Macintosh users aren't terribly interested in a ``real operating system'' for their computers. Nevertheless, a sizable technically oriented Macintosh user community does exist, with a lot of Macintosh hardware to go with it (probably more than any other non-Intel Linux platform). A further reason has been provided by Apple, whose quaint advice for owners of 68K machines now appears to be ``buy a new computer''.
The third barrier to a Linux port is less obvious and is hidden by a lack of documentation. Certain folks have speculated that embarrassment is the main reason for Apple Computer releasing so little documentation. In general, Macintosh platforms have positively Stone Age design features. For example, the interrupt controllers on a Macintosh II are a pair of 6522 VIA chips, intended for use with the 8-bit 6502 processor. Bad hardware design makes for poor performance, unless carefully handled. The complete lack of DMA (direct memory access) is even less helpful. Apple seems to think no DMA is a feature on most machines and actually have a technical note stating ``I used to be a teenage DMA junkie'', which seems to be a justification of their rather comical hardware design.
To get a port started, the first item needed is hardware. I had most of this (a 5MB MacII, cast off from the office as too slow for practical use). Initially, I felt safe helping to work out the directions for the Linux port, as this system lacked an MMU (memory management unit) and was therefore unable to run any proposed Linux port.
Rob Pelkey started on some very basic Linux work for the Macintosh, but needed a boot loader to load the Linux OS and kick it off. On #linux on the LinuxNet IRC network, Jes Sorensen (the keeper of Linux68K), I and several others got into a few discussions about the port and what would be required. After a lot of digging, we managed to gather some basic information on the Macintosh68K, then filled in further areas by investigating the excellent detective work the OpenBSD/Macintosh team had done in getting BSD limping along on Macintosh machines. Further information came to light from the Linux on OSF Mach port sponsored by Apple. We discovered that Apple continued to use the same 8-bit microcontrollers, or emulations of them, and had not redesigned the systems materially for the new processor.
Everything seemed perfectly fine. I had a Macintosh box to laugh at (and we used it occasionally to fail to duplicate problems Macintosh users had with CymruNet), we could kick ideas around and I had no MMU in my Macintosh, so I couldn't possibly help write any code.
By this point, Rob's effort had stalled badly, as he lacked the time to write the boot loader needed to run Linux and was working on passing courses and other sundry items. No worry--either someone would eventually take over the project, or he would finish his courses. Then Frank Neuman sent me an MMU for the MacII and someone else donated a pair of Ethernet cards--whoops, no more excuses.
Having fitted the MMU to the Macintosh without blowing it up, I tried to get MacOS to run with virtual memory. This is supposed to be simple--click on the memory tool and select 32-bit, virtual memory on. But no, my memory control didn't have a 32-bit option, let alone a virtual memory one. I stared a bit, then checked on a more modern Mac downstairs to be sure I had the right screen. The other Macintosh which was running the same MacOS version had the required option; mine didn't.
This was my first experience with the horrors of the Mac. While UNIX says ``I'm sorry you can't do that'', MacOS has exactly two error messages. It either goes ``eep?'' or the setup box is simply not there until 12 other unidentified items have been installed and three apparently unrelated dialog boxes have been completed. Mine was an error of the latter category.
Apple shipped the MacII with the ability to upgrade to include an MMU chip; therefore, they sensibly shipped it with a system ROM incapable of running with the MMU enabled. Brilliant--just don't design anything mission-critical, please. Fortunately, Apple had concealed on their web site a small tool which patches the ROM entry points so that it can run in 32-bit mode.
Okay, so all I had to do was download the tool, install it and be done--not so simple. To get the program, I needed the Ethernet to work. I ended up using kermit to transfer 700KB of Ethernet installer onto the Macintosh. After four hours of fighting with the completely alien Macintosh archiver tools, I had the machine talking AppleTalk shares to a Linux box using Netatalk, as well as insight into why Macintosh people meeting a PC for the first time look as if they'd just discovered alien life forms.
An hour later, I had figured out how to unpack Macbin files and the Macintosh was in 32-bit mode and admitted the MMU was present and functional.
The next stage in the operation was to figure out how to boot a Linux kernel image on the Macintosh. NetBSD and OpenBSD use a boot loader which loads a.out format executables into the memory of the Macintosh, shuts the Macintosh down, moves it to address 0 and jumps to it. I quickly decided I didn't want to write a boot loader. The OpenBSD loader was almost pure MacOS wizardry at a level far beyond my abilities. Not to worry--it soon became apparent that the OpenBSD loader could be persuaded to load Linux too. A true loader could wait.
The next problem was building a Linux kernel image that would link and (while most likely not doing anything useful) at least serve as something to feed the OpenBSD booter. Linux is built using the GNU tool chain, which supports the building of cross compilers. It is thus possible to compile and build 680x0 binaries on an ordinary Intel-based PC. It took a couple of builds to get gcc and the GNU binutils generating almost the right code. Linux a.out executables have a two-byte header different from the OpenBSD ones, and the OpenBSD boot loader checked those bytes. Rather than rebuild the entire tool chain again, I wrote a simple tool to fix the headers.
Most of Linux/M68K was quite content to build for a Macintosh target. I filled in everything that complained with dummy routines--for Mac keyboards, mice, display, etc. until it all compiled. Because of the well-designed abstraction layers in the Linux/M68K kernel, this was quite easy to do. I now had a completely useless, do-nothing, Macintosh kernel that the OpenBSD loader would load and which then promptly crashed the machine as I expected.
The Linux/M68K project had faced up to the challenges of supporting multiple types of 680x0-based computers within the same port, well before I got involved. As a result of the need to support both the Amiga and Atari systems, clear layers of abstractions are present. Adding an additional M68K target consists mostly of filling in platform-specific blank fields. A port to a completely new processor would have been far more challenging than this one.
For the Macintosh case, I filled in various, mostly blank function handlers. After finally getting the thing to link, I ended up with a kernel that was hard-coded for a 5MB 68020-based Macintosh with FPU and a display at 0xF9000000. It had no interrupt controllers, no disk controllers, no keyboard and no mouse. Anything else I could find was also hard coded. However, it linked and that was the important thing. Having done a bit of reading up on the innards of the console drivers (and much interrogation of Jes), I wrote a fairly simplistic back end for the generic console driver on the Macintosh. As it turned out, the very simplistic approach reflected the Macintosh hardware I had, which was a completely unaccelerated bitmapped display supporting 640x480 in 4-bit colour.
A Linux 68K kernel starts with a partially shared piece of initialisation code written in 680x0 assembler and using almost all the most Gothic and peculiar features of the architecture. This initialisation code also sets up the memory management and caching, and touches everything no one normally knows about. The 68020, 68851, 68881 combination of chips used in the Macintosh II is obsolete and Motorola didn't carry documentation on this device. I did know two things which, in theory, were enough to debug and figure out what was going on. First, I knew the base address of the screen memory; second, I knew the address that the code would begin executing. The very first routine I put in the startup code painted the screen a revolting blue colour. After about 15 boots and some staring at the source code, I had a Macintosh that booted to a blue screen, waited a short while, then crashed.
In many ways, this was the single hardest item to get going. When dealing with a completely unknown system environment with no idea what is around the code, debugging is extremely tricky. Real commercial hardware people use logic analysers--I didn't have that option. I learned several things in the process; notably, that Macintosh screen memory is not located where the hardware claims it is until the MMU is set up. I also made the amazing discovery that the rounded corners on the Macintosh display are drawn in software.
Over the next few weeks, the Macintosh went through an assortment of debugging stripes and coloured patterns as I inched a few lines at a time through the initialisation assembler code, fixing it bit by bit and gradually mapping in the needed hardware. Eventually, the kernel hit the magic start_kernel function in the C code without crashing on the way.
Hitting start_kernel is the beginning of the easy road; at least on a PC, text-mode consoles are now present instead of stripes. So theoretically, hitting start_kernel on a Macintosh should have meant that getting the kernel to initialise a text console and begin showing useful debugging information was close. Nothing could have been further from the truth.
After several attempts to get the console up, I wrote some routines to print penguins and Macintosh logos on the screen (this was easier than text). Each significant point the kernel reached added a penguin to the display, and a failure point before the console came up printed a given number of burning Macintosh logos. While hardly as good as print statements, this was good enough to rapidly locate several bugs in the processing of options passed by the boot loader (little things like apparently having 0KB of memory upset the Linux memory initialisation). The code would get to the beginning of the console setup and die.
To get past this point, I had to fill in support for the 4-bit packed pixel displays that were used by the Apple Macintosh ``Toby'' display card. The generic bitmapped console drivers for the 680x0 port supported a wide variety of pixel formats and naturally excluded the one I needed.
Had I known at the time, I could have simply switched the machine to Mono in the display preferences, but I didn't know that action physically switched the card into a monochrome mode. Adding 4-bit packed pixel wasn't too difficult. I left the somewhat scarier 2-bit packed pixel support for later, hoping someone else would write it. The console code is also very modular on the 680x0, and these console layers (abscon, fbcon) are now used by most non-Intel ports. It is reasonable to assume that it will be driving all the ports by the 2.3 kernel series.
The machine still crashed mysteriously and all evidence pointed to a structure getting stamped on. I put guard values on either side of it and checked that they were not overwritten; I moved the structure in memory; I tried everything I could think of in order to stop it from being apparently corrupted. (No joy, no change.) After a bit of head scratching, I added code to check that the values were okay at boot and at initialisation of each subsystem. The value was wrong at the start of the C code; it was also wrong at the start of the assembler.
This looked as if the boot loader was corrupting data, yet this made no sense, since the loader would corrupt the same location, not pick on a specific variable wherever it might be located. Eventually, I used the GNU objdump tools to look at the binary I was loading. It turned out the GNU linker was at fault and in some places was loading a completely bogus address for relocation.
A new linker and the magic words ``Calibrating Bogomips'' appeared on the screen, followed by a hang, then much rejoicing. In many ways, the time lost to the linker bug was not that bad. Eyeballing the code in search of the mystery bug, I had fixed some twenty or thirty other serious bugs in a vain attempt to find the illusionary real bug.
I wasn't too worried about the Bogomip calibration hanging. It is hard to calibrate time before the interrupt routines and, in particular, the timer interrupt routines have been written. I commented it out and after a short while the rest of the code booted to the point of saying ``Panic:unable to mount root file system''. A reasonable situation, as it had exactly no device support except the screen.
Getting the machine to the point where everything appears to boot is by no means a completion of the first steps of a porting project. This stage is when you finally appreciate the real problems and the scale of work remaining to be done.
The most important items to fill in were those that dealt with the most basic system resources: interrupts, memory and the I/O buses. The interrupts and several I/O subsystems are handled by a pair of 6522 VIA chips, 8-bit controllers from the Stone Age. These chips themselves are documented and their locations are known, even if some of the connections to their I/O pins are a mystery. A certain amount of mapping work and other detective information showed that the VIA chips provided the all-important system timer ticks, handled the keyboard at an extremely low (and at the time undeciphered) level and provided interfaces for external interrupts from the bus controllers.
Several other pins appear to do things such as turn the Macintosh off. Even now, we don't know what everything on the VIA chips does or if all the pins have a real use. It also turned out I got the easy end. The later Macintosh machines replace the second VIA with a device known as RBV (RAM-based video), which contains a bad emulation of a VIA chip and various other components in one piece of glue logic.
Basic interrupt handling on a Macintosh is relatively clean. A great deal of attention has been paid to keeping interrupts that need a fast response at a higher priority than time-consuming processes. That works well under MacOS, but Linux tends to take rather too binary a view of interrupts, especially in the drivers. Certain interrupts are wired in strange ways, presumably to save components; the SCSI interrupt, for example, is wired through a VIA but is effectively upside down compared to the other interrupt sources. Apple saved an inverter by using as an interrupt signal the fact that the VIA can handle either direction of state change.
I ended up with two layers of interrupt handling, which were mostly hard coded. Unlike a PC, the Macintosh interrupts are hard wired. Only the Nubus (plug in) cards change positions, and they all share one interrupt which sets bits in a VIA register to indicate the real interrupt source.
Nubus proved quite entertaining. The documentation is weak and written from the viewpoint of someone building a card for a Macintosh. It took about a week before the boot-up code would scan and report a list of which Nubus slots were occupied and the names of the devices. Once it worked, the Nubus turned out to be an extremely well-designed system with features much like PCI. Each slot is allocated a set of memory resources and can raise an interrupt. A ROM allows the OS to read each device for identification and driver information. The ROM also contains other ``useful'' data, including icons for the device. At the moment, these are not visible under Linux, but the intention is to support /proc/nubus/[slot]/icon.xpm at some time in the future.
The Daynaport card I had been given was very close to several PC designs. The 8390 Ethernet chip and block of RAM on it made that quite clear. There are, however, 224 possible locations for the chip and memory within each Nubus slot space.
Finding out where the device was hidden required building a collection of kernels which searched the 24 bits of address space looking for two things. First, it looked for areas of memory which could be read and written; second, it looked for areas like those which had the additional property of giving different results when read back. The 8390 chip has several control registers; by playing with these, it is possible to reliably identify the chip. (This same code is used to probe for NE2000 and WD80x3 cards in Linux for PC.) On the Macintosh, the RAM was easy to find but the 8390 did not show up.
Having played with the RAM behaviour a bit, I discovered that the memory was mapped to alternate 16 bits in its address space. That is, if you wanted to read it, you had to read two bytes, skip two bytes, read two bytes, etc. A bit of further experimentation revealed that the Ethernet controller registers occurred every fourth byte, that the RAM occurred every other pair of bytes and was 16-bits wide and that the Ethernet controller saw the 16-bit wide memory as 8-bit wide.
This sort of technique worked for mapping a large number of devices and address spaces and helped to discover the location of additional devices in the Apple I/O spaces. We still don't know enough to drive the Apple sound chip and the ``Integrated Woz Machine'' (floppy disk controller), but we do know where they are located.
When you need to start testing a system by booting into user space, you need a file system. The NFS root file system is extremely attractive for this and has been used for most ports. The NFS (Network File System) makes transaction requests at the level of files rather than disk blocks. This has the saving grace that errors in the new port cause transactions to get rejected. If you are trying to debug a new port and a SCSI controller driver at the same time, you will instead spend much of your time reformatting and reinstalling the disk from which you are attempting to boot. Using NFS limits the possibilities for errors and makes it easier to add and edit files as you attempt to make the machine work.
The initial installs were done with a set of tar files, known as ``watchtower'', for the M68K. Watchtower is extremely outdated but is small and easy to unpack. Since the goal was to get a shell prompt, the age of the binaries was not a serious worry. Watchtower also demonstrates another strength of Linux/M68K--all the ports run the same binaries. Instead of having to cross compile and debug all the binaries for the Macintosh, I was unpacking and booting a file system set up for installation on a Commodore Amiga.
With a few modifications to the drivers and several small bug fixes to the kernel code, the applications began to run. As most of the code we needed to add for a new M68K platform was drivers and setup code, once things began to work, most applications sprang to life. It took a couple of tweaks to get floating point to always behave, but once done, I was able to boot the machine fully multi-user but without keyboard, mouse or hard disk support.
It took almost a month before anyone else got the kernel to boot on their own machine. A lot of debugging removed some rather bad assumptions that had ``escaped'' the code cleanup. Gradually, other MacLinux 68K machines began to pop into being. This is an extremely important step for any project, as it allows others to contribute effectively. Michael Schmitz wrote the SCSI drivers and much of the keyboard and mouse support. He is now adding IDE. Numerous others have tested and debugged code on many varieties of Macintosh and even made it work on some.
While any new port is difficult, the structure of the Linux M68K kernel tree is very well-designed and delivers on its intention to allow easy portability between M68K targets. Several sections of this code are rightfully being used cross-architecture as well as cross-platform.
Making a free software port work seems to be about having a small number of people willing to take the project the first half of the way. Once this point is reached, the project gathers momentum of its own accord, even when it is something as pointless as Linux on a Macintosh II.
Lack of documentation is only a hindrance. It will not prevent determined people from exercising their basic rights to use and operate property they bought and now own. Instead, it reflects badly on the vendor who is trying to be a nuisance. If the only documentation on the keyboard interface is entitled ``Space aliens ate my mouse'', someone will still find it.
Always be the second operating system ported to an undocumented platform. The sterling work done by the OpenBSD/Macintosh team was a huge help to the Linux project. I'm also happy to say that even though half of the world may spend their time arguing on Usenet advocacy groups, the relationship between the Linux and BSD Macintosh teams has always been one of mutual co-operation. Together, we advance our detective work and knowledge of the Macintosh platforms to the good of all Macintosh users dumped and orphaned by Apple.
Alan Cox started hacking on Linux 0.95. He's since discovered he doesn't like working for small non-Linux companies and especially not for big ones, so he now runs Building #3, a Linux contracting company primarily working for Red Hat software. He can be reached at alan@snowcrash.cymru.net.