windows-xp/Source/XPSP1/NT/net/ndis/samples/coisdn/miniport.h

/*
�����������������������������������������������������������������������������

    (C) Copyright 1999
        All rights reserved.

�����������������������������������������������������������������������������

  Portions of this software are:

    (C) Copyright 1995 TriplePoint, Inc. -- http://www.TriplePoint.com
        License to use this software is granted under the same terms
        outlined in the Microsoft Windows Device Driver Development Kit.

    (C) Copyright 1992 Microsoft Corp. -- http://www.Microsoft.com
        License to use this software is granted under the terms outlined in
        the Microsoft Windows Device Driver Development Kit.

�����������������������������������������������������������������������������

@doc INTERNAL Miniport Miniport_h

@module Miniport.h |

    This module defines the interface to the <t MINIPORT_DRIVER_OBJECT_TYPE>.

@comm

    This module defines the software structures and values used to support
    the NDIS WAN/TAPI Minport.  It's a good place to look when your trying
    to figure out how the driver structures are related to each other.

    Include this file at the top of each module in the Miniport.

@head3 Contents |
@index class,mfunc,func,msg,mdata,struct,enum | Miniport_h

@end
�����������������������������������������������������������������������������
*/

/* @doc EXTERNAL INTERNAL
�����������������������������������������������������������������������������

@topic 1.0 Miniport Call Manager Overview |

    The NDIS wrapper provides services to both the Transport drivers, and the
    Miniport drivers.  The NDIS wrapper provides an abstraction layer between
    the two which allows them to interoperate with each other as long as they
    both adhere to the NDIS interfaces defined for Transports and Miniports.

    The NDIS wrapper also provides a set of services which isolates NDIS
    drivers from the specifics of the Operating System (Windows 98 vs
    Windows 2000), as well as the platform specifics (Processor, Bus,
    Interrupts).  The advantage of using the NDIS wrapper is that the Miniport
    can be easily ported to other Windows environments with little or no
    re-coding.

    An MCM consists of two, cooperating, drivers contained the the same binary.
    The DATA portion of the driver handles packet transmits and receives.  The
    CONNECTION portion handles call setup and tear down.

    The DATA side of the Miniport is very similar to an NDIS LAN style Miniport,
    except that some of the NDIS interfaces have been modified to support the
    WAN media type.  The primary difference from the Miniport's point of view is
    that we use a different set of NDIS requests, and more importantly the line
    can go up and down.

    The CONNECTION portion of the Miniport adds significant complexity to the
    Miniport.  The MCM Miniport must provide a pseudo Telephony Service Provider
    Interface (TSPI) which lives under NDPROXY.  The NDPROXY TSPI loads under
    TAPI as the 'real' service provider, and then routes all TAPI events to the
    MCM.

    NDPROXY can have multiple MCM's living under its TSPI interface.  And since
    Remote Access Services (RAS) usess the TAPI interface to place and accept
    all calls, any Dial Up Networking (DUN) requests associated with the MCM,
    will end up at the MCM via CONDIS requests from NDPROXY.

@topic 1.1 Reference Documents |

    The most reliable source of information is provided on the Microsoft
    Developer Network CD.  These documents will provide you with the complete
    NDIS interface requirements and architectural overviews.  In addition,
    there are many addendums and developer notes in the Microsoft Knowledge
    Base.  The most important references are:

@iex
    Product Documentation\DDKs\Windows 2000 DDK\Network Drivers\
        Design Guide\Part 2: Miniport NIC Drivers
            Chapters 1-7 discuss all the NDIS interface routines.
            Chapters 8 provide details on WAN/TAPI extensions.
            Section 8.7 discuss CoNdis extensions to support TAPI.

    Product Documentation\SDKs\Platform SDK\Networking and Directory Services\
        Telephone Application Programming Interfaces\TAPI Service Providers
        This section defines the Windows TSPI implementation.

@normal

@end
*/

