Form: Jarek Adamski <zx@yarek.com>
Date: 2003-07-11 23:53:33


DSKHNDLR is a block device driver. There are drivers for:
  -floppy disk controllers (#60 - 765A, #70 - WD177X, WD197X):
    -YAMOD.FDC765A (also Multi I/O ISA card in YABUS ports);
    -Beta 128 interface for ZX Spectrum (also build-in in Pentagon);
    -MB-02 interface for ZX Spectrum (doesn't use DMA),
    -ZX Spectrum +3 build-in controller,
    -Plus D interface for ZX Spectrum,
    -Sam Coupe,
    -Spectravideo 738 X'PRESS (MSX),
    -Timex FDD 3000,
  -harddisk controllers (#A0 - master, #B0 - slave):
    -YAMOD.ATBUS IDE module,
    -ZXATASP interface for ZX Spectrum,
    -ZXIDE128 interface for ZX Spectrum and Timex hardware,
    -ATOM interface for Sam Coupe,
    -IDE8255 interfce (8255 that reads IDE in MODE 1),
  -ramdisk (#00):
    -not included here as are very machine and software dependent.



DSKHNDLR structure is as follows:

+#00	JP	int		;interrupt entry, every 1s
+#03	JP	main		;function entry
+#06	DEFW	version		;type and version
+#08	DEFW	length		;from +#00 to the end
+#0A	DEFW	start		;address of pleacement (+#00 absolute)
+#0C	DEFW	datalen		;length of workarea
+#0E	DEFW	data		;start of workarea
+#10	DEFM	"DSKHNDLR"	;signature
+#18	DEFM	"NAMENAME"	;name
+#20	DEFS	datalen		;data used when DSKHNDLR is in RAM
	DEFS	length-datalen-#0020
;next DSKHNLR can be pleaced here or the RET must follow (int chain)	


The int entry should be called every 1s. It is used to stop the drive motors.
In IX must be provided address of present workarea. Nothing strange will
happen, when int entry isn't called at all - only the motors will work all
the time. All registers except AF are preserved. The int entries are chained,
so next DSKHNDLR can be pleaced just after one. In a chain, the
	LD	IX,($+18)	;takes data address from +#0E
should be before DSKHNDLR body. DSKHNDLRs shuld not be chained in ROM, unless
all are used in a hardware. In this case the value loaded into IX must point
into RAM.


The main entry is to call DSKHNDLR function. Register A contains function
number (bits 4..7 are ignored) and register C contains unit number (bits 4..7
are ignored), registers HL contain address of data buffer. There are
following functions defined:

 #00 - initialization - returns numer of drives in B and drives mask in DE.
For both master and slave harddisk call twice with C=#A0 then C=#B0. Value
0 returned in register B means no drives were found and the DSKHNDLR can be
disabled. Bit 0 in E means unit 0 and so on. Caution! In #A0 and #B0 DSKHNDLRs
the unit 0 is usually the system partition with informations about other
partions! So these DSKHNDLR in first use should return B=1 - then the system
partition must be analysed and cylinder shifts for other partitions must be
set.

 #01 - set parameters for unit C:
  B - step time (#70); maximal headunload (#60),
  D - sector length (#60 only),
  E - number of sectors (#60 only),
  L - gap for reading/writing (only #60),
  H - GAP3 for fomatting (only #60),
  HL - cylinder shift for partition (#A0 and #B0).

 #02 - read sector E from side B at cylinder D into HL. A=0 when correct.
No retry is performed in case of error. Sometimes the first attempt can fail.
Register HL contains address after last readed byte. BC, DE, F are modified.

 #03 - write sector E to side B at cylinder D from HL. A=0 when correct.
No retry is performed in case of error. Sometimes the first attempt can fail.
Register HL contains address after last written byte. BC, DE, F are modified.

 #04 - verify sector E from side B at cylinder D with HL. A=0 when correct.
No retry is performed in case of error. Sometimes the first attempt can fail.
Register HL contains address after last verified byte. BC, DE, F are modified.
Usually in ramdisk drivers only A=0 is done.

 #05 - format E sectors on side B at cylinder D with data at HL. A=0 when
correct. No retry is performed in case of error. Sometimes the first attempt
can fail. Register HL contains address after last used byte. BC, DE, F are
modified. Not every DSKHNDLR supports this function. The table pointer with HL
contains E blocks of 4 bytes - each block is the sector ID contents. The #60
DSKHNDLRs cannot format tracks with sectors of variable size (e.g. QED820
format has 5 1kB sectors and one 512B, used as bootsetor). The #A0 and #B0
DSKHNDLRs don't format at all.

 #0F - motor stop. Do not use, as this isn't official. Not every DSKHNDLR
supports this function. AF are modified.


The version word contains DSKHNDLR type in high byte and version number in
low byte. The current version is #02. Former versions had different structure.
Do not use DSKHNDLR if it has wrong version number.


The length and start words are for verifying DSKHNDLR placement in memory.
When the start address isn't equal to the address, where DSKHNDLR was found,
it cannot be used. You can copy to proper pleace using start and length values
(remember about the int chain). At start+length+4 you probaby can find another
DSKHNDLR, when they are chained.


The datalen and data can be used to allocate RAM, when DSKHNDLR is pleaced
in ROM. The data area must be copied into the allocated RAM, otherwise some
DSKHNDLRs will not work correctly. The data address is also used to load IX
with, when DSKHNDLR is in RAM.


The "DSKHNDLR" signature is used to search DSKHNDLR in ROM or BIOS. Verify
also the version number, start address and presence of #C3 codes at start
and start+3!


The "NAMENAME" signature is name of the DSKHNDLR. The name can be presented
to the user, after a DSKHNDLR is found. E.g.:
 DSKHNDLR.ZXIDE128 found, 3 units, mask %0019




Compilation notes.

The sources are for GEN80. Extentions are ".GI", as they must be included
with the "*I FILE.GI" option.

Comments are usually in Polish language. AmigaPL character set is used (as in
CPM22QED).

The dskhnd label must be defined as 0. When bit 5 in it is 1 (#0020), the
formatting code will be removed (DSKHNDLR will be shorter then). If the
DSKHNDLR will be pleaced in ROM, bit 0 must be set (#0001) - this activates
copying bytes from data into IX while initialization. Caution! Not all
DSKHNDLRs are now prepared for automatic copying the data area! Check this
before you use one and ask me for new release.



	End of file DSKHNDLR.TXT
