Making a Linux distribution Xbox compatible HOWTO
From Xbox-Linux
Vandalism shit removed by Xero.
(originally by Michael Steil)
Basically the Xbox is a PC, so standard i386 Linux can run on it. Still there are some small differences, mostly related to protection, that make it somewhat different and require some modifications in Linux.
Of course it is possible to write a Linux distribution for the Xbox from scratch, but as it is so similar to a PC, it makes more sense to just modify an existing distribution to be Xbox compatible. The great thing about it is that an Xbox-enabled boot or installation CD can run both on the Xbox as on the PC. This HOWTO describes how a modified Xbox works and summarizes the steps you need to take as a developer.
| Table of contents |
|
1.1 Unmodified Xbox |
Xbox Boot Process
The Xbox does not have a PC-style BIOS so it does not boot like a PC. By default, it even only accepts signed executables. There are several ways to modify an Xbox.
Unmodified Xbox
The Xbox only runs Xbox executables (XBEs) signed with the Microsoft retail key. This key is only known to Microsoft, so there is currently no way to produce a boot CD that will be accepted by a standard Xbox as if it was a game. Nevertheless, this section describes how an Xbox starts and where it boots from, so that it is easier to understand the various hacks.
- spin up hard drive and DVD drive, initialize Xbox kernel, show the boot animation
- unlock the hard drive, panic if unsuccessful
- mount the CD/DVD (either UDF or GDFS filesystem)
- run default.xbe from the root of the CD/DVD
- if mounting or running the XBE fails, mount partition C: on the hard disk and run C:\xboxdash.xbe
Software Exploit
Some Xbox games have buffer overflows in their savegame loading code, which can be exploited. MechInstaller for example includes a savegame "Emergency Linux" that runs a default.xbe that is included with the savegame. In order to make it impossible to use our hack for game piracy, the savegame only runs default.xbe if it is signed with the Xbox Linux key, which is only known by a few people.
Software Method
The Software Method modifies the Xbox system software in two ways:
- The Xbox Dashboard also accepts XBEs from CD/DVD signed with the Xbox Linux key.
- The Dashboard includes an item "LINUX" which runs E:\debian\default.xbe (or, if the first file is not found, C:\linux\default.xbe) from hard disk. This executable also has to be signed with the Xbox Linux key.
Hardware Method
The Hardware Method overwrites the onboard flash chip with Cromwell, a firmware replacement that includes a boot menu and a Linux bootloader not unlike GRUB or LILO. This method completely replaces all Microsoft code, so it is not possible to run XBEs (and thus games) any more.
Modchips with Linux Bootloader
Modchips like SmartXX include Cromwell boot code and can boot exactly like Cromwell.
Patched Microsoft Kernel
SECTION DELETE LEGALITY QUESTIONABLE!!!
Xbox Linux Bootloaders
There are two bootloaders for Xbox Linux: xbeboot and Cromwell.
xbeboot
xbeboot is an XBE file that must be executed (from CD/DVD or hard disk) from inside the original Xbox system environment. It loads linuxboot.cfg from the same directory, which contains, in LILO-style, the kernel and initrd filenames, as well as the kernel parameters.
xbeboot is open source (GPL), so you can adapt and compile it yourself. But if you want to run it on a "Software Method" Xbox, it must be signed with the Xbox Linux key, so better just use the signed binary version included with MechInstaller.
Cromwell
Cromwell is a firmware replacement, boot menu and Linux bootloader that can be written into the Xbox onboard flash or onto a modchip. The user can choose to boot from hard disk (FATX, ext2/3 or ReiserFS formatted), DVD (ISO formatted) or network (Etherboot). When booting from the Hard Disk/DVD drive a configuration file named linuxboot.cfg is required. See the Cromwell Manual for more details.
Cromwell can also be compiled as an XBE ("Xromwell"), so it can be run from inside the Xbox kernel environment and you still have features like network booting. There is no signed Xromwell for MechInstaller use.
Step by Step
This is an overview of the steps you should take to make your Linux distribution Xbox compatible.
Get a Modified Xbox
We suggest to have a 1.0 to 1.4 Xbox with a good DVD drive and a modern modchip, as this can speed up development significantly, and you can test all the different modifications with this setup. Backup the complete hard disk. Install Cromwell onto your modchip, so you can use the Etherboot option to load your kernel and initrd during development. Replace the DVD drive with a standard IDE CD/DVD, as it will read your CDs more reliably.
Install Xebian
Xebian is the reference distribution. Use it as a base to experiment with.
Patch your Kernel
A vanilla Linux kernel will crash on the Xbox because of a bug in the nForce chipset. Also the system timer would be off by 6% and it would be impossible to eject the DVD drive, which is not completely standards compliant. Additional code handles the TV-out chip and makes sure the video output is in sync with the internal VGA signal. The Xbox-Linux CVS (http://sourceforge.net/cvs/?group_id=54192) contains files that need to be modified in kernels 2.4 (module "kernel") and 2.6 (module "kernel-2.6") for full Xbox compatibility as well as documentation on how to apply the patch and recommended settings for the Xbox.
Compile an Xbox-compatible version of your kernel and test it. If it does not boot, try a vanilla kernel with the Xbox patches and add your patches one by one. Give your Xbox kernel the same name (don't add "-xbox" or the like) as your PC kernel, so that they can share the kernel modules.
As soon as the kernel boots and you see something on the Xbox screen, create an initrd that mounts root over NFS, as this will speed up your development significantly. If you are working with a Linux system that will install on hard disk, start working on an installed system first, then have a look at the installer.
Patch X
The CVS also includes a modified nVidia graphics chipset driver (module "XFree86") that controls the TV-out chip to match the resolution of the VGA hardware. It is recommended to include this driver, otherwise the user could only use the single resolution set up by the framebuffer driver and there would be no 2D (video) acceleration.
Add Swap
The Xbox only has 64 MB of RAM, of which 4 MB are continuously used for the framebuffer. Although it is possible to upgrade older Xboxes to 128 MB of RAM (and Cromwell/Linux will automatically detect this), most Xboxes must be able to cope with as little as 60 MB of effective memory. No matter whether your distribution is a live system or the boot CD is an installer, it may need more than 60 MB or RAM. On a Linux-only Xbox, it is of course possible to create a swap partition, just like on a normal PC, so include code in your init scripts that enable swap space. Scan through the partitions on /dev/hda and turn on swap if a partition has the swap signature.
On dual-boot Xboxes, there are two ways to have swap space. One possibility is to simply create a swap file in E:\debian. 256 MB is usially a good choice. Another possibility is to use one (or more) of the three "temp" partitions (750 MB each!) on the Xbox hard disk. They are used to cache game data and can be overwritten without any harm. So a Linux live CD can do:
mkswap /dev/hda52 && swapon /dev/hda52
This will create the swap signature on the first temp partition and enable it as swap space. If the hard disk is not configured for dual-boot and does not contain Xbox temp partitions, the instructions will just fail without doing any harm.
Add User Mode Tools
The CVS includes some user mode tools that are quite handy on Xbox Linux and should be bundled with any distribution:
- raincoat - overwrite the onboard flash; useful when doing the Hardware Modification
- blink - control the Xbox LED (See PIC page (http://www.xbox-linux.org/wiki/PIC#The_LED) for color codes)
- fancontrol - control the speed on the system fan
- temp - print out the cpu and system temperatures, as well as the fan speed
- xbox_info - print information about the Xbox hardware
Patch the Installer
If your system installs on hard disk, you have to patch the part of the installer that has to do with hard disk partitioning, partition selection and boot loader installation.
You can easily autodetect whether the installer runs on an Xbox or a PC, because the Xbox will boot a different kernel than the PC and can therefore have a different kernel command line passed, so it enough to scan /proc/cmdline for something like "xbox".
Dual Boot
If the "Software Modfication" has been done or a patched Microsoft kernel is used, the Xbox can run both games and Linux. Therefore, Linux can only exist in images files on existing partitions (typically E:, which should have about 4.7 GB free). For the Software Modification, Linux has to be installed into E:\debian, i.e. the "xbeboot" default.xbe has to be located there, and it is also a good idea to place the kernel, the initrd and the root filesystem image there. For a patched Microsoft kernel, Linux can be placed ahywhere on hard disk.
Note: The kernel 2.6 patches currently do not include a stable FATX driver, so it is impossible at the moment to run a 2.6 Linux on a dualboot Xbox.
We can detect whether it is a dual-boot machine by checking whether /dev/hda50 exists. If it does, then the original Xbox partitioning is still intact - but this could also mean that the original partitioning has just not been deleted yet. So the user must be asked whether the Xbox should remain dual-boot. If no, see section Linux Only below.
If yes, ask where to install Linux: Ask for a partition (E = /dev/hda50, F = /dev/hda55 or G = /dev/hda56, do not accept C = /dev/hda51) and a directory. Default to E:\debian, as this is the path MechInstaller expects the Linux installation.
If Linux gets installed into an image on a FATX partition, make sure the kernel and initrd that get installed include FATX filesystem and loop device drivers and code to correctly mount the image file.
Linux Only
If the "Hardware Modification" has been done or a Linux modchip is used, the standard code for partitioning and partition selection can be used, and the bootloader installation will just be skipped, as Cromwell will autodetect Linux on the hard disk.
Create the Boot CD
Cromwell can only boot from ISO CDs/DVDs, and xbeboot only accepts UDF CDs/DVDs, so it is important that a boot/install CD/DVD is in hybrid ISO/UDF format. "mkisofs -udf" does the trick.
Include the default.xbe from MechInstaller to the CD for Software Method/Patched Kernel boot. Include linuxboot.cfg for any Xbox boot (xbeboot or Cromwell). Add "xbox" to the kernel parameters in linuxboot.cfg, and do not include it to the parameters for PC boot.
Test the CD/DVD with different Xbox modification setups. If you have trouble with the built-in Xbox DVD drive, look at the Xbox Linux Boot CD/DVD Burning HOWTO.
Questions
If you have any questions or need support, contact Michael Steil or ask in the IRC channel.
