Skip to content

Neda Communications, Inc.

You are here: Home » PLPC » PLPC-110301: Open C Platform

PLPC-110301: Open C Platform

Open C Platform

Document Number: PLPC-110301   [ .bib ]
Version: 2.1
Dated: July 13, 1998
Group: software
Primary URL: http://www.neda.com/PLPC/110301
Author(s): Mohsen BANAN
Organization: Neda Communications, Inc

SHORT DESCRIPTION

This document describes the Open C Platform Library, a utility which aids in the consistency of portable implementation of data communications software.

AVAILABLE FORMATS

  • PDF: -- 568K -- Provides the document in Portable Document Format.
  • PS: -- 4.0M -- Provides the document in Postscript format for printing.
  • HTML: -- 1.9M -- Displays the document as a web page.

FULL INLINE DOCUMENT

OPEN C Platform Neda Document Number: 103-100-14 Revision: source unspecified Last Updated: Author unspecified Tag: CVS tag unspecified

OPEN C Platform
Neda Document Number: 103-100-14
Revision: source unspecified
Last Updated: Author unspecified
Tag: CVS tag unspecified

Mohsen Banan
Neda Communications, Inc.
17005 SE 31st Place
Bellevue, WA 98008

July 13, 1998

Intel is a trademark of the Intel Corporation.  
UNIX is a trademark of AT’T.  
XENIX is a registered trademark of Microsoft Corporation.  
MS-DOS is a registered trademark of Microsoft Corporation.  
VRTX is a trademark of Hunter ’ Ready Inc.  
VMS and VAX are trademarks of Digital Equipment Corporation.  
IBM and PC are trademarks of International Business Machines  
Corporation.  

 
This document describes the Open C Platform Library, a utility which  
aids in the consistency of portable implementation of data  
communications software.  

Copyright ©1988, 1989, 1994 Mohsen Banan.

Copyright ©1994-1997 Neda Communications, Inc.

 
Published by Neda Communications, Inc.  
3610 164th Place SE  
Bellevue, WA 98008 USA  
 
Permission is granted to make and distribute verbatim copies of this  
manual provided the copyright notice and this permission notice are  
preserved on all copies.  
 
Permission is granted to copy and distribute modified versions of this  
manual under the conditions for verbatim copying, provided that the  
entire resulting derived work is distributed under the terms of a  
permission notice identical to this one.  
 
Permission is granted to copy and distribute translations of this  
manual into another language, under the above conditions for modified  
versions, except that this permission notice may be stated in a  
translation approved by the Copyright holders.  

Contents

1 INTRODUCTION
 1.1 Lower Layers
 1.2 Target Environment
 1.3 Development Environment
 1.4 The Open C Environment
 1.5 Definition of Terms
2 OPEN C ENVIRONMENT
 2.1 Open C Layer Architecture
  2.1.1 Upper Interface
  2.1.2 Lower Interface
  2.1.3 Network Management Interface
  2.1.4 Open C Platform Interface
  2.1.5 Significant Events
3 CONVENTIONS
 3.1 Identifier Naming
 3.2 Identifier Naming Details
  3.2.1 Naming GuideLines
  3.2.2 Abbreviations
  3.2.3 Rationale
 3.3 Source File Names
 3.4 Implementation of Sequences and Sets
 3.5 Restrictions on Usage of Features in C
 3.6 Compile Time Configuration
 3.7 Global Standard Definitions (estd)
4 COMMON FEATURES OF A LAYER
 4.1 A Layer’s Interfaces
  4.1.1 Initialization
  4.1.2 SAP Management
  4.1.3 Upper Interface
  4.1.4 Lower Interface
  4.1.5 Layer Management Interface
 4.2 Usage of Resources
 4.3 Integration of Layers
  4.3.1 The G_ module
5 MODULE MANAGEMENT ARCHITECTURE
 5.1 Module Management (MM)
  5.1.1 Module Management Initialization
  5.1.2 Module Management Entity (MME) facilities
  5.1.3 Module Management Agent facilities
 5.2 Layer Management Entity Interface
