Documentation

Contents

1. Frequently Asked Questions
2. X-Amiga (Linux)
   1. Command-line X-Amiga
   2. Set up networking
   3. Access USB storage
   4. Change shutdown delay
   5. Minimal installation
   6. Build from scratch
   7. Technical notes
3. Installer CD
   1. Documentation
   2. 'Workbench' screen resolution
   3. Hardware detection
   4. Networking
   5. Sound
   6. CatWeasel

Frequently Asked Questions

The website doesn't display properly on my browser!

• Tested on: AWeb, Firefox, IBrowse, Konqueror, Links2, Opera, Safari
• Not tested on: Internet Explorer. IE 6 and below lack support for transparent png images, which will affect the way this website displays.

X-Amiga won't boot after installation

• Are you multi-booting X-Amiga with other operating systems? A grub configuration file is generated during installation, but it does not overwrite or append to your system's grub.conf - you'll need to manually copy the lines from /mnt/xamiga/boot/grub/grub.conf to your main grub.conf.

Why does X-Amiga start, then shut down almost immediately?

Note: release 20071201 has auto-shutdown disabled to avoid this problem.

• From release 20071124 you can abort automatic shutdown by pressing any key (except 'Enter') during the "Shutting down..." message. (Also see item 2.4 Change shutdown delay)
• Most likely the UAE configuration file hasn't been set up properly. Check the log file at /home/xamiga/uae.log to see if E-UAE reports any errors as it starts.
• Alternatively, if you are at the console, type 'startxa' and try to diagnose problem from there.
• A read-only filesystem will also cause shutdown problems. This is due to the absence of /etc/mtab in versions prior to 20071201. To create /etc/mtab, boot from the installer CD, and from the shell do the following:
  

  mkdir /mnt/xamiga
mount /dev/hda1 /mnt/xamiga
echo "/dev/hda1 / ext2 rw,noatime 0 0" > /mnt/xamiga/etc/mtab

  Note: this assumes you've installed X-Amiga to /dev/hda1

Why is there no splash screen, or an error about splash?

• On a multi-boot system, make sure lines in X-Amiga's grub.conf are copied/transferred to main bootloader.

Why are USB devices still there after removal?

• Adding a device works OK, but the Amiga side doesn't update when a device is removed. A hard reset seems to be required...

Why isn't networking working?

• Wired: Is DHCP uncommented in /etc/init.d/rcS?
• Wireless: Are wireless lines uncommented in /etc/init.d/rcS?
• Does lsmod show correct kernel network modules?

Why is the display flickering?

• It's a 'feature' ;-) The refresh rate is hard-set to 60Hz, so X-Amiga is currently suitable only for LCD monitors.

Why does the screen go blank when the computer's left unused for a while?

• It's the screensaver. Wriggle the mouse or press a key ('Shift' is a good choice).

Why doesn't [extra software] work when it's copied to the X-Amiga installation?

• X-Amiga is compiled against uClibc. If you wish to run any additional packages not included by the installer, they'll need to be either cross-compiled or built using a uClibc-based system.

Is X-Amiga simply a cut-down version of Gentoo Linux?

• X-Amiga was built with Gentoo Linux. However, apart from borrowing the Gentoo kernel, it is otherwise an original Linux OS. (The same goes for the Installer CD.)

Can X-Amiga be adapted to run other emulators (eg. VICE)?

• Yes. Referring to the Technical notes: only the Base, Display and Audio groups of packages are needed for a functional system. Add to these any packages and dependencies needed by the other emulator. The system scripts will be nearly identical.

Top

X-Amiga (Linux)

Command-line X-Amiga

Underlying the Amiga emulation is a simple Linux operating system. On occasion you may need to configure or tune your system. Here are instructions on how to perform some common tasks from the command line.

• To exit E-UAE without shutting down the computer, press:
  

  CTRL+ALT+BACKSPACE

  or
  

  CTRL+ALT+DEL

  (Pressing CTRL+ALT+DEL again will restart the computer)


• To restart E-UAE, type:
  

  exit

• To edit .uaerc, type:
  

  e3 /home/xamiga/.uaerc

  (To quit e3, press 'CTRL+k q' and 'y' to save changes)


• To execute administrative commands:
  Type 'sudo' before each command, and enter your password


• To set sound levels (two settings):
  

  sudo amixer set Master [0-31] unmute

  or
  

  sudo amixer set PCM [0-31] unmute

  To store settings, type:
  

  sudo alsactl store

• To poweroff or reboot, type:
  

  sudo poweroff

  or
  

  sudo reboot

