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