panic-serial

Prints panic information via a serial port, then goes into an infinite loop.

Status: experimental; biased towards Arduino

This crate implements a panic handler which prints panic information on a serial port (or other type of output - see below).

Why?

Seeing panic messages (or at least their location) is essential to make sense of what went wrong.

I don't want to live without it.

What is printed?

There are three levels of detail at which panics can be printed, depending on how much space you are willing to waste in your firmware. The level of detail is chosen by selecting feature flags:

• location: prints location information. Example:

  Panic at src/main.rs:91:9
  

• message: prints the actual full panic message. This uses core::fmt under the hood, so expect an increase in firmware size. Example:

  attempt to subtract with overflow
  

• full == location & message: Combined location and message. Example:

  Panic at src/main.rs:91:9: attempt to subtract with overflow
  

• (no features): if no features are chosen, a static message is printed. Example:

  PANIC !
  

  This option is easiest on firmware size.

Usage

An example project for Arduino Uno based on these instructions can be found here: https://github.com/nilclass/panic-serial-example.

1. Remove any existing panic handler. For example if you are currently using panic_halt, remove that dependency & it's usage.
2. Add panic-serial dependency to your project:

   # Check "What is printed" section above for features to choose
   cargo add panic-serial --features full
   

3. Within your main.rs (or elsewhere at top level) invoke the impl_panic_handler macro:

   panic_serial::impl_panic_handler!(
     // This is the type of the UART port to use for printing the message:
     arduino_hal::usart::Usart<
       arduino_hal::pac::USART0,
       arduino_hal::port::Pin<arduino_hal::port::mode::Input, arduino_hal::hal::port::PD0>,
       arduino_hal::port::Pin<arduino_hal::port::mode::Output, arduino_hal::hal::port::PD1>
     >
   );
   

This will do two things:

• define the actual panic handler
• define a function called share_serial_port_with_panic, which we'll use in the next step

4. Call share_serial_port_with_panic within main:

   #[arduino_hal::entry]
   fn main() -> ! {
     // ...
     let serial = arduino_hal::default_serial!(dp, pins, 57600);
     // this gives ownership of the serial port to panic-serial. We receive a mutable reference to it though, so we can keep using it.
     let serial = share_serial_port_with_panic(serial);
     // continue using serial:
     ufmt::uwriteln!(serial, "Hello there!\r").unwrap();
   
     // ...
   }
   

How does it work?

The impl_panic_handler macro defines a mutable static PANIC_PORT: Option<$your_type>. When you call share_serial_port_with_panic, that option gets filled, and you get back PANIC_PORT.as_mut().unwrap().

If a panic happens, the panic handler either just loops (if you never called share_serial_port_with_panic), or prints the panic info to the given port. It does this in two steps:

1. call port.flush()
2. use ufmt (or core::fmt) to print the fragments.

Technically this works with anything that implements ufmt::uWrite and has a flush() method.

How unsafe is this?

When you find out, please tell me.

License: MIT