Skip to content

Commit 5a8c701

Browse files
TayTay
Tay
and
Tay
authored
Adding instruction markdowns for Debian and Gentoo (#59)
* Adding debian instructions * Adding gentoo instructions * Removing old version directive. * Adding a link. * Adding a link. * Cleanup formatting for gentoo * Cleanup formatting for gentoo again * Cleanup formatting for gentoo again * Adding a warning note about using updxell thanks to Mitchell --------- Co-authored-by: Tay <tay@xenon>
1 parent 365eeff commit 5a8c701

4 files changed

Lines changed: 353 additions & 4 deletions

File tree

‎docker-compose.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
1-
version: "3"
21

32
services:
43
wiki:
54
build:
65
context: .
76
ports:
8-
- "127.0.0.1:8000:8000"
7+
- "8000:8000"
98
volumes:
109
- ./:/wiki

‎docs/Linux/Distros/Debian/sid.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Debian on the Xbox 360 in 2025 (Sid)
2+
3+
Big thanks to all of the wonderful people working on, with and adjacent to the Free60 Project for making this possible! These are the instructions that I have been following on my adventure running Linux on the 360 in 2025. It is not bulletproof as things are in constant change for now. The result is a Debian system that boots and you can install stuff on but is not optimized **at all**.
4+
5+
Special thanks:
6+
TechFlash
7+
rwf93
8+
SED4906
9+
InvoxiPlaysGames
10+
quarky
11+
tuxuser
12+
13+
## Kernel Compilation
14+
15+
**Note** If using the dockerized toolchain you must `apt install bc` to build the kernel within the container.
16+
17+
1. `git clone https://github.com/free60project/libxenon`
18+
- Check out the README there and set up the toolchain natively or for Docker as preferred.
19+
2. Download the linux kernel source from: https://kernel.org - get version 6.16.X.
20+
3. Clone the Free60 Linux patch set: `git clone https://github.com/free60project/linux-kernel-xbox360`
21+
4. CD into that directory.
22+
5. `cp linux-kernel-xbox360/xenon-6.16.9-defconfig .config`
23+
6. Patch the kernel with `patch -p1 < ../linux-kernel-xbox360/patch-6.16-xenon.diff`
24+
7. Configure the kernel with `make ARCH=powerpc CROSS_COMPILE=xenon- olddefconfig`
25+
8. Compile the kernel with: `make ARCH=powerpc CROSS_COMPILE=xenon- all`
26+
- Pass `-j` to `make` to have it use more CPU cores. Such as `make -j6 ...`
27+
9. When finished run `cp arch/powerpc/boot/zImage.xenon .`
28+
10. This guide will focus on Debian. It may be preferable to build all the relevant .deb packages for the kernel, headers, and modules as well. This can be done with an additional command in the kernel source directory `make ARCH=powerpc CROSS_COMPILE=xenon- bindeb-pkg`.
29+
30+
At this point the kernel is compiled.
31+
32+
## XeLL Compilation
33+
34+
XeLL as the bootloader must be recompiled. The v0.993 release from years ago was built with the original toolchain and is
35+
too old to boot any binaries built with newer toolchain. At present it is easiest to build XeLL with the Dockerized toolchain but it can also be done natively with the most up to date libxenon repo.
36+
37+
1. `docker run -it -v $PWD:/app free60/libxenon:latest`
38+
2. `cd /app`
39+
3. `make`
40+
41+
The resulting `.bin` files are the updated XeLL release artifacts. There are a few options now depending on preference:
42+
- rename xell-2f.bin to `xell.bin` and place it beside a XeLL Launch binary. *JTAG consoles*
43+
- rename xell-2f.bin to `updxell.bin` and place it on the root of a FAT32 formatted USB drive. Boot via the eject button for XeLL to auto update. *JTAG consoles*
44+
- rename xell-gggggg.bin to `xell.bin` and place it beside a XeLL Launch binary. *RGH consoles*
45+
- rename xell-gggggg.bin to `updxell.bin` and place it on the root of a FAT32 formatted USB drive. Boot via the eject button for XeLL to auto update. *RGH consoles*
46+
- rebuild the NAND with the appropriate xell image as it was done originally as per whatever instructions. *any console*
47+
48+
**Very important note here! Using `updxell` should be considered a last resort and only done if you have the hardware to undo it. In certain older builds of XeLL included with Jrunner this feature can brick the NAND!**
49+
50+
## Linux Installation
51+
52+
The kernel can be set up to boot a root filesystem on the Xbox 360 Xenon platform just like any other. Research the Linux
53+
kernel documentation especially for the `boot=` and `root=` options for the kernel `cmdline`.
54+
55+
Any distro can be chosen that still supports PowerPC architectures. The Xbox 360 is capable of running both 64 and 32 bit operating systems.
56+
It is worth noting however that distros that enable the `altivec` instruction set will not work without a patched GCC and binutils. Some
57+
distros that are known to work at time of writing:
58+
- ArchPOWER
59+
- Already works on Wii
60+
- Gentoo openrc ppc64
61+
- Debian sid ppc64
62+
63+
This guide will focus on Debian forky/sid ppc64 with systemd.
64+
65+
### Prerequisites
66+
67+
One must install these packages on their host operating system:
68+
- qemu
69+
- qemu-user-static
70+
- qemu-system-ppc
71+
- binfmt
72+
- debootstrap
73+
74+
### USB HDD Installation
75+
76+
Using a partition manager of choice plug in a USB HDD and wipe the entire disk. No need to zero it. Then set up the partition scheme as MBR and create three partitions on the disk.
77+
1. A 4GB primary partition at the beginning of the disk.
78+
2. An 8GB primary partition after that.
79+
3. The rest should be a primary partition.
80+
81+
Format the partitions like this:
82+
1. First partition = fat32
83+
2. Second partition = swap
84+
3. Final partition is ext4
85+
86+
Identify and mount the ext4 block device to a mountpoint such as `sudo mount /dev/sdb3 /mnt/debian360`.
87+
88+
1. Bootstrap the latest debian ppc system to that mount dir: `debootstrap --no-check-sig --arch ppc64 unstable /mnt/debian360 http://ftp.ports.debian.org/debian-ports/`
89+
2. Run all this as one command to setup the chroot environment:
90+
```
91+
cp --dereference /etc/resolv.conf /mnt/debian360/etc/
92+
mount --types proc /proc /mnt/debian360/proc
93+
mount --rbind /sys /mnt/debian360/sys
94+
mount --make-rslave /mnt/debian360/sys
95+
mount --rbind /dev /mnt/debian360/dev
96+
mount --make-rslave /mnt/debian360/dev
97+
mount --bind /run /mnt/debian360/run
98+
mount --make-slave /mnt/debian360/run
99+
```
100+
3. Chroot into the debian system with `chroot /mnt/debian360 /bin/bash`
101+
4. Make sure the date is correct with `date -s`, then `source /etc/profile`.
102+
5. Run `apt update` - you will get a keyring warning.
103+
6. Run `apt install debian-ports-archive-keyring` to install the necessary keyring for gpg authentication of apt packages.
104+
7. Run `apt update` again. The warning should be gone and apt packages able to be securely verified.
105+
8. Set the system locale by `apt install locales` and then `dpkg-reconfigure locales`
106+
9. Edit `/etc/fstab` such as below - find your disk UUID with `blkid`:
107+
```
108+
# <file system> <mount point> <type> <options> <dump> <pass>
109+
# BUP 1TB rootfs
110+
UUID=b756a0b6-c31c-451c-9aa7-c026641edb47 / ext4 errors=remount-ro 0 1
111+
# BUP 1TB swap
112+
UUID=d1faa05a-3975-43ae-8da1-31c30c2d966f none swap sw 0 0
113+
```
114+
10. `nano /etc/hostname` -> set a fun hostname.
115+
11. `nano /etc/network/interfaces` -> set dhcp or set a static IP as desired.
116+
```
117+
# DHCP setup
118+
auto eth0
119+
iface eth0 inet dhcp
120+
```
121+
12. Set a root password with `passwd`.
122+
123+
Before exiting the chroot environment you can do anything you want - add packages, users, set up an SSH server, etc. Anything done in the chroot QEMU environment will not need to be done on the console itself. It is up to personal preference how to set up the system but steps 1-10 yield a basic bootable system suitable for initial testing.
124+
125+
An example `/etc/apt/sources.list` file:
126+
```
127+
deb [trusted=yes] http://deb.debian.org/debian-ports unstable main
128+
deb [trusted=yes] http://deb.debian.org/debian-ports unreleased main
129+
deb-src [trusted=yes] http://ftp.debian.org/debian sid main
130+
```
131+
13. Set up network time sync and timezone since the console clock is often unreliable.
132+
```
133+
apt install systemd-timesyncd
134+
systemctl enable systemd-timesyncd
135+
timedatectl set-timezone UTC
136+
```
137+
138+
14. Exit the chroot environment and reboot the host operating system to undo all bind mounts. The rest of the configuration can be done on console.
139+
```
140+
umount -l /mnt/debian360/dev{/shm,/pts}
141+
umount -R /mnt/debian360
142+
```
143+
144+
## KBoot configuration
145+
146+
On each console the detected devices will be different. You can however set KBoot up so that it boots the partuuid of a connected disk:
147+
```
148+
#KBOOTCONFIG
149+
; #KBOOTCONFIG (and nothing else) has to stay in FIRST line of the file
150+
; netconfig - only if the ip= is valid and isnt the same as eventually in the previously parsed kboot.conf, the netconfig gets set
151+
; if netconfig values aren't set/set invalid/commented, XeLL will use: Either supplied DHCP address or if no DHCP available, static IP (192.168.1.99/255.255.255.0)
152+
;ip=
153+
;netmask=
154+
;gateway=
155+
; set custom tftp server IP
156+
; incase no tftp_server= is set/set invalid/commented, XeLL will use: Supplied address via DHCP, if no DHCP available it will use 192.168.1.98
157+
;tftp_server=
158+
; XeLL's videomode - valid modes:
159+
; 0: VIDEO_MODE_VGA_640x480
160+
; 1: VIDEO_MODE_VGA_1024x768
161+
; 2: VIDEO_MODE_PAL60
162+
; 3: VIDEO_MODE_YUV_480P
163+
; 4: VIDEO_MODE_PAL50
164+
; 5: VIDEO_MODE_VGA_1280x768
165+
; 6: VIDEO_MODE_VGA_1360x768
166+
; 7: VIDEO_MODE_VGA_1280x720
167+
; 8: VIDEO_MODE_VGA_1440x900
168+
; 9: VIDEO_MODE_VGA_1280x1024
169+
; 10: VIDEO_MODE_HDMI_720P
170+
; 11: VIDEO_MODE_YUV_720P
171+
; 12: VIDEO_MODE_NTSC
172+
; If no value is set/set invalid/commented, XeLL will continue using the autodetected value
173+
;videomode=
174+
; speed up cpu - valid modes:
175+
; 1: XENON_SPEED_FULL
176+
; 2: XENON_SPEED_3_2
177+
; 3: XENON_SPEED_1_2
178+
; 4: XENON_SPEED_1_3
179+
; If no value is set/set invalid/commented, XeLL won't change CPU Speed
180+
speedup=1
181+
; timeout of the bootmenu in seconds - timeout=0 skips user input completely!
182+
timeout=30
183+
; Kernel / Bootentries
184+
; ! first parameter: kernel path !
185+
; coherent_pool=16M recommended by Techflash to get graphical output sanity on 5.X and greater kernels
186+
linux_usb_616_maxcpu="uda0:/vmlinux616 root=/dev/sdb3 rootfstype=ext4 console=tty0 panic=60 maxcpus=6 coherent_pool=16M rootwait video=xenosfb noplymouth"
187+
```
188+
189+
## Boot and enjoy!
190+
191+
1. Place the kboot.conf file on the first partition of the USB HDD which is fat32. Place also the custom kernel with it's custom naming.
192+
2. Boot from XeLL by a method of choice. Select the boot entry or let it time out.
193+
3. That's it! Plug in a USB keyboard and enjoy! You're in Linux with a modern kernel and userland at this stage and the possiblities are endless. The base Gentoo install is only a shell with basic system tools and no GUI which can make the Xbox effective as a server.
194+
195+
### If there are boot issues
196+
197+
Most likely the root partition was not found. The kernel will try to help state what devices are plugged in with which UUIDs and detected partition formats. Use this to configure your kboot.conf and `/etc/fstab` file within the image as necessary. Generally this configuration will now hold until power is completely removed from the console. Each time the motherboard gets power USB devices are detected at random device IDs.
198+
199+
Power cycling the console fully by unplugging the power supply for a minute or so can help.
200+
201+
Checking the kernel output can also help.
202+
203+
## Further notes
204+
205+
https://wiki.debian.org/ZRam - Set up ZRAM in userland to maximize RAM usage. The 360 only has 512mb of RAM for retail, 1GB for X/eDK.
206+
- Requires Linux kernel support for ZRAM built in. Simple edit to .config file. Also incurs needing to load the driver for it.
207+
- RAM usage under load (compiling kernel with `make -j3`) memory usage is nearly max. OOM killer engages sometimes but things run OK. System is very sluggish feeling in general.
208+
209+
Compiling things on console from source with `make` usually benefits most from `-j2` in general. It's a balance. Higher jobs are more performant with ZRAM enabled.
210+
211+
Something at the 360 hardware level does not manage USB devices well. If you're not seeing a device reported by Linux, power cycle the console fully
212+
for 30 seconds by unplugging the PSU.
213+
214+
libpixman-1-0 ships with altivec enabled, which doesn't work due to the 360s special flavor of the instruction set. Installing it from git after `./configure --disable-vmx` works fine after.
215+
- `apt-src` is a good friend to have. Most packages can be entirely rebuilt as desired from source using this tool.
216+
- `grep -Ri altivec` for example in a Debian package source directory format will tell one how that particular package's build system wants a variable declared, how and where.
217+
218+
https://docs.mesa3d.org/install.html
219+
This may be a lead on how to finally get some kind of acceleration working on 360 Linux.
220+
Since the GPU accel already works in Libxenon in general, albeit requiring compiled shaders. Perhaps a rudimentary shader can be loaded and applied to all of Xorg to allow some GPU acceleration to happen broadly?'
221+
222+
Todo
223+
add to kboot PARTUUID of root = d7d4b5ef-02

0 commit comments

Comments
 (0)