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
******************************************************************************/
dbprint
dbprint_documentation.h
Generated on Sun Nov 17 2019 20:57:52 for DeBugPrint (dbprint) by
1.8.13