Dynamic function replacement for streams framework

Abstract

An extension to the STREAMS framework, referred to as dynamic function replacement, uses data structures that contain function pointers which allow STREAMS to execute various module or driver functions without requiring framework modification, or understanding what these functions actually do beyond their rudimentary classifications. This provides a simple, yet elegant, mechanism for replacing these function definitions and, hence, changing the execution behavior of STREAMS modules and drivers without requiring the modules or drivers to be rewritten or modified.

Claims

We claim:

1. A data structure implemented in a computer system that provides a bidirectional data path between a user process, a module which is an intermediate processing element that can be dynamically added to, or removed from, said data path, and a device driver, said device driver being resident in a system kernel and controlling a peripheral device to transfer data between said kernel and said device, where data written by said user process travel downstream toward said driver, and where data received by said driver from said device travel upstream to be retrieved by a user, the data structure comprising:

a normal function that implements a specific module or driver instance;

at least one alternative function that implements an optional module or driver instance; and

a controller for generating a control command that remaps addresses of said normal function and said at least one alternative function to define new function addresses that dynamically replace said normal function with said at least one alternative function, thereby implementing said optional module or driver or instance to dynamically change the execution behavior of said data structure, while either still executing an original execution path or executing a new execution path, and without requiring any modification to said module and said driver.

2. The data structure of claim 1, further comprising:

an alternative function that customizes system tracing facilities to trace only specific events or under specific conditions.

3. The data structure of claim 1, further comprising:

an alternative function that provides support facilities for applying custom failure catchers to target specified system problems.

4. The data structure of claim 1, further comprising:

an alternative function that applies a patch on a per instance basis.

5. The data structure of claim 1, further comprising:

an alternative function that allows testing to a single data path and that allows increased flexibility and control of data path execution.

6. The data structure of claim 1, further comprising:

an alternative function that allows replacement of either all module or driver instances or replacement on a per instance basis.

7. The data structure of claim 1, wherein said system is implemented in a STREAMS framework.

8. The data structure of claim 7, wherein each module or driver defines a streamtab structure that contains pointers to qinit structures.

9. The data structure of claim 8, wherein said qinit structures are for read, write, read multiplexor, and write multiplexor queues which are created by said STREAMS framework.

10. The data structure of claim 8, wherein said qinit structures contain function addresses for open, close, put, service, and administrative functions which are invoked by said STREAMS framework on behalf of a module or driver.

11. The data structure of claim 8, wherein functions defined within said qinit structures are automatically executed by said STREAMS framework based on a current application execution path, and wherein said controller generates control commands that remap addresses of said structures to alternative streamtabs and qinit structures that define new function addresses.

12. The data structure of claim 11, wherein all contents of said qinit structures of an default alternative streamtab are identical to those of a normal streamtab except for put routines.

13. The data structure of claim 8, said controller further comprising:

at least one STREAMS ioctl command that is used to alternate dynamically STREAMS module's/driver's streamtab's.

14. The data structure of claim 13, said controller further comprising:

an ioctl command that is used to alter active instances of a module.

15. The data structure of claim 13, said controller further comprising:

an ioctl command that is used to alter future instances of a module.

16. A data structure implemented in a computer system that provides a bidirectional data path between a user process, a module which is an intermediate processing element that can be dynamically added to, or removed from, said data path, and a device driver, said device driver being resident in a system kernel and controlling a peripheral device to transfer data between said kernel and said device, where data written by said user process travel downstream toward said driver, and where data received by said driver from said device travel upstream to be retrieved by a user, said system being implemented in a STREAMS framework in which each module or driver defines a streamtab structure that contains pointers to qinit structures, the data structure, comprising:

a normal function that implements a specific module or driver instance;

at least one alternative function that implements an optional module or driver instance; and

a controller for generating a control command that remaps addresses of said normal function and said at least one alternative function to define new function addresses that dynamically replace said normal function with said at least one alternative function, thereby implementing said optional module or driver or instance to dynamically change the execution behavior of said data structure, while either still executing an original execution path or executing a new execution path, and without requiring any modification to said module and said driver.

17. The data structure of claim 16, further comprising:

an alternative function that customizes system tracing facilities to trace only specific events or under specific conditions.

18. The data structure of claim 16, further comprising:

an alternative function that provides support facilities for applying custom failure catchers to target specified system problems.

19. The data structure of claim 16, further comprising:

an alternative function that applies a patch on a per instance basis.

20. The data structure of claim 16, further comprising:

an alternative function that allows testing to a single path and that allows increased flexibility and control of path execution.

21. The data structure of claim 16, further comprising:

an alternative function that allows replacement of either all module or driver instances or replacement on a per instance basis.

22. A method for implementing a data structure in a computer system that provides a bidirectional data path between a user process, a module which is an intermediate processing element that can be dynamically added to, or removed from, said data path, and a device driver, said device driver being resident in a system kernel and controlling a peripheral device to transfer data between said kernel and said device, where data written by said user process travel downstream toward said driver, and where data received by said driver from said device travel upstream to be retrieved by a user, said system being implemented in a STREAMS framework in which each module or driver defines a streamtab structure that contains pointers to qinit structures, the method comprising the steps of:

providing a normal function that implements a specific module or driver instance;

providing at least one alternative function that implements an optional module or driver instance; and

generating, with a controller, a control command that remaps addresses of said normal function and said at least one alternative function to define new function addresses that dynamically replace said normal function with said at least one alternative function, thereby implementing said optional module or driver or instance to dynamically change the execution behavior of said data structure, while either still executing an original execution path or executing a new execution path, and without requiring any modification to said module and said driver.

23. The method of claim 22, wherein said qinit structures are for read, write, read multiplexor, and write multiplexor queues which are created by said STREAMS framework.

24. The method of claim 22, wherein said qinit structures contain function addresses for open, close, put, service, and administrative functions which are invoked by said STREAMS framework on behalf of a module or driver.

25. The method of claim 22, further comprising the steps of:

automatically executing functions defined within said qinit structures by said STREAMS framework based on a current application execution path; and

generating a control command to remap addresses of said structures to alternative streamtabs and qinit structures that define new function addresses.

26. The method of claim 22, wherein all contents of said qinit structures of an default alternative streamtab are identical to those of a normal streamtab except for put routines.

27. The method of claim 22, further comprising the step of:

using at least one STREAMS ioctl command to alternate dynamically STREAMS module's/driver's streamtab's.

28. The method of claim 27, further comprising the step of:

using an ioctl command to alter active instances of a module.

29. The method of claim 27, further comprising the step of:

using an ioctl command to alter future instances of a module.

Description

BACKGROUND OF THE INVENTION

1. Technical Field

The invention relates to a framework for communications services in a data enterprise. More particularly, the invention relates to the STREAMS framework which provides communications services that include communications between terminals and a host computer, between processes on the same computer, and between processes on different computers.

2. Description of the Prior Art

STREAMS has become the industry de facto framework for implementing network protocols and various types of character device drivers (see S. Rago, UNIX System V Network Programming, Addison Wesley professional computing series (1993)). The STREAMS subsystem was designed to unify disparate and often ad hoc mechanisms that previously existed in the UNIX operating system to support different kinds of character based I/O. In particular, STREAMS was intended to replace the clist mechanism that provided support for terminal I/O.

In the clist-based terminal subsystem, each terminal line can have one associated processing element, referred to as a line discipline. The line discipline handles all special character processing. Thus, if a user required nonstandard processing of the terminal data stream, the line discipline could be changed, although only one line discipline may be associated with a terminal at a time.

STREAMS allows users to add ("push") and remove ("pop") intermediate processing elements, referred to as modules, to and from the data stream at will. The modules can be stacked so that more than one module can be used in the data stream at a time. This allows independent modules that perform simple tasks to be combined in useful ways to perform more complex tasks, in much that same way as UNIX commands are connected via shell pipelines.

Data transfer in a stream occurs by passing messages between adjacent processing elements. Only pointer to the messages are passed, avoiding the costly overhead of data copying. Messages are types and have an associated priority, both of which indicate how the message should be processed. Using message passing to perform I/O creates a data driven data transfer, rather than the demand driven data transfer associated with other character based subsystems.

In previous I/O subsystems, when a user wanted to read data from a device, the driver's read routine was invoked, Similarly, when a user wanted to write data, the driver's write routine was invoked. In STREAMS, drivers usually do not know when users are reading from or writing to the stream. A read is typically blocked until data are available, while a write results in messages being sent to the driver.

