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