Plus D
======

Hardware
--------
Technical info, well - the WD1772 is the controller chip (FDC) in the Disciple and Plus-D. I don't know if you can 
still find them. I do however have links to the Disciple/+D schematics directory at nvg and Ramsoft's pages with a 
complete technical document and Specification.

Programming the +D Interrupts
-----------------------------
Well, I've not really done it myself. Yet. I plan to in one (kind of large) project that's been simmering away a few 
years. However, luckily, there is a program called "Slowmo" which you can slow down your Spectrum. This uses 
the +D interrupts to wait some time every 50th second NMI interrupt: 
1. It loads the slowdown code which will get executed in the +D RAM to decimal address 12720, with the +D 
paged in. 
2. It then does a POKE @16, 12720 to say where the code is, @16 being actual address 8192+16 in the 
+D. This turns it on. 
3. It is deactivated by poking @16,8335 which looks like it is the default +D interrupt code. 
4. Note: Use a normal RET (I think) at the end of the interrupt routine, not a RETN / RETI. 

Disk structure/format and usage information
===========================================
This information was originally posted to the Speccy newsgroup, comp.sys.sinclair by Simon Cooke 
(simonc@jumper.mcc.ac.uk).

Standard MGT format
-------------------
10 sectors per track, 2 sides, 80 cylinders. 512 bytes per sector. Tracks are used linearly; track 0 on side 0 is 
followed by track 1, on side 0. Track 79 on side 0 is followed by track 0 on side 1.

Directory format
----------------
First 4 tracks (0-3) contain directory info. 2 entries per sector (each entry is 256 bytes long). This allows 80 files per 
disk, or more if proprietary alterations to the format are used.
First 11 bytes:

: (1) Attributes. bits 0-4 File type, or zero if erased
      ^^^^^^^^^^
I usually call this a directory byte - describes entry as shown in directory
listing.  Not to be confused with file byte (see below).  Not that it
matters much.


:                      6   Protected (read only)
:                      7   Hidden    (not shown) [I may have the functions 
: of bits 6 and 7 mixed up).

: (10) File name. If first byte of name is zero, and attributes byte is 
: zero, the directory after this point is unused, and does not/should not 
: be checked for more entries.

Not always... Some versions of G+DOS seem to continue checking, and when,
say you have a file containing all bad sectors at last directory entry
(no.80), it gets printed.

: The rest of the entry contains the bit mapped sector allocation for the 
: file (195 bytes) and file-specific information, including the length of 
: the file in sectors, and the start track and sector for the file. Tracks 
: on side 0 have bit 7 of the track number reset; tracks on side 1 have bit 
: 7 set. This convention is used throughout the system.

More info on this:
------------------
Considering offset 0 is first byte in 256 byte header, Offsets 0-10 as above (file type, name) followed by the 
following. All 2byte words are in low,high byte significance order.(lsb first)
offset 11/12=Number of data sectors in file (not including header)
offset 13=Track number of first data sector
offset 14=Sector number of first data sector
offset 15-210=Sector bitmap(1 bit for each sector, a 1 if used, 0 if not)
offset 211=file byte - same as tape format
		0=basic
		1=numerical array
		2=string array
		3=code
		(All attributes/directory byte types fit into one of these,
		 usually code if nothing else)
offset 212/213=file length in bytes
offset 214/215=file start address (only if code file or basic)
offset 216/217=autorun linenumber/number > 32767 for basic, or 65535 anyway
		for other file types???? Not too sure.