A simple stream (see FIG. 1) provides a bidirectional data path between a process 12 at user 11 level and a device driver 14 in the kernel 13. Data written by the user process travel downstream 15 toward the driver, and data received by the driver from the hardware travel upstream 16 to be retrieved by the user. Even though data travel up and down stream in messages, drivers and modules can treat the data flow as a byte stream.

A simple stream consists of two processing elements: the stream head 17 and a driver 14. The stream head consists of a set of routines that provide the interface between applications in user space and the rest of the stream in kernel space. When an application makes a system call with a STREAMS file descriptor, the stream had routines are invoked, resulting in the performance of data copying, message generation, or control operations. The stream head in the only component in the stream that can copy data between user space and kernel space. All other components effect data transfer solely by passing messages and thus are isolated from direct interaction with users of the stream.

The second processing element is the driver, found at the end or tail of the stream. The driver controls a peripheral device and transfers data between the kernel and the device. Because the driver interacts with hardware, the driver is referred to as a hardware driver. Another kind of driver, referred to as a software or pseudo driver, is not associated with any hardware. Instead, such driver provides a service to applications, such as emulating a terminal-like interface between communicating processes.

The stream head cannot be replaced in the same way that a driver can. Drivers can be added to the kernel simply by linking their object files with the kernel object files. The stream head, on the other hand, is provided with the kernel proper and is fixed. The same stream head processing routines are used with every stream in the system. Each stream head, however, is customizable to a small extent by changing the processing options it supports.

The fundamental building block in a stream is the queue (see FIG. 2). The queue links one component to the next, thereby forming the stream. Each component in the stream contains at least one pair of queues, i.e. one queue (21, 23) for the read side (upstream) and one queue (20, 22) for the write side (downstream). The queue serves as a location to store messages as they flow up and down the stream, contains status information, and acts as a registry for the routines that are used to process messages.

When one component want to pass a message along in the stream, the queue is used to identify the next component. Then, the next component queue is used to identify the function to call to pass the message to that component. In this manner, each component's queue provides an interface between the component and the rest of the stream.

A module 30 (see FIG. 3) is an intermediate processing element that can be dynamically added to, or removed from, the stream. Modules are structurally similar to drivers, but usually perform some kind of filter processing on the messages passing between the stream head and the driver. For example, a module might perform data encryption or translation between one interface and another.

Adding and removing modules are not the only ways that a user can customize a stream. A user can also establish and dismantle multiplexing configurations. Multiple streams can be linked underneath a special kind of software driver, referred to as a multiplexing driver or multiplexor 40 (see FIG. 4). The multiplexing driver routes messages between upper streams opened to access the driver, and lower stream that are linked underneath the driver. Multiplexing drivers are well suited to implementing windowing systems and networking protocols. Windowing systems multiplex data between multiple windows and the physical terminal. Networking protocols multiplex messages between multiple users and multiple transmission media.

While streams are used to connect processes with devices, they may also be used to connect processes with other processes. Pipes are implemented as streams in UNIX System V release 4. There are two kinds of pipes, i.e. unnamed pipes and named pipes. An unnamed pipe, also referred to as an anonymous pipe, has no entry in the file system name space. The pipe system call creates an unnamed pipe by allocating two stream heads 17a, 17b and pointing the write queue of each at the read queue of the other (see FIG. 5).

A named pipe, also referred to as a FIFO because data are retrieved therefrom in a first-in-first-out manner, is created via the mknod system call. It has a name in the file system and can be accessed with the open system call. A named pipe is actually one stream head 17 with it s write queue pointing at it s read queue (see FIG. 6). DAta written to a named pipe are available for reading from the same end of the pipe.

There are several advantages to STREAMS-based pipes. First, local interprocess communication ("IPC") uses the same mechanisms as remote, or networked, IPC. This allows applications to treat local IPC connections the same as remote connections. Most operations that can be applied to a stream can therefore be applied to a pipe. For example, modules can be pushed onto pipes to obtain more functionality. Second, STREAMS-based pipes are full duplex, allowing bidirectional communications between two processes with one pipe instead of two.

