A Layer's Interfaces

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.

Initialization

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.
     */
}

SAP Management

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.

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.

Lower Interface

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.

Layer Management Interface

Each layer has a layer management entity (LME) responsible for administration of the layer. This subject is discussed in more detail in chapter 4.