Start of +3DOS documentation

peter-mount · Nov 24, 2021 · 253d8cc · 253d8cc
1 parent 8b411f1
commit 253d8cc
Show file tree

Hide file tree

Showing 23 changed files with 1,305 additions and 12 deletions.
diff --git a/content/sinclair/asm/machinetype/_index.html b/content/sinclair/asm/machinetype/_index.html
@@ -20,18 +20,16 @@
 <p>
   There were six official models of Spectrum released:
 </p>
-<ul>
-  <ol>
-    <li>48K with a single rom (16K had the same ROM)</li>
-    <li>128K with 2 roms</li>
-    <li>Spanish 128K released 1985</li>
-    <li>+2 with a built-in Cassette Deck</li>
-    <li>
-      +2A and +3 - These have the same roms just differ with the +3 having a built-in 3" floppy drive
-      instead of the cassette deck.
-    </li>
-  </ol>
-</ul>
+<ol>
+  <li>48K with a single rom (16K had the same ROM)</li>
+  <li>128K with 2 roms</li>
+  <li>Spanish 128K released 1985</li>
+  <li>+2 with a built-in Cassette Deck</li>
+  <li>
+    +2A and +3 - These have the same roms just differ with the +3 having a built-in 3" floppy drive
+    instead of the cassette deck.
+  </li>
+</ol>
 
 <p>
   Below is a routine which will return a value representing the machine type the code is running on in the Accumulator.

