#	$NetBSD: README.iwm,v 1.2 1999/03/27 05:48:53 scottr Exp $

From: Hauke Fath <hauke@Espresso.Rhein-Neckar.DE>
Subject: NetBSD/mac68k IWM floppy driver


## Contents

This is a short overview over the package's contents.  

The sources in this archive implement a floppy disk driver for 
NetBSD/mac68k.  The driver can be built as a LKM (Loadable Kernel 
Module) as well as an integral part of the kernel. As the name "iwmfd" 
tries to point out, it currently supports 800K DD disks formatted in 
Apple's proprietary GCR. 

Sorry, no MFM, no HD disks.


## Where does it go?

cd to /usr/src and untar the archive.

Most of the contents go to "./sys/arch/mac68k/lkm/iwm", some files go 
to "./sys/arch/mac68k/dev" and "./sys/arch/mac68k/conf". 
The file "1-3-2-iwm.diff", located in "./sys/arch", contains diffs to 
files in the mac68k subtree and should be applied as "patch <1-3-2-iwm.diff" 
from the "./sys/arch" direectory.

To run the driver lkm, you need to have a custom kernel with patches 
(at least) in mac68k/machdep.c and configured with the option LKM.
For debugging, you'd also want DDB, DEBUG, DIAGNOSTIC and INSECURE, 
and maybe UCONSOLE (see the example kernel config file).

INSECURE runs the kernel in secure level #0 when in multi-user and allows 
root to attach an LKM to it.


## How do I run it?

I assume you have built a custom kernel that defines the IWM I/O address 
and was configured with LKM.

Go to "./sys/arch/mac68k/lkm/iwm", do a make depend && make.
After building the LKM (make links && make depend && make), you can type 
'make load' as root to attach the LKM to the kernel for testing, if it 
was configured with INSECURE (see above).
  
Then put the iwmfd.o file into /usr/lkm, create an entry in /etc/lkm.conf
for it (basically "iwmfd.o - - - - -", see man lkm.conf), make sure loading 
LKMs during startup is enabled in /etc/rc.conf, and reboot.

It helps if you have something sensible on your 800K floppy. Suntar 2.xx 
(available on any info-mac mirror, try archie) is capable of writing a tar 
archive to a raw 800k disk (it will complain, but you can ignore that); 
you may want to put some text files onto the disk.


## Getting technical

A Loadable Kernel Module is an object file that can be attached to a 
running kernel (see lkm(4), lkm.conf(5), modload(8), modunload(8)).  
The LKM code sees all the kernel's global symbols (functions, global 
variables); it can patch tables and variables and thus substitute kernel 
facilities (e.g.  system calls, file systems, device drivers) with its 
own functionality.

In fact, I found it harder to understand what a device driver is and how it 
fits into the kernel that to turn an existing ( and - hopefully - well
understood) device driver into a loadable module.  

The biggest change concerns the autoconfig framework: Noone calls the 
xxx{match,attach,print} functions so they can as well be scrapped.  The 
device initialization part of their functionality, though, has to be kept 
and should be called when the module is loaded (see fdProbe(), iwmProbe() 
in fd.c, called from iwmModule.c) and unloaded.  

Terry Lambert's LKM framework contains templates for file systems and 
system calls as well as for block and for character device drivers.  
Unfortunately, it lacks examples for the latter, and as we are talking 
about a disk driver which has to supply (patch) a character device switch 
as well as a block device switch, we have to roll our own. It's not that 
difficult, though... see {load,unload}Module() in iwmModule.c for the patch 
code.