小printf大作用（用日誌打印的方式調試程序）

轉載自蝸窩科技，www.wowotech.net。

前言

      一般來說，初學編程者所寫的第一個程序，就是使用printf打印“Hello world”。其實printf的功效遠不只這些，在程序調試方面，printf也有非常大的用處。 

      “蝸蝸”在接觸Linux driver開發之前，學習過桌面程序開發（如Turbo C、Visual C等），也從事了一段時間的嵌入式軟件開發。這些開發有一個共同點，對調試工具非常依賴，如桌面程序的Debugger（調試器）、嵌入式開發的仿真器（JTAG等）。還依稀記得，剛工作時，爲了插空使用仿真器，不得不趁週末別人不工作時加班使用。直到後來從事Linux driver開發、見識到了printk的魅力之後，多年來，就再也沒有使用過仿真器或者調試器了。 

      下面我就總結一下使用日誌打印輔助debug的心得。 

日誌打印的注意事項

      在編寫程序後，我們可以隨手在需要的地方加入打印信息，同時需要考慮如下事項：

      1. 日誌輸出是有代價的，特別是在嵌入式系統，或者對執行時序要求較高的應用場景。因此

          a) 只有在需要的地方加入，不能濫用

          b) 一定要有一個全局的開關，在不需要或者產品發佈的時候，關閉輸出，或者降低日誌輸出的頻率

      2. 日誌輸出需要有優先級控制，例如：發生錯誤時的日誌優先級最高，一般都要輸出；一些重要的提示，優先級中等，可能會在debug版的軟件中打開；一些不重要的提示，可能只會在需要的時候（例如跟蹤bug）打開

      3. 不要直接使用printf（或者printk）。日誌輸出的目標是多樣的，例如通過printf輸出到屏幕、通過串口輸出到串口調試助手、通過文件操作寫入到文件等等。要通過重定義的方式，將所有的日誌輸出指令定義到合適的輸出路徑，當需要修改輸出路徑的時候，只要修改重定義的部分即可。否則需要在整個代碼中修改，就麻煩了

      4. 最好爲每個軟件模塊提供單獨的日誌輸出開關，以增加調試的靈活性

      5. 很多時候，日誌輸出語句，可以部分代替代碼註釋的功能

 

日誌打印的實現

      結合上面的注意事項，我們可以按照如下步驟實現一個小型的日誌輸出系統。

      Step1. 新建debug.h（如果只是在PC上使用printf，則只需要一個頭文件即可。如果有需要文件或者串口操作，可以在這個基礎上增加debug.c，這裏暫時不再描述）

      Step2. 定義一個宏開關，用於控制日誌輸出的開關

1. /*
2. * debug control, you can switch on (delete 'x' suffix)
3. * to enable log output and assert mechanism
4. */
5. #define CONFIG_ENABLE_DEBUG

      Step3. 定義ERR、INFO、DEBUG三個日誌級別

1. /*
2. * debug level,
3. * if is DEBUG_LEVEL_DISABLE, no log is allowed output,
4. * if is DEBUG_LEVEL_ERR, only ERR is allowed output,
5. * if is DEBUG_LEVEL_INFO, ERR and INFO are allowed output,
6. * if is DEBUG_LEVEL_DEBUG, all log are allowed output,
7. */
8. enum debug_level {
9. DEBUG_LEVEL_DISABLE = 0,
10. DEBUG_LEVEL_ERR,
11. DEBUG_LEVEL_INFO,
12. DEBUG_LEVEL_DEBUG
13. };

      Step4. 如果使用系統的printf，需要包含stdio.h，並將printf重定義爲PRINT（無論是Windows還是Linux，皆是如此，如果是嵌入式平臺，可以自定義PRINT接口）

1. /* it can be change to others, such as file operations */
2. #include <stdio.h>
3. #define PRINT printf

      Step5. 定義一個宏，用於定義日誌輸出級別

1. /*
2. * the macro to set debug level, you should call it
3. * once in the files you need use debug system
4. */
5. #define DEBUG_SET_LEVEL(x) static int debug = x

需要在每一個需要日誌輸出的C文件中調用，如下：

1. /*
2. * define the debug level of this file,
3. * please see 'debug.h' for detail info
4. */
5. DEBUG_SET_LEVEL(DEBUG_LEVEL_ERR);

 

      Step6. 定義ASSERT、ERR、INFO、DEBUG等宏 

1. #define ASSERT() \
2. do { \
3. PRINT("ASSERT: %s %s %d", \
4. __FILE__, __FUNCTION__, __LINE__); \
5. while (1); \
6. } while (0)
8. #define ERR(...) \
9. do { \
10. if (debug >= DEBUG_LEVEL_ERR) { \
11. PRINT(__VA_ARGS__); \
12. } \
13. } while (0)
15. …

      Step7. 在需要日誌輸出的C文件中，包含debug.h，並定義所需的日誌級別。就可以在需要的時候輸出日誌信息了

1. debug_test.c
2. -----------------------------------------------------
3. #include "debug.h"
5. /*
6. * define the debug level of this file,
7. * please see 'debug.h' for detail info
8. */
9. DEBUG_SET_LEVEL(DEBUG_LEVEL_ERR);
11. int main(void) {
12. ERR("This is a error message\n");
13. INFO("This is a info message\n");
14. DEBUG("This is a debug message\n");
16. ASSERT();
17. return 0;
18. }

      Step8. 可以根據需要，修改容許輸出的日誌級別

 

      以上所有的源代碼和測試代碼都可以在下面獲取：

       https://github.com/wowotech/wowolib/tree/master/debug