May. 17, 2022

使用System Console來Debug FPGA

foaf:image

System Console提供使用者除了常見的in-system source and probe外，另一種Debug 的方式是：使用System Console透過TCL Command來控制Intel Avalon Interface , 以驗證透過Intel Avalon Interface 相關IP的功能。如圖一所示：

image not found 圖一、System Console API 支援在操作中存取的設計服務

system console建立與命令流程

以下內容會簡單的說明這個system console 如何建立與命令流程。

System Console Debug流程

  1.  將一個 IP Core 新增到 Platform Designer 系统。

  2.  生成 Platform Designer 系统。

  3.  編輯設計。

  4. 連接電路板並對 FPGA 進行编程。

  5. 啟動 System Console。

  6. 找到並打開 System Console service視窗。

  7. 使用此service執行debug操作。

  8. 關閉此service。
     


使用Console命令選擇一個路徑服務，以及打開和關閉連接。按照下面步驟啟動一個服務連接：

 

System Console 命令流程

  1. 通過使用 get_service_paths 命令來指定一個服務的路徑來執行服務。

  2. 使用 open_service 命令打開一個服務的連接。

  3. 使用 Tcl and System Console 命令測試連接的器件。

  4. 使用 close_service 命令關閉一個服務的連接。

  5. 以下內容將提供範例且更詳細介紹：

System Console 範例 - JTAG to Avalon Master Bridge

JTAG to Avalon Master Bridge是一個簡單好用的debug IP，可以讓使用者對Avalon 介面做簡單地驗證與控制，如果是簡單系統的debug只需要利用幾句簡單的TCL語言即可完成，而複雜的系統也可以透過TCL腳本來做debug。

前置作業

步驟如下:

1. 使用Quartus建立project：

使用者在打開Quartus.exe後，建立新的project，路徑如下： File -> 點選New Project Wizard 視窗的Next -> 在Directory, Name, Top-Level Entity中輸入位置跟project name -> 在Project Type中選擇Empty project-> 按下Next (由於是新Project 所以沒有File Add，直接按即可) -> 選好Device (此範例選得是開發版10CL025YU256I7) -> 按下Finish。

 

2. 建立好Project後，把clock與要控制的IO、RESET都設定好，如圖二所示：

image not found 圖二、簡單的Sample Code

3. 新增JTAG to Avalon Master Bridge：

在project裡面新增一個IP : JTAG to Avalon Master Bridge；加入後，連接該IP的clock和reset信號，並將master端口連接到需要觀察的slave上 (範例中需要觀察與控制的slave為on-chip memory & parallel I/O )，並給一個固定的地址位置，如圖三所示 :

image not found 圖三

4. 連接外部 & Compiler

Generate IP 後把輸出Module接到parallel I/O (LED1~4)，而clock 接到外部並重新compiler，如圖四所示 :

image not found 圖四

5. 燒錄

把code透過programmer燒錄進去FPGA，如圖五所示 :

image not found 圖五

6. 開啟System Console GUI介面

點選Tools -> System Debugging Tools -> System Console，如圖六、圖七所示 :

image not found 圖六
image not found 圖七、System Console GUI

備註：

(1). Toolkit Explorer：顯示所有可用的工具，並運行使用 System Console 框架的工具。
(2). System Explorer：顯示設計中project的列表。
(3). Tcl Console ：使用者能夠使用 Tcl 腳本，編寫程序和使用 System Console API 與設計連接。
(4). Messages：顯示與連接的相關的狀態、警告和錯誤消息。

7. TCL語法 ( set < service_path > [lindex [get_service_paths master] 0] )

首先，將Tcl console和JTAG master建立連接後，設置JTAG master的path，並在Tcl console中輸入set [lindex [get_service_paths master] 0]

 

備註：

 

(1). 當// Tcl console裡面顯示出路徑後即表示已經找到了使用者在Qsys中放入的JTAG to Avalon Master Bridge

image not found

其中，get_service_paths master可找尋service集合裡的全部paths，如果使用者用了很多個JTAG to Avalon Master Bridge IP，就會列出很多個內部號碼與路徑。

由於一次只能連接一組service_paths ，所以我們使用lindex指定集合中的其中一個service，此範例中因只有使用一個JTAG to Avalon Master Bridge IP，故先設定集合中的第0個。而在最前面SET的部分，因路徑 (如圖九灰色所示) 非常冗長，為了讓使用者更方便，把可p0變數設定為那串路徑。

