NetBSD/Mac68k HWDIRECT Page

This page documents the changes that are in place when using using NetBSD/mac68k kernels that have the MRG_ADB kernel option disabled.

Index

This page is under a general state of construction.[UNDER_CONSTRUCTION]
Last updated June 29th, 1998.

Background

Apple doesn't really release very in depth information about the hardware of the Macintosh line. So, when NetBSD/Mac was first being developed, (long before I even knew it existed), the developers used hints from the available Apple publications to get some code working to accept keyboard and mouse data from the ADB hardware. For the most part, this worked pretty well. The problem was that although it worked on the Mac II series of machines (II, IIx, IIcx, IIci and SE/30), the ADB hardware interface changed on the later machines, and so that code no longer worked.

So, one of the original Alice members (the Alice group started the NetBSD/Mac68k port), Brad Grantham, came up with the idea that the Mac ROM could be used to provide ADB support on ALL the Mac models, without having to resort to machine-specific code. He wrote this ingenious interface (IMHO) that allowed the NetBSD kernel to call routines in the Mac ROMs. In addition, this code allowed A-Trap calls within the ROM to be caught and intercepted by NetBSD. So, for example, the kernel could call ADBReInit in the Mac ROMs. Well, it turns out that ADBReInit needed to allocate memory, so it (being in the ROMs, of course) called NewPtr, which was intercepted and munged into a malloc call. Cool, huh? (This technique, dubbed "Mac ROM Glue", or "MRG", isn't limited to just ADB routines, either.)

Well, it was at around this point that I discovered NetBSD and wanted to get it running on my Mac IIsi, which wasn't really supported at the time. The reason was the one big drawback of the MRG approach: the Mac ROM routines expected certain low-level variables to be already set up in order for the ROM routines to work properly. And what exactly were these variables? That's the problem. No one was sure. But, after lots of hacking, guessing, and logging into his Mac over the serial line of a DG Personal-1 terminal, Dan Risacher, with inspiration and advice from Walter Reutten, figured out how initialize the proper low-level globals and got the IIsi to work.

After some time and experimentation, it started to look like a lot of the Mac models used different code to initialize the low-level globals. So each model had to be investigated separately, which was extremely time consuming. (Although Bob Nestor continues to do a terrific job of adding this support for an increasing list of Mac models!)

So, with some sample code and timing diagrams from Walter, I started working on a non-MRG method of accessing the ADB hardware. My hope was that there were less ADB hardware types than there are Mac ROM versions, and so the overall effort would be less.

Although it's took me a LONG time to get there, the end result is that I ended up writing a complete set of ADB routines for my IIsi that mimiced the Mac ROM versions. This way I could "insert" them into my copy of the official kernel source code without changing too much of the existing code. It turns out that my "IIsi" version also worked with the IIvi, IIvx, Performa 600, and LCIII, since they all have the same type of ADB hardware. I have added modifications to the code that allows for hooks for various ADB hardware types.

I later added support for another version of the ADB hardware, the "II" series ADB hardware. This of course includes the II, IIx, IIcx, and IIci, but also includes several Centris and Quadra models.

Takashi Hamada added code that works with mine and allows many of the Powerbook models to have working ADB support. You can check out the details of his changes on his Power Manager Patches for NetBSD page.

The final ADB hardware type that was built into the the 680x0 Macs (and therefore that NetBSD/mac68k needs to support) is the "Cuda" series. This model is now supported along with the others.

Although Apple doesn't explictly explain how the ADB hardware interfaces work, most of this code was developed using the available publications from Apple, including:

These, along with some educated guesses, various iterations and combinations of bit patterns, several random guesses, and LOTS of experimentation helped in developing this code.

These changes were formerly referred to under the name "ADBTEST".

The code is now part of the official kernel source and can be compiled in and by simply commenting out the MRG_ADB option in the appropriate kernel configuration file. This page explains the functional changes and contains other tidbits of information for kernels that have the MRG_ADB option disabled.

Current Status

The most recent HWDIRECT code, which was formerly called "ADBTEST", is now in the official kernel source.

My most recent changes will be checked into the official source tree in early-August, 1997.

When the MRG_ADB option is disabled, which in effect enables the HWDIRECT option, the ADB, RTC, and PRAM code in the kernel source access the hardware directly instead of calling routines in the ROMs. If the MRG_ADB option is enabled (which is the default for the GENERIC configuration files right now) all access to these devices are done by the MRG code, which calls routines in the ROMs.

A few details of the HWDIRECT code:

Some of the things that could be added to the code but I don't have time to do:

What HWDIRECT Provides

The HWDIRECT kernel provides the following features, grouped by ADB hardware type:

"II" Series Machines:

"IIsi" Series Machines: "Cuda" Series Machines: "PowerBook" Series Machines: (for more up to date info check out the Power Manager Patches for NetBSD page)

Current Machine Status

This section is updated as I receive reports from users who have tried the most recent kernel. I don't have access to very many Mac models, so I must rely on assistance from others for testing. See the How You Can Help section for details on how you can send me your results.

The current kernel is HWDIRECT #394

Here is the known status of all the Mac models:

[ Green Ball ]Machine has been tested - ADB and all other functions seem to be working.
[ Blue Ball ]Machine should work, but has not been tested.
[ Cyan Ball ]Machine has not been tested, but probably currently does not work completely, due to ADB issues.
[ Purple Ball ]Machine has not been tested, but probably currently does not work, due to issues unrelated to the ADB support.
[ Red Ball ]Machine has been tested and is not working, with further explaination of the problem.

"II" Series Machines:

"IIsi" Series Machines: "Cuda" Series Machines: "PowerBook" Series Machines:
These probably do not work because of internal video issues. (for more up to date info, and possibly working kernels, check out the Power Manager Patches for NetBSD page.)

Obtaining HWDIRECT Kernels

All the kernels I generate are named "HWDIRECT" kernels, instead of the more familiar GENERIC name. They are will also include a number after them, which is a "version" tag for the kernel that is updated with each kernel compile.

The most recent kernel is HWDIRECT #394. Be sure to read the Current Status and Affected Machines sections for more details about this kernel.

The older ADBTEST kernels may also be available. For more details, check out the NetBSD/Mac68k ADB 'Past Kernels' Page.

Using the HWDIRECT Kernels

These directions assume that you already have NetBSD 1.1 (or later) mostly installed on your system and you have already tried (perhaps unsuccessfully) to boot using some kernel image. For instructions on how to install NetBSD on your Mac, please see the Index to Ender's Notes, which can point you to some documentation.

In order to use one of the HWDIRECTT kernels, the first thing to do is to download the one you are going to try. See Obtaining HWDIRECT Kernels for the list of available kernels. The kernels are always gzipped to save space, so the resulting file will be named something like HWDIRECT.xxx.tar.gz.

Once you download the file, you must gunzip the file. There are two ways to do this:

Then just use the Booter to specify the correct kernel (whether in a NetBSD partition or in MacOS) and see what happens. See How You Can Help for how to let me know your results.

Note: If you have more ADB devices than simply a mouse and keyboard, and the mouse and/or keyboard doesn't work, try removing the other ADB devices from the ADB chain.

Note: If you boot with this kernel located in MacOS, or the kernel is located in the NetBSD partition and the kernel name is not "/netbsd", then you may experience problems with the "ps" command, the "identd" process, and other things. If the kernel works for you and you plan on running it for any significant amount of time, please save a copy of the existing "/netbsd" and install the HWDIRECT kernel as "/netbsd".

Obtaining HWDIRECT Kernel Patches

GOOD NEWS: The HWDIRECT code is now part of the official source tree, so no patches are required! Simply sup the -current kernel from the NetBSD sup server and comment out the MRG_ADB option in your kernel config file.

For those of you that roll your own not yet -current kernels, here are the most recent patches:

Please be careful when installing these patches. They may already be in your kernel source.

How You Can Help

If you try one of the HWDIRECT kernels, please send me email and let me know the results. I don't have access to very many Mac models, so I depend on net testers to assist me in determining how well a new kernel works on various machines.

If you try one of the kernels, and it does not work, please mail me the the contents of the /var/log/messages file if you can. Even if you can't boot NetBSD, you may be able to cpout the file from NetBSD to MacOS using the Installer. This file will help me to determine what the problem actually is.

If you can't get to this file or it doesn't exist, at least let me know where the kernel failed and what it said. I don't always need a verbatum listing of everything, just let me know the last few messages before the panic, trap, or hang.

If you use the source code to compile your own kernel, and find that you need to (or want to) make changes in my code, please send me email about it. This is especially true if anyone adds support for a new type of ADB hardware. If people let me know the changes they make, I can update the patches at this site so that others can benefit from the effort.

Acknowledgements

There are a number of people that I wish to thank for helping me with this project:

Disclaimer

I don't claim that any of the information presented on this page or any other of my web pages is accurate or correct, or that any of the code you get from this or any other page will actually work. You take full responsibility for consequences of and/or liability for using any information, source code, executable images, or anything else obtained by this document or any other documents made availble via this web page, regardless of the method you obtained them. An additional disclaimer may be posted at the head of any source code you obtain here.

Copyright © 1996,1997 John P. Wittkoski
jpw@mac68k.org