### Run ARMv4T Emulator Example

Source: https://github.com/daniel5151/gdbstub/blob/master/examples/armv4t/README.md

Execute the armv4t emulator example using Cargo. Ensure the 'std' feature is enabled. Rebuilding test.elf locally might be necessary if debug symbols fail to load.

```bash
cargo run --example armv4t --features=std
```

--------------------------------

### Zero-Overhead Protocol Extensions Example

Source: https://github.com/daniel5151/gdbstub/blob/master/README.md

This example highlights the 'You don't pay for what you don't use' principle, where unimplemented protocol extensions are dead-code-eliminated in release builds.

```rust
// Assume 'MyTarget' implements a specific extension trait, e.g., 'MemoryRead'
// If 'MemoryRead' is not used, its implementation code will be removed.
struct MyTarget;

// Example of an extension trait implementation:
// impl MemoryRead for MyTarget { ... }
```

--------------------------------

### Basic gdbstub Integration Example

Source: https://github.com/daniel5151/gdbstub/blob/master/README.md

This snippet demonstrates a basic integration of gdbstub, showing how to set up the stub and handle debugging sessions. It requires implementing the `Target` trait.

```rust
use gdbstub::stub::{GdbStub, GdbStubState};
use gdbstub::target::Target;
use gdbstub::conn::Connection;

struct MyTarget;

impl Target for MyTarget {
    // ... implementation of Target trait methods ...
}

fn main() {
    let mut gdbstub = GdbStub::new(MyTarget);
    let mut state = GdbStubState::default();
    // ... connection handling and main loop ...
}
```

--------------------------------

### Implement Breakpoints for Emulator

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Implement `Breakpoints`, `SwBreakpoint`, and `HwWatchpoint` traits to manage software and hardware breakpoints and watchpoints. This example shows adding and removing breakpoints in an emulator.

```rust
use gdbstub::target::ext::breakpoints::{
    Breakpoints, BreakpointsOps,
    SwBreakpoint, SwBreakpointOps,
    HwWatchpoint, HwWatchpointOps, WatchKind,
};
use gdbstub::target::TargetResult;

impl Breakpoints for MyEmulator {
    #[inline(always)]
    fn support_sw_breakpoint(&mut self) -> Option<SwBreakpointOps<'_, Self>> {
        Some(self)
    }

    #[inline(always)]
    fn support_hw_watchpoint(&mut self) -> Option<HwWatchpointOps<'_, Self>> {
        Some(self)
    }
}

impl SwBreakpoint for MyEmulator {
    fn add_sw_breakpoint(
        &mut self,
        addr: u32,
        _kind: gdbstub_arch::arm::ArmBreakpointKind,
    ) -> TargetResult<bool, Self> {
        self.breakpoints.push(addr);
        Ok(true)
    }

    fn remove_sw_breakpoint(
        &mut self,
        addr: u32,
        _kind: gdbstub_arch::arm::ArmBreakpointKind,
    ) -> TargetResult<bool, Self> {
        self.breakpoints.retain(|&b| b != addr);
        Ok(true)
    }
}

impl HwWatchpoint for MyEmulator {
    fn add_hw_watchpoint(
        &mut self,
        addr: u32,
        len: u32,
        kind: WatchKind,
    ) -> TargetResult<bool, Self> {
        self.watchpoints.push((addr, len, kind));
        Ok(true)
    }

    fn remove_hw_watchpoint(
        &mut self,
        addr: u32,
        _len: u32,
        _kind: WatchKind,
    ) -> TargetResult<bool, Self> {
        self.watchpoints.retain(|(a, _, _)| *a != addr);
        Ok(true)
    }
}

```

--------------------------------

### BlockingEventLoop Implementation for GDB

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Provides an example implementation of the `BlockingEventLoop` trait for a custom emulator. This setup handles incoming GDB data and emulator steps, returning appropriate `Event` types or errors. The `run_gdb_session` function demonstrates how to use `GdbStub::run_blocking` and handle its results.

```rust
use gdbstub::stub::{GdbStub, DisconnectReason, SingleThreadStopReason};
use gdbstub::stub::run_blocking::{self, BlockingEventLoop, Event, WaitForStopReasonError};
use gdbstub::conn::{Connection, ConnectionExt};
use gdbstub::common::Signal;
use gdbstub::target::Target;

enum EmuEventLoop {}

impl BlockingEventLoop for EmuEventLoop {
    type Target = MyEmulator;
    type Connection = Box<dyn ConnectionExt<Error = std::io::Error>>;
    type StopReason = SingleThreadStopReason<u32>;

    fn wait_for_stop_reason(
        target: &mut MyEmulator,
        conn: &mut Self::Connection,
    ) -> Result<
        Event<SingleThreadStopReason<u32>>,
        WaitForStopReasonError<&'static str, std::io::Error>,
    > {
        loop {
            // Check for incoming GDB data first (non-blocking peek)
            if conn.peek().map(|b| b.is_some()).unwrap_or(true) {
                let byte = conn.read().map_err(WaitForStopReasonError::Connection)?;
                return Ok(Event::IncomingData(byte));
            }

            // Execute one emulator step
            if let Some(stop_reason) = target.step() {
                return Ok(Event::TargetStopped(stop_reason));
            }
        }
    }

    fn on_interrupt(
        _target: &mut MyEmulator,
    ) -> Result<Option<SingleThreadStopReason<u32>>, &'static str> {
        Ok(Some(SingleThreadStopReason::Signal(Signal::SIGINT)))
    }
}

fn run_gdb_session(
    gdb: GdbStub<MyEmulator, Box<dyn ConnectionExt<Error = std::io::Error>>>,
    mut emu: MyEmulator,
) {
    match gdb.run_blocking::<EmuEventLoop>(&mut emu) {
        Ok(DisconnectReason::Disconnect) => println!("GDB client disconnected."),
        Ok(DisconnectReason::TargetExited(code)) => println!("Target exited: {}", code),
        Ok(DisconnectReason::TargetTerminated(sig)) => println!("Target terminated: {}", sig),
        Ok(DisconnectReason::Kill) => println!("GDB sent kill."),
        Err(e) if e.is_target_error() => {
            eprintln!("Fatal target error: {}", e.into_target_error().unwrap());
        }
        Err(e) if e.is_connection_error() => {
            let (err, kind) = e.into_connection_error().unwrap();
            eprintln!("Connection error ({:?}): {}", kind, err);
        }
        Err(e) => eprintln!("gdbstub error: {}", e),
    }
}
```