All communication within a stream occurs by passing pointers to STREAMS messages. The messages are typed, and the type indicates both the purpose of the message and its priority. Based on the type, a message can be either high priority or normal priority. The normal priority messages are further subdivided into priority bands for the purposes of flow control and message queuing.

Any data the user wants to transmit to the other end of the stream are packages in M.sub.-- DATA messages by the stream head. This is the most common message type. If the user needs to send or receive control information, then an M.sub.-- PROTO message is used. Control information is intended form a module or driver in the stream, is interpreted by that component, and is usually not transmitted past the component. A special message type, M.sub.-- PCPROTO, is reserved for high priority control information, such as interface acknowledgments.

Simple messages are composed of one message block. More complex messages can be created by linking multiple message blocks together. These are then treated logically as larger messages. The data in one message block are viewed as being contiguous with the data in the next message block. The message structure is usually transparent to user level applications. One exception to this is when dealing with a complex message including both control information and user data.

Because the STREAMS mechanism is a subsystem of the UNIX kernel, it is important to understand the environment provided by the kernel. STREAMS drivers and modules must abide by the constraints imposed by both the STREAMS subsystem and the rest of the kernel. The Device Driver Interface/Driver-Kernel Reference Manual, Prentice-Hall, Englewood Cliffs, N.J. ("DDI/DKI") defines all the data structures and interface routines provided by the kernel for use by drivers and modules, as well as the entry points drivers and modules must define to operate in the kernel.

The DKI portion refers to implementation independent interfaces. It promotes portability for the same version of the operating system across different hardware architectures. The DDI portion refers to processor specific and platform specific interfaces. It promotes compatibility from release to release for a particular hardware architecture. Interface can belong to DDI, DKI, or both. Each system implementation includes its own version of the DDI/DKI. All systems share the same DKI. All systems using the same processor type have the same DDI, except for some platform specific interfaces.

With regard to such STREAMS enhancements as value added tracing and logging facilities, a third party provider is typically required to modify all of their code to add macros to STREAMS that enable such tracing and logging. This limits the number of developers willing to port to a particular platform because a developer must do something special for such platform, as opposed to writing to the standard. Thus, it is preferred that developers be able to use primarily standard code.

Additionally, whenever any extensions are added to the STREAMS framework, a performance penalty is also added because it becomes necessary to check, for example whether the system is tracing or logging. The performance penalty results, for example from a cache miss and/or where the CPU stalls because it is necessary to check for some global variable that is not normally referenced until such check is performed. If a global variable is being referenced, it is typically not in the system's cache. This results in a cache miss. A cache miss in a high speed processor can lead to a processor stall, reducing the effective performance of the system.

It would be advantageous to provide a STREAMS framework in which various enhancements or options were readily available without the twin penalties of added complexity/lack of compliance and performance degradation.

SUMMARY OF THE INVENTION

The invention provides an extension to the STREAMS framework that is referred to herein as dynamic function replacement. As discussed above, the STREAMS framework uses data structures which contain function pointers that allow STREAMS to execute various module or driver functions without requiring framework modification, or understanding what these functions actually do beyond their rudimentary classifications. Dynamic function replacement provides a simple, yet elegant, mechanism for replacing these function definitions and, hence, changing the execution behavior of STREAMS modules and drivers without requiring the modules or drivers to be rewritten or modified. With the extension herein described, the application developer, support, and the customer are provided with a dynamic mechanism for developing, modifying, and troubleshooting STREAMS modules and drivers.

BRIEF DESCRIPTION OF THE DRAWINGS

FIG. 1 is a block diagram that shows a simple stream;

FIG. 2 is a block diagram that shows STREAMS queues;

FIG. 3 is a block diagram that shows a module on a stream;

FIG. 4 is a block diagram that shows a multiplexing driver;

FIG. 5 is a block diagram that shows an anonymous pipe;

FIG. 6 is a block diagram that shows a FIFO;

FIG. 7 is a block schematic diagram showing a data structure that implements dynamic function replacement for a STREAMS framework in accordance with the invention; and

FIG. 8 is a block diagram showing a data structure for a STREAMS framework that incorporates dynamic function replacement in accordance with the invention.

DETAILED DESCRIPTION OF THE INVENTION

