升级为 NVMe 设备的固件
NVMe 存储设备上的固件汇报将颁发给该设备的微型端口驱动程序。 向微型端口发出用于获取固件信息、下载和激活固件映像的函数命令。
固件升级过程
经 Windows 认证的 NVMe 设备能够在设备运行时更新其固件。 固件是使用 IOCTL_SCSI_MINIPORT 请求更新的，其中包含在 SRB 中设置格式的关联固件控制数据。 更新过程涉及：
收集固件槽信息以确定将更新放置到何处。 在确定固件更新的驻留位置时，有一些注意事项。
- 有多少个槽可用？
- 可以容纳更新的槽数是多少？ 某些槽是只读的或保留的映像，如果需要能够还原以前的映像，则必须保留这些映像。
- 哪个槽包含正在运行的固件) (当前活动固件映像？
为了更新设备，选择一个可写且当前不处于活动状态的槽。 更新完成后，将覆盖所选槽中的所有现有图像数据。
下载所选槽的新固件映像。 根据图像的大小，这发生在单个传输操作中或图像的多个部分的连续传输中。 映像的一部分受 最小 (控制器最大传输大小限制，) 为 512 KB。
为了使下载的映像成为活动固件映像，需要将其分配给槽。 然后，活动固件槽从当前使用的槽切换到分配给已下载映像的槽。 根据下载类型和固件映像中的更改，可能需要重新启动系统。 这由 NVMe 控制器确定。
微型端口固件控制请求
每个函数命令都是在FIRMWARE_REQUEST_BLOCK结构中设置的，该结构包含在IOCTL_SCSI_MINIPORT请求的缓冲区中的SRB_IO_CONTROL中。 SRB_IO_CONTROL 的 ControlCode 成员设置为 IOCTL_SCSI_MINIPORT_FIRMWARE 以指示微型端口固件操作。 每个函数命令都有一个位于 FIRMWARE_REQUEST_BLOCK后面的相关信息结构。 下表列出了IOCTL_SCSI_MINIPORT的系统缓冲区中包含的每个函数命令和结构。
| 函数 | 输入数据 | 输出数据 |
|---|---|---|
| FIRMWARE_FUNCTION_GET_INFO | SRB_IO_CONTROL + FIRMWARE_REQUEST_BLOCK | SRB_IO_CONTROL + FIRMWARE_REQUEST_BLOCK + STORAGE_FIRMWARE_SLOT_INFO |
| FIRMWARE_FUNCTION_DOWNLOAD | SRB_IO_CONTROL + FIRMWARE_REQUEST_BLOCK + STORAGE_FIRMWARE_DOWNLOAD | SRB_IO_CONTROL |
| FIRMWARE_FUNCTION_ACTIVATE | SRB_IO_CONTROL + FIRMWARE_REQUEST_BLOCK + STORAGE_FIRMWARE_ACTIVATE | SRB_IO_CONTROL |
固件函数和关联的结构在 ntddscsi.h 中定义。
固件槽信息
固件映像保留在名为槽的位置的设备上。 下载后激活固件映像时，必须找到一个可用槽供其驻留。 若要查找可用槽，升级实用工具可以向设备发送信息查询以接收槽信息描述符。 以下示例函数演示如何检索所选 NVMe 设备上所有固件槽的信息。
// A device list item structure for an adapter
typedef struct _DEVICE_LIST {
HANDLE Handle;
STORAGE_ADAPTER_DESCRIPTOR AdapterDescriptor;
} DEVICE_LIST, *PDEVICE_LIST;
BOOL
DeviceGetFirmwareInfo(
_In_ PDEVICE_LIST DeviceList,
_In_ DWORD Index,
_Inout_ PUCHAR Buffer,
_In_ DWORD BufferLength,
_In_ BOOLEAN DisplayResult
)
/*++
Routine Description:
Retrieve the firmware and firmware slot information from NVMe controller.
Arguments:
DeviceList – a pointer to device array that contains disks information.
Index – the index of NVMe device in DeviceList array.
Buffer – a buffer for input and output.
BufferLength – the size of the buffer.
DisplayResult – print information on screen or not.
Return Value:
BOOLEAN
--*/
{
BOOL result;
ULONG returnedLength;
ULONG firmwareInfoOffset;
PSRB_IO_CONTROL srbControl;
PFIRMWARE_REQUEST_BLOCK firmwareRequest;
PSTORAGE_FIRMWARE_INFO firmwareInfo;
srbControl = (PSRB_IO_CONTROL)Buffer;
firmwareRequest = (PFIRMWARE_REQUEST_BLOCK)(srbControl + 1);
//
// The STORAGE_FIRMWARE_INFO is located after SRB_IO_CONTROL and FIRMWARE_RESQUEST_BLOCK
//
firmwareInfoOffset = ((sizeof(SRB_IO_CONTROL) + sizeof(FIRMWARE_REQUEST_BLOCK) - 1) / sizeof(PVOID) + 1) * sizeof(PVOID);
//
// Setup the SRB control with the firmware ioctl control info
//
srbControl->HeaderLength = sizeof(SRB_IO_CONTROL);
srbControl->ControlCode = IOCTL_SCSI_MINIPORT_FIRMWARE;
RtlMoveMemory(srbControl->Signature, IOCTL_MINIPORT_SIGNATURE_FIRMWARE, 8);
srbControl->Timeout = 30;
srbControl->Length = BufferLength - sizeof(SRB_IO_CONTROL);
//
// Set firmware request fields for FIRMWARE_FUNCTION_GET_INFO. This request is to the controller so
// FIRMWARE_REQUEST_FLAG_CONTROLLER is set in the flags
//
firmwareRequest->Version = FIRMWARE_REQUEST_BLOCK_STRUCTURE_VERSION;
firmwareRequest->Size = sizeof(FIRMWARE_REQUEST_BLOCK);
firmwareRequest->Function = FIRMWARE_FUNCTION_GET_INFO;
firmwareRequest->Flags = FIRMWARE_REQUEST_FLAG_CONTROLLER;
firmwareRequest->DataBufferOffset = firmwareInfoOffset;
firmwareRequest->DataBufferLength = BufferLength - firmwareInfoOffset;
//
// Send the request to get the device firmware info
//
result = DeviceIoControl(DeviceList[Index].Handle,
IOCTL_SCSI_MINIPORT,
Buffer,
BufferLength,
Buffer,
BufferLength,
&returnedLength,
NULL
);
//
// Format and display the firmware info
//
if (DisplayResult) {
if (!result) {
_tprintf(_T("\t Get Firmware Information Failed: 0x%X\n"), GetLastError());
} else {
UCHAR i;
TCHAR revision[16] = {0};
firmwareInfo = (PSTORAGE_FIRMWARE_INFO)((PUCHAR)srbControl + firmwareRequest->DataBufferOffset);
_tprintf(_T("\t ----Firmware Information----\n"));
_tprintf(_T("\t Support upgrade command: %s\n"), firmwareInfo->UpgradeSupport ? _T("Yes") : _T("No"));
_tprintf(_T("\t Slot Count: %d\n"), firmwareInfo->SlotCount);
_tprintf(_T("\t Current Active Slot: %d\n"), firmwareInfo->ActiveSlot);
if (firmwareInfo->PendingActivateSlot == STORAGE_FIRMWARE_INFO_INVALID_SLOT) {
_tprintf(_T("\t Pending Active Slot: %s\n\n"), _T("No"));
} else {
_tprintf(_T("\t Pending Active Slot: %d\n\n"), firmwareInfo->PendingActivateSlot);
}
for (i = 0; i < firmwareInfo->SlotCount; i++) {
RtlCopyMemory(revision, &firmwareInfo->Slot[i].Revision.AsUlonglong, 8);
_tprintf(_T("\t\t Slot Number: %d\n"), firmwareInfo->Slot[i].SlotNumber);
_tprintf(_T("\t\t Slot Read Only: %s\n"), firmwareInfo->Slot[i].ReadOnly ? _T("Yes") : _T("No"));
_tprintf(_T("\t\t Revision: %s\n"), revision);
_tprintf(_T("\n"));
}
}
_tprintf(_T("\n"));
}
return result;
}
槽信息在 STORAGE_FIRMWARE_SLOT_INFO 结构的数组中返回。 每个结构都指示固件槽的激活状态和可用性。 可用性条件如下：
- ReadOnly 成员设置为 0。
- 槽不是STORAGE_FIRMWARE_INFO的 ActiveSlot 成员中的槽号指示的活动槽。
- STORAGE_FIRMWARE_INFO 的 PendingActiveSlot 成员设置为 STORAGE_FIRMWARE_INFO_INVALID_SLOT。
- STORAGE_FIRMWARE_INFO 的 PendingActiveSlot 成员未设置为所需的槽。
此外，如果槽状态满足可用性条件，但 Info 字符串包含有效的修订数据（即非零字节），则槽包含有效的固件映像，但可能会被替换。 Info 字符串中的所有零都表示空槽。
示例：固件升级 - 槽选择、下载和激活
升级实用工具将执行前面提到的三个步骤来更新控制器中的固件。 例如，以下升级例程包含过程中每个步骤的代码。 DeviceGetFirmwareInfo 示例中所示的槽发现步骤由升级例程调用以选择可用槽。 直接在选择槽后演示映像下载和激活步骤。 在每个步骤中，都会显示相应函数命令的使用。
在下载步骤中，固件映像文件将读入分配的缓冲区，并将缓冲区内容传输到控制器。 如果固件映像文件大于缓冲区的大小，则会多次读取映像文件，并传输固件映像的该部分，直到读取整个文件。
固件映像下载完成后，激活步骤需要控制器执行两项操作。 首先，将所选槽分配给固件映像，第二，将所选槽设置为活动槽。
VOID
DeviceFirmwareUpgrade(
_In_ PDEVICE_LIST DeviceList,
_In_ DWORD Index,
_In_ TCHAR* FileName
)
/*++
Routine Description:
Performs a firmware upgrade to the NVMe controller. The an available firmware
slot is selected, the firmware is downloaded to the controller from an image
file, and the new firmware is activated.
Arguments:
DeviceList – a pointer to device array that contains disks information.
Index – the index of NVMe device in DeviceList array.
FileName – the name of the firmware upgrade image file.
Return Value:
None
--*/
{
BOOL result;
PUCHAR buffer = NULL;
ULONG bufferSize;
ULONG firmwareStructureOffset;
ULONG imageBufferLength;
PSRB_IO_CONTROL srbControl;
PFIRMWARE_REQUEST_BLOCK firmwareRequest;
PSTORAGE_FIRMWARE_INFO firmwareInfo;
PSTORAGE_FIRMWARE_DOWNLOAD firmwareDownload;
PSTORAGE_FIRMWARE_ACTIVATE firmwareActivate;
ULONG slotNumber;
ULONG returnedLength;
ULONG i;
HANDLE fileHandle = NULL;
ULONG imageOffset;
ULONG readLength;
BOOLEAN moreToDownload;
//
// The STORAGE_FIRMWARE_INFO is located after SRB_IO_CONTROL and FIRMWARE_RESQUEST_BLOCK
//
firmwareStructureOffset = ((sizeof(SRB_IO_CONTROL) + sizeof(FIRMWARE_REQUEST_BLOCK) - 1) / sizeof(PVOID) + 1) * sizeof(PVOID);
//
// The Max Transfer Length limits the part of buffer that may need to transfer to controller, not the whole buffer.
//
bufferSize = min(DeviceList[Index].AdapterDescriptor.MaximumTransferLength, 2 * 1024 * 1024);
bufferSize += firmwareStructureOffset;
bufferSize += FIELD_OFFSET(STORAGE_FIRMWARE_DOWNLOAD, ImageBuffer);
buffer = (PUCHAR)malloc(bufferSize);
if (buffer == NULL) {
_tprintf(_T("\t FirmwareUpgrade - Allocate buffer failed: 0x%X\n"), GetLastError());
return;
}
//
// calculate the space available for the firmware image portion of the buffer allocation
//
imageBufferLength = bufferSize - firmwareStructureOffset - sizeof(STORAGE_FIRMWARE_DOWNLOAD);
RtlZeroMemory(buffer, bufferSize);
// ---------------------------------------------------------------------------
// ( 1 ) SELECT A SUITABLE FIRMWARE SLOT
// ---------------------------------------------------------------------------
//
// Get firmware slot information data.
//
result = DeviceGetFirmwareInfo(DeviceList, Index, buffer, bufferSize, FALSE);
if (result == FALSE) {
_tprintf(_T("\t FirmwareUpgrade: Get Firmware Information Failed: 0x%X\n"), GetLastError());
goto Exit;
}
//
// Set the request structure pointers
//
srbControl = (PSRB_IO_CONTROL)buffer;
firmwareRequest = (PFIRMWARE_REQUEST_BLOCK)(srbControl + 1);
firmwareInfo = (PSTORAGE_FIRMWARE_INFO)((PUCHAR)srbControl + firmwareRequest->DataBufferOffset);
if (srbControl->ReturnCode != FIRMWARE_STATUS_SUCCESS) {
_tprintf(_T("\t FirmwareUpgrade - get firmware info failed. srbControl->ReturnCode %d.\n"), srbControl->ReturnCode);
goto Exit;
}
//
// SelectFind the first writable slot.
//
slotNumber = (ULONG)-1;
if (firmwareInfo->UpgradeSupport) {
for (i = 0; i < firmwareInfo->SlotCount; i++) {
if (firmwareInfo->Slot[i].ReadOnly == FALSE) {
slotNumber = firmwareInfo->Slot[i].SlotNumber;
break;
}
}
}
//
// If no writable slot is found, bypass downloading and activation
//
if (slotNumber == (ULONG)-1) {
_tprintf(_T("\t FirmwareUpgrade - No writable Firmware slot.\n"));
goto Exit;
}
// ---------------------------------------------------------------------------
// ( 2 ) DOWNLOAD THE FIRMWARE IMAGE TO THE CONTROLLER
// ---------------------------------------------------------------------------
//
// initialize image length and offset
//
imageBufferLength = (imageBufferLength / sizeof(PVOID)) * sizeof(PVOID);
imageOffset = 0;
readLength = 0;
moreToDownload = TRUE;
//
// Open image file and download it to controller.
//
if (FileName == NULL) {
_tprintf(_T("\t FirmwareUpgrade - No firmware file specified.\n"));
goto Exit;
}
fileHandle = CreateFile(FileName, // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if (fileHandle == INVALID_HANDLE_VALUE) {
_tprintf(_T("\t FirmwareUpgrade - unable to open file \"%s\" for read.\n"), FileName);
goto Exit;
}
//
// Read and download the firmware from the image file into image buffer length portions. Send the
// image portion to the controller.
//
while (moreToDownload) {
RtlZeroMemory(buffer, bufferSize);
//
// Setup the SRB control with the firmware ioctl control info
//
srbControl->HeaderLength = sizeof(SRB_IO_CONTROL);
srbControl->ControlCode = IOCTL_SCSI_MINIPORT_FIRMWARE;
RtlMoveMemory(srbControl->Signature, IOCTL_MINIPORT_SIGNATURE_FIRMWARE, 8);
srbControl->Timeout = 30;
srbControl->Length = bufferSize - sizeof(SRB_IO_CONTROL);
//
// Set firmware request fields for FIRMWARE_FUNCTION_DOWNLOAD. This request is to the controller so
// FIRMWARE_REQUEST_FLAG_CONTROLLER is set in the flags
//
firmwareRequest->Version = FIRMWARE_REQUEST_BLOCK_STRUCTURE_VERSION;
firmwareRequest->Size = sizeof(FIRMWARE_REQUEST_BLOCK);
firmwareRequest->Function = FIRMWARE_FUNCTION_DOWNLOAD;
firmwareRequest->Flags = FIRMWARE_REQUEST_FLAG_CONTROLLER;
firmwareRequest->DataBufferOffset = firmwareStructureOffset;
firmwareRequest->DataBufferLength = bufferSize - firmwareStructureOffset;
//
// Initialize the firmware data buffer pointer to the proper position after the request structure
//
firmwareDownload = (PSTORAGE_FIRMWARE_DOWNLOAD)((PUCHAR)srbControl + firmwareRequest->DataBufferOffset);
if (ReadFile(fileHandle, firmwareDownload->ImageBuffer, imageBufferLength, &readLength, NULL) == FALSE) {
_tprintf(_T("\t FirmwareUpgrade - Read firmware file failed.\n"));
goto Exit;
}
if (readLength == 0) {
moreToDownload = FALSE;
break;
}
if ((readLength % sizeof(ULONG)) != 0) {
_tprintf(_T("\t FirmwareUpgrade - Read firmware file failed.\n"));
}
//
// Set the download parameters and adjust the offset for this portion of the firmware image
//
firmwareDownload->Version = 1;
firmwareDownload->Size = sizeof(STORAGE_FIRMWARE_DOWNLOAD);
firmwareDownload->Offset = imageOffset;
firmwareDownload->BufferSize = readLength;
//
// download this portion of firmware to the device
//
result = DeviceIoControl(DeviceList[Index].Handle,
IOCTL_SCSI_MINIPORT,
buffer,
bufferSize,
buffer,
bufferSize,
&returnedLength,
NULL
);
if (result == FALSE) {
_tprintf(_T("\t FirmwareUpgrade - IOCTL - firmware download failed. 0x%X.\n"), GetLastError());
goto Exit;
}
if (srbControl->ReturnCode != FIRMWARE_STATUS_SUCCESS) {
_tprintf(_T("\t FirmwareUpgrade - firmware download failed. srbControl->ReturnCode %d.\n"), srbControl->ReturnCode);
goto Exit;
}
//
// Update Image Offset for next iteration.
//
imageOffset += readLength;
}
// ---------------------------------------------------------------------------
// ( 3 ) ACTIVATE THE FIRMWARE SLOT ASSIGNED TO THE UPGRADE
// ---------------------------------------------------------------------------
//
// Activate the newly downloaded image with the assigned slot.
//
RtlZeroMemory(buffer, bufferSize);
//
// Setup the SRB control with the firmware ioctl control info
//
srbControl->HeaderLength = sizeof(SRB_IO_CONTROL);
srbControl->ControlCode = IOCTL_SCSI_MINIPORT_FIRMWARE;
RtlMoveMemory(srbControl->Signature, IOCTL_MINIPORT_SIGNATURE_FIRMWARE, 8);
srbControl->Timeout = 30;
srbControl->Length = bufferSize - sizeof(SRB_IO_CONTROL);
//
// Set firmware request fields for FIRMWARE_FUNCTION_ACTIVATE. This request is to the controller so
// FIRMWARE_REQUEST_FLAG_CONTROLLER is set in the flags
//
firmwareRequest->Version = FIRMWARE_REQUEST_BLOCK_STRUCTURE_VERSION;
firmwareRequest->Size = sizeof(FIRMWARE_REQUEST_BLOCK);
firmwareRequest->Function = FIRMWARE_FUNCTION_ACTIVATE;
firmwareRequest->Flags = FIRMWARE_REQUEST_FLAG_CONTROLLER;
firmwareRequest->DataBufferOffset = firmwareStructureOffset;
firmwareRequest->DataBufferLength = bufferSize - firmwareStructureOffset;
//
// Initialize the firmware activation structure pointer to the proper position after the request structure
//
firmwareActivate = (PSTORAGE_FIRMWARE_ACTIVATE)((PUCHAR)srbControl + firmwareRequest->DataBufferOffset);
//
// Set the activation parameters with the available slot selected
//
firmwareActivate->Version = 1;
firmwareActivate->Size = sizeof(STORAGE_FIRMWARE_ACTIVATE);
firmwareActivate->SlotToActivate = (UCHAR)slotNumber;
//
// Send the activation request
//
result = DeviceIoControl(DeviceList[Index].Handle,
IOCTL_SCSI_MINIPORT,
buffer,
bufferSize,
buffer,
bufferSize,
&returnedLength,
NULL
);
if (result == FALSE) {
_tprintf(_T("\t FirmwareUpgrade - IOCTL - firmware activate failed. 0x%X.\n"), GetLastError());
goto Exit;
}
//
// Display status result from firmware activation
//
switch (srbControl->ReturnCode) {
case FIRMWARE_STATUS_SUCCESS:
_tprintf(_T("\t FirmwareUpgrade - firmware activate succeeded.\n"));
break;
case FIRMWARE_STATUS_POWER_CYCLE_REQUIRED:
_tprintf(_T("\t FirmwareUpgrade - firmware activate succeeded. PLEASE REBOOT COMPUTER.\n"));
break;
case FIRMWARE_STATUS_ILLEGAL_REQUEST:
case FIRMWARE_STATUS_INVALID_PARAMETER:
case FIRMWARE_STATUS_INPUT_BUFFER_TOO_BIG:
_tprintf(_T("\t FirmwareUpgrade - firmware activate parameter error. srbControl->ReturnCode %d.\n"), srbControl->ReturnCode);
break;
case FIRMWARE_STATUS_INVALID_SLOT:
_tprintf(_T("\t FirmwareUpgrade - firmware activate, slot number invalid.\n"));
break;
case FIRMWARE_STATUS_INVALID_IMAGE:
_tprintf(_T("\t FirmwareUpgrade - firmware activate, invalid firmware image.\n"));
break;
case FIRMWARE_STATUS_ERROR:
case FIRMWARE_STATUS_CONTROLLER_ERROR:
_tprintf(_T("\t FirmwareUpgrade - firmware activate, error returned.\n"));
break;
default:
_tprintf(_T("\t FirmwareUpgrade - firmware activate, unexpected error. srbControl->ReturnCode %d.\n"), srbControl->ReturnCode);
break;
}
Exit:
if (fileHandle != NULL) {
CloseHandle(fileHandle);
}
if (buffer != NULL) {
free(buffer);
}
return;
}
注意
不支持同时下载多个固件映像。 下载单个固件后，始终是单个固件激活。
只需使用具有相应槽号的 activate 函数命令即可重新激活已驻留在槽中的固件映像。
SRB I/O 控件的IOCTL_SCSI_MINIPORT_FIRMWARE控制代码从 Windows 8.1 开始提供。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