OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 16:47:04 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci


MI_TIMER

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Wed, 16 Aug 2017 02:07:16 GMT
Index Return to Main Contents

NAME

mi_timer - schedule a M_PCSIG(9) STREAMS message for a future time

SYNOPSIS

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

void mi_timer(mblk_t *mp, ulong msec);

#define _SUN_SOURCE

#include <sys/ddi.h>
#include <sys/sunddi.h>
void mi_timer(queue_t *q, mblk_t *mp, ulong msec);

ARGUMENTS

q

a pointer to the STREAMS queue onto which to place the M_PCSIG(9) message when the timer expires. This pointer will be used as the argument to a putq(9) command when the timer expires. In the MacOT® form of the function, this argument is provided in the previous call to mi_timer_alloc(9). In the Solaris® form of the function, this argument is present here, but not in the call to mi_timer_alloc(9).
mp
a pointer to the M_PCSIG(9) message block that was allocated with mi_timer_alloc(9). This message block can also contain additional user data.
msec
the duration in milliseconds before timer expiry. The Solaris® form of mi_timer() accept two special values of msec as follows:
(clock_t)(-1)
the special value (minus one) requests that the timer be cancelled instead of scheduled. This is equivalent to calling mi_timer_stop(9).
(clock_t)(-2)
the special value (minus two) requests that the timer be moved to a new target queue instead of rescheduled. This is equivalent to calling mi_timer_move(9).

INTERFACE

MPS®-specific DDI.

DESCRIPTION

mi_timer() will schedule the mp message pointer (which must be created using mi_timer_alloc(9)) to be placed on the target STREAMS queue at the specified future time. mi_timer_valid(9) must be used in the target queue put or service procedure whenever a M_PCSIG(9) message is dequeued.

If the M_PCSIG(9) message block is freshly allocated with mi_timer_alloc(9) then mi_timer() schedules a timeout(9) that, upon expiry, will place the message block on the target queue.

If the message block already has a running timer associated with it, mi_timer() will cancel the previous timeout(9) and reschedule the timer. This occurs even if the timeout(9) has just expired and the message block has already been placed on the target queue. In this case mi_timer(9) marks the message block for rescheduling that will be performed when the message is dequeued and examined with mi_timer_valid(9) the timeout(9) will be rescheduled.

USAGE

mi_timer() is one of a set of timer functions including mi_timer(), mi_timer_alloc(9), mi_timer_cancel(9), mi_timer_free(9), mi_timer_move(9), mi_timer_q_switch(9), mi_timer_stop(9), mi_timer_valid(9), that are used to abstract the kernel timer functions and provide synchronization with STREAMS message queues.

Timers are abstracted in the following way:

When a timer is first created, a message block is allocated and associated with the timer. In general, a large amount of information can be associated with a timer by placing the information in the message block, see mi_timer_alloc(9). When the timer is set, see mi_timer(), normal kernel timeout functions are called. When the timeout occurs, the message block associated with the timer is placed on a specified queue with putq(9) as a M_PCSIG(9) message type. When the timer is processed by the queue qi_putp(9) or qi_srvp(9) procedure, mi_timer_valid(9) is called to ensure that the timer is still valid and the timeout action is otherwise performed. Timers can be freed, mi_timer_free(9), moved between target queues, mi_timer_move(9), mi_timer_q_switch(9), reset, mi_timer(), or stopped, mi_timer_cancel(9), mi_timer_stop(9).

One possible reason for this convoluted approach to timers could be that some STREAMS implementations place heavy restrictions upon which STREAMS utilities can be called from without a timeout(9) callback function. The OpenSS7 Project has no such restriction, and STREAMS timeout(9) callbacks can even be syncrhonized with queue procedures. See mp-streams(9) for more information.

Therefore, the mi_timer() functions are of limited utility on The OpenSS7 Project.

RETURN

mi_timer() returns void.

ERRORS

mi_timer() always succeeds. If mi_timer() is passed a NULL or invalid message pointer, or a pointer that points to an invalid structure, the kernel may destabilize and a kernel panic may ensue.

EXAMPLE

Following is an example using the MacOT® variants of mi_timer():


