Category: Amiga

This guide is a continuation / rewrite of piStorm – getting started with Emu68, which was written as a starters’ guide for just getting Emu68 up and running on the piStorm.

Since I wrote that guide, Michal has added similar instructions as I present here to the resources at GitHub.

Resources

Emu68 for piStorm Nightly build
Emu68 Docs section at GitHub

Getting the files you need

As described before, you should look for the latest file named something like “Emu68-pistorm-20211220-62363e.zip”. The content of this file will in the last step be copied to the root of the Fat32 partition of the SD-card.

Preparing the SD-card

Emu68 presents partitions with the 0x76 ID as hard drives to the Amiga side through the “brcm-sdhc.device”, so we need to create at least two partitions on the SD-card (which normally comes prepared as a single Fat32 partition).
I do this using entirely using the command line program “diskpart” on my Windows computer.

Find the “Diskpart” application, either somewhere in the windows menu, or using the search function and search for “cmd”. Right click the icon and select “Run as administrator”. You will be getting a warning that you are going to do something dangerous, accept that one 🙂

The dangerous part

Insert your SD-card, then run “diskpart” from the command prompt. List all recognized disks by the diskpart command “list disk”. If you find the obvious disk (in my case it’s “disk 3”) that must be your SD-card, use the “select disk” command to select it as the current one. List the partitions on the disk with “list part” to ensure you are working on the right disk.

In any case of uncertainty, exit “diskpart” by using the “exit” command, then remove the SD-card and run “diskpart” again and list the disks. The missing one is your SD-card.

Use the “clean” command to remove all the partitions on the SD-card (as seen as the last command in the image above, and as the first in the image below). Create the Fat32 partition. Only a few MB is needed, but I usually allocate 200MB for the Emu68 and kickstart files.
As shown below, I create a 500MB partition, a 2GB partition and one for the rest of the space on the card (in this case 26GB), and with that same command I set the partition ID to 0x76 (which is needed to be specified, so the Amiga can find the emulated disks).

Exit “diskpart” with the command “exit”, and then exit the command line shell, also with “exit”.
Commands above (create partitions):

cre part pri size=200
cre part pri size=500 id=76
cre part pri size=2000 id=76
cre part pri id=76

Give the Fat32 partition a drive letter

sel part 1
assign

Format the Fat32 partition
This can be done in many ways, but as we already are inside ‘diskpart’, I present the easiest way first 🙂

format fs=FAT32 label=Emu68 quick

Another way is either accept to format the partition in the request that windows pops up directly after the “assign” command in ‘diskpart’, or as the same, as described below:
Go to “This PC” in explorer (the file explorer, not the ancient web browser), right click the small partition on the SD-card and select “Format”.

Copy the files from the latest nightly Emu68 to the root of the SD-card. This can be done using WinRAR (rarlab.com) without extracting the files. Just select the latest nightly archive, right click and choose “Extract files…”, then type in the drive letter for the 200MB partition:

Copy your choice of Kickstart ROM (usually a kickstart for the A1200) file to the root of the Fat32 partition and update the config.txt accordingly.

Now the SD-card is ready to be booted on with the piStorm. Boot from some floppy with the AmigaOS hard drive installation utilities, then change the HDToolBox tooltype SCSI_DEVICE_NAME to brcm-sdhc.device then start HDToolbox and set up the partitions on the disks with IDs other than 0 (zero) (which represents the whole disk and should not be used within AmigaOS).

This procedure is well described in the current documentation by Michal (and on a lot of other places), so head over there and read his guide.
If you decide to install AmigaOS 3.2, you do not need to use the PFS3aio filesystem. FFS works fine with large disks and partitions in this release.

This article will probably repeat some points in the piStorm – basic configuration guide. It’s meant as a quickstart for those who not at this time want to explore all the possibilities the piStorm gives.

Be sure to put the files (kickstart and hdf) in the right location on the SD-card, whatever you want, or follow my directions and put them in /home/pi/amiga-files. The important thing is that the paths in the configuration is set to the same.

Installation of AmigaOS 3.1 on a small hard drive

For this installation, I have choosen AmigaOS 3.1 for several reasons. The main reason is its availability, in reach for everyone through Amiga Forever Plus edition, and also because its low amount of installation disks (6 disks needed, instead of 17 or similar for 3.2).

