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
#[cfg(all(feature = "encoding-raw", feature = "encoding-rzcobs"))]
compile_error!("Multiple `encoding-*` features are enabled. You may only enable one.");
#[cfg_attr(feature = "encoding-raw", path = "raw.rs")]
#[cfg_attr(not(feature = "encoding-raw"), path = "rzcobs.rs")]
mod inner;
// This wrapper struct is to avoid copypasting the public docs in all the impls.
/// Encode raw defmt frames for sending over the wire.
///
/// defmt emits "log frames", which are sequences of bytes. The raw log frame data
/// is then *encoded* prior to sending over the wire.
///
/// `Encoder` will encode the frames according to the currently selected
/// `encoding-*` Cargo feature. See `Cargo.toml` for the supported encodings
/// and their tradeoffs.
///
/// Encodings may perform two functions:
///
/// - Framing: Adds extra data to allow the encoder to know when each frame starts
/// and ends in the stream. Unframed log frames already contain enough information for
/// the decoder to know when they end, so framing is optional. However, without framing
/// the decoder must receive all bytes intact or it may "lose sync". With framing, it can
/// recover from missing/corrupted data, and can start decoding from the "middle" of an
/// already-running stream.
/// - Compression: The frame data has rather low entropy (for example, it contains many
/// zero bytes due to encoding all integers in fixed with, and will likely contain many
/// repetitions). Compression can decrease the on-the-wire required bandwidth.
///
/// defmt provides the `Encoder` separately instead of feeding already-encoded bytes
/// to the `Logger` because `Logger` implementations may decide to allow
/// concurrent logging from multiple "contexts" such as threads or interrupt
/// priority levels. In this case, the Logger implementation needs to create one
/// Encoder for each such context.
pub struct Encoder {
inner: inner::Encoder,
}
impl Encoder {
/// Create a new `Encoder`.
pub const fn new() -> Self {
Self {
inner: inner::Encoder::new(),
}
}
/// Start encoding a log frame.
///
/// `Logger` impls will typically call this from `acquire()`.
///
/// You may only call `start_frame` when no frame is currently being encoded.
/// Failure to do so may result in corrupted data on the wire.
///
/// The `write` closure will be called with the encoded data that must
/// be sent on the wire. It may be called zero, one, or multiple times.
pub fn start_frame(&mut self, write: impl FnMut(&[u8])) {
self.inner.start_frame(write)
}
/// Finish encoding a log frame.
///
/// `Logger` impls will typically call this from `release()`.
///
/// You may only call `end_frame` when a frame is currently being encoded.
/// Failure to do so may result in corrupted data on the wire.
///
/// The `write` closure will be called with the encoded data that must
/// be sent on the wire. It may be called zero, one, or multiple times.
pub fn end_frame(&mut self, write: impl FnMut(&[u8])) {
self.inner.end_frame(write)
}
/// Write part of data for a log frame.
///
/// `Logger` impls will typically call this from `write()`.
///
/// You may only call `write` when a frame is currently being encoded.
/// Failure to do so may result in corrupted data on the wire.
///
/// The `write` closure will be called with the encoded data that must
/// be sent on the wire. It may be called zero, one, or multiple times.
pub fn write(&mut self, data: &[u8], write: impl FnMut(&[u8])) {
self.inner.write(data, write)
}
}