6 OPEN C PLATFORM
 6.1 OCP Interfaces
 6.2 Environment Specific Facilities (SF_)
  6.2.1 Obtaining Memory
  6.2.2 Synchronization
  6.2.3 Atomic Queue Operations
  6.2.4 Scheduling
  6.2.5 Timer Facilities
 6.3 Execution Scheduler (SCH_)
 6.4 Byte Ordering (BO_)
 6.5 Byte String (BS_):
 6.6 Queue Module (QU_)
  6.6.1 QU_ Macros
 6.7 Sequence Module (SEQ_)
  6.7.1 Example Usage
 6.8 Non-Volatile Queue (NVQ_)
  6.8.1 NVQ_ReturnCode
  6.8.2 NVQ_create
  6.8.3 NVQ_open
  6.8.4 NVQ_close
  6.8.5 NVQ_delete
  6.8.6 NVQ_VIEW_HEAD
  6.8.7 NVQ_VIEW_TAIL
  6.8.8 NVQ_VIEW_ELEM
  6.8.9 NVQ_INSERT_AT_HEAD
  6.8.10 NVQ_INSERT_AT_TAIL
  6.8.11 NVQ_INSERT_BEFORE
  6.8.12 NVQ_INSERT_AFTER
  6.8.13 NVQ_REMOVE_HEAD
  6.8.14 NVQ_REMOVE_TAIL
  6.8.15 NVQ_REMOVE_ELEM
  6.8.16 NVQ_FIRST
  6.8.17 NVQ_LAST
  6.8.18 NVQ_NEXT
  6.8.19 NVQ_PREV
  6.8.20 NVQ_EQUAL
 6.9 Exception Handling (EH_)
 6.10 Log Module (LOG_)
  6.10.1 Log Module Initialization
  6.10.2 LOG_ User Initialization
  6.10.3 Log Message Display
 6.11 Trace Module (TM_)
  6.11.1 Trace Module Initialization
  6.11.2 TM_ User Initialization
  6.11.3 Trace Message Display
  6.11.4 Example Usage
  6.11.5 Run Time Control of TM_
 6.12 SAP management (SAP_)
  6.12.1 Representation of a SAP Address
  6.12.2 SAP Address Manipulation Facilities
 6.13 Timer Management Module (TMR_)
  6.13.1 Starting a Timer
  6.13.2 Stopping a Timer
  6.13.3 Associating User Data with Timers
  6.13.4 Implementation Specific Interfaces
  6.13.5 Example Usage
 6.14 Data Unit Management (DU_)
  6.14.1 Creation of a Pool
  6.14.2 Creation of a Data Unit
  6.14.3 Creating a new View
  6.14.4 Freeing a View
  6.14.5 Manipulating a View’s Data
  6.14.6 Accessing a View’s User Information
  6.14.7 Example Usage
 6.15 Buffer (BUF)
  6.15.1 Allocate and Free a Buffer
  6.15.2 Add, Get, and Unget an Octet
  6.15.3 Allocate and Assign a New Buffer Segment
  6.15.4 Prepend a Buffer
  6.15.5 Get the Next Chunk of a PDU
  6.15.6 Append a String to a Buffer
  6.15.7 Append One Buffer to Another
  6.15.8 Reset Buffer Pointers
  6.15.9 Copy a Buffer
  6.15.10 Clone a Portion of a Buffer
  6.15.11 Get the Length of a Buffer
  6.15.12 Display a Buffer
 6.16 Configuration Module (CFG)
  6.16.1 Open and Close a Configuration File
  6.16.2 Get a Section
  6.16.3 Get a Parameter
  6.16.4 Operate on Parameter Values
  6.16.5 Permanance
 6.17 Subscriber Profile Module (PROFILE)
  6.17.1 Open and Close a Profile Library
  6.17.2 Add an Attribute to a Profile
  6.17.3 Search a Profile
  6.17.4 Get an Attribute Value
 6.18 Abstract Syntax Notation (ASN)
  6.18.1 Trace Flags
  6.18.2 Functions
  6.18.3 Functions
  6.18.4 ASN_tableEntry Declaration
 6.19 Finite State Machine (FSM_)
  6.19.1 State Machine Functions
  6.19.2 Transition Diagram Functions
  6.19.3 FSM Usage Examples
 6.20 User Datagram Protocol Point of Control & Observation (UDP_PCO_)
  6.20.1 Initializing the Package
  6.20.2 Creating a SAP
  6.20.3 Removing a SAP
  6.20.4 Sending Data via a SAP
  6.20.5 Receiving Data via a SAP
  6.20.6 Logging User Data
  6.20.7 Intentionally Interrupting User Data
  6.20.8 Build Options
  6.20.9 Example
 6.21 IMQ
 6.22 UPQ
 6.23 Release Identification Module (RELID_)
  6.23.1 Generation of RELID_ String
  6.23.2 Example Usage
 6.24 Copyright Notice Module (CPR_)
 6.25 License Module (LIC_)
  6.25.1 Generating A License File
  6.25.2 Checking Against a License File
 6.26 Integer To English (int2english)
  6.26.1 PF_intToCardinalEnglish
  6.26.2 PF_intToOrdinalEnglish
  6.26.3 PF_intToDigitEnglish
  6.26.4 PF_strToDigitEnglish
7 EXAMPLE USAGE OF THE PLATFORM
8 IMPLEMENTATION OF THE PLATFORM
 8.1 Implementation Map
 8.2 Un-hosted Facilities
 8.3 Hosted Facilities
 8.4 Portable Facilities
  8.4.1 TM_ Module
 8.5 Supported Operating Systems
  8.5.1 UNIX
  8.5.2 MS-DOS
  8.5.3 VMS
