Remove remainings of the oltr(4).
[dragonfly.git] / sys / contrib / dev / fla / README
1                 README and FAQ for the fla driver.
2                 ==================================
3
4
5 [0]     COPYRIGHT & LICENSE
6
7         Please read the COPYRIGHT file carefully.  If you cannot
8         agree to be bound by the terms of this license, please
9         contact M-systems and make arrangements with them.
10
11 [1]     What does this driver do ?
12
13         This driver supports up to eight M-systems DiskOnChip
14         devices.
15
16         The driver has been tested with the following devices:
17
18         DiskOnChip2000 (8, 12, 24, 32, 40, 72, 144 MB)
19         DiskOnChipMillenium (8 MB)
20         DiskOnChipMillenium TSOP (8 MB)
21
22         You can find full details, specs etc on M-systems homepage:
23         http://www.m-sys.com
24
25 [2]     Which firmware version ?
26
27         The driver has only been tested with version 1.21.
28
29 [3]     How many devices ?
30
31         The driver supports up to 8 devices but have been tested only
32         with 5 due to hardware limitations in my test setup.
33
34 [4]     Which FreeBSD versions ?
35
36         The driver is tested for 4.0-CURRENT and 3.3-RELEASE.
37
38         Porting to earlier versions of FreeBSD should be a simple
39         matter of modifying the fla.c file.  [patches are welcome]
40
41 [5]     Can I install FreeBSD with sysinstall ?
42
43         Yes, it has been tested in FreeBSD-4.0-CURRENT and it works.
44         You will need to build a kernel with the fla driver since
45         the default "GENERIC" kernel doesn't contain the fla driver.
46
47 [6]     How to boot from a fla device ?
48
49         FreeBSD 4.0 and forward find their root device by reading
50         the /etc/fstab, so the DiskOnChip devices will work just
51         like any other device.
52
53         Earlier FreeBSD kernels recognizes the root device using
54         various hacks.  These hacks doesn't recognize the fla device
55         so some "real" hacks are needed to boot from your fla
56         device.
57
58         In pre 4.0 versions specifying the boot device in the kernel
59         config file this way is the easiest way to do it:
60
61                 config          kernel  root on major 28 minor 65538
62
63 [7]     How to disklabel a fla device ?
64
65         Look at the script in prep.fla.sh, it will do the job for you.
66
67 [8]     Who to contact ?
68
69         doc2k@phk.freebsd.dk will offer limited best-effort help
70         to the extent time permits.  Further support for special
71         projects or configurations available at reasonable hourly
72         rates.
73
74 [9]     Getting detailed
75
76         The DiskOnChip product gets out in some odd corners of the
77         PC-architecture, and chances are that things don't do what
78         you expect.  Here are some hints and random observations
79         I've made during my work with these devices.
80
81 [9a]    Choosing an address for the DOC
82
83         Each DOC needs a 8K memory window starting on an 8K boundary.
84         The lowest possible address is C000:0, the highest is DE00:0
85
86         If your hardware puts the DOC another place, you will need
87         to modify the doc2k_probe() call in fla.c.
88
89         It is important that you set the BIOS to not do "fancy things"
90         with this window, in particular no kind of cache or shadowing
91         can be enabled.
92
93         Be aware that some hardware will decode a 32k memory window 
94         for the DOC device.
95
96         If everything is OK, the DOC will print a message during
97         the BIOS startup.
98
99         For large devices it can take some time to check the flash
100         data structures, but if it takes more than 3 minutes
101         something is wrong.
102
103         If you boot a MSDOS floppy and run FDISK you should be able
104         to see the DOC device.
105
106         If it doesnt work:
107
108         If you machine never gets to the point where it will boot,
109         but just hangs it could be because you have a BIOS which
110         need the "slightly special" DOC firmware.  Obviously you
111         will need to put the DOC in another machine to load this
112         firmware.  You can download the firmware and utilities
113         from M-systems website http://www.m-sys.com
114
115         If the machine boots, but the device isn't visible it can
116         be because some other device uses the same memory window,
117         or because the BIOS prevents it from being used.  If you
118         boot MSDOS and enter DEBUG, you should be able to find a
119         BIOS extension signature at the address using the 'd'
120         command, for instance 'd d800:0'.
121
122         A special case is when the DOC prints the BIOS message
123         but disappears afterwards, this can happen because another
124         card (NCR SCSI controllers for instance) steal the memory
125         window later in the boot process.  In such a case the
126         above check with DEBUG will not show the BIOS signature.
127
128 [9b]    So just who is drive 'C' here anyway ?
129
130         Using the DUPDATE program you can choose to have the DOC
131         add itself at the front or the back of the device list.
132
133         This is, unfortunately not the only thing affecting the
134         drive order, the above mentioned NCR SCSI controllers also
135         have some builtin AI, and the result can be very confusing
136         because the DOC will come before even the floppy as a result.
137
138         There is no simple solution for this case, only variuos
139         work-arounds.  But chances are good that most users will
140         not use both a DOC and a SCSI in the same system, except
141         maybe for initial programming.
142
143 [9c]    MBR/fdisk
144
145         The boot firmware in the DOC and/or the FreeBSD bootblocks
146         mandate that the first MBR slice/(partition in FDISK lingo)
147         start exactly at "sector #1, head #1, cylinder #0."  You 
148         will have problems booting from the fla if you don't get this
149         right.  The prep.fla.sh script will do this for you.
150
151         DO NOT WRITE JUNK IN THE MBR!  The DOC firmware relies on
152         various fields and can get utterly confused if they don't
153         make sense.
154
155 [9d]    Getting the FreeBSD kernel to use the fla as root
156
157         Please see above under item 6.
158
159 [9e]    I turned the machine off while it was running and now my
160         DOC hangs during boot/panics the machine/does weird things.
161
162         If a write operation to the DOC gets interrupted by reset
163         or power-failure, it can happen that the flash data structures
164         are left in a state the sofware cannot cope with.
165
166         Your best chance is to DUPDATE, DFORMAT the device again.
167
168         If it hangs during boot, you can use this particular dirty
169         trick ENTIRELY AT YOUR OWN RISK!  DO NOT COMPLAIN IF THIS
170         DOESN'T WORK FOR YOU OR IF YOU DESTROY YOUR COMPUTER OR
171         DOC DEVICE DOING IT!
172
173         Jumper the DOC for an address which will not work, but which
174         will not interfere with the system either, C000:0 seems to
175         work pretty universally for this.
176
177         Boot MSDOS and rejumper the DOC for its real (working) address.
178
179         Run DUPDATE and use the /win:xxxx argument to point it at the
180         DOC device.
181
182 [9f]    Apart from that...
183
184         ...the DOC is just like any other disk, but it is silent,
185         has better MTBF and doesn't take up a lot of space.
186
187
188 [10]    History
189
190         The fla driver was written by Poul-Henning Kamp <phk@FreeBSD.org>
191         under contract for M-systems, and using their "OSAK"
192         development kit.
193
194 Good Luck,
195
196 Poul-Henning
197
198 $FreeBSD: src/sys/contrib/dev/fla/README,v 1.5 1999/11/10 10:50:51 phk Exp $
199 $DragonFly: src/sys/contrib/dev/fla/Attic/README,v 1.2 2003/06/17 04:28:20 dillon Exp $