The invention provides an extension to the STREAMS framework that is referred to herein as dynamic function replacement. As discussed above, the STREAMS framework uses data structures that contain function pointers which allow STREAMS to execute various module or driver functions without requiring framework modification, or understanding what these functions actually do beyond their rudimentary classifications. Dynamic function replacement provides a simple, yet elegant, mechanism for replacing these function definitions and, hence, changing the execution behavior of STREAMS modules and drivers without requiring the modules or drivers to be rewritten or modified.

With the extension herein described, the application developer, support organization, and the customer are provided with a dynamic mechanism for developing, modifying, and troubleshooting STREAMS modules and drivers. For example, overall system performance may be optimized, such that a penalty performance, such as is associated with tracing/logging, is only imposed when such tracing/logging function is actually enabled in the stream and not otherwise.

The developer may augment the original execution path or may replace it entirely, e.g. if the instance in question needs new functionality on-the-fly, without having to change all instances within the system. Such new functionality could be, for example, a failure catcher, or it may be making a particular instance use a specific conformance version of a module/driver, such as when the application requires an X/Open conformance level and the module/driver uses a default version which is not conformant to this level. The developer may allow the conformance version of the module/driver to be replaced on a per application instance basis, which helps to satisfy multiple needs on the system, a feature not normally possible in today's STREAMS implementations.

Because STREAMS is a complex kernel subsystem, the actual usages of the technique herein disclosed are not intuitively obvious, even to those who understand how the kernel or networking protocols work. The following provides sample usages for purposes of establishing a sufficient background to understand the invention.

One application of dynamic function replacement responds to the need to incorporate tracing and logging facilities within a given network driver or module. These facilities, while fairly light-weight in cost, still introduce a performance penalty because it is necessary to determine for every message if the message needs to be traced or logged. In addition, third-party code cannot use such proprietary tracing and logging utilities unless their code is modified to add these macros. Most developers do not like to do this because it adds to support and maintenance costs.

Sometimes it is only desired to examine a particular STREAMS instance, such as a connection between two systems. With today's tracing and logging mechanisms this is not possible, nor is it possible without writing complex code for the driver or module to respond for a particular instance. Dynamic function replacement allows replacement of either all module or driver instances or replacement on a per STREAMS queue basis. This allows developers, customers, and support to fine tune their alternative facilities, without effecting all other users of a particular subsystem. Such fine tuning for a particular instance does not affect the performance of other instances, such that other applications that are running over different stream instances continue to perform as before without any performance penalty.

By using dynamic function replacement the user can provide a new function that includes all tracing and logging services, while still executing the original execution path, without requiring any modification to the module or driver. In fact, by extending these new functions it is possible to offer a more flexible tracing and logging facility at any time, without requiring the driver or module to be rewritten. This also means that there are no performance penalties when tracing and logging functions are not necessary.

Dynamic function replacement allows third party developers to create new tracing and logging facilities which are customized to the need at hand instead of the generic facilities currently in use. This means that for large networked systems managing thousands of connections or within a multicomputer configuration, it is possible to customize the tracing facilities to trace only specific events or under specific conditions without having to pay a performance penalty for all other connections or driver instances.

In one embodiment of the invention, support facilities are able to apply custom failure catchers, not just tracing and logging, to target specific problems because the actual content of this new function is up to the developer. In fact, it is possible to apply a patch on a per instance basis, instead of wholesale replacement of a module or driver, which leads to many useful customer support and patching strategies that are not currently possible in any known STREAMS implementations.

One of the most difficult problems for kernel developers is creating problem conditions within modules and drivers to test exception conditions, or to drive a module or driver independently of the application or the rest of the stream's stack. Current testing mechanisms rely upon special test drivers and custom I/O controls ("ioctls") to drive the modules for a specific path and are very limited and difficult to develop and maintain.

Dynamic function replacement allows developers to treat the module or driver as a black box testing target by controlling what messages are created and sent and the timing involved. Such encapsulation concentrates the testing to a single path and allows increased flexibility and control of path execution. This leads to a higher quality module or driver, while total development and test time is reduced.

Dynamic function replacement also allows developers to develop STREAMS-based modules or drivers without requiring special tools from third-party companies. When dynamic loadable kernel modules become generally available, dynamic function replacement will provide a quick mechanism to apply any of the above usages without requiring the module or driver to be unloaded and reloaded which can cause productivity losses for a customer and may limit the software developer's ability to support its customers as quickly and painlessly as possible.

