Penguin - HOWTO

At the Top of the Iceberg

1. System Requirements or... Before You Boot
2. 1-2-3 Boot...
3. Settings dialog explained
4. Still can't boot?
5. The Penguin Menus

System Requirements or... Before You Boot

• 4 MB RAM is the bare minumum - more is required for large RAM disks and kernels.
• System 7.0 or later (7.5 for IIsi and IIci)
• MacOS in 32-bit mode (Memory control panel). Requires the MODE32 extension if your Macintosh ROM is not 32-bit clean
• SCC IOP in compatible mode (Serial Switch control panel). This only applies to IIfx, Quadra 900 and 950.
• MacOS RAM disk and Virtual memory should be disabled (Memory control panel)
• RAMDoubler, Pseud040 and SoftwareFPU extensions should be disabled if present (Extensions Manager control panel)
• Linux kernel image
• RAM disk image ("initrd") unless you're booting a hard disk partition
• Your favorite mug filled with hot java and 1 oz. patience

1-2-3, Boot...

1. Start the Penguin.
2. Select "Settings" from the File menu to bring up the configuration options dialog.

   Use the "Kernel:" button to select the kernel binary to use. Either gzip'd (vmlinuz) or uncompressed (vmlinux) binaries can be used, but because of a known bug, Penguin may fail to boot a large compressed kernel binary.

   Use the "RAMdisk:" button to select an initrd image unless you will be using a disk partition as your root filesystem.

   Enter the command line to use. If you're using a RAM disk as root you should enter root=/dev/ram If you have prepared a root filesystem on a hard disk partition, you'll need the relevant disk id and partition number. You can use the "Show SCSI Info" menu choice to find these. Something like root=/dev/sdXY; where X is the disk id ('a'-'p') and Y the partition number. For IDE drives, use root=/dev/hdXY. Common hard disk command lines are root=/dev/sda4 and root=/dev/sdb4.

   You don't need to touch any of the other options so hit the "OK" button.

3. Select "Boot Now"

   Did you reach the login prompt? Did you see any output from the Linux kernel? If not, see below.

Settings dialog explained

Some of the options in the Settings dialog can be a bit difficult to understand. Here is a brief explanation of each option: what it does and when you should use it.

Debugging output: [optional]

This item consists of several suboptions each giving you an additional piece of information about your machine during the boot process. If all went well and you're not interested in what the Penguin thinks about your machine then leave them all unchecked. They're here for informational purposes only. If you're going to file a bug report please turn all options on and select a log file in which the output from your failing boot will be saved.

Kernel: [mandatory]

This is were you specify what kernel image (aka kernel binary) to use. The file is the most important one of them all. This file is Linux, you won't get very far without it. Recent kernel images can be found on the downloads page. Penguin accepts both gzip'd and plain kernel images. Penguin-18 and later also accept bzip2-compressed kernels. Zipped kernels will be unzipped before each boot-up, causing a delay and a slight increase in memory requirement compared to loading an uncompressed kernel. So if you have little RAM and/or time, you may want to unzip the kernel image.

Ram disk: [optional]

If you have not prepared a hard disk partition to use as your Linux root filesystem (/) you will have to select a RAM disk image. A RAM disk usually contains a minimal file system for installing or testing. This is a good thing to use the first time you try Linux on your machine, it is a fast and easy way to determine if your Mac is Linux compatible.

Log file: [optional]

By checking this option and selecting an output file the debug output during the Penguin boot process will be mirrored and saved into the file of your choice.

Command Line: [mostly mandatory]

These command line options are kernel arguments. Some kernels can handle certain arguments that others can't. The most commonly required argument is the root filesystem Linux should use.

The "root" device that needs to be specified here will depend on your setup. The base option is root= followed by the (Linux) name of the disk partition or device, if you are using a RAM disk this will always be: root=/dev/ram.

If you are going to use a hard disk partition as "root" you must know the Linux naming scheme of devices. All SCSI hard disks have the base name "/dev/sd" with the disk and partition number appended ("/dev/hd" for IDE drives). The first hard disk found will have 'a' appended to "/dev/sd" giving us "/dev/sda". The second disk found will be named 'b' giving us "/dev/sdb" etc.

To these names the partition number is also appended. The partition count includes every partition on the disk including partition map, driver etc. Often the first "usable" partition is partition number four, thus the first partition found would have the name "/dev/sda4" and the command line would be: root=/dev/sda4.

If you have initialized and prepared a partition to use with Linux you probably already know what name to use. You can always use "Show SCSI Info" on the "Hardware" menu to get a listing of your connected SCSI devices, partitions, and their Linux names.

The command line options are separated with a space (blank), for instance: root=/dev/ram earlyprintk

Auto Boot On Prefs File Open: [optional]

Check this option if you would like the Penguin to boot automatically upon opening the settings (without waiting for the "Boot Now" menu command). To temporarily disable this behavior, so as to be able to change the settings, hold down the <command> key while Penguin is starting or when you open a settings file that has this option set.

Don't Actually Boot: [optional]

If you would like to try a dry-run to see the output produced when the debug options are used, check this option and Penguin will not take the final step or leap into the kernel. This will allow you to examine the output.

Color by Penguin: [optional]

This option will change the hardware palette your display is using. This is useful for those display cards that have only basic support in Linux, when would like to have the familiar white text/black background Linux look. The palette is a standard (S)VGA palette so if you do a "ls --color" in Linux you should get the same results as on an Intel machine. If you're using a monochrome display, try adding "video=inverse" to the kernel command line.