9 DEVELOPMENT ENVIRONMENT
 9.1 Supported Development Environments
  9.1.1 Solaris
  9.1.2 Windows NT
  9.1.3 Windows 95
  9.1.4 DOS
 9.2 Supported Compilers
  9.2.1 GCC
  9.2.2 Microsoft Visual C++ Developer Studio
  9.2.3 Borland C 4.5
  9.2.4 Purify
 9.3 Supported Target Environments
  9.3.1 Solaris
  9.3.2 Windows NT
  9.3.3 Windows 95
  9.3.4 DOS
  9.3.5 Windows CE
  9.3.6 Embedded
 9.4 General Philosophy
 9.5 Build Mechanisms
  9.5.1 Adding New Modules
  9.5.2 Adding Support For New Compilers
A GNU LIBRARY GENERAL PUBLIC LICENSE

List of Tables

List of Figures

Foreword

Realization of global connectivity through the concept of Open Systems Interconnection (OSI) will be the reward of a significant collective effort. The development of OSI over the past ten years has involved the collective efforts of many experts from many countries.

A great deal of the development of OSI is in its final stages. Fruits of these efforts are beginning to appear in our daily lives as implementation of OSI protocols. The future of OSI is very exciting and its impact on our lives will be significant.

This book focuses on creating an environment (a model, and architecture and a platform) for software implementation of OSI protocols. It is assumed that the reader is familiar with the concepts of OSI Reference Model. This book establishes a reference model for portable software implementation of OSI in C.

Although the primary intent of this book is to establish a platform for implementation of International Standards Organization (ISO) specification of OSI protocols, a great deal of the contents of this book applies to layered software implementation in general.

The C programming language has proven itself as a popular portable and efficient language for implementation of data communications software. The implementation environment described in this book is centered around C. It is assumed that the reader has a working knowledge of C.

Software implementation of OSI protocols that adhere to the ”Open C Environment” (OCE) described in this book can be integrated to realize efficient real open systems. The environment presented in this book has been used for implementation of a number of ISO specification of OSI protocols. Any C compiler that conforms to the ANSI C specification can be used to port this implementation platform to the target environment.

It is the aim of this book to refine the abstract descriptions of the OSI model as they apply to software implementation in C. An implementation environment that provides for efficient integration of OSI protocols is created. Specification of OSI protocols, C language and the environment described in this book provide for portable and efficient realization of real open systems.

Implementors, system architects, system programmers, application programmers and anyone who is interested in understanding the implementation aspects of OSI can benefit from reading this book. This book can be used to teach the practical aspects of data communications software development in conjunction with other books that deal with the concepts of Open Systems Interconnections.

The structure of this book is as follows. Chapter 1 provides an introduction to the issues involved in implementation of OSI. Chapter 2 describes the Open C Environment. Chapter 3 outlines a number of conventions followed in defining the Open C Platform. Chapter 4 outlines the common features of the implementation layers. Chapter 5 deals with the architecture of network management. Chapter 6 describes the interface and service definition for Open C Platform. Chapter 7 provides an example usage of Open C Platform. Chapter 8 deals with implementation issues. Appendix A contains a set of UNIX style manual pages for facilities of Open C Platform.

Acknowledgement

Many of the implementation techniques outlined in this book are very similar to the ones practiced by NBS 1, Retix and a number of other implementors. Little, if any, of the credit for the implementation techniques should go to the author. My goal has been to combine these commonly practiced good techniques into an environment that may facilitate the realization of OSI.

I wish to thank my colleagues at Retix who inspired the ideas behind many of the concepts appearing in this book.

A number of individuals at several companies have contributed to the creation and expansion of sections of this manual as well as the software itself. Neda Communications, Inc. leads the effort of maintaining and documenting the majority of the software.

Significant contributions to this work resulted from the use of OCP by AT&T Wireless Services.

Finally, a number of individuals who have made contributions to the OCP library and this document deserve special recognition.

  • Derrell Lipman - Visual Aviation derrell@vis-av.com
  • Sanjay Bapat - PCSI, Inc. SPB@pcsi.cirrus.com
  • Mohsen Banan - Neda Communications, Inc. mohsen@neda.com
  • Steve Farowich - Neda Communications, Inc. steve@neda.com
  • Kamran Ghane - Neda Communications, Inc. kamran@rostam.neda.com
  • Fletch Holmquist - Neda Communications, Inc. fletch@neda.com
  • Hugh Shane - Neda Communications, Inc. hshane@neda.com

We look forward to continued growth of the OCP library. Please send your feedback, including code contributions, to

Mohsen Banan - Neda Communications, Inc. mohsen@neda.com

About This Document

