 |
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. 17005 SE 31st Place, 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.
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.
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.
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
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 [].
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.
Module openCPlatform
Was released as Revision: on by The name tag for this release is The file capturing this release is
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 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
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:
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 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:
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.
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.
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.
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:
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.
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.
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
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
The following is a list of significant events that result into execution of code inside of (N) Open C layer.
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.
The identifier naming conventions include:
N_SapDesc
N_sapCreate(sapAddr)
N_SapAddr *sapAddr;
String, struct N_SapAddr
FALSE, MAXLENGTH
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.
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.
A set of recommendations are proposed for qualifier naming.
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.
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.
Recognizing the restrictions that may be imposed by the development environments that may be used, the following conventions are recommended.
With these restrictions even MS-DOS development environment can be supported.
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.
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.
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:
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:
Click here to see the complete codes.
All Open C Environment source modules include the global portable standard definitions definitions file estd.h. Documentation on estd.h is provided in appendix A. Basic portable data type definitions are defined in estd.h.
Each layer has a number of typical exposed interfaces. As an example let's consider a sample software layer called "Some Service Provider" (SSP_). (SSP_) is expected to provide some defined services to the layer above it (UPPER_). It can rely on the services offered by the layer below it (LOWER_). The usual interfaces of the SSP_ layer are listed below:
Initialization:
SSP_init()
SSP_term()
SAP Mangement Interface:
SSP_sapCreate()
SSP_sapDelete()
Upper Interface:
SSP_actionPrim(), ...
(*upperEventPrim)(), ...
Lower Interface:
LOWER_ActionPrim(), ...
ssp_lowerEventPrim(), ...
Layer Management Interface:
SSP_lmInit()
SSP_lmActionPrim(), ...
(*lmEventPrim)(), ...
Open C Platform Interface:
TM_, EH_, SCH_, DU_, TMR_, ...
Consistent with the naming conventions mentioned in the previous section, all exposed interfaces of this module are prefixed by SSP_. The indirect function invocation (*func)() notation is used to indicate the event primitive interaction with other layers.
Each layer can expect to be initialized before providing any services. During the initialization, the module can obtain its required resources and become ready to provide its expected services. The entry point to initialize the SSP_ layer is SSP_init().
Each Open C Layer must have a mechanism to be terminated and re-initialized. After termination a layer is not expected to maintain any history of what had happened prior to termination. The module must be re-initialized before being used. During a reset the layer should release all the resources that it had previously obtained. The entry point to terminate the SSP_ layer is SSP_term().
All initialization functions should be idempotent, meaning multiple invocations of the initialization facility do not result in an error. The following code fragment illustrates a conventional implementation of initialization and termination facilities.
static Bool virgin = TRUE;
Void SSP_init()
{
if (virgin) {
virgin = FALSE; /* Only first time counts */
/*
* - Obtain necessary resources.
* - Provide your services.
*/
}
}
Void SSP_term()
{
virgin = TRUE; /* Can be re-initialized */
/*
* - Terminate your services.
* - Release resources.
*/
}
All service provider layers have a means to support multiple service users simultaneously. This is supported through the concept of Service Access Points.
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. Above the network layer SAP address selectors are derived from SAP address suffixes.
Each service user is expected to create a service access point before using any of the services of the provider. Each layer has a function to create a SAP and a function to delete a SAP. Upon SAP creation, the service provider, associates SAP address selector of a service user entity with the address of a number of function(s) within the service user entity. These functions will be used by the service provider to handle indications and confirms (primitive events) at the upper interface.
Each Open C Layer is expected to provide its services at its upper interface. The set of action primitives provided by the layer must be known by the service user. Entry points for events primitives must have been conveyed to the layer during the creation of the service access point. The calling sequence for event primitive must be consistent with the service user's expectations.
Open C Layers may rely on the services provided by the layers below them. The set of action primitives provided by the layer below must be known. Entry points for event primitives are conveyed to the layer below during the SAP creation.
Each layer has a layer management entity (LME) responsible for administration of the layer. This subject is discussed in more detail in chapter 4.
OSI resources such as SAPs and CEPs are often dynamically used. Creation, usage and deletion of these resources often follow a common pattern. This common pattern is described in this section.
Usage of resources is often through a descriptor based scheme. Through a create operation a unique descriptor referencing an instance of the resource is obtained. This descriptor is used as a reference to the resource in all future transactions. Two basic variations on this scheme are described below. The one way resource usage model and the two way resource usage model. The one way resource usage is typically more appropriate for interfaces that only requires action primitives. The two way resource usage is typically more appropriate for interfaces that require action and event primitives.
In the one way model, a resource typically has:
FILE fopen(char *filename, char *permissions);in stdio module is an example of the one way model for resource usage. fileName is the address of the resource and FILE is the provider's reference.
In the two way model, a resource typically has:
Let's consider the case of a Connection End Point.
CepProvRef conReq(CepUserRef cepUserRef, DstAddr dstAddr, ...); Void (*conCnf)(CepUserRef cepUserRef, ...); Void dataReq(CepProvRef cepProvRef, ...);
conReq and dataReq are action primitives, conCnf is an event primitive. Prior to the creation of a CEP, the service user prepares its private model of the CEP. During the creation of the CEP (conReq), a reference to this (cepUserRef) is conveyed to the service provider module. The service provider module (conReq) in turn returns a provider reference. All future action primitives dealing with the CEP will use the provider reference. All future event primitives dealing with the CEP will use the user reference.
The layered architecture plus the consistent layer interface provides for ease of integration. Several communication layer implementations can be integrated into a multi-layered communication software entity.
The Global module responsible for integration of the communication layers is expected to be called the "G_" module. A number of features are expected of the G_ module. These features are described in the next section.
The following basic structure is typical of the program that integrates one or more layers into a communication system.
- Set the run time configuration parameters.
- Initialize the run time environment and
the communication layers.
- Wait for any significant event expected by any modules.
- Schedule the execution of the awakened module.
By convention the G_ module is responsible for integration of all other modules in the executable entity. By convention "g.h" is designated to contain global configuration and integration information to be shared among independent modules. G_Env may be shared among all modules to convey global environment information.
The specific nature of G_ module and "g.h" is specific to each target environment. The following figure illustrates the usage of g.h for configuration and integration purposes.
Click here to see the complete codes. Potential usages of the G_ module are demonstrated in other examples in this book.
The OSI Basic Reference Model introduces the concept of management within OSI, and identifies a category of management activity described as Systems Management. It is recognized that OSI Management Framework is young. Details of Management Information Services are presently not fully understood. However, it is within the scope of this book to address the issue of management.
The Network Management implementation architecture outlined here is based on []. The concepts described in [] trickle down to the lower layers. Layer management facilities, should therefore be designed to support these concepts. This sections deals with Common Management Information Services as they apply to the lower layers.
Following figure illustrates OCE's view of Network Management Architecture.
Each layer has a Layer Management Entity (LME) which provides an interface for manipulating and monitoring that layer's performance. Each System has an entity that can access individual LME and perform Network Management Functions. This entity will be called "Layer Management Entity Interface" Common Management Information Services Element (CMISE) is responsible for monitoring the system on behalf of a Network Management Administrator (NMA).
The Common Management Information Protocol (CMIP) provides request/response service between a CMISE in one real open system and a CMISE in a second real open system which may be carrying out management activities in that real open system on behalf of the CMISE in the first open system. The CMIP also provides an event reporting service between an event reporting CMISE and an event monitoring CMISE.
\#include "mm.h"
void
MM_init(char * pApplicationEntityInstanceName);
ReturnCode
MM_registerModule(char * pModuleName,
void ** phModule);
ReturnCode
MM_registerManagableEntity(void * hModule,
MM_ManagableEntityType managableEntityType,
char * pManagableEntityName,
char * pIdentificationMessage,
OS_Uint16 initialNotifyMask,
void ** phManagableEntity);
ReturnCode
MM_setThreshold(void * hManagableEntity,
MM_ThresholdType thresholdType,
OS_Sint32 value);
ReturnCode
MM_incrementValue(void * hManagableEntity,
OS_Sint32 incrementBy);
ReturnCode
MM_startTimer(void * hManagableEntity,
OS_Uint32 milliseconds);
ReturnCode
MM_stopTimer(void * hManagableEntity);
ReturnCode
MM_logMessage(void * hManagableEntity,
char * pFormat,
...);
ReturnCode
MM_registerDestination(ReturnCode (* pfAlert)(char * pApplicationEntityInstanceName,
char * pModuleName,
char * pIdentificationMessage,
MM_EventType eventType,
...),
OS_Uint16 initialNotifyMask,
void ** phDestination);
ReturnCode
MM_modifyDestination(void * hDestination,
OS_Uint16 newNotifyMask);
ReturnCode
MM_processEvents(OS_Boolean * pbFoundOne);
ReturnCode
MM_getValueByHandle(void * hManagableEntity,
void * pValue);
ReturnCode
MM_getValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
ReturnCode
MM_setValueByHandle(void * hManagableEntity,
void * pValue);
ReturnCode
MM_setValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Note that there are no "modify", "delete", or "create" operations. Creation must occur at the Module Management Entity level. Deletion can be accomplished by setting the Notification Mask to zero. Modify is accomplished via the "set" operation.
The Module Management Module uses the following data types:
typedef enum MM_ManagableEntityType
{
MM_ManagableEntityType_CounterSigned, /* Value Type: OS_Sint32 */
MM_ManagableEntityType_CounterUnsigned, /* Value Type: OS_Uint32 */
MM_ManagableEntityType_GuageSigned, /* Value Type: OS_Sint32 */
MM_ManagableEntityType_GuageUnsigned, /* Value Type: OS_Uint32 */
MM_ManagableEntityType_String, /* Value Type: STR_String */
MM_ManagableEntityType_Timer, /* No maintained value */
MM_ManagableEntityType_Log /* No maintained value */
} MM_ManagableEntityType;
These are the currently supported types of entities which we can manage.
typedef enum MM_NotificationType
{
/* Counter events */
MM_NotificationType_HighPriCounter = (1 << 13)
MM_NotificationType_MidPriCounter = (1 << 7)
MM_NotificationType_LowPriCounter = (1 << 1)
/* Event requires immediate notification */
MM_NotificationType_Urgent = (1 << 15)
/* Event is only informational and may not require any action */
MM_NotificationType_Info = (1 << 0)
/* Generic values for all possible bits */
MM_NotificationType_15 = (1 << 15) /* also Urgent */
MM_NotificationType_14 = (1 << 14)
MM_NotificationType_13 = (1 << 13) /* also HighPriCounter */
MM_NotificationType_12 = (1 << 12)
MM_NotificationType_11 = (1 << 11)
MM_NotificationType_10 = (1 << 10)
MM_NotificationType_9 = (1 << 9)
MM_NotificationType_8 = (1 << 8)
MM_NotificationType_7 = (1 << 7) /* also MidPriCounter */
MM_NotificationType_6 = (1 << 6)
MM_NotificationType_5 = (1 << 5)
MM_NotificationType_4 = (1 << 4)
MM_NotificationType_3 = (1 << 3)
MM_NotificationType_2 = (1 << 2)
MM_NotificationType_1 = (1 << 1) /* also LowPriCounter */
MM_NotificationType_0 = (1 << 0) /* also Info */
} MM_NotificationType;
Each managable entity may be assigned one or more notification types which are to be generated when an event on that managable entity is raised. The module itself may specify an initial set of notification types for the managable entity, but the manager entity may modify that set.
A general rule to follow in deciding what notification type to use, is that the higher-order bits should indicate more urgent events while lower-order bits should indicate less urgent events.
NOTE: The maximum number of bits allowed here is 16, as enum types are 16-bits when using some compilers.
typedef enum MM_EventType
{
MM_EventType_MaxThresholdExceededSigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Sint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Sint32"
*
*/
MM_EventType_MaxThresholdExceededUnsigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Uint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Uint32"
*
*/
MM_EventType_MinThresholdExceededSigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Sint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Sint32"
*
*/
MM_EventType_MinThresholdExceededUnsigned,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* Two optional parameters are passed:
*
* - the threshold value, as an "OS_Uint32"
* - the value which caused the event by exceeding the
* threshold, as an "OS_Uint32"
*
*/
MM_EventType_TimerExpired,
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* No optional parameters are passed.
*/
MM_EventType_LogMessage
/*
* Parameters passed to the Alert function when an event of this
* type is raised:
*
* One optional parameter is passed:
*
* - the log message string, as a "char *"
*/
} MM_EventType;
This is the current set of events which may be generated by a module's management entity.
IMPORTANT NOTE:
If additional event types are added, be sure to add comments specifying what optional parameters are passed to the Alert function (see MM_registerDestination()) when an event of this type is raised.
This function is to be called by all applications making use of any of the Module Management facilities.
void MM_init(char * pApplicationEntityInstanceName);
Initialize the Module Management Entity module.
Parameters:
pApplicationEntityInstanceName --
The name of the application entity instance in which the module
is located. Note that if the same application is running in
more then one instance, the instance name must be unique in
each one.
These functions are to be called by each module which wishes to use module management facilities.
ReturnCode
MM_registerModule(char * pModuleName,
void ** phModule);
Allocate management resources for a code module or protocol layer.
Parameters:
pModuleName --
The name of the module for which managable entities are to be
registered.
phModule --
Pointer to a handle. The handle is generated by this function.
Future requests to register a managable entity will use this
handle.
ReturnCode
MM_registerManagableEntity(void * hModule,
MM_ManagableEntityType managableEntityType,
char * pManagableEntityName,
char * pIdentificationMessage,
OS_Uint16 initialNotifyMask,
void ** phManagableEntity);
Register a managable entity for use by the specified module.
Parameters:
hModule --
A module handle previously returned by MM_registerModule().
managableEntityType --
The type of managable entity being registered.
pManagableEntityName --
The name of the managable entity being registered. This name must be
unique within the scope of this module.
pIdentificationMessage --
An identification string which will be passed to the module management
agent when an event is raised.
initialNotifyMask --
Bits identifying the urgency of an event rasied for this managable
entity. Multiple bits may be specified, but this use is discouraged.
phManagableEntity --
Pointer to a handle. The handle is generated by this function. Future
requests to set thresholds, modify values, etc. will require use of
this handle.
subsubsectionSet Threshold
ReturnCode
MM_setThreshold(void * hManagableEntity,
MM_ThresholdType thresholdType,
OS_Sint32 value);
Set the maximum or minimum threshold value for a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
thresholdType --
Indication of whether the threshold to be set is a Maximum threshold or
a Minimum threshold.
value --
Value to which the threshold should be set.
Note:
Thresholds are only applicable to certain managable entity types, such as
Counters and Guages.
ReturnCode
MM_incrementValue(void * hManagableEntity,
OS_Sint32 incrementBy);
Increment the numeric value of the specified managable entity (probably either a counter or a guage) by the specified value.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
incrementBy --
Amount by which the managable entity's value should be incremented.
The increment value may be negative to decrement the value.
ReturnCode
MM_startTimer(void * hManagableEntity,
OS_Uint32 milliseconds);
Start a timer. When it expires, an event will be raised.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
milliseconds --
Number of milliseconds before the timer should expire.
ReturnCode MM_stopTimer(void * hManagableEntity);
Stop a previously started timer.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
ReturnCode
MM_logMessage(void * hManagableEntity,
char * pFormat,
...);
Generate a message for logging, using a printf-style format.
Parameters:
hManagableEntity --
Handle to a managable entity, previously returned by
MM_registerManagableEntity().
pFormat --
Printf-style format string specifying the format for the remainder of
the parameters.
... --
Additional parameters, as specified by pFormat.
Each MMA talks to multiple Module Management Entities (MME's).
ReturnCode
MM_registerDestination(ReturnCode (* pfAlert)(char * pApplicationEntityInstanceName,
char * pModuleName,
char * pIdentificationMessage,
MM_EventType eventType,
...),
OS_Uint16 initialNotifyMask,
void ** phDestination);
Register a new destination to which events may be sent. A destination is a place where an event is sent. All Module Management Agents should register at least one destination - the Module Management Manager. Additional destinations may be registered, such as to a log file, to send email, etc.
Parameters:
pfAlert --
Pointer to a function which will be called when events are
destined to this registered destination.
If "pfAlert" is NULL, a default function is used, which sends events
for this destination to a non-standard-based Module Management Manager,
using a non-standard-based data format.
When the function pointed to by this parameter is ultimately
called, it will be passed a set of zero or more optional
parameters which are specific to the type of event which has
been raised. See the comments associated with the definition
of MM_EventType.
initialNotifyMask --
Bits specifying that events of notification types include in this mask
are to be sent to this destination (in addition, possibly, to other
destinations).
phDestination
Pointer to a handle. The handle is generated by this function. Future
requests to modify the notification mask for this destination will
require use of this handle.
ReturnCode
MM_modifyDestination(void * hDestination,
OS_Uint16 newNotifyMask);
Modify the set of notification types which should be sent to this destination.
Parameters:
hDestination --
Handle, previously provided by MM_registerDestination().
newNotifyMask --
New bit mask indicating which notification levels are to be sent to
this destination.
ReturnCode MM_processEvents(OS_Boolean * pbFoundOne);
Event notification does not happen asynchronously. The reason for this is that the event could be raised during interrupt routines, critical sections, etc. We therefore enqueue the event notification for action when this function is called.
This function should be called on a regular basis, either in a main loop, or via a timer expiration.
Parameters:
pbFoundOne --
Pointer to a boolean variable, which is set to TRUE by this function if
an event was found to process. This variable is _not_ modified if no
event was found to process, enabling a pointer to the same variable to
be passed to multiple functions to see if any of them had anything to
do.
This pointer may be NULL if an indication of whether an event was
processed is not required.
ReturnCode
MM_getValueByHandle(void * hManagableEntity,
void * pValue);
Get the current value of a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously provided by
MM_registerManagableEntity().
pValue --
Pointer to the location where the current value of the specified
managable entity is to be placed. It is up to the caller to provide a
pointer to the correct type of variable into which the value will be
placed.
ReturnCode
MM_getValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Get the current value of a managable entity.
Parameters:
pModuleName --
Name of the module in which the manangable entity resides.
pManagableEntityName --
Name of the managable entity for which the value is desired.
pValue --
Pointer to the location where the current value of the specified
managable entity is to be placed. It is up to the caller to provide a
pointer to the correct type of variable into which the value will be
placed.
ReturnCode
MM_setValueByHandle(void * hManagableEntity,
void * pValue);
Set the current value of a managable entity.
Parameters:
hManagableEntity --
Handle to a managable entity, previously provided by
MM_registerManagableEntity(), for which the value is to be
modified.
pValue --
Pointer to the new value for this managable entity. It is up
to the caller to provide a pointer to the correct type of
variable into which the value will be placed.
ReturnCode
MM_setValueByName(char * pModuleName,
char * pManagableEntityName,
void * pValue);
Get the current value of a managable entity.
Parameters:
pModuleName --
Name of the module in which the manangable entity resides.
pManagableEntityName --
Name of the managable entity for which the value is to be
modified.
pValue --
Pointer to the new value for this managable entity. It is up
to the caller to provide a pointer to the correct type of
variable into which the value will be placed.
Each LME should define the complete set of management information types and facilities that it supports. Mechanism for access to LME of each layer is same as the layer's other interfaces - Direct non-blocking function calls with a well defined set of arguments.
Open C Platform is a set of well defined interfaces and service definitions for basic facilities needed for implementation of lower layer OSI protocols in C.
Platform facilities are grouped into sets of related facilities. Module naming conventions, mentioned earlier is used to highlight this grouping. A list of these common facilities is provided in the following table:
Module Facility Environment Name Description Dependencies SF_ System Facilities Yes SCH_ Scheduling Yes BO_ Byte Ordering Yes BS_ Byte String Manipulation Can be QU_ Linked List Management No SEQ_ QU_ extensions SF_ EH_ Exception Handling Yes TM_ Tracing Yes DU_ Data Unit manipulation SF_ TMR_ Timer Management Yes SAP_ SAP Address Management No RELID_ Release Identifier LIC_ License Checking
EH_ and TM_ provide exception handling, event logging and tracing facilities. This type of basic facilities are required by any type of serious software development.
SF_ (System Facilities) module defines an interface for a number of inherently non portable facilities. Implementation of many of the facilities defined here can be made portable by relying on SF_ facilities.
SCH_ (Scheduling) module provides for efficient usage of the CPU in multi-processing environments.
BO_ provides for simple CPU independent value representation. BS_ defines an interface for manipulation of blocks of data.
#include "sf.h"
Ptr SF_memObtain(Uns nuOfBytes);
SuccFail SF_memRelease(Ptr data);
SF_Status SF_critBegin();
Void SF_critEnd(SF_Status status);
Int SF_quInsert(QU_Head *head, QU_Elem *elem);
Int SF_quRemove(QU_Head *head, Ptr *elem);
A set of inherently environment dependent services are expected of
the operating environment.
Environment independent services and interfaces defined in
Open C Platform can be implemented
by relying on the primitive environment specific facilities
available in each environment.
Ability to Obtain memory from the environment, a periodic interrupt and protection against preemption are among the few environment specific facilities that are assumed by Open C Platform. Other environment specific facilities such as atomic queue operations, and timer facilities may be available in some environments. When available these facilities may be used for efficient implementation of Open C Platform. Facilities described in this section are considered to be low level. Their direct usage by the application is not recommended.
During the initialization each module may reserve some memory for its usage and upon a soft reset each module may return the memory back to the environment. The lower layers should not assume the existence of a dynamic memory allocation facility such as malloc. All the memory that required by a module is expected be reserved upon initialization.
Ptr SF_memObtain(Uns nuOfBytes);
SuccFail SF_memRelease(Ptr data);
Provide a model for such environment specific facilities.
Asynchronous intercations with synchronous processing can result into inconsistencies. To prevent this the availability of a simple preemption protection mechanism is assumed. When the synchronous software is accessing a critical resource, it protects itself against preemption and once the critical section is completed preemption status is restored.
SF_Status SF_critBegin();
Void SF_critEnd(SF_Status status);
Provide a model for this service.
Enabling and disabling interrupts is an extreme way of implementing
this facilities in un-hosted environments.
Most modern CPUs include support for atomic queue (circular doubly linked list) operations. When available this facility may be exploited for coordination of synchronous and asynchronous interactions.
Int SF_quInsert(QU_Head *head, QU_Elem *elem);
Int SF_quRemove(QU_Head *head, QU_Elem **elem);
Provide a model for this service. The QU_ module describes the characteristics of circular doubly linked lists. QU_ facilities are not protected against asynchronous preemption and should not be used when asynchronous preemption can result into inconsistencies. SF_quInsert and SF_quRemove are expected to be atomic (non-preemptable during the entire operation).
SF_quInsert inserts elem at the tail of head. elem need not be initialized. If head was empty, -1 is returned. Otherwise 0 is returned.
SF_quRemove removes the first element of the queue from the head if there is one. If head was not empty *elem is a pointer to the removed element. The removed element will not be initialized at the completion of SF_quRemove. If head was empty, SF_quRemove returns -1 and *elem is untouched. Otherwise 0 is returned.
An example implementation of SCH_ module based on SF_qu facilities is illustrated in the following code fragment.
Click here to see the complete codes. In this example it is assumed that environment specific facilities for scheduling are provided through syshiber and syswake.
In multi-processing hosted environments, it is desirable to share the CPU with other processes. In these environments the availability of facilities for blocking and waking up are assumed. When available these facilities may be used in the implementation of SCH_ facilities.
SCH_ section defines the scheduling facility to be used by Open C Platform users.
Environment specific timer facilities are expected to be enhanced to conform to TMR_ facilities described later in this chapter. In un-hosted environments the only expected timer facility from the environment is a periodic interrupt.
#include "sch.h"
Void SCH_init(Int nuOfSchQuItems);
Void SCH_reset();
Void SCH_submit(func, arg)
Int (*func)();
Ptr arg;
Void SCH_block();
Void SCH_run();
In environments where multi processing is supported, it may be desirable to time share the CPU with other processes. In this scenario when the communication software has no more work to do it can block and deliver CPU to other processes.
SCH_ module can be used for rescheduling of known modules. One of the common usages of SCH_ module rescheduling of further processing with in the same module. This happens most often to prevent re-entry to non-re-entrant code.
Take the case of an (N-1) Action Primitive resulting into an (N-1) Event Primitive. If (N) layer code is non-re-entrant, this should not happen. The expected behavior of (N-1) module is:
The following example illustrates an example of such a sequence.
Click here to see the complete codes.
#include "bo.h"
Void BO_put1(netPtr, cpuValue)
Octet *netPtr; /* OUT */
Byte cpuValue;
Void BO_get1(cpuValue, netPtr) /* MACRO */
Octet *netPtr;
Byte cpuValue; /* OUT, VALUE EFFECTED */
BO_put2(netPtr, cpuValue)
Octet *netPtr; /* OUT */
MdUns cpuValue;
BO_get2(cpuValue, netPtr) /* MACRO */
Octet *netPtr;
MdUns cpuValue; /* OUT, VALUE EFFECTED */
BO_put4(netPtr, cpuValue)
Octet *netPtr; /* OUT */
LgUns cpuValue;
BO_get4(cpuValue, netPtr) /* MACRO */
Octet *netPtr;
LgUns cpuValue; /* OUT, VALUE EFFECTED */
BO_putN(netPtr, cpuPtr, n)
Octet *netPtr; /* OUT */
Byte *cpuPtr;
Int n;
BO_getN(cpuValue, netPtr, n)
Octet *netPtr;
Byte *cpuPtr; /* OUT */
Int n;
BO_ facilities provide primitive abstract data presentation facilities for simple types of values.
BO_ facilities convert CPU presentation of values to a machine independent byte ordering and vice versa. 8 bit values, 16 bit values, 32 bit values, and octet string types are converted to an abstract presentation commonly used by the lower layer protocols. This abstract presentation is expressed through a sequence of octets. Octets at the lower address always contain the most significant byte of the value. Least Significant Byte of the value is always at the higher address.
netPtr points to where the machine independent presentation value should be stored. Upon completion of all BO_ facilities netPtr is incremented by the appropriate value so that it can be used in subsequent BO_ operations. cpuValue is the machine dependent presentation of a value.
Get and Put verbs in BO_get/BO_put are with respect to the abstract presentation (the network). BO_get always converts the abstract presentation of contents of netPtr into a machine dependent value (cpuValue). Note that since cpuValue is an out put value and is not passed as a pointer BO_get facility must be implemented as a MACRO. BO_put always converts the machine dependent presentation of a value into an abstract presentation. netPtr is always incremented.
#include "bs.h"
BS_memCopy(src, dst, nuOfBytes)
Byte *src;
Byte *dst;
Int nuOfBytes;
BS_memCmp(src, dst, nuOfBytes)
Byte *src;
Byte *dst;
Int nuOfBytes;
BS_memFill(dst, value, nuOfBytes)
Byte *dst;
Byte value;
Int nuOfBytes;
A Byte String (BS_) is a consecutive memory address range.
A byte string is specified by its starting address and its length.
BS_ module operates on byte strings.
BS_memCopy copies nuOfBytes from string src to dst. src and dst are assumed to be non over lapping.
BS_memCmp compares byte string src against dst .
Byte string operations are often one of the most execution intensive parts of a protocol implementation. Environment specific facilities provided in the target environment can sometimes be used to implement these facilities more efficiently that they can be done as portable code.
#include "queue.h"
typedef struct QU_Elem {
Ptr next;
Ptr prev;
} QU_Elem;
typedef struct QU_Head {
Ptr first;
Ptr last;
} QU_Head;
QU_init(QU_Elem *q);
QU_insert(QU_Elem *q1, QU_Elem *q2);
QU_remove(QU_Elem *q);
QU_move(QU_Elem *q1, QU_Elem *q2);
QU_HEAD
QU_ELEMENT
QU_INIT(p)
QU_INSERT(pInsertThisElement, pInFrontOfThisElement)
QU_PREPEND(pInsertThisElement, pAtBeginOfThisQueue)
QU_APPEND(pInsertThisElement, pAtEndOfThisQueue)
QU_REMOVE(p)
QU_MOVE(pMoveMe, pBeforeThisElement)
QU_FIRST(p)
QU_LAST(p)
QU_NEXT(p)
QU_PREV(p)
QU_EQUAL(p1, p2)
QU_ facilities provide a uniform mechanism for manipulation of doubly linked circular lists. A queue is a circular doubly linked list. Queues are often used for implementation of sequences and sets. A queue entry is linked to the next by a pair of pointers. The first pointer (next) is the forward link. It specifies the location of the succeeding entry. The second pointer (prev) is the backward link, it specifies the location of the preceding entry.
A queue is specified by a queue header (QU_Head). Structure of queue header is same as queue element (two pointers). The forward link of the header (first) is called head of the queue. The backward link of the header (last) is called the tail of the queue.
Make no assumptions about the structure of this type. It may change in the future. All manipulation of queue elements must be accomplished solely by the functions in this queue module.
(As an example, if this code is ever moved into a multi-threading environment, some elements may be added to the header, for mutual exclusion while manipulating the queue pointers.)
Do not declare queue pointers in your own structures. Instead, declare the first element of your structures as either QU_ELEMENT or QU_HEAD. No variable name is necessary.
Two basic operations can be performed on queues: insertion of entries and removal of entries.
QU_ facilities are not protected against asynchronous preemption and should not be used when asynchronous preemption can result into inconsistencies. SF_quInsert and SF_quRemove are expected to be atomic (non-preemptable during the entire operation).
QU_init, QU_insert, QU_remove and QU_move all operate on an abstract data type "QU_Elem". Objects that queue management facilities manipulate are expected to be data types that allow for a QU_Elem to be casted over them.
QU_init initializes a QU_Elem so that it can be used in subsequent operations. A QU_Elem is initialized by having its "next" and "prev" field point to itself. An initialized QU_Elem is an empty circular list.
QU_insert(q1, q2) inserts linked list q1 before list q2. The result is a linked list that contains all members of q1 and q2.
It is interesting to note that the order of arguments is not important. The result of QU_insert(q1, q2) and QU_insert(q2, q1) is the same. Figure 6.3 illustrates this.
QU_move moves QU_Elem q1 to end of q2. This is equivalent to the commonly used coding sequence:
QU_remove(q1);
QU_insert(q2, q1);
QU_ also provides the following set of macros to simplify coding.
QU_HEAD QU_ELEMENT
QU_INITIALIZE(q)
QU_INIT(p) QU_INSERT(pInsertThisElement, pInFrontOfThisElement) QU_PREPEND(pInsertThisElement, pAtBeginOfThisQueue) QU_APPEND(pInsertThisElement, pAtEndOfThisQueue) QU_REMOVE(p) QU_MOVE(pMoveMe, pBeforeThisElement)
QU_FIRST(p) QU_LAST(p)
QU_NEXT(p) QU_PREV(p)
QU_EQUAL(p1, p2)
for (pElement = QU_FIRST(pHead);
! QU_EQUAL(pElement, pHead);
pElement = QU_NEXT(pElement))
{
...
}
QU_FREE(pQHead){
#include "seq.h"
SEQ_PoolDesc SEQ_poolCreate(Int sizeOfElem, Int nuOfElems);
Void SEQ_poolFree(SEQ_PoolDesc pool);
Ptr SEQ_elemObtain(SEQ_PoolDesc pool);
Void SEQ_elemRelease(SEQ_PoolDesc pool, Ptr elem);
SEQ_ module provides simple fixed size dynamic memory allocation capabilities for linked list elements. In conjunction with the QU_ module, sequences and sets implemented as linked lists can conveniently be maintained.
Memory for a number of elements within a sequence can initially be obtained through SEQ_poolCreate facility. As new elements of a set or a sequence are needed they can be obtained through SEQ_elemObtain facility. Sequence or set elements can be released back into the pool through the SEQ_elemRelease facility.
The following code fragment demonstrate the use of Queue management facilities.
Click here to see the complete codes. This example does not perform any useful task but demonstrates how the Queue manipulation facilities can be used to transfer some data through a queue. Flow of this example program is:
/* Call Graph */
enum NVQ_ReturnCode
{
NVQ_RC_CreateFailed = (1 | ModId_Nvq),
NVQ_RC_OpenFailed = (2 | ModId_Nvq),
NVQ_RC_WriteError = (3 | ModId_Nvq),
NVQ_RC_ReadError = (4 | ModId_Nvq),
NVQ_RC_Overflow = (5 | ModId_Nvq),
NVQ_RC_NonExistantElement = (6 | ModId_Nvq),
NVQ_RC_DataSizeTooLarge = (7 | ModId_Nvq),
};
typedef int NVQ_Element;
#define NVQ_NO_ELEMENTS ((NVQ_Element) -1)
ReturnCode
NVQ_create(char * pQueueName,
OS_Uint16 maxNumElements,
OS_Uint32 maxElementSize,
void ** phQueue);
Create a Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name for this queue.
maxNumElements --
Maximum number of elements that may be on this queue (ever).
maxElementSize --
Maximum number of octets of data in any one element.
phQueue --
Pointer to a location in which a handle to this queue is placed, upon
successful completion of this function.
ReturnCode
NVQ_open(char * pQueueName,
OS_Uint16 * pMaxNumElements,
OS_Uint32 * pMaxElementSize,
void ** phQueue);
Open an already-existant Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name for this queue.
pMaxNumElements --
Pointer to a location in which, upon successful completion of this
function, the maximum number of queue elements will be placed.
pMaxElementSize --
Pointer to a location in which, upon successful completion of this
function, the maximum number of octets in any element's data will be
placed.
phQueue --
Pointer to a location in which a handle to this queue is placed, upon
successful completion of this function.
void NVQ_close(void * hQueue);
Close a previously opened or created Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_create() or NVQ_open(), to the queue
to be closed.
ReturnCode NVQ_delete(charpQueueName);
Delete a Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name of the queue to be deleted.
#define NVQ_VIEW_HEAD(hQueue, ppData, pDataSize) \
nvq_viewData(hQueue, ppData, pDataSize, NVQ_Location_Head)
Retrieve a pointer to the data in the element at the head of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_VIEW_TAIL(hQueue, ppData, pDataSize) \
nvq_viewData(hQueue, ppData, pDataSize, NVQ_Location_Tail)
Retrieve a pointer to the data in the element at the tail of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_VIEW_ELEM(hQueue, ppData, pDataSize, elem) \
nvq_viewData(hQueue, ppData, pDataSize, \
NVQ_Location_Element, (NVQ_Element) (elem))
Retrieve a pointer to the data in the element at the specified location in the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
elem --
Identifier, of type NVQ_Element, specifying for which element a pointer
to the data is to be returned.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_INSERT_AT_HEAD(hQueue, pData, dataSize) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Head)
Insert an element at the head of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_AT_TAIL(hQueue, pData, dataSize) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Tail)
Insert an element at the tail of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_BEFORE(hQueue, pData, dataSize, beforeMe) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Before, \
beforeMe)
Insert an element before the specified element of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
beforeMe --
Identifier, of type NVQ_Element, of the element before which this new
element should be inserted into the queue.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_AFTER(hQueue, pData, dataSize, afterMe) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_After, \
afterMe)
Insert an element after the specified element of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
aftere --
Identifier, of type NVQ_Element, of the element after which this new
element should be inserted into the queue.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_HEAD(hQueue) \
nvq_remove(hQueue, NVQ_Location_Head)
Remove the element from the Non-Volatile Queue, which is at the queue's head.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_TAIL(hQueue) \
nvq_remove(hQueue, NVQ_Location_Tail)
Remove the element from the Non-Volatile Queue, which is at the queue's tail.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_ELEM(hQueue, elem) \
nvq_remove(hQueue, NVQ_Location_Element, (NVQ_Element) elem)
Remove a specified element from the Non-Volatile Queue
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
elem --
Identifier, of type NVQ_Element, of the element which is to be removed
from the queue.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_FIRST(hQueue) \
(nvq_getTail(hQueue) >= 0 ? 0 : NVQ_NO_ELEMENTS)
Obtain a handle to the first element of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
Returns:
A handle, of type NVQ_Element, to the first element on the queue.
#define NVQ_LAST(hQueue) \
(nvq_getTail(hQueue))
Obtain a handle to the last element of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
Returns:
A handle, of type NVQ_Element, to the last element on the queue.
#define NVQ_NEXT(hQueue, elem) \
(++elem, elem > nvq_getTail(hQueue) ? \
NVQ_NO_ELEMENTS : elem)
Obtain a handle to the next element in the queue, given the current element.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
elem --
Identifier, of type NVQ_Element, of the element to which the successor
element is desired.
Returns:
A handle, of type NVQ_Element, to the next element in the queue.
#define NVQ_PREV(hQueue, elem) \
(--elem)
Obtain a handle to the previous element in the queue, given the current element.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
elem --
Identifier, of type NVQ_Element, of the element to which the
predecessor element is desired.
Returns:
A handle, of type NVQ_Element, to the previous element in the queue.
#define NVQ_EQUAL(hQueue, elem1, elem2) \
(elem1 == elem2)
Compare two NVQ_Element handles for equivilency.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handles are being compared
elem1, elem2 --
Identifiers, of type NVQ_Element, of the elements to be compared for
equality.
Returns:
TRUE if the identifiers reference the same queue element; FALSE
otherwise.
/*
* THE REMAINDER IS NOT PART OF THE USER INTERFACE. DO NOT REFERENCE THESE
* DIRECTLY IN USER PROGRAMS. OTHER PORTATIONS OF THIS MODULE MAY NOT CONTAIN
* THEM.
*/
typedef enum NVQ_Location
{
NVQ_Location_Head,
NVQ_Location_Tail,
NVQ_Location_Element,
NVQ_Location_Before,
NVQ_Location_After
} NVQ_Location;
ReturnCode
nvq_insert(void * hQueue,
unsigned char * pUserData,
OS_Uint32 userDataSize,
NVQ_Location location,
...);
ReturnCode
nvq_viewData(void * hQueue,
unsigned char ** ppData,
OS_Uint32 * pDataSize,
NVQ_Location location,
...);
ReturnCode
nvq_remove(void * hQueue,
NVQ_Location location,
...);
NVQ_Element
nvq_getTail(void * hQueue);
#include "eh.h"
This module provides a uniform interface for handling of software exceptions.
EH_ defines the Exception Handling interface. An abstract description of the service to be performed for each of these facilities is described. The specific actions to be performed by each of these facilities may be altered by the integrator depending on the availability of the operating environment facilities.
#include "log.h" Void LOG_init(void); SuccFail LOG_config(Char *tmFileName); log_ModInfo * LOG_open(Char *moduleName); SuccFail LOG_event(Char *format, ...); Bool LOG_modEvent(log_ModInfo *modInfo, Char *format, ...);
The Log Module (LOG_) generates log messages in order to facilitate program monitoring. Within OCP, each module may have its own particular degree of LOG_ tracing enabled at run-time. Developers may also use LOG_ tracing within applications in a similar manner.
Use of the Log Module has several advantages over other traditional tracing methods such as printf() statements:
Loging may also be globally enabled or disabled at compile time without performing any changes to the source code, other than changing the value of a defined value in a single include file.
Void LOG_init() SuccFail LOG_config(char *pFileName)
Global initializatio