--------------------------------

### SingleThreadStopReason Examples

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Illustrates various `SingleThreadStopReason` variants for different target halt conditions like step completion, breakpoints, watchpoints, signals, and exits. Ensure the `U` type parameter matches the architecture's address type.

```rust
use gdbstub::stub::SingleThreadStopReason;
use gdbstub::common::Signal;
use gdbstub::target::ext::breakpoints::WatchKind;

// Target stopped because it completed a single step
let reason: SingleThreadStopReason<u32> = SingleThreadStopReason::DoneStep;

// Target hit a software breakpoint
let reason: SingleThreadStopReason<u32> = SingleThreadStopReason::SwBreak(());

// Target hit a hardware watchpoint at address 0x2000
let reason: SingleThreadStopReason<u32> = SingleThreadStopReason::Watch {
    tid: (),
    kind: WatchKind::Write,
    addr: 0x2000,
};

// Target received SIGINT (e.g. from Ctrl-C)
let reason: SingleThreadStopReason<u32> = SingleThreadStopReason::Signal(Signal::SIGINT);

// Target process exited with code 0
let reason: SingleThreadStopReason<u32> = SingleThreadStopReason::Exited(0);
```

--------------------------------

### Implement Connection for no_std UART

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Manual implementation of the `Connection` trait for a no_std bare-metal TCP socket. This example shows writing a single byte to a specific memory-mapped UART register and flushing.

```rust
use gdbstub::conn::Connection;

// Manual Connection implementation for a no_std bare-metal TCP socket
pub struct UartConnection {
    // ...platform-specific UART handle...
}

impl Connection for UartConnection {
    type Error = &'static str;

    fn write(&mut self, byte: u8) -> Result<(), Self::Error> {
        // write a single byte to the UART TX register
        unsafe { core::ptr::write_volatile(0x4000_C000 as *mut u8, byte) };
        Ok(())
    }

    fn flush(&mut self) -> Result<(), Self::Error> {
        // UART has no software buffer, nothing to flush
        Ok(())
    }
}
```

--------------------------------

### Implement MultiThreadBase for Multi-Threaded Targets

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Implement `MultiThreadBase` to support multi-threaded debugging. Requires implementing `list_active_threads` and providing `Tid` for operations. This example shows register and memory access for multiple cores.

```rust
use gdbstub::target::ext::base::multithread::{MultiThreadBase, MultiThreadResume};
use gdbstub::common::{Signal, Tid};
use gdbstub::target::{TargetResult};

impl MultiThreadBase for MyMultiCoreEmulator {
    fn read_registers(
        &mut self,
        regs: &mut gdbstub_arch::arm::reg::ArmCoreRegs,
        tid: Tid,
    ) -> TargetResult<(), Self> {
        let core = self.cores[tid.get() - 1];
        regs.pc = core.pc;
        Ok(())
    }

    fn write_registers(
        &mut self,
        regs: &gdbstub_arch::arm::reg::ArmCoreRegs,
        tid: Tid,
    ) -> TargetResult<(), Self> {
        self.cores[tid.get() - 1].pc = regs.pc;
        Ok(())
    }

    fn read_addrs(&mut self, start_addr: u32, data: &mut [u8], _tid: Tid) -> TargetResult<usize, Self> {
        // shared address space across cores
        for (i, b) in data.iter_mut().enumerate() {
            *b = self.shared_mem[start_addr as usize + i];
        }
        Ok(data.len())
    }

    fn write_addrs(&mut self, start_addr: u32, data: &[u8], _tid: Tid) -> TargetResult<(), Self> {
        for (i, &b) in data.iter().enumerate() {
            self.shared_mem[start_addr as usize + i] = b;
        }
        Ok(())
    }

    fn list_active_threads(
        &mut self,
        register_thread: &mut dyn FnMut(Tid),
    ) -> Result<(), Self::Error> {
        register_thread(Tid::new(1).unwrap()); // core 0
        register_thread(Tid::new(2).unwrap()); // core 1
        Ok(())
    }

    #[inline(always)]
    fn support_resume(&mut self) -> Option<gdbstub::target::ext::base::multithread::MultiThreadResumeOps<'_, Self>> {
        Some(self)
    }
}

impl MultiThreadResume for MyMultiCoreEmulator {
    fn resume(&mut self) -> Result<(), Self::Error> {
        self.run_all_cores();
        Ok(())
    }

    fn clear_resume_actions(&mut self) -> Result<(), Self::Error> {
        self.resume_actions.clear();
        Ok(())
    }

    fn set_resume_action_continue(
        &mut self,
        tid: Tid,
        signal: Option<Signal>,
    ) -> Result<(), Self::Error> {
        self.resume_actions.insert(tid, signal);
        Ok(())
    }
}

```

