Linux STREAMS (LiS)

Contents

Introduction

STREAMS Drivers

clone-drvr
fifo
link-drvr
loop-around
mini-mux
printk
sad

Pushable Modules

connld
ip_strms
pipemod
relay
relay2
timod
tirdwr

Introduction

The LiS package comes with a number of STREAMS drivers and pushable modules in source code form.  A number of these drivers and modules are small entities that are used in the testing of LiS.  They are included so as to make it easy for any user to run the LiS tests for themselves.

Other drivers are used to interface between STREAMS and the Linux networking subsystem (link-drvr, ip_strms).  Still others are used to implement STREAMS based pipes and FIFOs.

A driver in STREAMS has a major and minor device number associated with it and an entry in the /dev directory.  The driver is opened and closed just like any file.

A pushable module in STREAMS is an entity that is added to an existing STREAMS file via the I_PUSH ioctl.  These modules are known to LiS by mnemonic name, given as an argument to the I_PUSH ioctl.  There are no major and minor device numbers or /dev entries associated with pushable modules.

This document is broken down into two sections.  The STREAMS drivers and pushable modules are documented separately.  The driver names used in this document are the declared names that appear in the LiS Config file for the particular driver.

Back to Contents

clone-drvr

Device Name

/dev/clone_drvr

Description

This driver is used to assist LiS in implementing the "clone" open function.  It appears under its own name as /dev/clone_drvr.  By convention, it is allocated the first major number of all the STREAMS drivers.

In order to implement clone opens, one creates a node in the /dev directory for a device whose major number is set to that of the clone driver, and whose minor number is the major number of the driver to which the clone open is to be directed.

The clone driver's open routine forwards the open call to the target driver, passing a unique flag that informs the driver that a clone open is being requested.  The target driver then allocated a minor device number to uniquely associate with this instance of the open operation.  The clone driver synthesizes a new major/minor "device id" to pass back to LiS.  LiS recognizes the change of major/minor from the original open and takes steps to allocate control structures unique to this open.

The "clone open" operation is intended to make is easy to open one device from a pool of devices, such as pseudo ttys or logical connections.  It saves application programs from having to scan a list of device mnemonics issuing trial opens until one is found that succeeds.

Note that the driver is named /dev/clone_drvr instead of the more traditional SVR4 /dev/clone. This is to avoid a conflict with another driver named /dev/clone on Linux systems.
 

Author

David Grothe <dave@gcom.com>
 

Back to Contents

fifo

Device Name

/dev/fifo (clone device)
/dev/fifo.0

Description

The fifo pseudo-driver (which is internal to LiS) provides STREAMS-based fifos as single character special files, and STREAMS-based pipes as pairs of character special files which are interconnected (see pipe(3)).

STREAMS-based fifos differ from typical STREAMS-based character special files in that there are not separate stream head and driver queue pair within the STREAMS-based file. Instead, a fifo is created with only a single queue pair for the stream head. Moreover, in a typical driver queue pair, the write queue is not connected to a next queue. In a fifo, the write queue is directed to the read queue of the pair. A pipe comprises a pair of fifos, with the write queue of each pair directed to the read queue of the other. The two fifos comprising a pipe are referred to as peers, and each somewhat represents a driver to the other. As a degenerate case, a fifo is its own peer.

STREAMS modules may be pushed onto fifos and pipes, but should not expect a driver below them; instead, the SAMESTR() function should be used from the write queue of a pair to determine if the module is the lowest in the STREAMS-based file (this is called the midpoint). The structure of a fifo or pipe is preserved when modules are pushed (and popped); i.e., the write queue at the midpoint will always be directed at the read queue of the peer.

Input and output are handled at a fifo stream head as they would normally be handled at a stream head. In LiS, an fifo open() entry point exists to assign minor device numbers to new opens under the fifo major device number, and a close() entry point is used correspondingly to release them. These functions are kept in a streamtab data struc­ ture (as they would normally be for any STREAMS driver or module) which is private to the LiS implementation.

Application Usage

In the current Linux kernels, character special major numbers are limited to 16 bits, and major and minor device numbers to 8 bits each. This limits a system to 256 total major device numbers and 256 total minor devices per major device number. This is a rather severe limitation where mechanisms like fifos and pipes are concerned.