This manual is written in LATEXinfo. LATEXinfo is a documentation system that uses a single source file for both on–line documentation and a printed manual. See the LATEXinfo Manual for more details [1].

The on–line documentation is in the form of an Info file. An on-line Info file is a file formatted so that the Info documentation reading program can operate on it. Info files are divided into pieces called nodes, each of which contains the discussion of one topic. M-x info in emacs and xinfo under X11 are two Info documentation reading programs that can be used for on-line manipulation of this manual.

Release Information

Module openCPlatform
Was released as Revision: on by The name tag for this release is The file capturing this release is

Caveats

This manual is mostly complete and has gone through a few drafts. However, it is far from being flawless.

This document should be fully correct in what it does say; and it is therefore open to criticism on anything it does include — from specific examples and descriptive text, to the ordering of chapters and sections. If something is confusing or incorrect, then perhaps the document should be fixed.

As you use this document, please mark pages with corrections so you can later look them up and send them in. Please reference any comments to the chapter name and section name, since page numbers and chapter and section numbers will change.

Comments

Comments concerning this document should be addressed to:

        E-Mail:                 mohsen@neda.com  
 
        Postal Address:  
                                Mohsen Banan  
                                Neda Communications, Inc.  
                                17005 SE 31st Place  
                                Bellevue, WA 98008  
 
        Fax:                    (425) 562-9591

Chapter 1
INTRODUCTION

International Standards Organization (ISO) specification of OSI model and protocols are based on a number of abstract descriptions which specify essential requirements but make no mention of how these requirements should be met by an implementation.

Typically each OSI layer has two sets of specifications: One for the services provided by the protocol and one for the protocol. Service specifications for each layer are normally described in a high level of abstraction. The interfaces for the service definition is left at the level of primitive. Furthermore, the ISO specifications do not deal with any details concerning the mechanism used to exchange primitives across a layer interface.

Lack of a standard interface or a standard mechanism for exchange of primitives across a layer interface can cause severe problems in implementation of machine independent OSI software.

OSI Reference Model offers a number of features that are well aligned with today’s software implementation methodology. To name a few:

  • OSI model subdivides the communications functions into logically separate modules.
  • Exclusive peer-to-peer interaction.
  • A well defined service definition expected from each layer.
  • Independence of protocol specification from the services expected from the protocol.

A well defined model, architecture and interface provides for integration of independent implementations of OSI protocols. It is the aim of this book to refine the abstract descriptions of the OSI model and create a software implementation environment (A model, an architecture and a platform) that facilitates the implementation of OSI.

Given today’s state of technology a number of observations are made.

  • The specification of the bottom five layers of OSI have been adopted as ISO standards and are well understood.
  • C language has been recognized as a standard for portable and efficient implementation of data communication software.
  • A correct, efficient and environment independent implementation of OSI protocols is very desirable.

The author therefore feels that the time is right for creation of a software environment that can facilitate the realization of OSI. Such a platform should be:

  • Operating Environment (Operating System/ CPU/ Hardware) independent.
  • Efficient.
  • Consistent.
  • Expandable.

This has been the motivation behind the creation of ”Open C Environment” (OCE) for implementation of OSI. OCE is a set of architectural guide lines, conventions and a platform for portable implementation of OSI software. Independent implementations of OSI protocols that adhere to OCE can easily be integrated to realize real open systems.

A platform of facilities that can ease the implementation of OSI protocols is provided. One of the primary goals of this book is to formally define the interface to this platform of facilities.

1.1 Lower Layers

The nature of the different services expected of the different layers results into particular services expected from the implementation environment. The lower layers (Transport, Network, Data Link and Physical) are responsible for transport of unstructured data. The upper layers (Application, Presentation and Session) deal with the structure, syntax and semantics of the communication.

The upper layers expect more services form their implementation environment than the lower layers. The implementation environment expected by the upper layers can be considered as an extension of the lower layers implementation environment.

It is recognized that at this time only the bottom five layers have matured. This book’s primary focus is to create an implementation environment for the lower layers.

1.2 Target Environment

One of the goals for the creation of Open C Environment for implementation of OSI is portability and environment independence. Two basic categories of target environments are identified.

  • Hosted
  • Un-Hosted

The Hosted-Environment is an environment in which the existance of an operating system and multitasking capabilities may be assumed. The availability of facilities such as scheduling, timers, synchronization and dynamic memory allocation are often available in Hosted-Environments. UNIX, VMS, MS-DOS and VRTX are examples of hosted environments.

The Unhosted-Environment is an environment in which the existance of no facilities may be assumed. The underlying environment should at least provide:

  • CPU
  • Adequate amount of memory
  • Periodic interrupt

Bare, intelligent, front-end processors are examples of Unhosted-Environments.

Open C Environment is designed to exist in Hosted and Unhosted environments. In Hosted-Environments, the interface to host facilities should be mapped on to the Open C Platform interface definitions. Design of OCE does consider well-behaved existance in Hosted-Environments.

