Manchester documentation (#1325)

* manchester * Added manchester code and test * manchester * Formatting and added missing file * manchester * Some functions can only be constexpr since C++14 * manchester * Manchester decode and some refactoring * manchester * Added some missing typenames * manchester * constexpr void function not allowed in C++11 * manchester * condition on static_assert tests * manchester * revert CMakeLists.txt * Using ETL_STATIC_ASSERT * Some cleanup * manchester * Added static_assert message * manchester * Added compile time tests * manchester * Added invert manchester * Some refactoring * manchester * Disable test for now * Move ETL_NODISCARD before static * manchester * Test for valid_span * manchester * Remove redundant (?) storage specifiers for template specializations. Storage specifier already given in base template * manchester * refactoring to get rid of specialized template functions in template class * manchester * cleanup * manchester * Added documentation comments * Some refactoring * manchester * introducing namespace detail_manchester * manchester * Some refactoring * Update tests * manchester * Some refactoring * Removed possible undefined behavior by refactoring encode_span * constexpr version of encode_span * Static assertion for rare case where code doesn't work because CHAR_BIT is not the same as the number of bits in uint_least8_t * manchester * renamed valid to is_valid * manchester * renamed is_valid_span to is_valid * Using etl exceptions in ETL_ASSERT * manchester * Removed _fast functions * merged encode_in_place with encode and decode_in_place with decode * removed _span to create normal overloads of encode and decode for span * Some renaming and minor refactoring * manchester * Fix build issues * manchester * Conditionally compile manchester_decoded * Update test_manchester.cpp Removed redundant semicolon * #1258 Manchester coding * Formatting * consistency: hex literals with lower case 0x * #1258 Manchester coding * Moved copyright to top of file * Make constexpr encode/decode span functions equal for little and big endian platforms * #1258 Manchester coding * Added missing include * Added missing 8bit/64bit guards * Fixed is_valid for big endian platforms * #1258 Manchester coding * private memcpy alias * #1258 Manchester coding * Review comments * #1258 Manchester coding * Cleanup * Fix build error * #1258 Manchester coding * Add manchester documentation * #1258 Manchester coding * Preparation for GitHub pages * #1324 Manchester documentation * Some small fixes --------- Co-authored-by: Timon Zijnge <timon.zijnge@imec.nl>
2026-04-30 19:09:10 +08:00 · 2026-03-07 09:13:00 +01:00 · 2026-03-07 09:13:00 +01:00 · 521df8ee19
commit 521df8ee19
parent 8ce59792fd
3 changed files with 271 additions and 0 deletions
--- a/docs/_config.yml
+++ b/docs/_config.yml
@ -0,0 +1,6 @@
+plugins:
+  - jekyll-relative-links
+relative_links:
+  enabled: true
+include:
+  - manchester.md
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,7 @@
+---
+title: ETL documentation
+---
+
+## Pages
+
+* [Manchester](manchester.md)
--- a/docs/manchester.md
+++ b/docs/manchester.md
@ -0,0 +1,258 @@
+---
+title: Manchester encoding and decoding
+---
+
+Efficient Manchester encoding and decoding of data. The Manchester code represents a data bit as a sequence of a 'high' and a 'low' value. In software this translates to a conversion from one to two bits, or in a practical situation, from `n` bytes to `n*2` bytes.
+
+## See also
+
+[Manchester code](https://en.wikipedia.org/wiki/Manchester_code)
+
+## Features
+
+- Normal and inverted Manchester encoding
+- Support for multiple encoding chunk sizes: 8-bit, 16-bit and 32-bit
+- Span-based operations or chunk-based operations
+- Constexpr functions for compile-time encoding/decoding (8-bit chunk size only)
+- Validation of encoded data
+
+## Algorithm background
+
+To encode the value `0b11001100` we must first duplicate all bits to create the value `0b1111000011110000`. We then perform an XOR of this value with the constant `0b1010101010101010` (`0xAAAA`) to obtain the Manchester coded value of `0b1010010110100101`. We have now replaced each `1` bit with the sequence `10` and each `0` bit with the sequence `01`.
+
+### 2. Bit duplication
+
+Bit duplication is achieved with the following steps. This is also called binary interleaving. The example shows encoding of an 8-bit value.
+
+| Step | High Byte          | Low Byte           | Operation                  |
+|------|--------------------|--------------------|----------------------------|
+| 0    | `_ _ _ _ _ _ _ _`  | `A B C D E F G H`  | input value (i)            |
+| 1    | `_ _ _ _ A B C D`  | `_ _ _ _ E F G H`  | `(i \| (i << 4)) & 0x0F0F` |
+| 2    | `_ _ A B _ _ C D`  | `_ _ E F _ _ G H`  | `(i \| (i << 2)) & 0x3333` |
+| 3    | `_ A _ B _ C _ D`  | `_ E _ F _ G _ H`  | `(i \| (i << 1)) & 0x5555` |
+| 4    | `A A B B C C D D`  | `E E F F G G H H`  | `(i \| (i << 1))`          |
+
+This process can be easily extended to 16-bit or 32-bit values by adding additional steps to the bit duplication.
+
+### 3. Manchester Decoding
+
+Manchester decoding is done in a similar, but reversed way.
+
+### 4. Error Detection
+
+Error detection in Manchester coded data is done by comparing 2 neighboring bits. If they are
+equal, then there is an error in the encoded input data.
+
+Comparing all 8 bit pairs in a 16-bit word is done as follows.
+
+| Step | Binary Value | Operation         | Description                                                                                   |
+|------|--------------|-------------------|-----------------------------------------------------------------------------------------------|
+| 1    | `11011000`   | Original          | First bit pair (lsb, 00) is invalid. Last bit pair is also invalid. Other bit pairs are valid |
+| 2    | `01101100`   | Shift right by 1  | Shift the original value right by one bit                                                     |
+| 3    | `10110100`   | XOR               | XOR the original with the shifted value                                                       |
+| 4    | `01010101`   | Mask with 0x55    | Apply mask to isolate bit pairs                                                               |
+| 5    | `00010100`   | Result            | If result is not equal to 0x55, there was an error in the input                               |
+
+## Analysis
+
+Most traditional ways to Manchester encode data consist of a loop over all bits and a nested if-statement to check the value of the current bit. This approach does not scale well to increasing number of bits. The algorithm implemented here contains no conditional code and scales well. Doubling the number of processed bits per step (the chunk size) adds a single row to the bit duplication table. Because of the lack of loops and conditional code, this algorithm is likely to perform better than traditional ones on simple processors or when compiler optimization is disabled. On modern, powerful processors with caches and advanced optimization possibilities this algorithm may not show much benefit. In any case, the performance of the algorithm depends heavily on the processor type, compiler and compiler (optimization) settings.
+
+## API Reference
+
+### Classes
+
+Classes `etl::manchester` and `etl::manchester_inverted` contain static functions for encoding, decoding and validity checking. It is not necessary to instantiate objects of these classes.
+
+#### etl::manchester
+
+```cpp
+typedef manchester_base<private_manchester::manchester_type_normal> manchester;
+```
+
+Manchester encoder using normal encoding (no inversion).
+
+#### etl::manchester_inverted
+
+```cpp
+typedef manchester_base<private_manchester::manchester_type_inverted> manchester_inverted;
+```
+
+Manchester encoder using inverted encoding.
+
+### Encoding Functions
+
+#### Encode single value
+
+```cpp
+template <typename TDecoded>
+static ETL_CONSTEXPR14 typename encoded<TDecoded>::type encode(TDecoded decoded)
+```
+
+Encodes a single value using Manchester encoding.
+
+**Parameters:**
+
+- `decoded`: The value to encode (`uint8_t`, `uint16_t`, or `uint32_t`)
+
+**Returns:**
+
+- The Manchester encoded value (twice the bit width of input)
+
+**Example:**
+
+```cpp
+uint16_t encoded = etl::manchester::encode(0x55);
+```
+
+#### Encode range
+
+```cpp
+template <typename TChunk = uint_least8_t>
+static ETL_CONSTEXPR14 void encode(etl::span<const uint_least8_t> decoded, 
+                                   etl::span<uint_least8_t> encoded)
+```
+
+Encodes a span of data using the specified chunk size.
+
+**Parameters:**
+
+- `decoded`: Source data to encode
+- `encoded`: Destination for encoded data (must be twice the size of `decoded`)
+
+**Template Parameters:**
+
+- `TChunk`: Chunk size for encoding (`uint8_t`, `uint16_t` or `uint32_t`)
+
+**Example:**
+
+```cpp
+std::array<uint8_t, 4> data = {0x12, 0x34, 0x56, 0x78};
+std::array<uint8_t, 8> encoded_data1{};
+std::array<uint8_t, 8> encoded_data2{};
+
+// Encode with TChunk == uint8_t
+etl::manchester::encode(data, encoded_data1);
+
+// Encode with TChunk == uint32_t
+etl::manchester::encode<uint32_t>(data, encoded_data2);
+```
+
+### Decoding Functions
+
+#### Decode single value
+
+```cpp
+template <typename TEncoded>
+static ETL_CONSTEXPR14 typename decoded<TEncoded>::type decode(TEncoded encoded)
+```
+
+Decodes a single Manchester encoded value.
+
+**Parameters:**
+
+- `encoded`: The encoded value to decode (`uint16_t`, `uint32_t`, or `uint64_t`)
+
+**Returns:**
+
+- The Manchester decoded value (half the bit width of input)
+
+**Example:**
+
+```cpp
+uint8_t decoded = etl::manchester::decode(0x5A5A);
+```
+
+#### Decode range
+
+```cpp
+template <typename TChunk = typename private_manchester::encoded<uint_least8_t>::type>
+static ETL_CONSTEXPR14 void decode(etl::span<const uint_least8_t> encoded, 
+                                   etl::span<uint_least8_t> decoded)
+```
+
+Decodes a span of Manchester encoded data.
+
+**Parameters:**
+
+- `encoded`: Source data to decode
+- `decoded`: Destination for decoded data (must be half the size of `encoded`)
+
+**Template Parameters:**
+
+- `TChunk`: Chunk type for decoding (`uint16_t`, `uint32_t`, or `uint64_t`)
+
+**Example:**
+
+```cpp
+std::array<uint8_t, 8> encoded = {/* ... */};
+std::array<uint8_t, 4> decoded1 {};
+std::array<uint8_t, 4> decoded2 {};
+
+// Decode with TChunk == uint16_t
+etl::manchester::decode(encoded, decoded1);
+
+// Decode with TChunk == uint64_t
+etl::manchester::decode<uint64_t>(encoded, decoded2);
+```
+
+### Validation Functions
+
+#### Single value
+
+```cpp
+template <typename TChunk>
+static ETL_CONSTEXPR14 bool is_valid(TChunk encoded)
+```
+
+Validates that a single value contains valid Manchester encoded data.
+
+**Parameters:**
+
+- `encoded`: The encoded value to validate
+
+**Returns:**
+
+- `true` if the value contains valid Manchester encoded data, `false` otherwise
+
+**Example:**
+
+```cpp
+bool valid = etl::manchester::is_valid(0x5A5A);
+```
+
+#### Range
+
+```cpp
+static ETL_CONSTEXPR14 bool is_valid(etl::span<const uint_least8_t> encoded)
+```
+
+Validates that a range contains valid Manchester encoded data.
+
+**Parameters:**
+
+- `encoded`: The range of encoded data to validate
+
+**Returns:**
+
+- `true` if all data is valid Manchester encoding, `false` otherwise
+
+**Example:**
+
+```cpp
+std::array<uint8_t, 8> encoded_data = {/* ... */};
+bool valid = etl::manchester::is_valid(encoded_data);
+```
+
+## Supported Types
+
+### Input/chunk types for encoding
+
+- `uint8_t` → `uint16_t` (if 8-bit types are supported)
+- `uint16_t` → `uint32_t`
+- `uint32_t` → `uint64_t` (if 64-bit types are supported)
+
+### Input/chunk types for decoding
+
+- `uint16_t` → `uint8_t` (if 8-bit types are supported)
+- `uint32_t` → `uint16_t`
+- `uint64_t` → `uint32_t` (if 64-bit types are supported)