8. TCL語法( open_service master < service_path > )

接下來，可以先把該條路徑打開，這樣才能對這條路徑做控制

圖九

9. TCL語法( master_write_32 < service_path > ，<address>，<list_of_byte_values>)

如圖十，這邊對0x00的位置做寫入0x01的值。

圖十
foaf:image

備註：

 

．這邊為master_write_32中為寫入32bits，如下圖，若寫入的值大於32bits(Overflow) 則會取32bits的資料。


．除了master_write_32外還有許多Module Commands可以使用例如 :

 

1. master_write_memory < service_path >, <address>, <list_of_byte_values>
2. master_write_8< service_path >, <address>, <list_of_byte_values>
3. master_write_16< service_path >, <address>, <list_of_byte_values>

image not found 圖十一

10. TCL語法 ( master_read_32 < service_path >, <address>, <size_in_bytes>)

如圖十二，這邊對0x00進行寫入 在對0x00進行讀取的動作

image not found 圖十二
foaf:image

備註：

 

  • 這邊的是指使用者要讀取幾個byte address的資料 例如: 若要讀取0x00~0x03的資料，就可以寫4，如圖十三所示
image not found 圖十三
  • 而除了master_read_32外，也有相對於write的各種read的變化，例如：
  1. master_read_memory < service_path >, <address>, <size_in_bytes>
  2. master_read_8 < service_path >, <address>, <size_in_bytes>
  3. master_read_16 < service_path >, <address>, <size_in_bytes>

11. TCL語法( close_service master < service_path > )

當驗證完我們的IP後，我們要把我們的service_paths關閉，如圖十四

圖十四

附錄 : TCL語法 （有關TCL檔整理的部分）

如果不想每一次使用System console的時候都需要下複雜的command時，使用者可以把相關語法設定在.Tcl檔中，也可以寫成類似Module的方式，如果需要使用可直接呼叫，以利管理。如圖十五所示：

下圖內容為把open 與 close service寫成module，需要時可即時呼叫

image not found 圖十五

當輸入source 的tcl檔時，使用者就可以直接把當初打在TCL檔中的語法直接執行完，如下圖十六所示：

image not found 圖十六

備註：

因在TCL檔中輸入puts指令，所以會顯示出對應文字，如圖十七所示

image not found 圖十七

由於這篇主要在於探討系統上Debug的部分，所以後續內容提供了一個GUI介面作為參考，請見以下附錄。

附錄 : TCL語法 (GUI篇)

不但可以透過TCL語法做出GUI介面，使用者也可以在Tools中建立專屬的下拉式選單，如下圖的Cyclone 10 LP_TCL即是自己建立的下拉式選單

image not found 圖十八、TCL語法
image not found 圖十九、展示出來的結果

打開下拉式選單即可看到使用者自行設計的GUI介面，接下來的內容會繼續針對GUI介面的TCL語法，底下的附註亦提供參考。

image not found 圖二十、展示出來的結果
image not found 圖二十一、在開發版上的亮燈

第一個是連接系統的時間。

 

image not found 圖二十二、TCL語法的部分 (TimeGroup GUI)
image not found 圖二十三、展示出來的結果(TimeGroup GUI)

第二個是對IP 中ON-CHIP ROM做讀的部分

image not found 圖二十四、TCL語法的部分(ON-CHIP ROM GUI)
image not found 圖二十五、展示出來的結果(ON-CHIP ROM GUI)

第三個部分是連接到板子上的LED燈，使用者可以透過上面的按鈕來控制黃燈亮暗，如上圖，範例中，點選LED 1、LED 2、LED 4亮、LED 3不亮 因此，該對應板子的LED 3燈也不會亮

image not found 圖二十六、TCL語法的部分(PIO-LED GUI)
image not found 圖二十七、展示出來的結果(PIO-LED GUI)

以上範例給大家做參考，如果有興趣可以參考下方的Analyzing and Debugging Designs with System Console

總結

System Console的好處在於對系統級別的設計做驗證並做大範圍的控制、提高debug上的靈活度。這篇也針對Intel Avalon Interface IP的驗證，做了一個簡單的範例說明，讓各位對System Console有初步的印象。

參考文獻

  1. Intel®, Intel® Quartus® Prime Standard Edition User Guide: Debug Tools, https://reurl.cc/ZAWENg

  2. Altera, System Console User Guide, https://reurl.cc/q5LoK3

  3. Altera, Analyzing and Debugging Designs with System Console, https://reurl.cc/2ZLN74