Tag/tag.png

Needs Expansion
This article is incomplete, and needs to be expanded. More info...

This page describes how to set up the E-UAE Amiga emulator in Ubuntu. Note: as of 05/16/09, e-uae packages are available in Ubuntu universe repositories for Ubuntu 8.10, 9.04, 9.10 and above.

Introduction

UAE is the UNIX Amiga Emulator (Linux is UNIX-like) which lets you emulate an Amiga system, from the A1000 (the first Amiga) up to the A4000 (the last official "classic" Amiga). UAE is quite old now, and is pretty much abandoned. The Windows port of UAE, called WinUAE, has seen a lot of development however. Richard Drummond (well known for his contributions to Amiga Format magazine, now he often writes articles for Linux Format) has taken many of these newer features and put them into a cross-platform program called E-UAE (what the E stands for is debatable). UAE is packaged in Ubuntu, but E-UAE isn't (yet) so this guide will tell you how to install it. E-UAE is Free Software under the GNU GPL.

NOTE: E-UAE emulates the Amiga series of computers based on the Motorola 68000 series of processors. However, it does not provide any operating system software or the Kickstart ROM images, since these are copyrighted by Amiga Inc. The operating system software is not always needed to run software on an Amiga, since many programs and games can be run by booting directly from the floppy disk drive, but a Kickstart is always needed. E-UAE contains a basic Kickstart image which may work for some simple games, but a full, official Kickstart is preferred. In order to use one of these you must own some equivalent ROM chips (either in an Amiga or purchased separately) or you may obtain an image legally from Cloanto's Amiga Forever software. These images are encrypted, however, and come with a decryption key for use with emulators.

Installation

Obtaining E-UAE

E-UAE is available in Ubuntu repositories since Ubuntu 9.04 (and 8.10 with backports). Just install it using Applications>Add/Remove, System>Administration>Synaptic Package Manager, or the following command line:

sudo apt-get install e-uae

Building E-UAE from source

The source code for E-UAE can be found on http://rcdrummond.net/uae. A direct link to the latest version at the time of writing is here. Put this somewhere logical in your home folder. This is source code and we must compile it.

Firstly you will need the programs installed which let you build and install software. These can be installed with:

sudo apt-get install build-essential checkinstall

(FIXME: Are any development packages needed, such as SDL ones?) You may also need zlib packages:

sudo apt-get install zlibc zlib1g-dev

Now you need to extract the bzip2ed tar archive you downloaded. This can usually be done by right-clicking on the archive and selecting Extract Here. If not then you can use the command:

tar xf e-uae*

Once it is extracted you need to enter the newly created folder in a terminal. This is done with:

cd /the/full/path/to/the/folder

Where you replace that path with an appropriate path for your system. For example, on my system I would type:

cd /home/chris/Files/System/Programs/E-UAE

Since I have put the folder into /home/chris/Files/System/Programs and called it E-UAE. Once in the correct directory we can begin to set up and build the source code. Firstly it needs to be configured. This is done simply with the command:

./configure

If this reports no errors then go on to the next step. (FIXME: What errors may occur? (missing packages?))

Once it is configured it must be built into an executable program. This is done with:

make

It may take a while, and should not give any errors if the configure step worked.

Once the program has been made you can run it from where it is using:

src/uae

Installing E-UAE

A better idea would be to install it into the right system locations. We will make an Ubuntu package containing E-UAE with the command:

sudo checkinstall --install=yes

You will need to type your user's password. Don't give the package any documentation, but give it sensible attributes. Here is an example:

This package will be built according to these values:

0 -  Maintainer: [ root@chris ]
1 -  Summary: [ The enhanced version of UAE, the UNIX Amiga Emulator ]
2 -  Name:    [ e-uae ]
3 -  Version: [ 0.8.29-WIP2 ]
4 -  Release: [ 1 ]
5 -  License: [ GPL ]
6 -  Group:   [ checkinstall ]
7 -  Architecture: [ i386 ]
8 -  Source location: [ E-UAE ]
9 -  Alternate source location: [  ]
10 - Requires: [  ]

Enter a number to change any of them or press ENTER to continue:

When you have entered some logical values then press Enter and the package will be built and installed.

Using E-UAE

Needed Files

First you will need to choose your Kickstart image, the Kickstart is the data contained in the ROM chips on board classic Amiga computers. This data boots the computer, contains drivers for the hardware, a small animation of a floppy disk being inserted into a floppy disk drive (which appears when no floppy, CD/DVD or hard drive is present) and some base parts of the Amiga operating system (including graphical boot menus). E-UAE can emulate an Amiga 500 with a basic Free Software Kickstart, but for full compatibility you will need an official, proprietary Kickstart, which you can purchase from Cloanto as part of their Amiga Forever package.

