FPGA上位機開發(fā)里換底層通信庫算是我最不愿意輕易碰的活。之前一個FPGA采集卡項目把上位機控制通道從老供應(yīng)商的同步接口SDK遷到另一家供應(yīng)商的同類SDK項目標(biāo)題就叫“Opalkelly Frontpanel SDK到Pionway SDK的代碼遷移實例”。這名字聽起來像照著文檔改API就行真做起來完全是另一回事設(shè)備枚舉方式不同、管線下載時序不同、塊傳輸?shù)膶R要求不同連錯誤碼都沒法直接翻譯。這篇文章不點評具體廠商而是把這次代碼遷移的完整思路、API映射表、適配層設(shè)計、踩坑記錄和回歸測試方法整理出來。適合正在做FPGA上位機底層替換、或者準(zhǔn)備給項目加一層硬件無關(guān)抽象層的朋友參考。1. 為什么要做這次遷移不是閑得慌是硬件供應(yīng)變了1.1 表面是換接口實際上是重寫“邊界”這個項目原本的架構(gòu)非常典型上位機軟件通過USB 3.0跟FPGA采集卡通信采集卡里跑的是自己寫的邏輯上位機里則是廠商提供的動態(tài)庫。剛開始沒有想太遠(yuǎn)所有業(yè)務(wù)代碼都直接調(diào)用廠商SDK的函數(shù)比如枚舉設(shè)備、打開設(shè)備、下載管線的bit文件、讀寫寄存器、批量收發(fā)數(shù)據(jù)。項目跑起來之后功能確實沒問題但硬件方案一調(diào)整麻煩就來了原來那家供應(yīng)商的驅(qū)動和庫不能再繼續(xù)使用時上層業(yè)務(wù)代碼幾乎要到每個函數(shù)里改一遍。表面上這只是一個“換庫”的動作實際上等于把上位機與FPGA之間的邊界重寫一遍。因為兩家SDK雖然解決的是同一個問題但它們的抽象層級不一樣。老SDK把“設(shè)備”看成一套完整的FrontPanel工作環(huán)境打開設(shè)備之后要先初始化環(huán)境再下載bit流然后才能操作管線新SDK更偏向“命令式”的接口打開句柄、發(fā)送命令、關(guān)閉句柄沒有那么多隱含狀態(tài)。如果只是按函數(shù)名一一對應(yīng)替換很容易把A SDK里的隱式初始化邏輯丟掉結(jié)果就是設(shè)備打開成功、寄存器也能寫但數(shù)據(jù)通路完全不通。所以我的第一個結(jié)論是別急著寫代碼先承認(rèn)這是一次架構(gòu)層面的調(diào)整而不是文本替換。你需要重新梳理上位機軟件里所有跟硬件有關(guān)的操作把它們歸納為一組對上層穩(wěn)定的能力再在這組能力和具體SDK之間建立適配層。這么做的代價是前期多畫幾張圖、多建幾個類但好處是后續(xù)每換一次硬件只需要換一個適配器。1.2 三種遷移路線的對比直接替換、適配層、重寫針對這次遷移我認(rèn)真對比過三條路線結(jié)合實際項目情況才選了中間那條。第一條是全局替換API調(diào)用。把代碼里所有A_OpenDevice換成B_OpenDeviceA_WriteRegister換成B_WriteRegister看起來最省事。但這條路線的問題在于兩家SDK的調(diào)用上下文不一致。老的塊傳輸接口可能要求先打開一條管道并設(shè)置緩沖區(qū)新的接口卻是在調(diào)用時傳端點號老的上位機代碼里遍布各種A_GetLastError新的SDK卻直接返回布爾值把錯誤碼掛在另一個查詢函數(shù)里。全局替換下來改了一兩百處調(diào)用任何一處漏掉隱式依賴排查成本都會指數(shù)上升。第二條是做適配層也是我最后選的方案。定義一個中間接口把自己項目的語義放進去比如打開設(shè)備、配置FPGA、讀寄存器、寫寄存器、批量讀、批量寫。然后分別實現(xiàn)老SDK適配器和新SDK適配器業(yè)務(wù)代碼只依賴這個接口。這樣上層代碼幾乎不用動換SDK只是換一個工廠方法的事。第三條是重寫業(yè)務(wù)邏輯。如果項目本身就比較小功能就一個寄存器讀寫加一個中斷處理確實可以考慮直接在B SDK上重寫一套簡單的控制流程。但我們的采集卡項目涉及十幾個寄存器、三種以上的批量傳輸端點而且還帶一套內(nèi)部狀態(tài)機重寫業(yè)務(wù)的測試成本比寫適配層高得多。最終選適配層還有一個原因它可以跟舊代碼共存。遷移不是一天完成的老SDK的適配器先寫出來、先跑通業(yè)務(wù)層繼續(xù)用統(tǒng)一接口不會出現(xiàn)老代碼全部不可用的空窗期。2. 動手前的接口梳理先畫清楚映射再寫代碼2.1 端到端的最小調(diào)用鏈路在寫適配器之前我把現(xiàn)有上位機程序里所有跟FPGA有關(guān)的調(diào)用整理成了一條完整鏈路。最小調(diào)用鏈路大概是下面這樣枚舉設(shè)備拿到設(shè)備序列號列表。打開指定序列號的設(shè)備。如果固件不在Flash里就下載bit流文件到FPGA。讀取固件版本號等握手寄存器確認(rèn)固件已經(jīng)運行。寫采集控制寄存器啟動采集。通過批量傳輸端點讀回數(shù)據(jù)。停止采集關(guān)閉設(shè)備。這條鏈路看著簡單實際驗證時就會發(fā)現(xiàn)很多隱含動作。老SDK的設(shè)備枚舉返回的是一串字符串新SDK返回的是結(jié)構(gòu)體加索引兩者之間的對應(yīng)不是簡單的類型替換。固件版本這個動作也不僅僅是“讀0x10寄存器”因為新SDK可能要求在讀取之前先發(fā)一個同步命令。所以我在動手前做了一張“調(diào)用場景清單”把這條鏈路拆成六個業(yè)務(wù)場景初始化與枚舉、打開與關(guān)閉、固件配置、寄存器訪問、批量數(shù)據(jù)收發(fā)、錯誤處理。每個場景都標(biāo)注出老SDK的一份代碼路徑和新SDK應(yīng)有的對應(yīng)路徑。這張清單后來成了映射表的底稿也是回歸測試用例的來源。2.2 核心API對應(yīng)關(guān)系表映射表不需要覆蓋SDK的所有函數(shù)只需要覆蓋項目實際用到的部分。我們項目里用到的核心能力大概二十個我選其中最有代表性的放在下面功能層面老SDK接口新SDK接口需要重點關(guān)注的差異枚舉設(shè)備A_Enumerate()B_FindAll()序列號的格式與排序策略不同打開設(shè)備A_Open(serial)B_Open(index)一個用序列號字符串一個用索引號下載固件A_Configure(bitfile)B_LoadFirmware()新SDK不支持直接給bitfile需要先讀入內(nèi)存讀寄存器A_ReadRegister(addr, val)B_RegRead(addr, val)地址位寬和訪問對齊要求不同寫寄存器A_WriteRegister(addr, val)B_RegWrite(addr, val)寫后可能需要流水線同步批量寫A_PipeOut(ep, buf, len)B_BulkWrite(ep, buf, len)緩沖區(qū)對齊要求和超時語義不同批量讀A_PipeIn(ep, buf, len)B_BulkRead(ep, buf, len)一次請求中允許接收的數(shù)據(jù)量上限不同查詢錯誤A_GetLastError()B_ErrorString()錯誤碼體系完全不對應(yīng)必須包一層翻譯建這張表時最大的收獲是不要把老SDK的調(diào)用習(xí)慣帶到新SDK里去。比如老SDK里寫寄存器之前通常要調(diào)用一個“同步”函數(shù)新SDK沒有這個概念但新SDK要求所有寄存器寫入都帶一個明確的地址偏移不能直接傳邏輯地址。這些差異靠人肉記很容易漏落到表格里之后每個適配函數(shù)在實現(xiàn)前都能先找到對應(yīng)關(guān)系。3. 遷移落地的三步走分層、適配、逐模塊替換3.1 先定義自己的統(tǒng)一控制接口既然決定走適配層路線第一件事就是把統(tǒng)一接口設(shè)計出來。這個接口不應(yīng)該照著任何一家SDK的函數(shù)來而應(yīng)該照著項目業(yè)務(wù)來。我們的業(yè)務(wù)需求是上位機需要能夠打開一臺設(shè)備下載固件讀寫寄存器批量收數(shù)據(jù)。于是接口長這樣class IFpgaControl { public: virtual ~IFpgaControl() default; virtual bool OpenSerial(const std::string serial) 0; virtual void Close() 0; virtual bool Configure(const std::string bitFile) 0; virtual bool WriteRegister(uint32_t addr, uint32_t value) 0; virtual bool ReadRegister(uint32_t addr, uint32_t* value) 0; virtual bool BulkWrite(uint8_t endpoint, const void* data, size_t size) 0; virtual bool BulkRead(uint8_t endpoint, void* data, size_t size) 0; virtual const FpgaError GetLastError() const 0; virtual bool IsConnected() const 0; };這里有一個很容易踩的坑接口設(shè)計不要太厚不要一上來就想覆蓋SDK的所有能力。比如老SDK支持好幾種握手協(xié)議、支持通過寄存器動態(tài)改管腳電平新SDK也有類似功能但項目根本用不到。把用不到的功能塞進接口會讓每個適配器都背上沉重的實現(xiàn)負(fù)擔(dān)。我們只需要把現(xiàn)在和未來半年內(nèi)確定要用的能力放進來剩下的可以通過擴展接口再加。配套的錯誤信息結(jié)構(gòu)體我定義為struct FpgaError { bool hasError false; int32_t code 0; std::string message; };這個結(jié)構(gòu)體統(tǒng)一承載所有底層錯誤不管老SDK返回的是整型錯誤碼還是新SDK返回的是錯誤文本都在適配層里轉(zhuǎn)換好。上層業(yè)務(wù)不需要知道底層是哪家SDK。3.2 舊SDK適配器把A的調(diào)用包起來統(tǒng)一接口定義好之后先寫老SDK的適配器。這一步很有價值因為老SDK是已經(jīng)跑通的用它來驗證接口設(shè)計是否合理最省事。class AdapterOldSdk : public IFpgaControl { public: ~AdapterOldSdk() override { Close(); } bool OpenSerial(const std::string serial) override { uint32_t count 0; if (!A_GetDeviceCount(count) || count 0) { error_ { true, 0, no device found }; return false; } for (uint32_t i 0; i count; i) { char buf[64] {0}; if (A_GetDeviceSerial(i, buf, sizeof(buf)) serial buf) { device_ A_Open(buf); return device_ ! nullptr; } } error_ { true, 0, serial not found }; return false; } void Close() override { if (device_) { A_Close(device_); device_ nullptr; } } bool Configure(const std::string bitFile) override { if (!device_) return false; if (!A_Configure(device_, bitFile.c_str())) { error_ { true, A_GetLastError(device_), configure failed }; return false; } return true; } bool WriteRegister(uint32_t addr, uint32_t value) override { if (!device_) return false; if (!A_WriteRegister(device_, addr, value)) { error_ { true, A_GetLastError(device_), write reg failed }; return false; } return true; } bool BulkRead(uint8_t endpoint, void* data, size_t size) override { uint32_t transferred 0; bool ok A_PipeIn(device_, endpoint, data, (uint32_t)size, transferred, 2000); if (!ok || transferred ! size) { error_ { true, A_GetLastError(device_), bulk read failed }; return false; } return true; } const FpgaError GetLastError() const override { return error_; } bool IsConnected() const override { return device_ ! nullptr; } private: void* device_ nullptr; FpgaError error_{}; };寫老SDK適配器時確實會有一種“接口應(yīng)該有幾個參數(shù)”的糾結(jié)。比如老SDK的塊讀取函數(shù)需要傳入超時參數(shù)統(tǒng)一接口里要不要暴露超時我最后的做法是不暴露在適配器內(nèi)部給一個保守的默認(rèn)值。原因是上層業(yè)務(wù)大多不需要單獨控制超時真要控制超時是另外的接口設(shè)計問題不能讓每個調(diào)用點都背著參數(shù)。3.3 新SDK適配器別在老適配器上打補丁老適配器跑通之后新SDK的適配器就好寫了因為它要實現(xiàn)同樣的語義。很多人會在這一步偷懶想著在老適配器里加幾個#ifdef或者復(fù)制一份出來改成新調(diào)用。這兩種做法我都試過最終結(jié)論是老老實實新建一個類別在老適配器上打補丁。新SDK適配器的核心代碼長這樣class AdapterNewSdk : public IFpgaControl { public: ~AdapterNewSdk() override { Close(); } bool OpenSerial(const std::string serial) override { B_DeviceInfo info; uint32_t count 0; if (!B_FindAll(info, count) || count 0) { error_ { true, 0, no device found }; return false; } for (uint32_t i 0; i count; i) { if (serial std::string(info[i].serialNumber)) { handle_ B_Open(i, B_OPEN_FLAG_EXCLUSIVE); return handle_ 0; } } error_ { true, 0, serial not found }; return false; } void Close() override { if (handle_ 0) { B_Close(handle_); handle_ -1; } } bool Configure(const std::string bitFile) override { std::vectoruint8_t raw ReadFileAsBytes(bitFile); if (raw.empty()) return false; if (!B_LoadFirmware(handle_, raw.data(), raw.size())) { error_ { true, B_ErrorCode(handle_), firmware load failed }; return false; } return true; } bool WriteRegister(uint32_t addr, uint32_t value) override { if (addr 0x03) { error_ { true, 0, address should be 4-byte aligned }; return false; } if (!B_RegWrite(handle_, addr, value)) { error_ { true, B_ErrorCode(handle_), reg write failed }; return false; } return true; } bool BulkWrite(uint8_t endpoint, const void* data, size_t size) override { if (size % 16 ! 0) { error_ { true, 0, bulk size must be multiple of 16 }; return false; } uint32_t written 0; bool ok B_BulkWrite(handle_, endpoint, data, (uint32_t)size, written, 5000); if (!ok || written ! size) { error_ { true, B_ErrorCode(handle_), bulk write failed }; return false; } return true; } private: int32_t handle_ -1; FpgaError error_{}; };我在新適配器里加了幾個老適配器沒有的檢查比如寄存器地址必須4字節(jié)對齊、批量大小必須是16的整數(shù)倍。這些檢查來自新SDK固件的約束條件不是我想當(dāng)然加的。有一次我在新SDK上直接傳了一個奇數(shù)大小的緩沖給批量寫接口返回錯誤碼也很正常但FPGA那邊收到的數(shù)據(jù)整體錯位了兩字節(jié)。后來翻了固件源碼才發(fā)現(xiàn)新SDK的驅(qū)動內(nèi)核默認(rèn)把所有請求按整塊處理非對齊長度會被靜默處理成對齊值不會提示錯誤。新適配器剛寫好的時候不建議接入業(yè)務(wù)。先寫一個小測試程序直接調(diào)用新適配器的OpenSerial、Configure、WriteRegister、ReadRegister確認(rèn)能跑通最簡單的“寫一個寄存器再讀回來”流程。這一步通過之后再把它接到工廠方法里替換掉老適配器。3.4 業(yè)務(wù)層替換策略水管全換水龍頭不動適配器寫完之后業(yè)務(wù)層的替換其實是最簡單的。設(shè)計一個工廠函數(shù)std::unique_ptrIFpgaControl CreateControlDevice(DeviceKind kind) { switch (kind) { case DeviceKind::OldVendor: return std::make_uniqueAdapterOldSdk(); case DeviceKind::NewVendor: return std::make_uniqueAdapterNewSdk(); default: return nullptr; } }業(yè)務(wù)代碼只需要保證自己依賴的是IFpgaControl*指針不要直接依賴AdapterNewSdk內(nèi)部成員。初始化的地方從這一句std::unique_ptrIFpgaControl fpga CreateControlDevice(DeviceKind::OldVendor);改成std::unique_ptrIFpgaControl fpga CreateControlDevice(DeviceKind::NewVendor);然后把編譯錯誤一個個修掉絕大部分錯誤都是因為某個業(yè)務(wù)函數(shù)還在用老的裸調(diào)用。這個時候能明顯感受到適配層的好處修編譯錯誤是機械工不會出現(xiàn)“改完一處之后另一處設(shè)備狀態(tài)丟失”的問題。整個替換過程我分了三個批次推進。第一批只替換設(shè)備打開、關(guān)閉、握手保證程序能跑起來顯示“設(shè)備已連接”第二批替換寄存器讀寫第三批替換批量數(shù)據(jù)傳輸同時跑回環(huán)測試。每批都單獨提交代碼評審時目標(biāo)明確出了問題也能很快定位。4. 遷移過程中的真實踩坑記錄4.1 管線下載失敗不能只看返回碼第一個大坑出現(xiàn)在修改固件下載邏輯時。老適配器調(diào)用A_Configure把bitfile一次下載進去下載完畢之后FPGA自動進入運行狀態(tài)后續(xù)直接讀寫寄存器就能通。新SDK的B_LoadFirmware函數(shù)也是類似功能但下載完之后馬上讀寄存器發(fā)現(xiàn)讀回來的是全零。排查了很久才發(fā)現(xiàn)新SDK的下載函數(shù)只負(fù)責(zé)把bit流寫入FPGA并不會等待FPGA內(nèi)部的上電復(fù)位完成。老SDK在下載完之后內(nèi)部還有一步等待至少會打印出固件ID才能返回成功。新SDK則是下載命令發(fā)出后就返回如果立刻讀寄存器FPGA還在加載階段。這里得到的教訓(xùn)是下載完固件之后不要直接信任成功返回必須有一個“固件握手”動作。我在新適配器里添加了下載完成后的重試循環(huán)最多等2秒讀固件版本寄存器直到讀出非零值。這個動作不能放在業(yè)務(wù)代碼里否則每個用適配器的人都要記得。4.2 塊傳輸錯位對齊不是玄學(xué)是協(xié)議批量傳輸?shù)膶R問題是遷移中最隱蔽的坑。老SDK的批量寫函數(shù)對待緩沖區(qū)大小非常寬松傳500字節(jié)、傳512字節(jié)都能跑。新SDK底層驅(qū)動按塊設(shè)備處理緩沖區(qū)大小必須是16的整數(shù)倍而且緩沖區(qū)的內(nèi)存地址最好也做對齊。我們的業(yè)務(wù)里有幾種命令長度不是16倍數(shù)比如一條控制命令恰好是42字節(jié)。老SDK里直接調(diào)用A_PipeOut沒問題新SDK里寫42字節(jié)驅(qū)動返回成功但多包了14字節(jié)的空白填充FPGA那邊的狀態(tài)機把這個命令當(dāng)成兩條消息解析直接亂掉。解決辦法是在適配層加一層打包邏輯如果字節(jié)長度不是16的整數(shù)倍分配一個對齊后的緩沖前端填充原始數(shù)據(jù)剩余部分填0再告訴FPGA邏輯“實際有效長度”。這個邏輯必須和固件約定好固件端也要根據(jù)同樣的規(guī)則解包。如果不改固件也可以讓FPGA端自己按16字節(jié)對齊?？傊畬R規(guī)則必須是兩端共同確認(rèn)的協(xié)議不是適配器單方面能定的。4.3 回調(diào)線程里干活輕則超時重則死鎖新SDK的批量讀取支持兩種模式同步阻塞和異步回調(diào)。我們最開始圖省事直接用異步回調(diào)模式在回調(diào)函數(shù)里把數(shù)據(jù)搬到應(yīng)用緩沖區(qū)順便更新UI狀態(tài)。結(jié)果程序跑一會兒就出現(xiàn)讀超時嚴(yán)重時整個上位機界面卡死。問題不在回調(diào)本身而在回調(diào)線程里做了太多事情?；卣{(diào)函數(shù)是SDK內(nèi)部驅(qū)動線程調(diào)用的如果我在里面加鎖保護共享數(shù)據(jù)而主線程同時也在等待這次讀取完成就會形成死鎖。正確做法是回調(diào)只做一件事——把數(shù)據(jù)推到一個無鎖隊列里然后讓業(yè)務(wù)工作線程去隊列里取數(shù)據(jù)。這樣回調(diào)線程永遠(yuǎn)不被阻塞業(yè)務(wù)線程有自己的節(jié)奏處理數(shù)據(jù)。這里補充一個實測經(jīng)驗異步回調(diào)模式下隊列長度要有上限。如果采集卡每毫秒產(chǎn)生一塊數(shù)據(jù)而業(yè)務(wù)層處理速度跟不上隊列會無限膨脹最終內(nèi)存暴漲。我給隊列加了最大深度限制滿了就直接丟包并統(tǒng)計丟包計數(shù)器寧可丟包也不能把系統(tǒng)拖死。4.4 超時參數(shù)不能拿來就用要重新標(biāo)定老SDK的很多接口有默認(rèn)超時參數(shù)1000毫秒是常見的。新SDK有些接口也有默認(rèn)值有些需要顯式傳入。我在遷移時第一版直接把老SDK的2000毫秒搬過來結(jié)果固件下載經(jīng)常超時因為新SDK的固件下載函數(shù)要先把1MB多一點的bit文件從用戶態(tài)拷貝到內(nèi)核態(tài)再通過USB控制器下發(fā)大文件傳輸需要的時間遠(yuǎn)超2000毫秒。不同操作的超時需求差異很大。寄存器讀寫這種短事務(wù)500毫秒都算寬裕批量傳輸則要基于數(shù)據(jù)量估算時間比如USB 3.0實際有效帶寬約300MB/s傳輸1MB數(shù)據(jù)大約需要3.5毫秒但驅(qū)動握手、端點調(diào)度、FPGA處理都可能增加額外延遲所以我把批量傳輸?shù)某瑫r設(shè)置為至少10毫秒基數(shù)加上按數(shù)據(jù)量線性增長的部分。固件下載我干脆設(shè)成了30秒因為還要考慮讀SD卡鏡像、校驗和等步驟。超時不應(yīng)該寫死應(yīng)該做成適配器的配置項至少支持從配置文件讀取。比如固件文件變大了、USB線質(zhì)量變差了可能需要調(diào)高閾值。4.5 熱拔插之后句柄說沒就沒設(shè)備熱拔插是采集卡項目里一定會遇到的場景。老SDK對熱拔插處理得比較好設(shè)備拔掉之后API調(diào)用會直接返回錯誤重插之后枚舉列表會自然更新。新SDK在這方面差一些拔掉設(shè)備后已經(jīng)打開的句柄仍然是“看起來有效”的狀態(tài)但任何讀寫操作都會失敗重插之后如果不再枚舉一次句柄也不會自動恢復(fù)。這個問題的根因是兩邊驅(qū)動的事件通知機制不同。老SDK會在設(shè)備拔插時主動觸發(fā)一個系統(tǒng)事件新SDK則依賴應(yīng)用層周期性輪詢。我的做法是寫了一個設(shè)備健康檢查線程每3秒調(diào)用一次B_CheckHandle(handle_)判斷設(shè)備是否還在線。如果檢查失敗自動關(guān)閉舊句柄并觸發(fā)重連邏輯重連時重新枚舉設(shè)備列表。這個健康檢查邏輯必須放在適配層里業(yè)務(wù)層不需要知道設(shè)備在不在它只需要在調(diào)用任何接口失敗之后拿到一個明確的錯誤然后決定是否重新打開設(shè)備。4.6 線程安全先串行化再談并發(fā)適配器要支持的并發(fā)訪問模式往往被忽視。老SDK內(nèi)部做了全局鎖所有API調(diào)用天然串行化同一時間只允許一個線程訪問設(shè)備。新SDK雖然線程安全但不同接口之間并不保證原子性比如一個線程正在下載固件另一個線程同時寫寄存器可能會出現(xiàn)不可預(yù)期的狀態(tài)。遷移一開始我就踩了一次這個坑業(yè)務(wù)層有采集線程在持續(xù)批量讀數(shù)據(jù)UI線程偶爾會寫寄存器調(diào)整增益。在老SDK下這個模式跑了一年多都沒事切到新SDK之后寫寄存器偶發(fā)失敗并且伴隨采集數(shù)據(jù)掉幀。解決辦法是在適配器內(nèi)部增加一個互斥鎖所有公開接口都先拿鎖再執(zhí)行底層調(diào)用。這個鎖粒度雖然粗但保證了一次完整操作不會被其他線程打斷。如果未來業(yè)務(wù)需要更細(xì)的并發(fā)比如同時讀多個端點再針對具體端點升級為讀寫鎖。先串行化是遷移階段最保險的做法性能上損失很小但穩(wěn)定性的收益非常大。5. 回歸測試怎么做遷移能不能交差的標(biāo)準(zhǔn)5.1 功能回歸用例清單適配層寫完、業(yè)務(wù)替換完之后最容易出現(xiàn)的錯覺是“程序能跑就說明遷移成功了”。我這邊踩過一次深淺不定的坑程序能跑只是表面功能細(xì)節(jié)可能還是錯的。于是這次我把回歸測試用例做成了一張表格每一條都對應(yīng)一個可觀測的檢查點。用例編號測試內(nèi)容操作步驟通過標(biāo)準(zhǔn)TC01設(shè)備枚舉插上設(shè)備后調(diào)用枚舉接口能列出正確序列號TC02固件下載下載標(biāo)準(zhǔn)bit文件返回成功且固件版本寄存器非零TC03寄存器讀寫掃描寫入0x5A5A5A5A到不同地址并讀回讀寫結(jié)果完全一致TC04批量數(shù)據(jù)寫讀回環(huán)FPGA內(nèi)部將寫數(shù)據(jù)回環(huán)返回讀出內(nèi)容與寫入內(nèi)容完全一致TC05多端點并發(fā)兩個端點同時進行批量傳輸兩邊數(shù)據(jù)均無錯位和丟包TC06異常拔插數(shù)據(jù)傳輸中拔出設(shè)備再插回上位機能檢測到掉線并完成重連TC07長時間運行持續(xù)采集72小時無死機、無數(shù)據(jù)中斷、無內(nèi)存增長TC04的回環(huán)測試是最重要的一道關(guān)卡。我在FPGA邏輯里加了一個簡單的FIFO回環(huán)模塊上位機往端點A寫入什么FPGA就從端點B返回什么。這個測試能同時驗證塊傳輸?shù)亩它c映射、數(shù)據(jù)寬度、字節(jié)序和打包邏輯。如果回環(huán)測試通過批量傳輸這塊基本就穩(wěn)了。5.2 性能和穩(wěn)定性指標(biāo)怎么定功能回歸通過后還需要對比性能指標(biāo)否則系統(tǒng)上線后遇到吞吐量不足的問題會非常被動。我定的指標(biāo)很簡單回環(huán)測試連續(xù)傳輸100MB數(shù)據(jù)統(tǒng)計平均吞吐量分別記錄遷移前老SDK的數(shù)據(jù)、遷移后新SDK的數(shù)據(jù)要求新SDK的吞吐不低于老SDK的95%。這個5%的容差不是拍腦袋想出來的USB協(xié)議本身的調(diào)度和驅(qū)動層緩沖策略會帶來微小波動真正的性能瓶頸在FPGA處理邏輯和上位機應(yīng)用層如果一個SDK的性能差到兩位數(shù)百分比說明驅(qū)動或固件配置有問題。CPU占用也要測。老SDK的塊傳輸在驅(qū)動層用了零拷貝新SDK在部分接口上有一次額外的內(nèi)存拷貝。實測下來新SDK在傳輸相同數(shù)據(jù)量時CPU占用高出約5個百分點可以接受但如果不再做適配層緩沖很可能高出更多。穩(wěn)定性測試則需要跑足夠長時間。USB接口設(shè)備最怕出現(xiàn)運行一段時間后句柄失效、驅(qū)動棧異常、帶寬被莫名占用的現(xiàn)象。我跑了三天三夜連續(xù)采集日志里沒有出現(xiàn)一次傳輸錯誤基本可以確認(rèn)適配層的鎖設(shè)計和超時策略是靠譜的。5.3 自動化回歸讓遷移結(jié)果可重復(fù)手工回歸做了兩輪之后我把測試用例腳本化。腳本不需要復(fù)雜主要就是把上面的操作步驟串起來記錄每個用例的執(zhí)行結(jié)果和耗時。自動化之后每次修改適配器代碼都能在一個小時內(nèi)跑完全部回歸。自動化回歸里有一個額外動作值得提一下每次跑測試之前強制重新枚舉設(shè)備并重新下載固件。這樣能確保每次測試的初始狀態(tài)一致不會出現(xiàn)上一次測試殘留的狀態(tài)影響結(jié)論。我遇到過最典型的例子是某次寄存器讀寫測試失敗是因為上一次用例把設(shè)備狀態(tài)寄存器改成了錯誤值沒有復(fù)位就接著跑下一個用例結(jié)果誤判成適配器有bug。6. 經(jīng)驗總結(jié)遷移過程中最有用的幾個習(xí)慣6.1 先梳理協(xié)議鏈路再寫適配代碼如果讓我重新做一次這個遷移我一定會更早在協(xié)議層面花時間。所謂協(xié)議鏈路就是從FPGA的寄存器地址表、命令碼表、端點定義出發(fā)把上位機每個操作和固件里的某個邏輯單元對應(yīng)起來。拿寄存器來說FPGA可能定義了0x00狀態(tài)寄存器、0x04控制寄存器、0x08數(shù)據(jù)長度寄存器但兩家SDK訪問這些寄存器時的地址變換不一樣。老SDK可能要求傳入物理地址新SDK要求傳入虛擬地址差一個偏移讀出來的數(shù)據(jù)就對不上。協(xié)議梳理最好的產(chǎn)出是一張“寄存器地址對照表”左邊寫FPGA邏輯里的寄存器名和地址右邊寫兩個SDK調(diào)用時實際傳的參數(shù)。這張表比代碼注釋可靠得多也方便固件工程師參與評審。6.2 第一個適配器版本不要帶過多功能新手寫適配器容易貪全覺得一次性把SDK所有函數(shù)都包進去才叫“適配”。我建議第一個版本只實現(xiàn)最小閉環(huán)枚舉、打開、下載、一個寄存器讀寫、一個批量傳輸。先把這條鏈路跑通證明適配器架構(gòu)可行再逐批增加功能。最小閉環(huán)還有一個額外價值可以盡早驗證新SDK本身在這套硬件上的穩(wěn)定性。如果新SDK連最小回環(huán)都跑不穩(wěn)那就應(yīng)該先解決硬件和驅(qū)動問題而不是繼續(xù)往上疊功能。我在這個項目里第一次用新SDK時就發(fā)現(xiàn)一個驅(qū)動bug在極小概率下枚舉列表會返回重復(fù)設(shè)備如果我一上來就寫滿所有功能這個問題會被淹沒在其他報錯里排查會痛苦得多。6.3 評審不能只盯上位機要帶著固件一起看代碼遷移通常被認(rèn)為是上位機的事但實際上它牽動的是整個系統(tǒng)。適配器怎么處理對齊、超時、下載后握手這些都需要固件工程師確認(rèn)。如果固件端的端點配置沒有根據(jù)SDK特性調(diào)整適配器寫得再對數(shù)據(jù)還是對不上。因此遷移適配器的代碼評審我堅持拉上固件工程師一起看。評審重點不在于代碼風(fēng)格而在于適配器里的每個數(shù)據(jù)操作是不是和FPGA頂層模塊里的對應(yīng)端口一致固件下載之后的握手寄存器是不是真的已經(jīng)實現(xiàn)了批量傳輸端點的最大包長是不是和適配器的分塊策略匹配。這三項確認(rèn)完代碼評審才算有意義。6.4 制作一張“遷移對照卡”后續(xù)維護全靠它最后分享一個小技巧。我把這次遷移過程中的API映射、寄存器地址變換、超時參數(shù)、對齊規(guī)則、錯誤翻譯表全部整理到了一張紙上掛在工位旁邊。這張“遷移對照卡”不僅遷移期間用后續(xù)雙版本維護也長期在用。每有新需求涉及底層數(shù)據(jù)通路我先在對照卡上標(biāo)出兩個SDK的對應(yīng)端點、包長度和超時語義再討論固件側(cè)怎么改。幾次下來團隊里新來的同事也能自己動手做后續(xù)適配不用每次都要找我核對一遍底層細(xì)節(jié)?；氐介_頭說的那句話換底層通信庫不是簡單的API替換。真正決定這次遷移成敗的是邊界畫得清不清楚、協(xié)議梳理得完不完整、回歸測得到不到位。把這些基礎(chǔ)工作做好換哪個SDK都只是適配器里的一段普通代碼。