docs ahead of 0.7 release

CHANGELOG.md

@@ -6,19 +6,21 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 #### Breaking API Changes
 
-- `GdbStubError` has been overhauled. Instead of being an `enum`, it is now an opaque `struct` with a handful of methods to extract concrete user-defined error data.
-  - _This change will enable future versions of `gdbstub` to fearlessly improve error messages and infrastructure without making semver breaking changes._
-- `Signal` is not longer an `enum`, and is instead a `struct` with a single `pub u8` field + a collection of associated constants.
+- `stub::GdbStubError` is now an opaque `struct` with a handful of methods to extract user-defined context (as opposed to being an `enum` that directly exposed all error internals to the user).
+  - _This change will enable future versions of `gdbstub` to fearlessly improve error messages and infrastructure without making semver breaking changes. See [\#112](https://github.com/daniel5151/gdbstub/pull/132) for more._
+- `common::Signal` is not longer an `enum`, and is instead a `struct` with a single `pub u8` field + a collection of associated constants.
   - _As a result, yet another instance of `unsafe` could be removed from the codebase!_
 - `Arch` API:
   - Entirely removed `single_step_behavior`. See [\#132](https://github.com/daniel5151/gdbstub/pull/132) for details and rationale
 - `Target` APIs:
   - `SingleThreadBase`/`MultiThreadBase`
     - `read_addrs` now returns a `usize` instead of a `()`, allowing implementations to report cases where only a subset of memory could be read.
+  - `HostIo`
+    - `bitflags` has been updated from `1.x` to `2.x`, affecting the type of `HostIoOpenFlags` and `HostIoOpenMode`
 
 #### Internal Improvements
 
-- `rustfmt`: Switched to using `imports_granularity = "Item"`
+- Reformatted codebase with nightly rustfmt using `imports_granularity = "Item"`
 
 # 0.6.6
 

README.md

@@ -4,13 +4,13 @@
 [![](https://docs.rs/gdbstub/badge.svg)](https://docs.rs/gdbstub)
 [![](https://img.shields.io/badge/license-MIT%2FApache-blue.svg)](./LICENSE)
 
-An ergonomic and easy-to-integrate implementation of the [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol) in Rust, with full `#![no_std]` support.
+An ergonomic, featureful, and easy-to-integrate implementation of the [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol) in Rust, with _no-compromises_ `#![no_std]` support.
 
 `gdbstub`  makes it easy to integrate powerful guest debugging support to your emulator / hypervisor / debugger / embedded project. By implementing just a few basic methods of the [`gdbstub::Target`](https://docs.rs/gdbstub/latest/gdbstub/target/ext/base/singlethread/trait.SingleThreadBase.html) trait, you can have a rich GDB debugging session up and running in no time!
 
 `gdbstub`'s API makes extensive use of a technique called [**Inlineable Dyn Extension Traits**](#zero-overhead-protocol-extensions) (IDETs) to expose fine-grained, zero-cost control over enabled GDB protocol features _without_ relying on compile-time features flags. Aside from making it effortless to toggle enabled protocol features, IDETs also ensure that any unimplemented features are guaranteed to be dead-code-eliminated in release builds!
 
-**If you're looking for a quick snippet of example code to see what a typical `gdbstub` integration might look like, check out [examples/armv4t/gdb/mod.rs](https://github.com/daniel5151/gdbstub/blob/master/examples/armv4t/gdb/mod.rs)**
+**If you're looking for a quick snippet of example code to see what a featureful `gdbstub` integration might look like, check out [examples/armv4t/gdb/mod.rs](https://github.com/daniel5151/gdbstub/blob/master/examples/armv4t/gdb/mod.rs)**
 
 -   [Documentation (gdbstub)](https://docs.rs/gdbstub)
 -   [Documentation (gdbstub_arch)](https://docs.rs/gdbstub_arch)

docs/transition_guide.md

@@ -6,6 +6,76 @@ This document does _not_ discuss any new features that might have been added bet
 
 > _Note:_ after reading through this doc, you may also find it helpful to refer to the in-tree `armv4t` and `armv4t_multicore` examples when transitioning between versions.
 
+## `0.6` -> `0.7`
+
+`0.7` is a fairly minimal "cleanup" release, landing a collection of small breaking changes that collectively improve various ergonomic issues in `gdbstub`'s API.
+
+The breaking changes introduced in `0.7` are generally trivial to fix, and porting from `0.6` to `0.7` shouldn't take more than ~10 minutes, at most.
+
+##### `stub::GdbStubError` Changes
+
+`stub::GdbStubError` is now an opaque `struct` with a handful of methods to extract user-defined context.
+
+**Please file an issue if your code required matching on concrete error variants aside from `TargetError` and `ConnectionError`!**.
+
+In contrast with the old version - which was an `enum` that directly exposed all error internals to the user - this new type will enable future versions of `gdbstub` to fearlessly improve error infrastructure without requiring semver breaking changes. See [\#112](https://github.com/daniel5151/gdbstub/pull/132) for more.
+
+Assuming you stuck to the example error handling described in the `gdbstub` getting started guide, adapting to the new type should be quite straightforward.
+
+
+```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)
+    }
+}
+
+// ==== 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)
+        }
+    }
+}
+```
+
+
+##### `{Single, Multi}ThreadBase::read_addrs` return value
+
+`read_addrs` now returns a `usize` instead of a `()`, allowing implementations to report cases where only a subset of memory could be read.
+
+In the past, the only way to handle these cases was by returning a `TargetError`. This provides an alternative mechanism, which may or may not be more appropriate for your particular use-case.
+
+When upgrading, the Rust compiler will emit a clear error message pointing out the updated function signature. The fix should be trivial.
+
+##### Removal of `Arch::single_step_behavior`
+
+See [\#132](https://github.com/daniel5151/gdbstub/pull/132) for more discussion on why this API was removed.
+
+This change only affects you if you're maintaining a custom `Arch` implementation (vs. using a community-maintained one via `gdbstub_arch`).
+
+The fix here is to simply remove the `Arch::single_step_behavior` impl.
+
+That's it! It's that easy.
+
+
 ## `0.5` -> `0.6`
 
 `0.6` introduces a large number of breaking changes to the public APIs, and will require quite a bit more more "hands on" porting than previous `gdbstub` upgrades.

src/lib.rs

@@ -1,6 +1,6 @@
-//! An ergonomic and easy-to-integrate implementation of the
-//! [GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol)
-//! in Rust, with full `#![no_std]` support.
+//! An ergonomic, featureful, and easy-to-integrate implementation of the [GDB
+//! Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol)
+//! in Rust, with no-compromises `#![no_std]` support.
 //!
 //! ## Feature flags
 //!
@@ -86,8 +86,8 @@
 //!
 //! ### The `Target` Trait
 //!
-//! The [`Target`](target::Target) trait describes how to control and modify
-//! a system's execution state during a GDB debugging session, and serves as the
+//! The [`Target`](target::Target) trait describes how to control and modify a
+//! system's execution state during a GDB debugging session, and serves as the
 //! primary bridge between `gdbstub`'s generic GDB protocol implementation and a
 //! specific target's project/platform-specific code.
 //!