PRB: NDIS Miniport Does Not Return a Valid Parameter on Win95

ID: Q164460

The information in this article applies to:

Microsoft Win32 Device Driver Kit (DDK) Windows 95

SYMPTOMS

NdisReadConfiguration does not return a valid NDIS_CONFIGURATION_PARAMETER on Windows 95 even though it works correctly with the same miniport driver on Windows NT.

CAUSE

The miniport driver is written for a PCMCIA network card.

The miniport driver requires multiple resources of the same type.

The Windows 95 setup information file does not properly specify the parameters requested by the keyword parameter used in the miniport.

RESOLUTION

During initialization an NDIS miniport driver must determine its configuration parameters and the resources reserved for it by the operating system. Windows 95 includes Plug and Play technology not available on Windows NT and an NDIS miniport driver is a binary compatible driver for both platforms. Therefore, it is necessary for developers to use platform- specific code or setup information file to obtain these resources. For situations that require platform-specific code, NdisMQueryAdapterResources is added to the Ndis wrapper. Windows 95 setup information files can specify parameter keywords to allow binary compatibility with traditional configuration functions.

Allocation of resources in Windows 95 is dynamic and can change without rebooting. This is particularly true for PCMCIA cards. On Windows NT, a setup information file specifies registry entries that are used to store the values of resources. These values can be edited by the user if necessary. On Windows 95, this is unacceptable because of the dynamic nature and user independence of resource allocation with respect to PCMCIA adapters. NdisReadConfiguration does not return valid resources for a PCMCIA card on Windows 95. Therefore, you must use NdisMQueryAdapterResources to obtain resources.

Miniport drivers that require multiple resources of the same type must also use NdisMQueryAdapterResources. For example, a PCMCIA or ISA-PNP card that requires two memory regions must use this function. The driver must rely on a device specific convention to the order of fields of the same type. A PCMCIA card that needs a memory window and an attribute window must use an order convention to its Tuple information because the configuration manger memory descriptor can not distinguish between these memory resources. To allow this, configuration manager and NDIS preserve order when constructing the resource list from the bus-specific configuration of the device.

Most miniport drivers obtain their resources and device specific configuration parameters using Ndis...Configuration functions. While the adapter types mentioned above must use NdisMQueryAdapterResources to obtain resource information, all adapters obtain device specific configuration parameter values using the binary compatible NDIS configuration functions. The setup information file can specify any number of device-specific parameters to be saved under the driver's registry key. The parameter descriptions are saved under the "Ndi\params" subkey of the device node; their current values are saved at the root of the driver key. The NDIS wrapper can read these parameters from the root of the driver key and report them back to the miniport driver. The user views and edits the parameters from the "Advanced" property sheet page for the driver provided by the network device installer.

STATUS

This behavior is by design.

MORE INFORMATION

NdisMQueryAdapterResources is documented in the Windows NT DDK. It is available on both Windows NT and Windows 95 for a binary compatible driver. On the Windows NT platform, NdisMQueryAdapterResources returns NDIS_STATUS_NOT_SUPPORTED. This means a PCMCIA adapter miniport can use this function to reliably distinguish between platforms at run time. NdisMQueryAdapterResources is declared:


   VOID
    NdisMQueryAdapterResources(
           OUT PNDIS_STATUS  Status,
           IN NDIS_HANDLE  WrapperConfigurationContext,
           OUT PNDIS_RESOURCE_LIST  ResourceList,
           IN OUT PUINT  BufferSize
           );

NdisMQueryAdapterResources either returns a list of hardware resources, or it returns NDIS_STATUS_NOT_SUPPORTED. WrapperConfigurationContext specifies the handle returned from MiniportInitialize. ResourceList is a caller allocated buffer in which this function returns a list of PCMCIA resources.

The same format is returned by NdisMPciAssignResources. BufferSize points to the size of the allocated buffer in bytes. If the allocated buffer is too small to contain the entire list, this function returns NDIS_STATUS_RESOURCES and the integer referenced by BufferSize contains the minimum size required.

The layout of the ResourceList is declared in NDIS.H in the NT DDK. Windows 95 only reports resources of types:

CmResourceTypePort,
CmResourceTypeInterrupt,
CmResourceTypeMemory,
CmResourceTypeDma