--------------------------------

### Implement Custom Monitor Commands with `MonitorCmd`

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Extend the target to handle arbitrary `monitor <cmd>` commands from the GDB console. Output is sent back to GDB using `ConsoleOutput` and `outputln!` macros.

```rust
use gdbstub::target::ext::monitor_cmd::{MonitorCmd, ConsoleOutput};
use gdbstub::outputln;

impl MonitorCmd for MyEmulator {
    fn handle_monitor_cmd(
        &mut self,
        cmd: &[u8],
        mut out: ConsoleOutput<'_>,
    ) -> Result<(), Self::Error> {
        match cmd {
            b"reset" => {
                self.reset();
                outputln!(out, "Emulator reset.");
            }
            b"regs" => {
                outputln!(out, "PC=0x{:08x} SP=0x{:08x}", self.regs[15], self.regs[13]);
            }
            b"help" => {
                outputln!(out, "Available commands: reset, regs, help");
            }
            other => {
                outputln!(out, "Unknown command: {:?}", core::str::from_utf8(other));
            }
        }
        Ok(())
    }
}

// In GDB: (gdb) monitor reset     -> prints "Emulator reset."
// In GDB: (gdb) monitor regs      -> prints "PC=0x00008000 SP=0x20010000"
```

--------------------------------

### Migrate Connection API from 0.5.x to 0.6.0

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

Split the Connection implementation into base Connection and ConnectionExt traits. The read and peek methods are moved to ConnectionExt.

```rust
// ==== 0.5.x ====

impl Connection for MyConnection {
    type Error = MyError;

    fn write(&mut self, byte: u8) -> Result<(), Self::Error> { .. }
    fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error> { .. }
    fn read(&mut self) -> Result<u8, Self::Error> { .. }
    fn peek(&mut self) -> Result<Option<u8>, Self::Error> { .. }
    fn flush(&mut self) -> Result<(), Self::Error> { .. }
    fn on_session_start(&mut self) -> Result<(), Self::Error> { .. }
}

// ==== 0.6.0 ==== //

impl Connection for MyConnection {
    type Error = MyError;

    fn write(&mut self, byte: u8) -> Result<(), Self::Error> { .. }
    fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error> { .. }
    fn flush(&mut self) -> Result<(), Self::Error> { .. }
    fn on_session_start(&mut self) -> Result<(), Self::Error> { .. }
}

impl ConnectionExt for MyConnection {
    type Error = MyError;

    fn read(&mut self) -> Result<u8, Self::Error> { .. }
    fn peek(&mut self) -> Result<Option<u8>, Self::Error> { .. }
}

```

--------------------------------

### Handling GDB Protocol Extensions with IDETs

Source: https://github.com/daniel5151/gdbstub/blob/master/README.md

Demonstrates how Inlineable Dyn Extension Traits (IDETs) are used to manage GDB protocol extensions. This allows for fine-grained control and zero-cost abstraction over features.

```rust
use gdbstub::target::ext::base::singlethread::SingleThreadBase;

struct MyTarget;

impl SingleThreadBase for MyTarget {
    fn resume(&mut self, signal: gdbstub::target::ResumeAction) -> Result<(), gdbstub::target::TargetError> {
        // ... implementation ...
        Ok(())
    }

    // ... other methods for single-thread operations ...
}
```

--------------------------------

### Panic-Free Code Configuration

Source: https://github.com/daniel5151/gdbstub/blob/master/README.md

Details on configuring gdbstub for panic-free operation, crucial for embedded systems and resource-constrained environments.

```rust
// Configuration for panic-free operation often involves:
// 1. Ensuring all Target trait implementations are panic-free.
// 2. Using a minimal set of gdbstub features.
// 3. Avoiding operations that might panic in the underlying system.
```

--------------------------------

### Migrate `resume` from Gdbstub 0.5.x to 0.6.0

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

Illustrates the refactoring of the `resume` method from version 0.5.x to 0.6.0. In 0.6.0, the `resume` method's responsibility shifts to bookkeeping, with execution driving handled by upper API layers. Note the change in return type and the split of single-step functionality.

```rust
// ==== 0.5.x ====

impl SingleThreadOps for Emu {
    fn resume(
        &mut self,
        action: ResumeAction,
        gdb_interrupt: GdbInterrupt<'_>,
    ) -> Result<StopReason<u32>, Self::Error> {
        match action {
            ResumeAction::Step => self.do_single_step(),
            ResumeAction::Continue => self.block_until_stop_reason_or_interrupt(action, || gdb_interrupt.pending()),
            _ => self.handle_resume_with_signal(action),
        }
    }
}

// ==== 0.6.0 ====

impl SingleThreadBase for Emu {
    // resume has been split into a separate IDET
    #[inline(always)]
    fn support_resume(
        &mut self
    ) -> Option<SingleThreadResumeOps<Self>> {
        Some(self)
    }
}


impl SingleThreadResume for Emu {
    fn resume(
        &mut self,
        signal: Option<Signal>,
    ) -> Result<(), Self::Error> { // <-- no longer returns a stop reason!
        if let Some(signal) = signal {
            self.handle_signal(signal)?;
        }

        // upper layers of the `gdbstub` API will be responsible for "driving"
        // target execution - `resume` simply performs book keeping on _how_ the
        // target should be resumed.
        self.set_execution_mode(ExecMode::Continue)?;

        Ok(())
    }

    // single-step support has been split into a separate IDET
    #[inline(always)]
    fn support_single_step(
        &mut self
    ) -> Option<SingleThreadSingleStepOps<'_, Self>> {
        Some(self)
    }
}

impl SingleThreadSingleStep for Emu {
    fn step(&mut self, signal: Option<Signal>) -> Result<(), Self::Error> {
        if let Some(signal) = signal {
            self.handle_signal(signal)?;
        }

        self.set_execution_mode(ExecMode::Step)?;
        Ok(())
    }
}

```