However, a driver may handle more than one major device number. The fifo pseudo-driver uses this to overcome this limitation, by supporting the automatic allocation and use of multiple major device numbers for fifos and pipes.  Specifying more than 256 minor devices is done in the usual manner, i.e., by specifying the number of "units" in the appropriate Config file. Enough major device numbers will be allocated to cover the requested number of minor devices (if available, else an error will occur in strconf(8)). The number allocated will include one minor device per major number to be used as a fifo-specific clone minor device (specifically, minor number 0), which exhibits special behavior.

Normally, when cloning is done via the clone pseudo-driver, the clone major device number is used, along with the desired actual major number as the minor device num­ ber. When an open() is performed on such a device, the clone open() routine in turn calls the appropriate driver's open(), with the sflag parameter set to CLONEOPEN. The driver's open() is expected in this case to allocate an unused minor device number, and return it via an entirely new device number in the devp parameter. In this way, a driver can change the device number to be used for a STREAMS-based file. When minor device 0 for a specified for a fifo major device, the driver will also clone a new minor device number. However, LiS opens fifo devices differently; specifically, when an already-opened fifo-specific clone minor device is reopened, the new and subsequent opens will use the already-opened clone. Thus, using minor device 0 for a fifo when creating a file sys­ tem node will ensure that all concurrent opens of the associated path name will use the same STREAMS-based file; at the same time, opens of different file system nodes via different paths will open their respectively different STREAMS-based files. This is essentially how kernel-based fifos behave -applications and users of STREAMS-based fifos don't have to keep track of minor numbers to achieve this same behavior when it is desired.

It is in fact recommended that only two forms of file sys­ tem nodes be used for STREAMS-based fifos: the clone major number as major number with a fifo major number as minor number, to be used when every open of the associated path must clone a new fifo, and a fifo major number as major number with 0 as the minor number, to be used when new opens are to clone a new fifo but subsequent concurrent opens are to use the already opened fifo. These are represented by two device special file paths created when LiS is installed: /dev/fifo for the former, and /dev/fifo.0 for the latter. It is recommended that these be used, possibly along with the equivalent of stat(2) to determine appropriate major device numbers for the clone and fifo pseudo-drivers, which are also determined when LiS is installed. It can be noted that pipes are actually created as instances of the former, after which the write queues are peer-connected.

The fifo pseudo-driver allocates minor devices in round-robin fashion; i.e., a list of available minor devices is kept, and once a minor number is finally closed, it is put at the end of this list. Thus, a fifo minor device which is opened and closed will not be immediately reused.
 

Warnings

Because STREAMS-based fifos and pipes are implemented as character special devices, they do not appear as pipe devices when examined with stat(2) or the equivalent (e.g., ls(1)); i.e. the S_IFIFO indication is not set in the mode - S_IFCHR is set instead, and the actual device number is indicated in the st_rdev field of the stat data structure.

Because of the potential use of multiple major numbers, applications should not depend on a fifo or pipe having a specific major device number, nor should an application depend on all fifos and pipes having the same major device number.
 

See Also

clone(9), connld(9), fifo(4), ls(1), pipe(3), pipemod(9), STREAMS(4), stat(2), strconf(8)
 

Author

John Boyd, protologos LLC. <jaboydjr@netwalk.com>
 

Back to Contents

link-drvr

Device Name

/dev/ldl (clone device)

Description

The LDL driver provides an interface between STREAMS drivers and Linux network drivers.  It registers itself as a client of a Linux network driver and then presents a DLPI Provider interface to STREAMS drivers, which may be pushed or linked above LDL.

The LDL is controlled by DLPI primitives from its upstream client.  The DLPI primitives understood by this driver are as follows.  DLPI mnemonics come from the file <sys/dlpi.h>.  LDL mnemonics come from the file <sys/ldl.h>.
 

For data received from the Linux network driver, LDL forwards a copy of the received data in a DL_UNITDATA_IND DLPI message to each client whose stream is attached to the particular network driver and who has a SAP bound to the stream that matches the SAP information in the received frame.  Note that for non-raw frame operations that the MAC header is stripped from the received frame prior to forwarding it to the client.  The address of the sender is retained in the address field of the DL_UNITDATA_IND primitive.
 

Driver ioctls

The LDL driver implements the following ioctls.  The user codes these ioctls as type I_STR and passes a structure of type struct strioctl to the driver.  The ic_cmd field of this structure is decoded according to the following table.  the ic_dp and ic_len fields delimit an argument structure which is also passed to the driver.  The argument structure differs for each type of ic_cmd.
 
 

Author

Ole Husgaard <sparre@login.dknet.dk>

Back to Contents

loop-around

Device Name

/dev/loop_clone (clone device)
/dev/loop.1
/dev/loop.2

