Many of the steps that follow require you to modify files and directories owned by root. You must therefore be logged in as root or execute as the super-user to develop and debug device drivers. Throughout this section, the trace driver provided in Appendix C is used as a model.
1. Establish a device "Internal Name." This can be up to eight charac-ters long and must start with a letter, but it can have digits or under-scores after the first letter.
It is the name that the ID uses to identify the device. For the trace driver, the name is "trace." From now on let's call this
DEV~AME. For the UNIX System V /386 ID implementation, the following name definitions based on the internal name are required:
D Field 1 of the Master file. This must be DEV ~AME.
D Field 4 of the Master file. This is the driver entry point (func-tion) prefix. It is also called the "handler" field. It can be up to 4 characters. It is desirable to make this identical to field 1 if DEV -.NAME is 4 characters or less. For the trace driver this pre-fix is "tr."
D Field 1 of the System file. This must be DEV -.NAME.
D "Special file" names listed in the Node module. These should be DEV-.NAMEO, DEV_NAMEl, etc., unless other issues, like user perception of the node name, are important. Any numbering for subdevices should match the minor device of that node. The trace driver package uses traceO which causes ID to generate
DEVICE DRIVERS 3-65
/dev /traceO on the first boot of the new Kernel.
o
Function names inside your driver. The function names must use the device prefix defined above. The trace driver uses tropenO, trcloseO, trreadO, etc.o
External variables and internal functions used inside the driver.These should use the prefix defined above or prefix followed by an underline. The trace driver uses "tr_".
2. Manually create a System entry. Go to the directory
/etc/conf/sdevice.d, and create a file of name DEV-NAME contain-ing the System information. The trace driver uses the followcontain-ing:
trace Y 1
o o o o o o o
3. Manually create an mdevice entry. Since the ID assigns block and/or character major numbers when the package is installed, your Master file is required to have zeros in fields 5 and 6. Although you could manually edit /etc/conf/C£.d/mdevice and assign block and character major numbers, the best approach is to put a file called Master in your local directory (say /tmp) and execute the command:
/etc/conf/binlid:install -a -m -k DEV_NAME
This says add (-a) a Master entry (-m). Watch out! The Master file in your local directory will be removed by the idinstall command unless you use the -k option. The trace driver uses the following:
trace oeri icc tr
o o
1 1 -1Once idinstall adds the Master entry, examine
/etc/conf/C£.d/mdevice and note the block and/or character major number.
4. Create a file in /etc/conf/node.d to tell the ID to create device special files on the next system boot. The file should be named
DEV -NAME and conform to the Node module format. For the trace driver the Node module is as follows:
3-66 ISDG
trace traceD c D
5. Create /ete/eonf/init.d, /ete/eonf/re.d, and /ete/eonf/sd.d entries if appropriate. This step can probably wait until debugging has pro-ceeded.
6. Create a directory called /ete/eonf/paek.d/DEV--NAME. Put Driver.o and Spaee.e there (if you need them).
7. At this point, it would be a good idea to make a copy of your current UNIX Operating System kernel. Execute the following:
cp .Ilmi.x .Ilmi.x.bak
8. Manually execute the /ete/eonf/bin/idbuild shell script. This will run a configuration program and try to link edit your new driver into the Kernel. You will get a "time to rebuild UNIX System" message followed either by a "UNIX System has been rebuilt" message or by error messages from the configuration program or link editor.
If you get errors, correct them and repeat the above step. If the Ker-nel was built correctly a new UNIX System image will have been created in the /etc/conf/d.d directory. You can now shut the system down and reboot. Running jete/shutdown will cause the system to enter init state 0, and the new kernel in /ete/eonf/d.d will automati-cally be linked to /unix. On the next boot, if you specify /unix on the boot: prompt, the new kernel will execute, and upon entering init state 2, the new device nodes, inittab entries, etc., will be installed.
9. When the system comes up, test your driver.
Emergency Recovery (New Kerne. Will Not Boot)
There is a possibility that the Kernel will fail to boot if your driver con-tains a serious bug. This can be due to a panicO call that you put in your driver (see the next section) or some other system problem. If this happens, you should reset your system and boot your original kernel that you hopefully saved as recommended above. To do this, reset your machine, and when you
DEVICE DRIVERS 3-67
see the Booting UNIX System ... message, quickly strike the keyboard space bar to interrupt the default boot. When the boot prompt appears, type /unix.bak or whatever you named your old kernel. If you did not save a copy of your kernel or some other disaster occurred, you can recover the sys-tem using the following emergency procedures to put a bootable /unix image back on the hard disk:
1. Insert Floppy Diskette #1 of the Base System Software Set and push the RESET button on the front panel, or power the system down and then back up again.
2. When the prompt Please press <RETURN> when ready to install the UNIX System appears, press <DEL> to exit the installation pro-gram.
You are now executing a floppy-bootable UNIX Operating System kernel. This is not a standard way to run the system. It should be used for emergency procedures only.
3. Execute the following commands:
fsck -y /dev/dsk/Os1 nount /dev/dsk/Os1 /mnt cp /unix /mnt/unix unount /dev/dsk/Os1
Remove the Floppy Diskette.
# check the hard disk
# nount the hard disk
# copy a hard disk Kernel
# lll'llIOIlIlt the hard disk
Press the RESET Button or power down and then back up again.
The system should now boot normally with a standard foundation Kernel. Your new driver and any other drivers you had installed on your system will not be included in /unix even though they may appear in the displaypkg output. This can be corrected by removing your driver and executing /etc/conf/bin/idbuild. If that fails, the packages should be removed and re-installed.
This procedure can also be useful if other system files are damaged inad-vertently while debugging your driver. There are several reasons your system may fail to boot properly or not let you log in after it has booted. For exam-ple, a corrupted password or inittab file could prevent console IOgins.
3-68 ISDG
Since Floppy Diskette #1 of the Base System Software Set software con-tains a default /etc/passwd, /etc/init, /etc/inittab and other critical files, you can copy the default file from the floppy diskette to the root file system of the hard disk using the procedures above. Obviously, user logins you have added to /etc/passwd or other system changes you have made since instal-ling the original base system will be lost when you overwrite the corrupted file with the floppy diskette default file.
DEVICE DRIVERS 3-69