/* @doc EXTERNAL INTERNAL
�����������������������������������������������������������������������������

@topic 2.0 Installing and Configuring the Sample Driver |

    The sample driver implements a fully functional ISDN style CO-NDIS WAN
    driver.  It layers in under NDPROXY which translates the RAS/WAN/TAPI
    interfaces into a more generic CO-NDIS interface.  The driver supports
    multiple adapter instances, so you can install it more than once to
    create multiple adapters.

    Each adapter can emulate multiple ISDN B channels.  By default, each
    adapter is setup with 2 channels, but you can modify the "IsdnBChannels"
    and "WanEndPoints" registry entries to creates as many as you'd like.
    Alternatively, you can just modify these values in the INF file before
    you install the adapter.  Either way works fine.

@topic 2.1 Installation |

    The driver can be installed as a non-plug-n-play device using the Windows
    device manager interface as follows:

    1) Right-click the "My Computer" icon on the desktop and select the
    Properties item from the context menu.

    2) Select the "Hardware" tab on the "System Properties" dialog.

    3) Click the "Hardware Wizard" button, then click "Next" when the welcome
    dialog appears.

    4) Click "Next" again to "Add/Troubleshoot a device".

    5) Select "Add a new device" from the list presented, then click "Next".

    6) Select "No, I want to select the hardware from a list" radio button,
    then click "Next".

    7) Select "Network adapters" from the list presented, then click "Next".

    8) Click the "Have Disk" button, then browse to the location of the driver
    and INF file, then click OK."

    9) You should now see "TriplePoint COISDN Adapter" on the screen.  Click
    "Next" and then "Next" again to install the driver.  If Windows warns you
    about an unsigned driver, just click yes to install.  If you don't have
    permission to install such drivers, you'll have to exit and logon with the
    proper permissions.  You will have to disable the driver signing check on
    your system if it doesn't allow unsigned drivers to be installed.

    10) Now click "Finish" to load the driver.

@topic 2.2 Dial-In Setup |

    You must install and enable Dial-Up networking before you can accept an
    incoming call with the driver.  This can be done using the following
    procedure:

    1) Right-click the "My Network Places" icon on the desktop and select the
    Properties item from the context menu.

    2) Double-click the "Make New Connction" icon from the list.

    3) Select the "Accept incoming connections" radio button, then click "Next".

    4) Click the check box next to the "TriplePoint COISDN Adapter"(s) to allow
    incoming calls on the adapter.  All channels on that adapter are enabled
    for incoming calls.  Once you select the adapter(s), click "Next".

    5) Select "Do not allow virtual private connections", then click "Next".

    6) Select the users you want to have dial-in access, then click "Next".

    7) Select the protocols and services you want to support, then click "Next".

    8) Now click "Finish" to enable the dial-in connections.

@topic 2.3 Dial-Out Setup |

    The sample driver implements the following simple dialing method.

    A) "0" can be used to connect to any available more on any available
    adapter.  This is generally good enough for most testing.

    B) "N" specifies that the connection should be directed to a specific
    adapter instance.  Where N must match the ObjectID assigned to a particular
    adapter when the <f MiniportInitialize> routine is called.  Numbers are
    assigned from 1-M based on the adapter initialization order.  The call is
    then directed to any available listening channel on the selected adapter.

    You must create a dial-out connection before you can place call with the
    driver.  This can be done using the following procedure:

    1) Right-click the "My Network Places" icon on the desktop and select the
    Properties item from the context menu.

    2) Double-click the "Make New Connction" icon from the list.

    3) Select the "Dial-up to private network" radio button, then click "Next".

    4) Click the check box next to one or more "TriplePoint COISDN Adapter"
    ISDN Channels to allow outgoing calls on the channel.  Make sure you leave
    enough channels available to answer the call when it comes in...  You have
    no way to know which driver BChannel is actually going to be used, but that
    doesn't generally matter anyway. Once you select the channel(s), click "Next".

    5) Walk your way through the rest of the Wizard dialogs to setup the
    connection as you like.

    6) When you're done click "Finish" to enable the dial-out connection.

    Now you can double-click the dial-out connection to see how it all works.

    I suggest you also turn some debug flags in the driver to see how the call
    setup and teardown winds its way through the driver.  This can be quite
    useful before starting to modify the driver for your hardware.

@end
*/


/* @doc EXTERNAL INTERNAL
�����������������������������������������������������������������������������

@topic 4.0 Functional Overview |

    This section describes the major functional objects defined by the driver.

    This driver is designed as a generic ISDN device driver.  It does not
    support any specific hardware, but does have the basic elements of an ISDN
    device.  The network interface is emulated by placing calls between one or
    more of the driver's BChannels.  This is accomplished using a set of
    software events that simulate typical network events (i.e MakeCall,
    AnnounceCall, Tranmit, Receive, Hangup, etc).

    By using this design approach you can compile and test the driver without
    having to purchase specific hardware.  The downside is that you cannot
    easily test the data flow because the networking infrastructure does not
    support terminating the endpoint on the local host.  However, the data flow
    is not usually very difficult to test once the call manager interfaces are
    reliable.  RAS does support connecting to the local host, but the NDIS
    protocols won't normally route traffic through the interface because they
    just loop back before it reaches the driver.  The PPP negotiation packets
    are routed through the interface, so this does give some data flow excersise,
    but nothing worth writing home about.  The NDISWAN tester has been modified
    to allow it to run over locally terminated connections, so this is the only
    real way to test the data pump.

    Because this driver does not support real hardware, all the hardware
    resource code has been ifdef'd out.  This code has been used in working
    drivers, so I'm pretty sure it will work if you add the corresponding
    compiler options.  However, it has not been verified and may require some
    modifications for your environment.

    There are several other good samples included on the DDK that can be useful
    for using other NDIS features.  This sample focuses primarily on the
    CO-NDIS call manager interfaces.

@end
*/

