Chapter 5 Device Management —— Building Device Driver

1. Chapter 5 Device Management—— Building Device Driver • Yuan Cangzhou • yuancangzhou@buaa.edu.cn

2. Outline • Driver Development Summary • Preparing for Driver Installation • Installing and Loading Drivers • Testing Drivers • Debugging Tools

3. Driver Development Steps • Write, compile, and link the new code. • Create the necessary hardware configuration files. • Copy the driver to the appropriate module directory. • Install the device driver using add_drv(1M). • Load the driver. • Test the driver. • Remove the driver if necessary.

4. Driver Code Layout • Header files (.h files) • Source files (.c files) • Optional configuration file (driver.conf file)

5. Header Files • Data structures specific to the device, such as a structure representing the device registers • Data structures defined by the driver for maintaining state information • Defined constants, such as those representing the bits of the device registers • Macros, such as those defining the static mapping between the minor device number and the instance number

6. .c Files • Contains the data declarations and the code for the entry points of the driver • Contains the #include statements that are needed by the driver • Declares extern references • Declares local data • Sets up the cb_ops and dev_ops structures

7. .c Files (Cont.) • Declares and initializes the module configuration section, that is, the modlinkage(9S) and modldrv(9S) structures • Makes any other necessary declarations • Defines the driver entry points

8. driver.conf Files • driver.conf files are required for devices that are not self-identifying. • Entries in the driver.conf file specify possible device instances that the driver can probe for existence. • driver.conf files are optional for self-identifying devices (SID)

9. Outline • Driver Development Summary • Preparing for Driver Installation • Installing and Loading Drivers • Testing Drivers • Debugging Tools

10. Steps Preceding Installation of a Driver • Compile the driver. • Create a configuration file if necessary. • Identify the driver module to the system through either of these alternatives: • Match the driver’s name to the name of the device node. • Use either add_drv(1M) or update_drv(1M) to inform the system of the module names.

11. Compiling and Linking the Driver • All of the source files are compiled and linked into a driver module • 32–bit kernel example • % cc -D_KERNEL -c xx1.c % cc -D_KERNEL -c xx2.c • % ld -r -o xx xx1.o xx2.o • 64–bit kernel example • % cc -D_KERNEL -xarch=amd64 -xmodel=kernel -c xx1.c • ld -r must be run even if only one object module exists.

12. Module Dependencies • A driver module might depend on symbols exported by another kernel module • Example • % ld -dy -r -o xx xx1.o xx2.o -N misc/mySymbol

13. Writing a Hardware Configuration File • If a device is non-self-identifying, the kernel requires a hardware configuration file for that device. • If the driver is called xx, the hardware configuration file for the driver should be called xx.conf. • On the x86 platform, device information is now supplied by the booting system. • Arbitrary properties can be defined in hardware configuration files.

14. Outline • Driver Development Summary • Preparing for Driver Installation • Installing and Loading Drivers • Testing Drivers • Debugging Tools

15. Copying the Driver to a Module Directory • Three conditions determine a device driver module’s path: • The platform that the driver runs on • The architecture for which the driver is compiled • Whether the path is needed at boot time • 32–bit driver example • # cp xx /usr/kernel/drv • # cp xx.conf /usr/kernel/drv • 64–bit driver example • # cp xx /usr/kernel/drv/sparcv9# cp xx.conf /usr/kernel/drv

16. Installing Drivers with add_drv • add_drv(1M) should not be run when installing a STREAMS module. • # add_drv xx • If the driver installs successfully,add_drv runs devfsadm(1M) to create the logical names in /dev.

17. Updating and Removing the Driver • Use the update_drv(1M) command to notify the system of any changes to an installed device driver. • By default, the system re-reads the driver.conf(4) file and reloads the driver binary module. • To remove a driver from the system, use rem_drv(1M), then delete the driver module and configuration file from the module path. • A driver cannot be used again until that driver is reinstalled with add_drv(1M). • The removal of a SCSI HBA driver requires a reboot to take effect.

