Links

GitHub

Open HUB

Quick Links

Download

STREAMS

SIGTRAN

SS7

Hardware

SCTP

Related

Package

Manual

FAQ

Library

SDLI Tech Spec

SDTI Tech Spec

SLI Tech Spec

MTPI Tech Spec

TRI Tech Spec

TCI Tech Spec

ISUPI Tech Spec

BICCI Tech Spec

MAPI Tech Spec

CDI Tech Spec

DLPI Tech Spec

NPI Tech Spec

TPI Tech Spec

WAN Tech Spec

LLI Tech Spec

NLI Tech Spec

CHI Tech Spec

MXI Tech Spec

MGI Tech Spec

XCC Tech Spec

XGCP Tech Spec

XMAP Tech Spec

Resources

Packages

Sys Req

Repositories

Download

Mailing Lists

Browse Source

CVS Archive

Bug Reports

Library

Hardware

Vendor Links

Home

Overview

Status

Documentation

Resources

About

News

CHI Technical Specification

Description: OpenSS7 Project Library CHI

A PDF version of this document is available here.

Channel Interface (CHI)

Channel Interface (CHI) Specification

About This Manual

This is Edition 7.20141001, last updated 2014-10-25, of The Channel Interface (CHI) Specification, for Version 1.1 release 7.20141001 of the OpenSS7 package.


Preface

Notice

Software in this document and related software is released under the AGPL (see GNU Affero General Public License). Please note, however, that there are different licensing terms for some of the manual package and some of the documentation. Consult permission notices contained in the documentation of those components for more information.

This document is released under the FDL (see GNU Free Documentation License) with no invariant sections, no front-cover texts and no back-cover texts.

Abstract

This document is a Specification containing technical details concerning the implementation of the Channel Interface (CHI) for OpenSS7. It contains recommendations on software architecture as well as platform and system applicability of the Channel Interface (CHI).

This document specifies a Channel Interface (CHI) Specification in support of the OpenSS7 Channel (CH) protocol stacks. It provides abstraction of the Channel interface to these components as well as providing a basis for Channel control for other Channel protocols.

Purpose

The purpose of this document is to provide technical documentation of the Channel Interface (CHI). This document is intended to be included with the OpenSS7 STREAMS software package released by OpenSS7 Corporation. It is intended to assist software developers, maintainers and users of the Channel Interface (CHI) with understanding the software architecture and technical interfaces that are made available in the software package.

Intent

It is the intent of this document that it act as the primary source of information concerning the Channel Interface (CHI). This document is intended to provide information for writers of OpenSS7 Channel Interface (CHI) applications as well as writers of OpenSS7 Channel Interface (CHI) Users.

Audience

The audience for this document is software developers, maintainers and users and integrators of the Channel Interface (CHI). The target audience is developers and users of the OpenSS7 SS7 stack.

Revision History

Take care that you are working with a current version of this documentation: you will not be notified of updates. To ensure that you are working with a current version, check the OpenSS7 Project website for a current version.

A current version of this specification is normally distributed with the OpenSS7 package, openss7-1.1.7.20141001.1

Version Control

Although the author has attempted to ensure that the information in this document is complete and correct, neither the Author nor OpenSS7 Corporation will take any responsibility in it. OpenSS7 Corporation is making this documentation available as a reference point for the industry. While OpenSS7 Corporation believes that these interfaces are well defined in this release of the document, minor changes may be made prior to products conforming to the interfaces being made available. OpenSS7 Corporation reserves the right to revise this software and documentation for any reason, including but not limited to, conformity with standards promulgated by various agencies, utilization of advances in the state of the technical arts, or the reflection of changes in the design of any techniques, or procedures embodied, described, or referred to herein. OpenSS7 Corporation is under no obligation to provide any feature listed herein.

$Log: chi.texi,v $
Revision 1.1.2.2  2011-02-07 02:21:38  brian
- updated manuals

Revision 1.1.2.1  2009-06-21 11:50:35  brian
- added files to new distro

ISO 9000 Compliance

Only the TeX, texinfo, or roff source for this maual is controlled. An opaque (printed, postscript or portable document format) version of this manual is a UNCONTROLLED VERSION.

Disclaimer

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infrincement, or title; that the contents of the manual are suitable for any purpose, or that the implementation of such contents will not infringe on any third party patents, copyrights, trademarks or other rights. In no event shall OpenSS7 Corporation be liable for any direct, indirect, special or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action or contract, negligence or other tortious action, arising out of or in connection with any use of this documentation or the performance or implementation of the contents thereof.

U.S. Government Restricted Rights

If you are licensing this Software on behalf of the U.S. Government ("Government"), the following provisions apply to you. If the Software is supplied by the Department of Defense ("DoD"), it is classified as "Commercial Computer Software" under paragraph 252.227-7014 of the DoD Supplement to the Federal Aquisition Regulations ("DFARS") (or any successor regulations) and the Government is acquiring only the license rights granded herein (the license rights customarily provided to non-Government users). If the Software is supplied to any unit or agency of the Government other than DoD, it is classified as "Restricted Computer Software" and the Government’s rights in the Software are defined in paragraph 52.227-19 of the Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplerment to the FAR (or any successor regulations).

Acknowledgements

The OpenSS7 Project was funded in part by:

Thanks to the subscribers to and sponsors of The OpenSS7 Project. Without their support, open software like this would not be possible.

As with most open source projects, this project would not have been possible without the valiant efforts and productive software of the Free Software Foundation, the Linux Kernel Community, and the open source software movement at large.


1 Introduction

This document specifies a STREAMS-based kernel-level instantiation of the Channel Interface (CHI) definition. The Channel Interface (CHI) enables the user of a channel service to access and use any of a variety of conforming channel providers without specific knowledge of the provider’s protocol. The service interface is designed to support any network channel protocol. This interface only specifies access to channel service providers, and does not address issues concerning channel management, protocol performance, and performance analysis tools.

This specification assumes that the reader is familiar with ITU-T state machines and channel interface (e.g. G.703, G.704), and STREAMS.

1.1 Related Documentation

  • ITU-T Recommendation G.703 (White Book)
  • ITU-T Recommendation G.704 (White Book)
  • ANSI T1
  • System V Interface Definition, Issue 2 - Volume 3

1.1.1 Role

This document specifies an interface that supports the services provided by the Channel for ITU-T, ANSI and ETSI applications as described in ITU-T Recommendation G.703 and ITU-T Recommendation G.704. These specifications are targeted for use by developers and testers of protocol modules that require channel service.

