Enum gdbstub::target::TargetError

#[non_exhaustive]pub enum TargetError<E> {
    NonFatal,
    Io(Error),
    Errno(u8),
    Fatal(E),
}

The error type for various methods on Target and it's assorted associated extension traits.

Error Handling over the GDB Remote Serial Protocol

The GDB Remote Serial Protocol has less-than-stellar support for error handling, typically taking the form of a single-byte errno-style error codes. Moreover, often times the GDB client will simply ignore the specific error code returned by the stub, and print a generic failure message instead.

As such, while it's certainly better to use appropriate error codes when possible (e.g: returning a EFAULT (14) when reading from invalid memory), it's often fine to simply return the more general TargetError::NonFatal instead, and avoid the headache of picking a "descriptive" error code. Under the good, TargetError::NonFatal is sent to the GDB client as a generic EREMOTEIO (121) error.

From and Into implementations

• From<()> -> TargetError::NonFatal
• From<io::Error> -> TargetError::Io(io::Error) (requires std feature)

When using a custom target-specific fatal error type, users are encouraged to write the following impl to simplify error handling in Target methods:

type MyTargetFatalError = ...; // Target-specific Fatal Error
impl From<MyTargetFatalError> for TargetError<MyTargetFatalError> {
    fn from(e: MyTargetFatalError) -> Self {
        TargetError::Fatal(e)
    }
}

Unfortunately, a blanket impl such as impl<T: Target> From<T::Error> for TargetError<T::Error> isn't possible, as it could result in impl conflicts. For example, if a Target decided to use () as it's fatal error type, then there would be conflict with the existing From<()> impl.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NonFatal

A non-specific, non-fatal error has occurred.

Io(Error)

I/O Error.

At the moment, this is just shorthand for TargetError::NonFatal(e.raw_os_err().unwrap_or(121)). Error code 121 corresponds to EREMOTEIO.

In the future, gdbstub may add support for the "QEnableErrorStrings" LLDB protocol extension, which would allow sending additional error context (in the form of an ASCII string) when an I/O error occurs. If this is something you're interested in, consider opening a PR!

Only available when the std feature is enabled.

Errno(u8)

An operation-specific non-fatal error code.

Fatal(E)

A target-specific fatal error.

WARNING: Returning this error will immediately halt the target's execution and return a GdbStubError::TargetError from GdbStub::run! Note that the debugging session will will not be terminated, and can be resumed by calling GdbStub::run after resolving the error and/or setting up a post-mortem debugging environment.

Trait Implementations

impl<E> From<()> for TargetError<E>

Converts a () into a TargetError::NonFatal.

fn from(_: ()) -> TargetError<E>

Performs the conversion.

impl<E> From<Error> for TargetError<E>

Converts a std::io::Error into a TargetError::Io.

fn from(e: Error) -> TargetError<E>

Performs the conversion.