[hatari-devel] [PATCH] Recommend a combination of udisks2, parted and mtools to access disk images

[Emmanuel Kasper <emmanuel@xxxxxxxxx>]

On recent (post 2015) Linux distributions, udisks is installed for desktop installations, and is able to access MS-DOS partitioned disk images as non-root, and can also access AHDI partitioned disk images as root.

On top of that, parted has now support for AHDI partition, which we can leverage with mtools to access more exotic disk images.

The combination of these two tools, allow now to access any TOS disk image on Linux and presumably other Unixes, thus we can drop the complex matrix recommendation of choosing between EmuTOS, HD Driver and Cecile.

The procedures mentioned here were tested with the following disk images:
- emutos-bootloader disk image (should probably be recommended for hatari)
- HDDriver
- Cecile
- Atari AHDI 5
- ICD 97
- atari-hd-image script generated

This doc change is nearly identical to the blog post at https://00formicapunk00.wordpress.com/2024/12/29/accessing-atari-st-disk-images-on-linux/
---
 doc/manual.html | 176 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 114 insertions(+), 62 deletions(-)

diff --git a/doc/manual.html b/doc/manual.html
index b0707ff0..7c1348f5 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -2887,83 +2887,135 @@ You can convert HD Driver ZIP package to floppy image with the
 
 <h3>Accessing HDD image partitions outside of Hatari</h3>
 
-<p>
-If you want to access the hard disk image partitions also outside
-the emulation, the disk image needs to have a DOS partition table.
-The <span class="commandline">atari-hd-image</span> script included
-with Hatari can be used to create such an image.
-</p>
-<p>
-Inside the Hatari emulator, EmuTOS can access partition(s) on these
-kind of images directly without any driver software.  Of the Atari HD
-drivers mentioned above, Centek's C&eacute;cile and Uwe Seimet's HD Driver
-(demo) work fine with these partitions. E.g. AHDI and CBHD don't.
-C&eacute;cile works only with TT or Falcon.
-</p>
-<p>
-To summarise; if EmuTOS is enough, use that. Otherwise, if you want to
-use TT or Falcon emulation, use C&eacute;cile (or full HD Driver version if
-you have it), otherwise use HD Driver (demo).
+<h4>Accessing the content of a partition using a user mounted loop device</h4>
+
+<p>This is the easiest procedure and should be tried to first. Depending if your
+Linux kernel has support for AHDI partition tables, and the size of the FAT
+system on the partition, this procedure might not work. In that case, try the
+procedure using mtools further below.</p>
+
+<p> Attach a disk image called hd80mb.image to a loop device:
+<pre>
+$ udisksctl loop-setup --file hd80mb.image
+Mapped file hd80mb.image as /dev/loop0
+</pre>
+
+Notice how the kernel detected the partition table:
+<pre>
+$ dmesg | grep loop0
+[160892.151941] loop0: detected capacity change from 0 to 164138
+[160892.171061]  loop0: AHDI p1 p2 p3 p4
+</pre>
+
+Inspect the block devices created for each partition:
+<pre>
+$ lsblk | grep loop0
+</pre>
+
+If the partitions are not already mounted by udisks2 under
+<span class="file">/media/</span>, mount them manually:
+<pre>
+$ sudo mount /dev/loop0p1 /mnt/
+$ ls /mnt/
+SHDRIVER.SYS
+</pre>
+When you are finished copying data, unmount the partition, and detach the loop
+device.
+<pre>
+$ sudo umount /mnt
+$ udisksctl loop-delete --block-device /dev/loop0
+</pre>
 </p>
-<p>
-To access the content of the partitions on Linux host, there are two
-possibilities:
 
-<h4>Using Mtools</h4>
+<h4>Accesssing the content of a partition using mtools and parted</h4>
+
+<p> This procedure uses the mtools package and the support for the AHDI
+partition scheme in the <span class="commandline">parted</span>
+partition editor.</p>
+
 <p>
-For this you need to add an entry for the hard disk
-image to your <span class="commandline">~/.mtoolsrc</span> and
-specify which partition you want to access from the image. For
-an image created with the above mentioned script, the line in
-the configuration file should look something like this:
-</p>
+Display the partition table, with partitions offsets in bytes:
 <pre>
