Introduction

芯片驗證與測試組（VV，Verification & Validation Team）的同事在驗證新芯片產品時，需要在手冊完備之前就要開始展開開發工作，甚至需要根據驗證的結果對從設計文檔合成的初版用戶手冊進行調整。這些早期的開發工作也會對軟件工具的設備支持包提出需求，例如Keil集成開發環境的pack支持包，但正式給用戶發布的設備支持包又需要依賴于完備的用戶手冊。好吧，這其實是一個“雞蛋問題”（到底是先有雞再生蛋，還是先有蛋再孵小雞）。暫且跳過最初的情況，我們軟件與系統工程組（Software & System Engineering Team）的工程師可以基于已有的相近產品進行微調，然后同VV提供的驗證情況配合，不斷微調和迭代趨近最終發布狀態。這才是真實世界的開發過程。在這個過程中，對描述寄存器布局的SVD文件的更新是最活躍的，可能隨著驗證的實際情況，我們希望不要每次都重頭開始處理所有外設寄存器的布局，而是不斷根據每個周期的反饋，進行局部更新，以減少重復的工作量。在這個工作環境中，在現有SVD文件局部更新某個外設模塊，將會是一個非常頻繁基本操作。

本文詳細介紹了如何使用靈動軟件與系統工程組自主開發的sdk-npi-enablement-tool工具包，完成SVD文件局部更新的操作過程。

Overview

sdk-npi-enablement-tools工具包含了一個描述外設模塊寄存器分布信息的數據庫（xlsx文件和yaml文件集合），以及以數據庫為對象的一系列服務的工具，例如，從原始的doc格式的UM文檔中提取寄存器分布信息存放為xlsx記錄的工具類 gen_srctables.py、從描述外設模塊寄存器分布的xlsx文件生成SVD文件的工具類 gen_svdfile.py、從xlsx記錄中生成包含中斷向量表等具體芯片相關信息頭文件和dma_request.h文件的gen_sdkfile.py等。

Operation Steps

以新建的不會在真實世界中存在的虛擬平臺MM32F0000項目為例，以現有已經發布的MM32F0020微控制器的SVD文件為模板，更換其中的UART模塊為USART模塊，產生最終的MM32F0000微控制器項目的SVD文件。

創建芯片配置文件yaml

1. 在sdk-npi-enablement-tools\\tools\\generator\\yaml\\devices目錄下創建MM32F0000.yaml文件。這里的MM32F0000.yaml文件描述了SoC中包含了哪些外設模塊。

此處以MM32F0020項目在同級目錄下的配置文件為模板，復制創建MM32F0000.yaml的芯片配置文件。其中包含了MM32F0000芯片中集成的外設模塊。這些記錄的信息來自于芯片DS手冊中對片上資源介紹的描述，也可以來自于產品經理定義新芯片產品的PB文檔，但實際芯片集成資源的情況仍需以DS為準。

coretype: m0

subseries:
  MM32F0000B:
    peripherals:

peripherals:
  flash:
  pwr:
  rcc:
  crc:
  syscfg:
  gpio:
   gpioa:
   gpiob:
  exti:
  adc:
    adc1:
  tim1:
  tim3:
  tim14:
  wwdg:
  iwdg:
  uart:
   uart1:
   uart2:
  spi:
   spi1:
  i2c:
   i2c1:
  dbg:

其中，yaml文件名描述了本產品系列的名字，yaml文件中的subseries及下級屬性描述了產品系列內部子系列具體芯片型號的特有外設，例如在MM32F0270.yaml文件中，在不同的子系列中，對usb、can等模塊的支持情況就進行了細分。

2. 在sdk-npi-enablement-tools\\database\\ip_reg_desp目錄下為MM32F0000創建外設寄存器映射數據記錄。

此處以同級目錄下的MM32F0020目錄為模板，復制成MM32F0000的目錄。其中包含了以xlsx文件存放的各外設模塊獨自的寄存器映射地址信息。這些文件記錄的原始數據來自于芯片UM手冊中對外設模塊的描述，也可以來自于芯片設計組（芯片架構）提供的完備的寄存器描述材料。

圖x 描述IP外設模塊寄存器內部偏移的存儲映射的數據庫記錄

3. 在sdk-npi-enablement-tools\\resource目錄下為MM32F0000芯片創建關于中斷向量表和外設基址映射信息的記錄。
   此處仍以同級目錄下的MM32F0020項目為模板，復制成MM32F0000項目的目錄。其中包含了baseaddress.xlsx文件和interrupts.xlsx文件，分別記錄外設模塊的基地址和中斷向量表中各中斷向量的名字和排序。這些記錄的原始信息來自于芯片的UM手冊。