--------------------------------

### Add gdbstub_arch Dependency

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Include gdbstub and gdbstub_arch in your Cargo.toml to use pre-made architecture definitions.

```toml
# Cargo.toml
[dependencies]
gdbstub = "0.7"
gdbstub_arch = "0.3"
```

--------------------------------

### Create GdbStub with Heap Buffer

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Simple construction of `GdbStub` using `GdbStub::new`. This method requires the `alloc` feature and uses a default 4096-byte heap buffer for packet handling.

```rust
use gdbstub::stub::{GdbStub, GdbStubBuilder};
use std::net::TcpStream;

// Simple construction (requires alloc feature, uses a 4096-byte heap buffer):
let connection: TcpStream = wait_for_gdb_connection(9001).unwrap();
let gdb = GdbStub::new(connection);
```

--------------------------------

### Create GdbStub with Static Packet Buffer

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Fine-grained construction of `GdbStub` using `GdbStub::builder`. This approach is compatible with `no_std` environments as it allows specifying a static buffer for packet handling, avoiding heap allocations.

```rust
static mut PACKET_BUF: [u8; 4096] = [0; 4096];
let connection = my_uart_connection();
let gdb = GdbStub::builder(connection)
    .with_packet_buffer(unsafe { &mut PACKET_BUF })
    .build()
    .expect("failed to build GdbStub");
```

--------------------------------

### Update TargetXmlOverride API from &str to &mut [u8]

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

Porting from `0.5.x` to `0.6.0` involves changing the `target_description_xml` method signature to use a `&mut [u8]` buffer. Helper functions `copy_to_buf` and `copy_range_to_buf` are introduced for managing data copying.

```rust
// ==== 0.5.x ==== //

impl target::ext::target_description_xml_override::TargetDescriptionXmlOverride for Emu {
    fn target_description_xml(&self) -> &str {
        r#"<target version="1.0"><!-- custom override string --><architecture>armv4t</architecture></target>"#
    }
}
```

```rust
// ==== 0.6.0 ==== //

pub fn copy_to_buf(data: &[u8], buf: &mut [u8]) -> usize {
    let len = data.len();
    let buf = &mut buf[..len];
    buf.copy_from_slice(data);
    len
}

pub fn copy_range_to_buf(data: &[u8], offset: u64, length: usize, buf: &mut [u8]) -> usize {
    let offset = match usize::try_from(offset) {
        Ok(v) => v,
        Err(_) => return 0,
    };
    let len = data.len();
    let data = &data[len.min(offset)..len.min(offset + length)];
    copy_to_buf(data, buf)
}

impl target::ext::target_description_xml_override::TargetDescriptionXmlOverride for Emu {
    fn target_description_xml(
        &self,
        offset: u64,
        length: usize,
        buf: &mut [u8],
    ) -> TargetResult<usize, Self> {
        let xml = r#"<target version="1.0"><!-- custom override string --><architecture>armv4t</architecture></target>"#
            .trim()
            .as_bytes();
        Ok(copy_range_to_buf(xml, offset, length, buf))
    }
}
```

--------------------------------

### Target Trait Implementation for gdbstub

Source: https://github.com/daniel5151/gdbstub/blob/master/README.md

Illustrates the essential methods required for implementing the `gdbstub::Target` trait. This includes handling memory access, register operations, and thread management.

```rust
use gdbstub::target::{Target, TargetError, RegisterId};
use gdbstub::arch::Arch;

struct MyTarget;

impl Target for MyTarget {
    type Arch = Arch;
    type Error = TargetError;

    fn read_register(&mut self, reg_id: RegisterId, buf: &mut [u8]) -> Result<(), Self::Error> {
        // ... implementation ...
        Ok(())
    }

    fn write_register(&mut self, reg_id: RegisterId, data: &[u8]) -> Result<(), Self::Error> {
        // ... implementation ...
        Ok(())
    }

    // ... other methods like read_memory, write_memory, etc. ...
}
```

--------------------------------

### Configure gdbstub for no_std

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Disable default features for gdbstub and gdbstub_arch in Cargo.toml for no_std environments. Provide a static packet buffer to GdbStubBuilder.

```toml
# Cargo.toml - no_std configuration
[dependencies]
gdbstub = { version = "0.7", default-features = false }
gdbstub_arch = { version = "0.3", default-features = false }
```

--------------------------------

### HwWatchpoint Operations

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Handles adding and removing hardware watchpoints.

```APIDOC
## HwWatchpoint Operations

Implements hardware watchpoint management.

### Methods

- **`add_hw_watchpoint(addr: u32, len: u32, kind: WatchKind) -> TargetResult<bool, Self>`**: Adds a hardware watchpoint at the specified address and length.
- **`remove_hw_watchpoint(addr: u32, _len: u32, _kind: WatchKind) -> TargetResult<bool, Self>`**: Removes a hardware watchpoint from the specified address.
```