1.2 Definitions, Acronyms, Abbreviations

LM

Local Management.

LMS

Local Management Service.

LMS User

A user of Local Management Services.

LMS Provider

A provider of Local Management Services.

ISO

International Organization for Standardization

OSI

Open Systems Interconnection

QOS

Quality of Service

STREAMS

A communication services development facility first available with UNIX System V Release 3.


2 The Channel Layer

The Channel Layer provides the means to manage the association of CH-Users info connections. It is responsible for the routing and management of data to and from channel connections between CH-user entities.


2.1 Model of the CHI

The CHI defines the services provided by the channel layer to the channel user at the boundary between the channel provider and the channel user entity. The interface consists of a set of primitives defined as STREAMS messages that provide access to the channel layer services, and are transferred between the CHS user entity and the CHS provider. These primitives are of two types; ones that originate from the CHS user, and others that originate from the CHS provider. The primitives that originate from the CHS user make requests to the CHS provider, or respond to an indication of an event of the CHS provider. The primitives that originate from the CHS provider are either confirmations of a request or are indications to the CHS user that an event has occurred. Figure 1 show the model of the CHI.

Model of the CHI

Figure 1. Model of the CHI

The CHI allows the CHS provider to be configured with any channel layer user (such as a signalling data terminal application) that also conforms to the CHI. A channel layer user can also be a user program that conforms to the CHI and accesses the CHS provider via putmsg(2s) and getmsg(2s) system calls. The typical configuration, however, is to place a signalling data terminal module above the channel layer.


2.2 CHI Services

The features of the CHI are defined in terms of the services provided by the CHS provider, and the individual primitives that may flow between the CHS user and the CHS provider.

The CHI Services are broken into two groups: local management services and protocol services. Local management services are responsible for the local management of Streams, assignment of Streams to physical points of attachment, enabling and disabling of Streams, management of options associated with a Stream, and general acknowledgement and event reporting for the Stream. Protocol services consist of connecting a Stream to a medium, exchanging bits with the medium, and disconnecting the Stream from the medium.

2.2.1 Local Management

Local management services are listed in Table 1.

chit01

Table 1. Local Management Services

The local management services interface is described in Local Management Services, and the primitives are detailed in Local Management Service Primitives. The local management services interface is defined by the sys/chi.h header file (see CHI Header Files).

2.2.2 Protocol

Protocol services are listed in Table 2.

chit02

Table 2. Protocol Services

The protocol services interface is described in Protocol Services, and the primitives are detailed in Protocol Service Primitives. The protocol services interface is defined by the sys/chi.h header file (see CHI Header Files).


2.3 Purpose of the CHI

The CHI is typically implemented as a device driver controlling a TDM (Time Division Mutliplexing) device that provides access to channels. The purpose behind exposing this low level interface is that almost all communications channel devices can be placed into a raw mode, where a bit stream can be exchanged between the driver and the medium. The CHI provides an interface that, once implemented as a driver for a new device, can provide complete and verified data link capabilities by pushing generic HDLC (High Level Data Link Control) and LAPB (Link Access Procedure Balanced) modules over an open device Stream.

This allows CDI and DLPI modules to be verified independently for correct operation and then simply used for all manner of new device drivers that can implement the CHI interface.


2.4 Channel Addressing

Each use of CHI must establish an identity to communicate with other channel users. The CHS user must identify the physical medium over which it wil communicate. This is particularly evident on system that are attached to multiple physical media. Figure 17 illustrates the identification approach, which is explained below.

Channel Addressing Components

Figure 17. Channel Addressing Components

2.4.1 Physical Attachment Identification

The physical point of attachment (PPA in Figure 17) is the point at which a system interface attaches itself to a physical communications medium (a channel, facility or network interface). All communication on that physical medium funnels through the PPA associated with that physical medium. On systems where a CHS provider supports more than on physical medium, the CHS user must identify the medium through which it will communicate. A PPA is identified by a unique PPA identifier.

For media that supports physical layer multiplexing of multiple channels over a single physical medium (such as the B and D channels of ISDN), the PPA identifier must identify the specific channel(s) over which communication will occur. See also Multiplex Media.

Unlike the Data Link Provider Interface (DLPI), which also uses the concept of a PPA, CHI does not define a SAP for a CHS user.

Once a Stream has been associated with a PPA, all messages received on that medium are delivered to the attached CHS user. Only one major/minor device number combination (Stream head) can be associated with a given PPA and active for a range of channels at any point in time.

2.4.2 CHS Provider Styles

Two styles of CHS provider are defined by CHI, distinguished by the way they enable a CHS user to choose a particular PPA.

2.4.2.1 Style 1 CHS Provider

The Style 1 provider assigns a PPA based on the major/minor device the CHS user opened. One possible implementation of a Style 1 driver would reserve a major device for each PPA the channel device driver would support. This would allos the STREAMS clone open feature to be used for each PPA configured. This style of provider is appropriate when few PPAs will be supported.

For example, a CPI card that supports two V.35 ports could assign a major device number to the card diver and a minor device number to each of the ports on each card in the system. To establish a Stream to a CHS provider for a given port, the minor device number ‘1’ or ‘2’ could be opened for port ‘1’ or ‘2’ on card ‘1’, minor device number ‘3’ or ‘4’ could be opened for port ‘1’ or ‘2’ on card ‘2’, and so on. One major device number for the driver could easily support 127 cards in a system, which is not possible for typical PCI systems and, therefore, is ample.

Style 1 providers do not user the CH_ATTACH_REQ and CH_DETACH_REQ primitives and when freshly opened are in the CHS_ATTACHED state. That is, as illustrated in Figure 17, the Style 1 CHS provider associates the Stream with the PPA during the open(2s) system call.

2.4.2.2 Style 2 CHS Provider

If the number of PPAs as CHS provider will support is large, a Style 2 provider implementation is more suitable. The Style 2 provider requires a CHS user to explicitly identify the desired PPA using a special attach service primitive. For a Style 2 driver, the open(2s) system call creates a Stream between the CHS user and CHS provider, and the attach primitive then associated a particular PPA with that Stream. The format of the PPA identifier is specific to the CHS provider, and should be described in the provider-specific addendum documentation.

The CHS user uses the support primitvies(CH_ATTACH_REQ, CH_ENABLE_REQ) to associate a Stream with a given Physical Point of Appearance. Style 2 CHS providers, when freshly opened, are in the CHS_DETACHED state. That is, the Style 2 CHS provider does not associate the Stream with the PPA during the open(2s) call, but only later when the CH_ATTACH_REQ primitive is issued by the CHS user.

