HP 9000 Networking STREAMS/UX for the HP 9000 Reference Manual HP Part No. J2237-90005 Printed in U.S.A. E0195 Edition 2 © Copyright 1995, Hewlett-Packard Company.
Legal Notices Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty.
Legal Notices under license from the Regents of the University of California. ©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc.
Printing History Printing History The manual printing date and part number indicate its current edition. The printing date will change when a new edition is printed. Minor changes may be made at reprint without changing the printing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes.
Preface Preface STREAMS/UX for the HP 9000 is Hewlett Packard's implementation of the AT&T de facto standard environment for communications protocols. STREAMS/UX consists of the STREAMS environment, Transport Layer Interface (TLI), and XTI. TLI is an industry de facto standard application program interface for implementing transport-level communications by means of STREAMS-based network protocol stacks. HP also provides a Data Link Provider Interface (DLPI) adapter with the core operating system.
Preface Chapter 4 STREAMS/UX Multiprocessor Support discusses UP emulation, writing MP scalable modules and drivers, how to port SVR4 MP modules and drivers to HP-UX, and synchronization levels. Chapter 5 How to Compile and Link STREAMS/UX Drivers, Modules, and Applications provides step-by-step instructions for each of these topics. Chapter 6 Debugging STREAMS/UX Modules and Drivers provides a detailed look at how to use the strdb and adb debugging tools to debug STREAMS modules and drivers.
Installation and Verification of STREAMS/UX 13 System Requirements 15 STREAMS/UX Filesets 16 Loading STREAMS/UX Software 17 Configuring STREAMS-based Pipes with SAM 18 Verification of Correct Installation 19 Detailed Product Information 21 Adding STREAMS Drivers and Modules 23 Manual Kernel Build Procedures 23 STREAMS Drivers and Modules 25 STREAMS Drivers 25 STREAMS Modules 25 Miscellaneous STREAMS Functionality 25 Kernel Tunable Parameters 26 STREAMS-Related Device Files (Framework-specific) 28 Difference
esballoc 41 cmn_err 42 freezestr and unfreezestr 42 get_sleep_lock 42 itimeout 43 kmem_alloc 43 LOCK 43 LOCK_ALLOC 44 putctl2 44 putnextctl2 45 qprocson and qprocsoff 45 streams_put utilities 46 SV_WAIT 46 SV_WAIT_SIG 47 TRYLOCK 48 UNLOCK 48 weldq and unweldq 48 unweldq 49 weldq 50 vtop 51 HP-UX Changes to STREAMS/UX Drivers and Modules 52 clone 53 strlog 53 sad 53 echo 54 sc 54 timod 55 tirdwr 55 Stream Head 55 pipemod 56 HP-UX Changes to STREAMS/UX Data Structures 57 Message Structures 58 msgb 58 iocblk 5
Queue Structure 59 STREAMS/UX Data Structure Restrictions 60 STREAMS/UX Uniprocessor Synchronization 61 STREAMS/UX Internal Synchronization 61 Driver and Module Synchronization 63 Multiple Processes Accessing the Same Stream 64 The STREAMS/UX Scheduler 64 HP-UX Changes to Cloning 65 STREAMS/UX Hardware Driver Writing 68 STREAMS/UX Multiprocessor Support 69 Running Modules and Drivers in Uniprocessor Emulation Mode 71 How STREAMS/UX Executes UP Emulation Modules and Drivers 71 Configuring Modules and Drivers
Compiling and Linking TLI/XTI Applications and Threads 116 Debugging STREAMS/UX Modules and Drivers 119 Introduction 120 System V Debugging Tools Supported by STREAMS/UX 121 STREAMS/UX Tracing and Logging 121 cmn_err() and printf() 121 Dump Module Example 121 strdb and adb 122 STREAMS/UX Debugging Tool 123 Running strdb 123 strdb Commands 123 STREAMS/UX Subsystem Commands 124 ? and h Commands 125 q Command 126 v Command 126 s Command 126 la Command 127 lm Command 127 ll Command 127 lp Command 128 qc Command
Generating and Retrieving System Core Dumps 171 Setting Up Your System To Save a Core Dump 171 Manually Getting a Core File from the Swap Partition 172 Problems Encountered In Saving/Obtaining a Core Dump 172 Transfer of Control In Case of System Hang 172 Core File Size Requirements 173 Symbol Information 173 Using adb 174 Invoking adb 174 Context on Entry to adb 174 Debugging Hung Systems 175 Finding the Panic Message 176 Interpreting the Panic Stack Trace 177 Manual Stack Back-Tracing 177 PA-RISC Procedur
1 Installation and Verification of STREAMS/UX 13
Installation and Verification of STREAMS/UX This chapter covers installation, configuration and verification of the STREAMS/UX subsystem for HP-UX systems, and consists of the following sections: • System requirements • STREAMS/UX filesets • Loading STREAMS/UX software • Configuring STREAMS-based pipes with the SAM program • Verification of correct installation using pdfck and strvf 14
Installation and Verification of STREAMS/UX System Requirements System Requirements STREAMS/UX is installed and configured automatically during an HP-UX 10.0 installation. STREAMS/UX does not require any dedicated hardware. Its drivers are all pseudo drivers. STREAMS/UX is supported on all HP9000 Series 700 and 800 systems that HP-UX 10.0 supports.
Installation and Verification of STREAMS/UX STREAMS/UX Filesets STREAMS/UX Filesets The HP-UX STREAMS product is organized into filesets. The filesets are organized by grouping together the files that make up the runtime environment, the kernel build components, and the manpages. • STREAMS-RUN—Contains Transport Level Interface (TLI) library, X/Open Transport Interface (XTI) library, STREAMS/UX commands and STREAMS/UX user-space header files. • STREAMS-MAN—Contains the STREAMS/UX man pages.
Installation and Verification of STREAMS/UX Loading STREAMS/UX Software Loading STREAMS/UX Software Follow the steps below to load STREAMS/UX software using the HP-UX swinstall program. 1 Insert the software media (tape or disk) into the appropriate drive. 2 Run the swinstall program using the command: /usr/sbin/swinstall 3 Enter the mount point of the drive in the Source Depot Path field, and activate the OK button to return to the Software Selection Window.
Installation and Verification of STREAMS/UX Configuring STREAMS-based Pipes with SAM Configuring STREAMS-based Pipes with SAM System Administration Manager (SAM) allows you to configure various tunable parameters. After installation is complete, all of the STREAMS/UX parameters are set to a default value and do not require any modifications. You may, however, want to change one tunable parameter. If you want to use STREAMS-based pipes, you will need to change this default value.
Installation and Verification of STREAMS/UX Verification of Correct Installation Verification of Correct Installation Follow these steps to verify that the installation is correct: 1 Run the /usr/bin/pdfck command to verify that the STREAMS/UX software was correctly installed on your system. Verification is done by checking a master product description file (pdf), which is delivered with the fileset, against the files just installed on the system.
Installation and Verification of STREAMS/UX Verification of Correct Installation If you wish, you can use the verbose (-v) option to receive information on what strvf is doing. strvf checks the following items: 20 • STREAMS kernel daemons are running. • The echo driver (a core STREAMS driver) can be opened. • a putmsg() can be performed on the echo driver. • a getmsg() receives the same message sent by putmsg(). • A STREAMS ioctl can be passed to the echo driver and acknowledged.
2 Detailed Product Information This chapter provides a more in-depth explanation of the STREAMS/UX product installation than Chapter 1. The information provided here is primarily for reference.
Detailed Product Information This chapter contains information about core STREAMS drivers and modules, lists STREAMS-related tunables, and lists STREAMS-related device files.
Detailed Product Information Adding STREAMS Drivers and Modules Adding STREAMS Drivers and Modules NOTE: The instructions below do not apply to clustered systems. If your system is attached to a cluster, follow the instructions in System Administration Tasks for Series 700 computers to configure the kernel. Alternatively, you can also create a new kernel using the SAM utility.
Detailed Product Information Adding STREAMS Drivers and Modules sad; echo; timod; tirdwr; ffs pipemod pipedev sc; 5 Make a copy of the existing kernel (default name vmunix). 6 Regenerate the kernel with mk_kernel, using the edited system file as input. mk_kernel creates the new hp-ux kernel (the default is /stand/build/vmunnix_test). There are two examples below. The first creates a new kernel in the build directory called vmunix_test.
Detailed Product Information STREAMS Drivers and Modules STREAMS Drivers and Modules The configuration of STREAMS drivers and modules is statically defined at system creation time. The STREAMS subsystem, core drivers and modules are part of every 10.0 system. The following sections contain a list of the core drivers and modules, STREAMS kernel tunable parameters, and STREAMS configuration data structure (streams_devs[ ]) information. See the master(4) manpage for more details.
Detailed Product Information Kernel Tunable Parameters Kernel Tunable Parameters The following table describes STREAMS configurable parameters that are in /usr/conf/master.d/streams file. The master file should not be modified. The values can be tuned using SAM. Default Value Tunable Name Use NSTREVENT 50 Determines the maximum number of outstanding STREAMS bufcalls allowed at any one instance.
Detailed Product Information Kernel Tunable Parameters Tunable Name NSTRSCHED Default Value 0 Use Determines the number of streams scheduler daemons (smpsched) running on a MP system. The default value is 0, which indicates that Streams will determine the number of daemons based on the number of processors in the system.
Detailed Product Information STREAMS-Related Device Files (Framework-specific) STREAMS-Related Device Files (Framework-specific) This section lists the mknod commands necessary for manually creating device files. On a properly installed STREAMS system, these commands are not necessary. This section is included for informational purposes. All device files listed here are set-up to be STREAMS cloneable.
3 Differences Between STREAMS/UX and System V Release 4 STREAMS 29
Differences Between STREAMS/UX and System V Release 4 STREAMS This chapter summarizes the differences between STREAMS/UX and System V Release 4.2 STREAMS. Chapter 4 discusses STREAMS/UX multiprocessor support and the differences between STREAMS/UX and System V Release 4 Multiprocessor STREAMS. You need to use this manual in conjunction with USL's UNIX System V Release 4.2 STREAMS Modules and Drivers and UNIX System V Release 4.2 Device Driver Reference. The USL manuals will be referred to as the SVR4.
Differences Between STREAMS/UX and System V Release 4 STREAMS Overview Overview This chapter will be divided into the following categories for describing differences between HP-UX and SVR4.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Commands HP-UX Changes to STREAMS/UX Commands STREAMS/UX supports the commands listed below: • autopush • fdetach • strace • strchg • strclean • strconf • strerr • strvf HP versions of supported STREAMS/UX commands operate somewhat differently from the way the commands are described in the UNIX SVR4.2 Command Reference manual. NLS catalogs exist for the commands. The catalogs are called autopush.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Commands strace and strerr The strace and strerr commands use the STREAMS log driver, /dev/strlog. SVR4.2 calls this driver /dev/log, but HP-UX already includes a non-streams driver named /dev/log.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls HP-UX Changes to STREAMS/UX System Calls NOTE: By default HP-UX terminal I/O is not implemented using STREAMS/UX in HP-UX 10.0. But a STREAMS-based pty is available in the STREAMS-TIO offering included in the HP-UX runtime product.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls There are HP-UX modifications to the fattach, ioctl, pipe, poll, putmsg, putpmsg, select, signal, write, and writev system calls. These modifications are as follows. fattach Modifications STREAMS/UX supports the fattach(3) and fdetach(3) library calls and the fdetach(1m) command as described in the UNIX SVR4.2 Operating System API Reference and the SVR4.2 Command Reference.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls pipes on the system will be STREAMS-based. However, fifos will not be STREAMS-based. STREAMS/UX does not support STREAMS-based fifos. The STREAMS/UX device pipedev is only for internal STREAMS/UX use in implementing STREAMS-based pipes. Opening a device file with pipedev's major number will not result in a STREAMS-based pipe, or even a properly functioning stream.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls Write Offset A module or driver can send the stream head an M_SETOPTS message, telling the STREAM head to put an offset in the beginning of the first data block in a message sent by a putmsg call. STREAMS/UX will not put the offset into the data block if the amount of memory required is greater than the page size. See Chapter 5 of the SVR4.2 STREAMS manual for more information.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls A select exception event is returned if a poll event POLLPRI or POLLRDBAND exists on the STREAM. More specifically, an exception event is returned if a high-priority message or a banded message is waiting to be read. signal Modifications STREAMS/UX supports signals and the HP-UX signal system call.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX System Calls Write Offset A module or driver can send the STREAM head an M_SETOPTS message telling it to put an offset in the beginning of each data buffer segment (i.e. message) sent by a write call. See Chapter 5 of the SVR4.2 STREAMS manual for more information. STREAMS/UX will not put the offset into a message if the resulting message size exceeds STRMSGZ.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities HP-UX Modifications to STREAMS/UX Utilities STREAMS/UX supports the following kernel utilities described in the SVR4.2 Driver manual, although some of the utilities have been modified for HP-UX.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities In addition, HP-UX provides the following new utilities. get_sleep_lock putctl2 putnextctl2 streams_put unweldq weldq The strenv.h file redefines some native HP-UX kernel utilities to conform to System V Release 4.2. The strenv.h file redefines delay, get_sleep_lock, kmem_alloc, kmem_free, lbolt, max, min, sleep, time, timeout, and untimeout.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities Uniprocessor Synchronization” in this chapter and “Writing MP Scalable Modules and Drivers” in Chapter 4 for more information about esballoc free routines. cmn_err The STREAMS/UX cmn_err is the same as the cmn_err described in the SVR4.2 Driver manual with a few differences. The HP-UX cmn_err always sends messages to both the system console and the circular kernel buffer.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities spinlocks before sleeping. Other processes cannot wakeup the open or close between the time it calls get_sleep_lock and sleep. Modules and drivers must include strenv.h to use get_sleep_lock. strenv.h redefines get_sleep_lock to streams_get_sleep_lock.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities instead of acquiring a spinlock. Whether the caller will block or spin if the lock cannot be obtained is implementation defined. The HP-UX implementation spins. LOCK_ALLOC The STREAMS/UX LOCK_ALLOC calls the native HP-UX alloc_spinlock primitive. There are some small differences between the STREAMS/UX LOCK_ALLOC and the SVR4 MP utility.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities the put routine of the specified queue. putctl2 returns 0 if the type is M_DATA, M_PROTO or M_PCPROTO, or if a message block cannot be allocated. putctl2 returns 1 if it completes successfully. putnextctl2 STREAMS/UX provides the additional utility putnextctl2. This utility can be used to send a control message with a two-byte parameter to the next queue in a stream.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities streams_put utilities STREAMS/UX provides a new utility streams_put, which allows non-STREAMS/UX software to safely call STREAMS/UX utilities. timeout and bufcall user functions and other non-STREAMS/UX code cannot call several of the STREAMS/UX utilities or share data with modules and drivers.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities MP SV_WAIT has a priority argument that specifies the priority the caller would like to run at after waking. Since the HP-UX SV_WAIT is implemented by calling sleep, the HP-UX priorities are different than the SVR4 MP ones. On HP-UX, the priority passed into SV_WAIT is subtracted from PZERO-1.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities TRYLOCK The STREAMS/UX TRYLOCK calls the native HP-UX cspinlock primitive. TRYLOCK has an interrupt priority level parameter, which is used to raise the priority level and block interrupts which acquire the spinlock. The SVR4.2 Driver manual says that implementations which do not require the interrupt level to be raised can ignore this parameter.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities unweldq The utility unweldq disconnects two drivers' queues that were joined by weldq: int unweldq (d1_wq, d2_rq, d2_wq, d1_rq, func, arg, protect_q); queue_t * queue_t * queue_t * queue_t * weld_fcn_t weld_arg_t queue_t * d1_wq; d2_rq; d2_wq; d1_rq; func; arg; protect_q; d1_wq and d1_rq are one of the driver's write and read queues. d2_wq and d2_rq are the second driver's queues.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities weldq Weldq connects two drivers' queues to form a pipe by setting the q_next pointer: int weldq (d1_wq, d2_rq, d2_wq, d1_rq, func, arg, protect_q); queue_t * queue_t * queue_t * queue_t * weld_fcn_t weld_arg_t queue_t * d1_wq; d2_rq; d2_wq; d1_rq; func; arg; protect_q; d1_wq and d1_rq are one of the drivers' write and read queues. d2_wq and d2_rq are the second driver's queues.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Modifications to STREAMS/UX Utilities vtop The STREAMS/UX vtop only accepts a NULL process structure pointer. In other words, it only converts kernel space addresses.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Drivers and Modules HP-UX Changes to STREAMS/UX Drivers and Modules The unsupported drivers and modules include: • connld • console • ports • sxt • xt NOTE: Some STREAMS-based terminal I/O functionality is contained in a separate product called STREAMS-TIO. It is part of the HP-UX runtime product.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Drivers and Modules clone Major Number: 72 clone is used to provide cloning. The major number of the device file for a cloneable driver must be the clone driver's major number, 72. The minor number is set to the real major number of the device.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Drivers and Modules High Water Mark: 2048 Low Water Mark: 128 The HP-UX sad driver device file is /dev/sad. The system administrator and users can open /dev/sad. However, only the system administrator can execute the SAD_SAP ioctl system call. This differs from the System V sad driver, which is accessed through the /dev/sad/admin and /dev/sad/user device files.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Drivers and Modules timod Module ID Number: 5006 Maximum Packet Size: INFPSZ Minimum Packet Size: 0 High Water Mark: 2048 Low Water Mark: 128 timod provides TLI functionality as described in the UNIX SVR4.2 System Files and Devices Reference manual.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Drivers and Modules The Stream head provides the interface between HP-UX system calls and STREAMS/UX utilities in the kernel. The Stream head is the first queue pair of every Stream and is involved in flow control. Data being read from a stream will be taken off the stream head.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to STREAMS/UX Data Structures HP-UX Changes to STREAMS/UX Data Structures STREAMS/UX data structures are almost identical to those described in the SVR4.2 Driver manual. STREAMS/UX places additional restrictions on how some of these structures can be accessed. STREAMS/UX data structures that differ from the descriptions in the SVR4.2 Driver manual are described below. Data structures identical to those described in the SVR4.
Differences Between STREAMS/UX and System V Release 4 STREAMS Message Structures Message Structures These structures are slightly different from the ones in the SVR4.2 Driver manual. msgb This structure is defined in the file stream.h. The msgb structure contains MSG_KERNEL_FIELDS, which defines fields used internally by STREAMS/UX. iocblk The iocblk structure is defined in stream.h. ioc_count is defined to be a member of a union. copyreq The copyreq structure is defined in stream.h.
Differences Between STREAMS/UX and System V Release 4 STREAMS Queue Structure Queue Structure The queue structure is slightly different from the one described in the SVR4.2 Driver manual. The structure is defined in the file stream.h. QUEUE_KERNEL_FIELDS defines fields used internally by STREAMS/UX.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Data Structure Restrictions STREAMS/UX Data Structure Restrictions STREAMS/UX has the same restrictions as those described in the Kernel Data Structure chapter of the SVR4.2 Driver manual. Also, STREAMS/UX limits which user written functions can access the queue structure directly. A queue's open, close, put, or service routine can manipulate the queue structure as specified by SVR4.2.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Uniprocessor Synchronization STREAMS/UX Uniprocessor Synchronization This section describes STREAMS/UX synchronization on a uniprocessor system. Chapter 4 discusses multiprocessor synchronization. Also, Chapter 4 describes how modules and drivers running on a uniprocessor system can use multiprocessor synchronization mechanisms to protect against interrupts.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Uniprocessor Synchronization than those listed above. A put or service routine can only pass its own queue's q_next field or the q_next field of the other queue in its queue pair. These requirements apply to bcanput, canput, put, putctl, putctl1, putctl2, and streams_put. These utilities are not restricted when they are passed a parameter of the form q, except that the queue must still be allocated.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Uniprocessor Synchronization 7 Drivers and modules should not call STREAMS/UX utilities from software running on the interrupt control stack processing an spl6 or higher interrupt. STREAMS/UX protects its internal data structures using spl5. Driver and Module Synchronization Drivers and modules must protect their private data structures against interrupts. This can be done in four ways.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Uniprocessor Synchronization Multiple Processes Accessing the Same Stream STREAMS/UX synchronizes multiple processes that are accessing the same stream.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to Cloning HP-UX Changes to Cloning STREAMS/UX supports two methods of cloning. See the SVR4.2 STREAMS manual for more information about cloning. Some differences exist between HP-UX cloning and SVR4.2 cloning. The first cloning method uses a special clone major number, 72, to provide cloning.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to Cloning Drivers using the second cloning method must indicate this in their install functions or master file entries. See Chapter 5 for more information about configuring STREAMS/UX drivers. Install functions must set the C_CLONESMAJOR flag.
Differences Between STREAMS/UX and System V Release 4 STREAMS HP-UX Changes to Cloning MASTER FILE ENTRY $DRIVER_INSTALL * Driver example Block major 1 Char major -1 if ((retval = install_driver(&example_drv_info, &example_drv_ops))!= 0) return(retval); /* Configure streams specific parameters.
Differences Between STREAMS/UX and System V Release 4 STREAMS STREAMS/UX Hardware Driver Writing STREAMS/UX Hardware Driver Writing STREAMS/UX does not provide all the kernel utilities needed to write a hardware driver. STREAMS/UX provides only the utilities described in this manual. Customers who need to write hardware drivers should contact their HP representative for additional support.
4 STREAMS/UX Multiprocessor Support 69
STREAMS/UX Multiprocessor Support This chapter describes how STREAMS/UX runs on a multiprocessor (MP) system. The following topics are covered: • How to run modules and drivers in uniprocessor (UP) emulation mode. • How to write MP scalable modules and drivers. • How to port SVR4 MP modules and drivers to HP-UX. • How to use MP synchronization levels on a uniprocessor system to protect against interrupts.
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode Running Modules and Drivers in Uniprocessor Emulation Mode STREAMS/UX supports uniprocessor emulation for modules and drivers. Modules and drivers which run on uniprocessor systems can run on multiprocessor systems under UP emulation without code changes.
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode emulation driver, the I/O system acquires the spl lock. Then if the interrupt handler calls put, putnext, or streams_put, STREAMS/UX usually executes the put routine on the ICS with the spl lock. Note that the STREAMS/UX utilities do not acquire the spl lock. An MP scalable interrupt handler may not be able to safely call put, putnext, or streams_put to enter a UP emulation stream.
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode MASTER FILE $DEVICE TABLE CONFIGURATION name handle type lo lmodb loinfo lmbinfo 21 40 mask block FC 0 -1 -1 char 75 -1 /* 0x10000 not set in mask */ /* 0x10000 not set in mask */ INSTALL FUNCTION CONFIGURATION LO DRIVER static drv_info_t lo_drv_info = { “lo”, “pseudo”, DRV_CHAR | DRV_PSEUDO, -1, 75, NULL, NULL, NULL, } static drv_ops_t lo_drv_ops = { NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode int lo_install() { int retval; if ((retval = install_driver(&lo_drv_info, &lo_drv_ops)) != 0) return(retval); if ((retval = str_install(&lo_str_info)) != 0) { uninstall_driver(&lo_drv_info); return(retval); } /* success */ return 0; } LMODB MODULE static streams_info_t lmodb_str_info = { /* streams information */ “lmodb”, /* name */ -1, /* major number */ { &lmodbrinit, &lmodbwinit }, /* streamtab */ STR_IS_MODULE,
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode When a module is pushed onto a stream, STREAMS/UX checks if either the module is configured for UP emulation or if the stream is running under UP emulation. If either condition is true, the module and the entire stream run under UP emulation. Also, when the module is popped, the stream does not change back to its original mode.
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode mode. Another example is STREAMS/UX pipes, which are MP scalable. If UP emulation modules are pushed onto a pipe, the pipe runs under UP emulation. • As described earlier in this section, all user bufcall callback functions are executed in UP emulation mode. If an MP scalable module calls bufcall, the callback routine runs under UP emulation.
STREAMS/UX Multiprocessor Support Running Modules and Drivers in Uniprocessor Emulation Mode module which can run in UP emulation mode is timod. Although timod will be configured to be MP scalable, it is pushed onto many streams, some of which run in UP emulation mode. • Do not push a UP emulation module onto an MP scalable upper mux. Do not link a UP emulation driver under an MP scalable upper mux.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers Writing MP Scalable Modules and Drivers Overview of STREAMS/UX MP Support HP-UX STREAMS supports MP scalable drivers and modules. You can configure the amount of parallelism for modules and drivers. Pick a level which is consistent with a module's or driver's use of shared data structures. STREAMS/UX provides five levels of parallelism which are called queue, queue pair, module, elsewhere, and global. They are described below.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers Read Queue Write Queue Stream Head Echo echo_rput echo_rsrv echo_wput echo_wsrv Echo ECHO-A Read Queue echo_rput echo_rsrv echo_wput echo_wsrv Read Queue Write Queue sad_rput sad_rsrv sad_wput sad_wsrv Stream Head dlpi_rput dlpi_rsrv dlpi_wput dlpi_wsrv Sad DLPI-A Figure 1 Write Queue ECHO-B Write Queue Stream Head Dlpi Read Queue Stream Head SAD-A Understanding STREAMS/UX MP Support The queue synchronizat
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers different queue pairs run in parallel. (A queue pair is also known as a module instance.) For example, assume that the echo driver in Figure 1 is configured for queue pair synchronization. STREAMS/UX runs ECHO-A's echo_rput, echo_rsrv, echo_wput, and echo_wsrv one at a time.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers and sad drivers use global synchronization. Only one driver function in ECHO-A, ECHO-B, DLPI-A and SAD-A can run at a time. However, one of these drivers could run in parallel with a module configured for a synchronization level other than global. All modules configured with global synchronization can share data. The STREAMS/UX synchronization levels also apply to open and close.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers the same group. They can all share data. However, STREAMS/UX will not synchronize bufcall and timeout callback functions or any non-STREAMS/UX code with the modules or drivers. You may be able to use the streams_put utility described in Chapter 3. In general, UP emulation provides more protection for bufcall, timeout, and non-STREAMS functions.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers The sync name indicates which modules and drivers belong to a group. Choose a sync name with eight characters or less, and configure the name for each member of the group. See Chapter 5 for more information about configuring STREAMS/UX modules and drivers. Master File $DEVICE Table Configuration To configure an MP scalable module or driver using a master file $DEVICE table entry, add the 0x10000 (MGR_IS_MP) flag to the mask value.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers drv_info_t structure. Specify a synchronization level in the inst_sync_level field. The possible values are SQLVL_GLOBAL, SQLVL_ELSEWHERE, SQLVL_MODULE, SQLVL_QUEUEPAIR and SQLVL_QUEUE. If the module or driver is using the elsewhere synchronization level, add a sync name to the inst_sync_info field. Note that a module or driver which uses an install function for configuration needs an entry in the master file $DRIVER_INSTALL table.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers int strlog_install() { int retval; if ((retval = install_driver(&strlog_drv_info, &strlog_drv_ops)) != 0) return(retval); if ((retval = str_install(&strlog_str_info)) != 0) { uninstall_driver(&strlog_drv_info); return(retval); } /* success */ return 0; TIRDWR MODULE static streams_info_t tirdwr_str_info = { /* streams information */ “tirdwr”, /* name */ -1, /* major number */ { &rinit, &winit, NULL, NULL }, /* streamtab */ STR_IS_MOD
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers int C_install() { int retval; return(str_install(&c_str_info)); } D DRIVER static drv_info_t d_drv_info = { “D”, “pseudo”, DRV_CHAR | DRV_PSEUDO | DRV_MP_SAFE, -1, -1, NULL, NULL, NULL, /* driver information */ /* name */ /* class */ /* *****NOTE***** DRV_MP_SAFE flag specified */ /* block major number */ /* dynamically assigned character major number */ /* cdio, gio_private, and cdio_private structures */ } static drv_ops_t d_drv_
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers int D_install() { int retval; /* Configure driver and obtain dynamically assigned major number. */ if ((retval = install_driver(&d_drv_info, &d_drv_ops)) != 0) return(retval); /* Configure streams specific parameters.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers and service routines cannot block. This means, for example, that modules and drivers which run over a UP emulation hardware driver must run under UP emulation. • Modules and drivers which can run both MP scalable and under UP emulation must use queue or queue pair synchronization. An example of an MP scalable module which can run in UP emulation mode is timod.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers structures with STREAMS/UX modules and drivers, unless spinlocks are used to protect critical sections. Also, the code cannot call the following utilities: backq, bcanputnext, canputnext, flushband, flushq, freezestr, getq, insq, putbq, putnext, putnextctl, putnextctl1, putnextctl2, qreply, qsize, rmvq, SAMESTR, strqget, strqset, and unfreezestr.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers spinlocks when calling some STREAMS/UX utilities. See Table 1 at the end of this chapter for more information. See the SVR4.2 Driver manual for more information about SVR4 MP hierarchies. • To reduce contention and improve performance, you should minimize the amount of time that modules and drivers hold spinlocks.
STREAMS/UX Multiprocessor Support Writing MP Scalable Modules and Drivers No matter which utility is used to pass messages across the mux, you must make sure that the queues passed to the utilities are still allocated. You may also want to check that the driver is still linked under the mux. • Follow the design guidelines in the SVR4.2 STREAMS manual.
STREAMS/UX Multiprocessor Support Porting SVR4 MP Modules and Drivers to HP-UX Porting SVR4 MP Modules and Drivers to HP-UX Please read the previous section, “Writing MP Scalable Modules and Drivers,” before this one. If you compare the previous section to the SVR4.2 STREAMS manual, you will notice that there are some differences between SVR4 MP STREAMS and HP-UX MP STREAMS. This section discusses these differences and describes strategies for porting SVR4 MP modules and drivers to HP-UX.
STREAMS/UX Multiprocessor Support Porting SVR4 MP Modules and Drivers to HP-UX Strategies for Porting SVR4 MP Modules and Drivers to HP-UX The best way to port SVR4 MP scalable modules and drivers to HP-UX is to change the SVR4 MP code to use the STREAMS/UX synchronization levels. First, analyze how the SVR4 MP code shares data structures, and then configure the modules and drivers to use synchronization levels which correctly serialize access to shared data.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor MP Synchronization Levels on a Uniprocessor This section describes how modules and drivers can use MP synchronization levels on a uniprocessor system to protect their private data structures against interrupts. Please read “Writing MP Scalable Modules and Drivers” in this chapter and “STREAMS/UX Uniprocessor Synchronization” in Chapter 3 before reading this section.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor You can configure modules and drivers to use a particular synchronization level whether or not they are MP scalable, run under UP emulation, or only run on a uniprocessor system. The section “Configuring MP Scalable Modules and Drivers” in this chapter shows examples of configuring MP scalable modules and drivers to use synchronization levels.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor INSTALL FUNCTION CONFIGURATION B MODULE static streams_info_t b_str_info = { /* streams information */ “B”, /* name */ -1, /* major number */ { &brinit, &bwinit, NULL, NULL }, /* streamtab */ STR_IS_MODULE | STR_SYSV4_OPEN, /* *****NOTE***** MGR_IS_MP not specified */ SQLVL_MODULE, “”, /* *****NOTE***** synch level specified */ /* sync name */ } int B_install() { int retval; return(str_install(&b_str_info)); } D DRIVER static d
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor static streams_info_t d_str_info = { /* streams information */ “D”, /* name */ -1, /* dynamically assigned major number */ { &drinit, &dwinit, NULL, NULL}, /* streamtab */ STR_IS_DEVICE | STR_SYSV4_OPEN, /* *****NOTE***** MGR_IS_MP flag not specified */ SQLVL_ELSEWHERE, /* *****NOTE***** synch level specified*/ “netsync”, /* *****NOTE***** sync name specified */ } int D_install() { int retval; /* Configure driver and obtain dynam
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor The following table indicates if spinlocks can be held across calls to different STREAMS/UX utilities. Also, it specifies if the SVR4 MP STREAMS/UX utilities have the same restrictions. Table 1 Holding Module or Driver Defined Spinlocks While Calling Utilities Utility Spinlocks Can Be Held Across Call? Differs From SVR4 MP? adjmsg Yes No allocb Yes, if use STREAMS/UX user lock orders.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor Table 1 Holding Module or Driver Defined Spinlocks While Calling Utilities Utility Spinlocks Can Be Held Across Call? Differs From SVR4 MP? esballoc Yes, if use STREAMS/UX user lock orders. No esbbcall Yes, if use STREAMS/UX user lock orders. No flushband Yes, if use STREAMS/UX user lock orders (flushband may call user esballoc free routines).
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor Table 1 Holding Module or Driver Defined Spinlocks While Calling Utilities Utility Spinlocks Can Be Held Across Call? Differs From SVR4 MP? LOCK_ALLOC No Yes LOCK_DEALLOC Yes, if use STREAMS/UX user lock orders. No major Yes No makedev Yes No makedevice Yes No max Yes No min Yes No minor Yes No msgdsize Yes No msgpullup Yes, if use STREAMS/UX user lock orders.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor Table 1 Holding Module or Driver Defined Spinlocks While Calling Utilities Utility Spinlocks Can Be Held Across Call? Differs From SVR4 MP? putnextctl2 No No putq Yes, if use STREAMS/UX user lock orders, and does not pass driver’s read queue or lower mux’s write queue. Yes qenable Yes, if use STREAMS/UX user lock orders.
STREAMS/UX Multiprocessor Support MP Synchronization Levels on a Uniprocessor Table 1 Holding Module or Driver Defined Spinlocks While Calling Utilities Utility Spinlocks Can Be Held Across Call? Differs From SVR4 MP? SV_BROADCAST Yes, if use STREAMS/UX user lock orders. No SV_DEALLOC Yes, if use STREAMS/UX user lock orders. No SV_WAIT No, except for lkp parameter lock. No SV_WAIT_SIG No, except for lkp parameter lock. No testb Yes, if use STREAMS/UX user lock orders.
5 How to Compile and Link STREAMS/UX Drivers, Modules, and Applications 103
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications This chapter describes how STREAMS/UX drivers and modules can be added to the HP-UX kernel, and how STREAMS/UX TLI and XTI applications can be compiled and linked.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling STREAMS/UX Drivers and Modules Compiling STREAMS/UX Drivers and Modules The steps for compiling STREAMS/UX drivers and modules follow. 1 Table 2 Include the appropriate STREAMS/UX include files in the driver and module sources. Table 2 describes the files. Drivers and modules are compiled in the /usr/conf directory. They contain include statements with relative path names. The table shows the path names.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling STREAMS/UX Drivers and Modules Compile each of your modules and archive the object files into a library using the ar command. It is best to place all of your driver and module code into the same library. In the example below, libexample1.a is the name of the library and obj*.o are the object files: rm -f libexample1.a ar -r libexample1.a 106 ojb1.o obj2.o ... objn.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel Linking STREAMS/UX Drivers and Modules into the Kernel Linking STREAMS/UX drivers and modules into the kernel is a multi-step process. A summary of the steps is: 1 Create or modify your master file to reflect changes. 2 Add a driver header with the information previously located in the /etc/master file into the etc/master.d directory.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel For a STREAMS driver, your driver install routine will need to call both the function install_driver (CDIO3) and str_install(). And for a STREAMS module, your driver install routine will only need to call the str_install() routine. The call to install_driver() initializes the cdevsw entry points and d_flags for your STREAMS driver.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel An example of these declarations using the STREAMS test driver, “tlo” is as follows: (The STREAMS tlo test driver is used only as an example throughout this section. Please tailor this example to your specific driver configuration).
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel The definitions of the streams_flags used in the streams_info_t structure are (see stream.h and conf.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel assigned “dynamic” major number by running the lsdev(1) command after the system has rebooted with the kernel that includes your driver. There are details later in this section on lsdev(1).
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel Illustrated below is an example of the driver install routine required for a STREAMS module, using the example lmodb module. int lmodb_install() { int retval; if ((retval = str_install (&lmodb_str_info)) != 0) { return (retval); } return 0; /* return success */ }; Modifying Your Master File In 10.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel An example $DRIVER_INSTALL section from the STREAMS/UX master file is as follows: $DRIVER_INSTALL ************************************************************************* * Driver install table * * This table contains the name of drivers which have converged I/O header * structures and install entry points. Drivers in this table should not * be defined in the driver table above.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Linking STREAMS/UX Drivers and Modules into the Kernel For more details on driver headers and driver install routines, please read the HP-UX Driver Development Guide (P/N 98577-90000-E1). Dynamically-Assigned Major Numbers and lsdev(1) When using the dynamic major number facility, you will need to determine which major number was assigned to your driver during bootup, by consulting lsdev(1).
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling and Linking STREAMS/UX Applications Compiling and Linking STREAMS/UX Applications Follow these steps for compiling and linking STREAMS/UX applications: 1 Table 3 Include the appropriate header files. The following header files may be found in /usr/include or /usr/include/sys. Those found in /usr/include are pointers to the files found in /usr/include/sys.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling and Linking TLI/XTI Applications and Threads Compiling and Linking TLI/XTI Applications and Threads As with the STREAMS/UX system calls, compiling and linking a TLI or XTI application requires no special compile or linking options. Choose the appropriate include files from the table below and compile. Link your application with either the TLI library, libnsl_s.a or libnsl_s.sl, or the XTI library, libxti.a or libxti.sl.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling and Linking TLI/XTI Applications and Threads recommended that for loopback applications, the sending and receiving threads be in separate processes which will avoid any deadlock situation. NOTE: The libraries use two levels of internal locks and it is only during the small time frame between obtaining and releasing the locks that a deadlock can occur. • The libcma.a or libcma.
How to Compile and Link STREAMS/UX Drivers, Modules, and Applications Compiling and Linking TLI/XTI Applications and Threads • If using condition variables, a pthread_cond_signal() must be sent for each thread waiting on that condition. Condition variables are useful for synchronizing activity on a single endpoint where multiple threads may be attempting to manipulate that endpoint. Another use is coordinating multiple endpoints that need to arrive at a particular state before proceeding.
6 Debugging STREAMS/UX Modules and Drivers 119
Debugging STREAMS/UX Modules and Drivers Introduction Introduction This chapter describes tools for debugging STREAMS/UX modules and drivers. STREAMS/UX supports many System V tools, and provides new ones. This chapter contains the following: • An overview of the System V tools supported by HP-UX. • A description of a new tool, strdb, that displays STREAMS/UX data structures in running systems and HP-UX core dumps.
Debugging STREAMS/UX Modules and Drivers System V Debugging Tools Supported by STREAMS/UX System V Debugging Tools Supported by STREAMS/UX STREAMS/UX supports many of the System V STREAMS debugging tools. Refer to Appendix D in the SVR4PG manual for a description of the System V tools. STREAMS/UX Tracing and Logging STREAMS/UX supports tracing and logging. See Appendix D and the strace(1M), strclean(1M), strerr(1M), and log(7) man pages in the SVR4PG manual for more information about these tools.
Debugging STREAMS/UX Modules and Drivers System V Debugging Tools Supported by STREAMS/UX strdb and adb STREAMS/UX provides strdb for debugging. strdb can be used with the HP-UX crash and adb tools for debugging.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool STREAMS/UX Debugging Tool HP-UX provides the strdb tool for examining STREAMS/UX data structures in the kernel. strdb is an interactive tool. You run the strdb program, and then enter commands to see data structures. This section describes strdb commands and shows examples of using strdb to find STREAMS/UX driver problems. The strdb man page summarizes strdb commands.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Primary mode commands change the characteristics of the strdb session. For example, one command turns on logging to a file. Primary mode commands also allow you to navigate through STREAMS/UX data structures. When strdb starts up, you are in primary mode. You switch to STREAMS/UX subsystem mode by entering the :S command. STREAMS/UX subsystem mode commands report what STREAMS/UX are configured and active on the system.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q - quit the STREAMS subsystem commands qc 'driver' 'file' - print 'driver' read / write side qcount to 'file' qh 'name' 'minor' - display STREAM head queue structure for device 'name' and minor number 'minor' s [m | d] - Option d lists all the STREAMS drivers configured in the system.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q Command Enter the q command to exit STREAMS/UX subsystem mode and enter primary mode. This is shown below. q No current structure S:0 v Command Enter the v command to display the version of STREAMS/UX data structures. This version should always be Release V 4.0. An example is shown below. v STREAMS Version based on Release V 4.0 s Command Enter the s [m|d] command to see the STREAMS/UX modules and drivers configured into the system.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool loop sp test_wel MAJOR = 114 MAJOR = 115 MAJOR = 130 la Command Enter the la command to see a list of opened streams for a driver. Also, enter the name of the driver. This name can be obtained from s command output. An example is shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool lp Command Enter the lp command to see a list of drivers persistently linked under a multiplexor. You must enter the multiplexor name and the minor number. An example is shown below. lp tmx 1 lo MAJOR = lo MAJOR = lo MAJOR = 75 minor = 2 75 minor = 1 75 minor = 0 qc Command Enter the qc command to display the q_count field of a driver's read and write queues.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool qh Command Enter the qh command to see a stream head read queue. Enter the driver name and minor number to specify the stream head read queue to display. An example is shown below. When strdb prints the stream head read queue, you are put in primary mode. This lets you enter navigation commands to look at data structures pointed to by fields in the queue. These navigation commands are described below under “Primary Commands.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool prints the commands for formatting these fields. A carriage return will clear the help screen and redisplay the stream head read queue. In the example below, the m key is entered to see the message block pointed to by q_first. Next, a ? is entered to see which message block fields strdb can format.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_flag QUSE QOLD QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = 0x1120 = 0 = -1 = 0x200 = 0x100 = 0x0 = 0 = 00 = 00 m struct msgb 0x2156780 b_next b_prev b_cont b_rptr b_wptr b_datap b_band b_pad1 b_flag b_pad2 S:2 = 0x204ac00 = 0x0 = 0x21fb700 = 0x2242bf2 = 0x2242bf2 = 0x0 = 0 = 00 = 0x0 = 0 ? navigation 'n' = 'p' = 'm' = 'c' = 'd' = for structure msgb b_next (msgb) b_prev (msgb) b_rptr (b_rptr) b_co
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Qinit Navigation 'i' 's' = qi_minfo (module_info) = qi_mstat (module_stat) Message Block Navigation 'n' 'p' 'm' 'c' 'd' = = = = = b_next (msgb) b_prev (msgb) b_rptr (b_rptr) b_cont (msgb) b_datap (datab) Data Block Navigation 'd' = db_f (a__datab) Queue Band Navigation 'n' 'f' 'l' = qb_next (qband) = qb_first (msgb) = qb_last (msgb) The following information includes more navigation command examples.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_pad1[1] = 00 ? navigation 'i' = 'm' = 'z' = 'n' = 'l' = 'b' = 'o' = for structure queue q_qinfo (qinit) q_first (msgb) q_last (msgb) q_next (queue) q_link (queue) q_bandp (qband) q_other (queue) -- Hit any key to continue -- After typing a key to continue, you can enter any of the keys shown in the help text. For example, if you enter o, the stream head write queue will be displayed. This is shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_qinfo q_first q_last q_next q_link q_ptr q_count q_flag QUSE QOLD QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = = = = = = = = 0x1f7924 0x2156780 0x2185800 0x0 0x0 0x0029cc48 22518 0x1120 q_pad1[2] = 00 q_other = 0x21f7600 = 0 = -1 = 0x8000 = 0x4000 = 0x0 = 0 = 00 = 00 This queue contains a non-zero q_first pointer. The m navigation key can be used to look at the messages on the queue.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool n struct msgb 0x204ac00 b_next b_prev b_cont b_rptr b_wptr b_datap b_band b_pad1 b_flag b_pad2 S:5 = 0x21f4b00 = 0x218ee00 = 0x2198080 = 0x223dc00 = 0x223ddc3 = 0x204ac40 = 0 = 00 = 0x0 = 0 The m key shows the data associated with this message block. m struct msgb 0x204ac00 Message data at 0x0223dc00 0x0223dc00 : 01491800 76777879 .I..
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool At this point, you may want to see the next message in the queue. To do this, enter a key other than c to stop examining data. Then you can enter the primary mode command CTRL-P to pop the message data and get back to the message block for the data. This is shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool after strdb displayed the write queue below the stream head write queue. Then in the current example, CTRL-U could be entered to pop back to this queue. This is shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = 0 = -1 = 0x8000 = 0x4000 = 0x0 = 0 = 00 = 00 You may want to use CTRL-R when you are entering navigation commands, not just when you pop the data structure stack. This is because strdb does not automatically update the display when the contents of data structures change. You need to enter the CTRL-R command to update the display with new values from /dev/kmem.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool :x ? known data structure descriptions... streamtab msgb a__datab datab free_rtn queue qband qinit module_info module_stat strapush ioc_pad iocblk copyreq copyresp stroptions -- Hit any key to continue -- The type for a STREAMS/UX queue is queue. You can double check which type to use by looking in the include file . An example of entering the :x command to format the queue is shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Commands to Change strdb Session Characteristics After entering strdb, you can enter the :? command to get information about primary commands. Note that primary mode does not prompt for commands; you just enter the command keys.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Enter the :? command to see the help menu for primary mode. strdb prints the text shown below.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool 'name' and minor number 'minor' - list all modules pushed on STREAMS device 'name' and whose minor number is 'minor' lp 'name' 'minor' - list all drivers persistently linked under the STREAMS device 'name' and minor number 'minor' q - quit the STREAMS subsystem commands qc 'driver' 'file' - print 'driver' read / write side qcount to file qh 'name' 'minor' - display STREAM head queue structure for device 'name' and minor number 'minor' s [m
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool You can disable data structure stacking by entering the :u command. When data structure stacking is disabled, strdb does not display the stack depth. Data structure stacking is re-enabled by entering the :s command. An example is shown below. Note how the stack depth displayed in the upper right hand corner of the screen changes.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_pad1[0] q_pad1[1] = 00 = 00 o struct queue 0x21f7b74 q_qinfo q_first q_last q_next q_link q_ptr q_count q_flag QNOENB QWANTR QUSE QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = = = = = = = = 0x1f7a34 0x0 0x0 0x21f7674 0x0 0x21f7a00 0 0x102a q_pad1[2] = 00 q_other = 0x21f7b00 = 0 = -1 = 0x2800 = 0x400 = 0x0 = 0 = 00 = 00 :s struct queue 0x21f7b74 q_qinfo q_first q_last q_next q_link q_ptr q_count q_fl
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Enter the :S command to switch from primary mode to STREAMS/UX subsystem mode. After invoking strdb, you are in primary mode. Enter :S to switch to STREAMS/UX subsystem mode. In STREAMS/UX subsystem mode, you can see which STREAMS/UX are configured and active on the system. An example is shown below. strdb No current structure S:0 :S STREAMS subsystem help commands..
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Example 1: Flow Control and Fragmentation In this example, the user has written a loopback driver which uses the qreply STREAMS/UX utility to send all incoming messages up to the stream head read queue.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool if (fd < 0) printf(“Open returned %d and errno = %d.\n”, n, errno); /* Fill buffer with data to write */ for (n = 0; n < 1024; n++) wbuf[n] = (char) n; printf(“Call write with nbytes set to 1024.\n”); n = write(fd, wbuf, 1024); if (n != 1024) printf(“Write returned %d and errno = %d.\n”, n, errno); printf(“Call read to read in the message sent down stream.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool 'name' and minor number 'minor' 'name' 'minor' - list all modules pushed on STREAMS device 'name' and whose minor number is 'minor' lp 'name' 'minor' - list all drivers persistently linked under the STREAMS device 'name' and minor number 'minor' q - quit the STREAMS subsystem commands qc 'driver' 'file' - print 'driver' read / write side qcount to file qh 'name' 'minor' - display STREAM head queue structure for device 'name' and minor numbe
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = 0x200 = 0x100 = 0x0 = 0 = 00 = 00 The user notes that q_count, the number of bytes of data on the queue, is 512. This is the amount of data the test program was able to read. The user realizes that the test program could only read 512 bytes, because that is all that was in the queue.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool QFULL QUSE QOLD QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = 0 = 256 = 0x200 = 0x100 = 0x0 = 0 = 00 = 00 The user sees that the rest of the data is on this queue. The user wonders why the lo driver did not put this data on the stream head write queue. The user enters the CTRL-P command to go back to the stream head read queue.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool q_flag QREADR QFULL QWANTR QWANTW QUSE QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = 0x103d = 0 = -1 = 0x200 = 0x100 = 0x0 = 0 = 00 = 00 The user notices that the QFULL flag is set. This indicates that the queue is flow controlled. q_hiwat is set to 0x200 (512 decimal).
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool The user notes that there are 256 bytes in this message (b_wptr - b_rptr = 256). The user looks at the next message by entering the n key. n struct msgb 0x513780 b_next b_prev b_cont b_rptr b_wptr b_datap b_band b_pad1 b_flag b_pad2 S:3 = 0x0 = 0x50da00 = 0x0 = 0x4efc00 = 0x4efd00 = 0x5137c0 = 0 = 00 = 0x0 = 0 This message also contains 256 bytes. The user enters navigation commands to view lo's write queue.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool Example 2: Simple Driver Programming Error In this example, the user has written a loopback driver, sp, which uses timeout to simulate interrupts. sp's put routine calls timeout for each message it receives. When the timeout expires, HP-UX calls sp's timeout function. This function calls putq() to put the message on sp's read queue. Stream Head sp driver Read Queue Read Queue Write Queue Write Queue sp_put sets timeout . . later .
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool struct sp { unsigned sp_state; queue_t mblk_t mblk_t /* Set to SPOPEN when driver opened. */ /* Cleared when driver is closed. */ *sp_rdq; /* Contains sp's read q pointer. */ *first_mp; /* Pointer to head of message list. */ /* Messages are saved here until */ /* timeout expires. */ *last_mp; /* Pointer to tail of message list. */ }; /* Driver state values.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool static sp_timeout(private) struct sp *private; { mblk_t *temp; unsigned int s; /* Make sure driver isn't being closed. */ if ((private->sp_state & SPOPEN) && (private->first_mp)) { /* Take message off head of queue in private data structure. */ temp = private->first_mp; private->first_mp = private->first_mp->b_next; temp->b_next = NULL; /* Call putq to put message on sp's read queue and send it upstream.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool all the modules configured in the system - print version of STREAMS structures v displayed Then the user enters the la command for sp to see what minor number the driver assigned to the stream. la sp stack empty sp MAJOR = 115 ACTIVE Minor 0x000000 S:0 Stream head RQ = 0x005c1500 -- Hit any key to continue -- Next, the user enters the qh command for sp and minor number 0 to start examining the stream.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool o struct queue 0x5c1574 q_qinfo q_first q_last q_next q_link q_ptr q_count q_flag QNOENB QWANTR QUSE QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = = = = = = = = 0x29650c 0x0 0x0 0x605e74 0x0 0x5f0100 0 0x102a S:2 q_pad1[2] = 00 q_other = 0x5c1500 = 0 = -1 = 0x2800 = 0x400 = 0x0 = 0 = 00 = 00 The user looks at the next queue, sp's write queue, by entering the n key.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool o struct queue 0x605e00 q_qinfo q_first q_last q_next q_link q_ptr q_count q_flag QREADR QWANTR QUSE QOLD QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband q_pad1[0] q_pad1[1] = = = = = = = = S:5 0x296418 0x0 0x0 0x5c1500 0x0 0x29ec48 0 0x1129 q_pad1[2] = 00 q_other = 0x605e74 = 0 = 256 = 0x8000 = 0x4000 = 0x53b3c0 = 1 = 00 = 00 The user sees that there are no messages on the stream.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool address. As shown above, strdb also reports that sp's read queue address is 0x00605e00. The next two words are pointers to messages being saved until timeouts expire. The first word is the head of the message queue. Its value is 0x00000000. The second word is the tail. Its value is 0x005fb600. The user does not understand how the head of the list can be 0 and the tail non-zero.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool The user wonders if this is a valid message block. The fields seem to contain correct values. The user checks the data by entering the m key.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool b_wptr b_datap b_band b_pad1 b_flag b_pad2 = 0x599b36 = 0x5fb740 = 0 = 00 = 0x0 = 0 Again, the values in this message block appear valid. The user double checks the data by entering the m key.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool The user changes sp_timeout() to check if the list is empty, and sets private->last_mp to 0 if it is. The corrected function is shown below. static sp_timeout(private) struct sp *private; { mblk_t *temp; unsigned int s; /* Make sure driver isn't being closed. */ if ((private->sp_state & SPOPEN) && (private->first_mp)) { /* Take message off head of queue in private data structure.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool } /* while */ Get Process /* Initialize the stream and poll structures */ for (i=0; i
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool s [m | d] - Option d lists all the STREAMS drivers configured in the system. Option m lists all the modules configured in the system - print version of STREAMS structures displayed v Then the user enters the la command for lo to see what minor number the driver assigned to the stream.
Debugging STREAMS/UX Modules and Drivers STREAMS/UX Debugging Tool The user goes back to the code for the get process to see if poll() is being called incorrectly. The user checks the parameters passed to poll(). The user sees that the initialization code set revents instead of events before calling poll(). poll() returns 0 in the revents field because no events were requested. The corrected code fragment is shown below.
Debugging STREAMS/UX Modules and Drivers HP-UX Kernel Debugging Tools HP-UX Kernel Debugging Tools This section describes the HP-UX kernel debugging tools and techniques available for HP-UX release 10.0. These tools and techniques may change from release to release. This manual will focus primarily on the Series 700 and 800 debugging tools and techniques. Sources of additional information for the Series 700 are cited below. Kernel level debugging is associated with the hardware that a kernel is running on.
Debugging STREAMS/UX Modules and Drivers HP-UX Kernel Debugging Tools • PA-RISC Procedure Calling Conventions Reference Manual, part number 09740-90015 167
Debugging STREAMS/UX Modules and Drivers HP-UX Kernel Debugging Tools and strdb HP-UX Kernel Debugging Tools and strdb The strdb tool can be used in conjunction with other standard HP-UX kernel debugging tools to provide STREAMS/UX-specific information and data formatting. Generally, if your system is running normally except for STREAMS/UX, it is recommended that you use strdb to debug the problem.
Debugging STREAMS/UX Modules and Drivers HP-UX Kernel Debugging Tools and strdb The third is the occurrence of a High Priority Machine Check (HPMC), which usually indicates a hardware problem. An HPMC is characterized by a total, sudden system halt and an HPMC “tombstone” printed on the console, which records the contents of the system's registers. If you encounter an HPMC, contact your HP service representative.
Debugging STREAMS/UX Modules and Drivers HP-UX Kernel Debugging Tools and strdb trap type 6 pcsq.pcoq = 0.0 isr.ior = 4.78 @(#)9245XA HP-UX (A.10.00) #0: Sat Aug 13 23:17:54 PDT 1994 panic: (display==0xbf00, flags==0x0) Instruction page fault The pcsq.pcoq pair is important; the user attempted to jump to page zero and start executing. In this case, because the fault was an instruction page fault, the isr.ior pair is meaningless.
Debugging STREAMS/UX Modules and Drivers Generating and Retrieving System Core Dumps Generating and Retrieving System Core Dumps HP-UX will attempt to create a snapshot of physical memory and register contents before it stops running. This snapshot can assist engineers in determining the cause of the problem because it holds a record of what the system was doing at the time it crashed. The correct name for this snapshot is a core dump.
Debugging STREAMS/UX Modules and Drivers Generating and Retrieving System Core Dumps Manually Getting a Core File from the Swap Partition If savecore() was not run at boot-up, or did not succeed, you can still run savecore(1m) manually by taking the following steps: /usr/bin/bdf # find enough space for the dump mkdir /tmp/syscore # assuming /tmp has enough space /usr/sbin/savecore /tmp/syscore # savecore to the chosen directory savecore begins by reporting the date and time of the crash.
Debugging STREAMS/UX Modules and Drivers Generating and Retrieving System Core Dumps type a “Control b” on the console. This will put your console under the supervision of the access port. You will get a “CM>” prompt, at which you may type “TC.” • Series 800 Models 834/5, 845, and 8x2 have a key-operated TOC mechanism. To execute a TOC, turn the key all the way to the right (clockwise). • Series 800 Models 808 and 815 have a button-operated TOC mechanism.
Debugging STREAMS/UX Modules and Drivers Using adb Using adb This section describes how to use adb on core dumps obtained following a system crash. See “Generating and Retrieving System Core Dumps” for information on how these dumps are obtained. adb can also be used to examine a system that is currently running. See the adb(1) man page or ADB Tutorial for more information. Invoking adb When using adb on a system core dump, you must use the “-k” option.
Debugging STREAMS/UX Modules and Drivers Using adb occurred will be described later. These “panic time” register values enable the user to examine the context of the process that was running at the time of the system crash. Debugging Hung Systems If the system core dump is from a transfer of control (TOC) of a hung system, adb will be unable to determine the “dump time” or “panic time” register values.
Debugging STREAMS/UX Modules and Drivers Using adb Symptom Explanation You cannot ping your system. Your system may not be hung, its networking software state may be deadlocked in some way. If you have a terminal session that is working, use strdb and adb to look at the kernel and the STREAMS/UX subsystem state. Carriage returns do not echo on the console or on other login sessions. Your system is hung, but is probably TOC-able. TOC the system and examine the kernel globals in the dump.
Debugging STREAMS/UX Modules and Drivers Using adb Interpreting the Panic Stack Trace adb can be used to translate the hexadecimal stack trace printed after the panic message into procedure addresses. For each hexadecimal number in the stack trace, use the adb i command to determine where in the kernel the address occurs.
Debugging STREAMS/UX Modules and Drivers Using adb PA-RISC Procedure Calling Conventions Overview The following is a very brief overview of the PA-RISC procedure calling convention. More information can be obtained from the PA-RISC Procedure Calling Conventions Reference Manual. PA-RISC machines have 32 general use registers.
Debugging STREAMS/UX Modules and Drivers Using adb The only registers you need to be concerned with for manual stack back-tracing are r2 (rp) and r30 (sp), although the other registers become important when trying to determine what arguments a procedure in the trace was called with. In order to implement these register roles, at the start of each procedure a stack frame is allocated and callee save registers which the called procedure is planning to modify are stored in the stack frame.
Debugging STREAMS/UX Modules and Drivers Using adb Basic Stack Back-Tracing Given the stack pointer, sp, and the current instruction address, pcoqh, it is possible to get the previous stack pointer and instruction address. The starting values for sp and pcoqh are obtained from the adb $r command. As mentioned above, when adb is invoked on a system core with the -k option, it sets these registers to the values of the machine registers at the time the system core dump was taken.
Debugging STREAMS/UX Modules and Drivers Using adb [2] Print out the new value of sp. This information should be saved in case you need to find out the contents of registers which have been pushed onto the stack frame. See adb documentation for more information about the concept of “.”, the current location in the core file. [3] adb output in response to the previous command, .=X 3 Find the current return pointer.
Debugging STREAMS/UX Modules and Drivers Using adb crash_monarch_stack+16C: 0xDB938 0xDB938/i boot+24: addil 0,dp boot/3i boot: boot: stw rp,-14(sp) stwm r3,80(sp) stw r4,-7C(sp) sp .
Debugging STREAMS/UX Modules and Drivers Using adb [2] These two lines are adb's response. panic's actual sp is 7FFE6F48. [3] Reset sp to the correct address. Now that you have panic's real stack pointer, the other steps in the back-tracing process can be executed normally. Text preceded by “#” are comments. sp .=X # calculate new sp # print out new sp 7FFE6EC8 sp .
Debugging STREAMS/UX Modules and Drivers Using adb [2] Save state structure + 0x84 is the location of the pcogh. [3] adb's response -- 96B70 is the return instruction address. [4] Save state structure + 0x78 is the location of the sp. [5] adb's response -- 7FFE6B98 is the current stack pointer. [6] Reset sp to the correct value. [7] Continue to iterate the four basic stack back-tracing steps.
Debugging STREAMS/UX Modules and Drivers Using adb bl copen,rp [1] [1] a procedure call to copen() or: bl creat+34,rp (save_pn_info) [1] [1] a procedure call to save_pn_info() By comparing the branches in the assembly code before and after the instruction where the trap occurred with the procedure calls in the source code, the corresponding source code line can often be determined. See the examples at the end of this chapter for more details.
Debugging STREAMS/UX Modules and Drivers Using adb Obtaining Procedure Argument Values It is often useful in debugging a problem to know what parameter values a procedure in the stack trace was called with. For example, in the following stack trace it would be useful to know the arguments flushq() was called with.
Debugging STREAMS/UX Modules and Drivers Using adb realloccg: realloccg+4: realloccg+8: realloccg+0xC: realloccg+10: realloccg+14: realloccg+18: realloccg+1C: realloccg+20: realloccg+24: realloccg+28: realloccg+2C: realloccg+30: stw stwm stw stw stw stw stw stw stw or or or or rp,-14(sp) r3,80(sp) r4,-7C(sp) r5,-78(sp) r6,-74(sp) r7,-70(sp) r8,-6C(sp) r9,-68(sp) r10,-64(sp) arg0,r0,r3 arg1,r0,r6 arg2,r0,r7 arg3,r0,r4 Here is rmvq() storing its arguments away in its stack frame: rmvq: rmvq+4: rmvq+8: rmv
Debugging STREAMS/UX Modules and Drivers Using adb Now, edit filename, and search for all instances of the register or stack frame location of interest. Any instruction which would modify the contents of the register could potentially overwrite the information you are trying to get. Below are some examples of modifying instructions. Note that in all cases the register being modified, also known as the target register, is the last register in the instruction.
Debugging STREAMS/UX Modules and Drivers Using adb Suppose you have determined that the procedure whose arguments you are interested in does not modify the registers it loaded the arguments into before the next procedure call in your stack. You can look at the appropriate location in the stack frame of the next procedure call in the stack to get the value.
Debugging STREAMS/UX Modules and Drivers Using adb Obtaining Register Contents from Trap save_state or panic_save_state Areas If the system core dump was produced by a panic or a trap, copies of all the registers at the time of the trap or panic were saved in memory and are available in the core dump. For a trap, the registers are saved on the stack, in the order specified in the struct save_state, which is defined in /usr/include/machine/save_state.h.
Debugging STREAMS/UX Modules and Drivers Using adb Obtaining Important Kernel Global Variables To print out the value of a kernel global variable, simply use the symbol name with the appropriate formatting option (see adb(1) and the ADB Tutorial for more information). The following table lists some of the more interesting kernel globals, with the appropriate adb format for printing them, and brief descriptions of what they mean. adb Command Description msgbuf+0xc/sD Kernel’s circular printf buffer.
Debugging STREAMS/UX Modules and Drivers Using adb Obtaining Values from the Process Table Entry and User Area It is possible to use adb to print out fields of interest from the process table entry and user area of the process that was running when the system crashed. The following subsection describes how to print certain important fields and gives a very brief description of each field. For more information on the meaning of these fields, see The Design of the UNIX Operating System by Maurice Bach, pub.
Debugging STREAMS/UX Modules and Drivers Using adb Important User Area Fields The table below describes the adb command to use to print important user area fields. u means the value marked u printed on adb entry (see example above). When executing the adb commands in the table below, substitute the u value printed on adb entry for the letter u. Field Name Address Description u_procp u+0x258/X Pointer to process table entry.
Debugging STREAMS/UX Modules and Drivers Using adb Field Name Address Description p_flag p+0x20/X [Series 700] p+0xc/X [Series 800] per-process flags, see proc.h p_flag2 p+0x24/X [Series 700] p+0x48/X [Series 800] per-process flags, see proc.h p_mpflag p+0x10/X [Series 800 only] per-process flags, see proc.h p_stat p+0xc/b [Series 700] p+0x32/b [Series 800] current process state, see proc.
Debugging STREAMS/UX Modules and Drivers Using adb Field Name Address Description p_sigignore p+0x18/X [Series 700] p+0x40/X [Series 800] signals being ignored p_sigcatch p+0x1c/X [Series 700] p+0x44/X [Series 800] signals being caught by user 195
Debugging STREAMS/UX Modules and Drivers Debugging Examples Debugging Examples Example 1 The following core dump was obtained while using a modified version of the sp driver, which is described in example #2 in the strdb section of this chapter. On entry to adb, we first look at the msgbuf to look for the panic message and hex stack trace. The interesting portion of msgbuf for this dump is: msgbuf+10/s . . . interrupt type 15, pcsq.pcoq = 0.3b2cc, isr.ior = 0.
Debugging STREAMS/UX Modules and Drivers Debugging Examples struct sp { unsigned sp_state; queue_t *sp_rdq; mblk_t *mp; mblk_t *last_mp; }; static sp_timeout(lp) struct sp *lp; { mblk_t *temp; unsigned int s; if (lp->sp_state & SPOPEN) { /* Put message on driver's read queue */ s = splstr(); temp = lp->mp; lp->mp = lp->mp->b_next; if (lp->mp == NULL) lp->last_mp = NULL; temp->b_next = NULL; putq(lp->sp_rdq,temp); splx(s); } } Here is the relevant portion of the assembly code.
Debugging STREAMS/UX Modules and Drivers Debugging Examples this, and want to look at the rest of *lp. To do so, we need to find the value of r3 at the time of the panic. We may be able to extract this information from the stack if we know the value of sp at the time of the panic. To get this information, we do a manual stack back-trace. See “Manual Stack Back-Tracing” for details on how this is done.
Debugging STREAMS/UX Modules and Drivers Debugging Examples instance whose q_ptr is the same as the address we have for lp. lp is a pointer to the sp driver's private data, which is also pointed to by q_ptr.
Debugging STREAMS/UX Modules and Drivers Debugging Examples q_nband = 1 q_pad1[0] = 00 q_pad1[1] = 00 Now that we have reached the queue structure for the panicking sp driver instance, we can use strdb or adb to examine its contents.
Debugging STREAMS/UX Modules and Drivers Debugging Examples timeout(sp_timeout,lp,1); break; default: printf(“Routine spput: Should not be here\n”); break; } } Note that spput() never updates lp->mp. It just adds the new message to the tail of the list using lp->last_mp. But once sp_timeout() has processed the last message on the list and set lp->mp to NULL, spput() will never update lp->mp to point at the next message it receives. This causes sp_timeout() to be called with lp->mp == NULL.
Debugging STREAMS/UX Modules and Drivers Debugging Examples First we translate the hex stack trace in the panic message into procedure names and addresses.
Debugging STREAMS/UX Modules and Drivers Debugging Examples printf(“Routine spput: Should not be here\n”); break; } } Here is the relevant portion of the assembly code. The instruction where the panic occurred is marked with an “*”.
Debugging STREAMS/UX Modules and Drivers Debugging Examples We may be able to determine whether we executed the “if” clause or the “else” clause of the if statement, based on the fact that we know we executed spput+0x4C (because a trap occurred while executing it). The comibf instruction branches to its target address if the condition it is checking is false. This comibf instruction compares ret0 to zero. If ret0 equals zero, comibf will not branch, and execution will continue to spput+0x3C and spput+0x40.
Debugging STREAMS/UX Modules and Drivers Debugging Examples the value of sp at the time of the panic. To get this information, we do a manual stack back-trace. See “Manual Stack Back-Tracing” for details on how this is done.
Debugging STREAMS/UX Modules and Drivers Debugging Examples However, there is an alternative way to find out the value of lp. If we can determine what the procedure that called spput() set arg0 to before the call, we will know the value of q, and lp is q->q_ptr. The procedure which called spput() is csq_lateral(). The point where the call was made is marked with an asterisk. Note that the procedure call here is made using the instruction ble instead of the usual instruction bl.
Debugging STREAMS/UX Modules and Drivers Debugging Examples We see that spput did not save r5. Callee registers are only saved if the callee plans to overwrite the register. So we cannot get r5 from spput's stack frame, but if spput did not save r5 that means it did not overwrite it; therefore, the value for r5 in the save state area will be the same value that r5 had at csq_lateral+0x74.
Debugging STREAMS/UX Modules and Drivers Debugging Examples */ splx(s); In order to protect access to q->q_ptr, sp_timeout() must also call splstr() before it accesses q->q_ptr. The source code for sp_timeout() in the first example in this section shows the correct use of splstr(). See the STREAMS/UX synchronization section of Chapter 3 for guidelines on protecting module and driver critical sections.
Debugging STREAMS/UX Modules and Drivers Debugging Examples hpstreams_close+58: call_open_close+448: closed+138: ufs_close+11C: vn_close+24: vno_close+50: closef+0xE8: exit+2B4: rexit+20: syscall+2A4: stw or or movb,tr ldw addil ldw bl ldw ldhs ret0,-40(sp) ret0,r0,r3 ret0,r0,r5 r0,ret0,ufs_close+15C -54(sp),rp -59800,dp 18(r3),arg0 uffree,rp -54(sp),rp 0(r9),r19 The address where the illegal data access occurred is flushq+0x60. The isr.
Debugging STREAMS/UX Modules and Drivers Debugging Examples We can find flushq()'s calling sequence in its man page in SVR4PG: void flushq(queue_t *q, int flag) It is more likely that *q or one of its members is NULL than the parameter flag being the cause of our problem. We will trace the use of the first argument, originally in arg0, through flushq, to see how it might be related to the contents of r21. At flushq+0x8, arg0 is pushed onto the stack at offset sp - 0x64.
Debugging STREAMS/UX Modules and Drivers Debugging Examples q->q_first. Checking the instructions between flushq+0x3C and flushq+0x58 shows that sp - 0x34 has not been stored to by any of these instructions, only loaded from. So at flushq+0x58, r20 is loaded with q->q_first. At flushq+0x5C, r21 is loaded with some field of q->q_first. Looking at the structure definition for struct msgb, also found in /usr/include/sys/stream.
Debugging STREAMS/UX Modules and Drivers Debugging Examples Now that we have the values of sp for flushq, we know the q address we are interested in is at 0x7ffe7420 - 0x64: 0x7ffe7420-0x64/X 7FFE73BC: 5E9C00 Looking at the first few words of the q structure, we can determine the value of q_first, which is the second word: 5E9C00/4X 5E9C00: 294160 5D8C00 6C1880 0 Looking at q_first, we can see that the sixth word, b_datap, is NULL: 5D8C00/8X 5D8C00: 646480 6440D1 0 0 646400 0 644000 0 We can als
Debugging STREAMS/UX Modules and Drivers Debugging Examples :x msgb 0x5d8c00 struct msgb 0x5d8c00 b_next b_prev b_cont b_rptr b_wptr b_datap b_band b_pad1 b_flag b_pad2 S:1 = 0x646480 = 0x0 = 0x646400 = 0x644000 = 0x6440d1 = 0x0 = 0 = 00 = 0x0 = 0 b_datap could be NULL because its resources have been freed, or it could be NULL because the data structure was corrupted in some way. To try to narrow this down, we want to look at the message buffer b_cont.
Debugging STREAMS/UX Modules and Drivers Debugging Examples struct queue 0x5e9c00 q_qinfo q_first q_last q_next q_link q_ptr q_count q_flag QREADR QFULL QWANTW QUSE QOLD QSYNCH q_minpsz q_maxpsz q_hiwat q_lowat q_bandp q_nband = = = = = = = = 0x294160 0x5d8c00 0x6c1880 0x0 0x0 0x0 24896 0x1135 = = = = = = 0 256 0x8000 0x4000 0x539d00 1 S:3 q_pad1[0] q_pad1[1] q_pad1[2] q_other = 00 = 00 = 00 = 0x5e9c74 Note that this is a read queue whose q_next pointer is NULL.
Debugging STREAMS/UX Modules and Drivers Debugging Examples Using the adb i command, we can find out the name of the qi_putp routine: 0x785ac/i lmodcput: lmodcput: stw rp,-14(sp) This means the module lmodc was using the queue on which the panic occurred. We can double check this by looking at the qi_minfo structure in strdb.
Debugging STREAMS/UX Modules and Drivers Debugging Examples For the sp driver, we found that spclose() calls freemsg(): static spclose(q) queue_t *q; { struct sp *lp; unsigned int s; mblk_t *mp, *t_mp; lp = (struct sp *) (q->q_ptr); /* Free messages queued by spput() on interim mesg queue.
7 STREAMS/UX-NetTL Link 217
STREAMS/UX-NetTL Link NetTL (Network Tracing and Logging facility) is the facility used by network drivers and modules to capture network error events or trace data. In HP-UX 10.0, a mechanism will enable STREAMS/UX to deliver log/trace messages to NetTL. Previously, STREAMS/UX had its own error logging and tracing facility. This chapter describes the STREAMS/UX-NetTL link, which integrates the STREAMS/UX logging and tracing facility with NetTL.
STREAMS/UX-NetTL Link Mapping from STREAMS/UX Messages to NetTL Messages Mapping from STREAMS/UX Messages to NetTL Messages Both STREAMS/UX error logging and event tracing messages are mapped to NetTL logging messages.
STREAMS/UX-NetTL Link STREAMS/UX Subsystem ID and Subformatter STREAMS/UX Subsystem ID and Subformatter Subsystem ID STREAMS/UX subsystem ID used by NetTL is: ID Name: ID Number: STREAMS 129 Subformatter The messages logged by the NetTL facility can be formatted to a readable form by the netfmt command (see netfmt(1M)). The STREAMS/UX subformatter can be used to filter messages on STREAMS/UX module ID and sub-ID.
STREAMS/UX-NetTL Link Quick Guide On How to Use NetTL for STREAMS/UX Quick Guide On How to Use NetTL for STREAMS/UX • Check if NetTL is running. nettl -status NetTL will start running by default after the system boot (see nettl(1M) for more detail). If NetTL is running, you can check the log file name, STREAMS/UX subsystem ID, STREAMS/UX log classes, etc. • If it is not running, a superuser needs to start NetTL. nettl -start • NetTL can be stopped by a superuser.
STREAMS/UX-NetTL Link Quick Guide On How to Use NetTL for STREAMS/UX • You can format and read the logged messages. netfmt -f /var/adm/nettl.LOG00 The default error log file is /var/adm/nettl.LOG00. • You can format and filter the logged messages. netfmt -f /var/adm/nettl.
Index Symbols /etc/dmesg, 24 /etc/update, 16 ? command, 125 core dumps, 171 generating, 171 retrieving, 171 core file, size requirements, 173 A adb, 120, 122, 174 invoking, 174 registers, 174 applications, compiling and linking, 115 assembly language mapping, 184 autopush command, 32 D data segmentation faults, 169 data structure navigation commands, 129 data structure restrictions, 60 driver and module synchronization, 63 drivers clone, 25, 53 compiling, 105 echo, 25, 54 pipedev, 25 pipemod, 56 sad, 25
Index P panic data segmentation faults, 169 instruction page faults, 169 protection violations, 170 stack trace, 177 panic message, 176 panic_save_state, 190 pdfck, 19 pipe, 35 pipedev driver, 25 pipemod driver, 56 pipemod module, 25 primary commands, 129 priority number, 64 procedure argument values, 186 process table entry, 192 protection violations, 170 putctl2 utility, 44 putmsg system call, 26, 36 putnextctl2 utility, 45 putpmsg system call, 36 putq, 63, 64 Q q command, 126 qc command, 128 qh command,
