1. 為什么xsa文件更新是Vitis開發(fā)中的高頻痛點做過ZYNQ裸機(jī)開發(fā)或者Linux驅(qū)動開發(fā)的朋友大概率都經(jīng)歷過這樣的場景硬件同事在Vivado里改了一個GPIO引腳分配或者調(diào)整了QSPI Flash的時鐘頻率重新導(dǎo)出了xsa文件發(fā)給你你興沖沖地在Vitis里點了一下“Update Hardware Specification”結(jié)果工程直接飄紅——BSP編譯報錯、地址映射對不上、甚至整個工程結(jié)構(gòu)都亂了。更讓人頭疼的是有時候更新完xsa之后原來能跑的代碼突然跑不起來了串口沒有任何輸出JTAG也連不上目標(biāo)芯片。這個問題在ZYNQ開發(fā)中非常普遍尤其是涉及QSPI Flash固化、DDR配置變更、外設(shè)地址重映射的時候。很多人第一反應(yīng)是“刪掉工程重新建一個”但這樣做意味著之前所有的BSP配置、庫文件路徑、編譯選項都要重新來一遍費時費力還容易遺漏。其實Vitis本身提供了比較完善的xsa更新機(jī)制只是很多人沒有搞清楚它的工作邏輯導(dǎo)致更新過程中出現(xiàn)各種意外。這篇文章就是圍繞“如何快速、安全地更新xsa文件”這個核心問題展開的。我會從Vitis工程的底層結(jié)構(gòu)講起說明xsa文件到底影響了工程的哪些部分然后給出完整的更新流程和參數(shù)配置方法最后用一個QSPI Flash固化的實際案例來演示整個操作過程。不管你是剛接觸ZYNQ的新手還是已經(jīng)做過幾個項目的老手應(yīng)該都能從中找到一些之前踩過但沒搞明白的坑。2. Vitis工程結(jié)構(gòu)與xsa文件的關(guān)聯(lián)機(jī)制2.1 xsa文件里到底裝了什么xsa是Xilinx Software Archive的縮寫本質(zhì)上是一個壓縮包里面包含了Vivado硬件設(shè)計的所有導(dǎo)出信息。你可以用解壓工具直接打開它會看到里面有幾個關(guān)鍵文件.hwh文件是硬件描述的核心記錄了PS端的配置參數(shù)、PL端的IP核信息、地址映射關(guān)系、中斷分配等.xml文件描述了外設(shè)的寄存器地址和參數(shù)還有bitstream文件如果導(dǎo)出時勾選了包含bitstream。對于Vitis工程來說最重要的就是.hwh文件。Vitis在創(chuàng)建平臺工程Platform Project的時候會解析這個文件生成對應(yīng)的硬件平臺描述。BSPBoard Support Package再基于平臺描述生成xparameters.h、xparameters_ps.h等頭文件以及各種驅(qū)動配置。所以當(dāng)你更新xsa時本質(zhì)上是在更新這些底層描述信息而BSP和應(yīng)用程序都需要重新適配。2.2 平臺工程、BSP與應(yīng)用的依賴鏈Vitis的工程結(jié)構(gòu)是三層依賴平臺工程 → BSP → 應(yīng)用工程。平臺工程直接對應(yīng)xsa文件BSP依賴平臺工程應(yīng)用工程依賴BSP。這個依賴鏈意味著xsa的變更會沿著鏈條逐級傳遞。如果你只更新了平臺工程但沒有重新編譯BSP那么應(yīng)用工程用的還是舊的硬件參數(shù)就會出現(xiàn)“代碼里寫的地址和實際硬件對不上”的情況。我見過很多人更新xsa之后直接編譯應(yīng)用工程然后抱怨“明明更新了硬件為什么還是報錯”。原因就在這里——BSP沒有重新生成。正確的做法是更新平臺工程中的xsa → 重新編譯平臺工程 → 重新編譯BSP → 最后編譯應(yīng)用工程。這個順序不能亂亂了就會出各種莫名其妙的問題。2.3 哪些xsa變更會導(dǎo)致工程報錯不是所有的xsa更新都會引發(fā)問題。根據(jù)我的經(jīng)驗以下幾類變更最容易導(dǎo)致工程報錯變更類型影響范圍典型報錯PS端外設(shè)地址變更BSP頭文件、驅(qū)動配置xparameters.h中地址宏定義不匹配DDR配置變更FSBL、內(nèi)存映射啟動后DDR初始化失敗程序跑飛QSPI時鐘或引腳變更Flash驅(qū)動、固化腳本Flash讀寫失敗固化后無法啟動中斷號重新分配中斷控制器驅(qū)動中斷無法觸發(fā)或觸發(fā)錯誤中斷PL端IP核增刪地址映射、驅(qū)動編譯時找不到符號定義其中QSPI相關(guān)的變更特別容易出問題因為QSPI Flash的固化涉及到FSBL、BOOT.bin的生成以及Flash控制器的初始化參數(shù)。如果xsa里QSPI的時鐘頻率改了但BSP沒有重新生成FSBL就會用舊的時鐘參數(shù)去初始化Flash結(jié)果就是讀寫超時或者數(shù)據(jù)校驗失敗。3. 更新xsa文件的完整操作流程3.1 準(zhǔn)備工作備份與版本確認(rèn)在動手更新之前有兩件事必須做。第一是備份當(dāng)前工程可以直接把整個workspace目錄復(fù)制一份或者用Git做一次commit。我個人的習(xí)慣是在workspace同級目錄下建一個backup文件夾每次更新xsa之前把整個工程目錄壓縮存檔。這樣做的好處是萬一更新過程中出現(xiàn)不可逆的錯誤可以快速回滾。第二是確認(rèn)Vivado和Vitis的版本匹配。xsa文件是向下兼容的但不向上兼容。也就是說Vivado 2022.1導(dǎo)出的xsa可以在Vitis 2022.1或更高版本中打開但不能在Vitis 2021.2中打開。如果你拿到的xsa是更新版本Vivado導(dǎo)出的而你的Vitis還是舊版本那更新一定會失敗。這種情況下只能升級Vitis沒有別的辦法。提示在Vitis中可以通過菜單欄 Help → About 查看當(dāng)前版本號。Vivado導(dǎo)出的xsa文件在解壓后的sysdef.xml中也會記錄生成版本可以用文本編輯器打開確認(rèn)。3.2 在Vitis中更新平臺工程的xsa打開Vitis在Project Explorer中找到你的平臺工程通常以_platform結(jié)尾右鍵點擊選擇“Update Hardware Specification”。在彈出的對話框中瀏覽到新的xsa文件路徑確認(rèn)后點擊OK。Vitis會自動解析新的xsa并更新平臺工程中的硬件描述。這一步看起來很簡單但有幾個細(xì)節(jié)需要注意。首先如果你的平臺工程之前包含了bitstream而新的xsa沒有包含bitstream更新后平臺工程會丟失bitstream信息。這種情況下需要手動在平臺工程的hw目錄下放入新的bitstream文件。其次如果新的xsa中PS端的配置發(fā)生了較大變化比如從ZYNQ 7020換到了ZYNQ 7045平臺工程可能需要重新創(chuàng)建直接更新會報錯。更新完成后建議打開平臺工程下的hw目錄檢查.hwh文件的修改時間是否已經(jīng)更新。如果時間沒變說明更新沒有生效需要重新操作一次。3.3 重新生成BSP的兩種方式BSP的重新生成有兩種方式各有適用場景。第一種是在Vitis中右鍵點擊BSP工程選擇“Re-generate BSP Sources”。這種方式會保留你之前對BSP的設(shè)置比如勾選了哪些庫、修改了哪些編譯選項只更新硬件相關(guān)的部分。適合xsa變更不大的情況。第二種是刪除舊的BSP工程重新創(chuàng)建一個新的BSP。這種方式適合xsa變更較大、或者BSP已經(jīng)出現(xiàn)無法修復(fù)的編譯錯誤的情況。重新創(chuàng)建BSP時需要重新勾選需要的庫比如xilffs、xilrsa、lwip等并重新配置編譯選項。雖然麻煩一些但能保證BSP的干凈和完整。我個人的建議是如果只是地址映射的小改動用第一種方式如果涉及DDR配置、QSPI控制器參數(shù)、中斷分配的變更直接用第二種方式重新建BSP省得后面出各種玄學(xué)問題。3.4 應(yīng)用工程的清理與重新編譯BSP更新完成后應(yīng)用工程需要做一次Clean和Rebuild。在Vitis中右鍵點擊應(yīng)用工程選擇“Clean Project”然后選擇“Build Project”。Clean的作用是刪除之前編譯生成的中間文件確保所有源文件都用新的BSP頭文件重新編譯。如果不做Clean直接Build有些文件可能因為時間戳的原因不會被重新編譯導(dǎo)致新舊頭文件混用出現(xiàn)難以排查的錯誤。Clean之后如果編譯報錯大概率是以下幾種原因一是代碼中直接使用了舊的地址宏定義需要手動更新二是鏈接腳本linker script中的內(nèi)存布局和新xsa不匹配需要修改lscript.ld文件三是某些驅(qū)動庫的版本和新BSP不兼容需要更新庫文件。4. QSPI Flash固化案例從xsa更新到成功啟動4.1 案例背景與硬件配置這個案例來自我最近做的一個ZYNQ 7020項目。硬件同事在Vivado中修改了QSPI Flash的時鐘配置從原來的50MHz改到了100MHz同時調(diào)整了QSPI引腳的驅(qū)動能力。修改后的xsa文件發(fā)過來我需要在Vitis中更新并重新生成用于QSPI固化的BOOT.bin最后通過JTAG燒寫到Flash中驗證。硬件配置如下ZYNQ 7020芯片QSPI Flash型號為W25Q256FV容量32MB四線QSPI模式。FSBL基于Vitis自帶的模板修改增加了QSPI初始化的打印信息。應(yīng)用程序是一個簡單的LED閃爍程序用來驗證啟動是否成功。4.2 更新xsa后的BSP配置檢查按照前面的流程更新完xsa并重新生成BSP后我打開了BSP工程下的xparameters.h文件搜索XPAR_XQSPIPS_0相關(guān)的宏定義。重點檢查了以下幾個參數(shù)#define XPAR_XQSPIPS_0_BASEADDR 0xE000D000 #define XPAR_XQSPIPS_0_DEVICE_ID 0 #define XPAR_XQSPIPS_0_QSPI_CLK_FREQ_HZ 100000000 #define XPAR_XQSPIPS_0_QSPI_MODE 2其中QSPI_CLK_FREQ_HZ已經(jīng)從50000000變成了100000000說明xsa更新生效了。QSPI_MODE為2表示四線模式和硬件設(shè)計一致。如果這里發(fā)現(xiàn)參數(shù)不對說明xsa更新沒有成功需要回到平臺工程重新操作。另外還需要檢查xparameters_ps.h中的DDR配置參數(shù)確保DDR的時鐘頻率和容量沒有變化。如果DDR配置變了FSBL中的DDR初始化代碼也需要相應(yīng)調(diào)整否則系統(tǒng)啟動后會在DDR初始化階段卡住。4.3 FSBL的修改與BOOT.bin生成FSBLFirst Stage Boot Loader是ZYNQ啟動過程中運(yùn)行的第一段代碼負(fù)責(zé)初始化PS端外設(shè)、配置DDR、加載bitstream和應(yīng)用程序。在QSPI固化場景中FSBL還需要初始化QSPI控制器以便從Flash中讀取后續(xù)的啟動鏡像。更新xsa后FSBL工程也需要重新編譯。我打開FSBL的main.c文件在InitQspi函數(shù)中增加了一行打印語句用來確認(rèn)QSPI的時鐘頻率xil_printf(QSPI Clock: %d Hz\r\n, XPAR_XQSPIPS_0_QSPI_CLK_FREQ_HZ);重新編譯FSBL后在Vitis中右鍵點擊FSBL工程選擇“Create Boot Image”。在彈出的對話框中依次添加FSBL.elf、bitstream.bit和應(yīng)用程序.elf輸出格式選擇BIN輸出路徑設(shè)置為工程目錄下的boot.bin。點擊Create后Vitis會自動調(diào)用bootgen工具生成BOOT.bin文件。注意如果xsa中包含了新的bitstream需要確保在Create Boot Image時使用的是最新的bitstream文件。Vitis有時會緩存舊的bitstream路徑需要手動瀏覽確認(rèn)。4.4 JTAG燒寫與啟動驗證BOOT.bin生成后通過JTAG燒寫到QSPI Flash中。在Vitis中點擊菜單欄 Xilinx → Program Flash在彈出的對話框中選擇BOOT.bin文件Flash類型選擇qspi_single偏移地址設(shè)置為0。點擊Program后Vitis會通過JTAG將BOOT.bin寫入Flash。燒寫完成后將開發(fā)板的啟動模式撥碼開關(guān)設(shè)置為QSPI啟動重新上電。如果一切正常串口會打印出FSBL的啟動信息包括QSPI時鐘頻率和DDR初始化結(jié)果然后應(yīng)用程序開始運(yùn)行LED開始閃爍。如果串口沒有任何輸出或者輸出亂碼說明啟動失敗。這時候需要檢查以下幾個方面一是BOOT.bin是否正確生成可以用bootgen的-read選項查看BOOT.bin的頭部信息二是QSPI Flash的引腳分配是否和硬件一致三是FSBL中的QSPI初始化代碼是否使用了正確的時鐘參數(shù)。5. 常見問題排查與避坑經(jīng)驗5.1 更新xsa后BSP編譯報錯的典型原因更新xsa后BSP編譯報錯是最常見的問題根據(jù)我的經(jīng)驗主要有以下幾種原因第一種是地址宏定義沖突。新的xsa中某個外設(shè)的基地址變了但BSP中還有舊的宏定義殘留。這種情況下需要手動刪除BSP工程下的include目錄然后重新生成BSP。Vitis有時不會自動清理舊的宏定義導(dǎo)致新舊定義同時存在編譯時就會報“宏重定義”的錯誤。第二種是驅(qū)動版本不匹配。新的xsa可能使用了更新版本的IP核而BSP中的驅(qū)動還是舊版本。這種情況下需要更新BSP中的驅(qū)動庫或者從Vitis的安裝目錄中拷貝最新的驅(qū)動文件到BSP的drivers目錄下。第三種是中斷號沖突。新的xsa中中斷分配發(fā)生了變化但BSP中的中斷控制器配置沒有更新。這種情況下需要檢查xparameters.h中的中斷號宏定義并確保應(yīng)用程序中的中斷注冊代碼使用了正確的宏。5.2 QSPI固化后無法啟動的排查思路QSPI固化后無法啟動是一個比較棘手的問題因為涉及到硬件、FSBL、BOOT.bin等多個環(huán)節(jié)。我通常按照以下順序排查首先確認(rèn)啟動模式設(shè)置是否正確。ZYNQ的啟動模式由MIO引腳的電平?jīng)Q定如果撥碼開關(guān)設(shè)置錯誤芯片會從JTAG或SD卡啟動而不是QSPI?？梢杂萌f用表測量MIO引腳的電平確認(rèn)和硬件設(shè)計一致。其次確認(rèn)BOOT.bin的頭部信息是否正確。用bootgen -read boot.bin命令可以查看BOOT.bin的頭部確認(rèn)FSBL的入口地址、bitstream的加載地址、應(yīng)用程序的加載地址是否和xsa中的內(nèi)存映射一致。如果地址不對說明Create Boot Image時的配置有誤。然后確認(rèn)QSPI Flash的讀寫是否正常。可以在FSBL中增加Flash讀寫測試代碼讀取Flash的ID號確認(rèn)Flash型號和硬件設(shè)計一致。如果讀不到ID說明QSPI控制器的初始化有問題需要檢查時鐘頻率、引腳分配和Flash的供電。最后確認(rèn)DDR初始化是否成功。如果DDR初始化失敗FSBL會在加載bitstream或應(yīng)用程序時卡住。可以在FSBL中增加DDR測試代碼向DDR的某個地址寫入數(shù)據(jù)再讀出來確認(rèn)DDR工作正常。5.3 避免工程報錯的日常習(xí)慣經(jīng)過多次踩坑我總結(jié)了幾條日常習(xí)慣可以大大減少xsa更新導(dǎo)致的工程報錯每次更新xsa前先備份工程用Git或壓縮包都行確保可以回滾。更新xsa后先檢查xparameters.h確認(rèn)關(guān)鍵參數(shù)地址、時鐘、中斷號已經(jīng)更新。BSP重新生成后先編譯BSP確認(rèn)BSP本身沒有錯誤再編譯應(yīng)用工程。應(yīng)用工程編譯前先Clean避免新舊頭文件混用。QSPI固化前先用JTAG下載驗證確認(rèn)應(yīng)用程序在JTAG模式下能正常運(yùn)行再生成BOOT.bin固化。保留一份可用的BOOT.bin如果新的BOOT.bin啟動失敗可以用舊的BOOT.bin恢復(fù)。5.4 常見問題速查表問題現(xiàn)象可能原因解決方法BSP編譯報“宏重定義”舊宏定義殘留刪除BSP的include目錄重新生成應(yīng)用工程編譯報“找不到符號”BSP未重新編譯重新編譯BSPClean應(yīng)用工程JTAG下載后無輸出DDR配置不匹配檢查xparameters_ps.h中的DDR參數(shù)QSPI固化后無法啟動BOOT.bin地址錯誤用bootgen -read檢查頭部信息Flash讀寫超時QSPI時鐘配置錯誤檢查xparameters.h中的時鐘頻率中斷無法觸發(fā)中斷號不匹配檢查xparameters.h中的中斷宏定義6. 關(guān)于xsa更新的一些個人體會我在實際項目中發(fā)現(xiàn)xsa更新這件事最怕的不是操作復(fù)雜而是“想當(dāng)然”。很多人覺得更新xsa就是點一下按鈕的事結(jié)果忽略了BSP的重新生成和應(yīng)用的Clean最后花幾個小時排查一個本可以避免的問題。還有一種情況是硬件同事改了xsa但沒有通知軟件同事軟件同事在不知情的情況下繼續(xù)用舊工程調(diào)試結(jié)果怎么調(diào)都不對。我的建議是把xsa更新當(dāng)成一個正式的流程來對待。每次收到新的xsa先確認(rèn)版本和變更內(nèi)容然后按照“備份→更新平臺→重新生成BSP→Clean應(yīng)用→編譯驗證”的順序操作。如果涉及QSPI固化還要額外驗證BOOT.bin的生成和燒寫。這套流程看起來繁瑣但比起出問題后再排查效率要高得多。另外Vitis的版本更新也會影響xsa的兼容性。如果你從Vitis 2021.2升級到了2022.1舊的平臺工程可能需要重新創(chuàng)建因為Vitis 2022.1對平臺工程的內(nèi)部結(jié)構(gòu)做了一些調(diào)整。這種情況下直接更新xsa可能會報錯需要新建平臺工程并重新導(dǎo)入xsa。雖然麻煩但能避免后續(xù)更多的兼容性問題。最后分享一個小技巧在Vitis中可以用“Compare with”功能對比新舊xparameters.h文件快速找出哪些參數(shù)發(fā)生了變化。具體操作是右鍵點擊xparameters.h選擇“Compare With → Local History”Vitis會顯示文件的修改歷史方便定位變更點。這個功能在排查xsa更新導(dǎo)致的問題時特別有用。