		  Acorn 8-Bit ADFS Filesystem Structure
		  =====================================
		   mdfs.net/Docs/Comp/Disk/Format/ADFS

Acorn 8-bit ADFS is often refered to as ADFS-S, ADFS-M and ADFS-L, but
these refer to the size of formatted floppy disks. The filesystem is
identical, and is the same regardless of the media the data is on.

Acorn ADFS uses 256-byte logical disk sectors. Logical sectors are counted
with 24-bit numbers starting from &000000 at the start of the filesystem,
so the largest possible ADFS disk system is 4G. Acorn ADFS uses 32-bit
file lengths, so the largest possible file is 4G-1.

However, the ADFS API uses the top three bits of the sector address to
specify the drive, leaving 21 bits to specify the logical sector, so in
practice the largest possible filesystem is 512M.

Floppy disks are formatted to 2 sides, 80 tracks, 16 sectors, 256 bytes
for ADFS-L, 1 side for ADFS-M, and 1 side 40 tracks for ADFS-S. Tracks
are sequential, that is logical_sector=sector+track*16+side*1280. Logical
sector zero is zero bytes from the start of the physical disk (ie, sector
&000000). Hard drives have 256-byte sectors. Logical sector zero is 0
bytes from the start of the physical disk (ie sector &000000).


Sector 0,1 - Free Space Map
---------------------------
The first two sectors contain the free space map and disk identifier.
Sector 0 contains the start sectors of the free space blocks, sector 1
contains the length of each free space block.

000-002 	Start sector of first free space
003-005 	Start sector of second free space
006-008 	Start sector of third free space
...
0F6-0F8         Sector of Level 3 fileserver partition 'sec1', or zero
0F9-0FB 	Reserved (set to zero)
		(RISC OS stores half the disk name at 0F7-0FB, interleaved
		with the even characters at 1F6-1FA)
0FC-0FE 	Total number of sectors on disk
0FF		Checksum of sector 0

100-102 	Length of first free space
103-105 	Length of second free space
106-108 	Length of third free space
...
1F6-1F8         Sector of Level 3 fileserver partition 'sec2', or zero
1F9-1FA 	Reserved (set to zero)
		(RISC OS stores half the disk name at 1F6-1FA, interleaved
		with the odd characters at 0F7-0FB)
1FB-1FC 	Disk identifier
1FD		Boot option, set with *OPT 4
1FE		Pointer to end of free space list
		ie, 3*(number of free space blocks)
1FF		Checksum of sector 1

The checksums are calculated by starting with 255, then adding with carry
the 255 bytes of data, adding the bytes counting downwards from byte 254
to byte 0. The following BASIC code will do this.

	DEFFNadfs_sum(mem%):LOCAL sum%:sum%=255
	FOR A%=254 TO 0 STEP -1
	IF sum%>255:sum%=(sum%+1)AND255
	sum%=sum%+mem%?A%:NEXT:=sum%AND255

Note that a lot of documentation (including earlier versions of this
document) gets this wrong, often starting from 0 instead of 255, and adding
upwards instead of downwards.

The Disk Identifier is set to a random 16-bit number on initialisation.

A 'Bad map' error is generated if the checksums are wrong, or if bits
29-31 of any start sector are nonzero, or if bits 29-31 of any length are
nonzero.


Sector 2-6 - Root Directory
---------------------------
The five sectors following the Free Space Map contain the '$' root
directory. The parent of the root directory is again the root directory.


Directories
-----------
Directories occupy five logical sectors - &500 bytes - in the following
layout.

000	Directory Header
005	First directory entry
01F	Second directory entry
039	Third directory entry
...
4B1	47th directory entry
4CB	Directory Footer


Directory Header
----------------
  0  1  2  3  4
+--+--+--+--+--+
|Sq| H  u  g  o|
+--+--+--+--+--+
000		Directory Master Sequence Number in BCD
001-004 	Directory identifier - "Hugo"


Directory Entries
-----------------
  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F 10 11 12 13 14 15 16 17 18 19 
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Object name and attributes  | Load Addr | Exec Addr |  Length   | Sector |Sq|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
000-009 	Object name and access bits
		Access bits are encoded in b7 of bytes 000-009
		000: 'R' - object readable
		001: 'W' - object writable
		002: 'L' - object locked
		003: 'D' - object is a directory
		004: 'E' - object execute-only
		005: 'r' - object publicly readable
		006: 'w' - object publicly writable
		007: 'e' - object publicly execute-only
		008: 'P' - object private
		Files are created with 'WR' access, directories
		are created with 'DLR' on 8-bit systems and
		'DR' on 32-bit systems.
		ADFS ignores the bits stored in bytes 5 to 8, but some
		ADFSs will store and retrieve them to allow them to be
		preserved when transfering files to and from other filing
		systems.

00A-00D 	Load address
00E-011 	Execution address
012-015 	Length
016-018 	Start sector
019		Sequence number


Directory Footer
----------------
4CB   4CD   4CF   4D1   4D3   4D5   4D7   4D9   4DB   4DD   4DF   4E1   4E3   4E5   4E7   4E9   4EB
   4CC   4CE   4D0   4D2   4D4   4D6   4D8   4DA   4DC   4DE   4E0   4E2   4E4   4E6   4E8   4EA
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|       Directory name        | Parent |                    Directory title                     |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

   4ED   4EF   4F1   4F3   4F5   4F7   4F9   4FB   4FD   4FF
4EC   4EE   4F0   4F2   4F4   4F6   4F8   4FA   4FC   4FE
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|          Reserved, set to &00           |Sq| H  u  g  o|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

4CB		&00
4CC-4D5 	Directory name
4D6-4D8 	Start sector of parent directory
4D9-4EB 	Directory title - initially set to same as directory name.
4EC-4F9 	Reserved (set to zero)
4FA		Directory Master Sequence Number in BCD
4FB-4FE 	Directory identifier - "Hugo"
4FF		&00 - This is used by 32-bit ADFS as a directory checksum,
		if it is zero it is ignored. 8-bit ADFS always ignores it,
		and writes it as a zero.

A directory is reported as 'Broken' if the Master Sequence Number and "Hugo"
strings do not match - bytes 000-004 are compared with bytes 4FA-4FE.

Strings in directories are terminated with &0D or &00 if shorter than ten
characters, they are not space padded as with most other filesystems.

The objects in a directory are always stored in case-insensitive sorted
order. If objects are not sorted, then mis-sorted entries will not be
found by filing system operations.

The final directory entry is followed by a &00 byte, in a full directory
this &00 byte is the byte at &4CB.