Conditions:
Configuration files are given a descriptive name and put into /home/pi/cfg. At start of the emulator, the actual config is copied as “default.cfg” and put into /home/pi. This is part of what I did to make it possible to switch config files using the keyboard attached to the Pi (Linux: how to run commands by keypress on the local console).
Amiga-related files (kickstart and hdf) are stored in /home/pi/amiga-files

With “floppy”/”disk” (or drive) in this guide, any Amiga compatible replacement, such as a GoTek drive with Flashfloppy, can be used.

For a basic AmigaOS 3.1 installation, have these disks (in this order) available.
amiga-os-310-install
amiga-os-310-workbench
amiga-os-310-locale
amiga-os-310-extras
amiga-os-310-fonts
amiga-os-310-storage

These disks are available from your legally acquired Amiga Forever Plus Edition (or above), any release from 2008 (my oldest one) and up is recent enough. Look for the adf files in the “Amiga files/System/adf” or “Amiga files/Shared/adf” folder.
You also need the kickstart ROM from the same base folder (“System” or “Shared”). The file you want is the “amiga-os-310-a1200.rom”. I have renamed the kickstart file to “kick-31-a1200-40.68.rom” and then put it in my “amiga-files” folder on the pi.

Start by setting up the piStorm configuration for using the correct ROM and for enabling hard drive support:
Copy the configuration template “pistorm/default.cfg” to “/home/pi/cfg/a1200_4068_os31.cfg”, then change/add:

...
map type=rom address=0xF80000 size=0x80000 file=../amiga-files/kick-31-a1200-40.68.rom ovl=0 id=kickstart
...
setvar piscsi0 ../amiga-files/system_31.hdf
...

It’s also important to use a the first available free SCSI id here (piscsi0), as there is a unique feature in piscsi that hides all drives configured following a gap in the SCSI id sequence, so that they won’t be seen in HDToolBox. piscsi0 must always be used by any disk, otherwise, you will get an empty list of drives in HDToolBox.

After saving the changes, go ahead and create an empty hdf for the installation:

dd if=/dev/zero of=/home/pi/amiga-files/system_31.hdf bs=504k count=1000

504MB is enormous in Amiga-terms 🙂
The bs (block size) of 504k gives the piStorm the optimal number of heads (16) and blocks per track (63) on auto-detecting the hard drive geometry.

Insert the amiga-os-310-install floppy and start up the emulator:
(and start with stopping it if it’s running, “killall -9 emulator” or use systemctl if you have followed my instructions on setting it up as a service)

cd /home/pi/pistorm
sudo ./emulator --config ../cfg/a1200_4068_os31.cfg

Workbench will load from the installation disk. Copy HDToolBox from HDTools (put it on the RAM-disk). Change the tooltype SCSI_DEVICE_NAME (to pi-scsi.device).
Run HDToolBox from RAM:, and you will see a new unknown disk. Use “Change Drive Type”, “Define New…” and then “Read Configuration”. Return to the main window (click the “OK” buttons).
Partition the drive. Remove the second partition, and set the size of the first to something large enough for AmigaOS. 80MB is plenty of space (AmgiaOS 3.1 takes up 2.8MB fully installed). Create another partition of the rest of the space. Change the device names of the partitions if you wish.
Save changes and soft-reboot the Amiga (it will boot up from the install floppy again). You will see the two unformatted (PDH0 and PDH1:NDOS) drives. Format PDH0 (or whatever you set as device names), the smaller one, and name it “System”, uncheck “Put Trashcan”, check “Fast File System”, uncheck “International Mode”, then click “Quick Format” and accept all the warnings).

Start the installation from the Install-floppy (select “Intermediate user” to have some control of the options), use whatever language you wish for the installation process and select languages and keymaps as desired. Change floppy when the installer asks for it. Once done, remove the install floppy and let the installer reboot your Amiga.
It will boot up from the hard drive to your fresh installation of AmigaOS 3.1. Format the other partition and name it “Work” or whatever you want. Follow the instructions above (FFS, no trash, no intl, quick format).

That’s it.

a314: access to a folder on the pi as a drive on the Amiga

Most of below is a rewrite of the documentation for a314 for the pistorm.

To make it a lot easier to transfer files over to the Amiga, a folder can be shared as a drive through a314 emulation.

