Smart IPX Device Driver Interface to Srv.sys

This article was previously published under Q183794
This article has been archived. It is offered "as is" and will no longer be updated.
SUMMARY
This document defines the Smart IPX interface. This interface is providedby the Windows NT CIFS/SMB file server driver (Srv.sys) to facilitate theoffload of bulk transmit requests to IPX-based intelligent LAN subsystems.

WARNING: This interface exists in Windows NT version 4.0; however, theinterface is not guaranteed to exist in versions of Windows NT beyond 5.0.

The interface allows independent software vendors (ISVs) or independenthardware vendors (IHVs) to provide drivers that provides a bulk transmitcapability to Srv.sys. These ISV-provided drivers will be called SmartIOdrivers, or simply SmartIO. This Smart IPX interface is available as aWindows NT kernel-mode driver interface, and is not available to user-modeapplications.

NOTE: Although the term "Smart Card" is used in this interface, it shouldnot be confused with the normal use of "Smart Cards"; "Smart Card" in thiscontext is used to refer to IPX-based cards with the ability to deal withlarge amounts of I/O.

Traditionally, Srv.sys initiates data transmissions to requesting clientsby breaking bulk data down into network-sized packets and individuallysubmitting those packets to the lower networking layers (TDI/NDIS) fortransmission. This process can be very CPU-intense and may consume a largeportion of a server's CPU cycles. Bulk transmit requests, however, enableSrv.sys to efficiently pass large blocks of raw data to intelligent LANsubsystems for network packetization and transmission. The purpose of bulktransmit requests is to offload the CPU-intense network processing thatnormally occurs in Srv.sys, NwLinkIpx, NDIS wrapper, and NDIS drivers.

The Smart IPX Device Driver Interface (DDI) enables SmartIO drivers tointerface directly with Srv.sys. SmartIO drivers must, in turn, interfacewith intelligent LAN subsystems to submit bulk transmit operations. Thislower level interface is deemed to be ISV-specific and is not included inthe scope of this specification.

The Smart IPX interface is a call/callback between Srv.sys and a SmartIOdriver. The following calls are currently defined: Open, Read,ReadComplete, Close, and Deregister.

The call/callback addresses are initially exchanged as a result of aninternal device IOCTL sent by the SmartIO driver to Srv.sys. Direct callsare made between the two drivers after this initial IOCTL.
MORE INFORMATION
The following sections define the Smart IPX call/callback interface. It isassumed that the reader has the Windows NT Device Driver Kit (DDK) andunderstands how to write kernel-mode drivers.

Registration IOCTL

SmartIO registers and exchanges call/callback addresses with Srv.sys duringit's initialization. This registration is accomplished by sending an IOCTLto Srv.Sys of the following type:
   #define FSCTL_SRV_IPX_SMART_CARD_START \        _SRV_CONTROL_CODE (21, METHOD_NEITHER)				

Prior to sending the internal request, update the SystemBuffer field of theinternal request packet (IRP) to point to the following data structure,which is provided by the SmartIO driver.
   typedef struct {       BOOLEAN (*Open)(           IN PVOID SmbHeader           IN PFILE_OBJECT FileObject,           IN PUNICODE_STRING FileName,           IN PTDI_ADDRESS_IPX IpxAddress,           IN ULONG Flags,           OUT PVOID *SmartCardContext);       VOID (*Close)(           PVOID SmartCardContext);       BOOLEAN (*Read) (           IN PVOID SmbHeader,           IN PVOID SmartCardContext,           IN LONG Key,           IN VOID SrvContext);       VOID (*ReadComplete)(           IN PVOID SrvContext,           IN PFILE_OBJECT FileObject,           IN PMDL Mdl,           IN ULONG Length);       VOID (*DeRegister)(           VOID);   } SRV_IPX_SMART_CARD, *PSRV_IPX_SMART_CARD;				

The server fills in the ReadComplete field with its own routine address,which is used in the ReadComplete callback (see the ReadComplete sectionbelow).

Open

   BOOLEAN Open(       IN PVOID SmbHeader       IN PFILE_OBJECT FileObject,       IN PUNICODE_STRING FileName,       IN PTDI_ADDRESS_IPX IpxAddress,       IN ULONG Flags,       OUT PVOID *SmartCardContext);				

This is a call from Srv.Sys to SmartIO. It will occur for an OpenFile SMBfrom the client -- after Srv.Sys has validated the SMB and performed thefile open, but before the SMB response is sent back to the client. Itsparameters are:

SmbHeader -- Pointer to the SMB header for this request.

FileObject -- File object pointer for the file just opened on behalf of
the client.

FileName -- Name of the file just opened; this is for future use in case
we want do special processing based on the file extension.

IpxAddress -- Pointer to a structure defining the network address.

Flags -- Various file related flags; THUN_CACHE_SUPPORTED is the only
flag currently defined.

SmartCardContext -- Pointer to a location where SmartIO will place its
ID for this file. If a zero is returned, SmartIO should not be called
for reads of this file.

SmartIO returns TRUE if reads of this file can be accelerated; otherwise,it returns FALSE.

Return Values:

TRUE -- SmartIO should be called for reads of this file.

FALSE -- SmartIO should not be called for reads of this file.

Read

   BOOLEAN Read(       IN PVOID SmbHeader,       IN PVOID SmartCardContext,       IN LONG Key,       IN VOID SrvContext);				

This is a call from Srv.sys to SmartIO. It will occur for Read and ReadMultiplexed SMBs from the client, after the Server has validated the SMB.Its parameters are:

SmbHeader -- Pointer to the SMB header for this request.

SmartCardContext -- Value returned on Open.

Key -- Parameter required to read the file.

SrvContext -- Value that will be returned by SmartIO on a ReadComplete call.

SmartIO will send the read responses to the client as required and whencomplete will call the server's ReadComplete function. This routine must becalled at PASSIVE level.

If SmartIO can handle the read request, it will return TRUE; otherwise, itwill return FALSE.

Return Values:

TRUE -- SmartIO will perform the read of this file.

FALSE -- SmartIO cannot perform the read of this file.

ReadComplete

   VOID ReadComplete(       IN PVOID SrvContext,       IN PFILE_OBJECT FileObject,       IN PMDL Mdl,       IN ULONG Length);				

This is a call from SmartIO to Srv.sys. It occurs in response to a Readcall. Its parameters are:

SrvContext -- Value that was passed in on the Read call.

FileObject -- File object from Open call.

Mdl -- Mdl chain for just completed read operation.

Length -- Length of data for just-completed read operation.


Srv.sys will mark this read as complete and do any required cleanupprocessing. This routine can be called at DISPATCH level.

Return Values:

None

Close

   VOID Close(       PVOID SmartCardContext);				

This is a call from Srv.sys to SmartIO. It will occur for a CloseFile SMBfrom the client, after the server has validated the SMB. It has oneparameter:

SmartCardContext -- Value returned on Open call.

SmartIO will free any resources it allocated as a result of the Open calland will return.

Return Values:

None

Deregister

   VOID Deregister(       VOID);				


This is a call from Srv.sys to SmartIO. It will occur if Srv.sys isbeing unloaded.

Return Values:

None
Srv SmartIO IPX FSCTL_SRV_IPX_SMART_CARD_START
Properties

Article ID: 183794 - Last Review: 10/07/2013 22:45:46 - Revision: 1.1

  • Microsoft Windows NT Server 4.0 Standard Edition
  • Microsoft Windows NT Server 4.0 Enterprise Edition
  • kbnosurvey kbarchive kbinfo KB183794
Feedback