Remove remainings of the oltr(4).
[dragonfly.git] / sys / contrib / dev / fla / README
CommitLineData
984263bc
MD
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
194Good Luck,
195
196Poul-Henning
197
198$FreeBSD: src/sys/contrib/dev/fla/README,v 1.5 1999/11/10 10:50:51 phk Exp $
1de703da 199$DragonFly: src/sys/contrib/dev/fla/Attic/README,v 1.2 2003/06/17 04:28:20 dillon Exp $