AMIGA XL AND AMITHLON

Introduktion

Systemrequirements

To be able to use AmigaOS XL, you need a standard x86 PC with at least 600MHz tact-rate, recommended is 1GHz or more, and 128 Mb main memory, recommen- ded is 256 Mb.

The PC and the hardwarecomponents used should be supported by QNX 6.1. A list of supported hardwarecomponents can be found at

AmigaOS XL needs QNX 6.1 or newer as host-OS.

Why QNX?

At this time QNX 6.1 is the only whose micro-kernel- and driver- system guarantee a faultless running of the AmigaOS. QNX has many similarities to the AmigaOS. It has a micro-kernel, and the drivers are separate processes which, just as the devices and handlers with the AmigaOS, can dynamically be started and stopped. This leads to a very lightweight system. The user-interface immediately reacts to user-inputs, just as one is used to from the AmigaOS.

QNX confirms to the POSIX-standard, meaning that the paths from / to QNX and vice versa are very short and simple.

QNX can be run in "Big Endian" mode on a PowerPC, which leads to a clear per- formance increase for the AmigaOS hosted on QNX.

1

Installing QNX is extremely simple, secure and very fast. Within just a couple of mi- nutes the hardware is recognised, all necessary items are copied you can start using it.

Credits

The executable AmigaXL is based on the UAE-JIT. Thanks to the Following pro- grammers for that (no special order):

Bernd Schmidt Bernd Bernie Meyer Alessandro Bissacco Hannu Rummukainen Ed Hanway Denis Sablic Marcus Sundberg Stefan Reinauer Marco Nelissen Oliver Moehrke Olivier Raoul Markus Gietzen Herman ten Brugge Tauno Taipaleenmaki Michael Krause Stefan Ropke Joanne Dow Rodney Hester David Varley Christian Schmitt Brian King Holger Jakob Philippe Gerin Jake Hamby Toni Wilen Patrick Ohly Richard Hoffmann Sam Jordan Christian Bauer

2

What you should know about QNX

Multi-user-system

Like all POSIX-systems, QNX is a multi-user-system: multiple users can share the system. For this, one has to log in to the system with a username and password at startup.

Users can be divided in groups. Usually, for instance all normal users can be found in a group called „user“.

It is known for all files in the system which user created them or last changed them. Special user privileges can be set for every file: For yourself, for other users from the same group or for all other users. There can be the following access-privileges: r: Read“. The file can be read. w: Write“. The file can be written to. x: Execute“. The file can be executed as a program.

To change the privileges for a file, you will have to be the user of this file, or the „root“.

The group „root“ contains all privileged users, normally this will be only one so- called superuser „root“. This superuser sees everything, and can do anything. Most far-reaching changes to the system are privileged to him. This ensure that a normal user can not delete system files or the likes.

After you made a clean install of QNX, there is only the superuser without pass- word. So, in the login-dialog, enter „root” for user and leave the password-field empty.

Even if you alone only works with the system, it is recommended that you create a user for yourself. As long as there is no tool for this yet in the user-interface, you will have to open the QNX-Shell („Terminal“) for this, and call the following com- mand:

3

passwd

Various IDs are proposed, which you can accept by simply pressing . Un- der „Real name“ you enter your full name. Under „New password“ you can enter a password, which has to be entered at login. You can however also press the enter- key only, in case you don't need a password.

When working with AmigaOS XL, it can happen that a file is not shown, or you can not access it. The reason for this can be found in the access-privileges of the file, which forbids you to read or write to it.

With the Shell-command "chmod" you can change the access-rights of a file. With the Shell-command "chown" you can change the user of a file. With "use " you can get a short description of both commands (and most other shell-commands).

With "login root" or "su root" you can give yourself superuser-rights from a QNX- shell, even if you did not start this shell as superuser.

Installation and start

Installing QNX

Installing QNX is very easy and fast:

• If there already is an operating system on the harddrive of the PC, which should be kept, first a free (empty or unused) partition needs to be crea- ted. Sufficient free space on an existing partition is not enough: QNX needs its own partition to be used in a useful way. If your harddrive is full, and you can not empty an existing partition and then delete it, you can use a tool like PartitionMagic by PowerQuest to reduce the size of an exi- sting partition. You can get PartitionMagic in PC-software-stores.