The type of environment specific facilities defined in OCE are basic and simple. These facilities can easily be implemented from scratch in Un-Hosted environments.

1.3 Development Environment

A C compiler, an assembler, a linker, and a loader are expected of a development environment necessary for use of OCE.

The primary development environment used by the author is UNIX.

1.4 The Open C Environment

This section defines the relationship between OCP and the various components in it’s Environment. In the following discussion refer to the diagram in Figure 1.1


PIC

Figure 1.1: Open C Environment


The diagram as a whole represents a particular implementation of an Open C Layer. The Application, represented as the highest level component, is the body of software that is unique to a given application or service. The CPU/Memory combination, at the lowest level, represents the minimum computing functionality that OCP requires. The Operating System, which may or may not exist on a given computing platform, provides some set of services to OCP. Finally, a particular C Compiler is used to generate machine executable code.

For example, in the case of a Unix workstation, the CPU might be a 64-bit processor with gigabytes of virtual memory. The operating system would provide a wide range of services including disk file I/O, interprocess communication, and network services.

On the other hand, a portable messaging device might use a 16-bit processor with 64 kilobytes of memory while the operating system might be nothing more than a simple task scheduler.

OCP isolates the Application from all of this underlying complexity and variability. Once OCP is ported to a given Open C Environment (CPU/Memory, Operating System, and Compiler) any Application developed under one Open C Environment can easily be ported to another.

1.5 Definition of Terms

Definitions, notation, abbreviation and terminology used in this book are consistent with the terminology and principles established by ISO for Open Systems interconnection.

The OSI reference model is based on a number of ’abstract’ descriptions. In our implementation model, these abstract descriptions are refined to define the precise context they take as they apply to this implementation architecture.

Facility
To evade the question of whether an operation is implemented as a function or a preprocessor macro, the word facility is used. What is of interest is the facility’s interface description. Most of the facilities are described as if they were functions. But when efficiency justifies the equivalent may be implemented as macro. With this understanding, ’facility’ and ’function’ are used interchangeably.
Module
Typically a set of related facilities and data abstractions are combined into a module. The facility is typically realized by a link module (e.g. a library) and a declaration module. The correct way to use a facility is to have, at the beginning of the user program, a preprocessor #include command to include the relevant facility declarations.
Open C Environment
OCE is a set of architectural guide lines, conventions and a well defined platform interface that can ease portable implementation of OSI software.
Open C Platform
OCP is a collection of modules that provide the basic facilities expected by lower layers. The interface to these facilities is described in this book.
Open C Layer
An OCL is an implementation of an OSI layer that adheres to the architecture of Open C Environment.
Service Provider
A module responsible for providing some well defined set of services through a well defined set of interfaces.
Service User
A module that uses the services of a service provider.
Primitive
A facility expressing an interaction between a service user and a service provider.
Parameter
A facility argument to a primitive.
Primitive Action
A facility invocation into the service provider module. Primitive actions are provided in the service provider module and invoked by the service user. Primitive action is the collective name for requests and responses.
Primitive Event
A facility invocation outside of the service provider module. Typically in the service user module. Primitive events are provided in the service user module and invoked by the service provider. Primitive event is the collective name for indications and confirmations. The set of primitive events to be used are communicated to the service provider during the creation of the service access point.
Request
A primitive issued by the service user to express a request for a service from the service provider.
Indication
A primitive issued by the service provider to indicate that a request has been issued by the service user at the peer service access point or to communicate a local event to the service user.
Response
A primitive issued by the service user in response to some indication previously invoked by the service provider.
Confirm
A primitive issued by the service provider in response to some response previously issued by the service user.
Service Access Point

A service access point (SAP) is defined as the interface between a service user and a service provider. Each SAP is identified by the service provider through a SAP-Address-Selector.

Connection End Point

An (N) connection is an association established by the (N) layer between two or more (N+1) entities for the transfer of data. An (N) connection end point (CEP) is a terminator at one end of an (N) connection within an (N)-SAP. An (N) connection end point identifier (CEP-ID) is a unique representation of a CEP within the scope of the (N) service

sequence-of
Borrowed from ASN.1. sequence-of type: A structured type, defined by referencing a single existing type; each value in the new type is an ordered list of zero, one or more values of existing type.
set-of
Borrowed from ASN.1. set-of type: A structured type, defined by referencing a single existing type; each value in the new type is an unordered list of zero, one or more values of the existing type.

Chapter 2
OPEN C ENVIRONMENT

Open C Environment is a set of architectural guidelines, conventions, and a common platform that allow for efficient implementation and integration of OSI protocols in C. Open C Environment defines the architecture and the mechanism used for exchange of primitives across layer interfaces. Open C Platform defines the interfaces to a set of common facilities that may be used by Open C layers.

