ATRFS: Mount ATR files as local directories under Linux or Mac

[pcrow]

I have a collection of tools for manipulating and analyzing Atari disk images and files that I've written over the years.  In a recent discussion on my ATR2Unix tool, another user said it would be nice to be able to mount ATR image files as directories in the local file system.  I agreed that this was a great idea, so I wrote a tool to do just this, and I call it ATRFS.

 

https://github.com/pcrow/atari_8bit_utils

 

ATRFS uses the FUSE library to implement a file system in userspace.  This works on most Unix-like operating systems.  I developed it on Linux, but it should work on MacOS if you install the right software (I welcome help on making this work smoothly).

 

Once you have it built, just run "atrfs --name=file.atr subdir" and you'll see all the contents of file.atr in ./subdir/.

 

This currently supports the following file systems:

• Atari DOS 1
• Atari DOS 2.0s
• Atari DOS 2.5
• MyDOS 4.53
• SpartaDOS
• Atari DOS 3 (read-only)
• Atari DOS 4 published by Antic (read-only)
• LiteDOS [added on 12 Sep]

I also have preliminary detection of DOS XE images, but haven't yet implemented read/write support (that's next).  Atari DOS 2.0d seems to be a proper subset of MyDOS, so no additional support is needed.

 

It has some cool features that I tossed in:

• It creates several magic files:
  • .bootsectors: The raw bootsectors (however many the image uses, typically 3)
  • .bootinfo: A text file with additional information
  • .fsinfo: A text file with additional information
• Not shown in the directory, but other magic files are available:
  • .sector#: Fill in the number and it's a file with just that sector.  For example: 'hexdump -C .sector360' will show the VTOC table for DOS 2 disks.
  • .cluster#: For file systems that use blocks or clusters, this will let you dump a file system cluster.
  • FILE.NAM.info: Add ".info" to any file and it will give you a text file with a simple analysis of the file.

 

Things I can use help on:

• Build instructions for MacOS, including installing FUSE.
• SpartaDOS: I probably missed differences between 1.1, 2.0, and 2.1 file systems, so any technical help there would be great.
• Testing!  I probably have bugs.  In particular, renaming with directories gets complicated, especially with SpartaDOS saving the directory name in two places.

 

Please keep a safe copy of all your files before using this in case it corrupts things.

 

Besides DOS XE, I could add support for other file systems.  I could even add support for specific game disks if there is a useful well-defined format.  (I remember back in the day hacking maps in one of the Ultima games...)

Edited September 12, 2023 by pcrow

[pcrow]

I could add write support for DOS 3 and DOS 4, but I don't see as it's worth the effort.

 

Oh, and I forgot to mention one important feature: You can use "--create --mydos --secsize=256 --sectors=65000" to create an image.  It also works with --sparta.  And if you have an image in the DOS2 family and copy a DOS.SYS file over, it will detect that and modify the boot sectors to boot it if it correctly figures out which DOS it is.

[pirx]

drop the link and I am game

[pcrow]

2 minutes ago, pirx said:

drop the link and I am game

https://github.com/pcrow/atari_8bit_utils

 

I can't believe I forgot that!  I would edit the original post to add it at the top if it would let me.

Edited September 10, 2023 by pcrow

[Albert]

@pcrow - You can now edit the first post indefinitely.

Enjoy!

 

 ..Al

[+x=usr(1536)]

3 hours ago, pcrow said:

ATRFS uses the FUSE library to implement a file system in userspace.  This works on most Unix-like operating systems.  I developed it on Linux, but it should work on MacOS if you install the right software (I welcome help on making this work smoothly).

Regarding macOS: this may just be an issue of making sure that the makefile knows where the FUSE libraries, etc. reside.  So far, I've done a fair bit of work with manually pointing includes to where those are, but I get a significant number of build errors after that point.  I'll post (in a spoiler) the output of that build a bit later on.

3 hours ago, pcrow said:

Build instructions for MacOS, including installing FUSE.

The 'Installing macFUSE' part is easy:

• Download the current version of macFUSE from https://osxfuse.github.io/ and install, or:
• Install via brew with `brew install macfuse', or:
• Install via Macports with `port install macfuse'.

Any of those three methods should install all necessary components and create a preference pane in System Preferences for macFUSE.

 

Don't install osxfuse; it's deprecated.  macFUSE is its replacement and is what should be used.

 

As for the build instructions: have the current version of the XCode commandline tools installed.

 

