Adding Support for a Hard Sectored Disk Format

As of Applesauce 1.66, it is possible for users to be able to add their own format definitions to be used by Applesauce. When you add a format, it will automatically be recognized everywhere in the client software such as the Disk Analyzer and Fast Imager. In order to add new formats, there is an Applesauce directory in your Documents folder. Within this folder there is a Formats one that contains the file hardsector_config.json. The hard sector configuration files are text files in JSON format. The root object of the JSON should be an array. A single file can have as may format descriptions as desired. Whenever you edit the hardsector_config.json, you will need to restart the Applesauce client in order to have it load the changes.

Creating a format definition is a highly technical process and if you are not very familiar with how disks are structured, this will likely seem a daunting task. The hard sector configuration files are text files in JSON format. The root object of the JSON should be an array. A single file can have as may format descriptions as desired.

There is an example of a configuration file with 2 definitions in it at the end of this document.

String - Required
This is a descriptive name of the format. It must be unique, but otherwise is only used for informational purposes.

ex: “name”: “North Star SD”

String - Required
This name is used by the Fast Imager to remember user preferences related to this format.

ex: “settings”: “525NorthStar_Hard10x256”

String - Required
This is used by the Fast Imager when displaying the name of this format.

ex: “fastname”: “North Star”

[String] - Required
An array of disk image format names that can be used to save images of this format. It uses the internal names of formats.

ex: “export”: [“northstar_nsi”]

[Boolean] - Required
Set to true if you would like this named format definition to be considered when analyzing disks. If no value is provided, then it defaults to false.

ex: “enabled”: true

String - Required
The physical type of media used.

ex: “media”: “5.25”

String - Required
Encoding and bitrate used.

ex: “encoding”: “fm_250”

String
Bytes stored on disk are most commonly stored in “most significant bit” order, although some platforms store bytes in “least significant bit” order. This value allows you to specify which order should be used. If no value is provided, then it defaults to msb.

ex: “bitOrder”: “lsb”

String
Expected number of tracks per disk side (cylinders).

If this value is not provided, then the following values will be used based on the media type:

ex: “trackCount”: 35

Int
Logical track number of the first track on the disk (typically 0 or 1). If no value is provided, then it defaults to 0.

ex: “trackBase”: 0

Int
Number of drive heads. If no value is provided, then it defaults to 2.

ex: “headCount”: 1

Int - Required
Number of hard sectors of the media. This is used to help identify the format as well as for determining disk geometry.

ex: “sectorsPerTrack”: 10

Int
Logical sector number of the first sector on each track (typically 0 or 1). If no value is provided, then it defaults to 0.

ex: “sectorBase”: 0

String
This is the method of organization for double sided disks. If no value is provided, then it defaults to norm.

ex: “sideOrganization”: “norm”

String - Required
This describes which structures/fields are used for recording sectors.

ex: “sectorFields”: “blob”

[String] - Required
All disk formats have sync pattern(s) that inform the disk controller about how to synchronize itself to the proper start of bytes. Applesauce uses a sequence of 48 bits (6 bytes) that are represented by their hex values. Please note that the values used here are the values physically on the media for FM or MFM encoding, so every logical byte (8 bits) is represented by 16 bits. The last value of the sync pattern is also typically used as a start marker for the disk controller. If there are multiple possible sync sequences, then include them all.

ex: “syncPatterns”: [“AAAAAAAAFFEF”]

If the disk uses address and data fields (and your sectorFields is set to adda), then the following settings allow you to specify how the address field is structured. If your sectorFields is blob, then you can skip this section.

String - Required
Sync values leading up to the marker. These values are in hex.

ex: “addrSync”: “0000”

String - Required
Address field marker value in hex.

ex: “addrMarker”: “FB”

String - Optional
Address field marker bit mask to apply - value in hex.

ex: “addrMarkerBitMask”: “0F”

Int - Required
Byte size of the address field following the marker.

ex: “addrFieldSize”: 6

String - Required
Type of checksum to be used to validate the address field.

ex: “addrCksumType”: “8xrl”

Int - Required
Byte index of the start of the stored checksum relative to the address marker (0 = address marker).

ex: “addrCksumIndex”: 5

Int - Required
Number of bytes for the stored checksum.

ex: “addrCksumByteSize”: 1

String
Byte order of the stored checksum. If no value is provided, then it defaults to “be”.

ex: “addrCksumEndian”: “le”

Int - Required
Byte index of the first byte of the address field that needs to be checksummed, relative to the address marker (0 = address marker).

