the large library cleanup

5 files changed, 166 insertions, 0 deletions

diff --git a/lib/i2ctcp/CMakeLists.txt b/lib/i2ctcp/CMakeLists.txt
new file mode 100644
index 0000000..b47b1d7
--- /dev/null
+++ b/lib/i2ctcp/CMakeLists.txt
@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.29)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+
+project(i2ctcp C CXX)
+
+add_subdirectory(../mpack ${CMAKE_CURRENT_BINARY_DIR}/mpack)
+
+add_library(i2ctcp STATIC ./i2ctcpv1.c)
+target_link_libraries(i2ctcp mpack)
+target_include_directories(i2ctcp SYSTEM INTERFACE .)
+
diff --git a/lib/i2ctcp/i2ctcpv1.c b/lib/i2ctcp/i2ctcpv1.c
new file mode 100644
index 0000000..944df3a
--- /dev/null
+++ b/lib/i2ctcp/i2ctcpv1.c
@@ -0,0 +1,52 @@
+#include <mpack.h>
+#ifndef MIN
+#define MIN(a,b) (((a) < (b)) ? (a) : (b))
+#endif
+
+#include "i2ctcpv1.h"
+
+int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz) {
+	mpack_reader_t reader;
+	mpack_reader_init_data(&reader, buf, buf_sz);
+
+	// at start of message
+	if (target->_rdata == 0) {
+		target->addr = mpack_expect_u16(&reader);
+		target->length = target->_rdata = mpack_expect_bin(&reader);
+		if (mpack_reader_error(&reader) != mpack_ok) return -1;
+		target->data = (char *) malloc(target->length);
+
+		// seek forward in buf to where binary data begins (to avoid having to read
+		// from private member reader.data in the memcpy below)
+		buf += buf_sz - mpack_reader_remaining(&reader, NULL);
+	}
+
+	// continue reading chunks of target->data until the amount of bytes
+	// specified in target->length
+	size_t to_read = MIN(mpack_reader_remaining(&reader, NULL), target->_rdata);
+	char * data = target->data + target->length - target->_rdata;
+	memcpy(data, buf, to_read);
+	target->_rdata -= to_read;
+	// NOTE: memcpy is used here because mpack_read_bytes requires that a tag was
+	// opened, which is not the case for the chunks following the initial mpack
+	// header
+
+	// if rdata = 0, the message was completely read
+	return target->_rdata;
+}
+
+void i2ctcp_read_reset(i2ctcp_msg_t * target) {
+	target->_rdata = 0;
+}
+
+bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz) {
+	mpack_writer_t writer;
+	mpack_writer_init_growable(&writer, buf, buf_sz);
+
+	mpack_write_u16(&writer, target->addr);
+	mpack_write_bin(&writer, target->data, target->length);
+
+	// finish writing
+	return mpack_writer_destroy(&writer) == mpack_ok;
+}
+
diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h
new file mode 100644
index 0000000..799b668
--- /dev/null
+++ b/lib/i2ctcp/i2ctcpv1.h
@@ -0,0 +1,71 @@
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** \brief I2C over TCP message (v1) */
+struct i2ctcp_msg {
+	uint16_t addr; //!< I^2^C address
+	char * data;   //!< message content
+	size_t length; //!< message size
+	size_t _rdata; //!< \private remaining bytes to read until message is complete
+};
+typedef struct i2ctcp_msg i2ctcp_msg_t;
+
+/**
+ * \brief Read chunk of input stream, and store resulting message in \p target
+ *
+ * This function is called for each chunk of data from an input stream, and
+ * will parse the next puzzle bus message into \p target. The input stream is
+ * assumed to only contain messages encoded by \p i2ctcp_write()
+ *
+ * \param target  pointer to struct that will contain the finished message data
+ * \param buf     pointer to input stream data chunk
+ * \param buf_sz  size of \p buf
+ *
+ * \returns Integer representing amount of bytes required to finish message, or
+ * -1 if the message header could not be read. If this function returns 0, the
+ *  message in \p target is complete.
+ *
+ * \note target->data will automatically be allocated by this function, even if
+ * the message is not fully parsed. This variable must be `free()`d by the
+ * caller after each complete message to prevent memory leaks.
+ */
+int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz);
+
+/**
+ * \brief reset the remaining message data counter
+ *
+ * Calling this function has the effect of forcing \c i2ctcp_read() to parse
+ * the next buffer chunk as the start of a new message. This function may be
+ * called before reading a TCP frame's data to mitigate any synchronization
+ * issues arising from earlier corrupt or otherwise malformed messages.
+ */
+void i2ctcp_read_reset(i2ctcp_msg_t * target);
+
+/**
+ * \brief Allocate and write a msgpack-formatted message to \p buf
+ *
+ * This function allocates a buffer large enough to fit the message specified
+ * in \p target, and encodes the data in \p target in a format that can be
+ * decoded later using \p i2ctcp_read()
+ *
+ * \param target  pointer to struct that contains the message data
+ * \param buf     pointer to \c char* that will contain the formatted message
+ * \param buf_sz  pointer to \c size_t that will represent the final size of \p buf
+ *
+ * \returns boolean true if a the message could be encoded successfully, false
+ * if there was some kind of error
+ *
+ * \note the pointer stored in \p buf must be `free()`d by the caller afterwards
+ */
+bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz);
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/i2ctcp/makefile b/lib/i2ctcp/makefile
new file mode 100644
index 0000000..5ca3fd1
--- /dev/null
+++ b/lib/i2ctcp/makefile
@@ -0,0 +1,4 @@
+TARGET = $(BUILD_DIR)/libi2ctcp.a
+
+include ../../lazy.mk
+
diff --git a/lib/i2ctcp/readme.md b/lib/i2ctcp/readme.md
new file mode 100644
index 0000000..d5bfe6d
--- /dev/null
+++ b/lib/i2ctcp/readme.md
@@ -0,0 +1,25 @@
+# i2ctcp (I<sup>2</sup>C over TCP)
+
+This folder includes protocol (de)serialization functions for sending and
+receiving I<sup>2</sup>C messages over TCP. These functions are used by the
+[main controller](../main) and the [puzzle box client (pbc)](../client). This
+folder does not include any puzzle bus specific code, and the headers for
+puzbus are in the [shared](../shared) folder instead.
+
+[MessagePack][msgpack] (specifically the [mpack][mpack] implementation) is used
+for the actual serialization/deserializtion, and the functions in this folder
+act as helpers for parsing from chunked data streams.
+
+To use these functions, include the following statement in your CMakeLists.txt:
+```cmake
+include(../i2ctcp/include.cmake)
+```
+
+The functions are available by `#include`ing the `i2ctcpv1.h` header, and are
+extensively documented using Doxygen-style comments.
+
+[msgpack]: https://msgpack.org/
+[mpack]: https://github.com/ludocode/mpack/
+
+
+