Copyright (C) 2025-2026 Harley Travis <yoshi128k@gmail.com>.
This software (including source code) is licensed under the BSD Zero Clause
License. See the Copying.TXT file for 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).
Also include KFloppyA.HH and KFloppy.HC at the end of the #includes.
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 interrupt vector to my
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 main 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 newer hardware and is very different from
ISA DMA.

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