Driver Interface

The HDLC API for Windows NT (and Windows 2000 or later) includes an inter-driver interface that gives kernel drivers access to the API services. Any type of driver can access the API: standard kernel, NDIS miniport, NDIS intermediate or other. The driver that uses the API services is called the client driver in this document.

Details for using the driver interface and building a client driver are contained in the Base API manual. This section describes only the API functions associated with the link layer extensions to the API.

The use and naming of the driver interface functions follows that of the user mode functions. Driver interface function names are prepended with 'Di'. Return codes are defined in the NTSTATUS.H file of the Windows DDK instead of the WINERROR.H file of the Windows SDK. DiMgslDlWait polls for available primitives instead of using asynchronous notification like user mode version. The DlReady callback in the client driver is called by the API when a CONFIRM or INDICATION primitive becomes available.

Opening a Port

A port is opened using DiMgslOpen as described in the Base API manual.

Link Allocation

Link instances are allocated and freed in the same way as user mode applications.

DiMgslDlAllocate
DiMgslDlFree

Port Configuration

Port configuration is handled in the same way as user mode applications.

DiMgslDlGetParams
DiMgslDlSetParams
DiMgslDlGetPhysParams
DiMgslDlSetPhysParams

Data Link REQUEST and RESPONSE Primitives

Data link request and response primitives are sent to the API by passing an MGSL_DLPRIMITIVE structure to DiMgslDlCall, which is similar to the user mode MgslDlCall API function.

/* fill out primitive structure */

rc = DiMgslDlCall(Handle, &Primitive);

switch(rc) {
    case STATUS_SUCCESS:
        /* request or response accepted */
        break;
    case STATUS_DEVICE_BUSY:
        /* request/response not accepted due to temporary condition */
        break;

    /* process other return codes */
}

Data Link CONFIRM and INDICATION Primitives

Data link confirmation and indication primitives are retrieved from the API with the DiMgslDlWait call which is similar to the MgslDlWait user mode call. Unlike the user mode call, DiMgslDlWait is a polling function that returns STATUS_SUCCESS when a primitive is available, or STATUS_RETRY when no primitives are available. When a primitive becomes available, the API driver calls the DlReady callback function in the client driver. The client driver typically calls DiMgslDlWait until all available primitives have been processed.

void CbDlReady(void *Context)
{
    CLIENT_DEVICE_EXTENSION *pDX = (CLIENT_DEVICE_EXTENSION*)Context;

    /* do client device specific synchronization (spinlock) */

    pDX->Primitive.Size = PrimitiveBufferSize;
    while(DiMgslDlWait(pDX->Handle,&pDX->Primitive)
            ==STATUS_SUCCESS)
    {
        /* process confirm or indication primitive */
        pDX->Primitive.Size = PrimitiveBufferSize;
    }

    /* release client device synchronization */
}

Closing the Port

A port is closed with the DiMgslClose function as described in the Base API manual.

Contents