--------------------------------

### Describe Target Memory Regions with `MemoryMap`

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Report the target's memory layout to GDB in XML format, enabling GDB to display correct read/write/execute attributes and classifications in its memory view.

```rust
use gdbstub::target::ext::memory_map::MemoryMap;
use gdbstub::target::TargetResult;

const MEMORY_MAP_XML: &[u8] = br#"<?xml version="1.0"?>
<!DOCTYPE memory-map PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
  "http://sourceware.org/gdb/gdb-memory-map.dtd">
<memory-map>
  <memory type="flash" start="0x00000000" length="0x40000">
    <property name="blocksize">0x400</property>
  </memory>
  <memory type="ram" start="0x20000000" length="0x8000"/>
  <memory type="rom" start="0x1FFF0000" length="0x10000"/>
</memory-map>"#;

impl MemoryMap for MyEmulator {
    fn memory_map_xml(
        &self,
        offset: u64,
        length: usize,
        buf: &mut [u8],
    ) -> TargetResult<usize, Self> {
        let data = MEMORY_MAP_XML;
        let offset = offset as usize;
        if offset >= data.len() {
            return Ok(0);
        }
        let end = (offset + length).min(data.len());
        let n = end - offset;
        buf[..n].copy_from_slice(&data[offset..end]);
        Ok(n)
    }
}
```

--------------------------------

### Drive GdbStub in a Non-Blocking Event Loop

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Use `GdbStubStateMachine` for async/await or interrupt-driven systems where a blocking thread is not feasible. This API requires manual driving of the state machine by pushing bytes and events.

```rust
use gdbstub::stub::state_machine::{GdbStubStateMachine, state};
use gdbstub::stub::{GdbStub, SingleThreadStopReason, DisconnectReason};

fn drive_gdbstub_nonblocking(
    gdb: GdbStub<MyEmulator, MyConnection>,
    target: &mut MyEmulator,
) -> Result<DisconnectReason, Box<dyn std::error::Error>> {
    let mut gdb_state = gdb.run_state_machine(target)?;

    loop {
        gdb_state = match gdb_state {
            // Stub is idle - waiting for a packet from GDB
            GdbStubStateMachine::Idle(mut gdb) => {
                // In a real async context this would be `await`-ed
                let byte = gdb.borrow_conn().read()?;
                gdb.incoming_data(target, byte)?
            }

            // Target is running - waiting for a stop event or incoming GDB packet
            GdbStubStateMachine::Running(mut gdb) => {
                // poll both the target and the connection
                if let Some(byte) = gdb.borrow_conn().peek()? {
                    let _ = gdb.borrow_conn().read()?;
                    gdb.incoming_data(target, byte)?
                } else if let Some(stop_reason) = target.poll_stop() {
                    let stop: SingleThreadStopReason<u32> = stop_reason;
                    gdb.report_stop(target, stop)?
                } else {
                    // nothing happened yet, keep looping
                    GdbStubStateMachine::Running(gdb)
                }
            }

            // GDB sent Ctrl-C
            GdbStubStateMachine::CtrlCInterrupt(gdb) => {
                let stop = Some(SingleThreadStopReason::Signal(gdbstub::common::Signal::SIGINT));
                gdb.interrupt_handled(target, stop)?
            }

            // Session has ended
            GdbStubStateMachine::Disconnected(gdb) => {
                return Ok(gdb.get_reason());
            }
        };
    }
}
```

--------------------------------

### SwBreakpoint Operations

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Handles adding and removing software breakpoints.

```APIDOC
## SwBreakpoint Operations

Implements software breakpoint management.

### Methods

- **`add_sw_breakpoint(addr: u32, _kind: ArmBreakpointKind) -> TargetResult<bool, Self>`**: Adds a software breakpoint at the specified address.
- **`remove_sw_breakpoint(addr: u32, _kind: ArmBreakpointKind) -> TargetResult<bool, Self>`**: Removes a software breakpoint from the specified address.
```

--------------------------------

### Implement Target with Architecture

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Use architecture-specific implementations from gdbstub_arch as the Target::Arch associated type. Access architecture-specific register types.

```rust
use gdbstub_arch::arm::Armv4t;
use gdbstub_arch::aarch64::AArch64;
use gdbstub_arch::x86::X86_64_SSE;
use gdbstub_arch::riscv::Riscv32;
use gdbstub_arch::mips::Mips;

// Use an arch as the Target::Arch associated type:
impl Target for MyRiscVEmulator {
    type Arch = gdbstub_arch::riscv::Riscv32;
    type Error = &'static str;

    fn base_ops(&mut self) -> gdbstub::target::ext::base::BaseOps<'_, Self::Arch, Self::Error> {
        gdbstub::target::ext::base::BaseOps::SingleThread(self)
    }
}

// Access architecture-specific register types:
use gdbstub_arch::riscv::reg::RiscvCoreRegs;
use gdbstub_arch::x86::reg::X86_64CoreRegs;
use gdbstub_arch::arm::reg::ArmCoreRegs;
use gdbstub_arch::arm::reg::id::ArmCoreRegId; // Per-register ID enum
```

--------------------------------

### Consolidate Breakpoint IDETs in GDBStub

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

