Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_assert_basic: |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 2 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 3 | =============== |
| 4 | pw_assert_basic |
| 5 | =============== |
| 6 | |
| 7 | -------- |
| 8 | Overview |
| 9 | -------- |
Ewout van Bekkum | f7a5b51 | 2020-12-29 16:44:52 -0800 | [diff] [blame] | 10 | This is a simple assert backend to implement the ``pw_assert`` facade which |
| 11 | relies on a single function ``pw_assert_basic_HandleFailure`` handler facade |
| 12 | which defaults to the ``basic_handler`` backend. Users may be interested in |
| 13 | overriding this default in case they need to do things like transition to |
| 14 | crash time logging or implementing application specific reset and/or hang |
| 15 | behavior. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 16 | |
Ewout van Bekkum | f7a5b51 | 2020-12-29 16:44:52 -0800 | [diff] [blame] | 17 | .. attention:: |
| 18 | |
| 19 | This log backend comes with a very large ROM and potentially RAM cost. It is |
| 20 | intended mostly for ease of initial bringup. We encourage teams to use |
| 21 | tokenized asserts since they are much smaller both in terms of ROM and RAM. |
| 22 | |
| 23 | Custom handler backend example |
| 24 | ------------------------------ |
| 25 | Here is a typical usage example implementing a simple handler backend which uses |
| 26 | a UART backed sys_io implementation to print during crash time and then reboots. |
| 27 | Note that this example uses CMSIS and a psuedo STM HAL, as a backend implementer |
| 28 | you are responsible for using whatever APIs make sense for your use case(s). |
| 29 | |
| 30 | .. code-block:: cpp |
| 31 | |
| 32 | #include "cmsis.h" |
| 33 | #include "hal.h" |
| 34 | #include "pw_string/string_builder.h" |
| 35 | |
| 36 | using pw::sys_io::WriteLine; |
| 37 | |
| 38 | extern "C" void pw_assert_basic_HandleFailure( |
| 39 | [[maybe_unused]] const char* file_name, |
| 40 | [[maybe_unused]] int line_number, |
| 41 | [[maybe_unused]] const char* function_name, |
| 42 | const char* message, |
| 43 | ...) { |
| 44 | // Global interrupt disable for a single core microcontroller. |
| 45 | __disable_irq(); |
| 46 | |
| 47 | // Re-initialize the UART to ensure it's safe to use at crash time. |
| 48 | HAL_UART_DeInit(sys_io_uart); |
| 49 | HAL_UART_Init(sys_io_uart); |
| 50 | |
| 51 | WriteLine( |
| 52 | " Welp, that didn't go as planned. " |
| 53 | "It seems we crashed. Terribly sorry! Assert reason:"); |
| 54 | { |
| 55 | pw::StringBuffer<150> buffer; |
| 56 | buffer << " "; |
| 57 | va_list args; |
| 58 | va_start(args, format); |
| 59 | buffer.FormatVaList(format, args); |
| 60 | va_end(args); |
| 61 | WriteLine(buffer.view()); |
| 62 | } |
| 63 | |
| 64 | // Reboot the microcontroller. |
| 65 | HAL_NVIC_SystemReset(); |
| 66 | } |