Interrupts always have a share disposition of CmResourceShareShared for Multifunction devices. Port and Memory resources always have a share disposition of CmResourceShareDeviceExclusive however there is no I/O port trapping or memory trapping in kernel mode on Windows 95 so Multifunction devices are still accommodated. Dma resources always have a share disposition of CmResourceShareDeviceExclusive.

Driver parameters can be numeric (int, long, word, dword), or text (enum, edit). For numeric types, you can specify the minimum, maximum and, optionally, the interval value. For the enum type, you must specify a list of values and descriptions. For the edit type, you can specify maximum length and case. The following examples use the fictitious driver parameters ParamKey, EnumKey, EditKey and RescKey. Entries are displayed as they would appear in a setup information file.


   HKR,Ndi\Params\ParamKey,ParamDesc,,"My Parameter Type"
   HKR,Ndi\Params\ParamKey,type,,int
   HKR,Ndi\Params\ParamKey,default,,5
   HKR,Ndi\Params\ParamKey,min,,1
   HKR,Ndi\Params\ParamKey,max,,32
   HKR,Ndi\Params\ParamKey,step,,1
   HKR,Ndi\Params\ParamKey,base,,16
   HKR,Ndi\Params\ParamKey,flag,1,30,00,00,00

   HKR,Ndi\Params\EnumKey,ParamDesc,,"My Enumerated Type"
   HKR,Ndi\Params\EnumKey,type,,enum
   HKR,Ndi\Params\EnumKey,default,,"0"
   HKR,Ndi\Params\EnumKey\Enum,"0",,"Auto"
   HKR,Ndi\Params\EnumKey\Enum,"Sexy",,"My Type"
   HKR,Ndi\Params\EnumKey,flag,1,20,00,00,00

   HKR,Ndi\Params\EditKey,ParamDesc,,"My Edit Type"
   HKR,Ndi\Params\EditKey,type,,edit
   HKR,Ndi\Params\EditKey,default,,"Simplify"
   HKR,Ndi\Params\EditKey,limittext,,42
   HKR,Ndi\Params\EditKey,uppercase,,1
   HKR,Ndi\Params\EditKey,flag,1,20,00,00,00

   HKR,Ndi\Params\RescKey,ParamDesc,,"I/O Base Address"
   HKR,Ndi\Params\RescKey,resc,1,02,00,00,00

A driver retrieves these values by using NdisReadConfiguration. The NDIS_STRING Keyword would be initialized to "EnumKey" for the enumerated type and "ParamKey" for the integer in this example. For numeric types the NDIS_PARAMETER_TYPE is NdisParameterInteger or NdisParameterHexInteger; this depends on the numeric base outlined below. Text types require NdisParameterString. Notice that these setup information file entries describe a parameter or resource to the Network device installer instead of specifying a value for these parameters. Their current values are saved at the root of the driver key node for the network component. A binary compatible driver uses NdisReadConfiguration to obtain current data values rather than using Windows 95 specific configuration manager calls to obtain them.


HKR,Ndi\Params\PreserveCase,location,,"System\CurrentControlSet\Services\Vx
D\NWREDIR"
HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase,
ParamDesc,,"Preserve Case"
HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase,
default,,"1"
HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase,
type,,enum
HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase\ 
enum,0,,"No"
HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase\ 
enum,1,,"Yes"

This special case specifies another location for the Ndi parameter "PreserveCase". Notice that only the location entry will be found as a subkey of "Ndi\params" for the driver node. All other parameter entries are found in the "Ndi\params" subkey of the registry path specified by the location entry. Therefore, the data value of such a parameter can not be obtained using NdisReadConfiguration. A binary compatible driver will not try to obtain the data value of such a parameter. Location is used to add parameters to other network components or drivers.

Now let us take a closer look at each entry.


..\ParamKey,ParamDesc,,"My ... Type"     PARAMDESC specifies the text
..\EnumKey,ParamDesc,,"My ... Type"      description that will be shown
..\RescKey,ParamDesc,,"I/O ... Address"  in the "Advanced" property page.
..\EditKey,ParamDesc,,"My ... Type"

..\ParamKey,type,,int            Parameter TYPE can be int, long,
..\EnumKey,type,,enum            word, dword, enum or edit. The
..\EditKey,type,,edit            default type is edit. Use
                                 NdisParameterInteger or
                                 NdisParameterHexInteger for int,
                                 Long, word and dword. Use
                                 NdisParameterString for the text
                                 types, edit and enum.