That's about as far as I've got with it since I can't get it to build successfully 

[pcrow]

1 hour ago, x=usr(1536) said:

Regarding macOS: this may just be an issue of making sure that the makefile knows where the FUSE libraries, etc. reside.  So far, I've done a fair bit of work with manually pointing includes to where those are, but I get a significant number of build errors after that point.  I'll post (in a spoiler) the output of that build a bit later on.

My assumption is that the problem would be the use of the fuse3 headers.  If #include <fuse.h> works, but #include <fuse3/fuse.h> doesn't work, that would be it.  There's a define in the makefile that you can comment out, and it will try an older version.

[+x=usr(1536)]

17 minutes ago, pcrow said:

My assumption is that the problem would be the use of the fuse3 headers.  If #include <fuse.h> works, but #include <fuse3/fuse.h> doesn't work, that would be it.  There's a define in the makefile that you can comment out, and it will try an older version.

Unfortunately, it still errors out.  FWIW, this is with the Makefile that was checked in about 5 hours ago and use_modern_fuse=yes commented out.

 

1536@lolbox atrfs % make
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c atrfs.c
atrfs.c:289:11: error: no member named 'st_atim' in 'struct stat'
   stbuf->st_atim = atrfs.atrstat.st_atim;
   ~~~~~  ^
atrfs.c:289:35: error: no member named 'st_atim' in 'struct stat'
   stbuf->st_atim = atrfs.atrstat.st_atim;
                    ~~~~~~~~~~~~~ ^
atrfs.c:290:11: error: no member named 'st_mtim' in 'struct stat'
   stbuf->st_mtim = atrfs.atrstat.st_mtim;
   ~~~~~  ^
atrfs.c:290:35: error: no member named 'st_mtim' in 'struct stat'
   stbuf->st_mtim = atrfs.atrstat.st_mtim;
                    ~~~~~~~~~~~~~ ^
atrfs.c:291:11: error: no member named 'st_ctim' in 'struct stat'
   stbuf->st_ctim = atrfs.atrstat.st_ctim;
   ~~~~~  ^
atrfs.c:291:35: error: no member named 'st_ctim' in 'struct stat'
   stbuf->st_ctim = atrfs.atrstat.st_ctim;
                    ~~~~~~~~~~~~~ ^
atrfs.c:365:97: warning: format specifies type 'unsigned long' but the argument has type 'off_t' (aka 'long long') [-Wformat]
   if ( options.debug ) fprintf(stderr,"DEBUG: %s %s %ld bytes at %lu\n",__FUNCTION__,path,size,offset);
                                                                  ~~~                           ^~~~~~
                                                                  %lld
1 warning and 6 errors generated.
make: *** [atrfs.o] Error 1
1536@lolbox atrfs % 

 

[+kheller2]

https://github.com/hboetes/mg/issues/7
 

[pcrow]

26 minutes ago, kheller2 said:

https://github.com/hboetes/mg/issues/7
 

I applied the defines as suggested in the thread on that issue.

[pcrow]

Update: I got Atari DOS XE read-only support working.

I skipped all verification of the sector labels, so it won't detect corrupt images correctly.

Write support is significantly more work.

It does show the correct time stamps on all files (though there is no time stamp for the root directory itself).  Both modification and creation times are exported (though you normally only notice the modification time).

 

I think that covers all the major DOS releases, so it should get almost all images that aren't full-disk games such that you can at least read and copy files.  But this is fun, so I'll consider other DOS releases if someone is interested.

[woj]

This project is on my to-check-out list, so far I have read the readme files, but I already wonder about one thing and want to throw it at you here - will we be able, now or in a  future version, to mount actual SD cards (or complete images of thereof that one uses with Altirra) with APT partitions on them (and usually having a FAT one along) and read/write files to those?

[Piotr D. Kaczorowski]

@pcrow,

 

Great job! Thank you!

 

I have a small request, if possible. Could you please add the LiteDOS filesystem? LiteDOS is a compact DOS created by Mr. Atari. 

As I recall, it has a filesystem similar to DOS 2.0 but with more space. It's crucial to have both read and write access.

 

LiteDOS can be used for cross-development for users who have Atari, Fujinet, and a local TNFS server with a mounted ATR image, for example, in the LiteDOS format. Using the CC65 compiler or another, one can perform cross-compilation and then directly run it on real Atari hardware.

 

