DOS XE Technical Details (sector 1, VTOC, etc.)

pcrow · September 6, 2023

My searching is failing me, and I can't find details on DOS XE internal structures.

I know that the VTOC on logical sector 4 starts with 10 bytes of disk status, and I've figured out several of them:

byte 0: unknown

byte 1: unknown

bytes 2-3: total logical sectors

bytes 4-5: free logical sectors

byte 6: unknown

byte 7: unknown

bytes 8-9: volume number (to be used in sector labels)

I can't find anything on the non-code fields in the boot sectors other than the ones that are standard from the OS and that there is a "32-byte drive table." I think the drive table starts at offset 16, as my sample image has "AT810" there, three bytes, then the total and usable sectors.

It looks like it puts 'X' in byte 0 of sector 1 to indicate DOS XE.

There is a lot of information in the users manual, including the directory structure, but the above details aren't documented there, and I haven't found them.

Thanks for any pointers.

AtariGeezer · September 6, 2023

-------------------------------------------------------------------------

DOS XE
maximum file extent of 1500 clusters, or 375000 bytes (366.2 KB).
Max # of Files Per Disk: 65535
Max # of Files Per Directory: 1250
Max # of Clusters: 65535
Max # of Chars in a Pathname: 80 "D1>PROGRAMS>BASIC>PROGRAM1.BAS"

>>Boot Sector:
Byte:     Desc:
$00     - "X" Representing DOS XE
$09     - number of files possible to open at a time. Default 3, max. 7.
$0A     - a bitmap of active drives: bits 76543210 correspond to drives 12345678.
            A bit set to 1 means that the corresponding drive is active.
$0B     - $00
$0C-$0D - Buffer Base Address.
$0E-$0F - Date Code when DOS Was Written.
$10-$15 - an ASCII string, up to 6 characters, padded with zeros,
            if shorter, symbolizing the density (or disk type):
          - AT810 - single density
          - AT1050 - medium density
          - SSDD   - single sided double density (180k)
          - XF551 - double sided double density (360k)
          - 130RAM - 130XE ramdisk
$16     - 0x01   NOT Number of VTOC Clusters on Disk.
$17     - 0x01   ???.
$18-$19 - total number of clusters on the disk, (Plus 1).
$1A-$1B - initial number of free clusters on the disk
$1C     - First Byte of VTOC.
$1D     - number of the first cluster of the main directory
$1E-$1F - SIO Routine Address.
$22     - SIO command "Read sector",
            "R" for standard,
            "R"+$80 for XF551 fast mode.
$23     - SIO command "Write sector", "W" for standard etc.
$24     - Pokey's AUDF3/4 value to generate the command baud rate,
            $00 for standard, $28 for XF551 fast mode.
$25     - Pokey's AUDF3/4 value to generate the data baud rate,
            $00 for standard,
            $10 for XF551 fast mode.
$26     - SIO command "Format disk" for this disk type, "!" for standard
            interleave, "!"+$80 for turbo interleave. If the disk does not need
            formatting (ramdisks etc.), $00.
$28-$2f - first 8 bytes of the PERCOM block defining the disk parameters
            (number of tracks, sectors per track, sector size etc.)

>>VTOC:
----
The VTOC is held in the cluster 4 (sector 4 in DD, sectors 8-9 in SD and ED).
In the first 10 bytes there is disk information as follows:
      $00-$01 - value $0101, format magic/version number?
      $02-$03 - total number of clusters on disk, (Plus 1).
      $04-$05 - number of currently free clusters
      $06-$07 - number of files and directories on the disk
                  (= volume sequrntial number), intially $0000
      $08-$09 - volume random number

The further part of the VTOC, from byte $0a onwards, is occupied by the bitmap.
If a bit is set to 1, it means that the corresponding cluster is free, or it is
    in use otherwise.
Bit 7 of each byte is assigned to a cluster of a lower number, and the
    subsequent bits of the byte correspond to subsequent clusters.
The cluster 0 has no corresponding bit in the bitmap, bit 7 of the first
    byte in the bitmap (byte $0a of VTOC) corresponds to cluster 1,
    bit 6 - to cluster 2, bit 5 - to cluster 3 etc.