offset 218/219=0 (not sure what it's used for - maybe some BASIC parameter)
... ?????

If a byte(s) is not used, it is either 255/0 (can't remember)
The data area (tracks 4-79, 128-...) contains sectors of data. The sector pointed to by the directory area contains 510 
bytes of data, plus a pointer to the next sector in the last two bytes of the sector (510, 511). If this pointer is null (ie 
both track and sector are zero), then this is the last sector of the file.
The first data sector of a file if it's one of the types used in tape also (eg basic/array/code) has 10 bytes as a 
consistency check, containing:
offset 0=file byte (as above)
offset 1/2=file length
offset 3/4=start address
offset 5/6=autorun/>32767 or 65535 ???? (as above)
offset 7/8=not sure (same as offset 218/219 above)
offset 9 (byte 10 in file)=first byte of data.
That should be everything. All filled in from my own experiments, and should be correct but don't go suing me if it's 
wrong cos I aint 100% sure.
Here's some more info on +D/Disciple techy details:
Directory Byte
 No.	Type		Appears As (in disk CATalogue)	Comment
0	Erased		N/A				Guess!
1	Basic		BASIC				BASIC program
2	Numeric Array	ARRAY				e.g. DATA a()
3	Character Array	$ ARRAY				e.g. DATA a$()
4	Code		CODE				Plain code file
5	48k Snap	SNP 48k				48k Memory Snapshot
6	Microdrive	MDRV				Saved using m/drive commands
7	Screen$		SCREEN$				SCREEN$. You know!
8	Special		SPECIAL				User defined
9	128k Snap	SNP 128k			128k Memory Snapshot
10	Opentype	OPENTYPE			Stream in/output
11	Execute		EXECUTE				BASIC extension
			
The following are only used in Uni-Dos:			
	
12	Subdirectory	DIR				Subdirectories	
13	Create		CREATE				(BASIC extensions)	

If the disk has an extended catalogue (used by Betados), then offset 255 (the last byte of the first header) in the first 
sector of the directory (track 0, sector 1) will contain the number of extra tracks used for the directory. So a 2 
(decimal) would mean the usual 4 tracks(=80 files) + 2 tracks (10sectors*2per sector=20per track * 2=40) = 120 
directory entries in total (if you understood that). Basically no. directory entries allowed is: 80 + 20 * , where n is 
the number in offset 255.
As said before, if bit 7 (value=128) is set then it's a hidden file, and if bit 6 (value=64) then it's protected (read-only) 
and cannot be saved over / erased.
Now for some useful calls. Not all are here, but that's cos I don't know them all. Try looking in "AlchNews" 
(disk/tapezine produced by Alchemist Research) issues around 14 for the info on direct ROM calls. AlchNews 
available at ftp.nvg.unit.no/pub/sinclair/ .../mags/... or at the AlchNews website.
Most disk operations can use the RST 8 : DEFB , although using ROM calls directly with +D/Disciple ROM 
switched in is quicker. Here's a list of the hookcodes.
UFIA is the User File Information Area, an area in the +D RAM used for information about open files, and to open a 
file you should make up a UFIA somewhere in conventional memory and call the relevant routines with IX pointing 
to it. I don't have the UFIA strucuture to hand, but I will type it up sometime.
Hook Codes
 Hook Command
-------------
51	Transfer UFIA (in IX register) to disk file channel area
52	Open file (use info in file channel area to determine which file)
53	Do both 51 and 52 above - open file ready to write data
54	Save character to currently open file (in A, I believe??)
55	Save block to open file DE=address,BC=length
56	Close file (use file channel area)
57	RST 16 to +D/disciple printer port (A=char to print)
58	SAVE SCREEN$ 1 (see manual) a 32 column screen dump
59	Prepare file for loading - IX=UFIA address on entry, 1st 9 bytes of the file are the last 9 of the UFIA
60	Load character (in A register??)
61	Load block - DE=address, BC=length
62	Save sector
63	Load sector
64	Reset current drive to track 0, returns Carry flag set if drive empty. If bit 6 of A register is 1,disk is read-only
65	Erase file on disk,IX=UFIA address
66	SAVE SCREEN$ 2 (see manual) a large screen dump
67	Disc CATalogue (don't know details, probably IX=UFIA for filename etc)
68	Load any sector to address in IX: A=drive,D=track,E=sector
69	Save any sector from address in IX: same as above
70	Open/Close stream - A=0, open file using UFIA,A= then close the file associated with that stream (A=0-15 
	although BASIC uses 0-3 remember)
71	Page in +D/disciple ROM and RAM (eg for calling routines)

Yet more hookcodes exist for Uni-Dos, but seeing as how I only know of a very few people with this DOS, I don't 
think it's worth me typing in. Unless you REALLY want me to (email me if so...) There are also those from 27 to 50, 
used for Microdrive. I could type those too...
When the drive is mentioned (eg sector routines), the value can be 1 or 2 or (I think) "*" ie 42 decimal for the last 
drive used.
There are also some variables in the +D/disciple RAM, at 8192 decimal onwards. RTFM (if you have one).
Well thats all I can be bothered to type, as I've said, there are some sections in AlchNews on it (issues 13/14/..??).
DISCLAIMER: If you do any experimenting, I *definitely* advise using a blank disk, or one with files you don't 
mind losing in case. And it might be a good idea to reboot the +D after testing things.

Uni-Dos
=======

Uni-Dos is an extended ROM and system file that support more features than the standard Disciple or +D. There are 
a different ROM for Disciple or +D versions, but once you have it swapped (an easy-ish job) there is a single system 
file for each - thus the "Uni" part of the name.
Unfortunately, the changes also make it less compatible with software that uses +D or Disciple ROM calls directly 
although it should work for most (if not all) hookcode calls (RST 8:DEFB xx).
The Directory Bytes signifying the new filetypes are listed above with the others.

The RAMSOFT 
DISCiPLE / +D Technical Guide 
Revision 8 (9/9/99) 
=============================

The first exhaustive guide to all the secrets of the MGT drive interfaces, that we have 
always supported in our programs and conversions. It will help you to get the most from 
this wonderful disk system.
Covered topics are: 
* Detailed description of all the I/O ports and hardware registers. 
* VL1772 floppy disk controller (also mounted on Sam Coupe and Atari ST) registers info, with the list of all 
  the FDC commands and response codes. 
* Commented list of the DOS hook codes (including UNIDOS ones) for assembler programming with a 
  machine code example to load a file. 
* File system implementation, with a detailed analysis of all the file types structure including the snapshot 
  registers layout. UNIDOS specific file types are also covered. 
* GDOS, G+DOS and UNIDOS syntax overview. All the DOS BASIC statements are commented, including 
  printing and network commands. 
* Connectors pinouts, memory mapping and more, including a procedure to connect common 5.25" (1.2 MB) 
  PC disk drives to the DISCiPLE and +D. 


