Wine Altirra - working with VHD files on Linux

[woj]

No, it's not a question, it is a tutorial Promised myself to do something Atari-useful this weekend, my experimental PCBs are still in the mail, so here it goes.

 

My quest was to figure out the possible ways of creating and using VHD files on Linux to be used with Altirra, more specifically the SIDE3 device emulation. Now, you will say that one can create VHD files from within Altirra and Bob is your uncle. This, however, creates a totally empty drive, and unless it is not to be used entirely for APT partitions and formatted from the Atari/SDX level, you are still in trouble in the Linux land, as it is possible to mount VHD files (even for R/W operations, see below), but for editing partitions or formatting them there is still no easy way of doing it on Linux (and frankly I actually did not find any way for this particular thing). All this information is not new or anything, it is all out there, but sometimes you need to do 2+2, and also, some tutorials on this are totally wrong.

 

In any case, below my notes on how to go about doing all this and having relatively full control over the VHD files and their contents from Linux. One step in this, unfortunately, requires having VirtualBox tools installed (no need to
have any Windows virtual machines though). I do this on Ubuntu 20.04, your mileage may vary, and even on Ubuntu you can go alternative routes at some points. You may also need to have some packages installed on Linux that I already have (I had tons of crap accumulated over time).

 

There are four steps to get there:

1. Create and initialize an empty drive image with suitable partitions
2. Pre-populate the image with files
3. Convert that to an VHD file
4. Mount the VHD file on Linux to extract from or add new files to the virtual drive

 

Preemptive warning - make sure you do not have the same VHD file mounted / used by multiple ends, like Linux / VirtualBox / Altirra, this may end up in a total disaster. I am also very modest with any deeper explanations, I hope that if you are in the Linux land you do have some clue of what you are doing and what these things are.

 

1. Create an empty drive image and setup a FAT partition

 

dd if=/dev/zero of=sd.img bs=1M count=32

 

(adjust the count parameter to the desired size, this one is for 32MB)

 

fdisk sd.img

 

Inside fdisk, do "o" to write a DOS label, "n" to create a new partition, choose (p)rimary, hit Enter through other questions to get the defaults. Then say "t" to change type, choose "c" for FAT, and finally say "w" to write the partition.

 

sudo losetup -Pf --show sd.img

 

This will print you the loop device identifier that was linked to your image file, let's say it is /dev/loop5 (almost certainly it will be different for everyone, and it cab be different each time you do it). You can also use "lsblk" to see your loop device with the partition you created listed. Now you can format the partition with:

 

sudo mkfs -t vfat /dev/loop5p1

 

At this point you can go two different routes to put some initial files on it, one is the "old-school" using mount, one is using Ubuntu / modern facilities.

 

2a. Pre-populate the image with files, old-school way

 

Keep the loop device linked, and then:

 

sudo mount -t vfat -o loop /dev/loop5p1 /mnt

 

With super user privileges (sudo bash for example) you can now copy your files to /mnt. When done, unmount all this and unlink the loop device:

 

sudo umount /mnt
sudo losetup -d /dev/loop5

 

Go to point 3. below

 

2b. Pre-populate the image with files, udisksctl / Ubuntu way

 

First, unlink the loop device you created in step 1. if it is still linked.

 

sudo losetup -d /dev/loop5

 

Then:

 

udisksctl loop-setup --file sd.img

 

This will also print the loop device identifier assigned to your sd.img file, but here this is probably irrelevant. Instead, the Ubuntu file mounter should kick in, mount this for you and offer to open a file browser, use the file manager tools you are familiar with to copy the files over. (This should be the same behavior and procedures you get when inserting a USB Flash drive). When you are done you can simply unmount / eject the drive through the OS GUI. Alternatively, if for whatever reason the automatic mounting did not work, you can do things by hand:

 

udisksctl mount -b /dev/loop5p1

 

Similar to the automatic way, this will mount it at /media/<your user>/<disk label>. When done copying your files over, do:

 

udisksctl umount -b /dev/loop5p1
udisksctl loop-delete -b /dev/loop5

 

3. Create the actual VHD file that you can use with Altirra

 

For this step you need to have the Oracle VirtualBox tools, installing VirtualBox is outside of scope of this instruction.

 

VBoxManage convertfromraw sd.img image.vhd --format VHD

 

This will create a expandable VHD, if you want to have the fixed size one (it will be as large as the sd.img file you created), you can add "--variant Fixed" at the end of the last call. At this point you can use image.vhd with Altirra, and it is now safe to delete sd.img (unless you want to keep it for whatever reason).

 

4. Mount the VHD file to later add more files from Linux, or copy files you created on Atari back to Linux

 

Do not do this when Altirra is running and has the VHD file in use! For this you need guestfs things, install them with (for me it pulled in quite some dependencies):

 

sudo apt-get install libguestfs-tools

 

Then you need to figure out the device identifier for the partition inside the VHD, though I am convinced it is /dev/sda1 in 99.9% of cases, the proper way to do this is:

 

sudo guestfish --ro -a image.vhd

 

Inside guestfish say:

 

run
list-filesystems
exit

 

The second command will give you the device name for the FAT partition inside, you then use it with this command:

 

sudo guestmount -a image.vhd -m /dev/sda1 --rw /mnt

 

(/dev/sda1 is what you get from list-filesystems above). Now you can copy things to and from /mnt, but you do need to be in the superuser mode for this. When done, unmount (again, do not forget this before starting Altirra again!):

 

sudo guestunmount /mnt

 

And that is pretty much it. For the last point you can also use a Windows virtual machine if you have one running under VirtualBox, and mount image.vhd there to copy files with your virtual Windows, but I leave that exercise for the curious.
 

Edited February 4, 2023 by woj

[phaeron]

Altirra supports raw images, so you can mount the raw image directly if you want to. You can also use a fixed VHD image and just exclude the last 512 bytes when mounting it loopback.

 

 

[woj]

11 hours ago, phaeron said:

Altirra supports raw images, so you can mount the raw image directly if you want to. You can also use a fixed VHD image and just exclude the last 512 bytes when mounting it loopback.

 

 

Thank you for the feedback, from the man himself  So, all I described still stands for expandable VHD images, which make perfect sense for images of a large defined size in the range of GBs (though I do realize it is a bit pointless in an emulated environment to stick to such large sizes). For small ones, one can keep the fixed format and then take the raw image route. I had no idea raw images are supported in Altirra, the dialog does not suggest that, and I was too lazy to read any docs / help screens (typical, isn't it). Just tried, indeed works perfect.

 

Anyhow, to then complete the tutorial.

 

5. Easier way to mount the VHD if it is a fixed size one

 

udisksctl loop-setup --size 33554432 --file image.vhd

 

where the size is the size of the image.vhd file minus 512 (you could script it not to do the calculations by hand, again exercise for the inclined). After this you end up the same situation as the 2b. scenario in the first post. The plus thing is that you stay in user space this way, and you can also unmount / disconnect everything with one GUI click.

 

6. Convert VHD back to RAW

 

VBoxManage clonehd image.vhd sd.img --format RAW

 

The VHD can be of any kind, so also expandable.