18. Loading and Unloading Drivers • modload(1M) can also be used to load the driver into memory, but modload() does not call any routines in the module. • Normally, the system automatically unloads device drivers that are no longer in use. • During development, use of modunload(1M) might be necessary to unload the driver explicitly. • # modunload -i module-id • modunload takes a runtime-dependent module_id as an argument.

19. Driver Packaging • A package provides a controlled mechanism for installation and removal of all the components of a software product. • In addition to the files for using the product, the package includes control files for installing and uninstalling the application. • postinstall installation scripts • preremove installation scripts

20. Outline • Driver Development Summary • Preparing for Driver Installation • Installing and Loading Drivers • Testing Drivers • Debugging Tools

21. Testing With a Serial Connection • Using a serial connection is a saftest way to test new drivers. • Use the tip(1) command to make a serial connection between a host system and a test system. • A tip window has the following advantages: • Interactions with the test system and kernel debuggers can be monitored. • The test machine can be accessed remotely by logging into a tip host machine and using tip(1) to connect to the test machine.

22. To Set Up a Host System for a tip Connection • Connect the host system to the test machine using serial port A on both machines. • On the host system, make sure there is an entry in /etc/remote for the connection. See the remote(4) man page for details. • In a shell window on the host, run tip(1) and specify the name of the entry: • % tip debug

23. Setting Up Test Modules • The system(4) file in the /etc directory enables you to set the value of kernel variables at boot time. • Changes to kernel variables after boot are unreliable, because /etc/system is read only once when the kernel boots. • Setting Kernel Variables • set module_name:variable=value

24. Loading and Unloading Test Modules • Using the modload() Function • Use modload to force a module into memory. • Using the modinfo() Function • Use modinfo to confirm that the driver is loaded. • Using modunload() • To remove all of the currently unused modules from memory, run modunload with a module ID of 0

25. Settings to Debug • Setting the moddebug Kernel Variable • moddebugis a kernel variable that controls the module loading process. • Setting kmem_flags Debugging Flags • kmem_flags is a kernel variable used to enable debugging features in the kernel’s memory allocator.

26. Avoiding Data Loss on a Test System • Back Up Critical System Files • To be safe, make a backup copy of the root file system after the test machine is in the proper configuration. • To Boot With an Alternate Kernel • Make a copy of the drivers in /platform/* • Place the driver module in /platform/‘uname -i‘/kernel.test/drv • Boot the alternate kernel instead of the default kernel

27. Recovering the Device Directory • If either directory is damaged, you can rebuild the directory by booting the system and running fsck(1M) to repair the damaged root file system. The root file system can then be mounted. • Re-create /dev and /devices by running devfsadm(1M) and specifying the /devices directory on the mounted disk.

28. Outline • Driver Development Summary • Preparing for Driver Installation • Installing and Loading Drivers • Testing Drivers • Debugging Tools

29. Debugging Tools • kmdb(1) kernel debugger • kmdb provides typical runtime debugger facilities, such as breakpoints, watch points, and single-stepping. • mdb(1) modular debugger • mdb has limited usefulness as a real-time debugger but has rich facilities for postmortem debugging.

30. Using the kmdb Kernel Debugger • Control of kernel execution • Inspection of the kernel state • Live modifications to the code

31. Using the mdb Modular Debugger • Live operating system components • Operating system crash dumps • User processes • User process core dumps • Object files

32. Useful Debugging Tasks With kmdb and mdb • Exploring System Registers With kmdb • Detecting Kernel Memory Leaks • Writing Debugger Commands With mdb • Obtaining Kernel Data Structure Information • Obtaining Device Tree Information • Retrieving Driver Soft State Information • Modifying Kernel Variables

33. Reference • Sun Microsystems, Inc, Writing Device Drivers, January 2005 • Jim Mauro, Richard McDougall, Solaris Internals-Core Kernel Components, Sun Microsystems Press, 2000 • Sun,Multithreading in the Solaris Operating Environment, A Technical White Paper,2002 • Max Bruning, Threading Model In Solaris, Training lectures,2005 • Solaris internals and performance management, Richard McDougall, 2002

34. End • Last.first@Sun.COM