• Configure the BIOS of your PC so that it can boot from CD-ROM.

4

• Insert the QNX CD and boot the PC.

• Follow the installation-prompts. If you have an empty partition, you can enter this as destination-partition. If not, you can delete a full partition for use with QNX. Ensure that there are no vital files on this partition, of which you don't have a backup-copy.

Should there be problems when booting QNX, you can search for help here: http://get.qnx.com http://www.qnxstart.com http://qdn.qnx.com

Installing AmigaOS XL

Installing AmigaOS XL is even easier and faster:

• Insert the „AmigaOS XL“ CD-ROM. • Start the QNX Package Installer (in the „Start“-menu under „Software“ or the command pkg-installer in a Shell). • Double-click „CD-ROM Repository“. • Check the line „AmigaOS_XL“. • Click the „Install“-button.

After the installation the AmigaOS XL environment is located in the directory /usr/ . The Workbench Sys: partition will be shown in the directory /usr/amiga/Sy- stem and the Work: partition in the directory /usr/amiga/Work. To ensure correct performance of the AmigaOS XL environment, you should not change these de- fault settings.

5

Starting AmigaOS XL

There are multiple ways to start AmigaOS XL. Important is, that the of QNX ("Photon") must already be running.

STARTING FROM SHELL:

Open a Terminal (a shell). To start the AmigaOS XL you simply enter /usr/amiga/ AmigaXL and press the enter-key.

STARTING FROM THE SHELF:

The user-interface of QNX contains the so-called "Shelf" to start programs in a quick and easy way. After installing QNX, this Shelf can be found at the lower-left border of the QNX environment. To enter AmigaOS XL in the Shelf, you have to start the configure-tool for the Shelf. To do this, click the right mousebutton inside the Shelf, and select the option "Setup". Next, search for a suitable position for AmigaOS XL in the list. Click "Before" or "After", select "Launch Application" as Type, and confirm with "Apply". Enter "AmigaOS XL" as "Name", and under "Command to launch" "/usr/amiga/AmigaXL". Now click "Apply" and "Done".

AUTOMATIC START AFTER LOGIN:

If you wish, you can have AmigaOS XL started automatically after your login. To do this, create a file called phapps in your $HOME/.ph-directory (for instance with touch $HOME/.ph/phapps. Set the "x"-flag for this file chmod a+x $HOME/.ph/ phapps. Use an editor to write the command /usr/amiga/AmigaXL to this file ped $HOME/.ph/phapps.

Deinstalling AmigaOS XL

Should you want to remove AmigaOS XL from your system:

• Start the QNX Package Installer (in the "Start"-menu under "Software" or the command pkg-installer in a Shell).

6 • Select "View My Software".

• Double-click "User Repository".

• Select from the area "System", sub-area "Emulation" the item "AmigaOS_XL".

• Click "Remove".

• Click "Apply".

Your AmigaOS XL installation and the directory /usr/amiga will be completely re- moved. Changes you made there, or any files you stored there, will be lost.

General stuff about AmigaOS XL preboot-Script

AmigaOS XL executes the shell-script /usr/amiga/.preboot before booting the Amiga-environment. As a default this sets

• the general read-rights for the CD-ROM drives (/dev/cd0 .../dev/cd3) Otherwise, only users with „root“ rights can use the AmigaXL Blockde- vice to access the CD-ROM drives. • sets the general read-rights for the floppy-disk drives (/dev/fd0 ... /dev/ fd3). Otherwise, only users with „root“ rights can use the AmigaXL Blockdevice to access the floppy drives. • starts the -driver.

7 The above operations must be executed with „root“-rights, which is why only „root“- users can change this script (see Multi-user-system).

Virtual memory

With the AmigaOS XL it is possible for the first time to transparently make virtual me- mory available for the AmigaOS. Neither the AmigaOS nor Amiga-programs need to fulfill special requirements to use this extra memory.

With the AmigaXL-preferences you can choose whether AmigaOS XL should use virtual memory or not. You will find these under AmigaOS XL in the prefs-drawer of your Workbench. If the virtual memory is deactivated, any memory-usage in the Ami- ga will be taken from the work-memory of the host OS. In this case it can happen that the host-OS doesn't have any memory left, and that problems occur because of this. However, working without virtual memory gives the best performance. As a guideline for faultless functioning, the work-memory ("Fast-Ram") set for the Ami- gaOS XL should not be more than half of the physical memory of the host-.

If virtual memory is activated, memory-areas can be copied to and retrieved from the harddrive, if there is a shortage in physical memory. If a program accesses this swap-memory, there can be a delay, because the memory needs to be reloaded from the harddrive to the physical memory. The virtual memory is not unlimited, it is the size of the swapfile. As a guidance, the workmemory set for the AmigaOS XL should not be larger than the size of the swap-file.

Depending on the capabilities of the host-OS, a change in settings of the virtual me- mory can only be made active after a re-start of the AmigaOS XL or even of the host- OS.

8 Soundoutput

The AmigaXL has an emulation of the Paula-audio-output. With the AmigaXL-edi- tor you can set the quality of this emulation. The better thequality, the more com- puting power is needed for it.

AmigaOS XL comes with an AHI-driver, with which you can directly use the audio- output of the host-OS. With this the best output-quality with the lowest compu- ting-power can be reached. If you don't need the Paula-audio-emulation or the im- portant programs you use use AHI for audio-output, you can deactivate the Paula- audio-emulation completely with the AmigaXL-preferences-editor.

Harddrives and filesystems

The volumes and devices, as used on the Amiga to show harddrive-partitions of the computer, don't exist like that anymore. With AmigaOS XL selected directories from the QNX-paths are shown as devices and volumes to the AmigaOS. For in- stance, the volumenames System: or Sys: are linked to the QNX directory /usr/ amiga/System. This way, one has the benefit of both the speed and the failure- security of the QNX-filesystem. A side-effect of this behavior is that all volu- mes which are on the QNX-filesystem, show the same size and the same free-full proportions.

CD-ROM drives and PC-floppy-disks are further used by an AmigaOS-filesystem. CacheCDFS from AmigaOS 3.9 drives the CD-ROM drive, which improves the compatibility when compared to other Amiga-emulations. For instance the Amiga protectionbits are supported correctly. This way, you can usually install Amiga- software from the CD-ROM as usual.

9 Internet and network

Setting up internet-account through the modem

To set-up an internet account using your modem, you must start the QNX-tool Net- work Config from the Internet-drawer of your Workbench. If you get a warning "You must be root to make changes to network or device settings", you can ignore this warning.

• Change to the "Connections"-page. • Click "Add New Entries". • Enter a clear name for you internet-connection in "Name". Should you have more than one internet connections, you can identify these by this name. • Select the your modem is attached to under "Device". • Enter your username, and optionally your password for this internet-con- nection on the underlying "Network"-page. • On the "Modem"-page under "Number" enter the dialup-number for your internet-connection. To confirm, press the enter-key or click "Add". • If pulse dialing should be used instead of tone dialing, activate the item "Pulse Dialing" (only necessary with very old telephone connections). • If you want to hear the connection being made, activate the item "Spea- ker On".

To conclude the configuration of your internetaccount, click "Apply and "Done".

Connecting to the internet with the modem

The QNX-tool Dialer from the Internet-drawer of your Workbench connects you to the internet. If you start the QNX-webbrowser , and there is no internet- connection yet, the Dialer will be started automatically.

If you have not configured an internet-connection yet, the "Dial-Up"-field remains empty. You can now setup an internet connection by clicking "Edit...". Next, the

10 configuration-tool will be started. (see "Setting up internet-account through the modem" link "Setting up internet-account through the modem").

In the field "Dial-Up", select the internetconnection you want to use to dial in. If you haven't done so yet, enter your password. Click "Connect" to create the connec- tion.

If, when initialising the modem, the error "Connection Failed" occurs, your modem is either not turned on, or it is connected to a different serial port. In the field "De- vice" you can set the serial port to which your modem is connected.

Joystick

The AmigaXL allows the usage of an analogue PC-joystick. This will as default be shown as a digital joystick on port 1 of the Amiga hardware. Port 0 is normally re- served for the mouse.

To be able to use the analogue joystick, a suitable driver must be running. Becau- se QNX 6.1 doesn't offer its own joystickdriver yet, a simple driver comes with Ami- gaOS XL, which is started in the preboot-script (see ".preboot-script" link ".preboot-script") of AmigaOS XL. Make sure that the joystick-port is activated in the BIOS of your PC.

To adjust the joystick, start the program JoystickTest in the Tools}-drawer of your Workbench. Set the adjustingwheels of the joystick so that the joystick- move- ments are displayed correctly.