An Open C Layer is the implementation of an OSI protocol that conforms to Open C Environment architecture and guidelines. Direct function calls are used for exchange of primitives across Open C layers. This simple and efficient primitive exchange mechanism allows for integration of Open C Layers into multi-layered communication entities. Other methods for exchange of service primitives (such as interprocess or interprocessor communication facilities) often result into performance degradation across layer boundaries.

Once the upper and the lower interfaces of a Layer are defined (based on the service definitions), independent implementors can implement Open C Layers. Since the upper interface of implementation of (N) layer protocols match the lower interface of implementation of (N+1) layer protocols, several Open C Layers can be integrated into a multi-layered communication software entity.

2.1 Open C Layer Architecture

An Open C Layer is a cohesive piece of software that provides a well defined service and has a set of well defined interfaces. An OSI Open C Layer implements an OSI protocol. Open C Layers have a consistent design architecture. Each implementation of an OSI protocol, provides to its user the set of services defined for that protocol at its upper interface. It assumes the services of the layer below it to be present at its lower interface.

A typical software layer (N) appears to its user as a link module with four defined interfaces. The figure below (Figure 2.1) presents an interface model for the (N) software module.


PIC

Figure 2.1: Architecture of a Layer


2.1.1 Upper Interface

The (N) Open C Layer is expected to provide the services defined for the (N) layer at its upper interface. The (N) Open C Layer’s upper interface is a series of function calls (primitives). Each function call accepts a group of arguments (parameters). Each function call is non-blocking.

(N) request and responses, collectively referred to as (N) action primitives, are function calls into the (N) Open C Layer. (N) action primitives are invoked by the (N) service user. The code for (N) action primitives is inside the (N) Open C Layer.

(N) indication and confirmations, collectively referred to as (N) event primitives, are function calls outside of the (N) software module. (N) event primitives are invoked by the (N) software module. The code for (N) event primitives is expected to be provided by the (N) service user. The entry point for (N) event primitives is conveyed to the (N) layer during the creation of the service access point by (N) service user.

2.1.2 Lower Interface

The (N) Open C Layer may use the services defined for the (N-1) layer at its lower interface. The lower interface of the (N) software module matches the upper interface of (N-1) software module.

2.1.3 Network Management Interface

Operation of an OSI layer may be monitored and manipulated by the Network Management Administrator. To provide for this each Open C Layer is responsible for providing an interface that allows for network management administration.

Within each Open C Layer, often a Layer Management Entity (LME) is responsible for defining and providing the network administration interface.

2.1.4 Open C Platform Interface

An Open C Layer can rely on the services provided by the Open C Platform. The interface and the description of the services provided by the Open C Platform is described in this book.

2.1.5 Significant Events

The following is a list of significant events that result into execution of code inside of (N) Open C layer.

  • (N) Initialization.
  • (N) SAP Management.
  • (N) Action Primitives.
  • (N-1) Event Primitives.
  • Timer Expiration Events (See TMR_ module).
  • (N) Re-Scheduling Request.

Chapter 3
CONVENTIONS

A set of programming conventions and restrictions are followed to improve portability and readability. These conventions are visible to the software modules that interface with Open C Platform. For sake of consistency it is suggested that the following simple conventions be adapted when interfacing with other elements of Open C Environment.

Good programming conventions can result in improvements in consistency, portability, readability and writability. The development environment and the nature of the software developed have a large influence on the styles and conventions that are adapted. As the development environment and software engineering methodology evolve, the stylistic notations and conventions will also evolve.

The identifier naming conventions described here are consistent with ISO’s conventions in specification of ASN1 definitions. These naming conventions are also consistent with the conventions followed in the C bindings produced by MAP and TOP groups. There are some differences but these are minor.

3.1 Identifier Naming

The identifier naming conventions include:

  • Variables, functions, parameters and struct fields beginning with lower-case, then upper and lower-case mixed. N_sapCreate and sapAddr are examples of function and parameter identifiers in the following example. ”N_” in ”N_sapCreate” is a module prefix and is not subject to this convention.
        N˘SapDesc  
        N˘sapCreate(sapAddr)  
        N˘SapAddr ⋆sapAddr;

  • Typedefs, struct/Union/enum tags named with upper-case groups. Beginning with upper case, then lower and upper-case mixed:
        String, struct N˘SapAddr

  • #define and enumerated constants named with upper-case letters:
        FALSE, MAXLENGTH

  • Identifiers exported by a module prefix followed by an ’_’. The module prefix can be 1 to 4 letters long.
        QU˘init, TMR˘Desc, N˘SAPLENGTH

The layout of expressions and statements follow those in the book written by Kernighan and Ritchie entitled ”The C Programming Language”.

The few simple conventions mentioned above are adequate for describing the basic guide lines. The following section describe in more detail the naming conventions followed and the rationale behind it.

