pw_hdlc_lite: Added a C++ decoder class
Change-Id: I0a53147b96bf038807a54604ec345c40982dde4b
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/15243
Reviewed-by: Wyatt Hepler <hepler@google.com>
Commit-Queue: Shane Gomindes <shaneajg@google.com>
diff --git a/pw_hdlc_lite/BUILD b/pw_hdlc_lite/BUILD
index a090c10..8a9ceb9 100644
--- a/pw_hdlc_lite/BUILD
+++ b/pw_hdlc_lite/BUILD
@@ -24,11 +24,13 @@
pw_cc_library(
name = "pw_hdlc_lite",
hdrs = [
+ "public/pw_hdlc_lite/decoder.h",
"public/pw_hdlc_lite/encoder.h",
"public/pw_hdlc_lite/sys_io_stream.h",
],
srcs = [
"encoder.cc",
+ "decoder.cc"
],
includes = ["public"],
)
@@ -42,3 +44,14 @@
"//pw_unit_test",
],
)
+
+cc_test(
+ name = "decoder_test",
+ srcs = ["decoder_test.cc"],
+ deps = [
+ ":pw_hdlc_lite",
+ "//pw_stream",
+ "//pw_unit_test",
+ "//pw_result",
+ ],
+)
diff --git a/pw_hdlc_lite/BUILD.gn b/pw_hdlc_lite/BUILD.gn
index 31135f5..7786825 100644
--- a/pw_hdlc_lite/BUILD.gn
+++ b/pw_hdlc_lite/BUILD.gn
@@ -25,14 +25,20 @@
pw_source_set("pw_hdlc_lite") {
public_configs = [ ":default_config" ]
public = [
+ "public/pw_hdlc_lite/decoder.h",
"public/pw_hdlc_lite/encoder.h",
"public/pw_hdlc_lite/sys_io_stream.h",
]
- sources = [ "encoder.cc" ]
+ sources = [
+ "decoder.cc",
+ "encoder.cc",
+ ]
public_deps = [
dir_pw_assert,
dir_pw_bytes,
+ dir_pw_log,
dir_pw_preprocessor,
+ dir_pw_result,
dir_pw_span,
dir_pw_status,
dir_pw_stream,
@@ -42,7 +48,10 @@
}
pw_test_group("tests") {
- tests = [ ":encoder_test" ]
+ tests = [
+ ":encoder_test",
+ ":decoder_test",
+ ]
group_deps = [
"$dir_pw_preprocessor:tests",
"$dir_pw_span:tests",
@@ -59,6 +68,15 @@
sources = [ "encoder_test.cc" ]
}
+pw_test("decoder_test") {
+ deps = [
+ ":pw_hdlc_lite",
+ "$dir_pw_result",
+ "$dir_pw_stream",
+ ]
+ sources = [ "decoder_test.cc" ]
+}
+
pw_doc_group("docs") {
sources = [ "docs.rst" ]
}
diff --git a/pw_hdlc_lite/decoder.cc b/pw_hdlc_lite/decoder.cc
new file mode 100644
index 0000000..10ef347
--- /dev/null
+++ b/pw_hdlc_lite/decoder.cc
@@ -0,0 +1,133 @@
+// Copyright 2020 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+
+#include "pw_hdlc_lite/decoder.h"
+
+#include "pw_checksum/ccitt_crc16.h"
+#include "pw_log/log.h"
+
+using std::byte;
+
+namespace pw::hdlc_lite {
+namespace {
+
+constexpr byte kHdlcFrameDelimiter = byte{0x7E};
+constexpr byte kHdlcEscape = byte{0x7D};
+constexpr byte kHdlcUnescapingConstant = byte{0x20};
+
+} // namespace
+
+Result<ConstByteSpan> Decoder::AddByte(const byte new_byte) {
+ switch (state_) {
+ case DecoderState::kPacketActive: {
+ if (new_byte != kHdlcFrameDelimiter) {
+ // Packet active case
+ if (new_byte != kHdlcEscape) {
+ return Result<ConstByteSpan>(AddEscapedByte(new_byte));
+ }
+ state_ = DecoderState::kEscapeNextByte;
+ return Result<ConstByteSpan>(Status::UNAVAILABLE);
+ }
+ // Packet complete case
+ state_ = DecoderState::kNoPacket;
+ Status status = PacketStatus();
+ if (status.ok()) {
+ // Common case: Happy Packet
+ // Returning size_ - 2 is to trim off the 2-byte CRC value.
+ return Result<ConstByteSpan>(frame_buffer_.first(size_ - 2));
+ }
+ if (status == Status::DATA_LOSS && size_ == 0) {
+ // Uncommon case: Dropped an ending frame delimiter byte somewhere.
+ // This happens if a delimiter byte was lost or corrupted which causes
+ // the decoder to fall out of sync with the incoming flow of packets.
+ // Recovery is done by switching to active mode assuming that the frame
+ // delimiter "close" byte we just saw is actually a start delimiter.
+ PW_LOG_ERROR(
+ "Detected empty packet. Assuming out of sync; trying recovery");
+ clear();
+ state_ = DecoderState::kPacketActive;
+ return Result<ConstByteSpan>(Status::UNAVAILABLE);
+ }
+ // Otherwise, forward the status from PacketStatus().
+ return Result<ConstByteSpan>(status);
+ }
+
+ case DecoderState::kEscapeNextByte: {
+ byte escaped_byte = new_byte ^ kHdlcUnescapingConstant;
+ if (escaped_byte != kHdlcEscape && escaped_byte != kHdlcFrameDelimiter) {
+ PW_LOG_WARN(
+ "Suspicious escaped byte: 0x%02x; should only need to escape frame "
+ "delimiter and escape byte",
+ static_cast<int>(escaped_byte));
+ }
+ state_ = DecoderState::kPacketActive;
+ return Result<ConstByteSpan>(AddEscapedByte(escaped_byte));
+ }
+
+ case DecoderState::kNoPacket: {
+ if (new_byte != kHdlcFrameDelimiter) {
+ PW_LOG_ERROR("Unexpected starting byte to the frame: 0x%02x",
+ static_cast<int>(new_byte));
+ return Result<ConstByteSpan>(Status::UNAVAILABLE);
+ }
+ clear();
+ state_ = DecoderState::kPacketActive;
+ return Result<ConstByteSpan>(Status::UNAVAILABLE);
+ }
+ }
+ return Result<ConstByteSpan>(Status::UNAVAILABLE);
+}
+
+bool Decoder::CheckCrc() const {
+ uint16_t expected_crc =
+ checksum::CcittCrc16(frame_buffer_.first(size_ - 2), 0xFFFF);
+ uint16_t actual_crc;
+ std::memcpy(&actual_crc, (frame_buffer_.data() + size_ - 2), 2);
+ return actual_crc == expected_crc;
+}
+
+Status Decoder::AddEscapedByte(const byte new_byte) {
+ if (size_ >= max_size()) {
+ // Increasing the size to flag the overflow case when the packet is complete
+ size_++;
+ return Status::RESOURCE_EXHAUSTED;
+ }
+ frame_buffer_[size_++] = new_byte;
+ return Status::UNAVAILABLE;
+}
+
+Status Decoder::PacketStatus() const {
+ if (size_ < 2) {
+ PW_LOG_ERROR(
+ "Received %d-byte packet; packets must at least have 2 CRC bytes",
+ static_cast<int>(size_));
+ return Status::DATA_LOSS;
+ }
+
+ if (size_ > max_size()) {
+ PW_LOG_ERROR("Packet size [%zu] exceeds the maximum buffer size [%zu]",
+ size_,
+ max_size());
+ return Status::RESOURCE_EXHAUSTED;
+ }
+
+ if (!CheckCrc()) {
+ PW_LOG_ERROR("CRC verification failed for packet");
+ return Status::DATA_LOSS;
+ }
+
+ return Status::OK;
+}
+
+} // namespace pw::hdlc_lite
diff --git a/pw_hdlc_lite/decoder_test.cc b/pw_hdlc_lite/decoder_test.cc
new file mode 100644
index 0000000..0373727
--- /dev/null
+++ b/pw_hdlc_lite/decoder_test.cc
@@ -0,0 +1,325 @@
+// Copyright 2020 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+
+#include "pw_hdlc_lite/decoder.h"
+
+#include <array>
+#include <cstddef>
+
+#include "gtest/gtest.h"
+#include "pw_bytes/array.h"
+#include "pw_result/result.h"
+#include "pw_stream/memory_stream.h"
+
+using std::byte;
+
+namespace pw::hdlc_lite {
+namespace {
+
+TEST(DecoderBuffer, 1BytePayload) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 5> data_frame = bytes::Array<0x7E, 0x41, 0x15, 0xB9, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+}
+
+TEST(DecoderBuffer, 0BytePayload) {
+ std::array<byte, 4> data_frame = bytes::Array<0x7E, 0xFF, 0xFF, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_TRUE(result.value().empty());
+}
+
+TEST(DecoderBuffer, 9BytePayload) {
+ std::array<byte, 9> expected_payload =
+ bytes::Array<0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39>();
+ std::array<byte, 13> data_frame = bytes::Array<0x7E,
+ 0x31,
+ 0x32,
+ 0x33,
+ 0x34,
+ 0x35,
+ 0x36,
+ 0x37,
+ 0x38,
+ 0x39,
+ 0xB1,
+ 0x29,
+ 0x7E>();
+ DecoderBuffer<15> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+}
+
+TEST(DecoderBuffer, MultiFrameDecoding) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 10> multiple_data_frames = bytes::
+ Array<0x7E, 0x41, 0x15, 0xB9, 0x7E, 0x7E, 0x41, 0x15, 0xB9, 0x7E>();
+ DecoderBuffer<12> decoder;
+
+ for (size_t i = 0; i < multiple_data_frames.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(multiple_data_frames[i]);
+ if (i == 4u || i == 9u) {
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, UnescapingDataFrame_0x7D) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x7D>();
+ std::array<byte, 6> data_frame =
+ bytes::Array<0x7E, 0x7D, 0x5D, 0xCA, 0x4E, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+}
+
+TEST(DecoderBuffer, UnescapingDataFrame_0x7E) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x7E>();
+ std::array<byte, 7> data_frame =
+ bytes::Array<0x7E, 0x7D, 0x5E, 0xA9, 0x7D, 0x5E, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+}
+
+TEST(DecoderBuffer, UnescapingDataFrame_Mix) {
+ std::array<byte, 7> expected_payload =
+ bytes::Array<0x7E, 0x7B, 0x61, 0x62, 0x63, 0x7D, 0x7E>();
+ ;
+ std::array<byte, 14> data_frame = bytes::Array<0x7E,
+ 0x7D,
+ 0x5E,
+ 0x7B,
+ 0x61,
+ 0x62,
+ 0x63,
+ 0x7D,
+ 0x5D,
+ 0x7D,
+ 0x5E,
+ 0x49,
+ 0xE5,
+ 0x7E>();
+ DecoderBuffer<15> decoder;
+
+ for (size_t i = 0; i < data_frame.size() - 1; i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ Result<ConstByteSpan> result =
+ decoder.AddByte(data_frame[data_frame.size() - 1]);
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+}
+
+TEST(DecoderBuffer, IncorrectCRC) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 5> incorrect_data_frame =
+ bytes::Array<0x7E, 0x41, 0x15, 0xB8, 0x7E>();
+ std::array<byte, 5> correct_data_frame =
+ bytes::Array<0x7E, 0x41, 0x15, 0xB9, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < incorrect_data_frame.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(incorrect_data_frame[i]);
+ if (i == incorrect_data_frame.size() - 1) {
+ EXPECT_EQ(result.status(), Status::DATA_LOSS);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+
+ for (size_t i = 0; i < correct_data_frame.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(correct_data_frame[i]);
+ if (i == 4u) {
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, BufferSizeLessThan2EdgeCase) {
+ std::array<byte, 3> data_frame = bytes::Array<0x7E, 0xFF, 0x7E>();
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frame.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ if (i == data_frame.size() - 1) {
+ EXPECT_EQ(result.status(), Status::DATA_LOSS);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, BufferOutOfSpace_SkipsRestOfFrame) {
+ std::array<byte, 5> data_frame = bytes::Array<0x7E, 0x41, 0x15, 0xB9, 0x7E>();
+ DecoderBuffer<2> decoder;
+
+ for (size_t i = 0; i < data_frame.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frame[i]);
+ if (i >= 3u) {
+ EXPECT_EQ(result.status(), Status::RESOURCE_EXHAUSTED);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, BufferOutOfSpace_SkipsRestOfFrameAndDecodesNext) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 11> data_frames = bytes::
+ Array<0x7E, 0x41, 0x42, 0x15, 0xB9, 0x7E, 0x7E, 0x41, 0x15, 0xB9, 0x7E>();
+ DecoderBuffer<3> decoder;
+
+ for (size_t i = 0; i < data_frames.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frames[i]);
+ if (i == 4u || i == 5u) {
+ EXPECT_EQ(result.status(), Status::RESOURCE_EXHAUSTED);
+ } else if (i == 10u) {
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, UnexpectedStartingByte) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 12> data_frames = bytes::Array<0x7E,
+ 0x41,
+ 0x15,
+ 0xB9,
+ 0x7E, // End of 1st Packet
+ 0xAA, // Garbage bytes
+ 0xAA, // Garbage bytes
+ 0x7E,
+ 0x41,
+ 0x15,
+ 0xB9,
+ 0x7E>(); // End of 2nd Packet
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frames.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frames[i]);
+ if (i == 4u || i == 11u) {
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+TEST(DecoderBuffer, RecoveringMissingFrameDelimiterCase) {
+ std::array<byte, 1> expected_payload = bytes::Array<0x41>();
+ std::array<byte, 12> data_frames =
+ bytes::Array<0x7E,
+ 0x41,
+ 0x15,
+ 0xB9,
+ 0x7E, // End of 1st Packet
+ 0x41,
+ 0x7E, // End of Packet with missing start frame delimiter
+ 0x7E,
+ 0x41,
+ 0x15,
+ 0xB9,
+ 0x7E>(); // End of 2nd Packet
+ DecoderBuffer<10> decoder;
+
+ for (size_t i = 0; i < data_frames.size(); i++) {
+ Result<ConstByteSpan> result = decoder.AddByte(data_frames[i]);
+ if (i == 4u || i == 11u) {
+ EXPECT_TRUE(result.ok());
+ EXPECT_EQ(std::memcmp(result.value().data(),
+ expected_payload.data(),
+ expected_payload.size()),
+ 0);
+ } else {
+ EXPECT_EQ(result.status(), Status::UNAVAILABLE);
+ }
+ }
+}
+
+} // namespace
+} // namespace pw::hdlc_lite
diff --git a/pw_hdlc_lite/public/pw_hdlc_lite/decoder.h b/pw_hdlc_lite/public/pw_hdlc_lite/decoder.h
new file mode 100644
index 0000000..5c03977
--- /dev/null
+++ b/pw_hdlc_lite/public/pw_hdlc_lite/decoder.h
@@ -0,0 +1,127 @@
+// Copyright 2020 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+#pragma once
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstring>
+
+#include "pw_bytes/span.h"
+#include "pw_result/result.h"
+#include "pw_status/status.h"
+
+namespace pw::hdlc_lite {
+
+// The Decoder class facilitates decoding of data frames using the HDLC-Lite
+// protocol, by returning packets as they are decoded and storing incomplete
+// data frames in a buffer.
+//
+// The Decoder class does not own the buffer it writes to. It can be used to
+// write bytes to any buffer. The DecoderBuffer template class, defined below,
+// allocates a buffer.
+class Decoder {
+ public:
+ constexpr Decoder(ByteSpan buffer)
+ : frame_buffer_(buffer), state_(DecoderState::kNoPacket), size_(0) {}
+
+ // Parse a single byte of a HDLC stream. Returns a result object with the
+ // complete packet if the latest byte finishes a frame, or a variety of
+ // statuses in other cases, as follows:
+ //
+ // OK - If the end of the data-frame was found and the packet was decoded
+ // successfully. The value of this Result<ConstByteSpan> object will
+ // be the payload.
+ // RESOURCE_EXHAUSTED - If the number of bytes added to the Decoder is
+ // greater than the buffer size. This function call will clear the
+ // decoder before returning.
+ // UNAVAILABLE - If the byte has been successfully escaped and added to
+ // the buffer, but we havent reached the end of the data-frame.
+ // DATA_LOSS - If the CRC verification process fails after seeing the
+ // ending Frame Delimiter byte (0x7E). Additionally happens when the
+ // FCS is not in the payload or when the data-frame does not start
+ // with the initial Frame Delimiter byte (0x7E).
+ //
+ Result<ConstByteSpan> AddByte(const std::byte b);
+
+ // Returns the number of bytes of the active packet that are added to the
+ // frame buffer.
+ size_t size() const { return size_; }
+
+ // Returns the maximum size of the Decoder's frame buffer.
+ size_t max_size() const { return frame_buffer_.size(); }
+
+ // Clears the frame buffer at the beginning of decoding the next packet.
+ void clear() { size_ = 0; };
+
+ // Indicates if the decoder is currently in the process of decoding a packet.
+ bool IsPacketActive() { return state_ != DecoderState::kNoPacket; }
+
+ private:
+ // DecoderState enum class is used to make the Decoder a finite state machine.
+ enum class DecoderState {
+ kNoPacket,
+ kPacketActive,
+ kEscapeNextByte,
+ };
+
+ // Disallow Copy and Assign.
+ Decoder(const Decoder&) = delete;
+
+ Decoder& operator=(const Decoder&) = delete;
+
+ // Will return true if the CRC is successfully verified.
+ bool CheckCrc() const;
+
+ // Attempts to write the escaped byte to the buffer and returns a Status
+ // object accordingly:
+ //
+ // RESOURCE_EXHAUSTED - If the buffer is out of space.
+ // UNAVAILABLE - If the byte has been successfully added to the buffer.
+ //
+ Status AddEscapedByte(std::byte new_byte);
+
+ // Ensures the packet is correctly decoded and returns a status object
+ // indicating if the packet can be returned. The three checks it does are:
+ // 1. Checks if there are packet meets the minimum size of a HDLC-Lite
+ // packet.
+ // 2. Checks that the frame buffer wasnt overflowed.
+ // 3. Verifies if the CRC is correct
+ // Will log errors accordingly.
+ //
+ Status PacketStatus() const;
+
+ ByteSpan frame_buffer_;
+ DecoderState state_;
+
+ // The size_ variable represents the number of decoded bytes of the current
+ // active packet.
+ size_t size_;
+};
+
+// DecoderBuffers declare a buffer along with a Decoder.
+template <size_t size_bytes>
+class DecoderBuffer : public Decoder {
+ public:
+ DecoderBuffer() : Decoder(frame_buffer_) {}
+
+ // Returns the maximum length of the bytes that can be inserted in the bytes
+ // buffer.
+ static constexpr size_t max_size() { return size_bytes; }
+
+ private:
+ std::array<std::byte, size_bytes> frame_buffer_;
+};
+
+} // namespace pw::hdlc_lite
