WL:whiite-linux

From gc-linux

Jump to: navigation, search

whiite-linux: A real implementation of a GNU/Linux system for the Nintendo Wii

Contents

Introduction

The whiite-linux system is a real implementation of a GNU/Linux system for the Nintendo Wii console enabling its use as a PowerPC based Linux computer.

Two packages form the base of a whiite-linux system. The kernel package contains a Linux kernel build designed to run on a Nintendo Wii console. On the other hand, the filesystem package contains a tarball of a root filesystem targeted for PowerPC systems.

An overview of the system and the basics of getting it installed and running is described during the next sections.

Rationale

The Nintendo Wii is a gaming console with limited memory resources as the Nintendo GameCube was. Nevertheless, it incorporates a faster processor, consumes less power, and has a richer set of peripheral options. It is a relatively silent system as well, at least when the DVD unit is not spinning, and has a small thermal footprint.

All of these characteristics make the Nintendo Wii console suitable for becoming a small PowerPC Linux system on the cheap.

System Overview

The whiite-linux system is a non-intrusive extension to the Nintendo Wii: the console is not modified in any way by the Linux system.

Both the kernel image file (boot.elf / ppcboot.elf) and the operating system files reside on an external SD card inserted into the front SD card slot of the console. The SD card used can contain both Linux files and Wii save data or channel data information. It is recommended, though, that a special SD card for homebrew-only purposes is used to avoid accidental loss of Wii data information by mistake.

The system boots with the help of an existing "bootloader", like the Twilight Hack or the Homebrew Channel.

Once the "bootloader" hands control to the kernel, it configures the available hardware, locates and mounts the root filesystem stored on the SD card, and continues with the system initialization process.

Hardware

The hardware supported by the system depends highly on the version of the gc-linux kernel used.

Please, see the hardware support chart to determine what hardware is supported for a particular release.

Manual Installation

The following sections explain how to get the whiite-linux system installed into an empty SD card of your choice.

 DISCLAIMER:
 
 THE FOLLOWING PROCESS WILL ERASE THE CONTENTS OF YOUR SD CARD.
 BACKUP THE DATA ON THE SD CARD BEFORE CONTINUING IF YOU WISH TO PRESERVE ANY
 INFORMATION.
 USING PARTITIONING SOFTWARE WITHOUT UNDERSTANDING HOW IT WORKS CAN
 LEAD TO DATA LOSS.

Installation pre-requisites

 Note: Although installation via other operating systems may be possible, the
       following instructions apply to Linux operating systems only.

The installation of the whiite-linux system has the following requirements:

  • a working Linux system, where you can run root-privileged commands
  • an SD card reader
  • an SD card (512 MB minimum, 2 GB or greater recommended)
  • partitioning software, like the fdisk utility
  • FAT16 and ext2/ext3 filesystem utilities, like the mkfs.vfat and mkfs.ext3 utilities
  • GNU tar software with support for bzip2 compressed archives
  • a filesystem tarball (newest is Debian Lenny 5.0)
  • a kernel tarball for The Homebrew Channel / BootMii GUI (newest is based on mikep5)
  • (opt) a kernel image for BootMii direct booting (newest is MIKE p5 (v2.6.32), choose an image matching your video mode and environment)

Featured filesystem tarballs

Distribution Tarball Release Date
Debian Lenny 5.0 debian-lenny-5.0+whiite-1.10.tar.bz2 21 Oct 2009
Debian Etch 4.0 debian-etch-4.0+whiite-0.1.tar.bz2 19 Jun 2008

Featured kernel tarballs

Environment HBC? BootMii GUI? Video mode Kernel image Release Date
IOS,MINI Yes Yes auto gc-linux-mikep5-v2.6.32+whiite-1.10.tar.bz2 6 Dec 2009
IOS Yes No auto whiite-linux-0.1a.tar.bz2 4 Jul 2008

Featured kernel images

NOTE: The MINI images are suitable for direct booting via BootMii as boot2 (install as sd:/bootmii/ppcboot.elf).