Description

This driver is used by LiS and the strtst utility to assist in the regression testing of LiS.  It connects two streams together in a manner similar to that of a pipe.  Messages written into one stream can be read back from the other.

The driver can be operated as a clone device with the two streams being connected via ioctls.  A number of ioctls exist that tailor the operation of the driver.  The user codes these ioctls as type I_STR and passes a structure of type struct strioctl to the driver.  The ic_cmd field of this structure is decoded according to the following table.  the ic_dp and ic_len fields delimit an argument structure which is also passed to the driver.  The argument structure differs for each type of ic_cmd.
 

Author

David Grothe <dave@gcom.com> plus others originally.

Back to Contents

mini-mux

Device Name

/dev/mux_clone (clone device)
/dev/minimux.1
/dev/minimux.2

Description

This driver is used by LiS in its testing procedures. It is a small multiplexing driver that allows cascaded multiplexors to be built and torn down. The driver uses a pair of ioctls to establish connectivity between upper streams and lower streams. This allows control over how data flows through the multiplexor.

Both of these ioctls are coded as type I_STR and pass a structure of type struct strioctl to the driver.  The ic_cmd field of this structure is decoded according to the following table.  the ic_dp and ic_len fields delimit an argument structure which is also passed to the driver.  The argument structure may differ for each type of ic_cmd.
 

Author

David Grothe <dave@gcom.com>

Back to Contents

printk

Device Name

/dev/printk

Description

This driver accepts messages written to it and prints them from the kernel using the kernel's printk function. It is used by the LiS test software to keep messages from LiS and messages from the test program in sequence.

Author

David Grothe <dave@gcom.com>

sad

Device Name

/dev/sad

Description

The STREAMS Administrative Driver manages the autopush function of LiS. Using ioctls the system administrator can provide a list of modules that are to be automatically pushed onto a given device when that device is opened. The controls are specified via the strapush structure which is defined in <sys/sad.h>.

The ioctl used by the user is of the form:

ioctl(fd, command, arg)

Where fd is the file descriptor of the file that is open to the sad driver, command and arg are described in the following table.

The strapush structure used by the SAD_SAP and SAD_GAP ioctls contains the following fields.

The ioctl function call returns zero upon success or -1 on failure. Upon failure errno is set to the error number describing the failure, usually either EFAULT or EINVAL.

Note that the sad driver is a standard AT&T STREAMS function. More comprehensive documentation for this driver can be found in the SVR4 Programmer's Guide: STREAMS.

Author

Ole Husgaard <sparre@login.dknet.dk>

Back to Contents

connld

Module Name

connld

Description

The connld module provides a means to generate multiple unique STREAMS-based pipes from a single existing pipe end. connld may only be pushed (via the STREAMS I_PUSH ioctl) onto a STREAMS-based pipe. When first pushed, connld does nothing; on each subsequent open(2), connld will generate a unique STREAMS-based pipe. One end of each new pipe replaces the original pipe end from the perspective of the open call. The other end of each new pipe is sent, effectively as if by the I_SENDFD ioctl, to the other end of the original pipe, ostensibly to be received by a subsequent I_RECVFD ioctl operation.

Application Usage

The intent of connld is to provide a means to generate unique pipes which separately and independently connect client processes to a server process. The point of access for such clients is expected to be a path name known to all such clients and to which a pipe end may be connected (via fattach(3)) by the server process. The server establishes the original pipe, pushes connld onto the client end, and then listens via I_RECVFD for new connections on the server end. A client wishing to connect to the server will open(2) the path name representing the client end, and can determine via isastream(3) whether or not the server process is active and attached. If it is, the open() call returns one end of a unique new pipe that thus connects the client to the server.

Such a server is responsible both for accepting new connections via I_RECVFD on the original pipe, and for communicating with clients so connected via the received pipe ends. It would also be reasonable for such a server process to invalidate the point of access by calling fdetach(3) before terminating.

It should be noted that the poll(2) primitive may be used to indicate when an M_PASSFP representing a newly passed file is available on the original server pipe end. This is reflected by the POLLIN status setting in the events and revents fields of a pollfd structure. Moreover, any attempt to read an M_PASSFP message via the data-receiving primitives (i.e., read(2), getmsg(3), and getpmsg(3)) will fail with errno(3) returning an EBADMSG indication without discarding the message.

Even so, it should be reasonable to expect only M_PASSFP messages will be received on the original server pipe end, since it is not possible to carry on normal data traffic which has connld on one end, since connld does not support such traffic.