3.2 Identifier Naming Details

The naming conventions recommended in this section are specific to the C programming language. These conventions take full advantage of the identifier naming facilities offered by the standard definition of C language. Lower and upper case letters as well as ’_’ are used in this naming convention. All identifiers are expected to be unique with in the first 24 characters.

Concept of a module and hiding in C is limited to the source file. The scope of an identifier outside of a source file is global. Explicit importing and exporting of identifiers is not supported in standard C. This naming convention tries to address this known deficiency in C.

All identifiers are composed of two elements: module prefix and qualifier. Each module is identified by a module prefix. A module prefix is a short name (normally 1 to 4 characters long) followed by an ’_’. The case of the module prefix specifies the scope of the identifier with regard to that module. Identifiers exported by a module, have an all upper-case module prefix. An all lower case module prefix signifies that although the identifier is needed by more than one source file within the implementation of the module, it is purely private to the module and need not be exposed to any users of the module. Purely local identifiers need not have the module prefix component and consist of a pure qualifier. In addition to conveying the scope of the identifier, this convention results in prevention of naming collisions across independent modules.

The qualifier component of an identifier mainly conveys the semantic attributes of the identifier. The qualifier component may consist of many words. With the exception of the first word, all following words start with upper-case. The first character of the qualifier conveys some type information. Variables, functions, parameters and structure fields begin with lower-case, the then upper and lower-case mixed. Typedefs, struct/union/enum tags named with upper-case groups. Although not clearly specified in the language definition, typedefs name space is different from struct/union/enum tags name space. Name space overloading is encouraged.

This convention results into clear usage of the same name for a number of related identifiers. This is demonstrated in the following example.

        typedef struct SapSelector {  
                Int len;  
                Byte addr[NSAPSZ];  
        } SapSelector;  
 
        SapSelector sapSelector;

Same descriptive name ”sapSelector” is used for the structure tag identifier, the type definition identifier and the variable identifier for a generic instance.

3.2.1 Naming GuideLines

A set of recommendations are proposed for qualifier naming.

Grouping/Classing
A concept is often expressed through a set of related identifiers. Within a module, related identifiers can be grouped in a variety of ways. Grouping with regard to the data class often works fine. Take the case of SAP management in ”N_” module, N_sapCreate, N_sapDelete, n_SapInfo, N_SapDesc would be considered natural choices.
Procedures
A verb followed by noun is often a good choice.
Labels
Same as Procedures.
Booleans
A phrase expressing the TRUE case of the variable.

3.2.2 Abbreviations

A number of abbreviations are commonly used to express well defined concepts with in the scope of OSI implementation. These abbreviations are commonly used for identifier naming.

Req
A request primitive.
Rsp
A response primitive.
Ind
An indication primitive.
Cnf
A confirmation primitive.
Sap
Service Access Point.
Cep
Connection End Point.
Du
Data Unit.
Pdu
Protocol Data Unit.
Sdu
Service Data Unit.
Pci
Protocol Control Information.
Buf
Buffer.
Addr
Address.
Sel
Selector.
Src
Source.
Dst
Destination.
Loc
Local. Matches with Rem.
Rem
Remote. Matches with Loc.
Seq
Sequence. Head of a linked list of ordered elements.
Set
(Noun) Head of a linked list of unordered elements.
Elem
Element. An element in a sequence, queue, set.
Next
Matches with prev. A valid value.
Prev
Previous. Matches with next. A valid value.
Last
Matches with first. A valid value.
First
Matches with last. A valid value.
Lim
Limit. Not a valid value.
Min
Minimum. A valid value. Compile or link time constant.
Max
Maximum. Not a valid value. Compile or link time constant.
Info
Information. Often used to provide an internal representation of a resource.
Desc
Descriptor. Often used to provide a public handle to a resource.
Ref
Reference. Often used as a prefix to provide a handle to a resource.
Prov
Provider. To identify roles in a service provider/user situation.
User
To identify roles in a service provider/user situation.
Cur
Current.
Val
Value.
Init
Initialize.
Term
Terminate.
Get
Retrieve an information object from an information base.
Set
(Verb) Set an information object in an information base.

3.2.3 Rationale

The primary intentions of the identifier naming convention mentioned above is to convey important information about identifiers while keeping the names short and natural.

The following is a partial list of the intentions of this naming convention.

  • Maximize conveying important identifier attributes while keeping the names short and natural.
  • Emphasis on semantic information. An identifier’s primary responsibility is to convey the natural aspect of what it represents.
  • Emphasize module definition and highlight scope recognition. Definition of C language is limited in its ability with regard to modularity and hiding to one source files. This naming convention extends the module and scope concepts beyond one source module.
  • It is recognized that complete type information about all identifiers is accessible through their definition and context. Proper tools may be used to perform syntax type checking improve reliability. Some information regarding the type of the identifier is conveyed in this naming convention. The conventions with regard to type allow for name space over loading and minimize name selection.