Initially the first free cluster of the disk is cluster 6, and the first byte
of the bitmap has a value of %00000111 (clusters 1-5 in use, 6-8 free).

>>Directories:
-----------
The main directory begins right after the VTOC, and initially occupies
only one cluster.
Its number is indicated by the byte $1d of the bootsector.
A single direcotry entry consists of 49 bytes:

$00 - status byte:
      - bit 7 = 1, file deleted
      - bit 6 = 1, file in use. In closed files bit 7 and 6 always have opposite values.
      - bit 5 - unused
      - bit 4 - unused
      - bit 3 - unused
      - bit 2 = 1, the file is open for write. Bits 7 and 6 are simultaneously set to 1.
      - bit 1 = 1, file protected
      - bit 0 = 1, subdirectory

$01-$08 - file name padded with spaces, if necessary
$09-$0b - file name extension padded with spaces
$0c-$0d - number of data clusters occupied by the file. $0000 for a dir.
$0e     - number of data bytes in the last cluster of the file. $00 for a dir.
$0f-$10 - global file number (volume sequential number at the time when the file
            or dir was created, plus 1).
$11-$12 - volume random number (same as in VTOC)
$13-$14 - dir: number of the first cluster of the directory data
           file: number of the first cluster of the file map
$15-$2a - dir: 22 zeros
           file: 11 numbers of subsequent cluster of the file map ($0000 - unassigned)
$2b-$2c - file creation date:
          - bits 0-4 day of month
          - bits 5-8 month ($01 = January etc.)
          - bits 9-15 year-1900
$2d-$2e - file modification date (same format as above)
$2f-$30 - unknown bytes (always zeroed)

Every newly created file gets status $c4. After the file is closed,
bits 7 and 2 of this value are zeroed.

Directory data clusters
-----------------------
Each cluster of the directory always contains a integer number of
directory entries, maximum 5.
If the directory has more entries, the 6th entry is stored to a next
cluster of the directory etc.

Bytes:
$f5-$f7 - unused and the last 8 bytes ($f8-$ff) contain information
                about the directory:
$f8-$f9 - number of the next cluster of the directory ($0000 - last one)
$fa-$fb - global file number ($0000 - main directory)
$fc-$fd - volume random number (same as in VTOC)
$fe     - directory chain cluster number (starting from $00)
$ff     - cluster type ($ff = directory)

Files:
-----
The file map
The file map consists of clusters indicated by the bytes $13-$2a of the
            directory entry. The first 250 bytes of the map's cluster contain up
            to 125 numbers of data clusters allocated for the file.
            The last six bytes contains additional information:
$fa-$fb - global file number
$fc-$fd - volume random number (same as in VTOC)
$fe     - map's cluster number in the current file (starting from $00)
$ff     - cluster type ($80 - file map)

The directory entry provides 24 bytes for the list of the map clusters.
Because the cluster number is 16-bit, the file map may extend to max.12 clusters.
12 clusters * 125 data entries * 250 bytes (see below) results in the
maximum file extent of 1500 clusters, or 375000 bytes (366.2 KB).
If there isn't any other method of linking longer files,
this is the ultimate file length limit in this file system.

Data clusters
Each data cluster contains up to 250 bytes of data.
The last six bytes contain additional information:
$fa-$fb - global file number
$fc-$fd - volume random number (same as in VTOC)
$fe-$ff - the number of the data cluster in the current file
(starting from $0000)
The maximum "number of data cluster" is 32767.
The higher byte is always a positive value and thus forms the cluster type mark
(<= $7f = data cluster).

     Sector Label
Byte    Description
   1-2     File ID Number
   3-4     Volume Number
   5-6     If Byte #6=255($FF), it is a Directory Sector and Byte #5
              is a Sequence Number* within the Directory.
           If Byte #6 is between 128($80) and 254($FE) then Byte #5
              is the Sequence Number* of a File Map Sector.
           If Byte #6 is 127($7F) or less, Bytes #5 and #6 form a
              Standard 6502 WORD-Sized Sequence Number*.

        * The Sequence Number indicates the Relative Position of
              that Sector within it's Series (That is, 3rd Directory,
              Sector, 2nd File Map Sector, 75th Data Sector and So On.).

-------------------------------------------------------------------------

Edited September 6, 2023 by AtariGeezer