Environment Video mode Kernel image Release Date
MINI 480i PAL (60Hz) mikep5-zImage-2.6.32.mini.480i(PAL60).elf 6 Dec 2009
MINI 576i PAL (50Hz) mikep5-zImage-2.6.32.mini.576i(PAL).elf 6 Dec 2009
MINI 480p PAL (60Hz) mikep5-zImage-2.6.32.mini.480p(PAL).elf 6 Dec 2009
MINI 480i NTSC (60Hz) mikep5-zImage-2.6.32.mini.480i(NTSC).elf 6 Dec 2009
MINI 480p NTSC (60Hz) mikep5-zImage-2.6.32.mini.480p(NTSC).elf 6 Dec 2009
IOS auto mikep5-zImage-2.6.32.ios.elf 6 Dec 2009

Preparation of the SD card

Partitioning of the SD card

This procedure will create on the target SD card a primary partition for a FAT16 filesystem on the first partition, and a primary partition for a ext2/ext3 filesystem on the second partition.

For additional information about partitioning block devices, please refer to the Linux Partition HOWTO at http://tldp.org/HOWTO/Partition/fdisk_partitioning.html

  • Make sure that your SD card is inserted into your SD card reader.

From now on, the instructions will assume that your SD card is seen in Linux as a device node named /dev/sdx.

