third_party/pigweed/repo/pw_assert_basic/docs.rst

   1 .. _module-pw_assert_basic:
   2
   3 ===============
   4 pw_assert_basic
   5 ===============
   6
   7 --------
   8 Overview
   9 --------
  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.
  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 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   }