diskii/lib/dos3/dos3.go
2017-03-17 22:26:15 -04:00

695 lines
21 KiB
Go

// Copyright © 2016 Zellyn Hunter <zellyn@gmail.com>
// Package dos3 contains routines for working with the on-disk
// structures of Apple DOS 3.
package dos3
import (
"encoding/binary"
"fmt"
"io"
"strings"
"github.com/zellyn/diskii/lib/disk"
)
const (
// VTOCTrack is the track on a DOS3.3 that holds the VTOC.
VTOCTrack = 17
// VTOCSector is the sector on a DOS3.3 that holds the VTOC.
VTOCSector = 0
)
// DiskSector represents a track and sector.
type DiskSector struct {
Track byte
Sector byte
}
// GetTrack returns the track that a DiskSector was loaded from.
func (ds DiskSector) GetTrack() byte {
return ds.Track
}
// SetTrack sets the track that a DiskSector was loaded from.
func (ds DiskSector) SetTrack(track byte) {
ds.Track = track
}
// GetSector returns the sector that a DiskSector was loaded from.
func (ds DiskSector) GetSector() byte {
return ds.Sector
}
// SetSector sets the sector that a DiskSector was loaded from.
func (ds DiskSector) SetSector(sector byte) {
ds.Sector = sector
}
// TrackFreeSectors maps the free sectors in a single track.
type TrackFreeSectors [4]byte // Bit map of free sectors in a track
// IsFree returns true if the given sector on a track is free (or if
// sector > 15).
func (t TrackFreeSectors) IsFree(sector byte) bool {
if sector >= 16 {
return false
}
bits := byte(1) << (sector % 8)
if sector < 8 {
return t[1]&bits > 0
}
return t[0]&bits > 0
}
// UnusedClear returns true if the unused bytes of the free sector map
// for a track are zeroes (as they're supposed to be).
func (t TrackFreeSectors) UnusedClear() bool {
return t[2] == 0 && t[3] == 0
}
// DiskFreeSectors maps the free sectors on a disk.
type DiskFreeSectors [50]TrackFreeSectors
// VTOC is the struct used to hold the DOS 3.3 VTOC structure.
// See page 4-2 of Beneath Apple DOS.
type VTOC struct {
DiskSector
Unused1 byte // Not used
CatalogTrack byte // Track number of first catalog sector
CatalogSector byte // Sector number of first catalog sector
DOSRelease byte // Release number of DOS used to INIT this diskette
Unused2 [2]byte // Not used
Volume byte // Diskette volume number (1-254)
Unused3 [32]byte // Not used
// Maximum number of track/secotr pairs which will fit in one file
// track/sector list sector (122 for 256 byte sectors)
TrackSectorListMaxSize byte
Unused4 [8]byte // Not used
LastTrack byte // Last track where sectors were allocated
TrackDirection int8 // Direction of track allocation (+1 or -1)
Unused5 [2]byte
NumTracks byte // Number of tracks per diskette (normally 35)
NumSectors byte // Number of sectors per track (13 or 16)
BytesPerSector uint16 // Number of bytes per sector (LO/HI format)
FreeSectors DiskFreeSectors
}
// Validate checks a VTOC sector to make sure it looks normal.
func (v *VTOC) Validate() error {
if v.Volume == 255 {
return fmt.Errorf("expected volume to be 0-254, but got 255")
}
if v.DOSRelease != 3 {
return fmt.Errorf("expected DOS release number to be 3; got %d", v.DOSRelease)
}
if v.TrackDirection != 1 && v.TrackDirection != -1 {
return fmt.Errorf("expected track direction to be 1 or -1; got %d", v.TrackDirection)
}
if v.NumTracks != 35 {
return fmt.Errorf("expected number of tracks to be 35; got %d", v.NumTracks)
}
if v.NumSectors != 13 && v.NumSectors != 16 {
return fmt.Errorf("expected number of sectors per track to be 13 or 16; got %d", v.NumSectors)
}
if v.BytesPerSector != 256 {
return fmt.Errorf("expected 256 bytes per sector; got %d", v.BytesPerSector)
}
if v.TrackSectorListMaxSize != 122 {
return fmt.Errorf("expected 122 track/sector pairs per track/sector list sector; got %d", v.TrackSectorListMaxSize)
}
for i, tf := range v.FreeSectors {
if !tf.UnusedClear() {
return fmt.Errorf("unused bytes of free-sector list for track %d are not zeroes", i)
}
}
return nil
}
// ToSector marshals the VTOC sector to bytes.
func (v VTOC) ToSector() ([]byte, error) {
buf := make([]byte, 256)
buf[0x00] = v.Unused1
buf[0x01] = v.CatalogTrack
buf[0x02] = v.CatalogSector
buf[0x03] = v.DOSRelease
copyBytes(buf[0x04:0x06], v.Unused2[:])
buf[0x06] = v.Volume
copyBytes(buf[0x07:0x27], v.Unused3[:])
buf[0x27] = v.TrackSectorListMaxSize
copyBytes(buf[0x28:0x30], v.Unused4[:])
buf[0x30] = v.LastTrack
buf[0x31] = byte(v.TrackDirection)
copyBytes(buf[0x32:0x34], v.Unused5[:])
buf[0x34] = v.NumTracks
buf[0x35] = v.NumSectors
binary.LittleEndian.PutUint16(buf[0x36:0x38], v.BytesPerSector)
for i, m := range v.FreeSectors {
copyBytes(buf[0x38+4*i:0x38+4*i+4], m[:])
}
return buf, nil
}
// copyBytes is just like the builtin copy, but just for byte slices,
// and it checks that dst and src have the same length.
func copyBytes(dst, src []byte) int {
if len(dst) != len(src) {
panic(fmt.Sprintf("copyBytes called with differing lengths %d and %d", len(dst), len(src)))
}
return copy(dst, src)
}
// FromSector unmarshals the VTOC sector from bytes. Input is
// expected to be exactly 256 bytes.
func (v *VTOC) FromSector(data []byte) error {
if len(data) != 256 {
return fmt.Errorf("VTOC.FromSector expects exactly 256 bytes; got %d", len(data))
}
v.Unused1 = data[0x00]
v.CatalogTrack = data[0x01]
v.CatalogSector = data[0x02]
v.DOSRelease = data[0x03]
copyBytes(v.Unused2[:], data[0x04:0x06])
v.Volume = data[0x06]
copyBytes(v.Unused3[:], data[0x07:0x27])
v.TrackSectorListMaxSize = data[0x27]
copyBytes(v.Unused4[:], data[0x28:0x30])
v.LastTrack = data[0x30]
v.TrackDirection = int8(data[0x31])
copyBytes(v.Unused5[:], data[0x32:0x34])
v.NumTracks = data[0x34]
v.NumSectors = data[0x35]
v.BytesPerSector = binary.LittleEndian.Uint16(data[0x36:0x38])
for i := range v.FreeSectors {
copyBytes(v.FreeSectors[i][:], data[0x38+4*i:0x38+4*i+4])
}
return nil
}
// DefaultVTOC returns a new, empty VTOC with values set to their
// defaults.
func DefaultVTOC() VTOC {
v := VTOC{
CatalogTrack: 0x11,
CatalogSector: 0x0f,
DOSRelease: 0x03,
Volume: 0x01,
TrackSectorListMaxSize: 122,
LastTrack: 0x00, // TODO(zellyn): what should this be?
TrackDirection: 1,
NumTracks: 0x23,
NumSectors: 0x10,
BytesPerSector: 0x100,
}
for i := range v.FreeSectors {
v.FreeSectors[i] = TrackFreeSectors{}
if i < 35 {
v.FreeSectors[i] = TrackFreeSectors([4]byte{0xff, 0xff, 0x00, 0x00})
}
}
return v
}
// CatalogSector is the struct used to hold the DOS 3.3 Catalog
// sector.
type CatalogSector struct {
DiskSector
Unused1 byte // Not used
NextTrack byte // Track number of next catalog sector (usually 11 hex)
NextSector byte // Sector number of next catalog sector
Unused2 [8]byte // Not used
FileDescs [7]FileDesc // File descriptive entries
}
// ToSector marshals the CatalogSector to bytes.
func (cs CatalogSector) ToSector() ([]byte, error) {
buf := make([]byte, 256)
buf[0x00] = cs.Unused1
buf[0x01] = cs.NextTrack
buf[0x02] = cs.NextSector
copyBytes(buf[0x03:0x0b], cs.Unused2[:])
for i, fd := range cs.FileDescs {
fdBytes := fd.ToBytes()
copyBytes(buf[0x0b+35*i:0x0b+35*(i+1)], fdBytes)
}
return buf, nil
}
// FromSector unmarshals the CatalogSector from bytes. Input is
// expected to be exactly 256 bytes.
func (cs *CatalogSector) FromSector(data []byte) error {
if len(data) != 256 {
return fmt.Errorf("CatalogSector.FromSector expects exactly 256 bytes; got %d", len(data))
}
cs.Unused1 = data[0x00]
cs.NextTrack = data[0x01]
cs.NextSector = data[0x02]
copyBytes(cs.Unused2[:], data[0x03:0x0b])
for i := range cs.FileDescs {
cs.FileDescs[i].FromBytes(data[0x0b+35*i : 0x0b+35*(i+1)])
}
return nil
}
// Filetype is the type for dos 3.3 filetype+locked status byte.
type Filetype byte
// The DOS3 filetypes.
const (
// FiletypeLocked is just setting the high bit on other file types.
FiletypeLocked Filetype = 0x80
FiletypeText Filetype = 0x00 // Text file
FiletypeInteger Filetype = 0x01 // INTEGER BASIC file
FiletypeApplesoft Filetype = 0x02 // APPLESOFT BASIC file
FiletypeBinary Filetype = 0x04 // BINARY file
FiletypeS Filetype = 0x08 // S type file
FiletypeRelocatable Filetype = 0x10 // RELOCATABLE object module file
FiletypeA Filetype = 0x20 // A type file
FiletypeB Filetype = 0x40 // B type file
)
// FileDescStatus is the type used to mark file descriptor status.
type FileDescStatus int
// The three actual file descriptor status values.
const (
FileDescStatusNormal FileDescStatus = iota
FileDescStatusDeleted
FileDescStatusUnused
)
// FileDesc is the struct used to represent the DOS 3.3 File
// Descriptive entry.
type FileDesc struct {
// Track of first track/sector list sector. If this is a deleted
// file, this byte contains a hex FF and the original track number
// is copied to the last byte of the file name field (BYTE 20). If
// this byte contains a hex 00, the entry is assumed to never have
// been used and is available for use. (This means track 0 can never
// be used for data even if the DOS image is "wiped" from the
// diskette.)
TrackSectorListTrack byte
TrackSectorListSector byte // Sector of first track/sector list sector
Filetype Filetype // File type and flags
Filename [30]byte // File name (30 characters) Length of file in
// sectors (LO/HI format). The CATALOG command will only format the
// LO byte of this length giving 1-255 but a full 65,535 may be
// stored here.
SectorCount uint16
}
// ToBytes marshals the FileDesc to bytes.
func (fd FileDesc) ToBytes() []byte {
buf := make([]byte, 35)
buf[0x00] = fd.TrackSectorListTrack
buf[0x01] = fd.TrackSectorListSector
buf[0x02] = byte(fd.Filetype)
copyBytes(buf[0x03:0x21], fd.Filename[:])
binary.LittleEndian.PutUint16(buf[0x21:0x23], fd.SectorCount)
return buf
}
// FromBytes unmarshals the FileDesc from bytes. Input is
// expected to be exactly 35 bytes.
func (fd *FileDesc) FromBytes(data []byte) {
if len(data) != 35 {
panic(fmt.Sprintf("FileDesc.FromBytes expects exactly 35 bytes; got %d", len(data)))
}
fd.TrackSectorListTrack = data[0x00]
fd.TrackSectorListSector = data[0x01]
fd.Filetype = Filetype(data[0x02])
copyBytes(fd.Filename[:], data[0x03:0x21])
fd.SectorCount = binary.LittleEndian.Uint16(data[0x21:0x23])
}
// Status returns whether the FileDesc describes a deleted file, a
// normal file, or has never been used.
func (fd *FileDesc) Status() FileDescStatus {
switch fd.TrackSectorListTrack {
case 0:
return FileDescStatusUnused // Never been used.
case 0xff:
return FileDescStatusDeleted
default:
return FileDescStatusNormal
}
}
// FilenameString returns the filename of a FileDesc as a normal
// string.
func (fd *FileDesc) FilenameString() string {
var slice []byte
if fd.Status() == FileDescStatusDeleted {
slice = append(slice, fd.Filename[0:len(fd.Filename)-1]...)
} else {
slice = append(slice, fd.Filename[:]...)
}
for i := range slice {
slice[i] -= 0x80
}
return strings.TrimRight(string(slice), " ")
}
// descriptor returns a disk.Descriptor for a FileDesc, but with the
// length set to -1, since we can't know it without reading the file
// contents.
func (fd FileDesc) descriptor() disk.Descriptor {
desc := disk.Descriptor{
Name: fd.FilenameString(),
Sectors: int(fd.SectorCount),
Length: -1,
Locked: (fd.Filetype & FiletypeLocked) > 0,
}
switch fd.Filetype & 0x7f {
case FiletypeText: // Text file
desc.Type = disk.FiletypeASCIIText
case FiletypeInteger: // INTEGER BASIC file
desc.Type = disk.FiletypeIntegerBASIC
case FiletypeApplesoft: // APPLESOFT BASIC file
desc.Type = disk.FiletypeApplesoftBASIC
case FiletypeBinary: // BINARY file
desc.Type = disk.FiletypeBinary
case FiletypeS: // S type file
desc.Type = disk.FiletypeS
case FiletypeRelocatable: // RELOCATABLE object module file
desc.Type = disk.FiletypeRelocatable
case FiletypeA: // A type file
desc.Type = disk.FiletypeNewA
case FiletypeB: // B type file
desc.Type = disk.FiletypeNewB
}
return desc
}
// Contents returns the on-disk contents of a file represented by a
// FileDesc.
func (fd *FileDesc) Contents(lsd disk.LogicalSectorDisk) ([]byte, error) {
tsls := []TrackSectorList{}
nextTrack := fd.TrackSectorListTrack
nextSector := fd.TrackSectorListSector
seen := map[disk.TrackSector]bool{}
for nextTrack != 0 || nextSector != 0 {
ts := disk.TrackSector{Track: nextTrack, Sector: nextSector}
if seen[ts] {
return nil, fmt.Errorf("File %q tries to read TrackSector track=%d sector=%d twice", fd.FilenameString(), nextTrack, nextSector)
}
seen[ts] = true
tsl := TrackSectorList{}
if err := disk.UnmarshalLogicalSector(lsd, &tsl, nextTrack, nextSector); err != nil {
return nil, err
}
tsls = append(tsls, tsl)
nextTrack = tsl.NextTrack
nextSector = tsl.NextSector
}
data := make([]byte, 0, 256*122*len(tsls))
for i, tsl := range tsls {
end := 121
// If it's the last tsl, stop at the last non-zero TrackSector.
if i == len(tsls)-1 {
for j, ts := range tsl.TrackSectors {
if ts.Track != 0 || ts.Sector != 0 {
end = j
}
}
}
for j := 0; j <= end; j++ {
ts := tsl.TrackSectors[j]
if ts.Track == 0 && ts.Sector == 0 {
for k := 0; k < 256; k++ {
data = append(data, 0)
}
} else {
contents, err := lsd.ReadLogicalSector(ts.Track, ts.Sector)
if err != nil {
return nil, err
}
data = append(data, contents...)
}
}
}
return data, nil
}
// TrackSectorList is the struct used to represent DOS 3.3
// Track/Sector List sectors.
type TrackSectorList struct {
DiskSector
Unused1 byte // Not used
NextTrack byte // Track number of next T/S List sector if one was needed or zero if no more T/S List sectors.
NextSector byte // Sector number of next T/S List sector (if present).
Unused2 [2]byte // Not used
SectorOffset uint16 // Sector offset in file of the first sector described by this list.
Unused3 [5]byte // Not used
TrackSectors [122]disk.TrackSector
}
// ToSector marshals the TrackSectorList to bytes.
func (tsl TrackSectorList) ToSector() ([]byte, error) {
buf := make([]byte, 256)
buf[0x00] = tsl.Unused1
buf[0x01] = tsl.NextTrack
buf[0x02] = tsl.NextSector
copyBytes(buf[0x03:0x05], tsl.Unused2[:])
binary.LittleEndian.PutUint16(buf[0x05:0x07], tsl.SectorOffset)
copyBytes(buf[0x07:0x0C], tsl.Unused3[:])
for i, ts := range tsl.TrackSectors {
buf[0x0C+i*2] = ts.Track
buf[0x0D+i*2] = ts.Sector
}
return buf, nil
}
// FromSector unmarshals the TrackSectorList from bytes. Input is
// expected to be exactly 256 bytes.
func (tsl *TrackSectorList) FromSector(data []byte) error {
if len(data) != 256 {
return fmt.Errorf("TrackSectorList.FromSector expects exactly 256 bytes; got %d", len(data))
}
tsl.Unused1 = data[0x00]
tsl.NextTrack = data[0x01]
tsl.NextSector = data[0x02]
copyBytes(tsl.Unused2[:], data[0x03:0x05])
tsl.SectorOffset = binary.LittleEndian.Uint16(data[0x05:0x07])
copyBytes(tsl.Unused3[:], data[0x07:0x0C])
for i := range tsl.TrackSectors {
tsl.TrackSectors[i].Track = data[0x0C+i*2]
tsl.TrackSectors[i].Sector = data[0x0D+i*2]
}
return nil
}
// readCatalogSectors reads the raw CatalogSector structs from a DOS
// 3.3 disk.
func readCatalogSectors(d disk.LogicalSectorDisk) ([]CatalogSector, error) {
v := &VTOC{}
err := disk.UnmarshalLogicalSector(d, v, VTOCTrack, VTOCSector)
if err != nil {
return nil, err
}
if err := v.Validate(); err != nil {
return nil, fmt.Errorf("Invalid VTOC sector: %v", err)
}
nextTrack := v.CatalogTrack
nextSector := v.CatalogSector
css := []CatalogSector{}
seen := map[disk.TrackSector]bool{}
for nextTrack != 0 || nextSector != 0 {
ts := disk.TrackSector{Track: nextTrack, Sector: nextSector}
if seen[ts] {
return nil, fmt.Errorf("Catalog tries to read TrackSector track=%d sector=%d twice", nextTrack, nextSector)
}
if nextTrack >= v.NumTracks {
return nil, fmt.Errorf("catalog sectors can't be in track %d: disk only has %d tracks", nextTrack, v.NumTracks)
}
if nextSector >= v.NumSectors {
return nil, fmt.Errorf("catalog sectors can't be in sector %d: disk only has %d sectors", nextSector, v.NumSectors)
}
cs := CatalogSector{}
err := disk.UnmarshalLogicalSector(d, &cs, nextTrack, nextSector)
if err != nil {
return nil, err
}
css = append(css, cs)
nextTrack = cs.NextTrack
nextSector = cs.NextSector
}
return css, nil
}
// ReadCatalog reads the catalog of a DOS 3.3 disk.
func ReadCatalog(d disk.LogicalSectorDisk) (files, deleted []FileDesc, err error) {
css, err := readCatalogSectors(d)
if err != nil {
return nil, nil, err
}
for _, cs := range css {
for _, fd := range cs.FileDescs {
switch fd.Status() {
case FileDescStatusUnused:
// skip
case FileDescStatusDeleted:
deleted = append(deleted, fd)
case FileDescStatusNormal:
files = append(files, fd)
}
}
}
return files, deleted, nil
}
// operator is a disk.Operator - an interface for performing
// high-level operations on files and directories.
type operator struct {
lsd disk.LogicalSectorDisk
}
var _ disk.Operator = operator{}
// operatorName is the keyword name for the operator that undestands
// dos3 disks.
const operatorName = "dos3"
// Name returns the name of the operator.
func (o operator) Name() string {
return operatorName
}
// HasSubdirs returns true if the underlying operating system on the
// disk allows subdirectories.
func (o operator) HasSubdirs() bool {
return false
}
// Catalog returns a catalog of disk entries. subdir should be empty
// for operating systems that do not support subdirectories.
func (o operator) Catalog(subdir string) ([]disk.Descriptor, error) {
fds, _, err := ReadCatalog(o.lsd)
if err != nil {
return nil, err
}
descs := make([]disk.Descriptor, 0, len(fds))
for _, fd := range fds {
descs = append(descs, fd.descriptor())
}
return descs, nil
}
// fileForFilename returns the FileDesc corresponding to the given
// filename, or an error.
func (o operator) fileForFilename(filename string) (FileDesc, error) {
fds, _, err := ReadCatalog(o.lsd)
if err != nil {
return FileDesc{}, err
}
for _, fd := range fds {
if fd.FilenameString() == filename {
return fd, nil
}
}
return FileDesc{}, fmt.Errorf("Filename %q not found", filename)
}
// GetFile retrieves a file by name.
func (o operator) GetFile(filename string) (disk.FileInfo, error) {
fd, err := o.fileForFilename(filename)
if err != nil {
return disk.FileInfo{}, err
}
desc := fd.descriptor()
data, err := fd.Contents(o.lsd)
if err != nil {
return disk.FileInfo{}, err
}
fi := disk.FileInfo{
Descriptor: desc,
Data: data,
}
errType := "UNKNOWN"
switch fd.Filetype & 0x7f {
case FiletypeText: // Text file
for data[len(data)-1] == 0 {
data = data[:len(data)-1]
}
fi.Descriptor.Length = len(data)
fi.Data = data
return fi, nil
case FiletypeInteger, FiletypeApplesoft, FiletypeBinary:
switch fd.Filetype & 0x7f {
case FiletypeApplesoft:
fi.StartAddress = 0x801
case FiletypeInteger:
// TODO(zellyn): figure out what address integer basic programs are stored at.
case FiletypeBinary:
fi.StartAddress = uint16(data[0]) + uint16(data[1])<<8
data = data[2:]
}
length := int(data[0]) + int(data[1])*256
data = data[2 : length+2]
fi.Descriptor.Length = length
fi.Data = data
return fi, nil
case FiletypeS: // S type file
errType = "S"
case FiletypeRelocatable: // RELOCATABLE object module file
errType = "REL"
case FiletypeA: // A type file
errType = "A"
case FiletypeB: // B type file
errType = "B"
}
return disk.FileInfo{}, fmt.Errorf("%s does not yet implement `GetFile` for filetype %s", operatorName, errType)
}
// Delete deletes a file by name. It returns true if the file was
// deleted, false if it didn't exist.
func (o operator) Delete(filename string) (bool, error) {
return false, fmt.Errorf("%s does not implement Delete yet", operatorName)
}
// PutFile writes a file by name. If the file exists and overwrite
// is false, it returns with an error. Otherwise it returns true if
// an existing file was overwritten.
func (o operator) PutFile(fileInfo disk.FileInfo, overwrite bool) (existed bool, err error) {
return false, fmt.Errorf("%s does not implement PutFile yet", operatorName)
}
// Write writes the underlying disk to the given writer.
func (o operator) Write(w io.Writer) (int, error) {
return o.lsd.Write(w)
}
// operatorFactory is the factory that returns dos3 operators given
// disk images.
func operatorFactory(sd disk.SectorDisk) (disk.Operator, error) {
lsd, err := disk.NewMappedDisk(sd, disk.Dos33LogicalToPhysicalSectorMap)
if err != nil {
return nil, err
}
_, _, err = ReadCatalog(lsd)
if err != nil {
return nil, fmt.Errorf("Cannot read catalog. Underlying error: %v", err)
}
return operator{lsd: lsd}, nil
}
func init() {
disk.RegisterDiskOperatorFactory(operatorName, operatorFactory)
}