Enum TunerError 

#[non_exhaustive]
pub enum TunerError {
    PllNotLocked {
        freq_hz: u32,
    },
    XtalIsZero,
    PllProgrammingFailed {
        backend: &'static str,
        freq_hz: u32,
        reason: &'static str,
    },
    I2cTransferFailed {
        operation: &'static str,
        got: usize,
        expected: usize,
    },
    ShadowCacheMiss {
        reg: u8,
    },
    UnsupportedFilterBandwidth {
        mode: u8,
    },
    InvalidGain {
        what: &'static str,
        detail: String,
    },
    Context {
        context: &'static str,
        source: Box<TunerError>,
    },
}

Typed sub-variant of RtlSdrError::Tuner.

Since 0.2, tuner-side failures carry this enum instead of a stringly-typed String. Consumers can match on the variants to discriminate failure modes (e.g. retry on PllNotLocked, fail-fast on XtalIsZero).

Some variants carry a &'static str backend field naming the IC family ("R82xx", "FC0012", "FC0013", "E4K", "FC2580"); use it to disambiguate when the same failure shape can happen on multiple ICs.

#[non_exhaustive] so adding a new variant in any future patch release is non-breaking. Per #16.

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.

PllNotLocked

PLL did not achieve lock for the requested LO frequency within the IC’s retry budget. Usually means the frequency is at an awkward divider boundary or the crystal/clock is misconfigured. Backends: R82xx, E4K.

Fields

freq_hz: u32

XtalIsZero

The configured crystal reference is zero, which would divide-by-zero in PLL math. Backends: R82xx (general), FC2580 (more specifically “crystal frequency too low”).

PllProgrammingFailed

PLL programming failed for an IC-specific reason that doesn’t share a common shape with other backends. Catch- all for “no valid divider found”, “computed PLL value exceeds register range”, “VCO out of range”, etc. The reason carries a static diagnostic string identifying the specific failure.

Backends: R82xx, FC0012, FC0013, FC2580, E4K.

Fields

backend: &'static str

freq_hz: u32

reason: &'static str

I2cTransferFailed

I2C transfer to the tuner returned fewer bytes than expected. operation names which step failed ("write", "read addr", "read data").

Fields

operation: &'static str

got: usize

expected: usize

ShadowCacheMiss

R82xx: register read attempted before the shadow cache was populated. Indicates a programming error in the crate (caller used the helper before init), not a hardware fault.

Fields

reg: u8

UnsupportedFilterBandwidth

FC2580: the configured filter-bandwidth mode index doesn’t match any supported bandwidth in the IC’s LUT. mode is the internal mode tag (not a Hz value).

Fields

mode: u8

InvalidGain

Gain parameter out of valid range. what names the parameter ("E4K IF gain stage", "E4K mixer gain", "E4K enhancement gain", etc.) and detail is a human-readable specifier describing the bad value. Backends: E4K (the only IC with multi-stage gain that validates per stage).

Fields

what: &'static str

detail: String

Context

Operation context wrapper. Used to add a &'static str prefix (e.g. "filter calibration") to an inner TunerError without losing the typed inner variant. #[source] makes the inner error walkable via std::error::Error::source for consumers using anyhow-style chained-error UI.

Coverage caveat (per audit pass-2 #74): Context only wraps TunerError — by construction it can’t carry a Usb(rusb::Error) or DeviceLost from the same operation. The R82xx filter-calibration path uses this shape today: failures from the calibration’s tuner-side math get wrapped (Context { context: "filter calibration", source: ... }), but a USB transport error during the same calibration sequence propagates as a bare RtlSdrError::Usb(...) with no calibration-context breadcrumb. Consumers building diagnostic UIs should match on both shapes if they want full coverage of the “what was the device doing when it failed” question.

Fields

context: &'static str

source: Box<TunerError>

Trait Implementations

impl Clone for TunerError

fn clone(&self) -> TunerError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TunerError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for TunerError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for TunerError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<TunerError> for RtlSdrError

fn from(source: TunerError) -> Self

Converts to this type from the input type.

impl PartialEq for TunerError

fn eq(&self, other: &TunerError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for TunerError

impl StructuralPartialEq for TunerError