If you already have an Amiga then you can run the transrom program on your Amiga to dump the contents of your Kickstart ROMS into an image which can be used in E-UAE. Transrom comes with E-UAE, but for me the source does not compile. If you download one of the prebuilt archives from Richard Drummond's site then you will find the transrom tool in the "Amiga" folder. You can see further down this guide on how to transfer files between your Amiga and your Ubuntu computer. To use transrom just put it on your Amiga then open a terminal (Shell) in the Workbench and run:

transrom >RAM:kick.rom

This will create an image called kick.rom in the RAM disk. I find that it takes about 15 minutes on my standard 14MHz Amiga 1200. Open the RAM drawer on the Workbench to access this file. If you have access to a hard drive, but have very little RAM (1MB or less) then you can save this image somewhere else by substituting a different path into the above command, although this will slow down the process.

NOTE: I have been able to run the transrom program on my Amigas, but for unknown reasons it has not outputted an image. If you find yourself in such a situation then you may be able to find a Kickstart on the Internet, probably through Google. Distributing such copyrighted software without a license is illegal so I cannot recommend this method, or indeed give any details for web sites which may offer them, but it is usually acceptable to obtain an image in this way as long as you already own a license to the data it contains, that is; only download a Kickstart image if you already have that Kickstart but are unable to transfer it. This type of activity is usually covered by the same laws which govern your ability to rip CDs to MP3 format, since both activities involve transfering data for which you have a license from one medium to another. Do not attempt this method of obtaining a Kickstart if it is illegal to do this kind of activity where you live.

Once you have chosen a Kickstart you will need some kind of program to use in the emulator. E-UAE supports floppy discs and hard discs, so you can boot from either. If you wish to use a CDROM (either a physical disc or an "iso" image) then you should give E-UAE the mountpoint of the disc as if it were a hard disc partition. For more in-depth information on disc access in E-UAE see the Useful Information section.

Starting The Emulation

You can start E-UAE with the command:

uae

Or, if you have the UAE package installed as well:

/usr/local/bin/uae

If you have the older type of UAE installed then they will not conflict, however you may want to create an alternate name for E-UAE to allow a single command to run it. This can be done with, for example:

sudo ln -s /usr/local/bin/uae /usr/local/bin/euae

Which will allow you to start UAE normally, and to start E-UAE with the command:

euae

Now you may decide that you want to add this command to the Applications menu. You can do this with the Alacarte Menu Editor (found in Applications>Accessories). Enter a useful name and comment, then put the Command as whatever you use to start E-UAE (normally just "uae" but maybe different if you have regular UAE installed as well, see above). Choose an appropriate image for the icon (it is quite simple to make an Amiga "boing ball" logo in the GIMP. You may also find a suitable image on Google)

Load up E-UAE. You may find it's interface quite complex, but it is very powerful and easy to use if you keep away from what you don't understand and just concern yourself with the disc image parts. If you want to emulate a specific system then I have made a table of the hardware in each Amiga system below.

Note

There is a bug with ubuntu Lucid to ubuntu Meerkat (10.04 to 10.10) and e-uae in the netbook-remix interface, the file menu does not appear which means there is no way to save the configuration. The easiest way round this is to log out and back in selecting gnome or kde as the session this restores the missing file menu. This has been fixed in 11.04 Natty Narwhal Netbook Edition.

