
README!

debian-etch-4.0+whiite-0.1.tar.bz2
whiite-linux 0.1 root filesystem tarball, based on Debian 4.0 (etch)
20 June 2008, Albert "isobel" Herranz

whiite-linux-0.1a.tar.bz2
whiite-linux 0.1a kernel image
4 July 2008, Albert "isobel" Herranz


http://www.gc-linux.org


1. 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.


2. 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.


3. 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.


4. HARDWARE

  The hardware supported by the system depends highly on the version of the
  whiite-linux kernel used.
  Please, check http://www.gc-linux.org for a complete list of the hardware
  supported/unsupported.

4.1 Supported Hardware

  As of this writing, 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.)

4.2 Unsupported Hardware

  As of this writing, 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


5. MANUAL INSTALLATION

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

  Those in a hurry can go directly to "APPENDIX A. QUICK SD CARD INSTALLATION
  OVERVIEW".



  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.



 5.1 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
  - a SD card reader
  - a 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

 5.2 Preparation of the SD card

  5.2.1 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.


  5.2.2 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


  5.2.3 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 mount /dev/rvlsda1


  5.2.4 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  


6. BOOTING

 6.1 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.

 6.2 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:

  http://wiibrew.org/wiki/Twilight_Hack
  http://wiibrew.org/wiki/Homebrew_Channel


7. 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.

 7.1 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

 7.2 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


8. USAGE AND OPERATION

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

  Plese, refer to the following site for information on how to operate
  a Debian system:

  http://www.debian.org/doc/

  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.


9. EXAMPLE CUSTOMIZATION HINTS

 9.1 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

 9.2 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

 9.3 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.

  9.3.1 Keep your system up-to-date.

    # apt-get update
    # apt-get upgrade

  9.3.2 Install pakage foo

    # apt-get install foo

  9.3.3 Remove package foo

   # apt-get remove foo


10. 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).


11. 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.


12. 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.


13. 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.

  A big welcome to this world goes to Luca.


APPENDIX A. QUICK SD CARD INSTALLATION OVERVIEW

  * Get a non-SDHC SD card of at least 512 MB.
  * Create a FAT16 filesystem on the first partition of your SD card.
  * Create a ext3 filesytem as larger as possible (of at least 300 MB)
    on the second partition of your SD card.
  * Untar the contents of the package whiite-linux-0.1a.tar.bz2 to the root
    directory of the FAT16 filesystem.
  * Untar the contents of the package debian-etch-4.0+whiite-0.1.tar.bz2 to
    the root directory of the ext3 filesystem.
  * Boot the whiite-linux application from the Homebrew Channel.


APPENDIX B. EXAMPLE BLOCK DIAGRAM

  Fig A. An ASCII-art block diagram showing a sample for Nintendo Wii console
         used as a Linux system

                                   +-------------+
                                   | _________ ..|
     _--_--_                       |/         \oo|
    / +   A \ GameCube Controller  ||         |oo| TV 
   /  ___b_  \                     ||         |oo|
   \_/|    \_/                     |\_________/..|
      |                            +-------------+
      |
   +--|----------------------------------------------+                  x---x
   |  |                                              |                  |   |
   | (*) ( ) ( ) ( )              [======]           |                  | + |
   | GameCube controller ports    Front SD Card Slot |                  |(A)|
   |                                                 |                  |   |
   | +---+ +---+                         ........... |                  |   |
   | |USB| |USB|                         :Bluetooth: | (((((((((( |   |
   | +-^-+ +-^-+                         ........... |                  | 1 |
   |   |     |                                       |                  | 2 |
   +---|-----|---------------------------------------+                  x---x
       |     |                    Nintendo Wii console                Wiimote
       |     |
       |     \--------------------------\
       |                                |
     +-V--------+                     +-V-------+      +-------------------+
     |USB Hub   |                     | RVL-015 <======>Ethernet hub/router|
     +-^----^---+                     +---------+      +--^----------------+
       |    |                                             |
       |    |                                             |
       |    \------------\                                |   _   _
       |                 |                               / \_/ \_/ \
     +-V-------------+  +V-+                            /           \
     |ooooooooooooooo|  |00|                           (  Internet   )
     | ooooooooooooo |  |  |                            \   _   _   /
     +---------------+  +--+                             \_/ \_/ \_/
      USB Keyboard       USB Mouse



