STREAMS-UX Programmer's Guide (February 2007)

Modules and Drivers
Design Guidelines
Chapter 4
85
• STREAMS modules and drivers must not call the put and service procedures directly. They must be
executed by calling STREAMS utilities such as putnext, put, putq, or qenable. They cannot be called
using the function pointer stored in the q_qinfo structure.
• STREAMS modules and drivers can allocate their own spinlocks to protect data structures. If they do,
they should use the lock orders reserved for them in /usr/include/sys/semglobal.h:
STREAMS_USR1_LOCK_ORDER, STREAMS_USR2_LOCK_ORDER and STREAMS_USR3_LOCK_ORDER.
Modules and drivers cannot hold spinlocks when calling some STREAMS utilities (see Appendix B,
“STREAMS Utilities Supported by HP-UX,” for details). To reduce contention and improve performance,
the amount of time that the modules and drivers hold the spinlocks should be minimized.
• STREAMS modules and drivers written for HP-UX need to be multiprocessor safe (MP-safe) and specify
the flag MGR_IS_MP explicitly in their respective streams_info_t structures.
•On HP-UX modmeta files as mentioned in the “Installation Structures and Configuration Routines” on
page 64 need to be defined for both STREAMS modules and drivers in order to configure them into the
kernel.
Rules
A few rules have been established as guidelines for the following routines and procedures.
Open/Close Routines
1. The open and close routines may sleep with a priority <= PZERO or with PCATCH set in the sleep priority, so
as to return to the calling routines when the sleep is interrupted.
2. The open and close routines have a user context and can access the u_area (defined in <sys/user.h>).
3. The open and close routines should only access the following fields in the u_area namely, u_procp,
u_ttyp, u_uid, u_gid, u_ruid, and u_rgid.
4. The open and close routines also have access to some attributes p_pid, and p_pgrp in the process table
(defined in <sys/proc.h>).
5. The open routine should return zero on success and an error number on failure. When a cloneable
STREAMS driver executes its open routine (sflag has the CLONEOPEN flag set), the device number must
be set to an unused device number for that device.
6. If a module or driver wants to allocate a controlling terminal, a M_SETOPTS message should be sent to the
stream head (by the open routine) with the SO_ISTTY flag set.
Handling IOCTLs
1. If a module does not recognize the M_IOCTL message, it should forward the message to next component in
the stream without any change to the message. If a driver does not understand an IOCTL, it must send a
M_IOCNAK message upstream.
2. The modules and drivers must not change the ioc_id, ioc_cmd, ioc_uid or ioc_gid fields in a M_IOCTL
message.
3. In addition, the drivers and modules must not change cp_id, cp_cmd, cp_uid, and cp_gid fields in
M_IOCDATA messages and cq_id, cq_cmd, cq_uid and cq_gid in M_COPYIN/M_COPYOUT messages.
4. Modules and drivers should always validate ioc_count to see whether the IOCTL is the transparent or
the I_STR form.