diff --git a/content/sinclair/spectrum/3dos/_index.html b/content/sinclair/spectrum/3dos/_index.html
@@ -0,0 +1,53 @@
+---
+type: "manual"
+title: "+3 DOS"
+linkTitle: "+3DOS"
+description: "Notes on the Disk Operating System for the Plus 3"
+weight: 70
+categories:
+  - spectrum
+#no_list: true
+---
+<p>
+  +3DOS is the Disk Operating System of the Spectrum +3.
+  It is contained in ROM 2 on those machines and provides support for:
+</p>
+<ul>
+  <li>Support for one or two floppy disk drives and a RAMdisk.</li>
+  <li>CP/M Plus and CP/M 2.2 file compatibility.</li>
+  <li>AMSTRAD CPC range and PCW range file and media compatibility.</li>
+  <li>Up to 16 files open at the same time.</li>
+  <li>Reading and writing files to or from any page in memory.</li>
+  <li>Byte level random access.</li>
+  <li>Deleting disk files; renaming disk files; changing disk files' attributes.</li>
+  <li>Selecting the default drive and user.</li>
+  <li>Booting a game or operating system.</li>
+  <li>Low level access to floppy disk driver.</li>
+  <li>Optional mapping of two logical drives (A: or B:) onto one physical drive (unit 0).</li>
+</ul>
+
+<h3>Spectrum +2A</h3>
+<p>
+  The +2A (not the +2) has the exact same ROM's as the +3, it just has a Cassette tape instead of a 3" floppy drive.
+  As such, +3DOS is available but only provides:
+</p>
+<ul>
+  <li>Only drive M: is available (the RAMdisk)</li>
+  <li>The default drive for filenames is initialised to M: rather than A:</li>
+  <li>Any attempt to use drives A: or B: will fail with error '22 - Drive not found'</li>
+  <li>
+    As the sector cache is not required for use with the RAM disk,
+    it is increased to 64K (the whole of pages 1, 3, 4, 6).
+    This will give 62K of data and 2K of directory (64 entries).
+  </li>
+  <li>
+    The presence of the floppy disk interface can be determined by calling DD_INTERFACE.
+    If the interface were not present, then none of the other low level floppy disk routines (DD... etc.)
+    could be called; the effect of doing so is undefined.
+  </li>
+</ul>
+<p>
+  Another method to determine if a machine is a +3 or a +2A is to inspect bit 4 of FLAGS3 (0x5B66).
+  If the bit is set then a disk interface is present, hence a +3.
+  If the bit is reset then no disk is present, hence a +2A or a +3 with no disk interface or the interface disabled.
+</p>
diff --git a/content/sinclair/spectrum/3dos/apiadditional/_index.html b/content/sinclair/spectrum/3dos/apiadditional/_index.html
@@ -0,0 +1,10 @@
+---
+type: "manual"
+title: "Additional API"
+linkTitle: "Additional API"
+description: "+3DOS Additional API"
+weight: 11
+categories:
+  - spectrum
+#no_list: true
+---
diff --git a/content/sinclair/spectrum/3dos/apiessential/_index.html b/content/sinclair/spectrum/3dos/apiessential/_index.html
@@ -0,0 +1,10 @@
+---
+type: "manual"
+title: "Essential API"
+linkTitle: "Essential API"
+description: "+3DOS Essential API"
+weight: 10
+categories:
+  - spectrum
+#no_list: true
+---
diff --git a/content/sinclair/spectrum/3dos/apiessential/dos_abandon/_index.html b/content/sinclair/spectrum/3dos/apiessential/dos_abandon/_index.html
@@ -0,0 +1,50 @@
+---
+type: "manual"
+title: "DOS_ABANDON"
+linkTitle: "Abandon"
+description: "Abandon a file"
+weight: 0x010C
+categories:
+  - spectrum
+  - spectrumAPI
+no_list: true
+api:
+  - name: "DOS_ABANDON"
+    addr: "010C"
+    title: "Abandon a file"
+---
+<h3>Synopsys</h3>
+<p>
+  Abandon a file
+</p>
+<p>
+  Similar to DOS CLOSE, except that any header, or data, or directory data yet to be written to disk is discarded.
+  This routine should only be used to force a file closed in the event that DOS CLOSE is unable to close the file
+  (for example, if the media is damaged or permanently changed or removed).
+</p>
+<h3>Entry Parameters</h3>
+<table class="memoryMap">
+  <thead>
+  <tr>
+    <th>Register</th>
+    <th>Content</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+  <td>B</td>
+  <td class="text-left">File number 0&hellip;15</td>
+  </tr>
+  </tbody>
+</table>
+<h3>Exit Parameters</h3>
+<dl>
+  <dt>If OK:</dt>
+  <dd>Carry true</dd>
+  <dd>A corrupt</dd>
+  <dt>Otherwise:</dt>
+  <dd>Carry false</dd>
+  <dd>A=Error code</dd>
+  <dt>Always:</dt>
+  <dd>BC DE HL IX corrupt, all other registers preserved.</dd>
+</dl>
diff --git a/content/sinclair/spectrum/3dos/apiessential/dos_boot/_index.html b/content/sinclair/spectrum/3dos/apiessential/dos_boot/_index.html
@@ -0,0 +1,71 @@
+---
+type: "manual"
+title: "DOS_BOOT"
+linkTitle: "Boot"
+description: "Boot from disk"
+weight: 0x012A
+categories:
+  - spectrum
+  - spectrumAPI
+no_list: true
+api:
+  - name: "DOS_BOOT"
+    addr: "012A"
+    title: "Boot from disk"
+---
+<h3>Synopsys</h3>
+<p>
+  Boot from Disk
+</p>
+<p>
+  This routine loads a single bootstrap sector from the disk in drive A: into memory and enters it.
+  This is for loading games or other operating systems.
+</p>
+<h3>Entry Parameters</h3>
+<p>None</p>
+<h3>Exit Parameters</h3>
+<dl>
+  <dt>If OK:</dt>
+  <dd>No exit as the bootstrap has taken over</dd>
+  <dt>Otherwise:</dt>
+  <dd>Carry false</dd>
+  <dd>A=Error code</dd>
+  <dt>Always:</dt>
+  <dd>BC DE HL IX corrupt, all other registers preserved.</dd>
+</dl>
+<h3>Bootstrap environment</h3>
+<div class="row">
+  <div class="col-6">
+    <p>
+      When the bootstrap runs with the following memory configuration:
+    </p>
+    <p>
+      The bootstrap sector is on side 0, track 0, sector 1 of the disk.
+      It is loaded into memory at 0xFE00 and entered at 0xFE10.
+      Interrupts are disabled, and SP = 0xFE00.
+    </p>
+    <p>
+      The sum of all bytes in the sector must equal 3 MOD 256.
+      Byte 15 in the sector can be used to adjust the sum to achive this.
+      Bytes 0&hellip;15 of the sector hold the disk specification.
+    </p>
+    <p>
+    </p>
+  </div>
+  <div class="col-6">
+    <table class="hexGrid">
+      <thead>
+      <tr>
+        <th colspan="2">Memory Range</th>
+        <th>RAM Bank</th>
+      </tr>
+      </thead>
+      <tbody>
+      <tr><td>0x0000</td><td>0x3FFF</td><td>Bank 4</td></tr>
+      <tr><td>0x4000</td><td>0x7FFF</td><td>Bank 7</td></tr>
+      <tr><td>0x8000</td><td>0xBFFF</td><td>Bank 6</td></tr>
+      <tr><td>0xC000</td><td>0xFFFF</td><td>Bank 3</td></tr>
+      </tbody>
+    </table>
+  </div>
+</div>
diff --git a/content/sinclair/spectrum/3dos/apiessential/dos_catalog/_index.html b/content/sinclair/spectrum/3dos/apiessential/dos_catalog/_index.html
@@ -0,0 +1,120 @@
+---
+type: "manual"
+title: "DOS_CATALOG"
+linkTitle: "Catalog"
+description: "Get the disk catalog"
+weight: 0x011E
+categories:
+  - spectrum
+  - spectrumAPI
+no_list: true
+api:
+  - name: "DOS_CATALOG"
+    addr: "011E"
+    title: "Get the disk catalog"
+---
+<h3>Synopsys</h3>
+<p>
+  Fills a buffer with part of the directory (sorted).
+</p>
+<p>
+  The filename specifies the drive, user and a (possibly ambiguous) filename.
+</p>
+<p>
+  Since the size of a directory is variable (and may be quite large), this routine permits the directory to be
+  catalogued in a number of small sections.
+  The caller passes a buffer pre-loaded with the first required filename, or zeroes for the start of the directory.
+  The buffer is loaded with part (or all, if it fits) of the directory sorted in ASCII order.
+  If more of the directory is required, this routine is re-called with the buffer re-initialised with the last file
+  previously returned.
+  This procedure is followed repeatedly until all of the directory has been catalogued.
+</p>
+<p>
+  Note that +3DOS format disks (which are the same as single-sided, single track AMSTRAD PCW range format disks) may
+  have a maximum of 64 directory entries.
+</p>
+<h3>Entry Parameters</h3>
+<table class="memoryMap">
+  <thead>
+  <tr>
+    <th>Register</th>
+    <th>Content</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+    <td>B</td>
+    <td class="text-left">n+1 size of buffer in entries, must be &gt;= 2</td>
+  </tr>
+  <tr>
+    <td>C</td>
+    <td class="text-left">
+      Filter:<br/>
+      Bit 0 = include system files if set<br>
+      Bits 1&hellip;7 reserved
+    </td>
+  </tr>
+  <tr>
+    <td>DE</td>
+    <td class="text-left">Address of buffer, first entry initialised</td>
+  </tr>
+  <tr>
+    <td>HL</td>
+    <td class="text-left">Address of filename, wildcards permitted</td>
+  </tr>
+  </tbody>
+</table>
+<h3>Exit Parameters</h3>
+<dl>
+  <dt>If OK:</dt>
+  <dd>Carry true</dd>
+  <dd>A corrupt</dd>
+  <dd>
+    B number of completed entries in buffer, 0&hellip;n.<br/>
+    If B=n then there may be more entries for subsequent calls
+  </dd>
+  <dt>Otherwise:</dt>
+  <dd>Carry false</dd>
+  <dd>A=Error code</dd>
+  <dd>B corrupt</dd>
+  <dt>Always:</dt>
+  <dd>C DE HL IX corrupt, all other registers preserved.</dd>
+</dl>
+
+<h3>Buffer format</h3>
+<p>
+  The buffer passed to this routine consists of 2 or more entries, with the first one initialised
+  with the first filename required.
+  It is valid for the first entry to be all zero's.
+</p>
+<p>
+  If the buffer is too small for the directory then it can be called again with entry 0 being a
+  copy of entry n from the previous call.
+</p>
+<table class="hexGrid">
+  <caption>Directory Entry Format</caption>
+  <thead>
+  <tr>
+    <th colspan="2">Bytes</th>
+    <th>Length</th>
+    <th>Content</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+    <td>0</td><td>7</td><td>8</td>
+    <td class="text-left">Filename in ASCII, left justified, space padding</td>
+  </tr>
+  <tr>
+    <td>8</td><td>10</td><td>3</td>
+    <td class="text-left">Type in ASCII, left justified, space padding</td>
+  </tr>
+  <tr>
+    <td>11</td><td>12</td><td>2</td>
+    <td class="text-left">File size in KB</td>
+  </tr>
+  </tbody>
+</table>
+<p>
+  The file size is the disk space allocated, not the actual file size.
+</p>
diff --git a/content/sinclair/spectrum/3dos/apiessential/dos_close/_index.html b/content/sinclair/spectrum/3dos/apiessential/dos_close/_index.html
@@ -0,0 +1,45 @@
+---
+type: "manual"
+title: "DOS_CLOSE"
+linkTitle: "Close"
+description: "Close a file"
+weight: 0x0109
+categories:
+  - spectrum
+  - spectrumAPI
+no_list: true
+api:
+  - name: "DOS_CLOSE"
+    addr: "0109"
+    title: "Close a file"
+---
+<h3>Synopsys</h3>
+<p>
+  Close a file
+</p>
+<h3>Entry Parameters</h3>
+<table class="memoryMap">
+  <thead>
+  <tr>
+    <th>Register</th>
+    <th>Content</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+  <td>B</td>
+  <td class="text-left">File number 0&hellip;15</td>
+  </tr>
+  </tbody>
+</table>
+<h3>Exit Parameters</h3>
+<dl>
+  <dt>If OK:</dt>
+  <dd>Carry true</dd>
+  <dd>A corrupt</dd>
+  <dt>Otherwise:</dt>
+  <dd>Carry false</dd>
+  <dd>A=Error code</dd>
+  <dt>Always:</dt>
+  <dd>BC DE HL IX corrupt, all other registers preserved.</dd>
+</dl>