Copyright (C) 2025 Harley Travis <yoshi128k@gmail.com>.
This work is free. You can redistribute it and/or modify it under the
terms of the Do What The Fuck You Want To Public License, Version 2,
as published by Sam Hocevar. See the Copying.TXT file for more details.

These files contain the code required for the low-level floppy disk driver.
Currently, there is no block device code that implements this driver as I
find it a bit beyond my capabilities.

To install the driver:
1. Copy KFloppy.HC, KFloppyA.HH, KFloppyB.HH, and KFloppyDMA.HC to ::/Kernel/
2. In Kernel.PRJ(.Z), include KFloppyDMA.HC between KStart32 and KStart64; this adds a
buffer for DMA transfers to/from the floppy disk controller (see notes)
3. Then, include KFloppyA.HH and KFloppy.HC at the bottom of the above file.
4. In ::/StartOS.HC, include KFLoppyB.HH after KernelC.HH; this exports the driver
functions for use by your own programs.

On startup, you will have to unmask IRQ6 and point its int to the IRQ handler, FDCIrqHandler.
To do this, write 0xB8 to port 0x21, then use IntEntrySet to set the vector for the aforementioned int (this may be included in the startup files).

In HolyC, that would be:
OutU8(0x21,0xB8); // Unmask IRQ6
IntEntrySet(0x26,&FDCIrqHandler); // IRQ mode is the default

Use FDCReset to initialize the drive (make sure a disk is inserted; it does not test for one before doing things).

FDCSeek does what it says.

FDCRead/FDCReadMulti will read data from the disk.
FDCWrite/FDCWriteMulti will write data to the disk.
Data that has been read or is to be written goes in FDC_DMA.
(The FDC*Multi funs use multi-track mode; data will be read from both heads)

The result of seeks, recalibrations, and data xfers will be displayed in the Adam Task.

--A note about DMA--
If things went to plan, I would have use PIO to do data transfers to and from the disk.
However, they didn't, and my dev system would freeze when attempting to read from tracks
beyond 0 (the drive would make a seek noise, at which point it froze).

In Terry's demands document, he wrote:
"We don't want to do DMA."

This is a bit ambiguous, as there are two principle forms of DMA in the PC world:

1. ISA DMA, used by the floppy controller and ISA expansion cards.
2. PCI Busmastering, which is used by modern hardware and is very different from ISA DMA.

TheTinkerer on the TOS Discord suggested that Terry *may* have been fine ISA DMA, but I would still
consider my usage of it to be at least a little blasphemous (though it is not mentioned in the Charter).