In v0.5.0, breakpoint-related IDETs are consolidated under a single `Breakpoints` IDET. This change is organizational and does not require rewriting existing `add/remove_{sw_break,hw_break,watch}point` implementations. The `kind` parameter is new for `add_sw_breakpoint`.

```rust
// ==== 0.4.x ====

impl Target for Emu {
    fn sw_breakpoint(&mut self) -> Option<target::ext::breakpoints::SwBreakpointOps<Self>> {
        Some(self)
    }

    fn hw_watchpoint(&mut self) -> Option<target::ext::breakpoints::HwWatchpointOps<Self>> {
        Some(self)
    }
}

impl target::ext::breakpoints::SwBreakpoint for Emu {
    fn add_sw_breakpoint(&mut self, addr: u32) -> TargetResult<bool, Self> { ... }
    fn remove_sw_breakpoint(&mut self, addr: u32) -> TargetResult<bool, Self> { ... }
}

impl target::ext::breakpoints::HwWatchpoint for Emu {
    fn add_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
    fn remove_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
}
```

```rust
// ==== 0.5.0 ====

impl Target for Emu {
    // (New Method) //
    fn breakpoints(&mut self) -> Option<target::ext::breakpoints::BreakpointsOps<Self>> {
        Some(self)
    }
}

impl target::ext::breakpoints::Breakpoints for Emu {
    fn sw_breakpoint(&mut self) -> Option<target::ext::breakpoints::SwBreakpointOps<Self>> {
        Some(self)
    }

    fn hw_watchpoint(&mut self) -> Option<target::ext::breakpoints::HwWatchpointOps<Self>> {
        Some(self)
    }
}

// (Almost Unchanged) //
impl target::ext::breakpoints::SwBreakpoint for Emu {
    //                                            /-- New `kind` parameter
    //                                           \/
    fn add_sw_breakpoint(&mut self, addr: u32, _kind: arch::arm::ArmBreakpointKind) -> TargetResult<bool, Self> { ... }
    fn remove_sw_breakpoint(&mut self, addr: u32, _kind: arch::arm::ArmBreakpointKind) -> TargetResult<bool, Self> { ... }
}

// (Unchanged) //
impl target::ext::breakpoints::HwWatchpoint for Emu {
    fn add_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
    fn remove_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
}
```

--------------------------------

### Implement no_std GDB Stub with State Machine

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Manually implement the Connection trait and use GdbStubStateMachine for driving the GDB stub in a no_std environment, typically within an interrupt handler or polling loop.

```rust
#![no_std]
#![no_main]

use gdbstub::stub::GdbStub;
use gdbstub::stub::state_machine::GdbStubStateMachine;

static mut PACKET_BUF: [u8; 4096] = [0u8; 4096];

fn init_debug_session() {
    let conn = UartConnection::new(); // custom Connection impl

    let gdb = GdbStub::builder(conn)
        .with_packet_buffer(unsafe { &mut PACKET_BUF })
        .build()
        .unwrap();

    let mut target = MyBareMetalTarget::new();
    let mut gdb_sm = gdb.run_state_machine(&mut target).unwrap();

    // Drive the state machine from a UART interrupt handler or polling loop
    loop {
        gdb_sm = match gdb_sm {
            GdbStubStateMachine::Idle(mut inner) => {
                // Called from UART RX interrupt with received byte
                let byte = uart_receive_byte();
                inner.incoming_data(&mut target, byte).unwrap()
            }
            GdbStubStateMachine::Running(mut inner) => {
                if let Some(stop) = target.check_breakpoint() {
                    inner.report_stop(&mut target, stop).unwrap()
                } else {
                    GdbStubStateMachine::Running(inner)
                }
            }
            GdbStubStateMachine::CtrlCInterrupt(inner) => {
                inner.interrupt_handled(
                    &mut target,
                    Some(gdbstub::stub::SingleThreadStopReason::Signal(
                        gdbstub::common::Signal::SIGINT,
                    )),
                ).unwrap()
            }
            GdbStubStateMachine::Disconnected(_) => break,
        };
    }
}
```

--------------------------------

### Implement SingleThreadBase for MyEmulator

Source: https://context7.com/daniel5151/gdbstub/llms.txt

This snippet demonstrates implementing the `SingleThreadBase` trait for handling fundamental read/write operations on registers and memory. It includes error handling for invalid memory addresses.

```rust
use gdbstub::target::ext::base::singlethread::SingleThreadBase;
use gdbstub::target::{TargetResult, TargetError};

impl SingleThreadBase for MyEmulator {
    fn read_registers(
        &mut self,
        regs: &mut gdbstub_arch::arm::reg::ArmCoreRegs,
    ) -> TargetResult<(), Self> {
        regs.pc = self.regs[15];
        regs.sp = self.regs[13];
        // ...populate all other registers...
        Ok(())
    }

    fn write_registers(
        &mut self,
        regs: &gdbstub_arch::arm::reg::ArmCoreRegs,
    ) -> TargetResult<(), Self> {
        self.regs[15] = regs.pc;
        self.regs[13] = regs.sp;
        Ok(())
    }

    fn read_addrs(&mut self, start_addr: u32, data: &mut [u8]) -> TargetResult<usize, Self> {
        // Return Err(TargetError::Errno(14)) for EFAULT if address is invalid
        if start_addr >= 0xDEAD_0000 {
            return Err(TargetError::Errno(14)); // EFAULT
        }
        for (i, b) in data.iter_mut().enumerate() {
            *b = self.mem[start_addr as usize + i];
        }
        Ok(data.len())
    }

    fn write_addrs(&mut self, start_addr: u32, data: &[u8]) -> TargetResult<(), Self> {
        if start_addr >= 0xDEAD_0000 {
            return Err(TargetError::Errno(14));
        }
        for (i, &b) in data.iter().enumerate() {
            self.mem[start_addr as usize + i] = b;
        }
        Ok(())
    }
}

```

