Aktualisieren der Firmware für ein NVMe-Gerät
Updates der Firmware auf einem NVMe-Speichergerät werden an den Miniporttreiber für dieses Gerät ausgegeben. Funktionsbefehle zum Abrufen von Firmwareinformationen, Herunterladen und Aktivieren von Firmwareabbildern werden für den Miniport ausgegeben.
Firmwareupgradeprozess
NVMe-Geräte, die für Windows zertifiziert sind, können ihre Firmware aktualisieren, während das Gerät in Betrieb ist. Die Firmware wird mithilfe IOCTL_SCSI_MINIPORT Anforderung aktualisiert, die die zugehörigen Firmwaresteuerungsdaten enthält, die in einem SRB formatiert sind. Der Updateprozess umfasst:
Sammeln Sie die Firmwareslotinformationen, um zu bestimmen, wo das Update installiert werden soll. Bei der Entscheidung, wo sich das Firmwareupdate befindet, müssen einige Aspekte berücksichtigt werden.
- Wie viele Slots sind verfügbar?
- Wie viele Slots können ein Update halten? Bei einigen Slots handelt es sich um schreibgeschützte Oder-Images, die beibehalten werden müssen, wenn die Möglichkeit zum Rückgängig machen auf ein vorheriges Image gewünscht ist.
- Welcher Slot enthält das aktuelle aktive Firmwareimage (die ausgeführte Firmware)?
Um das Gerät zu aktualisieren, wird ein Slot ausgewählt, der schreibbar und derzeit nicht aktiv ist. Alle vorhandenen Imagedaten im ausgewählten Slot werden überschrieben, wenn das Update abgeschlossen ist.
Laden Sie das neue Firmwareimage für einen ausgewählten Slot herunter. Je nach Größe des Bilds tritt dies bei einem einzelnen Übertragungsvorgang oder bei nachfolgenden Übertragungen mehrerer Teile des Bilds auf. Ein Teil eines Images ist durch min (Maximale Übertragungsgröße des Controllers, 512 KB) beschränkt.
Damit das heruntergeladene Image zum aktiven Firmwareimage wird, wird es dem Slot zugewiesen. Der aktive Firmwareslot wird dann vom aktuell verwendeten Slot in den Slot umgeschaltet, der dem heruntergeladenen Image zugewiesen ist. Abhängig vom Downloadtyp und den Änderungen am Firmwareimage ist möglicherweise ein Neustart des Systems erforderlich. Dies wird durch den NVMe-Controller bestimmt.
Miniport-Firmwaresteuerungsanforderungen
Jeder Funktionsbefehl wird in einer FIRMWARE_REQUEST_BLOCK-Struktur festgelegt, die in einem SRB_IO_CONTROL im Puffer einer IOCTL_SCSI_MINIPORT ist. Das ControlCode-MitgliedSRB_IO_CONTROLauf IOCTL_SCSI_MINIPORT_FIRMWARE, um einen Miniport-Firmwarevorgang anzugeben. Jeder Funktionsbefehl verfügt über eine verwandte Informationsstruktur, die sich nach dem FIRMWARE_REQUEST_BLOCK. In der folgenden Tabelle sind die einzelnen Funktionsbefehle und die strukturen aufgeführt, die im Systempuffer für IOCTL_SCSI_MINIPORT.
| Funktion | Eingabedaten | Ausgabedaten |
|---|---|---|
| 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 |
Die Firmwarefunktionen und zugeordneten Strukturen werden in ntddscsi.h definiert.
Informationen zum Firmwareslot
Firmwarebilder werden auf dem Gerät an Standorten verwaltet, die als Slots bezeichnet werden. Es ist erforderlich, einen verfügbaren Slot zu finden, damit sich das Firmwareimage befindet, wenn es nach einem Download aktiviert wird. Um einen verfügbaren Slot zu finden, kann ein Upgradeprogramm eine Informationsabfrage an das Gerät senden, um die Slotinformationsdeskriptoren zu erhalten. Die folgende Beispielfunktion zeigt, wie Die Informationen für alle Firmwareslots auf einem ausgewählten NVMe-Gerät abgerufen werden.
// 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;
}
Slotinformationen werden in einem Array von STORAGE_FIRMWARE_SLOT_INFO zurückgegeben . Jede Struktur gibt den Aktivierungsstatus und die Verfügbarkeit des Firmwareslots an. Verfügbarkeitsbedingungen:
- Das ReadOnly-Member ist auf 0 festgelegt.
- Der Slot ist nicht der aktive Slot, der durch die Slotnummer im ActiveSlot-Member des STORAGE_FIRMWARE_INFO.
- Das PendingActiveSlot-MemberSTORAGE_FIRMWARE_INFO auf STORAGE_FIRMWARE_INFO_INVALID_SLOT.
- Das PendingActiveSlot-STORAGE_FIRMWARE_INFOist nicht auf den gewünschten Slot festgelegt.
Wenn der Slotstatus die Verfügbarkeitsbedingungen erfüllt, die Info-Zeichenfolge jedoch gültige Revisionsdaten enthält(byte ungleich 0), enthält der Slot ein gültiges Firmwareimage, kann jedoch ersetzt werden. Alle Nullen in der Info-Zeichenfolge geben einen leeren Slot an.
Beispiel: Firmwareupgrade– Slotauswahl, Download und Aktivierung
Ein Upgradeprogramm führt die drei zuvor erwähnten Schritte aus, um die Firmware im Controller zu aktualisieren. Beispielsweise enthält die folgende Upgraderoutine Code für jeden Schritt im Prozess. Der Im Beispiel DeviceGetFirmwareInfo gezeigte Schritt zur Slotermittlung wird von der Upgraderoutine aufgerufen, um einen verfügbaren Slot auszuwählen. Die Schritte zum Herunterladen und Aktivieren des Images werden direkt nach der Slotauswahl gezeigt. In jedem Schritt wird die Verwendung des entsprechenden Funktionsbefehls gezeigt.
Während des Downloadschritts wird eine Firmwareimagedatei in einen zugeordneten Puffer gelesen, und der Pufferinhalt wird an den Controller übertragen. Wenn die Firmwareimagedatei größer als die Größe des Puffers ist, wird die Imagedatei mehrmals gelesen, und dieser Teil des Firmwareimages wird übertragen, bis die gesamte Datei gelesen wird.
Nach Abschluss des Firmwareimagedownloads sind für den Aktivierungsschritt zwei Aktionen vom Controller erforderlich. Erstens wird der ausgewählte Slot dem Firmwareimage zugewiesen, und zweitens wird der ausgewählte Slot als aktiver Slot festgelegt.
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;
}
Hinweis
Das gleichzeitige Herunterladen mehrerer Firmwareabbilder wird nicht unterstützt. Auf einen einzelnen Firmwaredownload folgt immer eine einzelne Firmwareaktivierung.
Ein Firmwareimage, das sich bereits in einem Slot befindet, kann reaktiviert werden, indem nur der Befehl activate function mit der entsprechenden Slotnummer verwendet wird.
Der IOCTL_SCSI_MINIPORT_FIRMWARE für das SRB-E/A-Steuerelement ist ab Windows 8.1.