AmiKit for the Linux Platform Guide v2

NOTE:
Since AmiKit 1.5.0 there is an automatic install script. You can still follow the instructions here if you encounter any problems with the script.

This document makes no assumptions as to your skills at using E-UAE. Whether you are a first time user looking for a helping hand at using E-UAE and AmiKit or an old hand at using E-UAE and need a bit of advice in getting AmiKit to work with it then we hope you find some help for everyone here. There are subtle differences between UAE and E-UAE that we will discuss at the end of this document. Everywhere else you can safely swap E-UAE as we go along.

So, let us begin. First you must have E-UAE installed and at least loading up the setup GUI. You can download either a precompiled binary or the sources from http://www.rcdrummond.net/uae/index.html. Which ever it is you use we assume from here on that it loads up to the setup GUI.

Now would be a good time to download the Linux port of AmiKit. Make sure you are in the directory you want AmiKit to reside. You will need this path later when we add it to the setup GUI. I keep all my emulated Amiga stuff in one directory in my home directory which I named (imaginatively) Amiga-Emulation. Inside there I keep all hardfiles, eg. Beneath.hdf, ROMs and anything else Amiga emulation related. I will admit I keep my directory structures all neat and tidy and that that is not everyone's cup of tea, so there is no hard and fast rules on this, but there are plus points to this sort of layout which I am not going to go into in this document. You will just have to trust me. Just to make clear the paths used as examples are taken from my own setup you do not have to follow them, but if there happens to be a problem and you need extra help sorting it and you post to the AmiKit forums, it would make helping you a lot easier and therefore quicker if you did.

NOTE: Since AmiKit 1.5.0 the package is distributed as a self-executable archive with the automatic install script launched upon its extraction, to install the package manually using the instructions below either unpack the self-executable archive using the --noexec --keep switches (which simply unpacks it and doesn’t launch the installation script) or, if the archive was already self-extracted and the automatic install script was launched, simply exit the script, locate the AmKit-linux-latest.zip archive and follow the instructions below.

That said. Make a directory called AmiKit, cd to that directory and use unzip to extract those sources into the directory you just cd'ed into. (Note that in order to make the overall file size smaller the actual AmiKit.zip archive is located inside another zip archive which should be unpacked first.)

mkdir -p ~/Amiga-Emulation/AmiKit
cd ~/Amiga-Emulation/AmiKit
unzip /path/to/the/amikit/archive.zip

Now you should have the files that make up AmiKit in (if you followed my advice) ~/Amiga-Emulation/AmiKit/. These are Amiga binaries and will not run by themselves without some sort of Amiga emulator running them for you.

There are two distinct .uaerc files (E-UAE configuration files). One for x86 (32bit CPU) and one for x86_64 (64bit CPU). The x86 one is called .uaerc-x86 and the x86_64 one is called .uaerc-x86_64. Depending on your CPU type depends which one you install. If you are unsure on your CPU type then you can run the command 'uname -m' (sans quotes) which will show you.

