Embedded System Design 2 - Project
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 6.2
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  * @note
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  * VCOM is an on-board (SLSTK3400A) UART to USB converter alongside the Segger
50  * J-Link debugger, connected with microcontroller pins `PA0` (RX) and `PF2` (TX).
51  * This converter can then be used with Putty or another serial port program.
52  *
53  * @note
54  * When you want to debug using VCOM with interrupt functionality disabled, you
55  * can use the following initialization settings:@n
56  * `dbprint_INIT(USART1, 4, true, false);`
57  *
58  * @note
59  * When using `dbprint` functionality, the following settings are used:@n
60  * - Baudrate = 115200
61  * - 8 databits
62  * - 1 stopbit
63  * - No parity
64  *
65  * ******************************************************************************
66  *
67  * @section ENERGY Energy profiler and dbprint
68  *
69  * The Energy profiler in Simplicity Studio seems to use VCOM somehow, change
70  * to using an external UART adapter if both the energy profiler and UART
71  * debugging are necessary at the same time!
72  *
73  * If the energy profiler was used and the code functionality was switched,
74  * physically re-plug the board to make sure VCOM UART starts working again!
75  *
76  * ******************************************************************************
77  *
78  * @section UART Alternate UART Functionality Pinout
79  *
80  * | Location | `#0` | `#1` | `#2` | `#3` | `#4` | `#5` | `#6` |
81  * | ---------- | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
82  * | `US0_RX` | `PE11` | | `PC10` | `PE12` | `PB08` | `PC01` | `PC01` |
83  * | `US0_TX` | `PE10` | | | `PE13` | `PB07` | `PC00` | `PC00` |
84  * | | | | | | | | |
85  * | `US1_RX` | `PC01` | | `PD06` | `PD06` | `PA00` | `PC02` | |
86  * | `US1_TX` | `PC00` | | `PD07` | `PD07` | `PF02` | `PC01` | |
87  *
88  * VCOM:
89  * - USART1 #4 (USART0 can't be used)
90  * - RX - `PA0`
91  * - TX - `PF2`
92  *
93  * ******************************************************************************
94  *
95  * @section Keywords
96  *
97  * @subsection Volatile
98  *
99  * The `volatile` type indicates to the compiler that the data is not normal memory,
100  * and could change at unexpected times. Hardware registers are often volatile,
101  * and so are variables which get changed in interrupts.
102  *
103  * @subsection Static
104  *
105  * - **Static variable inside a function:** The variable keeps its value between invocations.
106  * - **Static global variable or function:** The variable or function is only "seen" in the file it's declared in.
107  *
108  * ******************************************************************************
109  *
110  * @section DATA Bits, bytes, nibbles and unsigned/signed integer value ranges
111  *
112  * - 1 nibble = 4 bits (`0b1111` = `0xF` )
113  * - 1 byte = 8 bits (`0b1111 1111` = `0xFF`)
114  *
115  * | Type | Alias | Size | Minimum value | Maximum value |
116  * | ---------- | ---------------- | ------- | -------------- | ----------------------------- |
117  * | `uint8_t` | `unsigned char` | 1 byte | 0 | 255 (`0xFF`) |
118  * | `uint16_t` | `unsigned short` | 2 bytes | 0 | 65 535 (`0xFFFF`) |
119  * | `uint32_t` | `unsigned int` | 4 bytes | 0 | 4 294 967 295 (`0xFFFF FFFF`) |
120  * | | | | | |
121  * | `int8_t` | `signed char` | 1 byte | -128 | 127 |
122  * | `int16_t` | `signed short` | 2 bytes | -32 768 | 32 767 |
123  * | `int32_t` | `signed int` | 4 bytes | -2 147 483 648 | 2 147 483 647 |
124  *
125  ******************************************************************************/