Manpage of MI_OPEN_COMM

MI_OPEN_COMM

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

NAME

mi_open_comm, mi_open_comm_cache - STREAMS common minor device open utility

SYNOPSIS

#define _MPS_SOURCE
#include <sys/stream.h>
#include <sys/ddi.h>
#include <sys/mpsddi.h>

int mi_open_comm(caddr_t *head, size_t size, queue_t *q, dev_t *devp, int oflag, int sflag, cred_t *crp);
int mi_open_comm_cache(caddr_t *head, kmem_cachep_t cachep, queue_t *q, dev_t *devp, int oflag, int sflag, cred_t *crp);

ARGUMENTS

head

Specifies the address of a static pointer which will be used internally by mi_open_comm() to store the address of the module's list of open Streams. The pointer that head references should be initialized to NULL before the first call to mi_open_comm() with head as an argument.

size

Specifies the amount of memory the module needs for its per-stream data. It is usually the size of the local structure which contains the module's instance data.

cachep

Specifies the kernel memory cache pointer of a memory cache with appropriately sized objects. The objects in this memory cache can be appropriately sized using the mi_open_size(9) utility.

q

A pointer to the driver or module's read queue, obtained directly from qi_qopen(9).

devp

A pointer to the device number, obtained directly from qi_qopen(9).

oflag

The open flags, obtained directly from qi_qopen(9).

sflag

The stream flags, obtained directly from qi_qopen(9). Specifies how the devp argument is used as follows:

DEVOPEN: The minor device number specified by the devp argument is used.
MODOPEN: The devp argument is NULL. This value should be used if mi_open_comm() is called from the qi_qopen(9) routine of a STREAMS module rather than a STREAMS driver.
CLONEOPEN: A unique minor device number (above 5) is assigned (minor numbers 0 through 5, inclusive, are reserved as special access codes).

crp

A pointer to the credentials of the opening user, obtained directly from qi_qopen(9).

INTERFACE

MPS®-specific DDI.

DESCRIPTION

mi_open_comm() and mi_open_comm_cache() perform housekeeping during STREAMS driver or module qi_qopen(9) operations. mi_open_comm() and mi_open_comm_cache() are intended to be called by the driver or module qi_qopen(9) procedure. They assign a minor device number to the stream (as specified by the sflag argument), allocate the requested per-stream data, and set the q_ptr fields of the stream being opened.

Each call to mi_open_comm() must have a corresponding call to mi_close_comm(9).

Each call to mi_open_comm_cache() must have a corresponding call to mi_close_comm_cache(9).

RETURN

When mi_open_comm() and mi_open_comm_cache() succeed, they return zero (0); when they fail, they return a non-zero error code.

ERRORS

When mi_open_comm() and mi_open_comm_cache() fail they return a non-zero error code as follows:

[ENXIO]: an argument to the call is invalid.
[EAGAIN]: an internal structure could not be allocated and the call should be retried.

These error codes are selected so that they can be returned directly from qi_qopen(9).

CONTEXT

mi_open_comm() and mi_open_comm_cache() can be called from User Context. mi_open_comm() and mi_open_comm_cache() are normally called from within a STREAMS module's qi_qopen(9) procedure (User Context).

MP-STREAMS

mi_open_comm() and mi_open_comm_cache() are MP-safe.

NOTICES

mi_open_comm() and mi_open_comm_cache() are MPS®-specific functions: _MPS_SOURCE, _AIX_SOURCE or _MAC_SOURCE must be defined before including DDI/DKI include files to expose these symbols. OpenSS7 STREAMS Compatibility must also have been compiled with CONFIG_STREAMS_COMPAT_MPS, CONFIG_STREAMS_COMPAT_MPS_MODULE, CONFIG_STREAMS_COMPAT_AIX, CONFIG_STREAMS_COMPAT_AIX_MODULE, CONFIG_STREAMS_COMPAT_MAC or CONFIG_STREAMS_COMPAT_MAC_MODULE defined.