To get started right away select the "Memory" tab and tell it where your Kickstart image is. (You will also need to give it the decryption key for your Kickstart if you have got it from the Amiga Forever package). The built-in Kickstart replacement is used when no file is given as a Kickstart image, however there is an entry of "kick.rom" by default, which can only be replaced not removed. The solution is to press the "Save Config" button and exit E-UAE. Now there should be a hidden file in your home folder called ".uaerc" (if this file doesn't exist then you should open E-UAE and set the Kickstart image to anything other than kick.rom, then select "Save Config" and the file should be there). Now edit this file with a text editor and look for a line something like this:

kickstart_rom_file=kick.rom

Remove the "kick.rom" from after the equals then save the file. Now when you start E-UAE the Kickstart setting should be empty, which will use the replacement.

Unless you are using a hard drive with the AmigaOS already installed, you will probably be booting from floppy disc. In an Amiga the internal floppy disc drive is referred to as "DF0:", and this is booted by default, even if you have enabled a hard disc. If you put a non-bootable disc image in DF0: then the Amiga may boot to the hard disc instead, or it may drop to a shell after failing to boot the disc. It is usually a better idea to put non-bootable disc images in the external floppy drives ("DF1:", "DF2:", etc.) or to wait until the Workbench has loaded before inserting the image. Image files can be swapped at any time, just like replacing a floppy disk, but you should try not to do so when the drive activity light is on.

To start the emulator once you have given it the configuration you want it to boot you can just click on the "Pause" button (which is already pressed, therefore you are un-pausing the emulation). You can use this button to pause your emulation (for instance if you want to pause a normally unpausable game).

Using E-UAE

You can reboot the emulated Amiga with the "Reset" button. You can also reset the Amiga by pressing Ctrl-Super-Super (that is both of the Super keys. The Super keys are often "Windows" keys on a PC, and "Command" keys on a Mac. On an Amiga they are the "A" keys). Additionally F12-R will reset the Amiga (a "warm" reset, like that of ctrl-A-A) and F12-Shift-R will do a "cold" reset (equivalent to turning off the Amiga and turning it back on).

If you find E-UAE is having problems with your mouse pointer moving at the wrong speed, or getting stuck when your Ubuntu pointer reaches the edge of the screen, you can press F12-G to grab and release the mouse.

To toggle between fullscreen and windowed mode you can press F12-S.

If you find E-UAE is going slowly try turning off the sound emulation (this can be done at any time from within the E-UAE control window and does not require resetting the emulated Amiga). The "100% Accurate" sound emulation will noticably impact the performance. To change the frame-rate of the emulator (skipping frames requires less work than rendering them all) you can use F12-+ and F12-- (+ and - on the NumPad).

Classic Amiga computers do not require a shutdown, you can just quit E-UAE (closing the control window will not stop the emulation, but closing the emulation window will close the entire program, including the control window) F12-Q will also quit E-UAE.

More documentation can be found in the "docs" folder in your dowloaded archive of E-UAE.

Useful Information

Amiga System Information

FIXME: Make a table of processors, graphics chips, RAM and possibly Workbench versions.

NOTE: There is no value in emulating a 68060 processor. There are two differences between 68040 and 68060 chips. The 68060 is able to go at much faster speeds than the 68040 (I have heard of one being overclocked to 100MHz, but this is very dangerous), however since you are emulating the chip this does not affect you. Emulating a 68040 and a 68060 will go at the same speed. The second difference is that to reach these higher speeds, the 68060 lost some of the instruction set of the 68040. This means that in a real 68060 system some of the processor instructions are emulated in software, which works well since the processor is able to go much faster than it's predecessors. This does not work very well in an emulator, however, since you would be emulating an emulator, which would cause a large performace loss, when you may as well run a 68040 will the full instruction set at the same speed as a 68060. Therefore "turning everything to full" would actually be best using an 040 rather than the "full" 060.

Using Floppy Disc Images

Amiga floppy drives are different from PC floppy drives, so much so that PC drives cannot read discs formatted for an Amiga filesystem. The Amiga's floppy drive controller can handle FAT formatted discs perfectly well using the CrossDOS tool included with Workench 2.1 and above. This means that you cannot put an Amiga floppy disc into a PC and run it in E-UAE, but you can use a PC formatted disc in your Amiga. To access an Amiga floppy disc in E-UAE you will have to dump the contents of the disc into a file (often called an Amiga Disk File and usually abbreviated to ADF since the popularity of WinUAE has produced "file extensions" necessary for Microsoft Windows to work). You can turn an Amiga floppy disc into an ADF file with the Transdisk tool (which you can find in the same place as Transrom), although you should be aware that the disc image will contain ALL of the data from the floppy disc. This means that the slight amount of used space on a formatted floppy disc (for it's filesystem to work) is actually too much, and the ADF will not fit onto a regular floppy disc. Since the ADF is just a stream of binary data you can often achieve good enough compression ratios with Zip, LHA, LZX or another compression algorithm to fit it onto a FAT formatted disc.

An alternative to creating an ADF then compressing it would be to use the Disk Masher System on your Amiga. This can compress a floppy disc into a file, which can can then be transferred to your PC on a FAT formatted disc. E-UAE can load DMS disc images into it's virtual floppy drives in the same way as ADFs. FIXME: Describe DMS's usage.

There is a hardware alternative called the CatWeasel which lets you plug an Amiga floppy disc drive into your PC and access the discs this way. E-UAE currently doesn't support using such a drive directly, but combined with a copying command like "dd" you could theoretically create ADFs by dumping the contents of the floppy disc into a file (the definition of an ADF). I have never used one of these devices so I do not know exactly how it is handled.

Using Hard Discs

