StorPortAllocateHostMemoryBuffer function (storport.h)

Article
10/21/2021

StorPortAllocateHostMemoryBuffer allocates one or more ranges of physically contiguous memory to be used as a Host Memory Buffer (HMB).

Syntax

ULONG StorPortAllocateHostMemoryBuffer(
  [in]           PVOID            HwDeviceExtension,
  [in]           SIZE_T           MinimumBytes,
  [in]           SIZE_T           PreferredBytes,
  [in]           ULONGLONG        UtilizationBytes,
  [in]           ULONG            AlignmentBytes,
  [in]           PHYSICAL_ADDRESS LowestAcceptableAddress,
  [in]           PHYSICAL_ADDRESS HighestAcceptableAddress,
  [in, optional] PHYSICAL_ADDRESS BoundaryAddressMultiple,
  [in, out]      PACCESS_RANGE    PhysicalAddressRanges,
  [in, out]      PULONG           PhysicalAddressRangeCount
);

Parameters

[in] HwDeviceExtension

A pointer to the hardware device extension for the host bus adapter (HBA).

[in] MinimumBytes

The minimum amount of memory that will be useful to the device, in bytes. A value of 0 indicates that any size of memory up to the preferred size is acceptable.

[in] PreferredBytes

The amount of memory the device prefers, in bytes. This must be a multiple of the page size.

[in] UtilizationBytes

The total number of blocks allocated on the device, in bytes.

[in] AlignmentBytes

The Host Memory Buffer alignment requirement from the device.

[in] LowestAcceptableAddress

The lowest physical address that is valid for the allocation. For example, if the device can only reference physical memory in the 8 MB to 16 MB range, this value would be set to 0x800000 (8 MB).

[in] HighestAcceptableAddress

The highest physical address that is valid for the allocation. For example, if the device can only reference physical memory below 16 MB, this value would be set to 0xFFFFFF (16 MB - 1).

[in, optional] BoundaryAddressMultiple

The physical address multiple that this allocation must not cross. This parameter is currently not used and must be set to 0.

[in, out] PhysicalAddressRanges

An array of physical address ranges that make up the Host Memory Buffer. The caller should provide a pre-allocated array. StorPortAllocateHostMemoryBuffer will fill in the array with one or more physical address ranges.

[in, out] PhysicalAddressRangeCount

The number of entries in PhysicalAddressRanges. This function will update this parameter to indicate how many physical address ranges it filled in.

Return value

StorPortAllocateHostMemoryBuffer returns one of the following status codes:

Return code	Description
STOR_STATUS_SUCCESS	The PhysicalAddressRanges array contains one or more valid physical address ranges that represent the host memory buffer.
STOR_STATUS_INVALID_PARAMETER	This could indicate a minimum value that is greater than a maximum value, a non-page-aligned size, or that PhysicalAddressRanges is empty.
STOR_STATUS_INSUFFICIENT_RESOURCES	The host memory buffer could not be allocated.

Remarks

HMB is memory that the device may use directly and exclusively. The device may use this memory however it sees fit, but it must ensure that there is no data loss or data corruption in the event of a surprise removal or unexpected power loss.

Depending on the allocation policy, this function may allocate as much as the device's preferred size, as little as the device's minimum size, or no memory at all.

This function will attempt to allocate as few physically contiguous address ranges as possible, but it may have to use multiple physical address ranges to satisfy the desired HMB size.

The caller should subsequently call StorPortFreeHostMemoryBuffer when it is done with the host memory buffer.

Requirements

Requirement	Value
Target Platform	Universal
Header	storport.h (include Storport.h)