--------------------------------

### Implement Target Trait for MyEmulator

Source: https://context7.com/daniel5151/gdbstub/llms.txt

This snippet shows how to implement the `Target` trait for a custom emulator struct. It defines the architecture and error type, and opts into breakpoint support.

```rust
use gdbstub::target::{Target, TargetResult, TargetError};
use gdbstub::target::ext::base::BaseOps;
use gdbstub::target::ext::base::singlethread::{SingleThreadBase, SingleThreadResume};
use gdbstub::target::ext::breakpoints::{Breakpoints, SwBreakpoint, BreakpointsOps, SwBreakpointOps};
use gdbstub::common::Signal;

struct MyEmulator {
    mem: [u8; 65536],
    regs: [u32; 16],
    breakpoints: Vec<u32>,
    running: bool,
}

impl Target for MyEmulator {
    type Arch = gdbstub_arch::arm::Armv4t;
    type Error = &'static str;

    #[inline(always)]
    fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error> {
        BaseOps::SingleThread(self)
    }

    // Opt-in to breakpoint support
    #[inline(always)]
    fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>> {
        Some(self)
    }
}

impl SingleThreadBase for MyEmulator {
    fn read_registers(
        &mut self,
        regs: &mut gdbstub_arch::arm::reg::ArmCoreRegs,
    ) -> TargetResult<(), Self> {
        regs.r.copy_from_slice(&self.regs[0..13]);
        regs.sp = self.regs[13];
        regs.lr = self.regs[14];
        regs.pc = self.regs[15];
        Ok(())
    }

    fn write_registers(
        &mut self,
        regs: &gdbstub_arch::arm::reg::ArmCoreRegs,
    ) -> TargetResult<(), Self> {
        self.regs[0..13].copy_from_slice(&regs.r);
        self.regs[13] = regs.sp;
        self.regs[14] = regs.lr;
        self.regs[15] = regs.pc;
        Ok(())
    }

    fn read_addrs(&mut self, start_addr: u32, data: &mut [u8]) -> TargetResult<usize, Self> {
        for (i, byte) in data.iter_mut().enumerate() {
            *byte = self.mem[(start_addr as usize + i) % self.mem.len()];
        }
        Ok(data.len())
    }

    fn write_addrs(&mut self, start_addr: u32, data: &[u8]) -> TargetResult<(), Self> {
        for (i, &byte) in data.iter().enumerate() {
            self.mem[(start_addr as usize + i) % self.mem.len()] = byte;
        }
        Ok(())
    }

    #[inline(always)]
    fn support_resume(&mut self) -> Option<gdbstub::target::ext::base::singlethread::SingleThreadResumeOps<'_, Self>> {
        Some(self)
    }
}

impl SingleThreadResume for MyEmulator {
    fn resume(&mut self, signal: Option<Signal>) -> Result<(), Self::Error> {
        if signal.is_some() {
            return Err("signals not supported");
        }
        self.running = true;
        Ok(())
    }
}

```

--------------------------------

### Breakpoints

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Manages software and hardware breakpoints and watchpoints for the target.

```APIDOC
## Breakpoints — `SwBreakpoint`, `HwBreakpoint`, `HwWatchpoint`

The `Breakpoints` IDET groups all breakpoint types. Enable individual breakpoint kinds by implementing the corresponding sub-trait and returning `Some(self)` from the relevant `support_*` method inside `Breakpoints`.

### Methods

- **`support_sw_breakpoint(&mut self) -> Option<SwBreakpointOps<'_, Self>>`**: Returns software breakpoint operations if supported.
- **`support_hw_watchpoint(&mut self) -> Option<HwWatchpointOps<'_, Self>>`**: Returns hardware watchpoint operations if supported.
```

--------------------------------

### MultiThreadResume Operations

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Handles resume operations for multi-threaded targets, including continuing execution and managing resume actions.

```APIDOC
## MultiThreadResume Operations

Implements resume operations for multi-threaded targets.

### Methods

- **`resume() -> Result<(), Self::Error>`**: Resumes all cores.
- **`clear_resume_actions() -> Result<(), Self::Error>`**: Clears all resume actions.
- **`set_resume_action_continue(tid: Tid, signal: Option<Signal>) -> Result<(), Self::Error>`**: Sets the resume action to continue for a specific thread.
```

--------------------------------

### Handle Target Errors in GDB Stub

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Distinguish between non-fatal (errno) and fatal errors in target methods using TargetError. Non-fatal errors allow the GDB session to continue.

```rust
use gdbstub::target::{TargetError, TargetResult};