..\ParamKey,default,,5           DEFAULT specifies the default value
..\EnumKey,default,,"0"          The default value will not be used
..\EditKey,default,,"Simplify"   to set an optional value. The
                                 default value will appear in the
                                 dialog control however it will
                                 not be available to the driver
                                 until the user manually sets it.

..\ParamKey,optional,,1        OPTIONAL should be used only to set
                               the optional property to true, "1".
                               This allows the user specify the
                               parameter "Not Present" in the
                               property page. If a parameter is
                               required, then the default must be
                               used or a value must be supplied.

..\ParamKey,min,,1             MIN specifies a minimum value for
                               a numeric parameter. This property
                               is ignored for text types.

..\ParamKey,max,,32            MAX specifies a maximum value for
                               a numeric parameter. This property
                               is ignored for text types.

..\ParamKey,step,,1            STEP specifies an increment value
                               for numeric parameters. This
                               property is ignored for text
                               types.
                               The default step is 1. Min, max
                               and step are used to build a "spin"
                               control on the property page.

..\ParamKey,base,,16           BASE specifies the numeric base
                               of a parameter. This property
                               is ignored for text types. The
                               base can be set to 10 or 16. The
                               default base is 10. Base 16
                               numeric parameters will be
                               displayed in hexadecimal.

..\EnumKey\Enum,<value>,,<description>  <value> is saved as the data value
..\EnumKey\Enum,"0",,"Auto"             in the registry and is returned
..\EnumKey\Enum,"Sexy",,"My Type"       in the NDIS_STRING argument of
                                        NdisReadConfiguration.
                                        <description> is displayed in a
                                        dropdown listbox as the parameter
                                        value in the property page.

..\EditKey,limittext,,42        LIMITTEXT specifies the maximum
                                string length of an edit parameter
                                This property is ignored by
                                numeric types.

..\EditKey,uppercase,,1         UPPERCASE is used to specify that
                                an editable string parameter must
                                contain upper case alpha
                                characters only. A value of 0
                                allows mixed case strings. The
                                default is mixed case.

..\RescKey,resc,1,02,00,00,00   RESC is a dword stored in the
                                registry in Intel byte order. It
                                indicates the hardware resource
                                type the parameter represents.
                                Windows 95 recognizes 4 resources:
                                  00 00 00 01 - Memory address
                                  00 00 00 02 - Port I/O address
                                  00 00 00 03 - DMA channel
                                  00 00 00 04 - IRQ
                                Notice that a parameter key can be
                                a resource or specified type
                                exclusively (not both).

..\ParamKey,flag,1,30,00,00,00  FLAG is a dword stored in the
..\EnumKey,flag,1,20,00,00,00   registry in Intel byte order. The
..\EditKey,flag,1,20,00,00,00   dword specifies flags for the
                                parameter. The flags dword is
                                created by the bitwise OR of the
                                following:
                                  0x10 parameter used by NDIS2
                                  0x20 parameter used by NDIS3
                                  0x40 device uses IRQ 2
                                Both NDIS2 and NDIS3 can use a
                                parameter. Parameters used by
                                NDIS2 will be saved in
                                Protocol.Ini for NDIS2.

..\PreserveCase,location,,"System\CurrentControlSet\Services\VxD\NWREDIR"

LOCATION tells NETDI to store a parameter in some other location in the registry. Note that this will be the only registry keyword listed relative to the root of the device node. The rest of the parameter entries must be specified relative to the desired registry location. The relative path in this example would be specified in the setup information file:

HKLM,System\CurrentControlSet\Services\VxD\NWREDIR\Ndi\Params\PreserveCase


..\PreserveCase,ParamDesc,,"Preserve Case"
..\PreserveCase,default,,"1"
..\PreserveCase,type,,enum
..\PreserveCase\enum,0,,"No"
..\PreserveCase\enum,1,,"Yes"

These registry entries will be stored in the Ndi\params section under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\NWREDIR instead of HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\Net\nnnn like the rest of the parameters discussed here. Therefore the data value of this parameter can not be obtained using NdisReadConfiguration.

REFERENCES

Windows NT DDK documentation
Windows 95 DDK documentation, "Network.Doc"

Keywords : ntddkndis
Version : 4.0
Platform : WINDOWS
Issue type : kbprb