#define NTIMERS 5
static caddr_t xxx_list = NULL;
typedef struct xxx_priv {
     ulong some_data;
     mblk_t *timers[NTIMERS];
} xxx_priv_t;
#define PRIVSZ (sizeof(xxx_priv_t))
int
xxx_open(queue_t *q, dev_t *devp, int flag, int sflag,
         cred_t *crp)
{
     int err;
     err = mi_open_comm(&xxx_list, PRIVSZ, devp,
                        flag, sflag, crp);
     if (err == 0) {
          xxx_priv_t *p = (typeof(p)) q->q_ptr;
          int i;
          for (i = 0; i < NTIMER; i++) {
               p->timers[i] =
                   mi_timer_alloc(q, sizeof(int));
               *(int *) (p->timers[i]->b_rptr) = i;
          }
          qprocson(q);
     }
     return (err);
}
int
xxx_close(queue_t *q, int oflag, cred_t *crp)
{
     xxx_priv_t *p = (xxx_priv_t *) q->q_ptr;
     int i;
     qprocsoff(q);
     mi_detach(q, (caddr_t) p);
     for (i = 0; i < NTIMER; i++)
          if (p->timers[i])
               mi_timer_free(p->timers[i]);
     mi_close_detached(&xxx_list, (caddr_t) p);
     return (0);
}
int
xxx_rput(queue_t *q, mblk_t *mp)
{
     xxx_priv_t *p = (xxx_priv_t *) q->q_ptr;
     switch (mp->b_datap->db_type) {
     case M_DATA:
          /* ... */
     case M_PROTO:
          /* ... */
     case M_PCSIG:
          if (mi_timer_valid(mp)) {
               int i = *(int *) (mp->b_rptr);
               switch (i) {
               case 0:
                    /* timeout action 1 */
                    mi_timer_cancel(p->timers[4]);
                    mi_timer(p->timers[3], 2000);
                    break;
               case 1:
                    /* timeout action 2 */
               case 2:
                    /* timeout action 3 */
               case 3:
                    /* timeout action 4 */
               case 4:
                    /* timeout action 5 */
               }
          }
          return (0);
          /* ... */
     case M_FLUSH:
          /* ... */
     }
}

Following is an example using the Solaris® variants of mi_timer():

For Solaris®, in the open procedure we use: (Notice the lack of a q argument to mi_timer_alloc(9).)


          for (i = 0; i < NTIMER; i++) {
               p->timers[i] =
                   mi_timer_alloc(sizeof(int));
               *(int *) (p->timers[i]->b_rptr) = i;
          }

and in the put procedure we use: (Notice the addition of a q argument to mi_timer().)


     case M_PCSIG:
          if (mi_timer_valid(mp)) {
               int i = *(int *) (mp->b_rptr);
               switch (i) {
               case 0:
                    /* timeout action 1 */
                    mi_timer_cancel(p->timers[4]);
                    mi_timer(q, p->timers[3], 2000);
                    break;
               case 1:
                    /* ... */
               }
          }

CONTEXT

mi_timer() must not be called from a priority level higher than a timeout. On Linux this means that mi_timer() must not be called from an interrupt service routine. To place the call at the same priority level, schedule a tasklet to make the call.

MP-STREAMS

mi_timer() is MP-safe when called from the correct context. When using the functions in the proscribed fashion, the called need not guarantee exclusive access to the passed in message block or queue. The MacOT® flavor of the functions use a double race-breaking state machine to provide MP safety. The Solaris® flavor of the functions have a race condition only in mi_timer_move(9), and this a call to mi_timer() with the special msec value of minus two (-2).

NOTICES

mi_timer() is an MPS®-specific function with MacOT® and Solaris® variants: _MPS_SOURCE, _SUN_SOURCE or _MAC_SOURCE must be defined before including DDI/DKI include files to expose this symbol. The OpenSS7 Project must also have been compiled with CONFIG_STREAMS_COMPAT_MPS, CONFIG_STREAMS_COMPAT_MPS_MODULE, CONFIG_STREAMS_COMPAT_SUN, CONFIG_STREAMS_COMPAT_SUN_MODULE, CONFIG_STREAMS_COMPAT_MAC or CONFIG_STREAMS_COMPAT_MAC_MODULE defined.

IMPLEMENTATION

Some versions of mi_timer() place the message block onto the target queue, bypassing the queue's put procedure. These variants only work for queues that have service procedures. The The OpenSS7 Project implementation of mi_timer() also uses putq(9) to place the message block on the target queue, thus the queue requires a service procedure.

SEE ALSO

mi_timer_alloc(9), mi_timer_cancel(9), mi_timer_free(9), mi_timer_valid(9), mpscompat(9), suncompat(9), maccompat(9), STREAMS(9).

BUGS

mi_timer() has no known bugs.

COMPATIBILITY

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

---
mi_timer() is an MPS®-specific function and should not be used by portable STREAMS drivers and modules. The more common timeout(9) function should be used in its stead.
---
mi_timer() is provided for source level compatibility with MPS® for the purpose of porting MPS® drivers to Linux. Because internal structures and definitions for The OpenSS7 Project[1] differ from that of MPS®, binaries are incompatible.
---
mi_timer() only provides functionality comparable to MPS® for use by STREAMS drivers and modules. Any and all functionality provided by mi_timer() in support of non-STREAMS devices are not supported.

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

CONFORMANCE

MPS® DDI documentation, MacOT® DDI documentation[2, 3].

HISTORY

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

REFERENCES

[1]
TCI, Transaction Component Interface (TCI) Specification, Revision 0.9.2, Draft 2, July 15, 2007, (Edmonton, Alberta), TheOpenSS7Project, OpenSS7Corporation. Distributed with package strss7-0.9.2. <http://www.openss7.org/docs/tci.pdf>
[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/>

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

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Wed, 16 Aug 2017 02:07:16 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

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

This document was created by man2html, using the manual pages.
Time: 02:07:16 GMT, August 16, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Last modified: Mon, 28 Apr 2008 16:47:04 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.