Ending AmigaXL

To end AmigaXL, simply press the key-combination --. You can also use the program Shutdown (see "Shutdown" link "ShutPa- thconversion

If filenames must be passed to the QNX-program as arguments, they show files in the Amiga-path, for instance:

11 System:S/User-Startup

For the QNX-program to find the files, the pathnames are converted to the QNX- path. If the Amiga-device System: is for instance on the QNX-directory /usr/amiga/ System, through the pathconversion instead ofthe above filename, the following name will be passed to the QNX-program:

/usr/amiga/System/S/User-Startup

The pathconversion can only function if an Amiga-device is located on a QNX-direc- tory. Files on devices that are only known to the Amiga, such as Ram: or CD0:, can not be passed to QNX-programs.

Filenames in the QNX-path are case-sensitive, so the filenames file1 and FiLe1 do not point to the same file. If you do not enter a filename in the correct case, the QNX- program can not find this file.

Tools for AmigaOS XL

Shutdown

The program Shutdown can be found in your Sys:System drawer. With, you can restart or end AmigaXL, or restart and end the entire QNX system.

AudioMixer

The commodity AudioMixer can be found in your Sys:Tools/Commodities-dra- wer. With it, you can set the volume for the various sound-sources, as long as it is supported by your soundcard. You can set the following volumes:

• Master: is the total volume used to control the output of all sound- sources. • Sound: is the volume of the (digitally) created sounds, such as sounds created by audio.device or ahi.device.

12 • CD: is the volume of audio-CDs played by the CD-ROM.

If the the field "Mute" is activated, the chanal will be set to mute, regardless of the current volume-settings.

QNXlaunch

QNXlaunch starts QNX programs form within the AmigaOS XL.

SHELL-USAGE

QNXLaunch is called from the Shell as follows:

QNXlaunch

The arguments for the QNX programs are read as follows:

• If the arguments start with a "-", it will be passed to the QNX program without changes. • If the arguments start with a "%", it will be passed to the QNX program without the "%", but with no further changes. • If an argument is within quotes (and there is no "%" before the first quo- te) it is interpreted as a filename, and will be translated to a QNX-filena- me using the pathconversion (see"Pathconversion" link "Pathconversion"). • All other arguments that do not start with a "&" are interpreted as filen- ames, and will be translated to QNX-filenames using the pathconversi- on (see "Pathconversion" link "Pathconversion").

Example:

QNXlaunch phplay -x30 -y %40 work:music.mp3 is converted to the QNX-call phplay -x30 -y 40 /usr/amiga/Work/music.mp3

13 WORKBENCH-USAGE

To be able to start a QNX-program from the Workbench, you need to create a pro- ject-icon for it, and set the default tool of this icon to QNXLaunch. Following tool- types can be given to the icon:

COMMAND:

This gives the name of the QNX-program. If this tooltype is not entered, the name of the icon will be used as programname. For instance:

COMMAND=phplay

ARGUMENTS:

This sets the arguments for the QNX-program. These will be passed unchanged to the QNX-program. For instance:

ARGUMENTS=-x30 -y40

If, when starting the program, further icons are selected by extended selection, the relevant filenames will be converted to QNX-filenames using the pathconversion (see "Pathconversion" link "Pathconversion", and passed to the program.

PATHCONVERSION

If filenames must be passed to the QNX-program as arguments, they show files in the Amiga-path, for instance:

System:S/User-Startup

For the QNX-program to find the files, the pathnames are converted to the QNX- path. If the Amiga-device System: is for instance on the QNX-directory /usr/ami- ga/System, through the pathconversion instead of the above filename, the following name will be passed to the QNX-program:

/usr/amiga/System/S/User-Startup

14 The pathconversion can only function if an Amiga-device is located on a QNX-di- rectory. Files on devices that are only known to the Amiga, such as Ram: or CD0:, can not be passed to QNX-programs.

Filenames in the QNX-path are case-sensitive, so the filenames file1 and FiLe1 do not point to the same file. If you do not enter a filename in the correct case, the QNX-program can not find this file.

Questions and Answers

Question: On my GeForce2 graphics-card 16 bit screenmodes are displayed all wrong, it only shows false colours

Answer: Some PC graphicscard use strange ways to represent the colourvalues of 16 bit screendepths in the graphics memory - the Picasso96 software can not deal with these representation.

Question: Selecting oversized screens in screenmode leads to crashes.

Answer: This is a weakness of the graphic-driverm which we will fix in the future. At the moment, one can only work with screens which are as wide and high as the screenmode. Leave the option selected in screenmode-preferences.

Question: Can floppy disks be used?

Answer: At the moment only very limited. Amiga floppy disks can't be read at all in a PC-drive, for technical reasons. But also PC-formatted disks still have problems when changing the disks: Either the diskchange is not recognised correctly, or la- ter access of the disk still give read errors. This will be fixed in the future.

Question: When changing from the QNX desktop to a ECS screen, only a border with the mouse is visible.

Answer: A complete redraw of the screencontents, which was lost when changing to the QNX desktop, is not done. Move the mouse all the way up and down once, or change to another screen and back.

Question: The border of ECS screens always show graphical garbage.

15 Answer: A fault in the emulation of ECS screens. Enlarging the visible area of the screen in the Overscan-Prefs to the maximum size should solve the problem. Even better would be: Use Picasso96 screens whenever you can. ECS screens are smal- ler, have less colours and are slower.

Question: Why doesn't HDToolbox show any of the attached harddrives?

Answer: The QNX harddrives (or Windows- or Linus formatted harddrives) are not visible as harddrives on the emulated Amiga at all. Only the mounted volumes Sy- stem:, Work:, Root: and Home: are on these harddrives.

Attached Amiga harddrives are used as harddrives (for instance the program C:MountAmigaHDDs reads the RDB and the partitioninformation, but they are also not shown in the HDToolBox, because the emulation of Amiga harddrives doesn't emulate SCSI-direct access yet.

16 INSTALLING AMITHLON

Simply boot the CD ROM. Watch the boing ball, and the emulated Amiga will boot. You can hold down both mouse keys, which should get you into the early startup menu (if instead you get just a blank screen, press F12-R, and then hold down both mouse buttons again). You might have to do this if you have a real Amiga disk attached, which might have a higher boot priority than the diskimage on the CD. The CD's diskimage's id is "HDH0:".

Special Keys

The left and right Window keys are mapped onto the left and right Amiga keys. The Windows Menu key is mapped onto the Amiga "Help" key.

There are several special key combinations using the F12 key:

F12-R: Do an Amiga Soft-Reset

F12-C: Do an Amiga Hard-Reset

F12-K: Restart the emulation from scratch

amithlon.device

All IDE and SCSI peripherals attached to the PC are accessed through the "amith- lon.device". The device supports serveral "boards"; Board 0 handles IDE hard- ware, board 1 is for diskimages, and board 2 and up correspond to actual SCSI controllers.

Amithlon.device supports NSD and TD64. It supports both Commodore and Phase5 style board/ID/LUN<-->Unit mapping. It also creates device nodes named

17 "2nd.amithlon.device", "3rd.amithlon.device" etc, to accomodate software that does not support board selection via unit numbers.

Glossary

Host-Computer: the computer running the AmigaOS XL, for instance a standard x86 PC.

Host-OS: the operating system running the AmigaOS XL, for instance QNX.

Kickstart (-ROM): is the basis of the AmigaOS. it contains fundamental li- braries and functions, needed to run the AmigaOS.

Swapfile: the file to which swap memory is written, for later re-use. Its size determi- nes the size of the virtual memory of a system, for instance 256 Mb.

Virtual memory: workmemory which is not available as physical memory. From the physical memory, parts that are currently not needed can be written to the swapfile on the harddrive. The memory that is freed by this, can be used for other things. If the memory in the swapfile is needed again, it can be reloaded from the swapfile in the physical memory. If there is not enough place for this in the physical memory, another part has to be put in virtual memory to make place.

18