Delay boot: [optional]

If, for some reason, you need to do work on your Mac between the time you tell Penguin to boot and the time it actually boots into Linux, check this option and specify a delay time. Could be useful in conjunction with the "Auto Boot" option.

Pre-configure ("warm up") serial ports: [optional]

As of Penguin 18, you can use this option to configure the baud rate, frame size, parity and stop bits for the Printer and Modem ports. Some old kernel releases had SCC initialization bugs and this option served as a workaround.

On PowerBooks, the serial ports are subject to power management but the Linux/mac68k serial driver does not power them up. This option gets the MacOS serial driver to do it before Linux starts up.

This option should not be used with the Centris/Quadra 660av or 840av. The combination can lead to DMA transfers which corrupt memory while Linux starts up, resulting in a crash.

Use old RAM detection: [optional]

NOTE: This option has been removed from Penguin 18.

Since the release of Penguin 0.4.d14 (a.k.a Penguin-14) a new memory detection method is used by default. Should you get an error message early in the Penguin boot process saying "Failure while reading MMU tables...", check this option and try to boot again.

Don't Disable Video Card VBL's: [optional]

NOTE: This option has been removed from Penguin 18.

To let the kernel initialize its environment in peace we try to shut down as much as possible of MacOS, including the interrupts your video card generates. Some video cards do not support this and Penguin will give you an error at the very end of the boot, after the message "slot_int_set...". To suppress the error message please check this option. The effect is the same - the interrupts will not be disabled.

68020: Don't force kernel into bank A: [optional]

NOTE: This option has been removed from Penguin 18.

This is a special option for the 68020 and MacII owners only. It has to do with the physical arrangement of the memory banks in the MacII. Normally this option should NOT be checked. If you own a MacII that hangs at the end of the Penguin boot, check this option and try again.

Enable external cache: [optional]

NOTE: This option has been removed from Penguin 18.

Some of the Mac's were equipped with external caches, the IIci has a cache expansion slot and the IIvx has this cache soldered on the main logic board. Clear this option if your Mac is equipped with an external cache and you get unexpected errors (bus faults, address errors) in Linux.

Still can't boot?

Certain devices, such as network cards, if enabled by MacOS, can cause a hang shortly after Penguin launches the Linux kernel. This happens when such devices generate interrupts before the Linux kernel has had a chance to load its device drivers. If you encounter this problem, boot MacOS with extensions disabled so as to keep these devices quiescent. MacOS extensions are easily disabled by holding down the <shift> key when you hear the startup chime. (You can also use the Extensions Manager control panel to disable particular extensions, if you know which devices are problematic.)

How long should I wait after "Booting Linux (fasten seat belts, please)..."?

About 10 to 15 seconds is the time it takes a Mac IIci to leave Penguin and enter the kernel. If nothing happens after a minute then Penguin, MacOS or Linux probably crashed.

My Mac is stuck at "slot_int_set ..."

This problem has several possible causes. One is a bug in Penguin that affects decompression of large kernel binaries. The workaround for this is to decompress the kernel binary first, so Penguin doesn't have to do it. For example,

# gzip -dc < vmlinuz > vmlinux

Another possible cause is use of System 7.0 or 7.1 on a Mac IIci or IIsi. There is a bug in the video drivers and Penguin can't do much about that. The solution is to upgrade to 7.5.x which has new, working, versions of the video drivers.

"Unable to allocate memory for kernel..." What does that mean?

This error indicates that the Penguin application's memory partition is not large enough to allow the Penguin to load the kernel and RAM disk. You'll have to increase the default memory partition for the Penguin application ("Get Info" in the Finder).

"Failure while reading MMU tables ..."???

The Penguin needs to collect information about your memory configuration, for reasons unknown it failed while doing so. This is when the "Use old RAM detection" setting can be useful, set that option and try to boot again.

The Penguin Menus

File

• Settings...

  Brings up the main settings dialog. This is the place were all boot parameters are set and configuration is done. See "Settings dialog explained" for information about the various parameters.

• Open Settings...

  Opens a previously saved settings file and loads the values from that file into the current setup. Double clicking or dragging-and-dropping a file onto the Penguin application will have the same effect.

• Save Settings...

  Saves the current setup into a settings file for later use.

• Save Settings As Default

  Set the current settings as your default choice, i.e. the settings that will be used every time you start the Penguin.

• Boot Now

  Starts the boot process using the current settings.

• Quit

  Exits the Penguin application.

Edit

The usual Macintosh Copy & Paste stuff. You can use the "Copy" item to transfer output from the log into other applications.

Hardware

• Show Machine Profile

  Dump current machine status. Interesting information about your Macintosh and what hardware we can expect to find inside the box.

• Show SCSI Info

  List your SCSI devices and the names Linux will give them. This can be useful if you don't know what to enter as the root filesystem on the command line.

• Show Device Mappings

  Some real hardware information about your Macintosh. This will show you the logical to physical translation of the various devices (chips) in your machine.

Written by Mikael Forselius <mikaelf@comenius.se>, March 13th 1998. Updated by Andrew McPherson <andrew@macduff.dhs.org>, May 30th 2000. Updated by Finn Thain <fthain@users.sourceforge.net>, 2007-2017 (current Penguin maintainer).