QINIT

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

qinit - STREAMS queue initialization structure

SYNOPSIS


typedef int (*qi_putp_t) (queue_t *, mblk_t *);
typedef int (*qi_srvp_t) (queue_t *);
typedef int (*qi_qopen_t) (queue_t *, dev_t *, int, int, cred_t *);
typedef int (*qi_qclose_t) (queue_t *, int, cred_t *);
typedef int (*qi_qadmin_t) (void);
struct qinit {
    qi_putp_t qi_putp;            /* put procedure */
    qi_srvp_t qi_srvp;            /* service procedure */
    qi_qopen_t qi_qopen;          /* each open (read q only) */
    qi_qclose_t qi_qclose;        /* last close (read q only) */
    qi_qadmin_t qi_qadmin;        /* admin procedure (not used) */
    struct module_info *qi_minfo; /* module info */
    struct module_stat *qi_mstat; /* module stats */
};

MEMBERS

The following are SVR 4.2 EFT[1] members:

qi_putp: driver or module qi_putp(9) procedure.
qi_srvp: driver or module qi_srvp(9) procedure
qi_qopen: driver or module qi_qopen(9) routine.
qi_qclose: driver or module qi_qclose(9) routine.
qi_qadmin: driver or module qi_qadmin(9) routine.
qi_minfo: driver or module defining module_info(9) structure.
qi_mstat: driver or module statistics module_stat(9) structure.

There are no Linux Fast-STREAMS specific members associated with the qinit structure.

INTERFACE

STREAMS.

DESCRIPTION

The qinit structure, defined in <sys/stream.h>, is a statically allocated structure that is used in the definition of a STREAMS driver or module. When a Stream is created as a result of a call to open(2s) or pipe(2s), particulars about the Stream head and driver queue pair are initialized to point to (usually two of) these structures.

Pointers to two or four qinit structures are used as the primary definition of a STREAMS driver or module in the streamtab(9) structure. Two qinit structures are referenced for the read and write side of a module, and two pairs of qinit structures are referenced for the read and write side of a driver, one pair for the upper multiplexer and another for the lower multiplexer for a multiplexing driver.

Module and Driver Entry Points

The qi_putp, qi_srvp, qi_qopen, qi_qclose, and qi_qadmin represent the primary functional entry points into the driver or module and are invoked at the appropriate times by the STREAMS scheduler. These are synchronous entry points in the sense that MP-STREAMS(9) synchronization is performed at each entry point predicated on q.

The qi_putp and qi_srvp fields are significant in each qinit structure associated with a queue(9). The qi_qopen, qi_qclose, and qi_qadmin members are only significant in the qinit structure associated with the read-side queue(9) structure. STREAMS ignores the values of the qi_qopen, qi_qclose, and qi_qadmin, function pointers in the qinit structure associated with the write-side queue(9) structure of a queue pair.

qi_qopen specifies the qi_qopen(9) routine for the driver or module. The qi_qopen(9) routine is called whenever a new queue pair forming an instance of the driver or module is allocated, initialized and inserted into a Stream, or whenever existing Stream is reopened, for each driver and module in the Stream. This routine permits the driver or module to perform whatever driver or module private initialization is necessary before the queue pair becomes active in the Stream, or to respond to a subsequent opening of the Stream. Error numbers returned by this function are reflected as error numbers returned in errno(3) from the open(2s) or I_PUSH(2s) operation that invoked the routine. All drivers and modules must have a qi_qopen routine defined. See qi_qopen(9) for details.

qi_qclose specifies the qi_qclose(9) routine for the driver or module. The qi_qclose(9) routine is called before a queue pair forming an instance of the driver or module is removed from the Stream and deallocated. This routine permits the driver or module to perform whatever driver or module private cleanup or deallocation is necessary before the queue pair is deactivated and removed from the Stream. Error numbers returned by this function are generally discarded. All drivers and modules must have a qi_qclose routine defined. See qi_qclose(9) for details.