There are two types of hard disc in E-UAE. You can either give it a real Amiga hard disc or an image of one, or you can give it a folder which it will treat as a hard disc partition. In WinUAE the hard disc access is very useful since it lets you plug a hard disc drive from an Amiga into your PC and access it via WinUAE. In Linux this is slightly less useful since Linux can access Amiga-formatted hard discs just like any other hard disc, so you are not forced into using E-UAE to copy files to and from such a drive. However, using an image of a hard disc actually runs more quickly than using a folder, so it is up to you which method you prefer. If you use a folder then you can easily get access to the files stored in it, and if you use an image then you must mount the partitions on it via the loopback device to access it.

A Good Workbench Setup

If you are new to the Amiga then you will probably find some libraries, etc. missing when you try installing some software. Since the Amiga Workbench does not have a package management ability like Ubuntu this is to be expected. One thing I have noticed after running the same Amiga systems for over a decade is that libraries and other tools tend to accumulate in the Workbench partition and after they reach a critical mass you find that pretty much everything works straight away, in stark contrast to a similar situation in Microsoft Windows where the accumulation of orphaned system files drives some users as far as formatting the entire disc just to remove these files as they clog the system. For those of you who are just beginning to use an Amiga system in an emulator I have made this section to help you create a managable system.

Installing The OS

Since you are not limited by hardware, since you have an emulator, I would SERIOUSLY recommend getting your hands on the latest officially released version of the AmigaOS for the classic architecture, OS3.9. You can buy this from many stores online, and maybe even eBay. Cloanto sells CD or downloadable ISO images of Amiga Forever, which comes with all versions of AmigaOS and all Kickstart ROMs. Like a Linux system, you will find that you get a much better experience if you parition your drive well. If you are using a real drive or an image then it is very difficult to resize partitions formatted for an Amiga filesystem, so you will want to get this right. If you are using a folder for each partition then the size of the drive will always be the size of the Linux partition it is stored on, so you don't need to worry about size. If you use folders then all of the "partitioning" is done by E-UAE when you tell it which folders to use. If you are using an image or disc then booting E-UAE from a Workbench floppy disc and inserting the "Install" disc will let you access the HDToolBox program, which lets you format your disc/image. (If you want to use OS3.9 then you will first need to set up your drive and install Workbench 3.1, since classic Amigas cannot boot from a CDROM drive without the appropriate drivers saved onto a hard disc.)

Firstly you will UNDOUBTEDLY have a better experience if you keep the Workbench (the main part of the operating system) separate from the rest of your files and programs. If you want to use an image or real drive then you may like to know that my oldest Amiga 1200 has comfortably got by with a 40MB partition for the Workbench (version 3.0) for over 10 years, even with vast amounts of libraries accumulating. These days data storage has become very cheap, and since most PC systems come with large 3.5 inch hard disk drives you are not restricted by the higher price of 2.5 inch drives which fit snugly into many Amiga "keyboard" cases, then you will probably have thousands of MBs available. In this case I would use 100MB or maybe even more for the Workbench. Anything over 500MB is a ridiculous waste in my opinion. It would be sensible to put "DH0:" (the first hard disc partition) as the Workbench's partition, and give it a volume name like "Workbench".

Next you will want a partition to put your programs onto. Many programs on the Amiga don't even need to be installed, you can just run them from wherever you put them. Make a partition, or folder, for your programs and assign it to "DH1:". I have found two partitioning systems which work well. One is "Workbench" "Applications" "Games", where data is stored individually in each application's folder (so, for example, Personal Paint will put pictures in "Applications:Personal Paint/Pictures"). If you would like to use a more Linux-like storage system and keep your files seperate then a "Workbench" "Programs" "Files" system also works well, where "Programs" contains drawers called "Serious" and "Games". (Remember these are only suggestions, but I find they work well). Your third partition should be drive "DH2:". If you are after sizes to use then I would fill the remaining space and make "Applications" about the same size as "Games", since you will probably have loads of games, but the applications also store their files (like music, pictures and animations which you make) in "Applications", that makes them about the same size. For the other approach I would once again fill the disc and put "Files" about twice as big as "Programs". I regularly use a 1.5GB Amiga hard drive which has "Workbench" as 100MB, "Programs" as 400MB and "Files" as 1GB. Even with loads of games installed, animations, pictures and music, and backups of the entire contents, it only around 10% full.

With your partitions set up you just need to run the installer for your language which you will find on the "Install" disc of the Workbench floppy set. After installing Workbench from floppy, you can insert your AmigaOS 3.9 CD and give E-UAE it's mount point as if it were a folder being used as a hard disc partition. You should make the device name "CD0:" and give it a Volume name of "AmigaOS3.9". With OS3.9 installed you now might want to install a few common libraries and tools, which I have compiled a list of.

