Guidelines for STREAMS drivers
The general guidelines for kernel-level device drivers
that are given in
``Guidelines for all kernel drivers''
are relevant for STREAMS drivers as well.
This section lists other issues
that relate only to STREAMS drivers.
Frames that are smaller than the minimum length
specified by Ethernet/802.3 must be padded.
Padding should be done by appending bytes
onto the end of a hardware buffer
rather than at the end of a STREAMS message.
STREAMS blocks are allocated with the
If no STREAMS blocks are available,
this call fails.
The driver should silently drop the mesage or data being processed
and increment the
failures show up in the STREAMS statistics
that can be viewed with the netstat -m command
STREAMS drivers should not generate
failures for DL_UNITDATA_REQ messages.
Drivers that use DMA should allocate a replacement block
function before attempting to pass
the completed receive frame upstream.
A DMA device usually uses some sort of
receive buffer descriptor list,
with each descriptor holding
a pointer to a STREAMS block.
At interrupt time, the driver disaasociates
the STREAMS block from the descriptor
and passes it upstream,
to allocate a replacement.
the descriptor is left without a place
for the adapter to place data.
The descriptor is now orphaned
and cannot be placed back in the RBD list.
The driver then has to deal with managing the orphan list
and try to get a STREAMS block at some later time.
The following code fragment illustrates
how to avoid this condition.
this frame is dropped.
STREAMS allocation falures usually result in a lost frame
and it does not really matter which frame gets dropped.
/* receive allocb logic for BusMaster DMA devices */
if ((mp=allocb(size, pri) == NULL)
; /* no STREAMS memory available, drop completed frame */
; /* pass up RBD.mp, replace RBD.mp with 'mp' */
Code STREAMS drivers to ensure
that STREAMS resources are not monopolized
by a driver controlling a hardware device
that is malfunctioning.
Some NICs fail to generate
a transmit complete interrupt
if the cable is not attached.
If the driver uses the transmit complete interrupt
to free the STREAMS message that has been sent
(which is required for adapters that use
DMA instead of shared RAM or programmed I/O),
then care must be taken to ensure
that the driver does not queue up all STREAMS messages
in the system waiting for transmit complete interrupts
that will never happen.
One way to avoid this problem is to use the
function to implement a watchdog timer routine
that runs every second or so
to free messages left around
as a result of missing transmit complete interrupts.
Drivers should never modify STREAMS messages
that have been dup'ed.
Such messages can be identified by a reference count
that is greater than 1.
The SCO OpenServer 5 Release 5 STREAMS subsystem
has been extended to allow allocation of
STREAMS buffers greater than 4K.
The pages in these large STREAMS blocks
are virtually contiguous but may not be physically contiguous.
Drivers for adapters that use Bus Master DMA expect that
address_start, length) scatter element
represents a physically contiguous region of memory.
In earlier releases of SCO systems,
the data contained within the
b_rptr and (
of the STREAMS message block (mblk_t)
were always physically contiguous,
but for SCO OpenServer 5 Release 5 the driver must check each block
and break it into separate scatter elements if necessary.
MDI drivers can use the
function to check whether a STREAMS message block
is physically contiguous.
Some devices such as the IBM Token-Ring Network
16/4 Busmaster Service Adapter/A
are limited to 24 address lines
and so cannot perform DMA operations
with addresses beyone 16Mb.
In earlier releases of SCO systems,
a boot-time parameter enabled you to load kernel data
(including STREAMS memory)
low in memory to avoid this problem.
Because of the SCO OpenServer 5 Release 5 dynamic memory allocation scheme,
it is not possible to guarantee that
all STREAMS memory is in the lowest 16Mb of memory.
Drivers for DMA devices that cannot perform
DMA operations above 16Mb
should use memory copies instead of DMA transfers
when running on systems with more than 16Mb of memory configured.
© 2005 The SCO Group, Inc. All rights reserved.