-MTOOLS_NO_VFAT=1
-drive c: file="/home/user/hatari/hd.img" partition=1
+$ parted st_mint-1.5.img -- unit B print
+...
+Partition Table: atari
+Disk Flags:
+
+Number  Start       End         Size        Type     File system  Flags
+ 1      1024B       133170175B  133169152B  primary               boot
+ 2      133170176B  266339327B  133169152B  primary
+ 3      266339328B  399508479B  133169152B  primary
+ 4      399508480B  532676607B  133168128B  primary
 </pre>
-<p>
-Note that Mtools is instructed to use FAT compatibility mode because
-EmuTOS cannot deal properly with VFAT file information.  If you don't
-want this setting for all your Mtools drives, you can set it also via
-the environment like this ("::" refers to the drive image given with
-the "-i" option):
-</p>
+
+Set some Atari-friendly mtools options:
 <pre>
-MTOOLS_NO_VFAT=1 mcopy -spmv -i hd.img files/* ::
+$ export MTOOLS_NO_VFAT=1
 </pre>
 
-<h4>Using a loopback device</h4>
-<p>
-This is recommended even by Mtools documentation, but it is less convenient
-as it requires root rights. First you need to "loop" mount the image:
-</p>
+List the content of the partition, passing as parameter the offset in bytes of
+the partition: For instance here we are interested in the second partition, and
+the parted output above indicates that this partition starts at byte offset
+133170176 in the disk image.
 <pre>
-$ su
-# image="hd.img"; mountdir="hd"
-# start=$(parted $image unit s print | awk '/ 1 /{print $2}' | tr -d s)
-# losetup -f $image -o $((512*$start))
-# loop=$(losetup -a | grep $image | cut -d: -f1)
-# mkdir -p $mountdir
-# mount -t msdos $loop $mountdir
+$ mdir -s -i st_mint-1.5.img@@133170176
+Volume in drive : has no label
+Directory for ::/
+
+demodata          2024-08-27  11:43
+        1 file                    0 bytes
+
+Directory for ::/demodata
+</pre>
+
+We can also use the command <span class="commandline">mcopy</span> with a
+similar syntax to copy data from and to the disk image. For instance here we
+copy a file named file.zip to the root directory of the second partition:
+<pre>
+$ mcopy -s -i st_mint-1.5.img@@133170176 file.zip ::
 </pre>
-<p>
-This uses <span class="commandline">parted</span> to find out the first
-partition offset in sectors and then tells <span class="commandline">losetup</span>
-to bind the first free loop device to a corresponding offset from
-the <span class="commandline">hd.img</span> image.
-<span class="commandline">mount</span> is then used to mount the file system
-from the loop device on top of the "hd" directory.
 </p>
-<p>
-After you have copied the relevant files to the "hd" directory, you need
-to unmount the file system and remove the loop device binding before
-using the disk image from Hatari:
+
+<h4>Recompiling mtools to access large partitions</h4>
+
+<p>For disk images having large AHDI partitions (well considered large in
+1992 …), you might encounter the error:
+<pre>
+mdir -s -i cecile-falcon-singlepart-1GB.img@@1024
+init: sector size too big
+Cannot initialize '::'
+</pre>
+This error is caused by the non-standard large logical sectors that the TOS
+uses for larger FAT partitions.
 </p>
+
+<p>We can inspect the logical sector size using fsck tools:
 <pre>
-# umount $mountdir
-# losetup -d $loop
+$ udiskctl loop-setup --file cecile-falcon-singlepart-1GB.img
+$ sudo fsck.fat -Anv /dev/loop0p1
+fsck.fat 4.2 (2021-01-31)
+...
+Media byte 0xf8 (hard disk)
+16384 bytes per logical sector
 </pre>
+</p>
 
+<p>To access the partition, you need to patch mtools, so that it supports a
+logical sector size of 16384 bytes. For this you need to change the MAX_SECTOR
+macro from 8192 to 16384 in <span class="file">msdos.h</span> in the mtools
+distribution and recompile. A rebuilt mtools is then able to access the
+partition:
+<pre>
+$ /usr/local/bin/mdir -s -i cecile-falcon-singlepart-1GB.img@@1024
+ Volume in drive : has no label
+Directory for ::/
+
+CECILE   SYS      8462 1998-03-27  22:42
+NEWDESK  INF       804 2024-09-09   9:23
+        2 files               9 266 bytes
+                      1 072 463 872 bytes free
+</pre>
+</p>
 
 <h2 id="Performance">Performance</h2>
 
-- 
2.39.5