The actual device node name will depend on your Linux distribution, your SD card reader type and your existing hardware. Usually, SD cards will end up having names like /dev/sd<letter>.

 WARNING:
 
 Triple-check that you are using the right device name, otherwise you risk
 wiping other block devices including your harddisks!!!
  • Unmount all the SD card partitions, if mounted.
 $ df | grep /dev/sdx
 /dev/sdx1            501688     49488    452200  10% /media/disk
 $ sudo umount /media/disk
  • Start the `fdisk' utility from a shell prompt.
 $ sudo /sbin/fdisk /dev/sdx

Hint: you can use the 'm' command to request help

  • Remove all SD card partitions by creating an empty partition table using fdisk command 'o'.
 Command (m for help): o
 Building a new DOS disklabel. Changes will remain in memory only,
 until you decide to write them. After that, of course, the previous
 content won't be recoverable.
  • Create a primary FAT16 type partition on the first partition to store the "bootloader", your homebrew applications and/or your console save data information.

The whiite-linux system will store the kernel image file (boot.elf) on this partition requiring only a few megabytes. The size of this partition should be estimated based on the other applications requirements.

 Command (m for help): n
 Command action
    e   extended
    p   primary partition (1-4)
 p
 Partition number (1-4): 1
 First cylinder (1-984, default 1): <RETURN>
 Using default value 1
 Last cylinder or +size or +sizeM or +sizeK (1-984, default 984): +256M
 
 Command (m for help): t
 Selected partition 1
 Hex code (type L to list codes): 6
 Changed system type of partition 1 to 6 (FAT16)
  • Create a primary Linux type partition on the second partition.

The whiite-linux system will store the root filesystem contents on this partition. A minimum of 256MB is required for the basic system, but additional space will be needed if further applications are installed. Be generous with this partition's size.

 Command (m for help): n
 Command action
    e   extended
    p   primary partition (1-4)
 p
 Partition number (1-4): 2
 First cylinder (126-984, default 126): <RETURN>
 Using default value 126
 Last cylinder or +size or +sizeM or +sizeK (126-984, default 984): 984
  • Verify the partition table layout.
 Command (m for help): p
 
 Disk /dev/sdx: 2032 MB, 2032664576 bytes
 64 heads, 63 sectors/track, 984 cylinders
 Units = cylinders of 4032 * 512 = 2064384 bytes
 
 Device Boot      Start         End      Blocks   Id  System
 /dev/sdx1            1         125      251968+   6  FAT16
 /dev/sdx2          126         984     1731744   83  Linux
  • Write the new partition layout to the SD card.
 Command (m for help): w
 The partition table has been altered!
 
 Calling ioctl() to re-read partition table.
 
 Syncing disks.
  • Physically remove and re-insert the SD card to make sure that the new partition layout is in effect.

Creation of the filesystems

  • Make sure that your SD card is inserted into your SD card reader and that no SD card partitions are currently mounted.

Double-check the latter as removing and re-inserting the SD card may have triggered an automatic mounting of the newly created partitions.

  • Create a FAT16 filesystem on the first partition and label it "boot".
 $ sudo /sbin/mkfs.vfat -n boot /dev/sdx1
  • Create a ext3 filesystem on the second partition and label it "whiite".
 $ sudo /sbin/mkfs.ext3 -L whiite /dev/sdx2

Installation of the kernel image (IOS and BootMii GUI)

  • Make sure that the new FAT16 filesystem is mounted. If not, mount it over an existing directory.
 $ df | grep /dev/sdx
 $ sudo mkdir /media/boot
 $ sudo mount /dev/sdx1 /media/boot
  • Untar the kernel tarball into the root directory of the FAT16 filesystem.
 $ sudo tar -C /media/boot -xjvf /tmp/downloads/gc-linux-mikep5-v2.6.32+whiite-1.10.tar.bz2 -o --strip-components 1

Hint: If you are using The Homebrew Channel this will automatically generate a new application entry for whiite-linux on the SD card.

 $ sudo cp /media/boot/apps/mikep5.110/boot.elf /media/boot/boot.elf
  • Umount the FAT16 filesystem.
 $ sudo umount /dev/sdx1

Installation of the kernel image (BootMii direct booting)

This installation method will make your BootMii-enabled Nintendo Wii boot directly into Linux instead of the BootMii GUI.

  • Make sure that the new FAT16 filesystem is mounted. If not, mount it over an existing directory.
 $ df | grep /dev/sdx
 $ sudo mkdir /media/boot
 $ sudo mount /dev/sdx1 /media/boot
  • Save your current Broadway boot image:
 $ sudo cp /media/boot/bootmii/ppcboot.elf /media/boot/bootmii/ppcboot.old
  • Choose a MINI-based kernel image matching your video mode and copy it into the FAT16 filesystem.
 $ sudo cp /tmp/downloads/mikep5-zImage-2.6.32.mini.480i\(PAL60\).elf /media/boot/bootmii/ppcboot.elf
  • Umount the FAT16 filesystem.
 $ sudo umount /dev/sdx1

Installation of the root filesystem

  • Make sure that the new ext3 filesystem is mounted. If not, mount it over an existing directory.
 $ df | grep /dev/sdx
 $ sudo mkdir /media/whiite
 $ sudo mount /dev/sdx2 /media/whiite
  • Untar the root filesystem files into the root directory of the ext3 filesystem.
 $ sudo tar -C /media/whiite -xjvf '/home/(username)/downloads/debian-lenny-5.0+whiite-1.10.tar.bz2'

Installation Via Mac

Installation Via Mac is possible, But it is not officially supported.

You Will Need

  • A sd or Usb stick
  • An Intel Mac Running 10.3 and up
  • Either

Ext FS For Mac OS X or Ext2FsX DIdn't Work For Me (Snow Leopard)

Step 1, Partitioning

Use Disk Utility (~/Applications/Utilities/) To format your drive In ext2 *****Important, This Will Only Work If You Installed Ext FS For Mac OS X, I Don't know how to do it any other way*****

Step 2, Extracting

Now Download The FileSystem TarBall [1] and extract using terminal ( ***cd*** into expanded directory, then type ***mv * /Path/To/Ext2/Drive*** That should take 15-30 min

Step 4 Loading From Wii

You may ask why I skipped 3, well I don't like 3 Now Download Boot It!!!, from Homebrew Browser.

Step 5, Booting

Load Boot It and choose boot device and Boot!!!!

Step 6, Enjoy

Booting

Last minute hardware checks

If you own a Nintendo RVL-015 LAN Adapter, make sure that it is properly connected to your Nintendo Wii console and to your LAN.

Verify that a USB keyboard is connected to your Nintendo Wii console.

Kernel image launch

Use your "bootloader" of choice to boot the kernel image.

Note: Do not use the kernel image (zImage1.dol) that comes with the package debian-etch-4.0+whiite-0.1.tar.bz2 as that was an early debug build for internal testing purposes not intended for release.

Kernel image launch (IOS environment)

If you are using The Hombrew Channel follow this steps:

  • insert the SD card into your Nintendo Wii
  • turn on your Nintendo Wii and load The Homebrew Channel
  • select the whiite-linux icon

If you are using one of the game-based "bootloaders", please refer to one of the following articles:

Kernel image launch (BootMii GUI)

If you are using BootMii GUI follow these steps:

  • insert the SD card into your Nintendo Wii
  • turn on your Nintendo Wii and boot into BootMii GUI
  • select the SD Explorer Icon (third icon from the left on the main screen)
  • navigate to the bootmii directory
  • select the mikep5.elf file

Kernel image launch (BootMii direct booting)

If you are using BootMii direct booting just turn on your Nintendo Wii to boot into Linux.

Logon

Once the system is completely initialized, it is possible to logon to the whiite-linux system via the two pre-configured methods described below.

USB keyboard and TV (local console)

Use a USB keyboard attached to one of the USB ports on the back of your Nintendo Wii console to type your credentials.

 Debian GNU/Linux 5.0 whiite tty1
 
 whiite login: root
 Password: whiite

Secure Shell (ssh)

If a Nintendo RVL-015 LAN adapter or compatible adapter is attached to your Nintendo Wii console, the whiite-linux system will try to configure the adapter using DHCP on the existing LAN.

Also, since whiite-linux-1.10 and when booting via BootMii, the /root/whiite-ez-wifi-config tool can be used to configure the internal WLAN card of the Nintendo Wii according to your wireless network security settings.

If a network card is successfully configured, the already installed Secure Shell server of the whiite-linux system can be used to logon to the system.

Use a ssh client to connect to the IP address assigned to your Nintendo Wii console and introduce your credentials.

 $ ssh root@192.168.1.47
 root@192.168.1.47's password: whiite

Usage and Operation

While running whiite-linux, your Nintendo Wii acts as a standard Debian system.

Plese, refer to http://www.debian.org/doc/ for information on how to operate a Debian system.

Important Notes:

  • Change your root password.
  • Remember to properly shutdown your Nintendo Wii console when using whiite-linux or you risk corrupting your mounted filesystems. You can shutdown your console via the 'poweroff' command, by pressing and holding the reset button or by pressing CTRL-ALT-DEL on your attached USB keyboard.

Example Customization Hints

Setting up the keyboard layout

By default, the whiite-linux system comes configured with a Spanish keyboard layout.

Use the following command to configure your keyboard layout:

 # dpkg-reconfigure console-data

Setting up the timezone

By default, the whiite-linux system comes configured with a timezone for Europe/Madrid.

Use the following command to configure your timezone:

 # dpkg-reconfigure tzdata

Setting up the locale

By default, the whiite-linux system does not come configured with a locale. This is important to set for perl to build text based windows on many applications. It may help to configure some swap before running this command.

Use the following command to configure your locale:

 # dpkg-reconfigure locales

apt-get magic

When connected to the internet it is possible to use the Debian Internet-based software repositories to install new software on your whiite-linux system.

Keep your system up-to-date

 # apt-get update
 # apt-get upgrade

Install pakage foo

 # apt-get install foo

Remove package foo

# apt-get remove foo

DOs And DON'Ts

  • The Nintendo Wii has only 24MB of "primary" RAM. The original whiite-linux system uses just that as RAM, and another ~52 MB of a secondary slightly slower memory as a swap device. Since the 2.6.27 release, the gc-linux kernel image can use both the primary and the secondary memory as normal RAM. In any case, DON'T try to install software which has greater RAM requirements than those specified or the system will become slow and/or unusable.
  • The current gc-linux kernel framebuffer implementation provides a false RGB framebuffer, so DON'T try to use applications that use directly the fb or the image will get displayed with the wrong colours and or format. Instead, DO use applications that use the fb through the gc-linux SDL library port or the xf86-video-cube X driver which are aware of the issue and do The Right Thing (TM). This issue will be addressed in the future in a different way.
  • DON'T manually down the bluetooth interface or you will need a reboot to up it again (this is a known issue).

Mini-FAQ

  • Q: How can I use the Nintendo Wii Remote in whiite-linux?
  • A: You can use one of the existing software packages for Linux. The Nintendo Wii Remote is used in whiite-linux exactly in the same way it is used in a normal Linux system. The Wiimote has been at least successfully tested with wminput from the cwiid 0.6.00 package.
  • Q: The sensor bar doesn't work.
  • A: Please, have a look at the GPIO driver article to learn how to enable it.
  • Q: What extra hardware do I need in order use whiite-linux ?
  • A: A USB keyboard is recommended.

DISCLAIMER

 IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR
 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 ON AN "AS IS" BASIS, AND THE AUTHOR HAS NO OBLIGATION TO
 PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Thanks

The usual suspects:

  • Team Twiizers
  • the wiibrew.org community
  • the libogc team

Unusual suspects:

  • Maarten ter Huurne for helping in getting the IOS-based USB HCD (rvl-sthcd) out
  • gc-linux.org's hopeful random irc visitors and idlers

Special thanks go to the Debian project contributors.

Personal tools