Merge pull request #912 from BenFordTytherington/add-design-warnings-…

…to-book Add warnings to design pages in book
knurling-rs · Dec 19, 2024 · 40ed0f6 · 40ed0f6
2 parents a34dbcb + 0eb3993
commit 40ed0f6
Show file tree

Hide file tree

Showing 23 changed files with 45 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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".