WL:whiite-linux
From GamecubeLinux Wiki
whiite-linux: A real implementation of a GNU/Linux system for the Nintendo Wii
This is a wikified version of the readme.txt file included in whiite-linux-0.1a.tar.bz2.
| Table of 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.
The package debian-etch-4.0+whiite-0.1.tar.bz2 contains a tarball of a standard "barebones" debootstrapped Debian 4.0 (etch) root filesystem targetted for PowerPC systems. In addition, the package whiite-linux-0.1a.tar.bz2 contains a Linux kernel build designed to run on a Nintendo Wii console.
Combined, these two packages form the base of the whiite-linux system.
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) 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.
The system displays a login banner once it is ready for use.
Hardware
The hardware supported by the system depends highly on the version of the whiite-linux kernel used.
Supported Hardware
The following hardware/peripherals are supported:
"Classic" hardware
- Non-accelerated 2D video hardware (VI)
- Note: correct RGB framebuffer support requires our SDL library port
- Note: video mode settings do not account for TV overscan
- Audio hardware (AI,DSP)
- EXI hardware (EXI)
- Nintendo SD Card Adapter (DOL-019) or compatibles
- Non-SDHC MMC/SD cards in SPI mode via a Nintendo DOL-019 or compatible
adapter
- Real Time Clock / SRAM
- Serial Interface hardware (SI)
- Nintendo GameCube controllers
- Nintendo GameCube WaveBird wireless controllers
"Native" hardware - MEM2 memory as a volatile block device - Non-SDHC SD cards in SD mode via the front SD card slot - Internal USB Bluetooth dongle - Nintendo Wii Remote (RVL-003) and related expansion accessories - External USB devices: - USB Hubs (only partially supported) - USB Mass Storage Devices (pen drives, hard disks, card readers, etc.) - USB Human Interface Devices (keyboards, mice, etc.) - USB network adapters (RVL-015, etc.)
Unsupported Hardware
The following hardware/peripherals are NOT supported:
"Classic" hardware - Nintendo GameCube memory cards
"Native" hardware - Internal wireless network card - USB devices using isochronous transfers (mainly audio-related USB devices) - Sensor bar
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 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
- http://downloads.sf.net/gc-linux/debian-etch-4.0%2Bwhiite-0.1.tar.bz2
- http://downloads.sf.net/gc-linux/whiite-linux-0.1a.tar.bz2
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/rvlsda.
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/rvlsda /dev/rvlsda1 501688 49488 452200 10% /media/disk $ sudo umount /media/disk
- Start the `fdisk' utility from a shell prompt.
$ sudo /sbin/fdisk /dev/rvlsda
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/sdc: 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/rvlsda1 1 125 251968+ 6 FAT16 /dev/rvlsda2 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/rvlsda1
- Create a ext3 filesystem on the second partition and label it "whiite".
$ sudo /sbin/mkfs.ext3 -L whiite /dev/rvlsda2
Installation of the kernel image
- Make sure that the new FAT16 filesystem is mounted. If not, mount it over an existing directory.
$ df | grep /dev/rvlsda $ sudo mkdir /media/boot $ sudo mount /dev/rvlsda1 /media/boot
- Untar the kernel image file into the root directory of the FAT16 filesystem.
$ sudo tar -C /media/boot -xjvf /tmp/downloads/whiite-linux-0.1a.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.
- (Optional) If you are using the Twilight Hack, copy the kernel image file to the root of the FAT16 filesystem on the SD card.
$ sudo cp /media/boot/apps/whiite-linux/boot.elf /media/boot/boot.elf
- Umount the FAT16 filesystem.
$ sudo umount /dev/rvlsda1
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/rvlsda $ sudo mkdir /media/whiite $ sudo mount /dev/rvlsda2 /media/whiite
- Untar the root filesystem files into the root directory of the ext3 filesystem.
$ sudo tar -C /media/whiite -xjvf /tmp/downloads/debian-etch-4.0+whiite-0.1.tar.bz2
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 (boot.elf).
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.
Please, refer to the following articles for additional information about "bootloaders":
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 4.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. If 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 4.0 (etch) 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:
# tzconfig
apt-get magic
When connected to the internet via a Nintendo RVL-015 LAN Adapter or compatible adapter 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 whiite-linux system uses just that as RAM, and another ~52 MB of a secondary slightly slower memory as a swap device, so DON'T try to install software which has greater RAM requirements or the system will become slow and/or unuseable.
- The current whiite-linux 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 colors and or format. Instead, DO use applications that use the fb through the gc-linux SDL library port which is aware of the issue and does 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: Yes, we didn't add code yet to set the bit that turns on the sensor bar.
- Q: What extra hardware do I need in order use whiite-linux ?
- A : usb keyboard should be enough
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 new USB HCD baby out
- gc-linux.org's hopeful random irc visitors and idlers
Special thanks go to the Debian project contributors.