IMPLEMENTATION

mi_open_comm() performs some sanity checks on the arguments that are passed to it, calls mi_open_alloc_sleep(9) to acquire the private structure and then calls mi_open_link(9) to link the private structure into the list and mi_attach(9) to attach the private structure to the q_ptr members of each queue in the queue pair.

mi_open_comm_cache() performs some sanity checks on the arguments that are passed to it, calls mi_open_alloc_cache(9) to acquire the private structure and then calls mi_open_link(9) to link the private structure into the list and mi_attach(9) to attach the private structure to the q_ptr members of each queue in the queue pair.

EXAMPLES

Following is an example of a module qi_qopen(9) procedure using mi_open_comm():


static caddr_t xxx_state = NULL;
typedef struct {
    dev_t my_dev;
    queue_t *rq;
    long some_data;
    long some_more_data;
} xxx_priv_t;
int
xxx_open(queue_t *q, dev_t *devp, int oflag, int sflag,
         cred_t *crp)
{
    int err;
    xxx_priv_t *priv;
err = mi_open_comm(&xxx_state, sizeof(xxx_priv_t),
                       q, devp, oflag, sflag, crp);
    if (err != 0) {
        return (err);
    }
priv = q->q_ptr;
priv->my_dev = *devp;
    priv->rq = q;
    priv->some_data = SOME_DATA_INITIALIZER;
    priv->some_more_data = SOME_MORE_DATA_INITIALIZER;
return (0);
}

BUGS

mi_open_comm() and mi_open_comm_cache() have no known bugs.

COMPATIBILITY

mi_open_comm() is compatible with MPS®, AIX®, MacOT®, and Solaris®, with the following portability considerations:

---: mi_open_comm() is an MPS®-specific function and should not be used by portable STREAMS drivers and modules.
---: Use of mi_open_comm() requires different include file sequences on OpenSS7 STREAMS Compatibility[1] than on AIX® or MacOT®. AIX® includes <pse/mi.h> and <sys/stream.h> only.
---: mi_open_comm() is provided for source level compatibility with MPS® for the purpose of porting MPS® drivers to Linux. Because internal structures and definitions for OpenSS7 STREAMS Compatibility[1] differ from that of MPS®, binaries are incompatible.
---: mi_open_comm() only provides functionality comparable to MPS® for use by STREAMS drivers and modules. Any and all functionality provided by mi_open_comm() in support of non-STREAMS devices are not supported.

See mpscompat(9), aixcompat(9), maccompat(9), and STREAMS(9) for additional compatibility considerations.

mi_open_comm_cache() is an OpenSS7 Project specific implementation of mi_open_comm() that is inherently non-portable. While it is fairly straightforward to implement these in any Mentat implementation present on modern day UNIX systems, it requires exposing internals to the MPS implementation that might not be desirable.

CONFORMANCE

MPS® DDI documentation, MacOT® DDI documentation[2, 3], AIX® documentation[4], The OpenSS7 Project.

HISTORY

mi_open_comm() first appeared in MPS®. mi_open_comm() is a Mentat, Inc. function that goes all the way back to the pre-OSF/1 Mentat implementations. mi_open_comm() appears in MacOT®[3] and AIX®[4]. An undocumented version of mi_open_comm() appears in Solaris®.

mi_open_comm_cache() is an OpenSS7 Project function based loosely on the mi_open_comm() Mentat function.

REFERENCES

[1]: strcompat-0.9.2, STREAMS Compatibility Modules (strcompat) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: Mac OS 9, Open Transport Reference, 2003, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macros/opentransport/>
[3]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>
[4]: AIX® 5L Version 5.1, AIX Communications Programming Concepts, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

OpenSS7 STREAMS Compatibility: Package strcompat version 0.9.2.7 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
INTERFACE
DESCRIPTION
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
IMPLEMENTATION
EXAMPLES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 14:24:54 GMT, May 23, 2013