圖x 描述芯片集成外設在內存空間中映射的數據庫記錄4. 運行sdk-npi-enablement-tools\\tools目錄下的gen_svdfile.py腳本程序，將在``sdk-npi-enablement-tools\\targetfiles目錄創建一個mm32f0000`的項目目錄，其中包含本次創建過程生成的SVD文件。

在腳本中修改chiptype的配置值為芯片名，mm32f0000，此處的設定值需要同MM32F0000.yaml文件的文件名保持一致。

import os
from generator.gen_regsvd import *


def main():

    chiptype = 'mm32f0000'  # change here to suit to different chip series

    wkdir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../'))
    outfiledir = os.path.join(wkdir, 'targetfiles', chiptype)  # Easy to manage, the generated file path is the specified path under the specific series of "targetfiles"

    # write register definition
    regdef = GenReg(chiptype)
    regdef.write_svd()


if __name__ == '__main__':
    main()

運行。成功?？梢钥吹?，在targetfiles新建的mm32f0000目錄下，生成了MM32F0000.svd文件。

圖x 生成新的SVD文件

運行成功。

此時，我們已經通過sdk-npi-enablement-tool得到了一個MM32F0000芯片項目的SVD文件。這個新生成的文件實際的內容還是現有MM32F0020項目的，仍需要調整其中的內容。但無論如何，創建新芯片項目SVD文件的框架已經搭起來了。接下來，需要解決向其中添加新外設模塊USART和刪減外設模塊UART的問題。

填充外設模塊的寄存器映射描述文件xlsx

在上一個環節中，我們已經通過sdk-npi-enablement-tool得到了一個MM32F0000芯片項目的SVD文件，創建新芯片項目SVD文件的框架和操作流已經搭起來了?，F在，需要解決刪減外設模塊UART并向其中添加新外設模塊USART的問題。

在現有項目中刪除模塊相對容易，直接在上文提到的MM32F0000.yaml文件中刪除不需要的模塊的記錄，然后在baseaddr.xlsx和interrupts.xlsx文件中刪除對應的記錄即可。如果要做得更徹底，還可以繼續刪掉sdk-npi-enablement-tool\\database\\ip_reg_desp\\mm32f0000目錄下描述UART模塊寄存器映射的uart.xlsx文件，但因為在上述配置文件中已經刪除了對UART模塊的引用，所以此處的uart.xlsx文件被刪與否都不會再起作用。

在現有項目中添加新外設同刪除模塊對等，只要在需要引用模塊的地方添加新模塊的記錄即可。例如，這里將UART模塊的名字改為USART（相當于刪掉了UART模塊后再添加USART）。

• 在sdk-npi-enablement-tool\\tools\\generator\\yaml\\devices目錄下的mm32f0000.yaml文件中，添加USART模塊的記錄
• 在sdk-npi-enablement-tool\\resource\\mm32f0000目錄下的baseaddress.xlsx文件中，添加USART模塊在存儲空間中的基地址
• 在sdk-npi-enablement-tool\\resource\\mm32f0000目錄下的interrupts.xlsx文件中，添加USART模塊在中斷向量表中的記錄
• 在sdk-npi-enablement-tool\\database\\ip_reg_desp\\mm32f0000目錄下，為USART模塊創建描述寄存器及其位域的表格，這個需要如下的操作，從UM手冊文檔中提取內容，才能創建生成。

目前，我有USART模塊的IP Spec文檔IP_USART_DesignSpec_v0.x.docx，其中包含了對USART模塊中各寄存器及其位域的地址映射信息。

配置sdk-npi-enablement-tool\\tools目錄下的gen_srctables.py腳本：

• 指定輸入文件為包含USART模塊中各寄存器及其位域的地址映射信息的IP_USART_DesignSpec_v0.x.docx，指定位于sdk-npi-enablement-tool\\resource\\mm32f0000目錄下。
• 指定輸出路徑在sdk-npi-enablement-tool\\database\\ip_reg_desp\\mm32f0000下，腳本會根據mm32f0000.yaml文件中指定的模塊清單，匹配傳入文件中的內容，如果在mm32f0000.yaml文件中登記并在傳入文件中找到相關模塊的記錄，則會在指定路徑下創建這個模塊的單獨的xlsx文件。

#！usr/bin/python3
#! encoding utf-8

from generator.gen_tables import GenTable

def main():

    RegTable = GenTable('mm32f0000', 'IP_USART_DesignSpec_v0.x.docx')  # 需修改兩個參數，第一個芯片系列（需小寫），第二個為文件Word文件名
    print('Data extraction finished.')

if __name__ == '__main__':
    main()

運行程序后，在sdk-npi-enablement-tool\\database\\ip_reg_desp\\mm32f0000目錄下生成了新的usart.xlsx文件。

此時，因為已經更新了yaml文件中的配置信息，重新執行上節中生成SVD文件的操作步驟，即可產生包含USART模塊的全新的SVD文件。

圖x 更新USART前的SVD文件片段其中，關于寄存器字段的描述是中文的，Keil的SVD解析器僅能識別英文。此處需要進行一些微調。故建議使用英文版手冊作為SVD生成過程的數據源，或者一種可行的做法，是直接使用寄存器位域名取代位域的解釋，至少先保證SVD文件能夠正常被SVD文件解析器識別。本例中直接修改USART模塊的數據源（寄存器映射表）文件，如圖x所示。

圖x USART模塊的寄存器映射表

重新運行gen_svdfile.py，更新成功。

驗證

使用sdk-npi-enablement-tool工具包生成的SVD文件，不一定能夠被Keil的SVD文件完全識別。為此，在正式交付之前，需要驗證SVD文件是否可用。CMSIS-SVD提供了一個工具 svdconv.exe，可以將SVD文件轉換成各種其他源文件，其中最基本的功能，就是驗證SVD文件的有效性。

在sdk-npi-enablement-tool\\tools目錄下找到SVDConv.exe工具，并在命令行下運行，傳入剛生成的mm32f0000.svd文件。

indMotion@PF2LD92H MINGW64 /d/workspace/sdk-npi-enablement-tool/tools
$ svdconv.exe

CMSIS-SVD SVD Consistency Checker / Header File Generator V3.3.42
Copyright (C) 2010-2022 ARM Ltd and ARM Germany GmbH. All rights reserved.


Usage:
  SVDConv.exe < SVD file > [Options]

Options:
  -o < output path >           Output Path, default current directory
  -b < log file >              Log file for Messages
  --generate=header          Generate CMSIS header file
  --fields=struct            Generate struct/union for bitfields
  --fields=macro             Generate macros for bitfields
  --fields=struct-ansic      Generate structs for bitfields (ANSI C)
  --fields=enum              Generate enumerated values for bitfields
  --debug-headerfile         Add Addresses to Registers comments
  --generate=partition       Generate CMSIS partition file
  -x [Mxxx, INFO, WARNING]   Suppress Message, Warnings or Infos
  -h, -?                     Show this help

Examples:
Check only >        SVDConv.exe myDevice.svd
Header Generation > SVDConv.exe myDevice.svd --generate=header


MindMotion@PF2LD92H MINGW64 /d/workspace/sdk-npi-enablement-tool/tools
$ svdconv.exe MM32F0000.svd

CMSIS-SVD SVD Consistency Checker / Header File Generator V3.3.42
Copyright (C) 2010-2022 ARM Ltd and ARM Germany GmbH. All rights reserved.

Arguments: "MM32F0000.svd"

...

** INFO M304: MM32F0000.svd (Line 6029)
  Interrupt number overwrite: '19 : TIM14' (Line 5715)


Found 26 Error(s) and 0 Warning(s).

這里發現有26個error。經排查發現，是因為存在有的寄存器地址用不同的名字命名。

*** ERROR M339: MM32F0000.svd (Line 5128)
  Register 'CCMR1_INPUT' (read-write) (@0x00000018:32) has same address or overlaps 'CCMR1_OUTPUT' (read-write) (@0x00000018:32) (Line 5069)

*** ERROR M339: MM32F0000.svd (Line 5128)
  Register 'CCMR1_INPUT' (read-write) (@0x00000018:32) has same address or overlaps 'CCMR1_OUTPUT' (read-write) (@0x00000018:32) (Line 5069)

這類問題需要在SVD文件中對應寄存器的定義中添加標簽。例如在CCMR_Input中的寫法。注意，在后續版本的sdk-npi-enablement-tool中，也將會加入這樣的生成策略，但在目前版本中，需要手動添加，以清理錯誤。

< register >
                    < name >CCMR1_Input< /name >
                    < displayName >CCMR1_Input< /displayName >
                    < description >capture/compare mode register 1 (input mode)< /description >
                    < alternateRegister >CCMR1_Output< /alternateRegister >
                    < addressOffset >0x18< /addressOffset >
                    < size >0x20< /size >
                    < access >read-write< /access >
                    < resetValue >0x00000000< /resetValue >
                    < fields >
                        < field >
                            < name >IC2F< /name >
                            < description >Input capture 2 filter< /description >
                            < bitOffset >12< /bitOffset >
                            < bitWidth >4< /bitWidth >
                        < /field >

另外，還有一些其他細微的地方需要人工處理，例如，由于sdk-npi-enablement-tool中腳本使用的正則表達式沒有完整呈現出寄存器命名的套路，有一些寄存器命名存在重疊、重復等等，這些問題在當前版本的軟件中，處理能力有限。后續版本會針對這些情況做一些限定，或者使用更強規則的正則表達式對寄存器名進行匹配和甄別。

總之，最后清理掉所有的ERROR就算大功告成。

生成芯片頭文件

sdk-npi-enablement-tool工具包中的gen_sdkfile.py工具，可用于生成芯片頭文件。實際上CMSIS-SVD中的SVDConv.exe工具也可以從SVD文件生成CMSIS規范的頭文件，但我們需要生成頭文件的宏定義要全部大寫，而不是SVDConv.exe工具生成的存在部分小寫字母的宏定義代碼，因此，仍然需要gen_sdkfile.py工具從sdk-npi-enablement-tool工具包的數據庫中生成描述全部芯片外設模塊在存儲空間中映射關系的芯片頭文件。在目前正在開發的版本中，生成頭文件的機制將有所改變，屆時將會基于SVD文件生成頭文件，類似于實現了一個Python版本的SVDConv.exe。

在sdk-npi-enablement-tool\\tools目錄下配置腳本文件gen_sdkfile.py，指定chiptype的值為mm32f0000，然后，運行。

#！usr/bin/python3
#! encoding utf-8

import os
import generator.soc_info
from generator.gen_dma_requests import GenDMARequests
from generator.gen_interrupts import GenInt
from generator.gen_regsvd import GenReg
from generator.gen_baseaddr import GenBase

def main():
    chiptype = 'mm32f0000'  # change here to suit to different chip series

    # output dir.
    wkdir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../'))
    outfiledir = os.path.join(wkdir, 'targetfiles', chiptype)

    # generate interruupt vector for startup file.
    interrupts = GenInt(chiptype)
    interrupts.get_sVector(outfiledir)

    # generate header file for registers.
    regdef = GenReg(chiptype)
    regdef.write_reg()


if __name__ == '__main__':
    main()

運行成功后，在sdk-npi-enablement-tool\\targetfiles\\mm32f0000目錄下生成了新文件MM32F0000\\mm32f0000.h和interrupt.h文件，其中，interrupt.h文件中包含中斷服務函數名的清單，這個清單可用于進一步創建在不同工具鏈下的啟動代碼。生成的mm32f0000.h文件，即為可發布的芯片頭文件。

圖x 新生成的芯片頭文件至此，我們已經為新芯片項目MM32F0000生成了芯片頭文件。

Conclusion

在本文中，記錄了使用sdk-npi-enablement-tool生成設備支持包中描述芯片寄存器存儲映射的SVD文件和芯片頭文件的過程。

• 在執行操作之前，需要準備好包含外設模塊寄存器描述信息的UM文檔的docx版本，sdk-npi-enablement-tool中的腳本會解析docx文件，從中提取描述寄存器及其位域的表格，先進行數據清洗，然后以xlsx文件的格式，將各個外設模塊的寄存器寄存器映射信息分別保存成獨立的文件。這些文件同IC設計的IP倉庫一一對映，形成外設模塊寄存器映射的數據庫。
• 需要在yaml數據庫中創建新芯片的記錄文件，這些文件描述了某一款芯片包含哪些外設模塊，相當于是IC設計過程中的SoC集成過程。
• 然后，就可以調用一系列腳本工作逐步生成需要的文件
  • 使用 gen_srctables.py從原始的doc格式的UM文檔中提取寄存器分布信息存放為xlsx記錄
  • 使用 gen_svdfile.py從描述外設模塊寄存器分布的xlsx文件生成SVD文件
  • 使用gen_sdkfile.py從xlsx記錄中生成包含中斷向量表等具體芯片寄存器清單的頭文件

sdk-npi-enablement-tool工具包目前保持在迭代更新當中，仍存在一些問題，需要少量的人工介入才能通暢地完成生成文件的過程，但已經能夠作為生產力工具對微控制器產品的軟件開發工作提供完備的技術服務。在接下來將要發布的版本中，將會不斷修復已知問題，優化使用體驗。