From 0eb3993cb09cd43b8230a3deaf3e2e351025e787 Mon Sep 17 00:00:00 2001 From: Ben Ford Date: Fri, 6 Dec 2024 15:34:38 +0000 Subject: [PATCH] Add warnings to design pages in book --- book/src/acq-rel.md | 2 ++ book/src/deserialization.md | 2 ++ book/src/design-format.md | 2 ++ book/src/design-global-logger.md | 2 ++ book/src/design-timestamp.md | 2 ++ book/src/duplicates.md | 2 ++ book/src/eval-order.md | 2 ++ book/src/interning.md | 2 ++ book/src/linker-sections.md | 2 ++ book/src/log-frame.md | 2 ++ book/src/lookup.md | 2 ++ book/src/preemption.md | 2 ++ book/src/re-entrancy.md | 2 ++ book/src/ser-array.md | 2 ++ book/src/ser-bitfield.md | 2 ++ book/src/ser-bool.md | 1 + book/src/ser-format-slice.md | 2 ++ book/src/ser-format.md | 2 ++ book/src/ser-integers.md | 2 ++ book/src/ser-istr.md | 2 ++ book/src/ser-slices.md | 2 ++ book/src/ser-str.md | 2 ++ book/src/serialization.md | 2 ++ 23 files changed, 45 insertions(+) diff --git a/book/src/acq-rel.md b/book/src/acq-rel.md index 43af3a48..d5efef85 100644 --- a/book/src/acq-rel.md +++ b/book/src/acq-rel.md @@ -1,5 +1,7 @@ # Acquire-release +> ⚠️ The design and implementation chapter is outdated ⚠️ + One solution to the re-entrancy issue that's deadlock-free is to make the log macros *take* the logger and hold it until it's done with it. In case of nesting any inner take attempt will silently fail. diff --git a/book/src/deserialization.md b/book/src/deserialization.md index c8e2bdf0..9544716a 100644 --- a/book/src/deserialization.md +++ b/book/src/deserialization.md @@ -1,5 +1,7 @@ # Deserialization +> ⚠️ The design and implementation chapter is outdated ⚠️ + The host has received the log data (binary data). How to make sense of it? diff --git a/book/src/design-format.md b/book/src/design-format.md index baf47653..9bb72656 100644 --- a/book/src/design-format.md +++ b/book/src/design-format.md @@ -1,5 +1,7 @@ # Single Format trait +> ⚠️ The design and implementation chapter is outdated ⚠️ + `core::fmt` has several formatting traits, like `Hex` and `Bin`. These appear as different formatting parameters, like `:x` and `:b`, in format strings and change how integers are formatted: `15` vs `0xF` vs `0b1111`. diff --git a/book/src/design-global-logger.md b/book/src/design-global-logger.md index 934e8b50..2299d6d5 100644 --- a/book/src/design-global-logger.md +++ b/book/src/design-global-logger.md @@ -1,4 +1,6 @@ # Global logger +> ⚠️ The design and implementation chapter is outdated ⚠️ + The global logger needs to operate correctly (be memory safe and not interleave log data) in presence of race conditions and re-entrant invocations. Race conditions can be avoided with mutexes but re-entrancy can occur even if mutexes are used and shouldn't result in deadlocks. diff --git a/book/src/design-timestamp.md b/book/src/design-timestamp.md index 6dfc4da9..f44377ed 100644 --- a/book/src/design-timestamp.md +++ b/book/src/design-timestamp.md @@ -1,5 +1,7 @@ # Timestamp +> ⚠️ The design and implementation chapter is outdated ⚠️ + `defmt::timestamp!` needs to be as efficient as possible, because it is implicitly invoked on every single log invocation. The timestamp format string index is not transmitted over the wire. diff --git a/book/src/duplicates.md b/book/src/duplicates.md index 87e3a0b3..8fa2f08e 100644 --- a/book/src/duplicates.md +++ b/book/src/duplicates.md @@ -1,5 +1,7 @@ # Dealing with duplicates +> ⚠️ The design and implementation chapter is outdated ⚠️ + The linker hates it when it finds two symbol that have the same name. For example, this is an error: diff --git a/book/src/eval-order.md b/book/src/eval-order.md index 6afe5a2c..1e674324 100644 --- a/book/src/eval-order.md +++ b/book/src/eval-order.md @@ -1,5 +1,7 @@ # Evaluation order +> ⚠️ The design and implementation chapter is outdated ⚠️ + Consider this log invocation: ``` rust diff --git a/book/src/interning.md b/book/src/interning.md index ac491a3e..87a0d60e 100644 --- a/book/src/interning.md +++ b/book/src/interning.md @@ -1,5 +1,7 @@ # Interning +> ⚠️ The design and implementation chapter is outdated ⚠️ + All string literals are interned in a custom ELF section. This has proven to be the way that requires the less post-processing and implementation work. It is not without downsides as we'll see. diff --git a/book/src/linker-sections.md b/book/src/linker-sections.md index b5e719d1..07bc0e5a 100644 --- a/book/src/linker-sections.md +++ b/book/src/linker-sections.md @@ -1,5 +1,7 @@ # Logging levels +> ⚠️ The design and implementation chapter is outdated ⚠️ + `defmt` supports several logging levels. To avoid serializing the logging level at runtime (that would reduce throughput), interned strings are clustered by logging level. diff --git a/book/src/log-frame.md b/book/src/log-frame.md index 13d22ca1..fb126d50 100644 --- a/book/src/log-frame.md +++ b/book/src/log-frame.md @@ -1,5 +1,7 @@ # Log frames +> ⚠️ The design and implementation chapter is outdated ⚠️ + Each log statement produces one log frame. Consider this log call: (let's include the timestamp this time) diff --git a/book/src/lookup.md b/book/src/lookup.md index 2f6113d1..06daf88a 100644 --- a/book/src/lookup.md +++ b/book/src/lookup.md @@ -1,5 +1,7 @@ # Lookup +> ⚠️ The design and implementation chapter is outdated ⚠️ + We have so far looked at the string table using `nm`. Programmatically the table can be found in the `.symtab` section. Each [entry] in this table represents a symbol and each entry has: diff --git a/book/src/preemption.md b/book/src/preemption.md index d63744b2..f1792d33 100644 --- a/book/src/preemption.md +++ b/book/src/preemption.md @@ -1,5 +1,7 @@ # Preemption +> ⚠️ The design and implementation chapter is outdated ⚠️ + Preemption can also result in re-entrancy. How to deal with it? Assuming single-core systems there are two approaches: diff --git a/book/src/re-entrancy.md b/book/src/re-entrancy.md index 0acc0848..956bdc67 100644 --- a/book/src/re-entrancy.md +++ b/book/src/re-entrancy.md @@ -1,5 +1,7 @@ # Re-entrancy +> ⚠️ The design and implementation chapter is outdated ⚠️ + Where can re-entrancy occur? Turns out that with global singletons it can occur about anywhere; you don't need interrupts (preemption) to cause re-entrancy. See below: diff --git a/book/src/ser-array.md b/book/src/ser-array.md index 131db669..ca25a969 100644 --- a/book/src/ser-array.md +++ b/book/src/ser-array.md @@ -1,5 +1,7 @@ # Arrays +> ⚠️ The design and implementation chapter is outdated ⚠️ + For arrays (`{=[u8; N]}`) the length is not serialized. ``` rust diff --git a/book/src/ser-bitfield.md b/book/src/ser-bitfield.md index 08294cd8..eee71b05 100644 --- a/book/src/ser-bitfield.md +++ b/book/src/ser-bitfield.md @@ -1,5 +1,7 @@ # Bitfield +> ⚠️ The design and implementation chapter is outdated ⚠️ + The integer argument is serialized in little endian format (`to_le_bytes`). ``` rust diff --git a/book/src/ser-bool.md b/book/src/ser-bool.md index 2e03cea4..9d041cfc 100644 --- a/book/src/ser-bool.md +++ b/book/src/ser-bool.md @@ -1,5 +1,6 @@ # Bool +> ⚠️ The design and implementation chapter is outdated ⚠️ Booleans are compressed in bytes, bitflags-style. diff --git a/book/src/ser-format-slice.md b/book/src/ser-format-slice.md index 4770e211..64ffd198 100644 --- a/book/src/ser-format-slice.md +++ b/book/src/ser-format-slice.md @@ -1,5 +1,7 @@ # Format Slices +> ⚠️ The design and implementation chapter is outdated ⚠️ + `{=[?]}` will serialize the length (LEB128 compressed) first, then the first element will be serialized in (recursively) *tagged* format. The rest of elements will be serialized *untagged*. "Tagged" means that the data will be preceded by the string indices that indicate how to format the data. diff --git a/book/src/ser-format.md b/book/src/ser-format.md index b35cb5da..76bfbe14 100644 --- a/book/src/ser-format.md +++ b/book/src/ser-format.md @@ -1,5 +1,7 @@ # Format +> ⚠️ The design and implementation chapter is outdated ⚠️ + The untyped argument (`=?`) requires one level of indirection during serialization. First let's see how a primitive implements the `Format` trait: diff --git a/book/src/ser-integers.md b/book/src/ser-integers.md index 8ebca668..5a6dc7e3 100644 --- a/book/src/ser-integers.md +++ b/book/src/ser-integers.md @@ -1,5 +1,7 @@ # Integers +> ⚠️ The design and implementation chapter is outdated ⚠️ + Integers will be serialized in little endian order using `to_le_bytes()`. `usize` and `isize` values will be subject to LEB128 compression. diff --git a/book/src/ser-istr.md b/book/src/ser-istr.md index 210e4ea9..ff0d7a35 100644 --- a/book/src/ser-istr.md +++ b/book/src/ser-istr.md @@ -1,5 +1,7 @@ # Interned strings +> ⚠️ The design and implementation chapter is outdated ⚠️ + Let's ignore timestamps for now and also ignore how access to the global logger is synchronized. This is the simplest case: logging a string literal with no formatting. diff --git a/book/src/ser-slices.md b/book/src/ser-slices.md index a4659d2c..345d0aa3 100644 --- a/book/src/ser-slices.md +++ b/book/src/ser-slices.md @@ -1,5 +1,7 @@ # Slices +> ⚠️ The design and implementation chapter is outdated ⚠️ + For slices (`{=[u8]}`) the length is LEB128 encoded and serialized first and then followed by the slice data. ``` rust diff --git a/book/src/ser-str.md b/book/src/ser-str.md index b671a498..6349d5e8 100644 --- a/book/src/ser-str.md +++ b/book/src/ser-str.md @@ -1,5 +1,7 @@ # Strings +> ⚠️ The design and implementation chapter is outdated ⚠️ + Strings that are passed directly (i.e. not as indices of interned strings) as format string parameters (`{:str}`) must be prefixed with their LEB128 encoded length. This behavior is analogous to that of Slices. diff --git a/book/src/serialization.md b/book/src/serialization.md index 0cab8f57..aa546038 100644 --- a/book/src/serialization.md +++ b/book/src/serialization.md @@ -1,3 +1,5 @@ # Serialization +> ⚠️ The design and implementation chapter is outdated ⚠️ + In this section we'll see how log data is "put on the wire".