RtndInitialize

RtndInitialize is called by the stack when an instance of a driver is being first brought online.  This is the first routine in a driver that is called by the stack.

RtndInitialize will be called once and only once per instance of the driver, but maybe called multiple times if more than one instance of the driver is needed for more than one NIC. As such, all drivers should keep a local configuration structure array to hold configuration information read in during the RtndInitialize function. The driver then simply increments a local instance count variable to index the array. RtndInitialize should store a copy of the device name and a pointer to a network device data structure in the local configuration structure array slot along with other configuration information, so that RtndConfigure can find the proper slot in the local configuration array.

Syntax

int RtndInitialize (
    int fDisplayErrorMessages,
    char *deviceName,
    PRTNINTERFACE pNetInterface
);

Parameters

fDisplayErrorMessages

Verbose flag. If non-zero then driver has the option to be verbose about errors or warnings. If 0, driver should be silent and simply return the -1 error code on catastrophic errors.

deviceName

ASCII name for this device. Can be stored in a local configuration structure to help de-reference network device pointer in RtndConfigure.

pNetInterface

Pointer to an RTNINTERFACE defined in rtnapi.h. This structure contains information used by the stack to bring up the driver. Normally the driver simply fills in the unsigned long dwMtu value with the maximum transmission unit (packet size), not including the Ethernet header (i.e. 1500 bytes for a standard Ethernet driver).

Return Value

A return value of 0 indicates Success, -1 indicates Failure.

Process Context

RtndInitialize is always called from within the process context of the RtxTcpIp Protocol Stack.

Requirements

Minimum Supported Version	RTX64 2013
Header	RtnApi.h
Library	RtTcpip.lib

Example: Basic configuration structure for a device

struct {
      // these are required by the stack interface
      void *ndp;
      char StackDeviceName[32];

      // these are device-specific, but are very 
      // common and will probably be required
      BYTE byMACAddress[6];
      ULONG Irq; // IRQ number
      HANDLE hInterrupt;
      ULONG ulIntPriority;
      ULONG ulRecvPriority;
      HANDLE hRecvEvent;
      HANDLE hXmitEvent;
      HANDLE hRecvThread;
      HANDLE hXmitThread;
      volatile BOOL fDriverIsUp;
      CriticalLock drvCritSect;

      // put your device-specific variables in here
} DRVDEV;

See the Driver Source files in the RT-TCP/IP SDK for samples of how a driver should keep track of multiple instances of its configuration information.