Commit | Line | Data |
---|---|---|
3edcb7c8 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
73916ffb | 3 | .\" |
3edcb7c8 KB |
4 | .\" %sccs.include.redist.roff% |
5 | .\" | |
6 | .\" @(#)6.t 6.3 (Berkeley) %G% | |
73916ffb | 7 | .\" |
57349e41 MK |
8 | .\".ds RH "Adding New Devices |
9 | .ne 2i | |
10 | .NH | |
11 | ADDING NEW SYSTEM SOFTWARE | |
73916ffb KM |
12 | .PP |
13 | This section is not for the novice, it describes | |
14 | some of the inner workings of the configuration process as | |
15 | well as the pertinent parts of the system autoconfiguration process. | |
16 | It is intended to give | |
17 | those people who intend to install new device drivers and/or | |
18 | other system facilities sufficient information to do so in the | |
19 | manner which will allow others to easily share the changes. | |
20 | .PP | |
21 | This section is broken into four parts: | |
22 | .IP \(bu 3 | |
23 | general guidelines to be followed in modifying system code, | |
24 | .IP \(bu 3 | |
57349e41 | 25 | how to add non-standard system facilities to 4.3BSD, |
73916ffb | 26 | .IP \(bu 3 |
57349e41 | 27 | how to add a device driver to 4.3BSD, and |
73916ffb | 28 | .IP \(bu 3 |
57349e41 | 29 | how UNIBUS device drivers are autoconfigured under 4.3BSD on the VAX. |
73916ffb KM |
30 | .NH 2 |
31 | Modifying system code | |
32 | .PP | |
33 | If you wish to make site-specific modifications to the system | |
34 | it is best to bracket them with | |
35 | .DS | |
36 | #ifdef SITENAME | |
37 | \&... | |
38 | #endif | |
39 | .DE | |
40 | to allow your source to be easily distributed to others, and | |
41 | also to simplify \fIdiff\fP\|(1) listings. If you choose not | |
42 | to use a source code control system (e.g. SCCS, RCS), and | |
43 | perhaps even if you do, it is | |
44 | recommended that you save the old code with something | |
45 | of the form: | |
46 | .DS | |
47 | #ifndef SITENAME | |
48 | \&... | |
49 | #endif | |
50 | .DE | |
51 | We try to isolate our site-dependent code in individual files | |
52 | which may be configured with pseudo-device specifications. | |
53 | .PP | |
57349e41 MK |
54 | Indicate machine-specific code with ``#ifdef vax'' (or other machine, |
55 | as appropriate). | |
56 | 4.2BSD underwent extensive work to make it extremely portable to | |
57 | machines with similar architectures\- you may someday find | |
73916ffb KM |
58 | yourself trying to use a single copy of the source code on |
59 | multiple machines. | |
60 | .PP | |
61 | Use \fIlint\fP periodically if you make changes to the system. | |
57349e41 | 62 | The 4.3BSD kernel has only two lines of lint in it. It |
73916ffb KM |
63 | is very simple to lint the kernel. Use the LINT configuration |
64 | file, designed to pull in as much of the kernel source code as | |
65 | possible, in the following manner. | |
66 | .DS | |
67 | $ cd /sys/conf | |
68 | $ mkdir ../LINT | |
69 | $ config LINT | |
70 | $ cd ../LINT | |
71 | $ make depend | |
72 | $ make assym.s | |
73 | $ make \-k lint > linterrs 2>&1 & | |
74 | (or for users of \fIcsh\fP\|(1)) | |
75 | % make \-k >& linterrs | |
76 | .DE | |
57349e41 | 77 | This takes about an hour on a lightly loaded |
73916ffb KM |
78 | VAX-11/750, but is well worth it. |
79 | .NH 2 | |
57349e41 | 80 | Adding non-standard system facilities |
73916ffb | 81 | .PP |
57349e41 MK |
82 | This section considers the work needed to augment |
83 | .IR config 's | |
84 | data base files for non-standard system facilities. | |
85 | .I Config | |
86 | uses a set of files that list the source modules that may be required | |
87 | when building a system. | |
88 | The data bases are taken from the directory in which | |
89 | .I config | |
90 | is run, normally /sys/conf. | |
91 | Three such files may be used: | |
92 | .IR files , | |
93 | .IR files .machine, | |
94 | and | |
95 | .IR files .ident. | |
96 | The first is common to all systems, | |
97 | the second contains files unique to a single machine type, | |
98 | and the third is an optional list of modules for use on a specific machine. | |
99 | This last file may override specifications in the first two. | |
100 | The format of the | |
101 | .I files | |
102 | file has grown somewhat complex over time. Entries are normally of | |
103 | the form | |
104 | .IP | |
105 | .nf | |
106 | .DT | |
107 | \fIdir/source.c\fP \fItype\fP \fIoption-list\fP \fImodifiers\fP | |
108 | .LP | |
109 | for example, | |
110 | .IP | |
111 | .nf | |
112 | .DT | |
113 | \fIvaxuba/foo.c\fP \fBoptional\fP foo \fBdevice-driver\fP | |
114 | .LP | |
115 | The | |
116 | .I type | |
117 | is one of | |
118 | .B standard | |
119 | or | |
120 | .BR optional . | |
121 | Files marked as standard are included in all system configurations. | |
122 | Optional file specifications include a list of one or more system | |
123 | options that together require the inclusion of this module. | |
124 | The options in the list may be either names of devices that may | |
125 | be in the configuration file, | |
126 | or the names of system options that may be defined. | |
127 | An optional file may be listed multiple times with different options; | |
128 | if all of the options for any of the entries are satisfied, | |
129 | the module is included. | |
130 | .PP | |
131 | If a file is specified as a | |
132 | .IR device-driver , | |
133 | any special compilation options for device drivers will be invoked. | |
134 | On the VAX this results in the use of the | |
135 | .B \-i | |
136 | option for the C optimizer. This is required when pointer references | |
137 | are made to memory locations in the VAX I/O address space. | |
138 | .PP | |
139 | Two other optional keywords modify the usage of the file. | |
140 | .I Config | |
141 | understands that certain files are used especially for | |
142 | kernel profiling. These files are indicated in the | |
143 | .I files | |
144 | files with a | |
145 | .I profiling-routine | |
146 | keyword. For example, the current profiling subroutines | |
147 | are sequestered off in a separate file with the following | |
148 | entry: | |
149 | .IP | |
150 | .nf | |
151 | .DT | |
152 | \fIsys/subr_mcount.c\fP \fBoptional\fP \fBprofiling-routine\fP | |
153 | .fi | |
154 | .LP | |
155 | The | |
156 | .I profiling-routine | |
157 | keyword forces | |
158 | .I config | |
159 | not to compile the source file with the | |
160 | .B \-pg | |
161 | option. | |
162 | .PP | |
163 | The second keyword which can be of use is the | |
164 | .I config-dependent | |
165 | keyword. This causes | |
166 | .I config | |
167 | to compile the indicated module with the global configuration | |
168 | parameters. This allows certain modules, such as | |
169 | .I machdep.c | |
170 | to size system data structures based on the maximum number | |
171 | of users configured for the system. | |
172 | .NH 2 | |
173 | Adding device drivers to 4.3BSD | |
174 | .PP | |
175 | The I/O system and | |
73916ffb KM |
176 | .I config |
177 | have been designed to easily allow new device support to be added. | |
57349e41 | 178 | The system source directories are organized as follows: |
73916ffb KM |
179 | .DS |
180 | .TS | |
181 | lw(1.0i) l. | |
182 | /sys/h machine independent include files | |
57349e41 | 183 | /sys/sys machine-independent system source files |
73916ffb | 184 | /sys/conf site configuration files and basic templates |
57349e41 | 185 | /sys/net network-protocol-independent, but network-related code |
73916ffb KM |
186 | /sys/netinet DARPA Internet code |
187 | /sys/netimp IMP support code | |
57349e41 MK |
188 | /sys/netns Xerox NS code |
189 | /sys/vax VAX-specific mainline code | |
73916ffb KM |
190 | /sys/vaxif VAX network interface code |
191 | /sys/vaxmba VAX MASSBUS device drivers and related code | |
192 | /sys/vaxuba VAX UNIBUS device drivers and related code | |
193 | .TE | |
194 | .DE | |
195 | .PP | |
196 | Existing block and character device drivers for the VAX | |
197 | reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''. Network | |
198 | interface drivers reside in ``/sys/vaxif''. Any new device | |
199 | drivers should be placed in the appropriate source code directory | |
200 | and named so as not to conflict with existing devices. | |
201 | Normally, definitions for things like device registers are placed in | |
202 | a separate file in the same directory. For example, the ``dh'' | |
203 | device driver is named ``dh.c'' and its associated include file is | |
204 | named ``dhreg.h''. | |
205 | .PP | |
206 | Once the source for the device driver has been placed in a directory, | |
207 | the file ``/sys/conf/files.machine'', and possibly | |
208 | ``/sys/conf/devices.machine'' should be modified. The | |
209 | .I files | |
57349e41 | 210 | files in the conf directory contain a line for each C source or binary-only |
73916ffb | 211 | file in the system. Those files which are machine independent are |
57349e41 MK |
212 | located in ``/sys/conf/files,'' while machine specific files |
213 | are in ``/sys/conf/files.machine.'' The ``devices.machine'' file | |
73916ffb KM |
214 | is used to map device names to major block device numbers. If the device |
215 | driver being added provides support for a new disk | |
216 | you will want to modify this file (the format is obvious). | |
217 | .PP | |
57349e41 | 218 | In addition to including the driver in the |
73916ffb KM |
219 | .I files |
220 | file, it must also be added to the device configuration tables. These | |
221 | are located in ``/sys/vax/conf.c'', or similar for machines other than | |
222 | the VAX. If you don't understand what to add to this file, you should | |
223 | study an entry for an existing driver. | |
57349e41 MK |
224 | Remember that the position in the |
225 | device table specifies the major device number. | |
226 | The block major number is needed in the ``devices.machine'' file | |
227 | if the device is a disk. | |
73916ffb KM |
228 | .PP |
229 | With the configuration information in place, your configuration | |
230 | file appropriately modified, and a system reconfigured and rebooted | |
231 | you should incorporate the shell commands needed to install the special | |
232 | files in the file system to the file ``/dev/MAKEDEV'' or | |
233 | ``/dev/MAKEDEV.local''. This is discussed in the document ``Installing | |
57349e41 | 234 | and Operating 4.3BSD on the VAX''. |
73916ffb KM |
235 | .NH 2 |
236 | Autoconfiguration on the VAX | |
237 | .PP | |
57349e41 | 238 | 4.3BSD requires all device drivers to conform to a |
73916ffb KM |
239 | set of rules which allow the system to: |
240 | .IP 1) | |
241 | support multiple UNIBUS and MASSBUS adapters, | |
242 | .IP 2) | |
243 | support system configuration at boot time, and | |
244 | .IP 3) | |
245 | manage resources so as not to crash when devices request | |
246 | resources which are unavailable. | |
247 | .LP | |
248 | In addition, devices such as the RK07 which require | |
249 | everyone else to get off the UNIBUS when they are running | |
250 | need cooperation from other DMA devices if they are to work. | |
251 | Since it is unlikely that you will be writing a device driver | |
252 | for a MASSBUS device, this section is devoted exclusively to | |
57349e41 | 253 | describing the I/O system and autoconfiguration process as it |
73916ffb KM |
254 | applies to UNIBUS devices. |
255 | .PP | |
256 | Each UNIBUS on a VAX has a set of resources: | |
257 | .IP \(bu | |
57349e41 MK |
258 | 496 map registers which are used to convert from the 18-bit UNIBUS |
259 | addresses into the much larger VAX memory address space. | |
73916ffb KM |
260 | .IP \(bu |
261 | Some number of buffered data paths (3 on an 11/750, 15 on an 11/780, 0 | |
262 | on an 11/730) which are used by high speed devices to transfer | |
263 | data using fewer bus cycles. | |
264 | .LP | |
265 | There is a structure of type \fIstruct uba_hd\fR in the system per UNIBUS | |
266 | adapter used to manage these resources. This structure also contains | |
267 | a linked list where devices waiting for resources to complete DMA UNIBUS | |
268 | activity have requests waiting. | |
269 | .PP | |
270 | There are three central structures in the writing of drivers for UNIBUS | |
57349e41 | 271 | controllers; devices which do not do DMA I/O can often use only two |
73916ffb KM |
272 | of these structures. The structures are \fIstruct uba_ctlr\fR, the |
273 | UNIBUS controller structure, \fIstruct uba_device\fR the UNIBUS | |
274 | device structure, and \fIstruct uba_driver\fR, the UNIBUS driver structure. | |
275 | The \fIuba_ctlr\fR and \fIuba_device\fR structures are in | |
276 | one-to-one correspondence with the definitions of controllers and | |
277 | devices in the system configuration. | |
278 | Each driver has a \fIstruct uba_driver\fR structure specifying an internal | |
279 | interface to the rest of the system. | |
280 | .PP | |
281 | Thus a specification | |
282 | .DS | |
283 | controller sc0 at uba0 csr 0176700 vector upintr | |
284 | .DE | |
285 | would cause a \fIstruct uba_ctlr\fR to be declared and initialized in | |
286 | the file \fIioconf.c\fR for the system configured from this description. | |
287 | Similarly specifying | |
288 | .DS | |
289 | disk up0 at sc0 drive 0 | |
290 | .DE | |
291 | would declare a related \fIuba_device\fR in the same file. | |
292 | The \fIup.c\fR driver which implements this driver specifies in | |
293 | its declarations: | |
294 | .DS | |
295 | int upprobe(), upslave(), upattach(), updgo(), upintr(); | |
296 | struct uba_ctlr *upminfo[NSC]; | |
297 | struct uba_device *updinfo[NUP]; | |
298 | u_short upstd[] = { 0776700, 0774400, 0776300, 0 }; | |
299 | struct uba_driver scdriver = | |
300 | { upprobe, upslave, upattach, updgo, upstd, "up", updinfo, "sc", upminfo }; | |
301 | .DE | |
302 | initializing the \fIuba_driver\fR structure. | |
303 | The driver will support some number of controllers named \fIsc0\fR, \fIsc1\fR, | |
304 | etc, and some number of drives named \fIup0\fR, \fIup1\fR, etc. where the | |
305 | drives may be on any of the controllers (that is there is a single | |
306 | linear name space for devices, separate from the controllers.) | |
307 | .PP | |
308 | We now explain the fields in the various structures. It may help | |
57349e41 | 309 | to look at a copy of \fIvaxuba/ubareg.h\fR, \fIvaxuba/ubavar.h\fR and drivers |
73916ffb KM |
310 | such as \fIup.c\fR and \fIdz.c\fR while reading the descriptions of |
311 | the various structure fields. | |
312 | .SH | |
313 | uba_driver structure | |
314 | .PP | |
315 | One of these structures exists per driver. It is initialized in | |
316 | the driver and contains functions used by the configuration program | |
317 | and by the UNIBUS resource routines. The fields of the structure are: | |
318 | .IP \fBud_probe\fP | |
57349e41 MK |
319 | A routine which, given a \fIcaddr_t\fR address as argument, |
320 | should attempt to determine that the device is present | |
321 | at that address in virtual memory, | |
322 | and should cause an interrupt from the device. | |
323 | When probing controllers, two additional arguments are supplied: | |
324 | the controller index, and a pointer to the \fIuba_ctlr\fP structure. | |
325 | Device probe routines receive a pointer to the \fIuba_device\fP structure | |
326 | as second argument. | |
327 | Both of these structures are described below. | |
328 | Neither is normally used, but devices that must record status or device | |
329 | type information from the probe routine may require them. | |
330 | .PP | |
331 | The autoconfiguration routine attempts to verify that the specified address | |
332 | responds before calling the probe routine. | |
333 | However, the device may not actually exist or may be of a different type, | |
334 | and therefore the probe routine should use delays | |
335 | (via the DELAY(n) macro which delays for \fIn\fR microseconds) rather than | |
73916ffb KM |
336 | waiting for specific events to occur. The routine must \fBnot\fR |
337 | declare its argument as a \fIregister\fR parameter, but \fBmust\fR declare | |
338 | .DS | |
339 | register int br, cvec; | |
340 | .DE | |
341 | as local variables. At boot time the system takes special measures | |
342 | that these variables are ``value-result'' parameters. The \fIbr\fR | |
343 | is the IPL of the device when it interrupts, and the \fIcvec\fR | |
344 | is the interrupt vector address on the UNIBUS. These registers | |
345 | are actually filled in in the interrupt handler when an interrupt occurs. | |
346 | .IP | |
347 | As an example, here is the \fIup.c\fR | |
348 | probe routine: | |
349 | .DS | |
350 | upprobe(reg) | |
351 | caddr_t reg; | |
352 | { | |
353 | register int br, cvec; | |
354 | ||
355 | #ifdef lint | |
57349e41 | 356 | br = 0; cvec = br; br = cvec; upintr(0); |
73916ffb KM |
357 | #endif |
358 | ((struct updevice *)reg)->upcs1 = UP_IE|UP_RDY; | |
359 | DELAY(10); | |
360 | ((struct updevice *)reg)->upcs1 = 0; | |
361 | return (sizeof (struct updevice)); | |
362 | } | |
363 | .DE | |
364 | The definitions for \fIlint\fR serve to indicate to it that the | |
57349e41 MK |
365 | \fIbr\fR and \fIcvec\fR variables are value-result. |
366 | The call to the interrupt routine satisfies lint that the interrupt | |
367 | handler is used. | |
368 | The cod here enable interrupts on the device and write the ready bit UP_RDY. | |
73916ffb KM |
369 | The 10 microsecond delay insures that the interrupt enable will |
370 | not be canceled before the interrupt can be posted. The return of | |
371 | ``sizeof (struct updevice)'' here indicates that the probe routine | |
372 | is satisfied that the device is present (the value returned is not | |
57349e41 | 373 | currently used, but future plans dictate that you should return the amount |
73916ffb KM |
374 | of space in the device's register bank). A probe routine may use |
375 | the function ``badaddr'' to see | |
376 | if certain other addresses are accessible on the UNIBUS (without generating | |
377 | a machine check), or look at the contents of locations where certain | |
378 | registers should be. If the registers contents are not acceptable or | |
379 | the addresses don't respond, the probe routine can return 0 and the | |
380 | device will not be considered to be there. | |
381 | .IP | |
382 | One other thing to note is that the action of different VAXen when illegal | |
383 | addresses are accessed on the UNIBUS may differ. Some of the machines | |
384 | may generate machine checks and some may cause UNIBUS errors. Such | |
385 | considerations are handled by the configuration program and the driver | |
386 | writer need not be concerned with them. | |
387 | .IP | |
388 | It is also possible to write a very simple probe routine for a one-of-a-kind | |
389 | device if probing is difficult or impossible. Such a routine would include | |
390 | statements of the form: | |
391 | .DS | |
392 | br = 0x15; | |
393 | cvec = 0200; | |
394 | .DE | |
395 | for instance, to declare that the device ran at UNIBUS br5 and interrupted | |
57349e41 | 396 | through vector 0200 on the UNIBUS. |
73916ffb KM |
397 | .IP \fBud_slave\fP |
398 | This routine is called with a \fIuba_device\fR structure (yet to | |
399 | be described) and the address of the device controller. It should | |
400 | determine whether a particular slave device of a controller is | |
401 | present, returning 1 if it is and 0 if it is not. | |
402 | As an example here is the slave routine for \fIup.c\fR. | |
403 | .DS | |
404 | upslave(ui, reg) | |
405 | struct uba_device *ui; | |
406 | caddr_t reg; | |
407 | { | |
408 | register struct updevice *upaddr = (struct updevice *)reg; | |
409 | ||
410 | upaddr->upcs1 = 0; /* conservative */ | |
411 | upaddr->upcs2 = ui->ui_slave; | |
57349e41 MK |
412 | if (upaddr->upcs2 & UPCS2_NED) { |
413 | upaddr->upcs1 = UP_DCLR | UP_GO; | |
73916ffb KM |
414 | return (0); |
415 | } | |
416 | return (1); | |
417 | } | |
418 | .DE | |
419 | Here the code fetches the slave (disk unit) number from the \fIui_slave\fR | |
420 | field of the \fIuba_device\fR structure, and sees if the controller | |
57349e41 | 421 | responds that that is a non-existent driver (NED). If the drive is not present, |
73916ffb KM |
422 | a drive clear is issued to clean the state of the controller, and 0 is |
423 | returned indicating that the slave is not there. Otherwise a 1 is returned. | |
424 | .IP \fBud_attach\fP | |
425 | The attach routine is called after the autoconfigure code and the driver concur | |
426 | that a peripheral exists attached to a controller. This is the routine | |
427 | where internal driver state about the peripheral can be initialized. | |
428 | Here is the \fIattach\fR routine from the \fIup.c\fR driver: | |
429 | .DS | |
430 | .DT | |
431 | upattach(ui) | |
432 | register struct uba_device *ui; | |
433 | { | |
434 | register struct updevice *upaddr; | |
435 | ||
436 | if (upwstart == 0) { | |
437 | timeout(upwatch, (caddr_t)0, hz); | |
438 | upwstart++; | |
439 | } | |
440 | if (ui->ui_dk >= 0) | |
441 | dk_mspw[ui->ui_dk] = .0000020345; | |
442 | upip[ui->ui_ctlr][ui->ui_slave] = ui; | |
443 | up_softc[ui->ui_ctlr].sc_ndrive++; | |
444 | ui->ui_type = upmaptype(ui); | |
445 | } | |
446 | .DE | |
447 | The attach routine here performs a number of functions. The first | |
448 | time any drive is attached to the controller it starts the timeout | |
449 | routine which watches the disk drives to make sure that interrupts | |
450 | aren't lost. It also initializes, for devices which have been assigned | |
451 | \fIiostat\fR numbers (when ui->ui_dk >= 0), the transfer rate of the | |
452 | device in the array \fIdk_mspw\fR, the fraction of a second it takes | |
453 | to transfer 16 bit word. It then initializes an inverting pointer | |
454 | in the array \fIupip\fR which will be used later to determine, for a | |
455 | particular \fIup\fR controller and slave number, the corresponding | |
456 | \fIuba_device\fR. It increments the count of the number of devices | |
457 | on this controller, so that search commands can later be avoided | |
458 | if the count is exactly 1. It then attempts to decipher the actual | |
459 | type of drive attached to the controller in a controller-specific | |
460 | way. On the EMULEX SC-21 it may ask for the number of tracks on | |
461 | the device and use this to decide what the drive type is. The drive | |
462 | type is used to setup disk partition mapping tables and other | |
463 | device specific information. | |
464 | .IP \fBud_dgo\fP | |
465 | .br | |
57349e41 | 466 | This is the routine which is called by the UNIBUS resource management |
73916ffb KM |
467 | routines when an operation is ready to be started (because the required |
468 | resources have been allocated). The routine in \fIup.c\fR is: | |
469 | .DS | |
470 | updgo(um) | |
471 | struct uba_ctlr *um; | |
472 | { | |
473 | register struct updevice *upaddr = (struct updevice *)um->um_addr; | |
474 | ||
475 | upaddr->upba = um->um_ubinfo; | |
476 | upaddr->upcs1 = um->um_cmd|((um->um_ubinfo>>8)&0x300); | |
477 | } | |
478 | .DE | |
479 | This routine uses the field \fIum_ubinfo\fR of the \fIuba_ctlr\fR | |
480 | structure which is where the UNIBUS routines store the UNIBUS | |
57349e41 | 481 | map allocation information. In particular, the low 18 bits of this |
73916ffb KM |
482 | word give the UNIBUS address assigned to the transfer. The assignment |
483 | to \fIupba\fR in the go routine places the low 16 bits of the UNIBUS | |
484 | address in the disk UNIBUS address register. The next assignment | |
485 | places the disk operation command and the extended (high 2) address | |
57349e41 | 486 | bits in the device control-status register, starting the I/O operation. |
73916ffb KM |
487 | The field \fIum_cmd\fR was initialized with the command to be stuffed |
488 | here in the driver code itself before the call to the \fIubago\fR | |
489 | routine which eventually resulted in the call to \fIupdgo\fR. | |
490 | .IP \fBud_addr\fP | |
57349e41 MK |
491 | This is a zero-terminated list of the conventional addresses |
492 | for the device control registers in UNIBUS space. | |
493 | This information is used by the system | |
73916ffb KM |
494 | to look for instances of the device supported by the driver. |
495 | When the system probes for the device it first checks for a | |
496 | control-status register located at the address indicated in | |
497 | the configuration file (if supplied), then uses the list of | |
498 | conventional addresses pointed to be \fIud_addr\fP. | |
499 | .IP \fBud_dname\fP | |
57349e41 | 500 | This is the name of a \fIdevice\fR supported by this controller; thus the |
73916ffb KM |
501 | disks on a SC-21 controller are called \fIup0\fR, \fIup1\fR, etc. |
502 | That is because this field contains \fIup\fR. | |
503 | .IP \fBud_dinfo\fP | |
57349e41 | 504 | This is an array of back pointers to the \fIuba_device\fR structures for |
73916ffb KM |
505 | each device attached to the controller. Each driver defines a set of |
506 | controllers and a set of devices. The device address space is always | |
507 | one-dimensional, so that the presence of extra controllers may be | |
508 | masked away (e.g. by pattern matching) to take advantage of hardware | |
509 | redundancy. This field is filled in by the configuration program, | |
510 | and used by the driver. | |
511 | .IP \fBud_mname\fP | |
512 | The name of a controller, e.g. \fIsc\fR for the \fIup.c\fR driver. | |
513 | The first SC-21 is called \fIsc0\fR, etc. | |
514 | .IP \fBud_minfo\fP | |
515 | The backpointer array to the structures for the controllers. | |
516 | .IP \fBud_xclu\fP | |
517 | If non-zero specifies that the controller requires exclusive | |
518 | use of the UNIBUS when it is running. This is non-zero currently | |
519 | only for the RK611 controller for the RK07 disks to map around a hardware | |
520 | problem. It could also be used if 6250bpi tape drives are to be used | |
521 | on the UNIBUS to insure that they get the bandwidth that they need | |
522 | (basically the whole bus). | |
57349e41 MK |
523 | .IP \fBud_ubamem\fP |
524 | This is an optional entry point to the driver to configure UNIBUS memory | |
525 | associated with a device. | |
526 | If this field in the driver structure is null, it is ignored. | |
527 | Otherwise, it is called before beginning to probe for devices | |
528 | when configuration of a UNIBUS is begun. | |
529 | The driver must probe for the existence of its memory, | |
530 | and is then responsible for allocating the map registers corresponding | |
531 | to the device memory addresses so that the registers are not used for other | |
532 | purposes. | |
533 | The \fBud_ubamem\fP returns 0 on success and \-1 on failure. | |
534 | A return value of 1 indicates that the memory exists, and that there | |
535 | is no further configuration required for the device. | |
73916ffb KM |
536 | .SH |
537 | uba_ctlr structure | |
538 | .PP | |
539 | One of these structures exists per-controller. | |
540 | The fields link the controller to its UNIBUS adapter and contain the | |
541 | state information about the devices on the controller. The fields are: | |
542 | .IP \fBum_driver\fP | |
543 | A pointer to the \fIstruct uba_device\fR for this driver, which has | |
544 | fields as defined above. | |
545 | .IP \fBum_ctlr\fP | |
546 | The controller number for this controller, e.g. the 0 in \fIsc0\fR. | |
547 | .IP \fBum_alive\fP | |
548 | Set to 1 if the controller is considered alive; currently, always set | |
549 | for any structure encountered during normal operation. That is, the | |
550 | driver will have a handle on a \fIuba_ctlr\fR structure only if the | |
551 | configuration routines set this field to a 1 and entered it into the | |
552 | driver tables. | |
553 | .IP \fBum_intr\fP | |
554 | The interrupt vector routines for this device. These are generated | |
555 | by \fIconfig\fP and this field is initialized in the | |
556 | \fIioconf.c\fR file. | |
557 | .IP \fBum_hd\fP | |
558 | .br | |
559 | A back-pointer to the UNIBUS adapter to which this controller is attached. | |
560 | .IP \fBum_cmd\fP | |
561 | A place for the driver to store the command which is to be given to | |
562 | the device before calling the routine \fIubago\fR with the devices | |
563 | \fIuba_device\fR structure. This information is then retrieved when the | |
564 | device go routine is called and stuffed in the device control status register | |
57349e41 | 565 | to start the I/O operation. |
73916ffb KM |
566 | .IP \fBum_ubinfo\fP |
567 | Information about the UNIBUS resources allocated to the device. This is | |
568 | normally only used in device driver go routine (as \fIupdgo\fR above) | |
569 | and occasionally in exceptional condition handling such as ECC correction. | |
570 | .IP \fBum_tab\fP | |
571 | This buffer structure is a place where the driver hangs the device structures | |
572 | which are ready to transfer. Each driver allocates a buf structure for each | |
573 | device (e.g. \fIupdtab\fR in the \fIup.c\fR driver) for this purpose. | |
574 | You can think of this structure as a device-control-block, and the | |
575 | buf structures linked to it as the unit-control-blocks. | |
576 | The code for dealing with this structure is stylized; see the \fIrk.c\fR | |
577 | or \fIup.c\fR driver for the details. If the \fIubago\fR routine | |
578 | is to be used, the structure attached to this \fIbuf\fR structure | |
579 | must be: | |
580 | .RS | |
581 | .IP \(bu 3 | |
582 | A chain of \fIbuf\fR structures for each waiting device on this controller. | |
583 | .IP \(bu 3 | |
584 | On each waiting \fIbuf\fR structure another \fIbuf\fR structure which is | |
57349e41 | 585 | the one containing the parameters of the I/O operation. |
73916ffb KM |
586 | .RE |
587 | .SH | |
588 | uba_device structure | |
589 | .PP | |
590 | One of these structures exist for each device attached to a UNIBUS | |
591 | controller. Devices which are not attached to controllers or which | |
592 | perform no buffered data path | |
57349e41 | 593 | DMA I/O may have only a device structure. Thus \fIdz\fR |
73916ffb KM |
594 | and \fIdh\fR devices have only \fIuba_device\fR structures. |
595 | The fields are: | |
596 | .IP \fBui_driver\fP | |
597 | A pointer to the \fIstruct uba_driver\fR structure for this device type. | |
598 | .IP \fBui_unit\fP | |
599 | The unit number of this device, e.g. 0 in \fBup0\fR, or 1 in \fBdh1\fR. | |
600 | .IP \fBui_ctlr\fP | |
601 | .br | |
602 | The number of the controller on which this device is attached, or \-1 | |
603 | if this device is not on a controller. | |
604 | .IP \fBui_ubanum\fP | |
605 | The number of the UNIBUS on which this device is attached. | |
606 | .IP \fBui_slave\fP | |
607 | The slave number of this device on the controller which it is attached to, | |
608 | or \-1 if the device is not a slave. Thus a disk which was unit 2 on | |
609 | a SC-21 would have \fIui_slave\fR 2; it might or might not be \fIup2\fR, | |
610 | that depends on the system configuration specification. | |
611 | .IP \fBui_intr\fP | |
612 | .br | |
613 | The interrupt vector entries for this device, copied into the UNIBUS | |
614 | interrupt vector at boot time. The values of these fields are filled | |
615 | in by \fIconfig\fP to small code segments which it | |
616 | generates in the file \fIubglue.s\fR. | |
617 | .IP \fBui_addr\fP | |
618 | The control-status register address of this device. | |
619 | .IP \fBui_dk\fP | |
620 | .br | |
621 | The iostat number assigned to this device. Numbers are assigned to | |
57349e41 | 622 | disks only, and are small nonnegative integers which index the various |
73916ffb KM |
623 | \fIdk_*\fP arrays in <\fIsys/dk.h\fP>. |
624 | .IP \fBui_flags\fP | |
625 | The optional ``flags \fIxxx\fP'' parameter from the configuration | |
626 | specification was copied to this field, to be interpreted by the driver. | |
627 | If \fIflags\fP was not specified, then this field will contain a 0. | |
628 | .IP \fBui_alive\fP | |
629 | The device is really there. Presently set to 1 when a device is | |
630 | determined to be alive, and left 1. | |
631 | .IP \fBui_type\fP | |
632 | The device type, to be used by the driver internally. | |
633 | .IP \fBui_physaddr\fP | |
634 | The physical memory address of the device control-status register. | |
57349e41 | 635 | This is typically used in the device dump routines. |
73916ffb KM |
636 | .IP \fBui_mi\fP |
637 | .br | |
638 | A \fIstruct uba_ctlr\fP pointer to the controller (if any) on which | |
639 | this device resides. | |
640 | .IP \fBui_hd\fP | |
641 | .br | |
642 | A \fIstruct uba_hd\fP pointer to the UNIBUS on which this device resides. | |
643 | .SH | |
644 | UNIBUS resource management routines | |
645 | .PP | |
646 | UNIBUS drivers are supported by a collection of utility routines | |
647 | which manage UNIBUS resources. If a driver attempts to bypass the | |
648 | UNIBUS routines, other drivers may not operate properly. | |
649 | The major routines are: \fIuballoc\fP to allocate UNIBUS resources, | |
650 | \fIubarelse\fP to release previously allocated resources, and | |
651 | \fIubago\fP to initiate DMA. When allocating UNIBUS resources | |
652 | you may request that you | |
653 | .IP NEEDBDP | |
654 | if you need a buffered data path, | |
655 | .IP HAVEBDP | |
656 | if you already have a buffered data path and just want new | |
57349e41 | 657 | mapping registers (and access to the UNIBUS), |
73916ffb | 658 | .IP CANTWAIT |
57349e41 MK |
659 | if you are calling (potentially) from interrupt level, and |
660 | .IP NEED16 | |
661 | if the device uses only 16 address bits, and thus requires | |
662 | map registers from the first 64K of UNIBUS address space. | |
73916ffb KM |
663 | .LP |
664 | If the presentation here does not answer all the questions | |
665 | you may have, consult the file /sys/vaxuba/uba.c | |
666 | .SH | |
667 | Autoconfiguration requirements | |
668 | .PP | |
669 | Basically all you have to do is write a \fIud_probe\fP and a \fIud_attach\fP | |
670 | routine for the controller. It suffices to have a \fIud_probe\fP routine | |
671 | which just initializes \fIbr\fP and \fIcvec\fP, and a \fIud_attach\fP | |
672 | routine which does nothing. | |
673 | Making the device fully configurable requires, of course, more work, | |
674 | but is worth it if you expect the device to be in common usage | |
675 | and want to share it with others. | |
676 | .PP | |
677 | If you managed to create all the needed hooks, then make sure you include | |
678 | the necessary header files; the ones included by \fIvaxuba/ct.c\fP are nearly | |
679 | minimal. Order is important here, don't be surprised at undefined structure | |
57349e41 MK |
680 | complaints if you order the includes incorrectly. |
681 | Finally, if you get the device configured in, you can try bootstrapping | |
73916ffb KM |
682 | and see if configuration messages print out about your device. |
683 | It is a good idea to have some messages in the probe routine so that | |
57349e41 MK |
684 | you can see that it is being called and what is going on. |
685 | If it is not called, then you probably have the control-status | |
686 | register address wrong in the system configuration. The autoconfigure | |
687 | code notices that the device doesn't exist in this case, | |
688 | and the probe will never be called. | |
73916ffb KM |
689 | .PP |
690 | Assuming that your probe routine works and you manage | |
691 | to generate an interrupt, then you are basically back to where you | |
692 | would have been under older versions of UNIX. | |
693 | Just be sure to use the \fIui_ctlr\fP field of the \fIuba_device\fP | |
694 | structures to address the device; compiling in funny constants | |
695 | will make your driver only work on the CPU type you have (780, 750, or 730). | |
696 | .PP | |
697 | Other bad things that might happen while you are setting up the configuration | |
698 | stuff: | |
699 | .IP \(bu 3 | |
700 | You get ``nexus zero vector'' errors from the system. This will happen | |
701 | if you cause a device to interrupt, but take away the interrupt enable | |
702 | so fast that the UNIBUS adapter cancels the interrupt and confuses | |
703 | the processor. The best thing to do it to put a modest delay in the | |
704 | probe code between the instructions which should cause and interrupt and | |
705 | the clearing of the interrupt enable. (You should clear interrupt | |
706 | enable before you leave the probe routine so the device doesn't interrupt | |
707 | more and confuse the system while it is configuring other devices.) | |
708 | .IP \(bu 3 | |
709 | The device refuses to interrupt or interrupts with a ``zero vector''. | |
710 | This typically indicates a problem with the hardware or, for devices | |
711 | which emulate other devices, that the emulation is incomplete. Devices | |
712 | may fail to present interrupt vectors because they have configuration | |
713 | switches set wrong, or because they are being accessed in inappropriate ways. | |
714 | Incomplete emulation can cause ``maintenance mode'' features to not work | |
715 | properly, and these features are often needed to force device interrupts. |