3.3 Source File Names

Recognizing the restrictions that may be imposed by the development environments that may be used, the following conventions are recommended.

  • Base of the file name is limited to 8 characters. The extension of a file name is limited to 3 characters.
  • Only lower case letters and ’_’ may be used in file name specification.
  • C header files have a ”.h” extension.
  • C source files have a ”.c” extension.

With these restrictions even MS-DOS development environment can be supported.

3.4 Implementation of Sequences and Sets

The concepts of ASN.1 sequences-of and sets-of are not inherent in C. Arrays are adequate for static usage. Dynamic usage is often implemented through the usage of linked lists. For implementation purposes set-of and sequence-of are considered the same. Relevance of order is the user’s view and not an implementation issue. Only the implementation of sequence-of is described here.

ASN.1 sequence concept maps to struct in C. With this understanding, for design purposes a shorthand notation is adapted to make the concept of sequence-of more natural to C. The following keyword extension are made:

        sequence  
        sequenceof

Their usage is similar to struct and union. sequence specifies an element of a list. sequenceof specifies the head of a list. These are based on the QU_ and SEQ_ module. sequence and sequenceof can be used for data or instance declaration.

Consider the following example:

        typedef sequence SomeInfo {  
                Int someField;  
        } SomeInfo;  

Which is equivalent to:

        typedef struct SomeInfo {  
                struct SomeInfo ⋆next;  
                struct SomeInfo ⋆prev;  
                Int someField;  
        } SomeInfo;

For a sequenceof instance declaration, consider:

        sequenceof SomeInfo someInfoSeq;

Which is equivalent to:

        struct {  
                SomeInfo ⋆first;  
                SomeInfo ⋆last;  
        } someInfoSeq;

For a sequenceof type declaration, consider:

        typedef sequenceof SomeInfo {  
                Int nuOfElems;  
        } SomeInfoSeq;  
        SomeInfoSeq someInfoSeq;

Which is equivalent to:

        typedef struct {  
                SomeInfo ⋆first;  
                SomeInfo ⋆last;  
                Int nuOfElems;  
        } SomeInfoSeq;  
        SomeInfoSeq someInfoSeq;

Implementation of sets-of can be done as sequences-of. The user may convey the irrelevance of order through the usage of:

        set  
        setof

reserved word extensions.

3.5 Restrictions on Usage of Features in C

Open C Environment conforms to the ANSI C standard. At present, a large number of existing C compilers have not implemented all the new features in ANSI C. New features of C, (function prototypes, structure assignment and new reserved words) may be used only if backwards compatibility is maintained. This can often be accomplished through conditional compilation.

Pre-processor identifier ANSIC is reserved for this purpose. Only environments that conform to the standard should have it defined. The following example demonstrates the proper usage of the new features.

#ifdef ANSIC  
typedef void ⋆ Ptr;  
#else  
typedef unsigned char ⋆ Ptr;  
#endif  
 
#ifdef ANSIC  
SuccFail N˘sapCreate(Int sapSel);  
#else  
SuccFail N˘sapCreate();  
#endif

Structure assignment and use of structures as function arguments is also discouraged unless compatibility with older compilers is maintained.

3.6 Compile Time Configuration

Environment specific facilities may be implemented in a variety of ways. To support more than one target environment through the same source code, conditional compilation features are often used. Three basic elements of the operating environment are recognized as:

  • The operating system.
  • The CPU type.
  • The C compiler.

Conventional compile time identifiers that identify the operating environment are placed in a file called ”oe.h”. When porting the Open C Platform ”oe.h” must be properly configured to reflect the target environment.

When developing on a PC-AT running XENIX, my oe.h is configured as: _______________________________

#ifndef _OE_H_ /*{*/

#define _OE_H_

/*

* CPU.

* Used for byte order representation of integers.

* Supported CPUs are:

* INTEL for 8086 family (8088, 80186, 80188, 80286)

* VAX for DEC VAX mini-computers.

* M68K for Motorola MC68000 family processors 10

* NS16 for National Semiconductor NS16000 series processors.

*/

#define INTEL

/*

* Operating System.

* Used for OS specific interprocess communication and

* other OS specific facilities.

* Supported Operating Systems are:

* SIMU No operating system at all. 20

* SYSV System V Unix release {2,3}.

* BSD Berkeley Unix release 4.{2,3}.

* MSDOS

* VMS

*/

#define SYSV

/*

* Compiler.

* Used to identify the compiler. 30

* This can be used to work around abnormalities of the C compiler.

* Supported Compilers are:

* KANDR Traditional compilers.

* ANSIC Standard conformant.

*/

#define ANSIC

#endif /*}*/ _________________________________________________________________________________


________________________________________________