2.4.3 Multiplex Media

To accommodate multiplexed media and multi-media channels, there are three kinds of PPA address:

  1. A discrete PPA that specifies a non-multiplexed medium.

    This is the normal case of a Style 1 or Style 2 CHS provider supporting access to a non-multiplexed medium. An example is a CHS provider supporting access to a V.35 interface.

  2. A specific PPA that specifies a single channel to a multiplexed medium.

    This is again the normal case of a Style 1 or Style 2 CHS provider supporting access to a specific channel in a multiplexed medium. An example is a CHS provider supporting access to channel 16 of a E1 interface.

  3. A general PPA that specifies a channel group for a multiplexed medium.

    This is th case of a Style 1 or Style 2 CHS provider supporting access to multiple channels in a multiplexed medium. An example is a CHS provider supporting statistically multiplexed channel access to a full or fractional T1 facilitiy. Another example is access to the left and right channels of a stereo program.

In the case of a general PPA, as enumerated in 3 above, some additional information is required to identify which slots in the group of channle forming the multiplex are associatedw the the CHS user Stream. This additional information is provided using the ch_slot parameter to the CH_CONNECT_REQ, CH_CONNECT_CON, CH_DATA_REQ, CH_DATA_IND, CH_EVENT_IND, CH_DISCONNECT_REQ, CH_DISCONNECT_CON and CH_DISCONNECT_IND primitives.2


2.5 Channel Parameters


3 CHI Services Definition


3.1 Local Management Services


3.1.1 Acknowledgement Service

The acknowledgement service provides the CHS user with the ability to receive positive and negative acknowledgements regarding the successful or unsuccessful completion of services.

  • CH_OK_ACK: The CH_OK_ACK message is used by the CHS provider to indicate successful receipt and completion of a service primitive request that requires positive acknowledgement.
  • CH_ERROR_ACK: The CH_ERROR_ACK message is used by the CHS provider to indicate successful receipt and failure to complete a service primitive request that requires negative acknowledgement.

A successful invocation of the acknowledgement service is illustrated in Figure 15.

Message Flow: Successful Acknowledgement Service

Figure 15. Message Flow: Successful Acknowledgement Service

As illustrated in Figure 15, the service primitives for which a positive acknowledgement may be returned are the CH_ATTACH_REQ and CH_DETACH_REQ.

An unsuccessful invocation of the acknowledgement service is illustrated in Figure 16.

Message Flow: Unsuccessful Acknowledgement Service

Figure 16. Message Flow: Unsuccessful Acknowledgement Service

As illustrated in Figure 16, the service primitives for which a negative acknowledgement may be returned are the CH_INFO_REQ, CH_ATTACH_REQ, CH_DETACH_REQ, CH_ENABLE_REQ, CH_DISABLE_REQ and CH_OPTMGMT_REQ messages.


3.1.2 Information Reporting Service

The information reporting service provides the CHS user with the ability to elicit information from the CHS provider.

  • CH_INFO_REQ: The CH_INFO_REQ message is used by the CHS user to request information about the CHS provider.
  • CH_INFO_ACK: The CH_INFO_ACK message is issued by the CHS provider to provide requested information about the CHS provider.

A successful invocation of the information reporting service is illustrated in Figure 2.

Message Flow: Successful Information Reporting Service

Figure 2. Message Flow: Successful Information Reporting Service


3.1.3 Physical Point of Attachment Service

The local management interface provides the CHS user with the ability to associate a Stream to a physical point of appearance (PPA) or to disassociate a Stream from a PPA. The local management interface provides for two styles of CHS provider:3

Style 1 CHS Provider

A Style 1 CHS provider is a provider that associates a Stream with a PPA at the time of the first open(2s) call for the device, and disassociates a Stream from a PPA at the time of the last close(2s) call for the device.

Physical points of attachment (PPA) are assigned to major and minor device number combinations. When the major and minor device number combination is opened, the opened Stream is automatically associated with the PPA for the major and minor device number combination. The last close of the device disassociates the PPA from the Stream.

Freshly opened Style 1 CHS provider Streams start life in the CH_DISABLED state.

This approach is suitable for CHS providers implemented as real or pseudo-device drivers and is applicable when the number of minor devices is small and static.

Style 2 CHS Provider

A Style 2 CHS provider is a provider that associates a Stream with a PPA at the time that the CHS user issues the CH_ATTACH_REQ message. Freshly opened Streams are not associated with any PPA. The Style 2 CHS provider Stream is disassociated from a PPA when the Stream is closed or when the CHS user issues the CH_DETACH_REQ message.

Freshly opened Style 2 CHS provider Streams start life in the CH_UNATTACHED state.

This approach is suitable for CHS providers implemented as clone real or pseudo-device drivers and is applicable when the number of minor devices is large or dynamic.


3.1.3.1 PPA Attachment Service

The PPA attachment service provides the CHS user with the ability to attach a Style 2 CHS provider Stream to a physical point of appearance (PPA).

  • CH_ATTACH_REQ: The CH_ATTACH_REQ message is issued by the CHS user to request that a Style 2 CHS provider Stream be attached to a specified physical point of appearance (PPA).
  • CH_OK_ACK: Upon successful receipt and processing of the CH_ATTACH_REQ message, the CHS provider acknowledges the success of the service completion with a CH_OK_ACK message.
  • CH_ERROR_ACK: Upon successful receipt but failure to process the CH_ATTACH_REQ message, the CHS provider acknowledges the failure of the service completion with a CH_ERROR_ACK message.

A successful invocation of the attachment service is illustrated in Figure 3.

Message Flow: Successful Attachment Service

Figure 3. Message Flow: Successful Attachment Service


3.1.3.2 PPA Detachment Service

The PPA detachment service provides the CHS user with the ability to detach a Style 2 CHS provider Stream from a physical point of attachment (PPA).

  • CH_DETACH_REQ: The CH_DETACH_REQ message is issued by the CHS user to request that a Style 2 CHS provider Stream be detached from the attached physical point of appearance (PPA).
  • CH_OK_ACK: Upon successful receipt and processing of the CH_DETACH_REQ message, the CHS provider acknowledges the success of the service completion with a CH_OK_ACK message.
  • CH_ERROR_ACK: Upon successful receipt but failure to process the CH_DETACH_REQ message, the CHS provider acknowledges the failure of the service completion with a CH_ERROR_ACK message.

A successful invocation of the detachment service is illustrated in Figure 4.

Message Flow: Successful Detachment Service

Figure 4. Message Flow: Successful Detachment Service