The use of connld can be made entirely free-standing by attaching well-known paths to both ends of the original pipe. The relevant capabilities are implemented in LiS so that the original creator of the pipe can close both ends after attaching paths to them, and the process of passing file descriptors can still be carried out via new open()'s as long as both ends remain attached.

See Also

fattach(3), fattach(8), fdetach(3), fifo(4), fifo(9),

pipe(3), STREAMS(4)

History

Unix System V Release 4 (SVR4)

Author

John Boyd, protologos LLC. <jaboydjr@netwalk.com>

Back to Contents

ip_strms

Module Name

ip_strms

Description

This module is pushed onto an open stream to a driver which implements the DLPI STREAMS protocol. It provides an interface between the DLPI driver below and the Linux IP module above. The effect is to be able to use a STREAMS DLPI driver as a network interface below Linux TCP/IP.

The ip_strms module monitors DLPI primitives sent from above on the stream file and shuttles them between the process which pushed the module onto the stream and the DLPI driver below. The ip_strms module will also allow data to be exchanged between the stream user and the DLPI driver until such time as the stream is logically attached to IP as a network driver.

In order to attach the stream to IP, the user process issues an ioctl of type SIOCSIFNAME. This ioctl causes ip_strms to register itself as a network driver of the given name. From that point onward data, in the form of M_DATA messages or of DL_UNITDATA_IND messages, are forwarded upstream to IP rather than to the stream user. Likewise, data messages received from IP are forwarded downstream to the DLPI driver as DL_UNITDATA_REQ messages. Downstream messages are completely formatted for the transmission medium and should be processed accordingly by the DLPI driver below.

After attaching to IP, the stream user must continue to remain in execution, holding the stream open. If the stream closes then ip_strms will detach from IP. Also, if the stream user sends a SIOCSIFNAME ioctl with an empty name then ip_strms will detach from IP.

The interfaces attached to IP will appear in the output of the netstat and ifconfig commands. An "ifconfig" down operation on the interface will also cause a detach from IP.

Application Processing

The application level program which manages the connection between a DLPI driver and TCP/IP should be coded to implement the following steps.

• Open a stream to the DLPI driver. This can be a clone open.

• Execute an I_PUSH ioctl on "ip_strms."

• Send the DLPI attach and bind primitives downstream.

• Execute an SIOCSIFNAME ioctl with the desired interface name. After this succeeds the DLPI driver will be connected to TCP/IP as a network driver via the ip_strms module.

• Perform any needed ifconfig or route commands for the interface.

• Sleep indefinitely keeping the stream open. Killing the process will cause the stream to be detached from IP.

Author

David Grothe <dave@gcom.com>

Back to Contents

pipemod

Module Name

pipemod

Description

The pipemod module has the relatively simple task of reversing the sense of the FLUSH flag bits in M_FLUSH messages sent in STREAMS-based fifos and pipes. This must happen at the midpoint of a fifo or pipe, so that FLUSHR becomes FLUSHW, and FLUSHW becomes FLUSHR. pipemod does this, and has no other function.

To be used appropriately, then, pipemod must be the first module pushed onto a pipe end or a fifo, but it is only necessary on one end of a pipe.

pipemod is not needed if flush handling need not be supported, or if its function is supported by other means.

See Also

fifo(9), pipe(3), fifo(4), STREAMS(4)

History

Unix System V Release 4 (SVR4)

Author

John Boyd, protologos LLC. <jaboydjr@netwalk.com>

Back to Contents

relay, relay2

Module Name

relay
relay2

Description

These are two names for the same module. All the module does is forward STREAMS messages along on the stream using putnext. These modules are used in the testing of LiS but are not otherwise useful. One could use the source code as a starting point for coding a pushable STREAMS module.

Author

David Grothe <dave@gcom.com>

Back to Contents

timod

Module Name

timod

Description

This is a primitive version of the standard AT&T SVR4 timod module. Its function is to convert user level ioctls to TLI primitives downstream.

Since there is no TLI Provider code within LiS, the timod module could be considered to be well ahead of its time.

Author

Ole Husgaard <sparre@login.dknet.dk>

Back to Contents

tirdwr

Module Name

tirdwr

Description

This is a primitive version of the standard AT&T SVR4 tirdwr module. Its function is to convert user level reads and writes to appropriate TLI protocol downstream.

Since there is no TLI Provider code within LiS, the tirdwr module could be considered to be well ahead of its time.

Author

Ole Husgaard <sparre@login.dknet.dk>

Back to Contents