Useful Extensions To Install

Picasso96 - Picasso96 is a Re-Targettable Graphics system (RTG). Picasso96 has a driver for E-UAE's display, called "uaegfx", and allows you to use VGA resolutions (like 1280x1024, 1024x768, 800x600, etc.) and full "32bit colour" (24bit with alpha) as if the emulated Amiga had an extra graphics card fitted. Please refer to http://winuaehelp.vware.at/emulation/picasso.htm for setup information (Important, as if your E-UAE configuration is not correct, the modes will not appear).

Magic Menu - A more comfortable right-click menu system for the Workbench.

MUI - The "Magic User Interface" is a shareware graphics toolkit (similar to GTK and QT in Ubuntu) used by many Amiga programs.

FIXME: Add some more basic libraries, datatypes and possibly tools.

Assigns

In the AmigaOS there are multiple volumes, unlike Linux. This means that your floppy drives, hard drive partitions and any other devices are all kept seperate. A colon after a location indicates that it is a volume. The AmigaOS does have another use for volumes though. An "Assign" is used to turn a drawer (Workbench's term for directories) into a volume. For example:

ASSIGN OctaMED: Applications:Serious/Music/OctaMED

(FIXME: Is this the right syntax?)

Will create a new volume called "OctaMED". Entering this volume will in fact be the same as entering the drawer Applications:Serious/Music/OctaMED (this is similar to symbolic links). A unique feature of assigns is that multiple drawers can be assigned to a single volume. For example, the assign FONTS: may point to SYS:Fonts (SYS: itself is an assign which points to the install location of the Workbench), Files:Graphics/Fonts, Applications:Serious/Graphics/DeluxePaint/Fonts and many more. The contents of all of these drawers will be accessible in FONTS:, and saving new files into FONTS: will save them into the first assign, in this case they will be saved into SYS:Fonts.

In your new Amiga system you will notice that there are many volumes which do not appear on the Workbench screen, such as C:, Devs:, S:, etc. These are all assigns and point to their respective locations within your Workbench partition.

Transferring Data Between Ubuntu And Real Amigas

CrossDOS

CrossDOS is a piece of software which comes with Workbench 2.1 and above. By copying the "PC0" device from "SYS:Storage/Device Drivers" into "SYS:Devs/Device Drivers" and rebooting you have given your DF0 drive the ability to read FAT formatted floppy discs, compatible with PC floppy drives. By formatting a disc as FAT (be aware that many Amigas, especially those which are contained within their keyboards, can only access DD floppies, that is Double sided, Double Density, which have an unformatted size of 880KB and a formatted size of usually 720KB. HD (High Density, 1.44MB) floppies can still be accessed by these Amigas, but they must be formatted as DD discs) you can save files to floppy disc and transfer them between PC and Amiga. Note that, to keep compatibility with Microsoft Windows and MSDOS, the filenames of files saved to such discs are truncated by CrossDOS to the MSDOS "8.3" style (eight capital letters or other characters, followed by a full stop, then ended by three capital letters or other characters). This is usually the easiest way of transferring small files between your machines.

Swapping Hard Drive

If you have a desktop PC and do not mind opening it up then you can transfer a 3.5 inch hard disk drive between your Amiga and your Ubuntu machine if you want to exchange large, or large amounts of, files. To use a 3.5 inch drive in an Amiga you either need a "big box" Amiga (usually one in the "thousand" series, A1000, A2000, A4000, etc.) which can directly support such drives, or you need to use special IDE cables and internal floppy drive power cables to get it working in a "keyboard case" Amiga. Set up the drive on your Amiga machine and Mount it like you would mount any other drive on Ubuntu, with the partition type as "affs" (Amiga Fast File System [which is not actually that fast these days]). You can save data to Amiga partitons with Ubuntu, but I would not recommend doing it frequently as it may produce corruption on your Amiga partition.

Networking

FIXME: Expand this. Ethernet, serial, possibly parallel.

To Do

Fix all of the FIXMEs

Fix the Wiki's mishandling of Amiga paths (those which include a colon)

See Also

E-UAE homepage - Richard Drummond's website, the maintainer of E-UAE

Amiga Inc. - The current Amiga company. Community sites may give you better information.

Aminet - A vast archive of Amiga software and documents (mainly in LHA format)

Amiga World - A highly active community site for Amiga users (including emulated ones)

Back 2 The Roots - A very useful website with great resources for Amiga emulation

EUAEAmigaEmulator (last edited 2011-09-01 03:06:27 by user-10mt698)