1.. _module-pw_assert_basic: 2 3=============== 4pw_assert_basic 5=============== 6 7-------- 8Overview 9-------- 10This is a simple assert backend to implement the ``pw_assert`` facade which 11relies on a single function ``pw_assert_basic_HandleFailure`` handler facade 12which defaults to the ``basic_handler`` backend. Users may be interested in 13overriding this default in case they need to do things like transition to 14crash time logging or implementing application specific reset and/or hang 15behavior. 16 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---------------------------- 24Module Configuration Options 25---------------------------- 26The following configurations can be adjusted via compile-time configuration of 27this module, see the 28:ref:`module documentation <module-structure-compile-time-configuration>` for 29more details. 30 31.. c:macro:: PW_ASSERT_BASIC_ACTION 32 33 Controls what happens after an assert failure. Should be set to one of the 34 following options: 35 36 - PW_ASSERT_BASIC_ACTION_ABORT: Call std::abort() 37 - PW_ASSERT_BASIC_ACTION_EXIT: Call std::_Exit(-1) 38 - PW_ASSERT_BASIC_ACTION_LOOP: Loop forever 39 40 Defaults to abort. 41 42.. c:macro:: PW_ASSERT_BASIC_SHOW_BANNER 43 44 Controls whether ASCII art banner is printed on assert failure. 45 46 This defaults to enabled. 47 48.. c:macro:: PW_ASSERT_BASIC_USE_COLORS 49 50 Controls whether colors are used in assert message printed to console. 51 52 This defaults to enabled. 53 54.. _module-pw_assert_basic-custom_handler: 55 56Custom handler backend example 57------------------------------ 58Here is a typical usage example implementing a simple handler backend which uses 59a UART backed sys_io implementation to print during crash time and then reboots. 60Note that this example uses CMSIS and a psuedo STM HAL, as a backend implementer 61you are responsible for using whatever APIs make sense for your use case(s). 62 63.. code-block:: cpp 64 65 #include "cmsis.h" 66 #include "hal.h" 67 #include "pw_string/string_builder.h" 68 69 using pw::sys_io::WriteLine; 70 71 extern "C" void pw_assert_basic_HandleFailure( 72 [[maybe_unused]] const char* file_name, 73 [[maybe_unused]] int line_number, 74 [[maybe_unused]] const char* function_name, 75 const char* message, 76 ...) { 77 // Global interrupt disable for a single core microcontroller. 78 __disable_irq(); 79 80 // Re-initialize the UART to ensure it's safe to use at crash time. 81 HAL_UART_DeInit(sys_io_uart); 82 HAL_UART_Init(sys_io_uart); 83 84 WriteLine( 85 " Welp, that didn't go as planned. " 86 "It seems we crashed. Terribly sorry! Assert reason:"); 87 { 88 pw::StringBuffer<150> buffer; 89 buffer << " "; 90 va_list args; 91 va_start(args, format); 92 buffer.FormatVaList(format, args); 93 va_end(args); 94 WriteLine(buffer.view()); 95 } 96 97 // Reboot the microcontroller. 98 HAL_NVIC_SystemReset(); 99 } 100