XDSL Manual
From XDSL
| Table of contents |
Introduction
XDSL is a xbox-linux distribution based on Damn Small Linux (http://damnsmalllinux.org). It weighs in at less than 50MBs with a nearly complete desktop, and many command line tools. The small size of bundled programs make it very suited to the Xbox's limited 64mb memory. It can be run as a livecd or installed to your Xbox hard drive.
Preparing the Xbox
A standard Xbox will only run code authorized by Microsoft, i.e. all executables must be signed with Microsoft's private key. To run X-DSL it is necessay to "mod" your Xbox to circumvent this restriction. For more details try looking on:
- Xbox Linux Wiki (http://www.xbox-linux.org)
- Xbox Scene (http://www.xbox-scene.com)
Download
XDSL is available to download from the xbox-linux sourceforge page (http://sourceforge.net/project/showfiles.php?group_id=54192&package_id=151661)
Burning the CD
Write the image to reliable recordable media which you know works in your Xbox DVD-ROM drive without any problems. Failure to do this will result in weird I/O errors and flaky installation problems, or you may not be able to boot XDSL livecd at all.
NOTE: you are not supposed to burn an .iso image as a single file on the CD. Instead, there should be a separate option in your CD authoring application that is specifically designed for burning CD images and not regular files. Use it. When burning is done, you should see several files on the disc - not just a single file.
Usage
Pop the XDSL CD you've just made into your Xbox and allow it to boot. You should be presented a choice of video modes (640x480, 800x600, 480p, 720p). 480p and 720p require your Xbox to be connected with component cables to a HDTV. Once you have choosen a video mode XDSL will boot and you'll automatically be logged into X as the user 'dsl'.
You can interact with XDSL by using a Xbox controller to move the mouse pointer. To launch programs right click on the desktop (B on the controller) to bring up the fluxbox menu. If you need to enter any text a virtual keyboard is available from the fluxbox menu under Apps. Alternatively you can use a USB Keyboard/Mouse with a USB adapter.
Passwords
The default passwords in XDSL are as follows:
user:dsl password:dsl
user:root password:xbox
Installation
If you are happy running XDSL from a livecd you can skip this section. However if you want XDSL to run from your hard drive you have three options:
- Frugal install - The XDSL compressed filesystem is copied to E:\KNOPPIX\KNOPPIX. This takes up the least diskspace (50Mbs). Since the filesystem is heavily compressed it is mounted read-only so this is just like running the livecd, except all the files reside on your hard disk
- Loopback install - The XDSL filesystem is installed onto a loopback file (either E:\xdslfs or F:\xdslfs). This requires a loopback file of at least 200MBs (you can choose a size upto 2GBs).
- Native install - XDSL will be installed onto a linux partition in the extra space on the Xbox HDD for those with hard disks bigger that 8GBs. This will keep the standard Xbox partitions (C,E,X,Y,Z) intact but will wipe all data on the F partition if it exists.
To perform one of these installations open the fluxbox menu and select the appropriate option under Apps, Tools. You will then be guided through the install process.
myDSL extensions
If you are running from the livecd or a frugal install you can load addition programs using myDSL extensions. XDSL should be fully compatible with extensions made for Damn Small Linux. Extensions are available from http://distro.ibiblio.org/pub/linux/distributions/damnsmall/mydsl/ or via the myDSL icon on the desktop. They should be copied to E:\ to load them when XDSL boots or E:\optional\ to give you the option of loading them via the fluxbox menu. Since each extension is loaded into the ramdisk it is recommend that you use E:\optional\ if possible to save on memory usage.
Backing up your settings
When using the frugal install/booting from a livecd it is not possible to write any changes to the XDSL filesystem. To get around this your settings can be saved in a seperate file called backup.tar.gz. Go to System, Backup/Restore in the desktop menu, type in hda50 and hit backup if you wish to make this file on your E drive. Once made your settings will be automatically saved on shutdown and restored on boot. To change what files are saved edit /home/dsl/.filetool.lst (was /home/dsl/.filetool.lst prior to X-DSL v0.3). None of this is necessary with Native/Loopback install methods since the root filesystem can be written to.
Enabling apt
If you are running from a loopback or native install you'll probably want to re-enable the debian package utility apt to allow you to install a huge range of programs from the debian repository. It is also recommended you restore the GNU Core Utilities. Both of these tasks can be done from the Desktop menu.
Once this is complete you can then install programs via the command apt-get install myprogram. You may wish to edit your /etc/apt/sources.list beforehand to point it to the debian testing repositary (comment out the existing lines with # and uncomment the testing lines). apt-get update updates the list of available programs and apt-cache search myprogram searches for a 'myprogram' in the debian repository. For more infomation on apt take a look at the apt howto (http://www.debian.org/doc/manuals/apt-howto/).
FTP Install
If you don't wish burn XDSL onto a cd and have the ability to ftp to you Xbox, it is possible to simply copy across the required files. Create a directory E:\KNOPPIX on your Xbox. Extract linux24, minirt24.gz and the KNOPPIX file (found in the KNOPPIX subdirectory) from the iso and copy them into this directory. You should be left with the following files:
E:\KNOPPIX\KNOPPIX E:\KNOPPIX\linux24 E:\KNOPPIX\minirt24.gz
There should be no subdirectories in E:\KNOPPIX. The filenames are case sensitive.
Now create a file E:\linuxboot.cfg with the following content:
title XDSL kernel KNOPPIX/linux24 initrd KNOPPIX/minirt24.gz append root=/dev/ram0 init=/etc/init rw video=xbox:640x480 frugal quiet kbd-reset
Finally if you are not using the Cromwell BIOS copy default.xbe somewhere where you can run it from your Xbox. Then run Cromwell/default.xbe to boot XDSL. If you then want to peform a loopback/native install simply select your desired option in the Apps, Tools menu.
New Features for xdsl-0.6
Xdsl Upgrades:
New for Xdsl 0.6 is the Xdsl upgrades menu. This is on the fuluxbox menu and the jwm menu (right click on desktop). This contains extensions that are mainly available through mydsl, but need special xbox Linux files or configuration to run properly for xdsl. A loopback or native install is needed for most of these apps to function.
Sound:
Sound can now be upgraded to Alsa (Advanced Linux Sound Architecture). This is crucial for good sound in flash player and various other apps.
Display:
The display can be upgraded to Xfree86 or Xorg. The screen will default to 640x480 when first installed, which should work for most tv's and monitors. Other settings can be implemented by editing /etc/X11/XF86Config-4 (for Xfree86) or /etc/X11/xorg.conf (for xorg). It is suggested to only do this if you have some understanding of these servers and a usb keyboard. If your unlucky and the display does not work at the your settings, and your back at the prompt, then type in startxf to get back to the original display (Xfbdev). Xfree86, Xorg and Xfbdev all have there pro's and cons. Personally I prefer Xfbdev as although it's marginally less clear than xfree86 and xorg it starts up in a fraction of the time.
Firefox gtk2:
Firefox2.0.0.16 gtk2 Can be downloaded using the menu item. This will be installed with mplayer plugin and configured for xdsl. This has been added, because a gtk2 version of firefox is required to run flash 9.
Flash Player:
Flashplayer can be installed using the installed using the option on the xdsl upgrades menu. This will install flashplayer to the stock firefox, and Flashplayer 9 for Firefox 2 gtk2 (also on the upgrades menu). It is suggested to download flash player from macromedia using this menu option, as various other files necessary to flash 9 are installed at the same time.
Overscan:
Overscan issues for 1.6 xboxes can be resolved using the xbox1.6 screen fix. This reduces the visible area of the screen in a couple of clicks. If it's not quite the correct size, or position then then settings can be adjusted in /home/dsl/xinitrc1.6 line 6. Here you will see:
-geometry 541x396+29+22
which refers to: width x height + x + y . It is important to shutdown your xbox correctly using the quit or shutdown menu, particularly when you use this app to prevent stale lock files. If for some reason the x server does not start, and you end up at the prompt, then, if you are using a keyboard, you can issue the command " resizex " to get back to the normal display. The screen fix can be used also for none 1.6 xboxes, if you have overscan problems. See appendix for getting the perfect settings.
Remaster Xdsl:
This tool was made to make remastering xdsl easier. It is primarily aimed at developers, but can be used to add various apps and settings to create a custom xdsl cd. You will need a native or loopback install to use this tool. Remaster xdsl step 1, will extract the contents of the original xdsl live cd, so files can be added to or removed from it's filesystem. If you do not have a live cd and installed from a frugal install, there is an option to extract from the frugal install instead. The files for remastering will be in /var/xdsl. Step 2 creates a new knoppix file and Step 3 makes the new iso image to be burned to cd/dvd. A more detailed description can be found in /usr/sbin/xdsl_remaster_info.
Multimedia:
Enabling xbox remote control:
Create a loopback or native install and the remote control will be enabled automatically. The remote control works for xmms and xine (as downloaded from the xdsl upgrades menu). It is possible to use the remote control as a mouse, by installing xfree86 and adding the command lircmd to /opt/bootlocal.sh. But this is not advisable as the system can become unstable.
DVD playback:
Dvd playback will also be enabled when a loopback or native install is created. The codecs are illegal in some countries and should only be used once legality has been confirmed.
Dvd's can be played via the right click menu or by right clicking on the xmms icon and selecting dvd playback. This will launch a very simple app that I made with basic functions, to control the stock mplayer. You can use the xpad with this app for play, pause, stop, skip forward, and volume (keyboard shortcuts also work). For fully featured playback, download xine from the xdsl upgrades menu. Xmms can also be used, but it's not too smooth and not recommended,
Volume control:
Volume control is enabled on mplayer and xine by default. For xmms you need to use the sound upgrade option on the upgrades menu. this will install Alsa. Once alsa is installed, the dock on the bottom right of the desktop is also enabled for system volume control. System volume control works for apps that have alsa and softvol (xmms, xine, flash player 9 etc).
Flicker filter:
for some tv's the flicker filter need to be turned down slightly for more clarity. This can only be used for connexant chips on 1.0-1.3 xboxes. There is no menu item for this as I'm not sure what it will do if used for none connexant chips. To turn down the setting uncomment #flicker in /home/dsl/.xinitrc.
Codecs:
If you can't get a certain audio or video track to work, then chances are you don't have th required codec. Many essential audio and video codecs are contained in xdsl 0.6. If xine is downloaded, then further codecs are installed. Extra codecs can be obtained from the xdsl testing repository. A comprehensive set of multimedia codecs can also be obtained from http://www.mplayerhq.hu/MPlayer/releases/codecs/ . These should be placed in /usr/local/lib/win32.
myDSL extensions.
Extension types:
uci and unc extensions are best used with frugal/live cd as they are images as is the frugal/live cd, so will use less ram than dsl or tar.gz apps. Uci's work well, and unc's are more experimental with xdsl. Unc apps work pretty well at time of writing but there's no guarantee for the future as xdsl does not use unionfs as dsl does. Conversely dsl and tar.gz work better in loopback and native installs, as they install into the filesystem and do not need to be mounted and unmounted.
Loading uci and unc apps permanently:
For xdsl 0.6, uci and unc apps can now be installed into the filesystem rather than just mounted. Unc apps will automatically be installed this way when they are loaded in loopback/native installs. However it is best to use a dsl, tar.gz, or uci version of the desired app, if one is available. To install uci apps permanently, for loopback/native installs, install in the normal way, then go to the uci tool in the tools menu (or right click on the mydsl icon). Here you will find which uci apps you have mounted. Click Set Permanent to load them into the filesystem.
Wine.
Here's a mini tutorial on using wine on xdsl 0.6:
1. Don't use Xwine, use wine0.9.22.dsl from the dsl system repository, Xwine has some compatibility issues with newer dsl versions.
2. Download your windows app, after checking WineHQ to see if it works.
3. Go into emelfm and double click the install .exe file of the app to install. Or issue the command wine your_file.exe.
4. Your app will probably install to /home/dsl/.wine/ drive_c/Program Files/ . You will need to click the little H button on the top bar of emelfm to see the hidden directory .wine in /home/dsl. So navigate to the launching .exe file for your program and double click it to run.
5. You can make a desktop icon or menu item to launch the app (instructions on the dsl wiki). An example of the launching command for bittornado is:
wine /home/dsl/.wine/drive_c/Program_Files/BitTornado/btdownloadgui.exe
You need to rename the directory /program Files to /Program_Files , because Linux does not like gaps in the command.
Upgrading xdsl
It is not possible to upgrade xdsl like some other distributions. However it is possible to download and install a new version of xdsl using a loopback or native install of xdsl. Just download the new version and mount the iso by double clicking it in emelfm (if you are working from xdsl0.6rc3 or newer), or issue the command:
perl -i -ne 'if( $. == 1 ) { print "iso;iso;sudo mkdir %d/ISO 2>/dev/null && sudo mount -o loop -t iso9660 %f %d/ISO\n",$_; } else { print; } ' /home/dsl/.emelfm/filetypes
This will give emelfm the ability to mount the iso by double clicking on it. You will see the directory /ISO appear with the contents of the iso file. Copy the contents across to the xbox E drive (hda50) as in a normal frugal install.
Shutting down.
Exit: Always shut down xdsl using the shutdown menu, or by clicking the QUIT button on the desktop. This will exit cleanly and help prevent filesystem problems and hard drive errors.
Restart: If you need to restart the display, then use ctrl alt backspace to stop the x server and issue the command startx to start it up again. This is particularly useful for apps that have not shut down properly and are still running in the background. For those without a keyboard, use the restart command on the shutdown menu or from the quit button menu.
Credits
X-DSL 0.6 is still 90% DSL. It is based on dsl 3.4 and would not be possible without John Andrews and Robert Shingledecker's work to create the Damn Small Linux (http://www.damnsmalllinux.org) distribution. Also the Xbox-Linux (http://www.xbox-linux.org) developer's work on porting Linux to the Xbox.
Freigold and Keo Keo, Have done most of the work on xdsl (http://www.x-dsl.org) up to version 5 which has been almost all included in xdsl 0.6. Xdsl 0.6 would not have been possible at all without Freigolds excellent developer articles.
Keo keo started off xdsl 0.6 and Stevewal carried it on. Stevewal has tried to add as many popular features as possible to xdsl.
Other contributers include; christian.remboldt, for xbox remote control function; scuba156, for work on Xorg, Xfre86 and testing; Russ W. Knize, for the Xorg driver; Tremere, for the Xbox1.6 screen fix; willows02 and ldotsfan, for work on sound; and Master reefed for finding stuff. Also The Xebian developers for a few files I've pinched.
Stevewal 2008
Appendix.
Overscan, getting the perfect settings:
To fix overscan issues with the xbox 1.6 screen fix, and get the perfect screen size, follow these directions. This needs to be done before implementing the the screen fix. If you're already running the screen fix then revert to the original display.
Go into emelfm, click the little H button next to the address bar to expose the hidden files and double click on /home/dsl/.xinitrc1.6. This will bring it up in beaver.
Go to line 6 where you should see:
/usr/bin/Xnest -bw 20 -geometry 541x396+29+22 :1 2>/dev/null &
You can delete -bw 20 . This is the border which we no longer need.
We are now going to use the beaver window in which we are viewing the file, to determine the visible screen size. Grab the top bar and reposition it so the top left corner is in the very top left of the visible screen. You will see the position values changing in the middle of the screen as you move it. Note these down when you have it in the correct place. Now replace to geometry values of +26+22 with the X and Y values you noted down.
Next stretch the bottom right of the window until it takes up the whole visible area of the screen. Again you will see the width and height values changing as you stretch the window. Note the values down when you have the correct size of the window so it is the same size as the visible screen. Add 4 to the width value and 30 to the height value, to allow for the borders. Replace the first two geometry values in the file with the new width and height values.
Now save the file and run the xbox 1.6 screen fix. This should give the perfect screen dimensions.