3.1.4 Initialization Service

The initialization service provides the CHS user with the abilty to enable and disable the Stream for the associated PPA.


3.1.4.1 Interface Enable Service

The interface enable service provides the CHS user with the ability to enable an CHS provider Stream that is associated with a PPA. Enabling the interface permits the CHS user to exchange protocol service interface messages with the CHS provider.

  • CH_ENABLE_REQ: The CH_ENABLE_REQ message is issued by the CHS user to request that the protocol service interface be enabled.
  • CH_ENABLE_CON: Upon successful enabling of the protocol service interface, the CHS provider acknowledges successful completion of the service by issuing a CH_ENABLE_CON message to the CHS user.
  • CH_ERRORK_ACK: Upon unsuccessful enabling of the protocol service interface, the CHS provider acknowledges the failure to complete the service by issuing an CH_ERROR_ACK message to the CHS user.

A successful invocation of the enable service is illustrated in Figure 5.

Message Flow: Successful Enable Service

Figure 5. Message Flow: Successful Enable Service


3.1.4.2 Interface Disable Service

The interface disable service provides the CHS user with the ability to disable an CHS provider Stream that is associated with a PPA. Disabling the interface withdraws the CHS user’s ability to exchange protocol service interface messages with the CHS provider.

  • CH_DISABLE_REQ: The CH_DISABLE_REQ message is issued by the CHS user to request that the protocol service interface be disabled.
  • CH_DISABLE_CON: Upon successful disabling of the protocol service interface, the CHS provider acknowledges successful completion of the service by issuing a CH_DISABLE_CON message to the CHS user.
  • CH_ERRORK_ACK: Upon unsuccessful disabling of the protocol service interface, the CHS provider acknowledges the failure to complete the service by issuing an CH_ERROR_ACK message to the CHS user.
  • CH_DISABLE_IND: The CH_DISABLE_IND message is used by the CHS provider to indicate to the CHS user that the Stream has been autonomously disabled and the cause of the autonomous disabling.

A successful invocation of the disable service is illustrated in Figure 6.

Message Flow: Successful Disable Service

Figure 6. Message Flow: Successful Disable Service


3.1.5 Options Management Service

The options management service provides the CHS user with the ability to control and affect various generic and provider-specific options associated with the CHS provider.

  • CH_OPTMGMT_REQ: The CHS user issues a CH_OPTMGMT_REQ message when it wishes to interrogate or affect the setting of various generic or provider-specific options associated with the CHS provider for the Stream upon which the message is issued.
  • CH_OPTMGMT_ACK: Upon successful receipt of the CH_OPTMGMT_REQ message, and successful options processing, the CHS provider acknowledges the successful completion of the service with an CH_OPTMGMT_ACK message.
  • CH_ERROR_ACK: Upon successful receipt of the CH_OPTMGMT_REQ message, and unsuccessful options processing, the CHS provider acknowledges the failure to complete the service by issuing an CH_ERROR_ACK message to the CHS user.

A successful invocation of the options management service is illustrated in Figure 7.

Message Flow: Successful Options Management Service

Figure 7. Message Flow: Successful Options Management Service


3.1.6 Error Reporting Service

The error reporting service provides the CHS provider with the ability to indicate asynchronous errors to the CHS user.

  • CH_ERROR_IND: The CHS provider issues the CH_ERROR_IND message to the CHS user when it needs to indicate an asynchronous error (such as the unusability of the communications medium).

A successful invocation of the error reporting service is illustrated in Figure 8.

Message Flow: Successful Error Reporting Service

Figure 8. Message Flow: Successful Error Reporting Service


3.1.7 Statistics Reporting Service

  • CH_STATS_IND:

A successful invocation of the statistics reporting service is illustrated in Figure 9.

Message Flow: Successful Statistics Reporting Service

Figure 9. Message Flow: Successful Statistics Reporting Service


3.1.8 Event Reporting Service

The event reporting service provides the CHS provider with the ability to indicate specific asynchronous management events to the CHS user.

  • CH_EVENT_IND: The CHS provider issues the CH_EVENT_IND message to the CHS user when it wishes to indicate an asynchronous (management) event to the CHS user.

A successful invocation of the event reporting service is illustrated in Figure 10.

Message Flow: Successful Event Reporting Service

Figure 10. Message Flow: Successful Event Reporting Service


3.2 Protocol Services

Protocol services are specific to the Channel interface. These services consist of connection services that permit the transmit and receive directions to be connected to or disconnected from the medium, and data transfer services that permit the exchange of bits between CHS users.

The service primitives that implement the protocol services are described in detail in Protocol Service Primitives.


3.2.1 Connection Service

The connection service provides the ability for the CHS user to connect to the medium for the purpose of transmitting bits, receiving bits, or both. In the OSI model, this is a Layer 1 function, possibly the responsibility of multiplex or digital cross-connect switch.

  • CH_CONNECT_REQ: The CH_CONNECT_REQ message is used by the CHS user to request that the Stream be connected to the medium. Connection to the medium might require some switching or other mechanism to prepare the Stream for data transmission and reception. Connections can be formed for the receive direction or the transmit direction independently.
  • CH_CONNECT_CON: The CH_CONNECT_CON message is used by the CHS provider to confirm that the Stream has been connected to the medium. Connection to the medium may have required some switching or other mechanism to prepare the Stream for data transmission and receptoin. Connection can be confirmed for the receive or transmit directions independently.

A successful invocation of the connection service is illustrated in Figure 11.

Message Flow: Successful Connection Service

Figure 11. Message Flow: Successful Connection Service


3.2.2 Data Transfer Service

The data transfer service provides the CHS user with the ability to request that bits be transmitted on the medium, and the CHS provider with the ability to indicate bits that have been received from the medium.

  • CH_DATA_REQ: The CH_DATA_REQ message is used by the CHS user to place raw bits onto the medium. The Stream must have first been successfully activated in the transmit direction using the CH_CONNECT_REQ message.
  • CH_DATA_IND: The CH_DATA_IND message is issued by the CHS provider when activated for the receive direction with the CH_CONNECT_REQ message, to indicate bits received on the medium.

A successful invocation of the data transfer service is illustrated in Figure 12.

Message Flow: Successful Data Transfer Service

Figure 12. Message Flow: Successful Data Transfer Service


3.2.3 Disconnection Service