fn example_read_addrs(
    &mut self,
    start_addr: u32,
    data: &mut [u8],
) -> TargetResult<usize, Self> {
    // Non-fatal: report EFAULT to GDB, session continues
    if start_addr < 0x1000 {
        return Err(TargetError::Errno(14)); // EFAULT
    }

    // Non-fatal: generic non-specific error (sent as EREMOTEIO=121)
    if self.is_locked() {
        return Err(TargetError::NonFatal);
    }

    // Non-fatal: I/O error (std feature only)
    #[cfg(feature = "std")]
    if let Err(e) = self.mmap_file.seek(std::io::SeekFrom::Start(start_addr as u64)) {
        return Err(TargetError::Io(e)); // maps to appropriate errno
    }

    // Fatal: terminates the GDB session immediately
    if self.is_corrupted() {
        return Err(TargetError::Fatal("emulator state corrupted"));
    }

    for (i, b) in data.iter_mut().enumerate() {
        *b = self.mem[start_addr as usize + i];
    }
    Ok(data.len())
}
```

--------------------------------

### Extract Single-Register Access to New Trait in GDBStub

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

In v0.5.0, single-register access methods (`read_register`, `write_register`) are moved to a separate `SingleRegisterAccess` trait as they are not a required part of the GDB protocol. This is an organizational change. The `tid` parameter is new for these methods.

```rust
// ==== 0.4.x ====

impl SingleThreadOps for Emu {
    fn read_register(&mut self, reg_id: arch::arm::reg::id::ArmCoreRegId, dst: &mut [u8]) -> TargetResult<(), Self> { ... }
    fn write_register(&mut self, reg_id: arch::arm::reg::id::ArmCoreRegId, val: &[u8]) -> TargetResult<(), Self> { ... }
}
```

```rust
// ==== 0.5.0 ====

impl SingleThreadOps for Emu {
    // (New Method) //
    fn single_register_access(&mut self) -> Option<target::ext::base::SingleRegisterAccessOps<(), Self>> {
        Some(self)
    }
}

impl target::ext::base::SingleRegisterAccess<()> for Emu {
    //                           /-- New `tid` parameter (ignored on single-threaded systems)
    //                          \/
    fn read_register(&mut self, _tid: (), reg_id: arch::arm::reg::id::ArmCoreRegId, dst: &mut [u8]) -> TargetResult<(), Self> { ... }
    fn write_register(&mut self, _tid: (), reg_id: arch::arm::reg::id::ArmCoreRegId, val: &[u8]) -> TargetResult<(), Self> { ... }
}
```

--------------------------------

### MultiThreadBase Operations

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Implements base operations for multi-threaded targets, requiring a Tid parameter for all operations and the implementation of `list_active_threads`.

```APIDOC
## MultiThreadBase — Base Operations for Multi-Threaded Targets

`MultiThreadBase` mirrors `SingleThreadBase` but adds a `Tid` parameter to all operations and requires implementing `list_active_threads` to enumerate live threads. Used when `Target::base_ops` returns `BaseOps::MultiThread(self)`.

### Methods

- **`read_registers(regs: &mut ..., tid: Tid) -> TargetResult<(), Self>`**: Reads registers for a specific thread.
- **`write_registers(regs: &..., tid: Tid) -> TargetResult<(), Self>`**: Writes registers for a specific thread.
- **`read_addrs(start_addr: u32, data: &mut [u8], tid: Tid) -> TargetResult<usize, Self>`**: Reads data from a specific address for a given thread.
- **`write_addrs(start_addr: u32, data: &[u8], tid: Tid) -> TargetResult<(), Self>`**: Writes data to a specific address for a given thread.
- **`list_active_threads(register_thread: &mut dyn FnMut(Tid))`**: Registers active threads.
- **`support_resume() -> Option<MultiThreadResumeOps<'_, Self>>`**: Returns resume operations if supported.
```

--------------------------------

### Migrate GdbStubError Handling from 0.6 to 0.7

Source: https://github.com/daniel5151/gdbstub/blob/master/docs/transition_guide.md

Update error handling to use the new opaque GdbStubError struct in version 0.7. Use `is_target_error()` and `is_connection_error()` methods to check error types and `into_target_error()` or `into_connection_error()` to extract them.

```rust
// ==== 0.6.x ==== //

match gdb.run_blocking::<EmuGdbEventLoop>(&mut emu) {
    Ok(disconnect_reason) => { ... },
    Err(GdbStubError::TargetError(e)) => {
        println!("target encountered a fatal error: {}", e)
    }
    Err(e) => {
        println!("gdbstub encountered a fatal error: {}", e)
    }
}
```

```rust
// ==== 0.7.0 ==== //

match gdb.run_blocking::<EmuGdbEventLoop>(&mut emu) {
    Ok(disconnect_reason) => { ... },
    Err(e) => {
        if e.is_target_error() {
            println!(
                "target encountered a fatal error:જી{}",
                e.into_target_error().unwrap()
            )
        } else if e.is_connection_error() {
            let (e, kind) = e.into_connection_error().unwrap();
            println!("connection error: {:?} - {}", kind, e,)
        } else {
            println!("gdbstub encountered a fatal error: {}", e)
        }
    }
}
```

--------------------------------

### Wait for GDB Connection over TCP

Source: https://context7.com/daniel5151/gdbstub/llms.txt

Waits for a GDB client to connect over TCP on a specified port. This function is suitable for std environments and returns a `TcpStream` which automatically implements the `Connection` trait.

```rust
use std::net::{TcpListener, TcpStream};

fn wait_for_gdb_connection(port: u16) -> std::io::Result<TcpStream> {
    let sockaddr = format!("localhost:{}", port);
    eprintln!("Waiting for GDB on {:?}...", sockaddr);
    let sock = TcpListener::bind(sockaddr)?;
    let (stream, addr) = sock.accept()?;
    eprintln!("Debugger connected from {}", addr);
    Ok(stream) // TcpStream automatically implements Connection
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.