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 allocb(D3str) function. If no STREAMS blocks are available, this call fails. The driver should silently drop the mesage or data being processed and increment the mac_frame_nosr statistic. STREAMS allocb( ) failures show up in the STREAMS statistics that can be viewed with the netstat -m command or the crash(ADM) strstat command.

  STREAMS drivers should not generate DL_UNITDATA_IND messages because of allocb( ) failures for DL_UNITDATA_REQ messages.

• Drivers that use DMA should allocate a replacement block with the allocb(D3str) 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, then calls allocb( ) to allocate a replacement. If the allocb( ) call fails, 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. If the allocb( ) call fails, 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 */
     else
     	;	/* 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 timeout(D3oddi) 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 (mp->b_datap->dp_ref) 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 each (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 (b_wptr -1) 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 mdi_end_of_contig_segment(D3mdi) 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.