The disconnection service provides the ability for the CHS user to disconnect from the medium, withdrawing from the purpose of transmitting bits, receiving bits, or both. It allows the CHS provider to autonomously indicate that the medium has been disconnected from the Stream. In OSI, this is a Layer 1 function, possibly the responsibilyt of a multiplex or digital cross-connect switch.

  • CH_DISCONNECT_REQ: The CH_DISCONNECT_REQ message is used by the CHS user to request that the Stream be disconnected from the medium. Disconnection from the medium might require some switching or other mechanism. Disconnection can be performed for the receive direction or the transmit direction independently.
  • CH_DISCONNECT_CON: The CH_DISCONNECT_CON message is used by the CHS provider to confirm that the Stream has been disconnected from the medium. Disconnect from the medium might require some switching or other mechanism. Disconnection can be confirmed for the receive or transmit directions independently.
  • CH_DISCONNECT_IND: The CH_DISCONNECT_IND message is used by the CHS provider to indicate to the CHS user that the Stream has been disconnected from the medium. Disconnection is indicated for both the receive and transmit directions.

A successful invocation of the disconnection service by the CHS user is illustrated in Figure 13.

Message Flow: Successful Disconnection Service by SDLS User

Figure 13. Message Flow: Successful Disconnection Service by SDLS User

A successful invocation of the disconnection service by the CHS provider is illustrated in Figure 14.

Message Flow: Successful Disconnection Service by SDLS Provider

Figure 14. Message Flow: Successful Disconnection Service by SDLS Provider


4 CHI Service Primitives


4.1 Local Management Service Primitives

These service primitives implement the local management services (see Local Management Services).


4.1.1 Acknowledgement Service Primitives

These service primitives implement the acknowledgement service (see Acknowledgement Service).


4.1.1.1 CH_OK_ACK

Description

This primitive is used to acknowledge receipt and successful service completion for primitives requiring acknowledgement that have no confirmation primitive.

Format

This primitive consists of one M_PCPROTO message block, structured as follows:

typedef struct CH_ok_ack {
    ch_ulong ch_primitive;
    ch_ulong ch_correct_prim;
    ch_ulong ch_state;
} CH_ok_ack_t;

Parameters

The service primitive contains the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_OK_ACK.

ch_correct_prim

Indicates the service primitive that was received and serviced correctly. This field can be one of the following values:

CH_ATTACH_REQAttach request.
CH_ENABLE_REQEnable request.
CH_CONNECT_REQConnect request.
CH_DISCONNECT_REQDisconnect request.
CH_DISABLE_REQDisable request.
CH_DETACH_REQDetach Request.
ch_state

Indicates the current state of the CHS provider at the time that the primitive was issued. This field can be one of the following values;

CHS_UNINITUnitialized.
CHS_UNUSABLEDevice cannot be used, Stream in hung state.
CHS_DETACHEDNo PPA attached, awaiting CH_ATTACH_REQ.
CHS_ATTACHEDPPA attached, awaiting CH_ENABLE_REQ.
CHS_WCON_EREQWaiting to send CH_ENABLE_CON.
CHS_WCON_RREQWaiting to send CH_DISABLE_CON.
CHS_ENABLEDReady for use, awaiting primitive exchange.
CHS_WCON_CREQWaiting to send CH_CONNECT_CON.
CHS_WCON_DREQWaiting to send CH_DISCONNECT_CON.
CHS_CONNECTEDConnected, active data transfer.

State

This primitive is issued by the CHS provider in the CHS_WACK_AREQ, CHS_WACK_UREQ, CHS_WACK_CREQ or CHS_WACK_DREQ state.

New State

The new state is CHS_DETACHED, CHS_ATTACHED, CHS_ENABLED or CHS_CONNECTED, depending on the primitive to which the message is responding.


4.1.1.2 CH_ERROR_ACK

Description

The error acknowledgement primitive is used to acknowledge receipt and unsuccessful service completion for primitives requiring acknowledgement.

Format

The error acknowledgement primitive consists of one M_PCPROTO message block, structured as follows:

typedef struct CH_error_ack {
    ch_ulong ch_primtive;
    ch_ulong ch_error_primitive;
    ch_ulong ch_error_type;
    ch_ulong ch_unix_error;
    ch_ulong ch_state;
} CH_error_ack_t;

Parameters

The error acknowledgement primitive contains the following parameters:

ch_primitive

Indicates the primitive type. Always CH_ERROR_ACK.

ch_error_type

Indicates the CH error number. This field can have one of the following values:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.
ch_unix_error

Indicates the reason for failure. This field is protocol-specific. When the ch_error_type field is [CHSYSERR], the ch_unix_error field is the UNIX error number as described in errno(3).

ch_error_primitive

Indicates the primitive that was in error. This field can have one of the following values:

CH_INFO_REQInformation request.
CH_OPTMGMT_REQOptions management request.
CH_ATTACH_REQAttach request.
CH_ENABLE_REQEnable request.
CH_CONNECT_REQConnect request.
CH_DATA_REQData request.
CH_DISCONNECT_REQDisconnect request.
CH_DISABLE_REQDisable request.
CH_DETACH_REQDetach Request.
CH_INFO_ACKInformation acknowledgement.
CH_OPTMGMT_ACKOptions Management acknowledgement.
CH_OK_ACKSuccessful receipt acknolwedgement.
CH_ERROR_ACKError acknowledgement.
CH_ENABLE_CONEnable confirmation.
CH_CONNECT_CONConnect confirmation.
CH_DATA_INDData indication.
CH_DISCONNECT_INDDisconnect indication.
CH_DISCONNECT_CONDisconnect confirmation.
CH_DISABLE_INDDisable indication.
CH_DISABLE_CONDisable confirmation.
CH_EVENT_INDEvent indication.
ch_state

Indicates the state of the CHS provider at the time that the primitive was issued. This field can have one of the following values:

CHS_UNINITUnitialized.
CHS_UNUSABLEDevice cannot be used, Stream in hung state.
CHS_DETACHEDNo PPA attached, awaiting CH_ATTACH_REQ.
CHS_WACK_AREQWaiting for attach.
CHS_WACK_UREQWaiting for detach.
CHS_ATTACHEDPPA attached, awaiting CH_ENABLE_REQ.
CHS_WCON_EREQWaiting to send CH_ENABLE_CON.
CHS_WCON_RREQWaiting to send CH_DISABLE_CON.
CHS_ENABLEDReady for use, awaiting primitive exchange.
CHS_WACK_CREQWaiting acknolwedgement of CH_CONNECT_REQ.
CHS_WCON_CREQWaiting to send CH_CONNECT_CON.
CHS_WACK_DREQWaiting acknolwedgement of CH_DISCONNECT_REQ.
CHS_WCON_DREQWaiting to send CH_DISCONNECT_CON.
CHS_CONNECTEDConnected, active data transfer.

