![[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.