On the pi-side:
To keep contents and configuration files safe when updating the piStorm software, I put the config files in /home/pi/cfg and content in /home/pi/amiga-files/a314-shared. If you do not, and keep the configuration unchanged, the shared files will be in the “data” folder inside the pistorm binary directory (/home/pi/pistorm/data/a314-shared).

Copy the files that needs to be changed for keeping the content safe:

cd
cp pistorm/a314/files_pi/a3*conf cfg

In a314d.conf, change the a314fs line (add the -conf-file part):

a314fs python3 ./a314/files_pi/a314fs.py -conf-file /home/pi/cfg/a314fs.conf

In a314fs.conf, change the location for the shared folder:

{
  "devices": {
    "PI0": {
      "volume": "PiDisk",
      "path": "/home/pi/amiga-files/a314-shared"
    }
  }
}

Then, in the pistorm computer configuration (your copy of ‘default.cfg’), enable a314 and the custom configuration for it:

...
setvar a314_conf /home/pi/cfg/a314d.conf
setvar a314
...

On the Amiga-side:
The needed files are on the pistorm utility hdf (pistorm.hdf, disk named “PiStorm”) pre-set in the default.cfg and you should have had it available since activation of piscsi above.

From the a314 folder on the utility hdf, copy “a314.device” to DEVS:, “a314fs” to L: and append the content of “a314fs-mountlist” to DEVS:mountlist:

copy pistorm:a314/a314.device DEVS:
copy pistorm:a314/a314fs L:
type pistorm:a314/a314fs-mountlist >> DEVS:Mountlist

Then after a restart of the emulator (with the newly modified configuration in place), you should be able to mount the shared folder using “execute command” or from a shell:

mount pi0:

RTG with Picasso96 (old version)

RTG is a standard feature of the piStorm since ‘long’ ago. It requires the Picasso96 (2.0 from Aminet, or the more recent one, renamed P96, from Individual Computer) software to be installed before adding the necessary drivers from the piStorm utility hdf.

On the Amiga-side:
Using Picasso96 2.0 from Aminet, go through the installation process and do not install application drivers or the printer patch, then from the piStorm utility hdf, the installation script for the needed drivers can be found in the “RTG” folder.
You need to have the extracted content of the Picasso96 installation files available during this step of the installation.

On the pi-side:
Activate rtg in the configuration:

...
setvar rtg
...

Restart the emulator. The Amiga will be rebooted at that point. After a reboot, you will have the RTG sceenmodes available in Prefs/Screenmode.

Be sure to test the screenmodes before saving. Some of the modes are less useable because of the way the scaling is handled. I recommend sticking to mainly two resulotions on a 1080p capable screen: 960×540 (and any color depth) and 1920×1080 (up to 16 bit).

a314: networking

How to set up the network using the a314 emulation is well described in the a314 documentation on Github, execpt from how to set it up on “any” Amiga TCP/IP stack.

On the pi-side:
Follow the directions in the documentation for the pi-side, mainly as below:
Enable the a314 emulation in your configuration (should already have been done if you followed this guide):

...
setvar a314
...

Then install pip3, pytun and copy the tap0 interface:

sudo apt install python3-pip
sudo pip3 install python-pytun
sudo cp /home/pi/pistorm/a314/files_pi/eth-config-pi/tap0 /etc/network/interfaces.d/

Add the firewall rules for forwarding packages, and make the rules persistant:

sudo iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE  
sudo iptables -A FORWARD -i wlan0 -o tap0 -m state --state RELATED,ESTABLISHED -j ACCEPT  
sudo iptables -A FORWARD -i tap0 -o wlan0 -j ACCEPT
sudo apt install iptables-persistent

Enable IPv4 forwarding (in the /etc/sysctl.conf file):

sudo nano -w /etc/sysctl.conf