As can be seen from the above sample usages, the primary advantages of dynamic function replacement are:

.circle-solid. No performance penalties for tracing and logging, or any other type of functionality, to be implemented.

.circle-solid. Modules and drivers do not require special modifications to take advantage of facilities such as tracing and logging.

.circle-solid. Support can apply special failure catchers more easily and apply patches without effecting all users of a system when verifying if a patch works correctly or not, thereby reducing the effects on the customer's system.

.circle-solid. It is possible to target specific situations for activation down to the per-module, driver, or queue instance level.

.circle-solid. It provides a new tool to improve product quality and shorten development time.

In the preferred embodiment of the invention, dynamic function replacement uses standard SVR4.2 Device Driver Reference STREAMS data structures, although the invention is intended for application to other data structures and other frameworks. The data structures manipulated in the preferred embodiment of the invention are the streamtab and qinit structures. Each module or driver defines a streamtab structure that contains pointers to qinit structures.

qinit structures are for the read, write, read multiplexor, and write multiplexor queues which are created by the STREAMS framework.

qinit structures contain function address for the open, close, put, service, and administrative functions which are invoked by the STREAMS framework on behalf of the queue's owner, i.e. the module or driver.

The functions defined within the qinit structure are actually written by the module or driver developer and are automatically executed by the framework based on the current application execution path, such as a message flowing up or down a stream. Because the STREAMS framework knows the locations of all of these data structures and may access them independently of the application or the module or driver, dynamic function replacement remaps these structure addresses to alternative streamtabs and qinit structures that define the new function addresses. As a default, the STREAMS framework may provide enhancements, such as a standard alternative streamtab for tracing and logging facilities.

