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