Top

Set up networking

Network setup is not yet fully implemented. However, X-Amiga installs a suite of networking tools, for both wired and wireless networks; and kernel networking modules are all present. If your card is supported by the Linux kernel, it's just a case of determining which kernel module matches your network card and adding it to the modules list. If only Windows drivers exist for your card, an alternative system can be used, called ndiswrapper.

To find out which module should be used for your network card, you can use the installer CD's hardware detection as described below.

Then edit /etc/init.d/modules from your X-Amiga installation and add the module name to the list. Important: each module must be on a new line.

Finally, uncomment the relevant lines from /etc/init.d/rcS:

# Wireless networking
#iwconfig wlan0 mode [MODE] essid [ESSID] key [HEX KEY]
#ifconfig wlan0 up
#dhcpcd wlan0

# Wired networking
#dhcpcd eth0

Top

Access USB storage

X-Amiga has support for USB block devices: commonly, flash or hard drives. When a USB block device is connected, it is automatically mounted at /mnt and a new directory created, eg. USB1

To access such a device from within E-UAE, you need to edit .uaerc and add an extra line to '# Hard disk options':

filesystem2=rw,DH2:USB:/mnt,0

Top

Change shutdown delay

X-Amiga pauses for 5 seconds before shutting down; it aborts shutdown if a key is pressed within this time.

To change this behaviour, edit /etc/profile:

sudo e3 /etc/profile

Here's what the file looks like:

/usr/bin/startxa >/home/xamiga/uae.log 2>&1

echo "Shutting down..."
stty -echo -icanon min 0 time 50 # 5 second delay
key=$(head -c1)
[ -z "$key" ] && sudo poweroff || echo "Shutdown aborted!" && stty echo

Simply change 'time' from '50' to any other value (in tenths of a second).

Top

Minimal installation

Is 40MB just too bloated? How to make the installation truly minimal...

• Re-compile the kernel specifically for your hardware
• Re-compile busybox with fewer features
• Run as root
• Don't install: sudo, shadow, e3, jpeg, libpng, splashutils
• Depending on your particular system, don't install: net-tools, wireless-tools, ndiswrapper; sysfsutils, cpufrequtils
• Remove the 'xamiga' splash theme from /etc/splash
• Delete unused executables from /usr/bin and /usr/sbin
• Use squashfs to compress read-only directories

Top

Build from scratch

How to build a system similar to X-Amiga completely from scratch...

[To do]

Top

Technical notes

On a separate page

Top

Installer CD

Documentation

To save space on the CD, man pages are not installed. Docs for E-UAE and CatWeasel can be found in /docs [in the next release]

Top

'Workbench' screen resolution

The default resolution for the AmiWM 'Workbench' is 800x600 in 24 bit colour. To change this resolution, you must first exit AmiWM, then reload 'Workbench' with an appropriate argument:

loadwb [X-res]x[Y-res]x[Color-depth]

For example, typing 'loadwb 1024x768x8' will start AmiWM with a resolution of 1024x768 in 8 bit colour. For a list of allowed screen modes, type 'Xvesa -listmodes'

Top

Hardware detection

Currently the installer CD doesn't automatically detect hardware, because neither sound nor networking are necessary for the installation of X-Amiga. However, hardware detection can be useful, so here's how to initialise it:

hwsetup

This will take a few seconds. Nothing will have seemed to have changed. But if you list the modules loaded, you will (hopefully) see your hardware represented:

lsmod

To determine the exact kernel modules for specific hardware, you'll probably need to cross-reference this list against the output from the hardware lister.

Top

Networking

First initialise hardware detection as detailed above. If using a wired network card, type:

dhcpcd eth0

If using a wireless network card, type:

iwconfig wlan0 mode [MODE] essid [ESSID] key [HEX KEY]
ifconfig wlan0 up
dhcpcd wlan0

Note: 'eth0' or 'wlan0' may be different for your system (eg. 'eth1' or 'wlan1').

Top

Sound

You may wish to test ALSA settings using 'speakertest' or 'aplay'. First initialise hardware detection as detailed above. To change sound levels and unmute channels, type:

alsamixer

Use the cursor keys to change levels and spacebar to mute/unmute channels. Press 'Esc' to exit.

Top

CatWeasel

There is experimental support for the CatWeasel controller card. To load the kernel module, type:

insmod /lib/modules/2.6.21-gentoo-r4/kernel/drivers/char/cw.ko

Check the documentation in /docs/cw for further details, and visit the cw website.

Top