ex: “addrCksumFromIndex”: 1

Int - Required
Byte index of the last byte of the address field that needs to be checksummed, relative to the address marker (0 = address marker).

ex: “addrCksumToIndex”: 4

Int
A 32-bit value that is used as the initial value of the checksum. If no value is provided, then it defaults to 0.

ex: “addrCksumInit”: 0

Int
A 32-bit value that is xor'ed with checksum post calculation. If no value is provided, then it defaults to 0 which means not to perform an xor.

ex: “addrCksumXorOut”: 0

Int
A 32-bit value that is the polynomial to be used for CRC checksums. If no value is provided, then it defaults to 4129 (0x1021) for crc16 checksums.

ex: “addrCksumPoly”: 4129

Boolean
If true, then the data bytes will be reflected (bit-endian reversed (eg: 0x80 becomes 0x01)) on input to the checksum algorithm. If no value is provided, then it defaults to false.

ex: “addrCksumRefIn”: true

Boolean
If true, then the result of the checksum algorithm will have its data reflected (bit-endian reversed) on output. If no value is provided, then it defaults to false.

ex: “addrCksumRefOut”: true

String
Some formats use bytes that follow the address field as part of the data integrity check. If an epilog is included, then it will be verified in order to consider a sector as being valid. Epilog values are in hex.

ex: “addrEpilog”: “DEAAEB”

Int - Required if including an addrEpilog
Byte index of the start of the epilog relative to the address marker (0 = address marker).

ex: “addrEpilogIndex”: 258

If the format uses an address field, then the bit indexes referenced below are relative to the address marker. Otherwise they are relative to the data marker.

String
Method that is to be used to determine the volume number for a sector. If no value is provided, then it defaults to none.

ex: “volumeDerived”: “data”

Int - Required if volumeDerived is “data”
The bit index of the start of the volume number. This index is relative to the field marker with 0 being the first bit of the marker.

ex: “volumeBitIndex”: 8

Int - Only used if volumeDerived is “data”
The number of bits that comprise the volume number. If no value is provided, then it defaults to 8.

ex: “volumeBitSize”: 8

String - Required
Method that is to be used to determine the track number for a sector.

ex: “trackDerived”: “phys”

Int - Required if trackDerived is “data”
The bit index of the start of the track number. This index is relative to the field marker with 0 being the first bit of the marker.

ex: “trackBitIndex”: 8

Int - Only used if trackDerived is “data”
The number of bits that comprise the track number. If no value is provided, then it defaults to 8.

ex: “trackBitSize”: 8

Boolean - Only used if trackDerived is “data”
Set to true if you would like to validate that the track number matches the physical track number. If no value is provided, then it defaults to false.

ex: “trackVerify”: true

String
Method that is to be used to determine the head number for a sector. If no value is provided, then it defaults to none.

ex: “headDerived”: “data”

Int - Required if headDerived is “data”
The bit index of the start of the head number. This index is relative to the field marker with 0 being the first bit of the marker.

ex: “headBitIndex”: 16

Int - Only used if headDerived is “data”
The number of bits that comprise the head number. If no value is provided, then it defaults to 8.

ex: “headBitSize”: 8

String - Required
Method that is to be used to determine the sector number for a sector.

ex: “sectorDerived”: “data”

Int - Required if sectorDerived is “data”
The bit index of the start of the sector number. This index is relative to the field marker with 0 being the first bit of the marker.

ex: “sectorBitIndex”: 24

Int - Only used if sectorDerived is “data”
The number of bits that comprise the sector number. If no value is provided, then it defaults to 8.

ex: “sectorBitSize”: 8

Boolean - Only used if sectorDerived is “data”
Set to true if you would like to validate that the sector number matches the physical sector number. If no value is provided, then it defaults to false.

ex: “sectorVerify”: true

String - Required
Sync values leading up to the marker. These values are in hex.

ex: “dataSync”: “0000”

String - Required
Data field marker value in hex.

ex: “dataMarker”: “FB”

String - Optional
Data field marker bit mask to apply - value in hex. The length of the bit mask should equal the length of the marker. This value is used to “mask off” particular bits to exclude them from consideration when locating a marker. A binary value of 1 in any position will retain that bit for comparison. A binary value of 0 in any position will exclude that bit from comparison.

ex: “dataMarkerBitMask”: “0F”

Int - Required
Byte index of the start of the data relative to the data marker (0 = data marker byte).

ex: “dataStartIndex”: 1

Int - Required
Number of bytes of data.

ex: “dataSize”: 256