State

This primitive can be issued in any state for which a local acknowledgement is not pending. The CHS provider state at the time that the primitive was issued is indicated in the primitive.

New State

The new state remains unchanged.


4.1.2 Information Reporting Service Primitives

These service primitives implement the information reporting service (see Information Reporting Service).


4.1.2.1 CH_INFO_REQ

Description

This CHS user originated primitive is issued by the CHS user to request that the CHS provider return information concerning the capabilities and state of the CHS provider.

Format

The primitive consists of one M_PROTO or M_PCPROTO message block, structured as follows:

typedef struct CH_info_req {
    ch_ulong ch_primitive;
} CH_info_req_t;

Parameters

This primitive contains the following parameters:

ch_primitive

Specifies the primitive type. Always CH_INFO_REQ.

State

This primitive may be issued in any state but only when a local acknowledgement is not pending.

New State

The new state remains unchanged.

Response

This primitive requires the CHS provider to acknowledge receipt of the primitive as follows:

  • - Successful: The CHS provider is required to acknowledge receipt of the primitive and provide the requested information using the CH_INFO_ACK primitive.
  • - Unsuccessful (non-fatal errors): The CHS provider is required to negatively acknowledge the primtive using the CH_ERROR_ACK primitive, and include the reason for failure in the primitive.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.2.2 CH_INFO_ACK

Description

This CHS provider originated primitive acknowledges receipt and successful processing of the CH_INFO_REQ primitive and provides the requested information concerning the CHS provider.

Format

This message is formatted a one M_PROTO or M_PCPROTO message block, structured as follows:

typedef struct CH_info_ack {
    ch_ulong ch_primitive;    /* always CH_INFO_ACK */
    ch_ulong ch_addr_length;  /* channel address length */
    ch_ulong ch_addr_offset;  /* channel address offset */
    ch_ulong ch_parm_length;  /* channel paramters length */
    ch_ulong ch_parm_offset;  /* channel paramters offset */
    ch_ulong ch_prov_flags;   /* provider options flags */
    ch_ulong ch_prov_class;   /* provider class */
    ch_ulong ch_style;        /* provider style */
    ch_ulong ch_version;      /* channel interface version */
    ch_ulong ch_state;        /* channel state */
} CH_info_ack_t;

Parameters

The information acknowledgement service primitive has the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_INFO_ACK.

ch_addr_length

Indicates the length of the PPA address to which the provider is attached. When in states CHS_DETACHED or CHS_WACK_AREQ, this value will be zero (‘0’).

ch_addr_offset

Indicates the offset, beginning from the start of the M_PCPROTO message block of the PPA address associated with the provider. When the ch_addr_length field is zero, this field is also zero (‘0’).

ch_parm_length

Indicates the length of the parameters associated with the provider.

ch_parm_offset

Indicates the offset, beginning from the start of the M_PCPROTO message block, of the parameters associated with the provider. When the ch_parm_length field is zero, this field is also zero (‘0’).

ch_prov_flags

Indicates the options flags associated with the provider. This is a bitwise OR of zero or more of the following flags:

ch_prov_class

Indicates the provider class. This can be one of the following values:

CH_CIRCUITCircuit provider class.
ch_addr_length

This is a variable length field. The length of the field is determined by the length attribute.

For a Style 2 driver, when ch_style is CH_STYLE2, and when in an attached state, this field provides the current PPA associated with the Stream; the length is typically 4 bytes.

For a Style 1 driver, when ch_ppa_stype is CH_STYLE1, the length is 0 bytes.

ch_style

Indicates the PPA style of the CHS provider. This value can be one of the following values;

CH_STYLE1PPA is implicitly attached by open(2s).
CH_STYLE2PPA must be explicitly attached using CH_ATTACH_REQ.
ch_version

The version of the interface. This version is CH_VERSION_1_1.

CH_VERSION_1_0Version 1.0 of interface.
CH_VERSION_1_1Version 1.1 of interface.
CH_VERSIONAlways the current version of the header file.
ch_state

Indicates the state of the CHS provider at the time that the information acknolwedgement service primitive wsa issued. This field can be one of the following values:

CHS_UNINITUnitialized.
CHS_UNUSABLEDevice cannot be used, Stream in hung state.
CHS_DETACHEDNo PPA attached, awaiting CH_ATTACH_REQ.
CHS_WACK_AREQWaiting for attach.
CHS_WACK_UREQWaiting for detach.
CHS_ATTACHEDPPA attached, awaiting CH_ENABLE_REQ.
CHS_WCON_EREQWaiting to send CH_ENABLE_CON.
CHS_WCON_RREQWaiting to send CH_DISABLE_CON.
CHS_ENABLEDReady for use, awaiting primitive exchange.
CHS_WACK_CREQWaiting acknolwedgement of CH_CONNECT_REQ.
CHS_WCON_CREQWaiting to send CH_CONNECT_CON.
CHS_WACK_DREQWaiting acknolwedgement of CH_DISCONNECT_REQ.
CHS_WCON_DREQWaiting to send CH_DISCONNECT_CON.
CHS_CONNECTEDConnected, active data transfer.

State

This primitive can be issued in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged.


4.1.3 Physical Point of Attachment Service Primitives

These service primitives implement the physical point of attachment service (see Physical Point of Attachment Service).


4.1.3.1 CH_ATTACH_REQ

Description

This CHS user originated primitive requests that the Stream upon which the primitive is issued be associated with the specified Physical Point of Attachment (PPA). This primitive is only applicable to Style 2 CHS provider Streams, that is, Streams that return CH_STYLE2 in the ch_style field of the CH_INFO_ACK.

Format

This primitive consists of one M_PROTO message block, structured as follows:

typedef CH_attach_req {
    ch_ulong ch_primitive;
    ch_ulong ch_addr_length;
    ch_ulong ch_addr_offset;
    ch_ulong ch_flags;
} CH_attach_req_t;

Parameters

The attach request primitive contains the following parameters:

ch_primitive

Specifies the service primitive type. Always CH_ATTACH_REQ.

ch_addr_length

Specifies the Physical Point of Attachment (PPA) to which to associate the Style 2 Stream. This is a variable length identifier whose length is determined by the ch_addr_length value. Specifies the length of the Physical Point of Attachment (PPA) address. The form of the PPA address is provider-specific.

ch_addr_offset

Specifies the offset, from the beginning of the M_PROTO message block, of the start of the Physical Point of Attachment (PPA) address.

