DeBugPrint (dbprint)
Homebrew minimal low-level println/printf replacement
dbprint_documentation.h
Go to the documentation of this file.
1 /***************************************************************************//**
2  * @file dbprint_documentation.h
3  * @brief This file contains useful documentation closely related to dbprint.
4  * @version 7.0
5  * @author Brecht Van Eeckhoudt
6  *
7  * ******************************************************************************
8  *
9  * @section DeBugPrint
10  *
11  * DeBugPrint is a homebrew minimal low-level println/printf replacement.
12  * It can be used to to print text/values to uart without a lot of external
13  * libraries. The end goal was to use no external libraries (with methods
14  * like `itoa`) apart from the ones specific to the microcontroller.
15  *
16  * ******************************************************************************
17  *
18  * @section Doxygen
19  *
20  * These files have been made with [**Doxygen**](www.doxygen.org) comments above
21  * all methods to generate documentation. A combination of **Doxygen-specific tags**
22  * (preceded with an `@` symbol) and **markdown syntax** are supported to generate,
23  * for example, HTML-files.
24  *
25  * ******************************************************************************
26  *
27  * @section ENABLE Enable/disable dbprint using definition in `debug_dbprint.h`
28  *
29  * In the file `debug_dbprint.h` **dbprint UART functionality can be enabled/disabled**
30  * with the definition `#define DEBUG_DBPRINT`. If it's value is `0`, all dbprint
31  * functionality is disabled.
32  *
33  * @warning
34  * This means that the **only header file to include in your projects** for
35  * dbprint to work is@n
36  * `#include debug_dbprint.h`
37  *
38  * @note
39  * If you also want to use this definition to enable/disable dbprint statements
40  * in your code, please use the following convention:@n
41  * `#if DEBUG_DBPRINT == 1 // DEBUG_DBPRINT `@n
42  * `<your source code dbprint statements go here>`@n
43  * `#endif // DEBUG_DBPRINT`
44  *
45  * ******************************************************************************
46  *
47  * @section DBPRINT More info about dbprint (and VCOM)
48  *
49  * @note
50  * When using `dbprint` functionality, the following settings are used and
51  * can't be changed without editing the source code:@n
52  * - Baudrate = 115200
53  * - 8 databits
54  * - 1 stopbit
55  * - No parity
56  *
57  * VCOM is an on-board (SLSTK3400A) UART to USB converter alongside the Segger
58  * J-Link debugger, connected with microcontroller pins `PA0` (RX) and `PF2` (TX).
59  * This converter can then be used with Putty or another serial port program.
60  *
61  * @note
62  * When you want to debug using VCOM with interrupt functionality disabled, you
63  * can use the following initialization settings:@n
64  * `dbprint_INIT(USART1, 4, true, false);`
65  *
66  * @warning
67  * Setting the third argument to `true` indicates to the code that `PA9`
68  * (`EFM_BC_EN`) should be set high to enable the isolation switch on the PCB
69  * of the Happy Gecko to link `PA0` (RX) and `PF2` (TX) to the debugger. Don't
70  * use this pin yourself if you want to make use of the on-board UART to USB converter!
71  *
72  * ******************************************************************************
73  *
74  * @section ENERGY Energy profiler and dbprint
75  *
76  * The Energy profiler in Simplicity Studio seems to use VCOM somehow, change
77  * to using an external UART adapter if both the energy profiler and UART
78  * debugging are necessary at the same time!
79  *
80  * If the energy profiler was used and the code functionality was switched,
81  * physically re-plug the board to make sure VCOM UART starts working again!
82  *
83  * ******************************************************************************
84  *
85  * @section UART Alternate UART Functionality Pinout
86  *
87  * | Location | `#0` | `#1` | `#2` | `#3` | `#4` | `#5` | `#6` |
88  * | ---------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
89  * | `US0_RX` | `PE11` | | `PC10` | `PE12` | `PB08` | `PC01` | `PC01` |
90  * | `US0_TX` | `PE10` | | | `PE13` | `PB07` | `PC00` | `PC00` |
91  * | | | | | | | | |
92  * | `US1_RX` | `PC01` | | `PD06` | `PD06` | `PA00` | `PC02` | |
93  * | `US1_TX` | `PC00` | | `PD07` | `PD07` | `PF02` | `PC01` | |
94  *
95  * VCOM:
96  * - USART1 #4 (USART0 can't be used)
97  * - RX - `PA0`
98  * - TX - `PF2`
99  * - Isolation switch - `PA9` (`EFM_BC_EN`)
100  * (don't use this pin yourself when using the on-board UART to USB converter)
101  *
102  * ******************************************************************************
103  *
104  * @section Keywords
105  *
106  * @subsection Volatile
107  *
108  * The `volatile` type indicates to the compiler that the data is not normal memory,
109  * and could change at unexpected times. Hardware registers are often volatile,
110  * and so are variables which get changed in interrupts.@n
111  * Volatile variables are stored in *RAM*.
112  *
113  * @subsection Static
114  *
115  * @subsubsection VARIABLE Static variable
116  *
117  * During compile time (this is why we can't use variable length array's) memory
118  * gets reserved for this variable. The data itself gets put in the *data* segment
119  * of the memory (regular variables are put in the *stack* segment).@n
120  * It's best to keep the use of `static` variables to a minimum. One should ask
121  * himself the question if it's necessary to keep the variable constantly in the
122  * memory. If the answer is yes, a `static` variable is acceptable.@n
123  * A **static variable inside a function** keeps its value between invocations.
124  *
125  * @subsubsection FUNCTION Static global function
126  *
127  * The function is only "seen" in the file it's declared in. This means `static`
128  * can be used for methods the same way `private` is used for certain methods in C++.
129  *
130  * ******************************************************************************
131  *
132  * @section DATA Bits, bytes, nibbles and unsigned/signed integer value ranges
133  *
134  * - 1 nibble = 4 bits (`0b1111` = `0xF` )
135  * - 1 byte = 8 bits (`0b1111 1111` = `0xFF`)
136  *
137  * | Type | Alias | Size | Minimum value | Maximum value |
138  * | ---------- | ---------------- | ------- | -------------- | ----------------------------- |
139  * | `uint8_t` | `unsigned char` | 1 byte | 0 | 255 (`0xFF`) |
140  * | `uint16_t` | `unsigned short` | 2 bytes | 0 | 65 535 (`0xFFFF`) |
141  * | `uint32_t` | `unsigned int` | 4 bytes | 0 | 4 294 967 295 (`0xFFFF FFFF`) |
142  * | | | | | |
143  * | `int8_t` | `signed char` | 1 byte | -128 | 127 |
144  * | `int16_t` | `signed short` | 2 bytes | -32 768 | 32 767 |
145  * | `int32_t` | `signed int` | 4 bytes | -2 147 483 648 | 2 147 483 647 |
146  *
147  * - `-128` = `0x80` = `0b1000 0000` (If the left most bit is one, the sign of the number is negative)
148  * - `127` = `0x7F` = `0b0111 1111`
149  *
150  ******************************************************************************/