vexide is designed to be fault-tolerant, meaning it should be difficult for code to unintentionally fail in unexpected ways. Sometimes, that doesn’t go to plan and you need to find out why. This page will cover how to troubleshoot and fix unrecoverable failures in vexide programs.

There are two forms of errors that will cause a program to crash — panics and aborts (also known as exceptions).

Panics

A panic is an intentional decision made by the program to stop running due to some unrecoverable or unhandled error. Panics can occur for a variety of reasons, but typically happen when something goes wrong at the logic or runtime level. For example:

• Accessing an out-of-bounds index in an array.
• Unwrapping a Result or Option that contains an error or None.
• Failing an internal assertion (e.g. assert!(condition)).
• Violating the contract of a function with documented panic conditions.

When a panic occurs, vexide halts the program and prints a detailed message describing what happened to the Brain’s display and terminal.

A panic message is drawn to the screen along with a stack backtrace.

Diagnosis

The information that vexide gives us tells us both the cause and the location of the panic. This can be used to diagnose and fix the problem.

{...}
use vexide::prelude::*;
#[vexide::main]async fn main(_peripherals: Peripherals) {    panic!();}

panicked at main.rs:5:5:explicit panicstack backtrace:  0: 0x380832f  1: 0x380041b  2: 0x38064b7  3: 0x3804983  4: 0x3804913  5: 0x38061e3  6: 0x3803373  7: 0x380351b  8: 0x3800ed3  9: 0x3800c1f 10: 0x3800407note: Use a symbolizer to convert stack frames to human-readable function names.

In the example above, we are told that the panic originates from main.rs:5:5. This can be read as “main.rs, line 5, column 5”. Looking at line 5 of main.rs shows us that there is indeed a panic!() invocation.

use vexide::prelude::*;#[vexide::main]async fn main(_peripherals: Peripherals) {    panic!();
Panic occurred here.
}

The message we are given is simply “explicit panic”, which is the default message that Rust will use when invoking panic!() with no custom message. In practice, you will typically be given a more helpful message describing exactly what went wrong.

Panicking Functions

Aborts

An abort (also called an exception) is a serious, unexpected failure that occurs when the Brain’s user processor encounters an unrecoverable hardware or system-level error. Aborts are typically a sign of undefined behavior that occurs as a result of unsafe code being misused (either from your code or from a library you’re using).

An abort message is drawn to the screen along with a register dump and stack backtrace. This abort was caused by a null pointer dereference (hence the “writing to 0x0” message).

Unlike a panic which is raised intentionally by your program, an abort is triggered by the processor itself when something goes catastrophically wrong. Aborts give us less useful information about exactly where they occurred, making them harder to diagnose.

Abort Types

There are a few types of processor exceptions that will cause an abort. Knowing exactly what causes each of them isn’t necessarily required to find the location of the abort, but may help with identifying why it happened.

• Data Abort Exception: Occurs when the Brain tries to read or write to data memory in a way that isn’t allowed. Common causes include null pointer dereferences (accessing address 0x0), trying to access protected memory, and dangling pointers (use-after-free, double-free).
• Prefetch Abort Exception: Occurs when the Brain tries to fetch (execute) an instruction from memory that isn’t allowed or accessible. This can occur if the instruction is in a protected region, the memory is unmapped, or a jump address is incorrect.
• Undefined Instruction Exception: Occurs when the Brain encounters an instruction it doesn’t recognize or support. This could be caused by executing data as code, jumping to misaligned instructions, or running code compiled for the wrong architecture.

Using a Symbolizer