ScsiPortGetUncachedExtension function (srb.h)

The ScsiPortGetUncachedExtension routine allocates memory that can be used by both the CPU and a bus-master HBA for DMA or for shared data.

Syntax

SCSIPORT_API PVOID ScsiPortGetUncachedExtension(
  [in] PVOID                           HwDeviceExtension,
  [in] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in] ULONG                           NumberOfBytes
);

Parameters

[in] HwDeviceExtension

Pointer to the hardware device extension. This is a per-HBA storage area that the port driver allocates and initializes on behalf of the miniport driver. Miniport drivers usually store HBA-specific information in this extension, such as the state of the HBA and the HBA's mapped access ranges. This area is available to the miniport driver in the DeviceExtension->HwDeviceExtension member of the HBA's device object immediately after the miniport driver calls ScsiPortInitialize. The port driver frees this memory when it removes the device.

[in] ConfigInfo

Specifies information about the HBA's DMA capabilities. The following members must be filled in: DmaChannel or DmaPort, DmaWidth, DmaSpeed, MaximumTransferLength, ScatterGather, Master set to TRUE, NumberOfPhysicalBreaks, AdapterInterfaceType, Dma32BitAddresses, SystemIoBusNumber, AutoRequestSense, and SrbExtensionSize.

Members that are not pertinent to the HBA, such as DmaChannel for an EISA bus-master adapter, must be left as is.

[in] NumberOfBytes

Indicates the size in bytes of the uncached extension to be allocated. Drivers in Windows XP and earlier operating systems must not allocate more than 100 kilobytes of uncached extension, and if they participate in I/O operations on the hibernation file or the crash dump file, they must limit the amount of uncached extension that they allocate to under 32 kilobytes.

Return value

ScsiPortGetUncachedExtension returns a virtual address pointer to the uncached extension. If it cannot allocate the requested memory, it returns NULL.

Remarks

ScsiPortGetUncachedExtension can be called only from miniport driver's HwScsiFindAdapter routine and only for a bus-master HBA. Calls from other miniport driver routines will result in system failure or incorrect operation for the caller.

Because high-end machines have caches and large memories, any memory to be shared between an HBA and the CPU must be specially allocated. Mailboxes or I/O request queues in system memory are examples of this type of shared memory.

A miniport driver must set SrbExtensionSize. before calling ScsiPortGetUncachedExtension to change the size of its per-request storage based on NumberOfPhysicalBreaks.

The HwScsiFindAdapter routine can call ScsiPortGetUncachedExtension only once for each bus-master HBA the miniport driver supports.

To obtain the physical address for the uncached extension that the HBA can use, call ScsiPortGetPhysicalAddress.

The ScsiPort driver will free the memory allocated by ScsiPortGetUncachedExtension when the adapter device is stopped.

Requirements

See also

HwScsiFindAdapter

PORT_CONFIGURATION_INFORMATION (SCSI)

ScsiPortGetPhysicalAddress