libbladerf-rs 0.5.0

Fully Rust native BladeRF driver
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! Pure Rust driver for the Nuand BladeRF1 SDR.
//!
//! This crate provides a complete, native-Rust driver for the BladeRF1 (x40/x115)
//! software-defined radio platform, with no dependency on the C libbladeRF library.
//! USB transport is handled via [nusb].
//!
//! # Feature flags
//!
//! | Flag        | Default | Effect                                  |
//! |-------------|---------|-----------------------------------------|
//! | `bladerf1`  | yes*    | BladeRF1 support (x40/x115)            |
//! | `bladerf2`  | no      | BladeRF2 support — **stub only**       |
//! | `xb100`     | yes     | XB-100 expansion board support         |
//! | `xb200`     | yes     | XB-200 transverter board support       |
//! | `xb300`     | yes     | XB-300 amplifier board support         |
//! | `smol`      | yes     | nusb `smol` runtime integration         |
//! | `tokio`     | no      | nusb `tokio` runtime integration        |
//!
//! \* Enabled implicitly by the `xb100`, `xb200`, or `xb300` features.
//!
//! # Session-based USB model
//!
//! The BladeRF1 FX3 firmware exposes three USB alternate settings, each providing
//! access to a different functional mode of the device:
//!
//! - **RfLink** — normal RF operation (streaming, tuning, gain, etc.)
//! - **SpiFlash** — SPI flash read/write/erase
//! - **Config** — FPGA loading and device configuration
//!
//! [`bladerf1::BladeRf1`] owns the device and grants access through session types that
//! borrow `&mut NiosCore`. The Rust borrow checker enforces that only one
//! session is active at a time, serializing all register I/O at compile time.
//!
//! # Sync and async
//!
//! Every I/O method returns a [`MaybeFuture`]: call `.wait()` to block the
//! current thread (native targets only) or `.await` it from async code. The
//! crate mirrors nusb's semantics: like every nusb-based driver it needs
//! nusb's `smol` (default) or `tokio` feature on native targets, selected
//! through the features of the same name. Streaming timeouts apply to the
//! blocking path only; awaited stream futures consume one USB completion per
//! await and are cancel-safe.
//!
//! On `wasm32-unknown-unknown` (WebUSB) there is no `.wait()`; open the
//! device with [`bladerf1::BladeRf1::from_device`] and shut it down with
//! [`bladerf1::BladeRf1::close`].
//!
//! # Entry point
//!
//! Open a device and obtain an [`bladerf1::RfLinkSession`] to begin RF operations:
//!
//! ```ignore
//! use libbladerf_rs::MaybeFuture;
//!
//! let mut dev = BladeRf1::from_first().wait()?;
//! let mut sess = dev.rf_link_session().wait()?;
//! sess.initialize(false).wait()?;
//! ```
//!
//! [nusb]: https://github.com/kevinmehall/nusb

#![deny(missing_docs)]

#[cfg(all(
    not(target_arch = "wasm32"),
    not(any(feature = "smol", feature = "tokio"))
))]
compile_error!(
    "libbladerf-rs requires the `smol` or `tokio` feature on native targets (`smol` is part of \
     the default features); nusb resolves blocking USB operations through one of these runtimes"
);

#[cfg(feature = "bladerf1")]
pub mod bladerf1;
#[cfg(feature = "bladerf2")]
pub mod bladerf2;
/// RX/TX channel selector.
pub mod channel;
pub mod error;
pub mod flash;
pub(crate) mod maybe_future;
pub(crate) mod nios_client;
pub mod protocol;
pub mod range;
pub(crate) mod usb;
/// Semantic version triple reported by firmware and FPGA.
pub mod version;
pub use channel::Channel;
pub use error::{Error, ErrorKind, Result};
pub use nusb;
pub use nusb::MaybeFuture;
pub use nusb::transfer::Buffer;
pub use version::SemanticVersion;
pub(crate) const fn khz(value: u32) -> u32 {
    value * 1_000
}
pub(crate) const fn mhz(value: u32) -> u32 {
    value * 1_000_000
}
#[allow(dead_code)]
pub(crate) const fn ghz(value: u32) -> u32 {
    value * 1_000_000_000
}