ch_flags

Specifies the options flags for attachment. Options flags are provider-specific.

State

This primitive is only valid in state CHS_DETACHED and when a local acknowledgement is not pending.

New State

Upon success, the new state is CHS_WACK_AREQ. Upon failure, the state remains unchanged.

Response

The attach request service primitive requires that the CHS provider respond as follows:

  • - Successful: The CHS provider acknowledges receipt of the primitive and successful outcome of the attach service with a CH_OK_ACK primitive. The new state is CHS_ATTACHED.
  • - Unsuccessful (non-fatal errors): The CHS provider acknowledges receipt of the primitive and failure of the attach service with a CH_ERROR_ACK primitive containing the reason for failure. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.3.2 CH_DETACH_REQ

Description

This CHS user originated primitive requests that the Stream upon which the primitive is issued be disassociated from the Physical Point of Appearance (PPA) to which it is currently attached. This primitive is only applicable to Style 2 CHS provider Streams, that is, Streams that return CH_STYLE2 in the ch_style field of the CH_INFO_ACK.

Format

The detach request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_detach_req {
    ch_ulong ch_primitive;
} CH_detach_req_t;

Parameters

The detach request service primitive contains the following parameters:

ch_primitive

Specifies the service primitive type. Always CH_DETACH_REQ.

State

This primitive is valid in the CHS_ATTACHED state and when no local acknowledgement is pending.

New State

Upon success, the new state is CHS_WACK_UREQ. Upon failure, the state remains unchanged.

Response

The detach request service primitive requires that the CHS provider respond as follows:

  • - Successful: The CHS provider acknowledges receipt of the primitive and successful outcome of the detach service with a CH_OK_ACK primitive. The new state is CHS_DETACHED.
  • - Unsuccessful (non-fatal errors): The CHS provider acknowledges receipt of the primitive and failure of the detach service with a CH_ERROR_ACK primitive containing the reason for failure. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.4 Initialization Service Primitives

Initialization service primitives allow the CHS user to enable or disable the protocol service interface. Enabling the protocol service interface may require that some action be taken to prepare the protocol service interface for use or to remove it from use. For example, where the PPA corresponds to a channel identifier as defined in G.703, it may be necessary to perform switching to connect or disconnect the circuit identification code associated with the channel identifier.

These service primitives implement the initialization service (see Initialization Service).


4.1.4.1 CH_ENABLE_REQ

Description

This CHS user originated primitive requests that the CHS provider perform the actions necessary to enable the protocol service interface and confirm that it is enabled. This primitive is applicable to both styles of PPA.

Format

The enable request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_enable_req {
    ch_ulong ch_primitive;
    ch_ulong ch_addr_length;
    ch_ulong ch_addr_offset;
    ch_ulong ch_flags;
} CH_enable_req_t;

Parameters

The enable request service primitive contains the following parameters:

ch_primitive

Specifies the service primitive type. Always CH_ENABLE_REQ.

ch_addr_length

Specifies a remote address to which to connect the PPA. The need for and form of this address is provider-specific. The length of the field is determined by the value of this field. This remote address could be a circuit identification code, an IP address, or some other form of circuit or channel identifier.

ch_addr_offset

Specifies the offset, from the beginning of the M_PROTO message block, of the start of the remote address.

ch_flags

Specifies the options flags associated with the enable request. Options flags are provider-specific.

State

This primitive is valid in the CHS_ATTACHED state and when no local acknowledgement is pending.

New State

Upon success the new state is CHS_WCON_EREQ. Upon failure, the state remains unchanged.

Response

The enable request service primitive requires that the CHS provider acknowledge receipt of the primitive as follows:

  • - Successful: When successful, the CHS provider acknowledges successful completion of the enable service with a CH_ENABLE_CON primitive. The new state is CHS_ENABLED.
  • - Unsuccessful (non-fatal errors): When unsuccessful, the CHS provider acknowledges the failure of the enable service with a CH_ERROR_ACK primitive containing the error. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.4.2 CH_ENABLE_CON

Description

This CHS provider originated primitive is issued by the CHS provider to confirm the successful completion of the enable service.

Format

The enable confirmation service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_enable_con {
    ch_ulong ch_primitive;
    ch_ulong ch_addr_length;
    ch_ulong ch_addr_offset;
    ch_ulong ch_flags;
} CH_enable_con_t;

Parameters

The enable confirmation service primitive contains the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_ENABLE_CON.

ch_addr_length

Confirms the length of the remote address to which the enable is confirmed.

ch_addr_offset

Confirms the offset, from the beginning of the M_PROTO message block, of the start of the remote address.

ch_flags

Confirms the options flags associated with the enable confirmation. Options flags are provider-specific.

State

This primitive is issued by the CHS provider in the CHS_WCON_EREQ state.

New State

The new state is CHS_ENABLED.


4.1.4.3 CH_DISABLE_REQ

Description

This CHS user originated primitive requests that the CHS provider perform the actions necessary to disable the protocol service interface and confirm that it is disabled. The primitive is applicable to both styles of PPA.

Format

The disable request service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_disable_req {
    ch_ulong ch_primitive;
} CH_disable_req_t;

Parameters

The disable request service primitive contains the following parameters:

ch_primitive

Specifies the service primitive type. Always CH_DISABLE_REQ.

State

The disable request service primitive is valid in the CHS_ENABLED state and when no local acknowledgement is pending.

New State

Upon success, the new state is CHS_WCON_RREQ. Upon failure, the state remains unchanged.

Response

The disable request service primitive requires the CHS provider to acknowledge receipt of the primitive as follows:

  • - Successful: When successful, the CHS provider acknowledges successful completion of the disable service with an CH_DISABLE_CON primitive. The new state is CHS_ATTACHED.
  • - Unsuccessful (non-fatal errors): When unsuccessful, the CHS provider acknowledges the failure of the disable service with a CH_ERROR_ACK primitive containing the error. The new state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.4.4 CH_DISABLE_CON

Description

This CHS provider originated primitive is issued by the CHS provider to confirm the successful completion of the disable service.

Format

The disable confirmation service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_disable_con {
    ch_ulong ch_primitive;
} CH_disable_con_t;

Parameters

The disable confirmation service primitive contains the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_DISABLE_CON.

State

This primitive is issued by the CHS provider in the CHS_WCON_RREQ state.

New State

The new state is CHS_ATTACHED.


4.1.4.5 CH_DISABLE_IND

Description

This CHS provider originated primitive is issued by the CHS provider, if an autonomous event results in the disabling of the CHS use Stream without an explicity CHS user request.