It's also important for such software to manipulate the disk, rather than create an entirely new disk that contains files in the directory.

It's important for all types of LiteDOS formats to work - that is, also those with significantly more disk space for data.
 

Here is the webpage with documentation that includes the filesystem specification:

http://www.mr-atari.com/Mr.Atari/LiteDOS/

 

At one point, I planned to write such a program in Python so it could run on Win/OSX/Linux, but I ran out of time.

If needed, there's also contact with Mr. Atari, who will surely be willing to help.

 

[TGB1718]

I thought I would give it a try, so downloaded to Ubuntu under Windows Subsystem for Linux.

Initially I had an issue with the fuse.h, it appears Ubuntu puts the header in /use/unclude/linux

 

Once I fixed that in the Makefile I get the following error:-

cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=30 "-DFUSE_INCLUDE=<linux/fuse.h>" -D_FILE_OFFSET_BITS=64  -c atrfs.c
In file included from atrfs.c:21:
atrfs.h:115: error: invalid type
make: *** [Makefile:31: atrfs.o] Error 1

 

Which points to this line :-

int (*fs_readdir)(const char *path, void *buf, fuse_fill_dir_t filler, off_t offset, struct fuse_file_info *fi);

 

[TGB1718]

@pcrow I had a bit of  a play, and it appears although Ubuntu says fuse3 is installed, but I couldn't find it, so I found a way

to download the source for fuse3, build it and then install the libraries in /usr/local/lib manually

 

I made the necessary  changes to the Makefile and it built ok.

 

I create a mount point just called atr and tried the demo .atr you supplied and it read fine with the command:-

./atrfs/atrfs --name=disk.atr atr

 

Nice work.

[+x=usr(1536)]

6 hours ago, pcrow said:

I applied the defines as suggested in the thread on that issue.

Out of curiosity, is libbsd required to build atrfs?

 

The macOS defines are definitely present in the header files, but here's what I'm seeing:

 

1536@lolbox atrfs % make
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c atrfs.c
atrfs.c:365:97: warning: format specifies type 'unsigned long' but the argument has type 'off_t' (aka 'long long') [-Wformat]
   if ( options.debug ) fprintf(stderr,"DEBUG: %s %s %ld bytes at %lu\n",__FUNCTION__,path,size,offset);
                                                                  ~~~                           ^~~~~~
                                                                  %lld
1 warning generated.
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c special.c
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c info.c
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c mydos.c
mydos.c:20:10: fatal error: 'linux/fs.h' file not found
#include <linux/fs.h> // RENAME_NOREPLACE
         ^~~~~~~~~~~~
1 error generated.
make: *** [mydos.o] Error 1
1536@lolbox atrfs % 

 

Which makes sense, since the linux/fs.h header file doesn't exist on macOS.

 

[TGB1718]

@pcrow maybe I missed something, but couldn't see how to unmount an ATR, then the penny dropped

just use linux umount DOH!!!

 

[pcrow]

4 hours ago, x=usr(1536) said:

Out of curiosity, is libbsd required to build atrfs?

 

The macOS defines are definitely present in the header files, but here's what I'm seeing:

...

Which makes sense, since the linux/fs.h header file doesn't exist on macOS.

 

Yes, obviously that include will need to be removed.  I should conditionalize that on Linux, as well as the use of the RENAME_REPLACE flag on the rename operation.

 

Edit: I've pushed that change.  I just define the flags as zero so that they never match any bits if it's not Linux.

Edited September 11, 2023 by pcrow

[pcrow]

8 hours ago, woj said:

This project is on my to-check-out list, so far I have read the readme files, but I already wonder about one thing and want to throw it at you here - will we be able, now or in a  future version, to mount actual SD cards (or complete images of thereof that one uses with Altirra) with APT partitions on them (and usually having a FAT one along) and read/write files to those?

That's an interesting idea.  Take a source that is a bunch of ATR files, and create a single mount that covers all of them.  That's probably fairly complicated, though I could see a shell script to do build up a directory structure and mount all the ATR files in it using ATRFS as-is.  It would need a clean-up script to unmount things and clean up the directory.  That could be useful.

[pcrow]

6 hours ago, Piotr D. Kaczorowski said:

I have a small request, if possible. Could you please add the LiteDOS filesystem? LiteDOS is a compact DOS created by Mr. Atari. 

As I recall, it has a filesystem similar to DOS 2.0 but with more space. It's crucial to have both read and write access.

 