(remove the # from the commented out line)

...
net.ipv4.ip_forward=1
...

Add to the end of /etc/rc.local, but before the “exit 0” line:

...
arp -s 192.168.2.2 40:61:33:31:34:65
exit 0
...

Reboot the pi.

sudo reboot

On the Amiga-side:
If not already done so, copy the a314.device from the piStorm utility hdf to DEVS:

copy pistorm:a314/a314.device DEVS:

Copy the a314 SANA-II driver to devs:

copy pistorm:a314/a314eth.device DEVS:

For the rest of the configuration on the Amiga, you need a TCP/IP stack such as Roadshow or AmiTCP as documented on Github. For any other stack you’re “on your own”. Here are the settings you have to enter in the correct places:
SANA-II driver: a314eth.device (in Miami, it’s the last option “other SANA-II driver”)
Unit: 0
Your IP address: 192.168.2.2
Netmask: 255.255.255.0
Gateway: 192.168.2.1
DNS: 8.8.8.8, 4.4.4.4, 1.1.1.1, 1.0.0.1 or similar (any public DNS will work, these are the Google public DNS servers)

Installing Miami 3.2b

Miami 3.2b is a GUI-based TCP/IP stack for the Amiga available from Aminet. You need three archives to make the installation complete:
Miami32b2-main.lha
Miami32b-020.lha
Miami32b-GTL.lha

Extract these files to RAM: (lha x [archive name] ram:), and start the Miami installer from there. The next step is the configuration. From the folder where Miami was installed, start MiamiInit and follow the guide, giving the values as listed above for IP address, netmask, gateway and DNS.
When you reach the end of MiamiInit, you should input “Name” and “user name”, then save the configuration (you can uncheck the “Save information sheet” and “Print information sheet”.

Start Miami and import the just saved settings.
Click the “Database” button and choose “hosts” from the pull-down menu.
Click on “Add” and fill in your IP-address (192.168.2.2) and name (for example “amiga”).
Click “Ok”, then choose “Save as default” from the Settings menu.
Click on “Online” whenever you want to be connected (auto-online is available only for registered users but I assume you could launch Miami and put it online from ARexx).

After going through my Getting Started guide you have the piStorm starting up automatically (if followed the very last step) as a emulated 68020 CPU. If your onboard kickstart allows it, you might also have 128MB Z3 RAM. It will start up and display the “insert a disk” screen/animation depending on which Kickstart you have on the Amiga motherboard.

Configuration file

The default configuration file, named “default.cfg”, is located in the “pistorm” folder. It’s a good idea to keep this file untouched and make changes to a copy of it, then telling the emulator to use it by using the –config parameter.

In my installations, I have put the copy of “default.cfg” in /home/pi (“../” as a relative path from within the pistorm folder), and keep the rest of Amiga-related files (kickstart and hdf) in a folder named “amiga-files” in the ‘pi’ user’s home (/home/pi/amiga-files).

Here are the very initial steps to copy the default configuration to /home/pi, and to set up the amiga-files folder (after logging in as the ‘pi’ user):

cp -p pisotrm/default.cfg .
mkdir amiga-files

Stop the 68k-emulator if it is running (two methods, depending on how/if it is auto starting):
If started from rc.local:

sudo killall emulator

If set up as a service:

sudo systemctl stop pistorm

Now to autostart the 68k-emulator with a specified configuration file, edit rc.local (if it is started from there) and add –config ../default.cfg so the full command reads:

cd /home/pi/pistorm/ && sudo ./emulator --config ../default.cfg&

For the service method (using my instructions), change the file “start-emulator.sh” in /home/pi:

#!/bin/sh
cd /home/pi/pistorm/
sudo ./emulator --config ../default.cfg
exit 0

Start the 68k-emulator again by running the command from the rc.local file above (for non-service autostart), or by using systemctl if you have set it up as a service:

sudo systemctl start pistorm

For further restarts of the 68k-emulator, do as previously described with “killall” or “systemctl” depending on your choice of setup. With “systemctl” there is also the “restart” option:

sudo systemctl restart pistorm

A restart of the 68k-emulator will also reboot the Amiga.

Configuration options

The default.cfg contains some examples and descriptions of many of the options available. You can also read the current distributed configuration file on GitHub:
default.cfg

Documentation for some the piStorm features for the Amiga is located within some subfolders on GitHub:
piscsi (map hdf files as hard drives on the Amiga side)
rtg (RTG using the Picasso96/P96 package)
net (not fully implemented)
a314 (includes shared folder on sd-card, networking and shell-access to the pi)

CPU type

The easiest one, leave this at “68020”. This is the most complete and compatible CPU for the emulator.

Kickstart mapping

To get better performance and enable Z3 RAM and get P96 2.4+ working, a Kickstart version 3.1 (40.68) for Amiga 1200 is highly recommended. To obtain the kickstart file the correct way, purchase the Plus edition of Amiga Forever. If you own an Amiga 1200, you can also use any of the tools available for saving the kickstart to a file.

You can name the file whatever you want, but mine is named (renamed from the Amiga Forever set) “kick-31-a1200-40.68.rom”, and I have the file in “/home/pi/amiga-files”.

Early in the config, there is this line:

# Map 512KB kickstart ROM to default offset.
map type=rom address=0xF80000 size=0x80000 file=kick.rom ovl=0

It makes the emulator look for the file “kick.rom” in the current directory (as cd:ed to /home/pi/pistorm before starting the emulator).

Change this to:

# Map 512KB kickstart ROM to default offset.
map type=rom address=0xF80000 size=0x80000 file=../amiga-files/kick-31-a1200-40.68.rom ovl=0

Then restart the emulator to see that it uses the kickstart file (easy to spot if you have a 2.x or 1.x KS on the motherboard).

Have the installation floppy for AmigaOS 3.1 ready (also available from Amiga Forever). If you boot the installation floppy, you would end up at the Workbench and be able to see that the FastRAM (128MB Z3) has been mapped.

Memory mapping

The default memory section in the config looks like this:

# Map 128MB of Fast RAM at 0x8000000, also known as 32-bit Fast RAM or CPU local Fast RAM.
# Only supported properly on select Kickstarts, such as 3.1+ for Amiga 1200, 3000 and 4000.
#map type=ram address=0x08000000 size=128M id=cpu_slot_ram
# Map 128MB of Z3 Fast. Note that the address here is not actually used, as it gets auto-assigned by Kickstart itself.
# Enabling Z3 fast requires at least Kickstart 2.0.
map type=ram address=0x10000000 size=128M id=z3_autoconf_fast
# Max 8MB of Z2 Fast can be mapped due to addressing space limitations, but for instance 2+4MB can be chained to leave 2MB for something else.
#map type=ram address=0x200000 size=8M id=z2_autoconf_fast
#map type=ram address=0x200000 size=2M id=z2_autoconf_fast
#map type=ram address=0x400000 size=4M id=z2_autoconf_fast

Pretty self-explanatory, but some of the RAM types are not supported on all Kickstarts. There is no speed difference in using “32-bit FastRAM” compared to “Z3 Fast”. The “Z2 FastRAM” is the equivalent of a RAM expansion plugged into the expansion port of Amiga 500 and Amiga 1000, or in a Zorro slot on the Amiga 2000. These expansions could be standalone or a part of a hard drive controller for those systems.

piscsi – hard drive emulation

The next section in the configuration is about piscsi, which allows you to assign up to 7 auto-mounted and auto-bootable virtual hard drives on the Amiga.

# Uncomment this line to enable the PiSCSI interface
#setvar piscsi
# Use setvar piscsi0 through piscsi6 to add up to seven mapped drives to the interface.
#setvar piscsi0 PI0.hdf
#setvar piscsi1 PI1.hdf

My virtual disk is 1GB in size and consists of several partitions (three smaller ones for different versions of AmigaOS, and a larger one for common content) and is named “amiga-1gb.hdf”. The location for my .hdf is as the Kickstart ROM, “/home/pi/amiga-files”.
To enable the pi-scsi.device, just uncomment the line “setvar piscsi”, then put the name of the .hdf as a parameter the “setvar piscsi0” (or 1-6):

# Uncomment this line to enable the PiSCSI interface
setvar piscsi
# Use setvar piscsi0 through piscsi6 to add up to seven mapped drives to the interface.
setvar piscsi0 ../amiga-files/amiga-1gb.hdf

This will make the Amiga recognize the harddrive with the correct DEVICE tooltype of HDToolbox (“DEVICE=scsi.device” should be changed to “DEVICE=pi-scsi.device”). Once set up using HDToolbox (detect/change disk type and create the partitions), it can be used to install AmigaOS on and boot from.

Also take a look at the current documentation at GitHUb:
piscsi

RTG using Picasso96 or P96

See the documentation at GitHub:
rtg (RTG using the Picasso96/P96 package)

You need two files from the GitHub repository transferred over to the Amiga after having installed Picasso96 or the more maintaned release of P96. I use my registered 2.4.6 from Individual Computers
Google search for 'P96+2.4.6'

See my updated instructions in piStorm – AmigaOS 3.1 installation

Keyboard and mouse passthrough

It’s pretty well documented in the default.cfg:

# Forward keyboard events to host system, defaults to off unless toggle key is pressed, toggled off using F12.
# Syntax: keyboard [grab key] [grab|nograb] [autoconnect|noautoconnect]
#   "grab" steals the keyboard from the Pi so Amiga/etc. input is not sent to the Pi
#   (also helps prevent sending any ctrl-alt-del to the Amiga from resetting the Pi)
#
#   "autoconnect" connects the keyboard to the Amiga/etc. on startup
keyboard k nograb noautoconnect
# Select a specific filename for the keyboard event source.
# This is typically /dev/input/event1 or event0, but it may be event3 with for instance a wireless keyboard.
# Use ls /dev/input/event* to check which event files are available and try until you find the one that works.
#kbfile /dev/input/event1
# Forward mouse events to host system, defaults to off unless toggle key is pressed on the Pi.
# Syntax is mouse [device] [toggle key] [autoconnect|noautoconnect]
# (see "keyboard" above for autoconnect description)
mouse /dev/input/mice m noautoconnect

Just enable the kbfile line and set the correct device there if it doesn’t work with the defaults.

Real Time Clock (RTC)

The RTC is enabled in the default configuration and transfers over the time and date on the Pi to the Amiga.

# Map RTC as a register range.
map type=register address=0xDC0000 size=0x30000

To get the correct time on the Pi, it must be connected to the Internet (as set up in my Getting Started guide).
Also, you must ensure the timezone is set correct on the Pi, otherwise your time will be off an hour or two. To set the correct time zone, hse the ‘timedatectl’ command:

List the available time zones:

timedatectl list-timezones

Set the time zone:

sudo timedatectl set-timezone Europe/Stockholm

Switching between multiple configurations

When you have one configuration you’re happy with, you might want to set up alternative configurations for compatibility or experimental reasons.
I wrote this guide on how to capture keypresses on a keyboard connected to the pi on the piStorm. Before setting up the commands to execute (the very last step), make a copy of your /home/pi/default.cfg, as this file is to be overwritten when changing configuration using the defined keypress events (in my example SHIFT in combination with the F-keys, SHIFT+F12 to reboot the pi, CTRL+SHIFT+F12 to shut down the pi).

Getting files over to the Amiga

Not really a configuration thing, but I’ll explain the possible methods to transfer files (as for example archives for installing, or unpacked archives of programs ready to launch the installer from) over to the Amiga.

Since networking is not yet implemented, and a shared folder from the Linux side is not available, files have to be transferred the ‘classic’ way.

The options as I see are:
* (real) floppy disks
* (adf) through either an externally connected GoTek drive, or as a replacement for the internal drive
* (hdf) a pre-prepared hdf (full RDSK image, not a partition) file containing archives of programs to install
* (adf) from a hdf, mounting using any of the available options like GoADF
* physical disk connected to the pi, then exported as a piscsi device on the Amiga (complicated and a bit risky, described in detail in the piscsi documentation at GitHub)
* since May or June 2021, a314 emulation can be used to access a folder on the SD-card and even transferring files over to the Amiga over the a314 SANA-II network device. You find my detailed instructions on setting up the shared folder and network in my “AmigaOS 3.1 installation guide“.

Some documentation (at least of changes) can be found in the repo: https://github.com/beeanyew/pistorm/tree/wip-crap/

Get and build piStorm software (wip-crap tree)

mkdir -p /home/pi/bnu
cd /home/pi/bnu
git clone https://github.com/beeanyew/pistorm.git
cd pistorm
git checkout wip-crap
make
cd ..
mv pistorm ../pistorm-bnu

Expected output:

Update CPLD bitstream

Build the program to test access to chip RAM

cd pistorm-bnu
chmod +x ./build_buptest.sh
./build_buptest.sh

For EPM240

chmod +x nprog_240.sh
sudo ./nprog_240.sh

For EPM570

chmod +x nprog.sh
sudo ./nprog.sh

wip-crap-only feature configuration

By the merge of July 11 2021, main is up to date with wip-crap.