教學課程:建立及偵錯合作夥伴應用程式
此教學課程示範如何建置和偵錯包含高階應用程式和支援即時應用程式的範例專案,其中兩個應用程式會在高階 A7 核心和即時 M4 核心之間通訊。 如需高階應用程式和支援即時應用程式的基本資訊,請參閱 Azure 球體應用程式概觀 。
在此教學課程中,您將瞭解如何:
- 安裝 GNU Arm 工具鏈
- 設定硬體以顯示輸出
- 啟用開發與偵錯
- 複製 Azure 球體樣本 repo
- 啟動終端模擬器以檢視輸出
- 建立、執行及偵錯一對合作夥伴應用程式
重要
這些指示假設您使用的硬體遵循 MT3620 參考面板設計 (RDB) 硬體,例如來自 Seeed Studio 的 MT3620 Dev Kit。 如果您使用不同的 Azure 球體硬體,請參閱製造商的檔,以瞭解 UART 是否公開以及如何存取。 您可能需要 設定硬體以不同方式顯示輸出 ,並更新範例程式代碼和app_manifest.json檔案的 Uart 功能 變數,以使用不同的 UART。
先決條件
- 安裝 適用於 Windows 或 Linux 的 CMake 和 Ninja。
- 安裝適用於 Windows 或 Linux的 Visual Studio Code。
- 安裝 適用於 Windows 或 Linux 的 CMake 和 Ninja。
- 安裝適用於 Windows 或 Linux 的 Azure 球體 SDK。
- 選擇目錄並宣告您的裝置。
- 設定網路功能並更新裝置作業系統。
安裝 GNU Arm Embedded Toolchain
若要在 Arm 開發人員網站上安裝工具鏈,請尋找 GNU Arm Embedded Toolchain (arm-none-eabi) ,其中包含 ARM Cortex-M4 處理器的編譯程式。 依照該處的指示下載並安裝操作系統平臺的編譯程式。
根據預設,Visual Studio Code 搜尋工具鏈,應該會找到您安裝的版本。 如果您遇到與工具鏈相關的組建問題,請檢查 [ 喜好設定>] 設定>擴充功能>AzureSphere,以確保「Azure 球體:Arm Gnu 路徑」能識別 GNU Arm Embedded Toolchain 安裝目錄。
設定硬體以顯示輸出
目前,每個即時核心都支援 TX 專用 UART。 RTApps 可以使用此 UART 從裝置傳送記錄輸出。 在應用程式開發和偵錯期間,您通常需要讀取和顯示輸出的方式。 HelloWorld_RTApp_MT3620_BareMetal範例顯示應用程式如何寫入 UART。
使用 USB 對序列適配卡,例如 FTDI 好友,將即時核心上的 UART 連接到您電腦上的 USB 埠。 您也需要 終端模擬器 ,以建立具有 115200-8-N-1 終端機設定的序列連線 (115200 bps、8 個位、無同位位) 來顯示輸出。
若要設定硬體以從 RTApp 顯示輸出,請遵循下列步驟。 您必須參閱硬體製造商的檔,以判斷釘選位置。 如果您使用的硬體遵循 MT3620 參考面板設計 (RDB) 硬體,例如 Seeed Studio 的 MT3620 Dev Kit,則查看 RDB 介面標頭 可能有助於判斷釘選位置。
將 USB 對串行適配卡上的 GND 連接到開發工具包上的 GND。 在MT3620 RDB硬體上,GND為頁首 3,釘選 2。
將 USB 對序列適配卡上的 RX 連接到開發工具包上的 IOM4-0 TX。 在MT3620 RDB硬體上,IOM4-0 TX為頁首 3,釘選 6。
將 USB 對序列適配卡連接到開發電腦上的免費 USB 埠,並判斷序號裝置連接的埠。
在 Windows 上,啟動 裝置管理員,選取 [依容器檢視>裝置],然後尋找 [USB UART]。 例如,FT232R USB UART 代表 FTDI Friend 配接器。
在 Linux 上,輸入下列命令:
dmesg | grep ttyUSB
埠應命名為 ttyUSBn,其中 n 代表埠號碼。
dmesg
如果命令列出數個 USB 埠,則會連線到通常最後一個回報為附加的埠。 例如,在下列專案中,您會使用 ttyUSB4:
~$ dmesg | grep ttyUSB [ 144.564350] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB0 [ 144.564768] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB1 [ 144.565118] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB2 [ 144.565593] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB3 [ 144.570429] usb 1-1.1.3: FTDI USB Serial Device converter now attached to ttyUSB4 [ 254.171871] ftdi_sio ttyUSB1: FTDI USB Serial Device converter now disconnected from ttyUSB1
啟動終端模擬器程式,並開啟轉接器所使用的 115200-8-N-1 終端機至 COM 埠。 請參閱終端模擬器的檔,瞭解如何指定埠和速度。
啟用開發與偵錯
您必須先啟用開發和偵錯,才能在 Azure 球體裝置上建立範例應用程式或開發新的應用程式。 根據預設,Azure 球體裝置會被「鎖定」;也就是說,他們不允許從計算機載入開發中的應用程式,也不允許偵錯應用程式。 準備裝置進行偵錯會移除此限制,並載入偵錯和解除鎖定裝置功能 所需的軟體。
若要偵錯即時核心,請使用 az 球體裝置啟用開發 命令。 此命令會將裝置設定為接受來自計算機的應用程式進行偵錯,並將裝置指派給「開發裝置」群組,而此群組不允許雲端應用程式更新。 在應用程式開發和偵錯期間,您應將裝置留在此群組中,讓雲端應用程式更新不會覆寫開發中的應用程式。
在 Windows 上,您必須新增 --enable-rt-core-debugging
參數,將偵錯伺服器和每種核心類型的必要驅動程式載入裝置上。
如果您尚未登入 Azure 球體,請登入:
az login
使用 PowerShell 或具有系統管理員許可權的 Windows 命令提示字元開啟命令行介面。 參數
--enable-rt-core-debugging
需要系統管理員許可權,因為它會安裝偵錯程式的USB驅動程式。輸入下列命令:
az sphere device enable-development --enable-rt-core-debugging --catalog <CatalogName> --resource-group <ResourceGroupName>
由於不再需要系統管理員許可權,所以在命令完成後關閉視窗。 最佳作法是一律使用能完成工作的最低許可權。
如果 az 球體裝置啟用開發 命令失敗,請參閱 Azure 球體問題的疑難解答 以取得協助。
下載範例應用程式
您可以下載 InterCore Communications 應用程式,如下所示:
- 將瀏覽器指向 Microsoft 範例瀏覽器。
- 在 搜尋 方塊中輸入 「Azure 球體」。。
- 從搜尋結果中選取 [Azure 球體 - 核心間通訊 ]。
- 選取 [下載 ZIP]。
- 開啟下載的檔案,然後解壓縮到本機目錄。
建置及執行合作夥伴應用程式
啟動 Visual Studio。 選取 [開啟本機資料夾],然後流覽至您擷取 IntercoreComms 應用程式的資料夾。
重要
如果您使用的是 Visual Studio 2022 版本 17.1 或更新版本,而且您是在 22.02 Azure 球體發行之前擷取 IntercoreComms 樣本,則必須 將CMakeWorkspaceSettings.json檔案新增至最上層的項目資料夾。
如果您不是使用 MT3620 RDB,請更新應用程式和硬體定義檔的app_manifest.json檔案 ,並CMakeLists.txt 檔案,讓高階應用程式符合您的硬體。
如果 CMake 產生不會自動啟動,請選取 CMakeLists.txt 檔案。
在 Visual Studio 中, 檢視>輸出>顯示來自: CMake 輸出應顯示訊息
CMake generation started
和CMake generation finished
。選 取 [全部組建>]。 如果功能表不存在,請開啟 方案總管,以滑鼠右鍵按兩下 CMakeLists.txt 檔案,然後選取 [組建]。 IntercoreComms_HL & IntercoreComms RT 應用程式的輸出位置會顯示在 [ 輸出 ] 視窗中。
選取 [所有核心) (啟動專案>IntercoreComms。
選 取 [偵錯>] 或按 F5 來部署和偵錯應用程式。
在 [ 輸出] 視窗中, 選取功能表中的輸出 ,選取 [裝置輸出]。 [輸出] 視窗應該會顯示高階應用程式輸出:
Remote debugging from host 192.168.35.1, port 58817 High-level intercore comms application Sends data to, and receives data from a real-time capable application. Received 19 bytes: rt-app-to-hl-app-07 Sending: hl-app-to-rt-app-00 Sending: hl-app-to-rt-app-01
連線的終端機模擬器應該會顯示即時支援程式的輸出:
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627 Message size: 19 bytes: Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30 Text: hl-app-to-rt-app-00 Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627 Message size: 19 bytes: Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31 Text: hl-app-to-rt-app-01
使用偵錯程式設定斷點、檢查變數,以及嘗試其他偵錯工作。
在 Visual Studio Code 中,開啟您擷取 IntercoreComms 應用程式的資料夾。 Visual Studio Code 偵測到 intercore.code-workspace 檔案,並詢問您是否要開啟工作區。 選取 [開啟工作區],同時開啟即時應用程式和高階應用程式。
如果您不是使用 MT3620 RDB,請更新應用程式和硬體定義檔的app_manifest.json檔案 ,並CMakeLists.txt 檔案,讓高階應用程式符合您的硬體。
按 F5 啟動調試程式。 如果專案先前尚未建立,或是檔案已變更且需要重建,Visual Studio Code 會在偵錯開始之前建立專案。
Azure 球體輸出視窗應該會顯示「正在部署影像...」後面接著 SDK 和編譯程式的路徑。
輸出視窗應該會顯示高階應用程式輸出:
Remote debugging from host 192.168.35.1, port 58817 High-level intercore comms application Sends data to, and receives data from a real-time capable application. Received 19 bytes: rt-app-to-hl-app-07 Sending: hl-app-to-rt-app-00 Sending: hl-app-to-rt-app-01
連線的終端機模擬器應該會顯示即時支援程式的輸出:
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627 Message size: 19 bytes: Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30 Text: hl-app-to-rt-app-00 Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627 Message size: 19 bytes: Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31 Text: hl-app-to-rt-app-01
使用 Visual Studio Code 偵錯功能來設定斷點、檢查變數,以及嘗試其他偵錯工作。
故障排除
應用程式可能會在 OpenOCD 連線之前開始執行。 因此,在程式代碼早期設定的斷點可能會遺漏。 一個簡單的因應措施是延後應用程式的啟動,直到 OpenOCD 連線。
在應用程式進入點 RTCoreMain 的開頭插入下列程式代碼。 這會導致應用程式進入並保持迴圈,
while
直到變數f
設為 True 為止。static _Noreturn void RTCoreMain(void) { . . . volatile bool f = false; while (!f) { // empty. } . . . }
按 F5 以啟動具有偵錯功能的應用程式,然後中斷執行。
在 [ 本地 人偵錯] 窗格中,將值
f
從零變更為一。像往常一樣逐步執行程序代碼。
使用 CLI 建置時,您會先建置並部署支援即時的應用程式,然後建置及部署高階應用程式。
建置及部署支援即時的應用程式
流覽至您擷取 IntercoreComms 應用程式的資料夾,然後選取 IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal 資料夾。
開啟app_manifest.json檔案,並確認高層級應用程式的元件標識符顯示在AllowedApplicationConnections功能中。
使用 PowerShell、Windows 命令提示字元或 Linux 命令殼層開啟命令行介面。 流覽至您的專案組建目錄。
在專案組建目錄的命令提示字元中,使用下列參數執行 CMake:
cmake --preset <preset-name> <source-path>
--preset <preset-name>
組建設定預設名稱,如 CMakePresets.json 中所定義。
--build <cmake-path>
包含 CMake 快取的二進位目錄。 例如,如果您在 Azure 球體樣本上執行 CMake,則組建命令會是
cmake --build out/ARM-Debug
。<source-path>
包含範例應用程式之來源檔案的目錄路徑。 在範例中,Azure 球體樣本存放庫已下載到名為 AzSphere 的目錄。
CMake 參數會以空格分隔。 Windows 命令行的線條延續字元 (^、 \ for Linux 命令行或 ' for PowerShell) 可用於可讀性,但並非必要。
下列範例顯示 IntercoreComms RTApp 的 CMake 命令:
在專案組建目錄的命令提示字元中,執行 [忍者] 以建立應用程式並建立圖像套件檔案。
ninja -C out/ARM-Debug
忍者會將產生的應用程式和 .imagepackage 檔案放在指定的目錄中。
您也可以使用下列命令透過 CMake 叫用忍者:
cmake --build out/<binary-dir>
設定
<binary-dir>
為包含 CMake 快取的二進位目錄。 例如,如果您在 Azure 球體樣本上執行 CMake,則組建命令會是cmake --build out/ARM-Debug
。進行疑難解答時,尤其是對 CMake 命令進行任何變更之後,請刪除整個組建,然後再試一次。
刪除已部署到裝置的任何應用程式:
az sphere device sideload delete
在專案組建目錄的命令提示字元中,載入忍者建立的影像套件:
az sphere device sideload deploy --image-package <path-to-imagepackage>
應用程式載入之後很快就會開始執行。
取得影像的元件識別碼:
az sphere image-package show --image-package <path-to-imagepackage>
命令會傳回圖像套件的所有元數據。 應用程式的元件識別碼會出現在應用程式圖像類型的 [身分識別] 區段中。 例如:
... "Identity": { "ComponentId": "<component-id>", "ImageId": "<image-id>", "ImageType": "Application" }, ...
建置和部署高階應用程式
流覽至您擷取 IntercoreComms 應用程式的資料夾,然後選取 IntercoreComms/IntercoreComms_HighLevelApp 資料夾。
開啟app_manifest.json檔案,並確認 RTApp 的元件標識碼顯示在 AllowedApplicationConnections 功能中。
使用 PowerShell、Windows 命令提示字元或 Linux 命令殼層開啟命令行介面。 流覽至您的專案組建目錄。
在專案組建目錄的命令提示字元中,使用下列參數執行 CMake:
cmake --preset <preset-name> <source-path>
--preset <preset-name>
組建設定預設名稱,如 CMakePresets.json 中所定義。
--build <cmake-path>
包含 CMake 快取的二進位目錄。 例如,如果您在 Azure 球體樣本上執行 CMake,則組建命令會是
cmake --build out/ARM-Debug
。<source-path>
包含範例應用程式之來源檔案的目錄路徑。 在範例中,Azure 球體樣本存放庫已下載到名為 AzSphere 的目錄。
CMake 參數會以空格分隔。 Windows 命令行的線條延續字元 (^、 \ for Linux 命令行或 ' for PowerShell) 可用於可讀性,但並非必要。
下列範例顯示 IntercoreComms 高階應用程式的 CMake 命令。
在專案組建目錄的命令提示字元中,執行 [忍者] 以建立應用程式並建立圖像套件檔案。
ninja -C out/ARM-Debug
忍者會將產生的應用程式和 .imagepackage 檔案放在指定的目錄中。
您也可以使用下列命令透過 CMake 叫用忍者:
cmake --build out/<binary-dir>
設定
<binary-dir>
為包含 CMake 快取的二進位目錄。 例如,如果您在 Azure 球體樣本上執行 CMake,則組建命令會是cmake --build out/ARM-Debug
。進行疑難解答時,尤其是對 CMake 命令進行任何變更之後,請刪除整個組建,然後再試一次。
在專案組建目錄的命令提示字元中,載入忍者建立的影像套件:
az sphere device sideload deploy --image-package <package-name>
應用程式載入之後很快就會開始執行。
取得影像的元件識別碼:
az sphere image-package show --image-package <path-to-imagepackage>
命令會傳回圖像套件的所有元數據。 應用程式的元件識別碼會出現在應用程式圖像類型的 [身分識別] 區段中。 例如:
... "Identity": { "ComponentId": "<component-id>", "ImageId": "<image-id>", "ImageType": "Application" }, ...
在啟用偵錯功能時執行合作夥伴應用程式
如果您正在執行即時應用程式,請停止該應用程式。
az sphere device app stop --component-id <component id>
重新啟動偵錯應用程式。
az sphere device app start -- --debug-mode true --component-id <component id>
此命令會傳回應用程式執行的核心。
<component id> App state: running Core : Real-time 0
流覽至應用程式所建置之 sysroot 的 Openocd 資料夾。 Sysroots 會安裝在 Azure 球體 SDK 安裝資料夾中。 例如,在 Windows 上,預設會在
C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\openocd
Linux 安裝資料夾,/opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux
如
openocd
以下範例所示執行。 此範例假設應用程式在核心 0 上執行。 如果應用程式在核心 1 上執行,請將「目標 io0」取代為「目標 io1」。(Windows Azure 球體傳統 CLI) 、標準命令提示字元或 Windows Azure CLI) (PowerShell,或是 Linux) 的終端 (視窗,開啟新的 Azure 球體命令提示字元。
瀏覽至包含支援即時應用程式 .out 檔案和啟動
arm-none-eabi-gdb
的資料夾,這是 GNU Arm Embedded Toolchain 的一部分:Windows 命令提示字元
"C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out
Windows PowerShell
& "C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out
OpenOCD 伺服器在 :4444 提供 GDB 伺服器介面。 設定偵錯的目標。
target remote :4444
您現在可以對支援即時功能的應用程式執行 gdb 命令。 在函數 HandleSendTimerDeferred 新增斷點:
break HandleSendTimerDeferred
連接的終端機模擬器應該會顯示支援即時應用程式的輸出。
(Windows Azure 球體傳統 CLI) 、標準命令提示字元或 Windows Azure CLI) (PowerShell,或是 Linux) 的終端 (視窗,開啟新的 Azure 球體命令提示字元。
流覽至包含高階應用程式 .imagepackage 檔案的資料夾。
如果高階應用程式正在執行,請停止該應用程式。
az sphere device app stop --component-id <component id>
使用偵錯功能重新啟動高階應用程式。
az sphere device app start --debug-mode true --component-id <component id> --debug-mode
在埠 2342 開啟 終端機模擬器 ,並建立 192.168.35.2 的 Telnet 或 TCP 連線,以檢視高階應用程式的輸出。
使用下列命令啟動 gdb:
Windows 命令提示字元
"C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out
Windows PowerShell
& "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out
注意
Azure 球體 SDK 會隨附多個 sysroots ,讓應用程式可以按照 應用程式運行時間版本、sysroots 和 Beta API 中所述,以不同的 API 集為目標。 Sysroots 會安裝在 Sysroots 下的 Azure 球體 SDK 安裝資料夾中。
將遠端偵錯目標設定為埠 2345 上的 IP 位址 192.168.35.2:
target remote 192.168.35.2:2345
在 SendMessageToRTApp 函數新增斷點:
break SendMessageToRTApp
輸入
c
以繼續、觀察 Telnet/TCP 終端機中的輸出,然後切換到包含即時應用程式偵錯會話的命令提示字元或終端機視窗。輸入
c
以繼續並觀察連線的序列會話中的輸出。
您可以在偵錯會話之間來回工作,在支持即時功能的應用程式和高階應用程式之間切換。 您應該在兩個輸出視窗中看到類似下列的輸出:
Starting debugger....
Process /mnt/apps/25025d2c-66da-4448-bae1-ac26fcdd3627/bin/app created; pid = 40
Listening on port 2345
Remote debugging from host 192.168.35.1, port 56522
High-level intercore comms application
Sends data to, and receives data from a real-time capable application.
Sending: hl-app-to-rt-app-00
Sending: hl-app-to-rt-app-01
IntercoreComms_RTApp_MT3620_BareMetal
App built on: Nov 17 2020, 09:25:19
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
Text: hl-app-to-rt-app-00
若要結束每個偵錯會話,請在 gdb 提示字元中輸入 q
。
後續步驟
- 探索高階和支持即時應用程式的其他範例
- 深入瞭解 Azure 球體應用程式
- 深入瞭解 Azure 球體開發環境