I hadn't heard of LiteDOS, but I'll add it to my to-do list.

Edited September 11, 2023 by pcrow

[+x=usr(1536)]

8 hours ago, pcrow said:

Yes, obviously that include will need to be removed.  I should conditionalize that on Linux, as well as the use of the RENAME_REPLACE flag on the rename operation.

 

Edit: I've pushed that change.  I just define the flags as zero so that they never match any bits if it's not Linux.

Using the new Makefile:

 

1536@lolbox atrfs % make
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c atrfs.c
atrfs.c:365:97: warning: format specifies type 'unsigned long' but the argument has type 'off_t' (aka 'long long') [-Wformat]
   if ( options.debug ) fprintf(stderr,"DEBUG: %s %s %ld bytes at %lu\n",__FUNCTION__,path,size,offset);
                                                                  ~~~                           ^~~~~~
                                                                  %lld
1 warning generated.
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c special.c
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c info.c
cc -g -O0 -W -Wall  -DFUSE_USE_VERSION=25  "-DFUSE_INCLUDE=<fuse.h>" -D_FILE_OFFSET_BITS=64  -c mydos.c
mydos.c:1402:97: warning: format specifies type 'unsigned long' but the argument has type 'unsigned long long' [-Wformat]
   if ( options.debug ) fprintf(stderr,"DEBUG: %s %s extend file %lu bytes\n",__FUNCTION__,path,size+offset);
                                                                 ~~~                            ^~~~~~~~~~~
                                                                 %llu
mydos.c:1674:26: error: use of undeclared identifier 'RENAME_NOREPLACE'
   if ( r==0 && (flags & RENAME_NOREPLACE) ) return -EEXIST;
                         ^
1 warning and 1 error generated.
make: *** [mydos.o] Error 1
1536@lolbox atrfs % 

 

[pcrow]

I think I fixed the error.  We can live with the warnings for now.

[+x=usr(1536)]

Good news: it builds!  Thank you!

 

I'm working on getting macFUSE to recognise and use atrfs.  This is being based off of the way that the sshfs package does it, which is to place the binary in /usr/local/bin/, set it 755 / root:staff, and install the man page to /usr/local/share/man/man1/sshfs.1, 644 / root:staff (no ACLs or extended attributes, etc. on either one).  Granted, mentioning the man page right now is getting ahead of things a bit, but figured I'd note it just so it's there.

[+x=usr(1536)]

So far, I've been able to create a blank image, mount it, and both write to and read from it.  File deletion also works, as does renaming. 'Open in Terminal' even works properly from Finder's context menu, which is huge for my typical workflow.  Here's what I'm seeing:

 

1536@lolbox A8 % atrfs --create --name=blank.atr /Volumes/blank 
1536@lolbox A8 % 

 

The image is successfully created and mounted at /Volumes/blank with the following files:

 

1536@lolbox blank % ls -al
total 5
drwxr-xr-x@ 2 1536  staff  1024 Sep 11 21:05 .
drwxr-xr-x  7 root  wheel   224 Sep 11 21:05 ..
-r--r--r--  1 1536  staff   302 Sep 11 21:05 .bootinfo
-r--r--r--  1 1536  staff   384 Sep 11 21:05 .bootsectors
-r--r--r--  1 1536  staff   135 Sep 11 21:05 .fsinfo
1536@lolbox blank % 

 

And the contents of .bootinfo and .fsinfo are:

 

1536@lolbox blank % cat .bootinfo
Boot information
Boot sectors: 3
Load boot sectors at $0700-$087f
Init with JMP $0714
Run after load at: $1540
Max open files: 3 [default] (DOS 2 and compatible only)
Number of drives supported: 2 [DOS 2 default] (DOS 2 and compatible only)
DOS 2 flag for DOS.SYS: $00
DOS 2 DOS.SYS starting sector: 4
1536@lolbox blank % 

1536@lolbox blank % cat .fsinfo 
File system information
Sectors: 720
Sector size: 128
File system type: Atari DOS 2.0s
Total data sectors: 707
Free sectors:       707
1536@lolbox blank % 

 

Trying to do things the FS doesn't support (non-8.3 filenames, extended characters, etc.) are trapped properly with error -43.

 

I'll need to do some further testing with other than the default images, but so far this looks great!  Thanks again!

[pcrow]

Sounds good so far.  I'm sure we'll hit bugs, and I'm pushing updates as I find them.