Pembaruan Firmware Perangkat Broadband Seluler
Artikel ini memberikan panduan kepada produsen modul Mobile Broadband (MB) yang berniat mendukung perangkat peningkatan firmware melalui Windows Update (WU). Perangkat harus mematuhi spesifikasi USB NCM Mobile Broadband Interface Model (MBIM) V1.0 yang dirilis oleh Usb-IF Device Working Group.
Informasi dalam artikel ini berlaku untuk:
- Windows 8/Windows 10/Windows 11
Persyaratan Perangkat
Untuk mendukung pembaruan firmware pada Mobile Broadband menggunakan Windows Update, produsen modul atau perangkat perlu mematuhi persyaratan berikut:
- Driver berbasis UMDF (User Mode Driver Framework) yang dikembangkan oleh modul atau produsen perangkat, dikemas bersama dengan file INF dan payload firmware. Contoh file INF dan detail disediakan di bagian selanjutnya dari dokumen ini
- Firmware perangkat untuk menerapkan fungsionalitas berikut:
- Firmware ID Device Service (FID). Untuk informasi selengkapnya, lihat FID Device Service.
- Firmware untuk mendukung layanan perangkat pembaruan firmware. Ini adalah layanan perangkat khusus produsen perangkat yang memungkinkan driver UMDF untuk memanggil dan menjalankan/mengunduh payload firmware dan memulai proses pembaruan firmware.
Gambaran Umum Operasional
Diagram berikut menunjukkan desain tingkat tinggi dan interaksi antara tiga komponen yang terlibat: perangkat MBIM, Sistem Operasi Windows 8, dan driver peningkatan firmware yang disediakan IHV.
- Ketika Layanan WWAN mendeteksi kedatangan perangkat MB baru, layanan perangkat mendukung Firmware ID (FID) Device Service. Jika ada, ia mengambil FID, yang didefinisikan sebagai GUID. Spesifikasi Firmware Device Service yang dibutuhkan IHV untuk dukungan pada perangkat dijelaskan di bawah ini.
- WWAN Service (OS Windows) menghasilkan "node perangkat lunak" menggunakan FID yang diperoleh di atas sebagai Id perangkat keras perangkat. Ini disebut sebagai "Node Dev Lunak" dalam diagram di atas. Pembuatan dev-node akan memulai subsistem PnP (OS Windows) untuk menemukan driver yang paling cocok. Di Windows 8, sistem PnP pertama-tama akan mencoba menginstal driver dari penyimpanan lokal, jika tersedia, dan pada OS paralel akan mencoba mengambil driver yang lebih cocok dari WU. Driver NULL kotak masuk akan digunakan sebagai default jika driver yang lebih cocok tidak tersedia untuk menghilangkan masalah "Driver Not Found".
- Paket IHV WU, berdasarkan kecocokan FID, ditarik ke bawah ke mesin dan diinstal. Diharapkan bahwa FID mewakili SKU firmware yang unik (keunikan di sini didefinisikan oleh perangkat kombinasi VID/PID/REV dan MNO). Paket WU akan berisi driver UMDF yang ditulis IHV serta payload firmware.
- Setelah IHV UMDF dimuat pada node pengembangan lunak, IHV UMDF bertanggung jawab untuk mengontrol alur pembaruan firmware. Perlu dicatat bahwa waktu hidup node pengembangan lunak terkait dengan kehadiran fisik perangkat MBIM. Driver UMDF harus melakukan langkah-langkah berikut untuk melakukan pembaruan firmware
- Perangkat dapat di-boot ulang beberapa kali selama proses pembaruan firmware, tetapi akan menyebabkan driver UMDF dibongkar/dimuat ulang
- Seluruh proses peningkatan firmware, termasuk reboot, harus berlangsung tidak lebih dari 60 detik.
- Setelah pembaruan firmware selesai dan perangkat telah kembali ke mode MBIM, Windows harus diberi tahu. Ini dilakukan dengan menghapus properti DEVPKEY_Device_PostInstallInProgress yang ditetapkan sebelumnya. Antarmuka IWDFUnifiedPropertyStore menjelaskan cara mengatur properti pada dev-node. Properti yang ditetapkan sebelumnya dapat dibersihkan menggunakan DEVPROP_TYPE_EMPTY.
- Selama panggilan balik UMDF OnPrepareHardware, driver UMDF harus memeriksa apakah firmware pada perangkat perlu diperbarui. Ini dilakukan dengan membandingkan versi firmware pada perangkat dengan yang masuk melalui Windows Update. Panduan tambahan diberikan nanti dalam dokumen mengenai lokasi penempatan biner firmware. Jika pembaruan firmware diperlukan, driver UMDF harus:
- Menjadwalkan item kerja. Peningkatan firmware aktual terjadi dalam konteks item kerja.
- Setelah item kerja berhasil dijadwalkan, beri tahu Windows tentang dimulainya pembaruan firmware. Ini dilakukan dengan mengatur properti DEVPKEY_Device_PostInstallInProgress pada node dev lunak dalam konteks callback UMDF OnPrepareHardware.
- Penting untuk tidak memblokir panggilan balik OnPrepareHardware saat pembaruan firmware sedang berlangsung. Diharapkan bahwa panggilan balik OnPrepareHardware selesai dalam satu atau dua detik paling banyak.
Contoh file INF untuk Paket WU
Bagian ini menyediakan contoh INF yang merupakan bagian dari paket WU. Poin-poin penting yang perlu diperhatikan dalam file INF adalah:
- Biner firmware independen dari driver UMDF.
- Biner firmware terletak di direktori driverstore, jalur yang ditentukan oleh sistem operasi dan direferensikan dalam INF menggunakan DIRID 13. Biner tidak dapat dieksekusi yang berisi header PE/COFF.
%13%\<UniqueBinaryName>.bin- File INF menyimpan lokasi ini di registri dan driver UMDF membaca nilai registri untuk menemukan lokasi biner.
- Contoh templat INF berikut menyoroti item yang perlu diisi oleh IHV.
[Version]
Signature = "$WINDOWS NT$"
Class = Firmware
ClassGuid = {f2e7dd72-6468-4e36-b6f1-6488f42c1b52}
Provider = %Provider%
DriverVer = 06/21/2006,6.2.8303.0
CatalogFile = MBFWDriver.cat
PnpLockdown = 1
[Manufacturer]
%Mfg% = Firmware,NTx86
[Firmware.NTx86]
%DeviceDesc% = Firmware_Install,MBFW\{FirmwareID} ; From Device Service
;%DeviceDesc% = Firmware_Install,MBFW\{2B13DD42-649C-3442-9E08-D85B26D7825C}
[Firmware_Install.NT]
CopyFiles = FirmwareDriver_CopyFiles,FirmwareImage_CopyFiles
[Firmware_Install.NT.HW]
AddReg = Device_AddReg
[Device_AddReg]
HKR,,FirmwareBinary,,"%13%\MBIHVFirmware-XYZ-1.0.bin"
[Firmware_Install.NT.Services]
AddService = WUDFRd,0x000001fa,WUDFRD_ServiceInstall
[WUDFRD_ServiceInstall]
DisplayName = %WudfRdDisplayName%
ServiceType = 1
StartType = 3
ErrorControl = 1
ServiceBinary = %12%\WUDFRd.sys
LoadOrderGroup = Base
[Firmware_Install.NT.CoInstallers]
CopyFiles = WudfCoInstaller_CopyFiles
[WudfCoInstaller_AddReg]
HKR,,CoInstallers32,0x00010000,"WUDFCoinstaller.dll"
[Firmware_Install.NT.Wdf]
UmdfService = MBIHVFirmwareDriver,MBIHVFirmwareDriver_Install
UmdfServiceOrder = MBIHVFirmwareDriver
[MBIHVFirmwareDriver_Install]
UmdfLibraryVersion = 1.11
ServiceBinary = %12%\UMDF\MBFWDriver.dll
DriverCLSID = {<DriverClassGuid>} ; From UMDF driver
[FirmwareImage_CopyFiles]
MBIHVFirmware-XYZ-1.0.bin ; Firmware Image
[FirmwareDriver_CopyFiles]
MBFWDriver.dll ; UMDF driver for SoftDevNode
[DestinationDirs]
FirmwareImage_CopyFiles = 13 ; Driver Store
FirmwareDriver_CopyFiles = 12,UMDF ;%SystemRoot%\System32\drivers\UMDF
[SourceDisksFiles]
MBIHVFirmware-XYZ-1.0.bin = 1
[SourceDisksNames]
1 = %DiskName%
; ================== Generic ==================================
[Strings]
Provider = "MBIHV"
Mfg = "MBIHV"
DeviceDesc = "MBIHV Mobile Broadband Firmware Device"
DiskName = "Firmware Driver Installation Media"
Firmware Identification Device Service (FID Device Service)
Perangkat yang mematuhi MBIM akan menerapkan dan melaporkan layanan perangkat berikut saat dikueri oleh CID_MBIM_DEVICE_SERVICES. Layanan terkenal yang ada didefinisikan dalam spesifikasi NCM MBIM di bagian 10.1. Microsoft Corporation memperluas ini untuk menentukan layanan berikut.
Nama Layanan = ID Microsoft Firmware
UUID = UUID_MSFWID UUID
Nilai = e9f7dea2-feaf-4009-93ce-90a3694103b6
Secara khusus, CID berikut didefinisikan untuk layanan perangkat UUID_MSFWID:
CID = CID_MBIM_MSFWID_FIRMWAREID
Kode Perintah = 1
Kueri = Ya
Set = Tidak
Peristiwa = Tidak
Atur payload InformationBuffer = N/A
Payload Query InformationBuffer = N/A
Informasi Penyelesaian PayloadBuffer = UUID
CID_MBIM_MSFWID_FIRMWAREID
Perintah mengembalikan ID Firmware yang ditetapkan MNO atau IHV untuk perangkat. UUID dikodekan berdasarkan pedoman dalam spesifikasi MBIM.
Kueri = InformationBuffer di MBIM_COMMAND_MSG tidak digunakan. UUID dikembalikan dalam MBIM_COMMAND_DONE InformationBuffer.
Set = Tidak didukung
Kejadian Yang Tidak Diminta = Tidak didukung
Cuplikan kode untuk perilaku driver UMDF
Seperti yang ditunjukkan sebelumnya, driver UMDF harus menunjukkan ke Windows ketika dimulai dan menyelesaikan peningkatan firmware. Bagian ini menyediakan cuplikan kode yang menunjukkan bagaimana driver harus memberi tahu Windows tentang peristiwa ini.
/**
* This is the IPnpCallbackHardware*:OnPrepareHardware handler
* in the UMDF driver. This is called every time the firmware
* update is device is started. Since this handler should be
* blocked from returning actual the firmware update process
* should be done in a workitem
*/
HRESULT
CMyDevice::OnPrepareHardware(IWDFDevice* pDevice)
{
HRESULT hr = S_OK;
BOOL bFirmwareUpdateInProgress = FALSE;
BOOL bFirmwareUpdateNeeded = FALSE;
BOOL bFirmwareUpdateIsDone = FALSE;
//
// The snippets below demonstrates the steps for firmware
// update against a MB device that loads the updated firmware
// on device boot. So the firmware update driver needs to
// send the new firmware down to the device and then tell
// the device to initiate a stop/start. Once the device has
// reappeared, it would have automatically loaded the
// new firmware
//
//
// First, determine if firmware update is in progress. This
// can be based on some registry key that is saved when
// firmware update is started
//
// Assuming this status is returned in bFirmwareUpdateInProgress
if (bFirmwareUpdateInProgress)
{
//
// If firmware update is in progress, check if its done. For
// this it may be necessary to access the MB device. Note that
// if the MB device (& hence the Firmware update device) needs
// multiple stop/starts to do the firmware update. In that case
// it will be marked as done at the end of the process
//
// Assuming this status is returned in bFirmwareUpdateIsDone
if (bFirmwareUpdateIsDone)
{
//
// Signal the completion of the firmware update
// process.
//
SignalFirmwareUpdateComplete(pDevice);
}
else
{
//
// Take appropriate steps to get notified when
// firmware update is done. Call SignalFirmwareUpdateComplete
// when that notification is received
//
}
}
else
{
//
// Determine if firmware update is needed. This can be
// based on checking state in the registry of the last
// firmware version set on the device to the firmware
// version associated with this driver
//
// Assuming this status is returned in bFirmwareUpdateNeeded
if (bFirmwareUpdateNeeded)
{
//
// Create and queue a workitem to perform the firmware
// update process. IWDFWorkItem can be used for this
//
// Assuming the creation/enquing status
// is returned in hr
if (SUCCEEDED(hr))
{
//
// Work item queued. It will do the firmware update
// Tell the OS that firmware update is in progress
//
SignalFirmwareUpdateInProgress(pDevice);
}
}
}
//
// If we have a failure, we clear the firmware update
// in progress state
//
if (FAILED(hr))
{
SignalFirmwareUpdateComplete(pDevice);
}
return S_OK;
}
/**
* This function tells the OS that firmware update is in progress.
* It should be called from the firmware update UMDF driver's
* IPnpCallbackHardware*:OnPrepareHardware handler after it has
* successfully queued a workitem to perform the firmware update
*/
HRESULT
CMyDevice::SignalFirmwareUpdateInProgress(
__in IWDFDevice* pDevice
)
{
HRESULT hr = S_OK;
IWDFUnifiedPropertyStoreFactory* spPropertyStoreFactory = NULL;
IWDFUnifiedPropertyStore* spPropStore = NULL;
WDF_PROPERTY_STORE_ROOT wdfPropRoot = { sizeof(WDF_PROPERTY_STORE_ROOT), WdfPropertyStoreRootClassHardwareKey };
DEVPROP_BOOLEAN boolValue = DEVPROP_TRUE;
do
{
hr = pDevice->QueryInterface(IID_PPV_ARGS(&spPropertyStoreFactory));
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to query for property store factory. Error = 0x%x", hr);
break;
}
hr = spPropertyStoreFactory->RetrieveUnifiedDevicePropertyStore(
&wdfPropRoot,
&spPropStore
);
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to query for device property store. Error = 0x%x", hr);
break;
}
// Set the OS flag
hr = spPropStore->SetPropertyData(
reinterpret_cast<const DEVPROPKEY*>(&DEVPKEY_Device_PostInstallInProgress),
0, // this property is language neutral
0,
DEVPROP_TYPE_BOOLEAN,
sizeof(DEVPROP_BOOLEAN),
&boolValue
);
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to set device property for PostInstallInProgress. Error = 0x%x", hr);
break;
}
//
// Save some state so that we know we are in the process
// of firmware update
//
} while (FALSE);
if (spPropStore)
{
spPropStore->Release();
}
if (spPropertyStoreFactory)
{
spPropertyStoreFactory->Release();
}
return hr;
}
/**
* This function tells the OS that firmware update is done
* It should be called only after the full firmware update process
* (including any MB device stop/start) has finished
*/
HRESULT
CMyDevice::SignalFirmwareUpdateComplete(
__in IWDFDevice* pDevice
)
{
HRESULT hr = S_OK;
IWDFUnifiedPropertyStoreFactory* spPropertyStoreFactory = NULL;
IWDFUnifiedPropertyStore* spPropStore = NULL;
WDF_PROPERTY_STORE_ROOT wdfPropRoot = { sizeof(WDF_PROPERTY_STORE_ROOT), WdfPropertyStoreRootClassHardwareKey };
do
{
hr = pDevice->QueryInterface(IID_PPV_ARGS(&spPropertyStoreFactory));
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to query for property store factory. Error = 0x%x", hr);
break;
}
hr = spPropertyStoreFactory->RetrieveUnifiedDevicePropertyStore(
&wdfPropRoot,
&spPropStore
);
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to query for device property store. Error = 0x%x", hr);
break;
}
hr = spPropStore->SetPropertyData(
reinterpret_cast<const DEVPROPKEY*>(&DEVPKEY_Device_PostInstallInProgress),
0, // this property is language neutral
0,
DEVPROP_TYPE_BOOLEAN,
0,
NULL
);
if (FAILED(hr))
{
Trace(TRACE_LEVEL_ERROR, "Failed to clear device property for PostInstallInProgress. Error = 0x%x", hr);
break;
}
//
// Save some state so that we can do quick check on
// whether firmware update is needed or not
//
} while (FALSE);
if (spPropStore)
{
spPropStore->Release();
}
if (spPropertyStoreFactory)
{
spPropertyStoreFactory->Release();
}
return hr;
}