1. 從“printf 不輸出”說起1.1 一個典型的 STM32 重定向翻車現(xiàn)場我接到過不少類似的移植需求項目原本在 Keil MDK 里跑得好好的調(diào)試信息一直靠fputc重定向到串口輸出。某天團隊決定統(tǒng)一開發(fā)環(huán)境把工程遷移到 CLion配合 STM32CubeMX 生成的 CMake 工程用 OpenOCD 下載調(diào)試。代碼基本沒改編譯也過了唯獨調(diào)試第一句printf(hello\r\n)的時候串口助手上一片死寂。這個時候絕大多數(shù)人的第一反應(yīng)是查 UART 初始化、查波特率、查引腳復(fù)用甚至懷疑是不是 HAL 庫版本變了。但真正的問題往往不在這。等你把網(wǎng)上的示例代碼翻了一圈會發(fā)現(xiàn)很多 STM32CubeIDE、CLion 用戶給出的重定向函數(shù)不是fputc而是一個看起來不太“標(biāo)準(zhǔn)”的函數(shù)int _write(int file, char *ptr, int len)于是就有了文章的標(biāo)題在 CLion 這種 GNUGCC 工具鏈環(huán)境里為什么要重寫_write而不是我們用了很多年的fputc1.2 一句話先回答標(biāo)題里的問題因為 CLion 嵌入式工程最常用的工具鏈?zhǔn)莂rm-none-eabi-gcc它自帶的 C 運行庫是 Newlib 或 Newlib-nano。Newlib 把printf的最終輸出點設(shè)計在底層系統(tǒng)調(diào)用_write上而不是 C 標(biāo)準(zhǔn)庫的fputc。fputc是文件流層的單字符接口_write是運行庫向底層硬件輸出字節(jié)的總出口。你寫的printf在 Newlib 內(nèi)部根本不會去找外部的fputc符號所以單獨重寫fputc對printf來說等于沒寫。這個結(jié)論聽起來有點反直覺尤其是習(xí)慣了 Keil MicroLIB 的人。但只要你理解了標(biāo)準(zhǔn)庫的分層邏輯和工具鏈的調(diào)用路徑這個問題就不會再困擾你了。2. 先分清兩個函數(shù)fputc和_write真的不是一回事2.1fputc文件流層的“單字符搬運工”fputc是標(biāo)準(zhǔn) C 庫函數(shù)原型是int fputc(int ch, FILE *stream);它把單個字符ch寫入一個FILE流對象中。FILE在標(biāo)準(zhǔn)庫內(nèi)部往往帶了緩沖區(qū)、文件位置標(biāo)志、錯誤標(biāo)志等狀態(tài)。你可以把FILE理解成一條“傳送帶”而fputc就是這條傳送帶上一次搬一個零件的工人。問題在于這條傳送帶不是最終目的地。對于嵌入式裸機程序來說字符最終要去串口 TX 引腳、SWO 調(diào)試引腳或者某個自定義的外設(shè)緩沖區(qū)。標(biāo)準(zhǔn)庫的角色是把字符從printf格式化系統(tǒng)搬到一個“出口”這個出口通常就是系統(tǒng)調(diào)用層的某個函數(shù)。在很多桌面系統(tǒng)里這個出口是write()系統(tǒng)調(diào)用最終由操作系統(tǒng)驅(qū)動設(shè)備。在裸機嵌入式環(huán)境里沒有操作系統(tǒng)所以這個出口需要你自己實現(xiàn)否則標(biāo)準(zhǔn)庫不知道該把數(shù)據(jù)送到哪里。2.2_write標(biāo)準(zhǔn)庫和硬件之間的“系統(tǒng)調(diào)用閘口”_write不是標(biāo)準(zhǔn) C 庫函數(shù)而是 POSIX 系統(tǒng)調(diào)用層在嵌入式 C 庫里的投影。它的常見簽名是int _write(int file, char *ptr, int len);這里file是文件描述符ptr是指向輸出數(shù)據(jù)的指針len是要輸出的字節(jié)數(shù)。標(biāo)準(zhǔn)庫內(nèi)部會通過文件描述符來判斷你是往哪個流里寫比如說1通常對應(yīng)標(biāo)準(zhǔn)輸出 stdout2通常對應(yīng)標(biāo)準(zhǔn)錯誤 stderr。_write的職責(zé)就是把這len個字節(jié)交給實際的硬件設(shè)備然后返回實際寫入的字節(jié)數(shù)。你可以把_write理解成水廠的“總閥門”。你修改fputc像是挨家挨戶換水龍頭而printf的數(shù)據(jù)流壓根不經(jīng)過你家那根水管你修改_write才是直接改總閥門所有流過來的水都能被你接管。2.3 不同工具鏈到底調(diào)誰不同嵌入式工具鏈選用的 C 運行庫完全不同這直接決定了你該重寫哪個函數(shù)工具鏈常用運行庫printf 底層輸出接口常見重定向點Keil MDK ARMCCMicroLIB簡化 stdio最終落到fputcfputcIAR EWARMIAR DLIB與配置有關(guān)可能走__write__write或fputcARM Compiler 6 ARMCLANG標(biāo)準(zhǔn) ARM C 庫情況較復(fù)雜有些配置也走fputc取決于庫配置arm-none-eabi-gccNewlib / Newlib-nano內(nèi)部通過_write做底層輸出_writeCLion OpenOCD 常用組合Newlib-nano同上_write看到這張表你應(yīng)該就明白為什么網(wǎng)上資料會打架了。在 Keil 論壇里搜“printf 重定向”十有八九是讓改fputc在 STM32CubeIDE 或 CLion 的討論區(qū)里搜答案基本都會指向_write。不是誰對誰錯而是工具鏈不同。3. 為什么 CLion 里的printf不認(rèn)fputc3.1 CLion 嵌入式工程的實際工具鏈組合CLion 本身不是一個嵌入式編譯器而是一個 IDE 殼。它通過 CMake 調(diào)用外部工具鏈。絕大多數(shù) STM32 的 CLion 工程長這樣STM32CubeMX 生成 CMake 模板或 MakefileCMake 里通過toolchain.cmake指定編譯器路徑編譯器是arm-none-eabi-gcc鏈接時帶上-specsnano.specs、-specsnosys.specs用 OpenOCD GDB 完成下載和調(diào)試這里的核心變量是arm-none-eabi-gcc。它默認(rèn)配套的 C 庫是 Newlib。Newlib 的 stdio 實現(xiàn)不是直接調(diào)用fputc的而是在格式化完成之后把整塊緩沖區(qū)通過流對象內(nèi)部的寫函數(shù)最終交給系統(tǒng)調(diào)用層。所以CLion 工程里那個“應(yīng)該被重寫”的函數(shù)不由你的個人習(xí)慣決定而是由 Newlib 的源碼設(shè)計決定。3.2 Newlib 的隱藏緩沖層和輸出路徑Newlib 的printf調(diào)用鏈簡化來說是這樣的printf - vfprintf - 把格式化字符寫入 stdout 的 FILE 緩沖區(qū) - 緩沖區(qū)滿或 flush 時調(diào)用底層寫函數(shù) - _write在 Newlib 的實現(xiàn)里stdout本身就是一個帶緩沖區(qū)的FILE流。格式化出來的字符會先進入這塊緩沖區(qū)而不是一個字符一個字符地往硬件丟。等到緩沖區(qū)滿了或者有人調(diào)用fflush(stdout)或者輸出里包含了換行符且流被設(shè)置為行緩沖時緩沖區(qū)里的數(shù)據(jù)才會整體進入_write。那fputc在哪里如果在你的程序里主動調(diào)用fputc它也會最終走到_write。但問題在于printf內(nèi)部并不會去調(diào)用外部重定義的這個fputc符號它使用的是 Newlib 內(nèi)部專門為流寫操作準(zhǔn)備的一套機制。所以你在 Keil 里通過替換fputc來劫持字符輸出的方式在 Newlib 這個體系里完全對不上。我經(jīng)常打一個比方fputc是某個小區(qū)單元門禁的訪客登記本printf是小區(qū)外的城市主干道。你改了單元門禁的登記規(guī)則主干道上的車并不會因此變道它們只會開到真正的主干道出口去。3.3 半主機不動_write的另一顆雷如果你在 CLion 工程里不寫_write會發(fā)生什么一種可能是printf輸出完全沒反應(yīng)。另一種可能更嚇人程序一旦執(zhí)行到printf就卡死或者直接跳進 HardFault。這兩種情況背后往往是同一個原因半主機。半主機是 ARM 調(diào)試系統(tǒng)提供的一種機制允許開發(fā)板上的代碼通過調(diào)試通道使用開發(fā)機上的資源。Newlib 在沒有經(jīng)過重定向裁剪時_write的默認(rèn)實現(xiàn)可能指向半主機調(diào)用。也就是說你的printf數(shù)據(jù)被丟給了調(diào)試器而不是 UART。如果此時調(diào)試器沒有連接或者 OpenOCD 沒有配置相關(guān)半主機通道程序執(zhí)行到半主機指令時可能直接觸發(fā)異常。在舊的 STM32 開發(fā)經(jīng)歷里很多人會在工程里手動實現(xiàn)一整套 syscall 函數(shù)比如_sbrk、_read、_write目的就是打斷半主機的默認(rèn)路徑。現(xiàn)在更方便的方式是在鏈接時使用nosys.specs它會提供一個不做實際事情的空 syscall 庫。但如果你需要真實輸出仍然要提供自己的_write。3.4 只改fputc的“幸存者偏差”你可能會說我在 CLion 工程里也試過只改fputc好像有時候也有輸出這種情況確實存在但它很可能不是你以為的路徑。比如你的printf其實被某些代碼庫包裝過或者你用的是其他 C 庫配置又或者你看到的輸出其實是從調(diào)試器的 semihosting 控制臺里出來的而不是串口。還有一種情況是你在中斷服務(wù)函數(shù)里直接調(diào)用了putchar而某些移植層把putchar映射到了fputc這也會讓人誤以為重定向fputc對printf有效。換句話說只改fputc在 Newlib 環(huán)境下不是“絕對無效”而是“作用范圍極窄”。你無法保證printf、fprintf、puts這些常用函數(shù)都會走你寫的那個fputc。這種不確定性在工程里是很危險的所以正確做法是直接堵住總出口。4. 實操在 CLion STM32CubeMX 工程中重定向 printf4.1 最小可用的_write實現(xiàn)假設(shè)你已經(jīng)用 CubeMX 生成好了工程UART1 初始化正常。新建一個retarget.c代碼如下#include stdio.h #include unistd.h #include main.h #if defined(__GNUC__) !defined(__clang__) int _write(int file, char *ptr, int len) { if (file STDOUT_FILENO || file STDERR_FILENO) { HAL_UART_Transmit(huart1, (uint8_t *)ptr, len, HAL_MAX_DELAY); return len; } return -1; } #endif這段代碼做了幾件事判斷file是不是標(biāo)準(zhǔn)的 stdout 或 stderr。如果是就把ptr指向的len個字節(jié)通過 HAL 庫串口發(fā)送函數(shù)發(fā)出去。發(fā)送完成返回len告訴上層“我成功處理了所有字節(jié)”。return len這一步千萬不要丟。如果返回 0 或者小于len運行庫會認(rèn)為寫輸出失敗可能出現(xiàn)重復(fù)寫、截斷、錯誤狀態(tài)等奇怪問題。如果你的工程用了 C 源文件記得加extern Cextern C int _write(int file, char *ptr, int len) { // ... }否則 C 編譯器會對函數(shù)名做 name mangling鏈接時找不到符號。4.2 鏈接器選項與 CMake 配置光寫代碼還不夠CMake 鏈接選項也要配合。典型配置是在CMakeLists.txt里給目標(biāo)加上target_link_options(${PROJECT_NAME} PRIVATE --specsnano.specs --specsnosys.specs )如果你的printf里還要用浮點數(shù)格式比如%f而庫用的是 Newlib-nano那還要加上target_link_options(${PROJECT_NAME} PRIVATE -u _printf_float )這里簡單解釋一下nano.specs告訴鏈接器使用體積更小的 Newlib-nano它是給嵌入式系統(tǒng)裁剪過的 C 庫。nosys.specs告訴鏈接器使用一個不依賴半主機的空 syscall 實現(xiàn)可以把“程序跑進 semihosting 然后卡死”的問題擋在門外。-u _printf_float的作用是從庫里強制拉入浮點格式化代碼。Newlib-nano 默認(rèn)不啟用浮點打印用%f時會輸出空白或者錯誤結(jié)果。如果你的工程是從 CubeMX 生成的 CMake 工程通常 CubeMX 生成的鏈接命令里已經(jīng)帶了--specsnano.specs但你仍要確認(rèn)有沒有nosys.specs以及你的_write文件有沒有被編譯進目標(biāo)。4.3 換成 ITM/SWO 輸出只改_write內(nèi)部即可_write的好處是輸出目標(biāo)完全由你自己決定。同樣是這段printf如果你不想走 UART想通過 SWD 調(diào)試接口的 ITM/SWO 輸出只需要改函數(shù)內(nèi)部#include core_cm4.h // 具體頭文件按芯片系列 int _write(int file, char *ptr, int len) { if (file STDOUT_FILENO || file STDERR_FILENO) { for (int i 0; i len; i) { ITM_SendChar(ptr[i]); } return len; } return -1; }這就是為什么我建議統(tǒng)一用_write而不是fputc——你只需要維護一個出口所有標(biāo)準(zhǔn)輸出函數(shù)就都被接管了。以后想從串口換成 SWO只要改這一個函數(shù)業(yè)務(wù)代碼一行都不用動。4.4 從 Keil/MicroLIB 遷移代碼時怎么平滑過渡如果你維護的代碼同時要跑在 Keil 和 CLion 兩個環(huán)境里可以用編譯器宏做條件編譯避免同一個文件兩邊打架#if defined(__ARMCC_VERSION) !defined(__GNUC__) int fputc(int ch, FILE *f) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, HAL_MAX_DELAY); return ch; } #else int _write(int file, char *ptr, int len) { if (file STDOUT_FILENO || file STDERR_FILENO) { HAL_UART_Transmit(huart1, (uint8_t *)ptr, len, HAL_MAX_DELAY); return len; } return -1; } #endif這樣在 Keil 下用 ARMCC 編譯時走fputc在 CLion 下用 GCC/Newlib 編譯時走_write兩邊都是正統(tǒng)路徑不會互相干擾。這段代碼也是我實際項目里常用的一種寫法。5. 常見問題與排查清單5.1 printf 沒有任何輸出的排查路徑如果你的printf還是沒輸出按下面的順序檢查首先確認(rèn)_write是否真的被鏈接進最終程序。最簡單的方法是給_write加斷點或者在里面翻轉(zhuǎn)一個 GPIO甚至塞一個for循環(huán)改變某個全局變量。如果斷點沒觸發(fā)、GPIO 沒反應(yīng)說明你的_write沒有被鏈接進去或者這個目標(biāo)文件根本沒被編譯。其次檢查stdout緩沖。Newlib 的 stdout 帶緩沖如果程序在緩沖區(qū)滿之前就終止了數(shù)據(jù)可能壓根沒機會進入_write。可以在main開頭執(zhí)行setvbuf(stdout, NULL, _IONBF, 0);這會關(guān)閉 stdout 緩沖讓每個字符盡快進入_write。調(diào)試狀態(tài)下這是最省心的做法。正式工程里如果性能要求高再改回緩沖模式。然后檢查串口初始化。確認(rèn)huart1這個變量名和你工程里一致確認(rèn) UART GPIO 復(fù)用配置正確確認(rèn)串口助手的波特率和代碼一致。這些問題雖然基礎(chǔ)但發(fā)生頻率非常高。最后檢查接收端。ST-Link 的虛擬串口是否枚舉成功、串口助手是否選中了正確的 COM 口、地線是否連接好。很多“程序沒問題”的案例最后敗在這種物理環(huán)節(jié)上。5.2 程序一執(zhí)行 printf 就 HardFault這個癥狀十有八九和半主機有關(guān)。如果你在鏈接時沒有使用nosys.specs也沒有提供自己的_writeNewlib 的默認(rèn)實現(xiàn)會嘗試通過半主機通道輸出。沒有調(diào)試器配合時這會觸發(fā)異常。處理辦法很簡單在CMakeLists.txt里加上--specsnosys.specs或者寫一個真實可用的_write。兩者可以同時做實際項目里也是這么做的。還有一個容易被忽略的點如果你自己寫的_write里有問題比如HAL_UART_Transmit傳入了一個未初始化的huart1指針或者 UART 外設(shè)時鐘沒開也可能觸發(fā)異?；蛩赖?。排查時不要把所有鍋都甩給半主機。5.3 輸出出現(xiàn)中文亂碼 / write failure 提示中文亂碼的原因通常不在_write而在編碼。_write是字節(jié)流接口它不知道什么 UTF-8、GBK。如果你在源碼里寫了一個中文字符串源碼文件保存成 UTF-8編譯器會把中文字符按 UTF-8 編碼成多個字節(jié)。串口助手如果按 GBK 解碼看到的自然是一堆亂碼。解決辦法是把串口助手編碼切到 UTF-8或者干脆在嵌入式日志里優(yōu)先用英文和 ASCII 字符。有些熱詞里提到的fatal: write failure on stdout: bad file descriptor在嵌入式重定位場景下其實就是在提示你_write收到了一個你沒有處理過的文件描述符。比如你往stderr寫入數(shù)據(jù)但_write里只判斷了file 1沒處理file 2于是返回了-1。雖然這種提示在很多桌面日志里才常見但嵌入式側(cè)如果接了文件系統(tǒng)也會遇到類似問題。建議在_write里把STDOUT_FILENO和STDERR_FILENO都納入判斷避免誤傷。5.4 速查表癥狀、原因、處理癥狀常見原因處理方式printf 沒輸出_write未實現(xiàn)或未鏈接實現(xiàn)_write確認(rèn)目標(biāo)文件加入編譯printf 沒輸出stdout 緩沖未刷用\nfflush或setvbuf(_IONBF)跑到 printf 就卡死半主機調(diào)用缺少調(diào)試器鏈接選項加--specsnosys.specs浮點格式化輸出空白Newlib-nano 裁剪了浮點 printf加-u _printf_float中文顯示亂碼源碼編碼與終端解碼不一致統(tǒng)一 UTF-8或日志用 ASCII重寫_write后報重復(fù)符號工程里已有 syscalls.c 或類似文件刪除你沒在用的那一個C 工程鏈接不到_write缺少extern C給_write加 extern C 聲明6. 一點經(jīng)驗談重定向 printf 不只是改函數(shù)6.1 選_write還是fputc先看工具鏈以后遇到“printf 重定向”這類需求我的建議是先問一句你手上到底是用哪套編譯工具鏈如果是 Keil ARMCC MicroLIB那fputc就是正統(tǒng)路徑網(wǎng)上那些經(jīng)典例程可以直接用。如果是 CLion arm-none-eabi-gcc Newlib那_write才是你要接的地方。這個判斷 10 秒鐘就能做完但能省下你一整天的排查時間。我自己踩過最深的坑就是跨工程復(fù)制代碼時把 fputc 從一個 Keil 工程原封不動搬進 CMake 工程然后反復(fù)在串口配置和時鐘樹上做無用功。后來靜下心去看編譯器標(biāo)準(zhǔn)庫的源碼路徑才意識到問題根本不在硬件層而在運行庫的接口層。6.2 重定向之外建議順手做好日志緩沖和并發(fā)控制當(dāng)你成功用_write打通 printf 之后建議再做兩件事。第一把_write里阻塞發(fā)送改成非阻塞或加保護。HAL_UART_Transmit配合HAL_MAX_DELAY在調(diào)試階段很好用但如果你在定時器中斷或者高優(yōu)先級任務(wù)里調(diào)用 printf長時間阻塞可能影響系統(tǒng)實時性。更好的做法是維護一個環(huán)形緩沖區(qū)_write只把數(shù)據(jù)塞進緩沖區(qū)后臺用 DMA 或者中斷慢慢發(fā)送。這個改動在日志量大的項目里收益非常明顯。第二給日志系統(tǒng)留一個統(tǒng)一開關(guān)。比如在_write里加一個全局變量判斷日志是否使能或者封裝一個日志模塊讓你的業(yè)務(wù)代碼不要直接散落printf。這樣以后你要關(guān)閉日志、切換輸出通道、增加時間戳都能集中處理。我個人在實際項目里體會最深的一點是重定向函數(shù)雖然只有幾行但它決定了你整個調(diào)試鏈路是否穩(wěn)定。先花 20 分鐘搞清楚運行庫的出口在哪比在串口助手里換十種波特率更有價值。