[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Communications, Volume 2


str_install Utility

Purpose

Installs streams modules and drivers.

Syntax

#include <sys/strconf.h>


int
str_install(cmd, conf)
int cmd;
strconf_t * conf;

Description

The str_install utility adds or removes Portable Streams Environment (PSE) drivers and modules from the internal tables of PSE. The extension is pinned when added and unpinned when removed (see the pincode kernel service). It uses a configuration structure to provide sufficient information to perform the specified command.

The configuration structure, strconf_t, is defined as follows:

typedef struct {
        char *sc_name;
        struct streamtab *sc_str;
        int sc_open_stylesc_flags;
        int sc_major;
        int sc_sqlevel;
        caddr_t sc_sqinfo;
} strconf_t;

The elements of the strconf_t structure are defined as follows:

sc_name Specifies the name of the extension in the internal tables of PSE. For modules, this name is installed in the fmodsw table and is used for I_PUSH operations. For drivers, this name is used only for reporting with the scls and strinfo commands.
sc_str Points to a streamtab structure.
sc_open_stylesc_flags Specifies the style of the driver or module open routine. The acceptable values are:

STR_NEW_OPEN
Specifies the open syntax and semantics used in System V Release 4.

STR_OLD_OPEN
Specifies the open syntax and semantics used in System V Release 3.

If the module is multiprocessor-safe, the following flag should be added by using the bitwise OR operator:

STR_MPSAFE
Specifies that the extension was designed to run on a multiprocessor system.

If the module uses callback functions that need to be protected against interrupts (non-interrupt-safe callback functions) for the timeout or bufcall utilities, the following flag should be added by using the bitwise OR operator:

STR_QSAFETY
Specifies that the extension uses non-interrupt-safe callback functions for the timeout or bufcall utilities.

This flag is automatically set by STREAMS if the module is not multiprocessor-safe.

STR_PERSTREAM
Specifies that the module accepts to run at perstream synchronization level.

STR_Q_NOTTOSPEC
Specifies that the extension is designed to run it's service routine under process context.

By default STREAMS service routine runs under interrupt context (INTOFFL3). If Streams drivers or modules want to execute their service routine under process context (INTBASE), they need to set this flag.

STR_64BIT
Specifies that the extension is capable to support 64-bit data types.

STR_NEWCLONING
Specifies the driver open uses new-style cloning. Under this style, the driver open() is not checking for CLONEOPEN flag and returns new device number.
sc_major Specifies the major number of the device.
sc_sqlevel Reserved for future use. Specifies the synchronization level to be used by PSE. There are seven levels of synchronization:

SQLVL_NOP No synchronization
Specifies that each queue can be accessed by more than one thread at the same time. The protection of internal data and of put and service routines against the timeout or bufcall utilities is done by the module or driver itself. This synchronization level should be used essentially for multiprocessor-efficient modules.

SQLVL_QUEUE Queue Level
Specifies that each queue can be accessed by only one thread at the same time. This is the finest synchronization level, and should only be used when the two sides of a queue pair do not share common data.

SQLVL_QUEUEPAIR Queue Pair Level
Specifies that each queue pair can be accessed by only one thread at the same time.

SQLVL_MODULE Module Level
Specifies that all instances of a module can be accessed by only one thread at the same time. This is the default value.

SQLVL_ELSEWHERE Arbitrary Level
Specifies that a group of modules can be accessed by only one thread at the same time. Usually, the group of modules is a set of cooperating modules, such as a protocol family. The group is defined by using the same name in the sc_sqinfo field for each module in the group.

SQLVL_GLOBAL Global Level
Specifies that all of PSE can be accessed by only one thread at the same time. This option should normally be used only for debugging.

SQLVL_DEFAULT Default Level
Specifies the default level, set to SQLVL_MODULE.
sc_sqinfo Specifies an optional group name. This field is only used when the SQLVL_ELSEWHERE arbitrary synchronization level is set; all modules having the same name belong to one group. The name size is limited to eight characters.

Parameters


cmd Specifies which operation to perform. Acceptable values are:

STR_LOAD_DEV
Adds a device into PSE internal tables.

STR_UNLOAD_DEV
Removes a device from PSE internal tables.

STR_LOAD_MOD
Adds a module into PSE internal tables.

STR_UNLOAD_MOD
Removes a module from PSE internal tables.
conf Points to a strconf_t structure, which contains all the necessary information to successfully load and unload a PSE kernel extension.

Return Values

On successful completion, the str_install utility returns a value of 0. Otherwise, it returns an error code.

Error Codes

On failure, the str_install utility returns one of the following error codes:

EBUSY The PSE kernel extension is already in use and cannot be unloaded.
EEXIST The PSE kernel extension already exists in the system.
EINVAL A parameter contains an unacceptable value.
ENODEV The PSE kernel extension could not be loaded.
ENOENT The PSE kernel is not present and could not be unloaded.
ENOMEM Not enough memory for the extension could be allocated and pinned.
ENXIO PSE is currently locked for use.

Implementation Specifics

This utility is part of STREAMS Kernel Extensions.

Related Information

The pincode kernel service, unpincode kernel service.

The streamio operations.

Configuring Drivers and Modules in the Portable Streams Environment (PSE) and List of Streams Programming References in AIX 5L Version 5.1 Communications Programming Concepts.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]