Format

The disable indication primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_disable_ind {
    ch_ulong ch_primitive;
    ch_ulong ch_cause;
} CH_disable_ind_t;

Parameters

ch_primitive

Indicates the service primitive type. Always CH_DISABLE_IND.

ch_cause

Indicates the cause of the autonomous disabling of the CHS user Stream.

State

This primitive will only be issued by the CHS provider in the CHS_ENABLED state.

New State

The new state is CHS_ATTACHED.


4.1.5 Options Management Service Primitives

The options management service primitives allow the CHS user to negotiate options with the CHS provider, retrieve the current and default values of options, and check that values specified for options are correct.

The options management service primitive implement the options management service (see Options Management Service).


4.1.5.1 CH_OPTMGMT_REQ

Description

This CHS user originated primitive requests that CHS provider options be managed.

Format

The option management request service primitive consists of one M_PROTO or M_PCPROTO message block, structured as follows:

typedef struct CH_optmgmt_req {
    ch_ulong ch_primitive;
    ch_ulong ch_opt_length;
    ch_ulong ch_opt_offset;
    ch_ulong ch_mgmt_flags;
} CH_optmgmt_req_t;

Parameters

The option management request service primitive contains the following parameters:

ch_primitive

Specifies the service primitive type. Always CH_OPTMGMT_REQ.

ch_opt_length

Specifies the length of the options.

ch_opt_offset

Specifies the offset, from the beginning of the M_PROTO message block, of the start of the options.

ch_mgmt_flags

Specifies the management flags that determine what operation the CHS provider is expected to perform on the specified options. This field can assume one of the following values:

CH_NEGOTIATE

Negotiate the specified value of each specified option and return the negotiated value.

CH_CHECK

Check the validity of the specified value of each specified option and return the result. Do not alter the current value assumed by the CHS provider.

CH_DEFAULT

Return the default value for the specified options (or all options). Do not alter the current value assumed by the CHS provider.

CH_CURRENT

Return the current value for the specified options (or all options). Do not alter the current value assumed by the CHS provider.

State

This primitive is valid in any state where a local acknowledgement is not pending.

New State

The new state remains unchanged.

Response

The option management request service primitive requires the CHS provider to acknowledge receipt of the primitive as follows:

  • - Successful: Upon success, the CHS provider acknolwedges receipt of the service primitive and successful completion of the options management service with an CH_OPTMGMT_ACK primitive containing the options management result. The state remains unchanged.
  • - Unsuccessful (non-fatal errors): Upon failure, the CHS provider acknowledges receipt of the service primitive and failure to complete the options management service with an CH_ERROR_ACK primitive containing the error. The state remains unchanged.

Reasons for Failure

Non-Fatal Errors: applicable non-fatal errors are as follows:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.
[CHBADFLAG]Bad flag.
[CHBADPRIM]Bad primitive.
[CHNOTSUPP]Primitive not supported.
[CHBADSLOT]Bad multplex slot.

4.1.5.2 CH_OPTMGMT_ACK

Description

This CHS provider originated primitive is issued by the CHS provider upon successful completion of the options management service. It indicates the outcome of the options management operation requested by the CHS user in a CH_OPTMGMT_REQ primitive.

Format

The option management acknowledgement service primitive consists of one M_PCPROTO message block, structured as follows:

typedef struct CH_optmgmt_ack {
    ch_ulong ch_primitive;
    ch_ulong ch_opt_length;
    ch_ulong ch_opt_offset;
    ch_ulong ch_mgmt_flags;
} CH_optmgmt_ack_t;

Parameters

The option management acknowledgement service primitive contains the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_OPTMGMT_ACK.

ch_opt_length

Indicates the length of the returned options.

ch_opt_offset

Indicates the offset of the returned options from the start of the M_PCPROTO message block.

ch_mgmt_flags

Indicates the returned management flags. These flags indicate the overall success of the options management service. This field can assume one of the following values:

CH_SUCCESS

The CHS provider succeeded in negotiating or returning all of the options specified by the CHS user in the CH_OPTMGMT_REQ primitive.

CH_FAILURE

The CHS provider failed to negotiate one or more of the options specified by the CHS user.

CH_PARTSUCCESS

The CHS provider negotiated a value of lower quality for one or more of the options specified by the CHS user.

CH_READONLY

The CHS provider failed to negotiate one or more of the options specified by the CHS user because the option is treated as read-only by the CHS provider.

CH_NOTSUPPORT

The CHS provider failed to recognize one or more of the options specified by the CHS user.

State

This primitive is issued by the CHS provider in direct response to a CH_OPTMGMT_REQ primitive.

New State

The new state remains unchangted.

Rules

The CHS provider observes the following rules when processing option management service requests:

  • — When the ch_mgmt_flags field in the CH_OPTMGMT_REQ primitive is set to CH_NEGOTIATE, the CHS provider will attempt to negotiate a value for each of the options specified in the request.
  • — When the flags are CH_DEFAULT, the CHS provider will return the default values of the specified options, or the default values of all options known to the CHS provider if no options were specified.
  • — When the flags are CH_CURRENT, the CHS provider will return the current values of the specified options, or all options.
  • — When the flags are CH_CHECK, the CHS provider will attempt to negotiate a value for each of the options specified in the request and return the resulg of the negotiation, but will not affect the current value of the option.

4.1.6 Event Reporting Service Primitives

The event reporting service primitives allow the CHS provider to indicate asynchronous errors, events and statistics collection to the CHS user.

These service primitives implement the event reporting service (see Event Reporting Service).


4.1.6.1 CH_ERROR_IND

Description

This CHS provider originated service primitive is issued by the CHS provider when it detects and asynchronous error event. The service primitive is applicable to all styles of PPA.

Format

The error indication service primitive consists of one M_PROTO message block, structured as follows:

typedef struct CH_error_ind {
    ch_ulong ch_primitive;
    ch_ulong ch_error_type;
    ch_ulong ch_unix_error;
    ch_ulong ch_state;
} CH_error_ind_t;

Parameters

The error indication service primitive contains the following parameters:

ch_primitive

Indicates the service primitive type. Always CH_ERROR_IND.

CH_error_type

Indicates the CHI error number describing the error. This field can have one of the following values:

[CHSYSERR]UNIX system error.
[CHBADADDR]Bad address format or content.
[CHOUTSTATE]Interface out of state.
[CHBADOPT]Bad options format or content.
[CHBADPARM]Bad parameter format or content.
[CHBADPARMTYPE]Bad paramater structure type.