Crate probe_rs

Debugging toolset for embedded devices

Prerequisites

• Udev rules
• libusb

Examples

Halting the attached chip

use probe_rs::{Probe, Permissions};

// Get a list of all available debug probes.
let probes = Probe::list_all();

// Use the first probe found.
let mut probe = probes[0].open()?;

// Attach to a chip.
let mut session = probe.attach("nrf52", Permissions::default())?;

// Select a core.
let mut core = session.core(0)?;

// Halt the attached core.
core.halt(std::time::Duration::from_millis(10))?;

Reading from RAM

use probe_rs::{Session, Permissions};
use probe_rs::MemoryInterface;

let mut session = Session::auto_attach("nrf52", Permissions::default())?;
let mut core = session.core(0)?;

// Read a block of 50 32 bit words.
let mut buff = [0u32;50];
core.read_32(0x2000_0000, &mut buff)?;

// Read a single 32 bit word.
let word = core.read_word_32(0x2000_0000)?;

// Writing is just as simple.
let buff = [0u32;50];
core.write_32(0x2000_0000, &buff)?;

// of course we can also write 8bit words.
let buff = [0u8;50];
core.write_8(0x2000_0000, &buff)?;

probe-rs is built around 4 main interfaces: the Probe, Target, Session and Core structs.

Re-exports

• pub use crate::config::Target;

Modules

• architecture
  All the interface bits for the different architectures.
• config
  Target specific configuration
• debug
  Debugging support for probe-rs
• flashing
  Flash programming operations.
• rtt
  Host side implementation of the RTT (Real-Time Transfer) I/O protocol over probe-rs

Macros

• define_ap
  Defines a new typed access port.
• define_ap_register
  Defines a new typed access port register for a specific access port. Takes
• define_dp_register
  Defines a new debug port register for typed access.
• memory_mapped_bitfield_register
  Create a MemoryMappedRegister type, with the required method implementations for:

Structs

• Core
  Generic core handle representing a physical core on an MCU.
• CoreInformation
  An struct for storing the current state of a core.
• CoreRegister
  Describes a core (or CPU / hardware) register with its properties. Each architecture will have a set of general purpose registers, and potentially some special purpose registers. It also happens that some general purpose registers can be used for special purposes. For instance, some ARM variants allows the LR (link register / return address) to be used as general purpose register R14.“
• CoreRegisters
  A static array of all the registers (CoreRegister) that apply to a specific architecture.
• CoreState
  A generic core state which caches the generic parts of the core state.
• DebugProbeInfo
  Gathers some information about a debug probe which was found during a scan.
• DebugProbeSelector
  A struct to describe the way a probe should be selected.
• FakeProbe
  This is a mock probe which can be used for mocking things in tests or for dry runs.
• Permissions
  The Permissions struct represents what a Session is allowed to do with a target. Some operations can be irreversable, so need to be explicitly allowed by the user.
• Probe
  The Probe struct is a generic wrapper over the different probes supported.
• RegisterId
  The location of a CPU \register. This is not an actual memory address, but a core specific location that represents a specific core register.
• Session
  The Session struct represents an active debug session.

Enums

• Architecture
  The architecture family of a specific CoreType.
• AttachMethod
  The method that should be used for attaching.
• BreakpointCause
  When the core halts due to a breakpoint request, some architectures will allow us to distinguish between a software and hardware breakpoint.
• CoreStatus
  The status of the core.
• CoreType
  Type of a supported core.
• DebugProbeError
  This error occurs whenever the debug probe logic encounters an error while operating the relevant debug probe.
• DebugProbeType
  Denotes the type of a given DebugProbe.
• Error
  The overarching error type which contains all possible errors as variants.
• HaltReason
  The reason why a core was halted.
• InstructionSet
  Instruction set used by a core
• ProbeCreationError
  An error during probe creation accured. This is almost always a sign of a bad USB setup. Check UDEV rules if you are on Linux and try installing Zadig (This will disable vendor specific drivers for your probe!) if you are on Windows.
• RegisterRole
  This is used to label the register with a specific role that it plays during program execution and exception handling. This denotes the purpose of a register (e.g. return address), while the CoreRegister::name will contain the architecture specific label of the register.
• RegisterValue
  A value of a core register
• SemihostingCommand
  Indicates the operation the target would like the debugger to perform.
• SpecificCoreState
  The architecture specific core state.
• VectorCatchCondition
  When a core hits an exception, we halt the core.
• WireProtocol
  The protocol that is to be used by the probe when communicating with the target.

Traits

• CoreInterface
  A generic interface to control a MCU core.
• DebugProbe
  An abstraction over general debug probe functionality.
• MemoryInterface
  An interface to be implemented for drivers that allow target memory access.
• MemoryMappedRegister
  A memory mapped register, for instance ARM debug registers (DHCSR, etc).