String - Required
Type of checksum to be used to validate the data.

ex: “dataCksumType”: “8xrl”

Int - Required
Byte index of the start of the stored checksum relative to the data marker (0 = data marker).

ex: “dataCksumIndex”: 257

Int - Required
Number of bytes for the stored checksum.

ex: “dataCksumByteSize”: 1

String
Byte order of the stored checksum. If no value is provided, then it defaults to “be”.

ex: “dataCksumEndian”: “le”

Int - Required
Byte index of the first byte of data that needs to be checksummed, relative to the data marker (0 = data marker).

ex: “dataCksumFromIndex”: 1

Int - Required
Byte index of the last byte of disk data that needs to be checksummed, relative to the data marker (0 = data marker).

ex: “dataCksumToIndex”: 256

Int
A 32-bit value that is used as the initial value of the checksum. If no value is provided, then it defaults to 0.

ex: “dataCksumInit”: 0

Int
A 32-bit value that is xor'ed with checksum post calculation. If no value is provided, then it defaults to 0 which means not to perform an xor.

ex: “dataCksumXorOut”: 0

Int
A 32-bit value that is the polynomial to be used for CRC checksums. If no value is provided, then it defaults to 4129 (0x1021) for crc16 checksums.

ex: “dataCksumPoly”: 4129

Boolean
If true, then the data bytes will be reflected (bit-endian reversed (eg: 0x80 becomes 0x01)) on input to the checksum algorithm. If no value is provided, then it defaults to false.

ex: “dataCksumRefIn”: true

Boolean
If true, then the result of the checksum algorithm will have its data reflected (bit-endian reversed) on output. If no value is provided, then it defaults to false.

ex: “dataCksumRefOut”: true

String
Some formats use bytes that follow the sector data as part of the data integrity check. If an epilog is included, then it will be verified in order to consider a sector as being valid. Data epilog values are in hex.

ex: “dataEpilog”: “DEAAEB”

Int - Required if including a dataEpilog
Byte index of the start of the epilog relative to the data marker (0 = data marker).

ex: “dataEpilogIndex”: 258

[String]
Used if the sector data requires any kind of special processing. Multiple values can be used.

ex: “dataProcess”: [“negate”]

[
	{
		"name": "North Star",
		"enabled": true,
		"settings": "525NorthStar_Hard10x512",
		"export": ["northstar_nsi"],
		"media": "5.25",
		"encoding": "mfm_250",
		"trackCount": 35,
		"trackBase": 0,
		"headCount": 2,
		"sectorsPerTrack": 10,
		"sectorBase": 0,
		"syncPatterns": ["AAAAAAAA5545"],
		"sectorFields": "blob",
		"trackDerived": "phys",
		"headDerived": "phys",
		"sectorDerived": "phys",
		"dataSync": "0000",
		"dataMarker": "FB",
		"dataStartIndex": 2,
		"dataSize": 512,
		"dataCksumType": "8xrl",
		"dataCksumIndex": 514,
		"dataCksumByteSize": 1,
		"dataCksumFromIndex": 2,
		"dataCksumToIndex": 513
	},
	{
		"name": "Heath/Zenith H-17",
		"enabled": true,
		"settings": "525HeathH17_Hard10x256",
		"export": ["heath_h8d"],
		"media": "5.25",
		"encoding": "fm_250",
		"trackCount": 40,
		"trackBase": 0,
		"headCount": 2,
		"sectorsPerTrack": 10,
		"sectorBase": 0,
		"sideOrganization": "trks",
		"syncPatterns": ["AAAAAAAAEFFF"],
		"bitOrder": "lsb",
		"sectorFields": "adda",
		"addrSync": "0000",
		"addrMarker": "FD",
		"addrFieldSize": 3,
		"addrCksumType": "8xrl",
		"addrCksumIndex": 4,
		"addrCksumByteSize": 1,
		"addrCksumFromIndex": 1,
		"addrCksumToIndex": 3,
		"volumeDerived": "data",
		"volumeBitIndex": 8,
		"trackDerived": "data",
		"trackBitIndex": 16,
		"trackVerify": true,
		"headDerived": "phys",
		"sectorDerived": "data",
		"sectorBitIndex": 24,
		"dataSync": "0000",
		"dataMarker": "FD",
		"dataStartIndex": 1,
		"dataSize": 256,
		"dataCksumType": "8xrl",
		"dataCksumIndex": 257,
		"dataCksumByteSize": 1,
		"dataCksumFromIndex": 1,
		"dataCksumToIndex": 256
	}
]