大家好，我是痞子衡，是正經搞技術的痞子。今天痞子衡給大家分享的是MCUXpresso IDE下高度靈活的FreeMarker鏈接文件模板機制。

痞子衡之前寫過一篇文章 《MCUXpresso IDE下工程鏈接文件配置管理與自動生成機制》，這篇文章介紹了 MCUXpresso IDE 在鏈接文件管理設計上跟其它 IDE（IAR/Keil）不一樣的地方，與 IAR/Keil 下用戶直接改寫鏈接文件去做個性化目標鏈接（比如把某個源文件里全部代碼重定向鏈接到 RAM 里執行）不同的是， MCUXpresso IDE 下用戶都是在圖形化配置界面里做對應操作，然后 MCUXpresso IDE 會自動生成相應的鏈接文件（.ld）。但是圖性化操作界面里有時候不能百分百滿足用戶的個性化鏈接需求，這時候除了回退到 IAR/Keil 下那種傳統方式外，還有沒有其它方式呢？答案是有的，這就是今天要聊的 MCUXpresso IDE 下 FreeMarker 鏈接文件模板機制。

一、準備工作

首先需要準備好環境，包含必要的軟件，痞子衡的環境如下：

集成開發環境：MCUXpresso IDE_11.6.0_8187，點此下載

軟件開發包：SDK_2.12.1_EVK-MIMXRT1170（Toolchain需包含MCUXpresso IDE），點此下載

然后按照 《MCUXpresso IDE下將關鍵函數重定向到RAM中執行的幾種方法》 文章 一、準備工作 小節里改造下 evkmimxrt1170_hello_world_demo_cm7 示例工程選項，并添加 critical_code.c 源文件。在這篇文章的 2.3 針對源文件中全部函數 小節里，痞子衡為了將 critical_code.c 里代碼全部鏈接到 DTCM，使用了回退到 IAR/Keil 那種傳統改寫鏈接文件的方式。今天我們就嘗試用 FreeMarker 鏈接文件模板機制這個特性來實現。

二、FreeMarker機制

FreeMarker 是一個模板引擎（更通俗的說法其實就是鏈接文本的生成器），它集成在 MCUXpresso IDE 內部，由 MCUXpresso IDE 自動調用。MCUXpresso IDE 下最終的鏈接文件其實是由這個 FreeMarker 處理生成的。在 MCUXpresso IDE 軟件內部有一組默認的系統模板（也叫根模板），它還支持用戶提供的模板（這些模板均是用一種專用的語法 FTL 來描述的），所有適用工程的模板最終統一經過 FreeMarker 來處理。

模板的設計是組件化的，這意味著用戶不需要編寫整個工程的模板，只需要加入指定的用戶模板實現個性化鏈接需求即可，其它部分仍由 MCUXpresso IDE 圖形配置界面完成。默認情況下，用戶模板需要被放在指定的 user_project_root/linkscripts 目錄下（這個路徑不用額外添加進工程選項 C/C++ General Paths and Symbols Source Location 中）。

Note：更多 FreeMarker 細節，可以參見 MCUXpressoIDE_11.6.0_8187MCUXpresso_IDE_User_Guide.pdf 文檔里的 17.14 FreeMarker Linker Script Templates 小節。

三、新方法解決問題

現在我們嘗試用 FreeMarker 特性來解決 critical_code.o 的鏈接需求。首先是在 MCUXpressoIDE_11.6.0_81874workspaceevkmimxrt1170_hello_world_demo_cm7 下創建一個名為 linkscripts 的文件夾（前面說了，這個新文件夾路徑不需要在工程選項里登記），然后在 linkscripts 里面新建如下三個 .ldt 文件（固定文件名，由 FreeMarker 定死的）：

bss.ldt
data.ldt          -- 作用是將 critical_code.o 放到指定 RAMx 區域
                  -- 備注：如果 MCU 僅一塊 RAM 空間，則此處應為 main_data.ldt
main_text.ldt     -- 作用是將 critical_code.o 從 .text 段（默認鏈接在 Flash 區域）移出來

main_text.ldt 內容比較簡單，僅僅是用于告訴 FreeMarker 不要將 critical_code.o 里的 text 段放進主 .text 段里一起處理：

// 單目標文件寫法
*(EXCLUDE_FILE(*critical_code.o) .text*)

// 如果是多目標文件，寫法可以這樣
*(EXCLUDE_FILE(*critical_code1.o *critical_code2.o) .text*)

data.ldt 中內容比較關鍵，用于重置 critical_code.o 里的 text 段。這里需要注意的是如果是將該 text 放置進主 RAM 區域（即工程選項 MCU settings 里 Alias 名為 RAM 的空間），其寫法跟不放進主 RAM 不一樣：

// 如果目標文件放進主 RAM        - 正確寫法，等效于放進 memory.alias=="RAM" 或者 memory.name=="SRAM_DTC_cm7" 區域
*critical_code.o(.text*)

// 如果目標文件放進主 RAM        - 錯誤寫法，實際不生效，等于沒有重置，代碼依舊放進 Flash 區域
<#if memory.alias=="RAM">
*critical_code.o(.text*)


// 如果目標文件不是放進主 RAM    - 正確寫法1
<#if memory.name=="SRAM_ITC_cm7">
*critical_code.o(.text*)


// 如果目標文件不是放進主 RAM    - 正確寫法2
<#if memory.alias=="RAM2">
*critical_code.o(.text*)


// 如果是多目標文件，寫法可以這樣
<#if memory.name=="SRAM_ITC_cm7">
*critical_code1.o(.text*)
*critical_code2.o(.text*)

現在編譯工程查看映射文件，我們會發現 critical_code.c 里全部函數都已經鏈接在指定的 RAMx 區域了。如果你想更進一步，把 critical_code.c 里全部 RO data 段都放進指定 RAMx 區域，則需要再在 linkscripts 文件夾里增加一個名為 main_rodata.ldt 文件。其內容如下，這里是告訴 FreeMarker 不要將 critical_code.o 里的 RO data 段放進主 RO data 段里一起處理。

*(EXCLUDE_FILE(*critical_code.o) .rodata)
*(EXCLUDE_FILE(*critical_code.o) .rodata.*)
*(EXCLUDE_FILE(*critical_code.o) .constdata)
*(EXCLUDE_FILE(*critical_code.o) .constdata.*)
. = ALIGN(${text_align});

然后 data.ldt 里改成如下這樣就可以了：

<#if memory.alias=="RAM2">
*critical_code.o(.text*)
*critical_code.o(.rodata .rodata.* .constdata .constdata.*)

至此，MCUXpresso IDE下高度靈活的FreeMarker鏈接文件模板機制痞子衡便介紹完畢了，掌聲在哪里~~~

審核編輯：湯梓紅