qi_putp specifies the qi_putp(9) procedure for the driver or module. The qi_putp(9) procedure is invoked during active use of the queue pair whenever a message is passed to either queue of the queue pair, in either direction along the Stream, using the put(9) or putnext(9) STREAMS utilities. This procedure is responsible for processing, passing along, or queueing the message passed to the queue. A separate qi_putp(9) procedure is normally associated with each queue in the queue pair forming an instance of the module or driver. The return value of the qi_putp(9) procedure is ignored by STREAMS. All drivers and modules must have a qi_putp procedure defined. See qi_putp(9) for details.

qi_srvp specifies the qi_srvp(9) procedure for the driver or module. The qi_srvp(9) procedure for a driver or module services the messages that are placed on the corresponding message queue. The qi_srvp(9) procedure is invoked by the STREAMS scheduler. Queues are scheduled to have their qi_srvp(9) procedures executed (when a qi_srvp(9) procedure is specified) by STREAMS utility functions that queue or dequeue messages from message queues within the Stream. The return value of the qi_srvp(9) procedure is ignored by STREAMS. It is optional for a driver or module to define a qi_srvp(9) procedure: if one is not defined, qi_srvp is set to NULL. See qi_srvp(9) for details.

qi_qadmin specifies the administrative routine return by getadmin(9) for the driver or module. The qi_qadmin function pointer is for a module private administrative function that is not normally used. STREAMS never invokes the qi_qadmin function; however, the getadmin(9) utility can be used to locate this function and it may be invoked by a driver or module procedure, or by any other kernel subsystem at the module designer's option. It is optional for a driver or module to define a getadmin(9) procedure: normally, qi_qadmin is set to NULL. See qi_qadmin(9) for details.

For a description of the use and guidelines for the qi_qadmin, qi_qopen, qi_qclose, qi_putp, and qi_srvp, functions provided by a driver or module, see getadmin(9), qi_qopen(9), qi_qclose(9), qi_putp(9), and qi_srvp(9).

Initialization

The qi_minfo member points to a module_info(9) structure that contains the name and identifier for the driver or module. The qi_minfo module_info(9) structure also contains the initialization queue packet size and flow control limits used to initialize queue(9) structures when a queue pair is formed.

Four members of the queue(9) structure, q_minpsz, q_maxpsz, q_hiwat, q_lowat, are initialized from the corresponding members of the module_info(9) structure, mi_minpsz, mi_maxpsz, mi_hiwat, mi_lowat, pointed to by this structure. These members of the queue(9) structure are initialized from the associated qinit structure's referenced module_info(9) structure. The remaining two fields of the module_info(9) structure, mi_idnum, and mi_idname, provide read-only information concerning the module identification number [see getmid(9)] and module name, associated with the driver or module.

See queue(9) and module_info(9) for more information.

Statistics

The qi_mstat member points to a module_stat(9) structure that contains collected statistics for the module. Statistics include the number of times that each of the procedures were called as well a private statistics. As the read and write side queues can point to different qinit structures, a module_stat(9) structure can be associated with each queue in the queue pair, or they can share one module_stat(9) structure. Providing a module_stat(9) structure is optional: when not provided, the qi_mstat member is set to NULL.

STREAMS will not maintain the statistics in this structure whether it is provided or not. It is the responsibility of the driver or module designer to increment counts in this structure as is appropriate to the module. Nevertheless, if an module_stat(9) structure is provided, its counts can be examined with system administration utilities such as scls(8).

See module_stat(9) for more information.

USAGE

The qinit structure is statically allocated and associated with a statically allocated streamtab(9) structure to define a STREAMS driver or module.

Once the associated streamtab(9) structure has been registered with the STREAMS subsystem as a driver or module, all fields in the structure must be treated as read-only by a driver or module. The following guidelines pertain to the use of the fields in the qinit structure:

*: Function pointers qi_qadmin, qi_qopen, qi_qclose, qi_putp, qi_srvp, must not be altered after the streamtab (9) structure is registered.
*: Of theses, only qi_qadmin can be called directly by the a driver or module. qi_qopen must only be called indirectly using the open(2s) or I_PUSH(7) ioctl(2s). qi_qclose must only be called indirectly using the close(2s) or I_POP(7) ioctl(2s). qi_putp must only be called via the appropriate STREAMS utility functions: put(9) and putnext(9), and then only in the appropriate contexts.
*: qi_srvp must only be called by the STREAMS scheduler; that is, invoked with the STREAMS utility functions: qenable(9), putq(9), putbq(9), or any utility invoking back-enabling.
*: The qi_minfo pointer must not be modified after registration. The point can, however, be read directly to find the location of the module_info(9) structure that corresponds to a given queue, queue pair or module. See module_info(9) for restrictions on the use of its members.
*: The qi_mstat pointer must not be modified after registration. The pointer can, however, be read directly to find the location of the module_stat(9) structure that corresponds to a given queue pair or module. See module_stat(9) for restrictions on the use of its members.
*: The pointers to qinit structure from the streamtab(9) structure for a driver or module must not be altered after the streamtab(9) structure has been registered.
*: The pointer to a qinit structure contained within the queue(9) structure must only be altered by the Stream head.

EXAMPLES

This example is taken directly from the bufmod(4) test module, located in the src/modules/bufmod.c source file in the streams-0.9.2.4 distribution. The declarations provide an example of static declaration of qinit and associated structures to define a module:

 1  int bufmod_wput(queue_t *, mblk_t *);
 2  int bufmod_wsrv(queue_t *);
 3  
 4  int bufmod_rput(queue_t *, mblk_t *);
 5  int bufmod_rsrv(queue_t *);
 6  
 7  int bufmod_open(queue_t *, dev_t *, int, cred_t *);
 8  int bufmod_close(queue_t *, dev_t *, cred_t *);
 9  
10  static struct module_info bufmod_minfo = {
11      .mi_idnum = 0,
12      .mi_idname = "bufmod",
13      .mi_minpsz = STRMINPSZ,
14      .mi_maxpsz = STRMAXPSZ,
15      .mi_hiwat = STRHIGH,
16      .mi_lowat = STRLOW,
17  };
18  
19  static struct qinit bufmod_rinit = {
20      .qi_putp = bufmod_rput,
21      .qi_srvp = bufmod_srv,
22      .qi_qopen = bufmod_open,
23      .qi_qclose = bufmod_close,
24      .qi_minfo = &bufmod_minfo,
25  };
26  
27  static struct qinit bufmod_winit = {
28      .qi_putp = bufmod_wput,
29      .qi_srvp = bufmod_srv,
30      .qi_minfo = &bufmod_minfo,
31  };
32  
33  static struct streamtab bufmod_info = {
34      .st_rdinit = &bufmod_rinit,
35      .st_wrinit = &bufmod_winit,
36  };

At lines 19 through 25 and lines 27 through 31, the qinit structures for the read and write queues are defined. These qinit structures are referenced by the streamtab(9) structure that defines the module, at lines 33 through 36.

For more examples of declarations, see any of the drivers or modules in the streams-0.9.2.4 distribution source code directories: src/modules and src/drivers.

COMPATIBILITY

The qinit structure is compatible with SVR 4.2 EFT MP[1]. and implementations based on SVR 4 EFT[2], with the following portability considerations:

---: SVR 4[2] provided two different prototypes for the qi_qopen function pointer, depending on whether the xxxflag symbol was defined or not. If the xxxflag symbol was not defined, the prototype defaulted to SVR 3-style for qi_qopen(9) and qi_qclose(9) procedures. If the xxxflag was defined, the prototype became SVR 4-style for qi_qopen(9) and qi_qclose(9) procedures. Linux Fast-STREAMS only provides an SVR 4-style prototype for qi_qopen and qi_qclose.
: Portable STREAMS drivers and modules will be written to SVR 4 instead of SVR 3.
---: Aside from the above, the qinit structure is very consistent across implementations.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 EFT MP[1].

HISTORY

The qinit structure first appeared in SVR 3[3].

REFERENCES

[1]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.