1//! A highly efficient logging framework that targets resource-constrained
2//! devices, like microcontrollers.
3//!
4//! Check out the defmt book at <https://defmt.ferrous-systems.com> for more
5//! information about how to use it.
6//!
7//! # Compatibility
8//!
9//! This is a defmt-0.3 compatbility crate. It depends upon `defmt-1.0` and
10//! re-exports the items that were available in `defmt-0.3`. This allows you to
11//! mix defmt-0.3 and defmt-1.0 within the same compilation.
12//!
13//! The `defmt` wire format might change between minor versions. Attempting to
14//! read a defmt stream with an incompatible version will result in an error,
15//! and any tool used to process that stream should first check for a symbol
16//! named like `_defmt_version_ = X`, where X indicates the wire format version
17//! in use.
18//!
19//! Updating your version of defmt might mean you also have to update your
20//! version of `defmt-print` or `defmt-decoder`.
21
22#![no_std]
23
24/// Just like the [`core::assert!`] macro but `defmt` is used to log the panic message
25///
26/// [`core::assert!`]: https://doc.rust-lang.org/core/macro.assert.html
27///
28/// If used, the format string must follow the defmt syntax (documented in [the manual])
29///
30/// [the manual]: https://defmt.ferrous-systems.com/macros.html
31pub use defmt10::assert;
32
33/// Just like the [`core::assert_eq!`] macro but `defmt` is used to log the panic message
34///
35/// [`core::assert_eq!`]: https://doc.rust-lang.org/core/macro.assert_eq.html
36///
37/// If used, the format string must follow the defmt syntax (documented in [the manual])
38///
39/// [the manual]: https://defmt.ferrous-systems.com/macros.html
40pub use defmt10::assert_eq;
41
42/// Just like the [`core::assert_ne!`] macro but `defmt` is used to log the panic message
43///
44/// [`core::assert_ne!`]: https://doc.rust-lang.org/core/macro.assert_ne.html
45///
46/// If used, the format string must follow the defmt syntax (documented in [the manual])
47///
48/// [the manual]: https://defmt.ferrous-systems.com/macros.html
49pub use defmt10::assert_ne;
50
51/// Just like the [`core::debug_assert!`] macro but `defmt` is used to log the panic message
52///
53/// [`core::debug_assert!`]: https://doc.rust-lang.org/core/macro.debug_assert.html
54///
55/// If used, the format string must follow the defmt syntax (documented in [the manual])
56///
57/// [the manual]: https://defmt.ferrous-systems.com/macros.html
58pub use defmt10::debug_assert;
59
60/// Just like the [`core::debug_assert_eq!`] macro but `defmt` is used to log the panic message
61///
62/// [`core::debug_assert_eq!`]: https://doc.rust-lang.org/core/macro.debug_assert_eq.html
63///
64/// If used, the format string must follow the defmt syntax (documented in [the manual])
65///
66/// [the manual]: https://defmt.ferrous-systems.com/macros.html
67pub use defmt10::debug_assert_eq;
68
69/// Just like the [`core::debug_assert_ne!`] macro but `defmt` is used to log the panic message
70///
71/// [`core::debug_assert_ne!`]: https://doc.rust-lang.org/core/macro.debug_assert_ne.html
72///
73/// If used, the format string must follow the defmt syntax (documented in [the manual])
74///
75/// [the manual]: https://defmt.ferrous-systems.com/macros.html
76pub use defmt10::debug_assert_ne;
77
78/// Just like the [`core::unreachable!`] macro but `defmt` is used to log the panic message
79///
80/// [`core::unreachable!`]: https://doc.rust-lang.org/core/macro.unreachable.html
81///
82/// If used, the format string must follow the defmt syntax (documented in [the manual])
83///
84/// [the manual]: https://defmt.ferrous-systems.com/macros.html
85pub use defmt10::unreachable;
86
87/// Just like the [`core::todo!`] macro but `defmt` is used to log the panic message
88///
89/// [`core::todo!`]: https://doc.rust-lang.org/core/macro.todo.html
90///
91/// If used, the format string must follow the defmt syntax (documented in [the manual])
92///
93/// [the manual]: https://defmt.ferrous-systems.com/macros.html
94pub use defmt10::todo;
95
96/// Just like the [`core::unimplemented!`] macro but `defmt` is used to log the panic message
97///
98/// [`core::unimplemented!`]: https://doc.rust-lang.org/core/macro.unimplemented.html
99///
100/// If used, the format string must follow the defmt syntax (documented in [the manual])
101///
102/// [the manual]: https://defmt.ferrous-systems.com/macros.html
103pub use defmt10::todo as unimplemented;
104
105/// Just like the [`core::panic!`] macro but `defmt` is used to log the panic message
106///
107/// [`core::panic!`]: https://doc.rust-lang.org/core/macro.panic.html
108///
109/// If used, the format string must follow the defmt syntax (documented in [the manual])
110///
111/// [the manual]: https://defmt.ferrous-systems.com/macros.html
112pub use defmt10::panic;
113
114/// Unwraps an `Option` or `Result`, panicking if it is `None` or `Err`.
115///
116/// This macro is roughly equivalent to `{Option,Result}::{expect,unwrap}` but invocation looks
117/// a bit different because this is a macro and not a method. The other difference is that
118/// `unwrap!`-ing a `Result<T, E>` value requires that the error type `E` implements the `Format`
119/// trait
120///
121/// The following snippet shows the differences between core's unwrap method and defmt's unwrap
122/// macro:
123///
124/// ```
125/// use defmt::unwrap;
126///
127/// # let option = Some(());
128/// let x = option.unwrap();
129/// let x = unwrap!(option);
130///
131/// # let result = Ok::<(), ()>(());
132/// let x = result.unwrap();
133/// let x = unwrap!(result);
134///
135/// let x = result.expect("text");
136/// let x = unwrap!(result, "text");
137///
138/// # let arg = ();
139/// let x = result.expect(&format!("text {:?}", arg));
140/// let x = unwrap!(result, "text {:?}", arg); // arg must be implement `Format`
141/// ```
142///
143/// If used, the format string must follow the defmt syntax (documented in [the manual])
144///
145/// [the manual]: https://defmt.ferrous-systems.com/macros.html
146pub use defmt10::unwrap;
147
148/// This is an alias for defmt's [`unwrap`] macro which supports messages like std's except.
149/// ```
150/// use defmt::expect;
151///
152/// # let result = Ok::<(), ()>(());
153/// # let arg = ();
154/// let x = result.expect(&format!("text {:?}", arg));
155/// let x = expect!(result, "text {:?}", arg); // arg must be implement `Format`
156/// ```
157///
158/// For the complete documentation see that of defmt's *unwrap* macro.
159// note: Linking to unwrap is broken as of 2024-10-09, it links back to expect
160pub use defmt10::unwrap as expect;
161
162/// Overrides the panicking behavior of `defmt::panic!`
163///
164/// By default, `defmt::panic!` calls `core::panic!` after logging the panic message using `defmt`.
165/// This can result in the panic message being printed twice in some cases. To avoid that issue use
166/// this macro. See [the manual] for details.
167///
168/// [the manual]: https://defmt.ferrous-systems.com/panic.html
169///
170/// # Inter-operation with built-in attributes
171///
172/// This attribute cannot be used together with the `export_name` or `no_mangle` attributes
173pub use defmt10::panic_handler;
174
175/// Creates an interned string ([`Str`]) from a string literal.
176///
177/// This must be called on a string literal, and will allocate the literal in the object file. At
178/// runtime, only a small string index is required to refer to the string, represented as the
179/// [`Str`] type.
180///
181/// # Example
182///
183/// ```
184/// let interned = defmt::intern!("long string literal taking up little space");
185/// ```
186///
187/// [`Str`]: struct.Str.html
188pub use defmt10::intern;
189
190/// Always logs data irrespective of log level.
191///
192/// Please refer to [the manual] for documentation on the syntax.
193///
194/// [the manual]: https://defmt.ferrous-systems.com/macros.html
195pub use defmt10::println;
196
197/// Logs data at *debug* level.
198///
199/// Please refer to [the manual] for documentation on the syntax.
200///
201/// [the manual]: https://defmt.ferrous-systems.com/macros.html
202pub use defmt10::debug;
203/// Logs data at *error* level.
204///
205/// Please refer to [the manual] for documentation on the syntax.
206///
207/// [the manual]: https://defmt.ferrous-systems.com/macros.html
208pub use defmt10::error;
209/// Logs data at *info* level.
210///
211/// Please refer to [the manual] for documentation on the syntax.
212///
213/// [the manual]: https://defmt.ferrous-systems.com/macros.html
214pub use defmt10::info;
215/// Logs data at *trace* level.
216///
217/// Please refer to [the manual] for documentation on the syntax.
218///
219/// [the manual]: https://defmt.ferrous-systems.com/macros.html
220pub use defmt10::trace;
221/// Logs data at *warn* level.
222///
223/// Please refer to [the manual] for documentation on the syntax.
224///
225/// [the manual]: https://defmt.ferrous-systems.com/macros.html
226pub use defmt10::warn;
227
228/// Just like the [`std::dbg!`] macro but `defmt` is used to log the message at `TRACE` level.
229///
230/// [`std::dbg!`]: https://doc.rust-lang.org/std/macro.dbg.html
231pub use defmt10::dbg;
232
233/// Writes formatted data to a [`Formatter`].
234///
235/// [`Formatter`]: struct.Formatter.html
236pub use defmt10::write;
237
238/// Defines the global defmt logger.
239///
240/// `#[global_logger]` needs to be put on a unit struct type declaration. This struct has to
241/// implement the [`Logger`] trait.
242///
243/// # Example
244///
245/// ```
246/// use defmt::{Logger, global_logger};
247///
248/// #[global_logger]
249/// struct MyLogger;
250///
251/// unsafe impl Logger for MyLogger {
252/// fn acquire() {
253/// # todo!()
254/// // ...
255/// }
256/// unsafe fn flush() {
257/// # todo!()
258/// // ...
259/// }
260/// unsafe fn release() {
261/// # todo!()
262/// // ...
263/// }
264/// unsafe fn write(bytes: &[u8]) {
265/// # todo!()
266/// // ...
267/// }
268/// }
269/// ```
270///
271/// [`Logger`]: trait.Logger.html
272pub use defmt10::global_logger;
273
274/// Defines the global timestamp provider for defmt.
275///
276/// This macro can be used to attach a timestamp or other data to every defmt message. Its syntax
277/// works exactly like the logging macros, except that no local variables can be accessed and the
278/// macro should be placed in a module instead of a function.
279///
280/// `timestamp!` must only be used once across the crate graph.
281///
282/// If no crate defines a timestamp, no timestamp will be included in the logged messages.
283///
284/// # Examples
285///
286/// ```
287/// # use core::sync::atomic::{AtomicU32, Ordering};
288///
289/// static COUNT: AtomicU32 = AtomicU32::new(0);
290/// defmt::timestamp!("{=u32:us}", COUNT.fetch_add(1, Ordering::Relaxed));
291/// ```
292pub use defmt10::timestamp;
293
294/// Generates a bitflags structure that can be formatted with defmt.
295///
296/// This macro is a wrapper around the [`bitflags!`] crate, and provides an (almost) identical
297/// interface. Refer to [its documentation] for an explanation of the syntax.
298///
299/// [its documentation]: https://docs.rs/bitflags/1/bitflags/
300///
301/// # Limitations
302///
303/// This macro only supports bitflags structs represented as one of Rust's built-in unsigned integer
304/// types (`u8`, `u16`, `u32`, `u64`, or `u128`). Custom types are not supported. This restriction
305/// is necessary to support defmt's efficient encoding.
306///
307/// # Examples
308///
309/// The example from the bitflags crate works as-is:
310///
311/// ```
312/// defmt::bitflags! {
313/// struct Flags: u32 {
314/// const A = 0b00000001;
315/// const B = 0b00000010;
316/// const C = 0b00000100;
317/// const ABC = Self::A.bits | Self::B.bits | Self::C.bits;
318/// }
319/// }
320///
321/// defmt::info!("Flags::ABC: {}", Flags::ABC);
322/// defmt::info!("Flags::empty(): {}", Flags::empty());
323/// ```
324pub use defmt10::bitflags;
325
326#[doc(inline)]
327pub use defmt10::{Debug2Format, Display2Format, Encoder, Formatter, Str};
328
329#[doc(inline)]
330pub use defmt10::{Format, Logger};
331
332#[doc(hidden)]
333pub use defmt10::export;
334
335#[doc(inline)]
336pub use defmt10::flush;
337