To understand the basic principles involved in operation of the invention, the following basic Streams framework data structures are provided. The three data structures of most interest are:

    ______________________________________
    /* Streams queue initialization structure */
    struct qinit {
    int (*qi.sub.-- putp)();
                    /*    Queue put procedure
                                           */
    int (*qi.sub.-- srvp)();
                    /*    Queue service procedure
                                           */
    int (*qi.sub.-- qopen)();
                    /*    Queue open procedure
                                           */
    int (*qi.sub.-- qclose)();
                    /*    Queue close procedure
                                           */
    int (*qi.sub.-- qadmin)();
                    /*    Queue administrative
                                           */
                          procedure
    struct module.sub.-- info * qi.sub.-- minfo;
    struct module.sub.-- stat * qi.sub.-- mstat;
    /* Streams driver and module declaration structure */
    struct streamtab {
    struct qinit * st.sub.-- rdinit;
                    /*    defines read QUEUE
                                           */
    struct qinit * st.sub.-- wrinit;
                    /*    defines write QUEUE
                                           */
    struct qinit * st.sub.-- muxrinit;
                    /*    for multiplexing drivers only
                                           */
    struct qinit * st.sub.-- muxwinit;
                    /*    ditto            */
    }
    /* Streams queue structure */
    struct queue {
    struct qinit * q.sub.-- qinfo;
                    /*    procedures and limits for
                                           */
                          queue
    struct msgb * q.sub.-- first;
                    /*    head of message queue
                                           */
    struct msgb * q.sub.-- last;
                    /*    tail of message queue
                                           */
    struct queue * q.sub.-- next;
                    /*    next QUEUE in Stream
                                           */
    struct queue * q.sub.-- link;
                    /*    link to scheduling queue
                                           */
    void *  q.sub.-- ptr;
                    /*    to private data structure
                                           */
    ulong  q.sub.-- count;
                    /*    weighted count of characters
                                           */
                          on q
    ulong  q.sub.-- flag;
                    /*    QUEUE state      */
    long  q.sub.-- minpsz;
                    /*    min packet size accepted
                                           */
    long  q.sub.-- maxpsz;
                    /*    max packet size accepted
                                           */
    ulong  q.sub.-- hiwat;
                    /*    high water mark, for flow
                                           */
                          control
    ulong  q.sub.-- lowat;
                    /*    low water mark   */
    struct qband * q.sub.-- bandp;
                    /*    band information */
    unsigned char q.sub.-- nband;
                    /*    number of bands  */
    unsigned char q.sub.-- pad1›3!
                    /*    reserved         */
    struct queue * q.sub.-- other;
                    /*    pointer to other Q in queue
                                           */
                          pair
    QUEUE.sub.-- KERNEL.sub.-- FIELDS
    }
    ______________________________________

    ______________________________________
    str.sub.-- alt.sub.-- install(name, flags, n, streamtabs)
    char    *name;     /*    name of module or driver
                                             */
    unsigned int
            flags;     /*    STR.sub.-- IS.sub.-- MODULE/DEVICE
                                             */
    int     n;         /*    number of alternative streamtabs
                                             */
    struct  *streamtabs›!;
                       /*    array of pointers to streamtabs
                                             */
    streamtab
    Str.sub.-- alt.sub.-- install() returns 0 on success and -1 on
    ______________________________________
    failure.

    ______________________________________
    foo.sub.-- rput.sub.-- trace(q, mp)
    ktrc.sub.-- write();
              /*      call NETTL packet tracing routine
                                         */
    foo.sub.-- rput(q, mp);
              /*      call original rput routine
                                         */
    }
    foo.sub.-- rput.sub.-- debug(q, mp)
    {
    /*
    * Original rput routine plus debugging code.
    */
    }
    foo.sub.-- rput.sub.-- timestamp(q, mp)
    {
    timestamp();
              /*      record entry timestamp
                                         */
    foo.sub.-- rput(q, mp);
              /*      call original rput routine
                                         */
    timestamp();
              /*      record exit timestamp
                                         */
    }
    ______________________________________

    ______________________________________
    struct qinit foo.sub.-- rinit.sub.-- trace = {
    foo.sub.-- rput.sub.-- trace,foo.sub.-- rsrv.sub.-- trace,foo.sub.--
    open,foo.sub.-- close,NULL,
    &foo.sub.-- minfo,NULL}
    struct qinit foo.sub.-- rinit.sub.-- debug = {
    foo.sub.-- rput.sub.-- debug,foo.sub.-- rsrv.sub.-- debug,foo.sub.--
    open,foo.sub.-- close,NULL,
    &foo.sub.-- minfo,NULL}
    struct qinit foo.sub.-- rinit.sub.-- timestamp = {
    foo.sub.-- rput.sub.-- timestamp,foo.sub.-- rsrv.sub.-- timestamp,foo.sub.
    -- open,foo.sub.-- close,NULL,
    &foo.sub.-- minfo,NULL}
    ______________________________________

    ______________________________________
    struct streamtab foo.sub.-- trace.sub.-- info
                      = {&foo.sub.-- rinit.sub.-- trace,
                      &foo.sub.-- winit.sub.-- trace};
    struct streamtab foo.sub.-- debug.sub.-- info
                      = {&foo.sub.-- rinit.sub.-- debug,
                      &foo.sub.-- winit.sub.-- debug};
    struct streamtab foo.sub.-- timestamp.sub.-- info
                      = {&foo.sub.-- rinit.sub.-- timestamp,
                      &foo.sub.-- winit.sub.-- timestamp};
    ______________________________________

    ______________________________________
    struct streamtab * streamtabs›3!
                    = {      &foo.sub.-- trace.sub.-- info,
                             &foo.sub.-- debug.sub.-- info,
                             &foo.sub.-- timnestamp.sub.-- info }
    str.sub.-- alt.sub.-- install("foo", STR.sub.-- IS.sub.-- DEVICE, 3,
    streamtabs);
    ______________________________________

    ______________________________________
    subsys.sub.-- id =
               STREAMS
    kind =     PDU.sub.-- IN for M.sub.-- DATA at read-side,
               HDR.sub.-- IN for other message types at read-side,
               PDU.sub.-- OUT for M.sub.-- DATA at write-side,
               HDR.sub.-- OUT for other message types at write-side.
    path.sub.-- id =
               module id
    ______________________________________

    ______________________________________
    long  alt.sub.-- major;
                           /*    major number
                                             */
    long  alt.sub.-- minor;
                           /*    minor number
                                             */
    int   alt.sub.-- index;
                           /*    alternative streamtab
                                             */
                           /*    index
    un-   alt.sub.-- flags;
                           /*    STR.sub.-- IS.sub.-- MODULE/
                                             */
    signed                       DEVICE
    int
    char  alt.sub.-- name›FMNAMESZ+1!;
                           /*    name of module or
                                             */
                                 driver
    ______________________________________

    ______________________________________
    NORMAL.sub.-- L STRTAB
                   Routines in the original streamtab.
    DEFAULT.sub.-- ALT.sub.-- STRTAB
                   Routines in the default alternative
                   streamtab.
    0              Routines in the first streamtab passed
                   via str.sub.-- alt.sub.-- install.
    1              Routines in the second streamtab passed
                   via str.sub.-- alt.sub.-- install.
    .
    .
    N-1            Routines in the Nth streamtab passed via
                   str.sub.-- alt.sub.-- install.
    On failure, errno is set to the following value:
    EACCES         The alt.sub.-- major is not
                   ALT.sub.-- OWN.sub.-- MAJOR and the user does
                   not have the super-privilege.
    EFALUT         The arg points outside the allocated
                   address space.
    EINVAL         The alt.sub.-- name, alt.sub.-- major, alt.sub.-- minor,
                   alt.sub.-- flags, or alt.sub.-- index is
    ______________________________________
                   invalid.

    ______________________________________
    int   alt.sub.-- index;
                           /*    alternative streamtab
                                             */
                                 index
    un-   alt.sub.-- flags;
                           /*    STR.sub.-- IS.sub.-- MODULE/
                                             */
    signed                       DEVICE
    int
    char  alt.sub.-- name›FMNAMESZ+1!;
                           /*    name of module or
                                             */
                                 driver
    ______________________________________

    ______________________________________
    struct modsw {
    struct  d.sub.-- next;  /*    next modsw */
    modsw *
    struct  d.sub.-- prev;  /*    previous modsw
                                             */
    modsw *
    char    d.sub.-- name›FMNAMESZ+1!;
                            /*    unique module
                                             */
                                  name
    char    d.sub.-- flags; /*    OLD.sub.-- OPEN,
                                             */
                                  UP.sub.-- MODE
    SQHP    d.sub.-- sqh;   /*    for module/else-
                                             */
                                  where synch
    int     d.sub.-- curstr;
                            /*    current streamtab
                                             */
                                  index
    struct  d.sub.-- str;   /*    normal streamtab
                                             */
    streamtab *
    struct  d.sub.-- default.sub.-- alt;
                            /*    default alternative
                                             */
    streamtab *                   streamtab
    int     d.sub.-- naltstr;
                            /*    # of alternative
                                             */
                                  streamtabs
    struct  d.sub.-- altstr;
                            /*    alternative streamtab
                                             */
    streamtab *                   array
    int     d.sub.-- sq.sub.-- level
                            /*    synch level
                                             */
    int     d.sub.-- nrefcnt;
                            /*    reference count
                                             */
    int     d.sub.-- major; /*    major # (should be
                                             */
                                  unique)
    };
    ______________________________________

    ______________________________________
    struct modsw * q.sub.-- modsw;
                      /* pointer to struct modsw */
    ______________________________________

    ______________________________________
    I.sub.-- ALTSTRTAB.sub.-- ACTIVE ioctl
    if (alt.sub.-- major == ALT.sub.-- OWN.sub.-- MAJOR)
    current sth is the target stream:
    }
    else
    {
    check the caller's credentials;
    find sth for ›alt.sub.-- major, alt.sub.-- minor!;
    }
    acquire mult.sub.-- sqh lock to prevent plumbing;
    search for the target queue specified by alt.sub.-- name›!;
    q->q.sub.-- qinfo = pointer to the appropriate alternative qinit;
    I.sub.-- ALTSTRTABL.sub.-- FUTRUE ioctl
    check the caller's credentials
    find modsw for module specified by alt.sub.-- name›!;
    modsw.d.sub.-- curstr = alt.sub.-- index;
    ______________________________________

• Inventors
  Krause, Michael R.; Ishijima, Yoshihiro;
• Assignee
  Hewlett-Packard Company (Palo Alto, CA)
• Published
  Sep-29-1998
• Current US Classes:
  719/321
• Application #
  545561
• International Classes
  G06F 009/40
• Field of Search
  395/681
• Examiner
  Oberley; Alvin E.
• US Patent References:
  5338247
  5410694
  5517668
  5548731