#ifndef _MPDMAIN_H
#define _MPDMAIN_H

#define MINIPORT_DRIVER_OBJECT_TYPE     ((ULONG)'D')+\
                                        ((ULONG)'R'<<8)+\
                                        ((ULONG)'V'<<16)+\
                                        ((ULONG)'R'<<24)

#define INTERRUPT_OBJECT_TYPE           ((ULONG)'I')+\
                                        ((ULONG)'N'<<8)+\
                                        ((ULONG)'T'<<16)+\
                                        ((ULONG)'R'<<24)

#define RECEIVE_OBJECT_TYPE             ((ULONG)'R')+\
                                        ((ULONG)'E'<<8)+\
                                        ((ULONG)'C'<<16)+\
                                        ((ULONG)'V'<<24)

#define TRANSMIT_OBJECT_TYPE            ((ULONG)'T')+\
                                        ((ULONG)'R'<<8)+\
                                        ((ULONG)'A'<<16)+\
                                        ((ULONG)'N'<<24)

#define REQUEST_OBJECT_TYPE             ((ULONG)'R')+\
                                        ((ULONG)'Q'<<8)+\
                                        ((ULONG)'S'<<16)+\
                                        ((ULONG)'T'<<24)

/*
// NDIS_MINIPORT_DRIVER and BINARY_COMPATIBLE must be defined before the
// NDIS include files.  Normally, it is defined on the command line by
// setting the C_DEFINES variable in the SOURCES build file.
*/
#include <ndis.h>
#include <ndiswan.h>
#include <ndistapi.h>
#include "vTarget.h"
#include "TpiDebug.h"

#if !defined(IRP_MN_KERNEL_CALL) && !defined(PCI_SUBCLASS_DASP_OTHER)
// This should be defined in the NTDDK 5.0 ndis.h, but it's not.
// So I copied this here from ntddk.h to use with NdisQueryBufferSafe().
typedef enum _MM_PAGE_PRIORITY {
    LowPagePriority,
    NormalPagePriority = 16,
    HighPagePriority = 32
} MM_PAGE_PRIORITY;
#endif

// Figure out which DDK we're building with.
#if defined(NDIS_LCODE)
#  if defined(NDIS_DOS)
#    define USING_WFW_DDK
#    define NDIS_MAJOR_VERSION          0x03
#    define NDIS_MINOR_VERSION          0x00
#  elif defined(OID_WAN_GET_INFO)
#    define USING_WIN98_DDK
#  elif defined(NDIS_WIN)
#    define USING_WIN95_DDK
#  else
#    error "BUILDING WITH UNKNOWN 9X DDK"
#  endif
#elif defined(NDIS_NT)
#  if defined(OID_GEN_MACHINE_NAME)
#    define USING_NT51_DDK
#  elif defined(OID_GEN_SUPPORTED_GUIDS)
#    define USING_NT50_DDK
#  elif defined(OID_GEN_MEDIA_CONNECT_STATUS)
#    define USING_NT40_DDK
#  elif defined(OID_WAN_GET_INFO)
#    define USING_NT351_DDK
#  else
#    define USING_NT31_DDK
#  endif
#else
#  error "BUILDING WITH UNKNOWN DDK"
#endif

// Figure out which DDK we should be building with.
#if defined(NDIS51) || defined(NDIS51_MINIPORT)
#  if defined(USING_NT51_DDK)
#    define NDIS_MAJOR_VERSION          0x05
#    define NDIS_MINOR_VERSION          0x01
#  else
#    error "YOU MUST BUILD WITH THE NT 5.1 DDK"
#  endif
#elif defined(NDIS50) || defined(NDIS50_MINIPORT)
#  if defined(USING_NT50_DDK) || defined(USING_NT51_DDK)
#    define NDIS_MAJOR_VERSION          0x05
#    define NDIS_MINOR_VERSION          0x00
#  else
#    error "YOU MUST BUILD WITH THE NT 5.0 DDK"
#  endif
#elif defined(NDIS40) || defined(NDIS40_MINIPORT)
#  if defined(USING_NT40_DDK) || defined(USING_NT50_DDK) || defined(USING_NT51_DDK)
#    define NDIS_MAJOR_VERSION          0x04
#    define NDIS_MINOR_VERSION          0x00
#  else
#    error "YOU MUST BUILD WITH THE NT 4.0 or 5.0 DDK"
#  endif
#elif defined(NDIS_MINIPORT_DRIVER)
#  if defined(USING_NT351_DDK) || defined(USING_NT40_DDK) || defined(USING_NT50_DDK) || defined(USING_NT51_DDK)
#    define NDIS_MAJOR_VERSION          0x03
#    define NDIS_MINOR_VERSION          0x00
#  else
#    error "YOU MUST BUILD WITH THE NT 3.51, 4.0, or 5.0 DDK"
#  endif
#elif !defined(NDIS_MAJOR_VERSION) || !defined(NDIS_MINOR_VERSION)
//   Must be FULL MAC
#    define NDIS_MAJOR_VERSION          0x03
#    define NDIS_MINOR_VERSION          0x00
#endif