Now, once you know your CPU type you can then either copy one of the configuration files to your home folder (e.g. /home//.uaerc) where E-UAE will find it automatically (just don’t forget to rename it to .uaerc). If, like me, you like to have several E-UAE configurations for different purposes then you can copy one of the files anywhere you keep your configurations. If you do this then you will need to run E-UAE with the -f switch. For example:

./uae -f /path/to/your/configurations/uaerc-x86 or ./uae -f /path/to/your/configurations/uaerc-x86_64

Now if E-UAE is not already running, run it now. You should be looking at the setup GUI in which E-UAE always starts. This behavior can be changed but for now we need the GUI so we can set it up for use with AmiKit.

AmiKit itself requires an AmigaOS higher then 3.1. For example, AmigaOS 3.5, AmigaOS 3.5 and so on. In this document we will be using Amiga Forever which contains the needed commercial files. If you have AmigaOS3.9 or 3.5 then you will not need Amiga Forever, so, in place of copying the Amiga Forever CD to harddrive copy which ever version you have and replace the names (AmigaOS3.9 or AmigaOS3.5) according in the relevant places throughout this document.

So, we have AmiKit installed and we have our installation media. But, as E-UAE is not yet configured to use the hosts CD/DVD media we have to work around that. We do that by mounting the Amiga Forever CD and then copying the CD contents to hard drive. Again I make a directory in ~/Amiga-Emultion called AmigaForever then I copy the entire CD to that directory.

mkdir -p ~/Amiga-Emulation/AmigaForever
cp -Rav /mnt/cdrom/* ~/Amiga-Emulation/AmigaForever/

Note: to make WHDLoad work (the Amiga Game Loader installed in AmiKit) please copy the ROM3.1 file (in Amiga Forever package it’s named ”amiga-os-310.rom”) to AmiKit/Devs/Kickstarts folder and name it “kick40068.A4000”. Also copy ROM1.3 file (”amiga-os-130.rom”) to the same location and name it ”kick34005.A500”. Don’t forget to copy the “rom.key” file there too.

Now we have AmiKit installed and Amiga Forever installed. Now it is time to add those two directories to E-UAE. If you haven't already fire up E-UAE start it now. When E-UAE starts up it presents the setup GUI which looks like the image below.

 (Click to enlarge)

Looking at the setup GUI, along the tabs across the top you will see 'hard disks'. Click on 'Hard disks'. Click on the 'Add' button and you will be presented with the image below.

 (Click to enlarge)

We first setup AmiKit by clicking on the 'select' button and selecting where you placed the AmiKit files earlier. Set 'Device name' as DH0 and 'Volume name' as AmiKit. Second setup Amiga Forever by clicking on 'Add' then 'Browse', selecting where you put the Amiga Forever files. Set 'Device name' as DH1 and 'Volume name' as AmigaForever.

Once that is done we need to tweak a few setting which are visible in the setup GUI, others we need to edit the ~/.uaerc file directly.

Start at the beginning tab 'CPU' which looks like the image below.

 (Click to enlarge)

If you click on the 'CPU Model' button you will be presented with a list of available CPU types. As you can see in the image below I personally use a 68040 but recommended for AmiKit is a 68020. Again there are no hard and fast rules as to which CPU Model you use but do not try selecting 68060 as the emulation layer is not complete for such a CPU.

Next up we have the 'Memory' tab (image below).

 (Click to enlarge)

Here you must specify an Amiga ROM file. Amiga OS 3.1 ROM is required so click on 'change', find it and select it here. If you are using a Cloanto Amiga Forever ROM then you must specify the ROM key here as well. Both the Amiga OS ROM and the Cloanto ROM key are on the Amiga Forever CD which we copied to hard drive earlier so they are both available.

Here also we can set the various memory settings. AmiKit is memory intensive so as a guide set 2MB Chip Mem, 128MB Z3 Mem and 32MB P96 Mem. These setting you can play with later if you feel more memory is required then up the required setting. Note that you can't use JIT direct memory access if you use more than 32Mb of Z3 memory.

Next we have the Chipset tab (image below).

 (Click to enlarge)

Via the Chipset model button you can get various selections but we strongly recommend you use AGA here. Anything else may produce unexpected results. Emulation speed can be left at defaults.

The sound tab

 (Click to enlarge)

Not a lot to change here. We recommend you set Mode = Accurate, Channels = Stereo and Resolution = 16 bit.

The JIT tab (not available on all systems)

 (Click to enlarge)

The JIT feature (Just In Time compiler) should increase the emulation performance. Currently it works on x86 machines only (not the 64bit CPU). Configure the settings according to the picture. These setting you can play with later if you feel the AmiKit runs slow but the most important thing is to set the 'Translation Buffer' above zero (16384 or more recommended) or JIT won't be activated.

On some systems you might still get performance problems with JIT enabled. If you still do not get any useful performance on your system then try the following:
Edit the ~/.uaerc file and set 'x86.use_tsc=no'
In the JIT settings GUI set 'Flags' to 'Always generate'
NOTE: Do not have the E-UAE GUI running when editing the ~/.uaerc file.

The Game Ports tab

 (Click to enlarge)

Port 0 and Port 1 refers to the Amiga mouse ports. Here they can be emulated in various ways. As you can see in the screen shot for this tab I have Port 0 as Mouse and Port 1 as numeric pad.

And that is as much as you can set currently in the E-UAE setup GUI. So, save the changes, if any, you just made via the 'File' menu and 'Save config'. This will write out the setup setting we just did to a file in your home directory called .uaerc. You can edit this file directly in your editor of choice but if or when you do remember to quit E-UAE and restart it so it picks up the changes.

We are now going to edit ~/.uaerc as there are some settings that are not available via the setup GUI. Open .uaerc in your editor of choice.

You should be looking at a sight similar to the screenshot below.

 (Click to enlarge)

As you can see it is a plain text file. This makes editing the file easy. Look through it and you will see some options that are set as false or true and other options that have strings behind them. Yet other options available simply are not there. We can change and add all available options. Remember to close and reopen E-UAE to make any changes take.

Look for, or search for, the following settings. If something is not to be found then simply add it as well as the string that follows it.

*.use.tsc= (where * means x86 or amd64 depending on your CPU type)

This setting can be ‘yes’ or ‘no’.

There is one flag in the .uaerc settings file that differs depending on CPU type. It is called *.use.tsc=yes/no. On x86_64 CPU's UAE sets this as amd64.use.tsc=yes<.i>, on x86 CPU's it sets it as x86.use.tsc=yes

Whether you need this set to yes or no is entirely up to you. On x86 however, it has been said that setting x86.use.tsc to no speeds up the JIT part. As I said though, how you use this setting is totally your own choice.

bsdsocket_emu= is probably set to 'false'. Change it to 'true' otherwise networking will not work on the Amiga side.

scsi= is an option that is not written out by default so add it and set it to 'true'. This option, along with another one we will get to next, allows the Amiga to use the hosts CDROM/Writer or DVDReader and Writer.

scsi_device= is an option that is usually left blank. On Linux we should add our CD/DVD device node here. E.G. /dev/hda or /dev/sdb etc.

So, those 3 options are:

bsdsocket_emu=true
scsi=true
scsi_device=/dev/hda (or /dev/hdc or /dev/sdc etc)

Another hack worth looking into especially on any Linux x86_64 system is the 'frame rate' setting. Take another look at the image above for the 'chipset' tab and you will see this setting towards the bottom. x86 users will not need this hack as they benefit from JIT which does not yet compile on x86_64 platforms. However, x86 owners can still play with this setting if they want to drain every last drop of speed from the emulation. If you are editing ~/.uaerc or ~/.uaerc-amikit directly the setting to look for is 'gfx_framerate='. By default it is set to 1 but by playing with this setting we can speed up E-UAE. I find a setting of 8 suitable for my needs. You may find a higher or lower figure suits yours. If you use the .uaerc-amikit mentioned below then this setting is already set to 4 so it is worth going both up and down to find that elusive sweet spot.The 'gfx_framerate=' comes at a cost (what trade off doesn't?). The documentation for E-UAE describes it thus:

gfx_framerate= (default=1)

• Specifies the rate at which display frames are rendered when emulating graphics output from the Amiga chipset. can be a number between 1 and 20, where 1 means that every display frame is rendered and 20 means only 1 in every 20 frames is rendered.
• Increasing increases the speed of emulation (there's less work to do), but decreases the quality of the display output.
• For example, when emulating a PAL display (50 Hz), for full-quality output (gfx_framerate=1), E-UAE must update its display 50 times a second. Setting gfx_framerate=4 will cause E-UAE to draw only 1 frame in 4 and thus its display will updated only 12.5 times a second.

Once again this option is worth playing with until you are happy with the output. If AmiKit is already installed and you setup a 'Work' "partition" for the Amiga side then you will have a program called uaectrl installed. Take a look in 'Work:UAE-Control' whilst in the emulator, inside there you will find 'UAE-Control' which is a Workbench program. Once run, or clicked on, it opens a window on your Workbench. It offers the ability to insert and remove 'floppies', basically they load.adf (Amiga Disk Format) images and .ipf (Software Preservation Society format rather then going to and from the setup GUI. As well as that is offers a few things that can be changed at runtime as well as a debug button and a reset button. One of the runtime options it can change on the fly is the frame rate. You can play with this setting for as long as you like and it does make it easier to see what setting suits you. Once you are happy with the frame rate setting you can then enter the same value in the setup GUI and save your config so the change is there on every boot.

There are many more options visible in the settings file which have 'false', 'true', 'yes' or 'no' after them and some with strings. All of these can be switched and generally played with.

We hope this document has proven useful to you and that you derive many hours of enjoyment from AmiKit used with E-UAE.

Tom Newsom (A.K.A. Jeepster)

Differences between UAE and E-UAE

At the top of this document I mentioned some subtle differences between UAE and E-UAE. I am talking about how they store their configuration data not how both setup GUI's look. There is one potential show stopper that you should aware of and that is how UAE and E-UAE store filesystem and hardfile information in ~/.uaerc. While it is possible to keep both programs configuration stting seperate and use the '-f' switch to load whichever one you want to use this can be impractical for many reasons. So, what is this difference? I will show you. Consider how E-UAE stores its information:

filesystem2=rw,DH0:AmiKit:$(FILE_PATH)/Amiga-Emulation/AmiKit,0
filesystem=rw,AmiKit:$(FILE_PATH)/Amiga-Emulation/AmiKit
filesystem2=rw,DH1:AmigaForever:$(FILE_PATH)/Amiga-Emulation/AmigaForever,0
filesystem=rw,AmigaForever:$(FILE_PATH)/Amiga-Emulation/AmigaForever
filesystem2=rw,DH2:Work:$(FILE_PATH)/Amiga-Emulation/Work,0
filesystem=rw,Work:$(FILE_PATH)/Amiga-Emulation/Work

Then UAE:

filesystem=rw,AmiKit:$(FILE_PATH)/Amiga-Emulation/AmiKit2
filesystem=rw,AmigaForever:$(FILE_PATH)/Amiga-Emulation/AmigaForever
filesystem=rw,Work:$(FILE_PATH)/Amiga-Emulation/Work

Notice how E-UAE has the additional 'filesystem2' information? It is that that can stop UAE from loading. Conversely, E-UAE has no problem bootng a UAE created configuration file. All other options can be shared between programs.

 About the author of this guide:

Tom Newsom (AKA Jeepster) has been a Slackware user since 1993. Currently he uses Bluewhite64 which is a 64bit derivative of Slackware. He works from home as a remote administrator and specialises in Slackware administration.

Email: tom [at] jeepster [dot] org [dot] uk
Web Site: http://www.jeepster.org.uk