// Gotta nest NDIS_STRING_CONST or compiler/preprocessor won't be able to
// handle L##DEFINED_STRING.
#define INIT_STRING_CONST(name)     NDIS_STRING_CONST(name)
#define DECLARE_WIDE_STRING(name)   L##name
#define INIT_WIDE_STRING(name)      DECLARE_WIDE_STRING(name)

typedef struct MINIPORT_ADAPTER_OBJECT  *PMINIPORT_ADAPTER_OBJECT;
typedef struct BCHANNEL_OBJECT          *PBCHANNEL_OBJECT;
typedef struct DCHANNEL_OBJECT          *PDCHANNEL_OBJECT;
typedef struct CARD_OBJECT              *PCARD_OBJECT;
typedef struct PORT_OBJECT              *PPORT_OBJECT;

/*
// The <t NDIS_MAC_LINE_UP> structure is confusing, so I redefine the
// field name to be what makes sense.
*/
#define MiniportLinkContext                 NdisLinkHandle

#if defined(_VXD_) && !defined(NDIS_LCODE)
#  define NDIS_LCODE code_seg("_LTEXT", "LCODE")
#  define NDIS_LDATA data_seg("_LDATA", "LCODE")
#endif

/*
// The link speeds we support.
*/
#define _64KBPS                     64000
#define _56KBPS                     56000

#define MICROSECONDS                (1)
#define MILLISECONDS                (1000*MICROSECONDS)
#define SECONDS                     (1000*MILLISECONDS)

#define TSPI_ADDRESS_ID             0

/*
// Include everything here so the driver modules can just include this
// file and get all they need.
*/
#include "Keywords.h"
#include "Card.h"
#include "Adapter.h"
#include "BChannel.h"
#include "CallMgr.h"
#include "DChannel.h"
#include "Port.h"
#include "TpiParam.h"
#include "TpiMem.h"

/***************************************************************************
// These routines are defined in Miniport.c
*/

NTSTATUS DriverEntry(
    IN PDRIVER_OBJECT           DriverObject,
    IN PUNICODE_STRING          RegistryPath
    );

NDIS_STATUS MiniportInitialize(
    OUT PNDIS_STATUS            OpenErrorStatus,
    OUT PUINT                   SelectedMediumIndex,
    IN PNDIS_MEDIUM             MediumArray,
    IN UINT                     MediumArraySize,
    IN NDIS_HANDLE              MiniportAdapterHandle,
    IN NDIS_HANDLE              WrapperConfigurationContext
    );

void MiniportHalt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportShutdown(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

NDIS_STATUS MiniportReset(
    OUT PBOOLEAN                AddressingReset,
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

/***************************************************************************
// These routines are defined in interrup.c
*/
BOOLEAN MiniportCheckForHang(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportDisableInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportEnableInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportHandleInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportISR(
    OUT PBOOLEAN                InterruptRecognized,
    OUT PBOOLEAN                QueueMiniportHandleInterrupt,
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void MiniportTimer(
    IN PVOID                    SystemSpecific1,
    IN PMINIPORT_ADAPTER_OBJECT pAdapter,
    IN PVOID                    SystemSpecific2,
    IN PVOID                    SystemSpecific3
    );

/***************************************************************************
// These routines are defined in receive.c
*/
void ReceivePacketHandler(
    IN PBCHANNEL_OBJECT         pBChannel,
    IN PNDIS_BUFFER             pNdisBuffer,
    IN ULONG                    BytesReceived
    );

VOID MiniportReturnPacket(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter,
    IN PNDIS_PACKET             pNdisPacket
    );

/***************************************************************************
// These routines are defined in request.c
*/
NDIS_STATUS MiniportCoRequest(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter,
    IN PBCHANNEL_OBJECT         pBChannel,
    IN OUT PNDIS_REQUEST        NdisRequest
    );

/***************************************************************************
// These routines are defined in transmit.c
*/
VOID MiniportCoSendPackets(
    IN PBCHANNEL_OBJECT         pBChannel,
    IN PPNDIS_PACKET            PacketArray,
    IN UINT                     NumberOfPackets
    );

void TransmitCompleteHandler(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter
    );

void FlushSendPackets(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter,
    IN PBCHANNEL_OBJECT         pBChannel
    );

#endif // _MPDMAIN_H