diff options
Diffstat (limited to 'lib')
33 files changed, 1053 insertions, 300 deletions
diff --git a/lib/Arduino-CMake-Toolchain b/lib/Arduino-CMake-Toolchain -Subproject e745a9bed3c3fb83442d55bf05630f31574674f +Subproject 953b2e63ddf434868bfba60244fb714262fce5f diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h index 799b668..e9bc0d9 100644 --- a/lib/i2ctcp/i2ctcpv1.h +++ b/lib/i2ctcp/i2ctcpv1.h @@ -2,43 +2,69 @@ #include <stddef.h> #include <stdint.h> +#include <stdbool.h> #ifdef __cplusplus extern "C" { #endif -/** \brief I2C over TCP message (v1) */ -struct i2ctcp_msg { - uint16_t addr; //!< I^2^C address +/** + * \defgroup i2ctcp i2ctcp + * \brief I2C over TCP + * + * This library includes protocol (de)serialization functions for sending and + * receiving I2C messages over TCP. These functions are used by the \ref main + * "main controller" and the \ref pbc "puzzle box client (pbc)". This library + * does not include any puzzle bus specific code. + * + * mpack is used for the actual (de)serialization, and the functions in this + * library act as helpers for parsing from chunked data streams. + * + * To use these functions, include the following statement in your + * CMakeLists.txt: + * + * ```cmake + * # include pbdrv + * add_subdirectory(lib/i2ctcp) + * + * # link with executable + * target_link_libraries(main i2ctcp) + * ``` + * + * \{ + */ + +//! I2C over TCP message (v1) +typedef struct { + uint16_t addr; //!< I2C 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; +} 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() + * assumed to only contain messages encoded by \c 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 + * \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 + * \note \p 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 + * \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 @@ -52,19 +78,21 @@ void i2ctcp_read_reset(i2ctcp_msg_t * target); * * 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() + * decoded later using \c 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 + * \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 + * \returns Boolean \c true if a the message could be encoded successfully, \c + * false if there was some kind of error * - * \note the pointer stored in \p buf must be `free()`d by the caller afterwards + * \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/readme.md b/lib/i2ctcp/readme.md deleted file mode 100644 index d5bfe6d..0000000 --- a/lib/i2ctcp/readme.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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/ - - - diff --git a/lib/mpack/mpack.h b/lib/mpack/mpack.h index 7c0c089..33521c4 100644 --- a/lib/mpack/mpack.h +++ b/lib/mpack/mpack.h @@ -2,18 +2,39 @@ #include "src/src/mpack/mpack.h" +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup mpack mpack + * \brief Mpack extensions specific to this project + * + * The mpack folder under `lib/` contains a CMakeLists.txt for integrating the + * mapck library with CMake, and includes an extension in the form of an + * additional utility function. + * + * \{ + */ + /** - * \brief read remaining bytes in reader without opening a tag first + * \brief Read remaining bytes in reader without opening a tag first * - * \param reader pointer to mpack reader object - * \param p pointer to write data to - * \param count maximum number of bytes to read + * \param reader Pointer to mpack reader object + * \param p Pointer to write data to + * \param count Maximum number of bytes to read * * This function reads *up to* the amount of bytes specified in \p count, or * less if there is less remaining data in the buffer. If \p count is equal to * 0, all remaining data in the buffer is read. * - * \return amount of bytes read + * \return Amount of bytes read */ size_t mpack_read_remaining_bytes(mpack_reader_t * reader, char * p, size_t count); +/// \} + +#ifdef __cplusplus +} +#endif + diff --git a/lib/pbdrv/CMakeLists.txt b/lib/pbdrv/CMakeLists.txt index 998ed4d..903a3b4 100644 --- a/lib/pbdrv/CMakeLists.txt +++ b/lib/pbdrv/CMakeLists.txt @@ -23,7 +23,7 @@ add_library(pbdrv STATIC pb-buf.c ) target_include_directories(pbdrv SYSTEM INTERFACE .) -target_link_libraries(pbdrv mpack) +target_link_libraries(pbdrv PRIVATE mpack) # puzzle bus *module* specific code add_library(pbdrv-mod OBJECT @@ -32,9 +32,9 @@ add_library(pbdrv-mod OBJECT pb-route.c ) target_include_directories(pbdrv-mod SYSTEM INTERFACE .) -target_link_libraries(pbdrv-mod pbdrv) +target_link_libraries(pbdrv-mod PUBLIC pbdrv) # puzzle bus drivers include(drv/arduino/include.cmake) -# include(drv/rp2040/include.cmake) # please see /main/pbdrv.h +include(drv/rp2040/include.cmake) diff --git a/lib/pbdrv/drv/arduino/include.cmake b/lib/pbdrv/drv/arduino/include.cmake index 1e2ff08..5ec1124 100644 --- a/lib/pbdrv/drv/arduino/include.cmake +++ b/lib/pbdrv/drv/arduino/include.cmake @@ -3,7 +3,7 @@ if(NOT DEFINED ARDUINO) endif() target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.cpp") -target_link_arduino_libraries(pbdrv-mod core Wire) +target_link_arduino_libraries(pbdrv-mod PRIVATE core Wire) # freertos is used to defer the handling of i2c messages outside the receive # interrupt service routine diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox new file mode 100644 index 0000000..03510dd --- /dev/null +++ b/lib/pbdrv/drv/arduino/index.dox @@ -0,0 +1,25 @@ +// vim:ft=doxygen +/** +\ingroup pb_drv +\defgroup pb_drv_arduino Arduino +\brief Arduino ATmega (w/ Arduino-CMake-Toolchain) driver + +This driver is known to work with the following MCUs: +- ATmega328P (Arduino Uno) +- ATmega2560 (Arduino Mega) + +\par Usage +- Link the \c pbdrv-mod library with your main executable + +\note This driver is automatically enabled if the variable \c ARDUINO is +defined in your CMakeLists.txt (it is by default when using +Arduino-CMake-Toolchain). + +\note This driver automatically includes the \ref pb_ext_freertos +"FreeRTOS extension" for deferring calls to \c pb_i2c_recv() from the I2C ISR. + +A complete example for this driver is available in the \ref puzzle/dummy +folder. + +*/ + diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp index 9130334..c381077 100644 --- a/lib/pbdrv/drv/arduino/mod.cpp +++ b/lib/pbdrv/drv/arduino/mod.cpp @@ -1,7 +1,3 @@ -#ifndef ARDUINO -#error This driver only works on the Arduino platform! -#endif - #include <Arduino.h> #include <Wire.h> #include <avr/delay.h> @@ -42,7 +38,17 @@ static void pb_setup() { Wire.onReceive(recv_event); } +/** + * \ingroup pb_drv_arduino + * \warning This function includes a hard-coded 10ms delay before sending. This + * is to work around a weird issue where the Arduino pulls both SDA and SCL low + * while attempting to initiate an I2C transmission. We were able to verify + * that the Arduino correctly handles bus arbitration under a test scenario + * with 2 Uno's, but ran into issues while integrating the Arduino's with the + * RP2040. + */ __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { + vTaskDelay(10 / portTICK_PERIOD_MS); // prevent bus collisions Wire.beginTransmission((int) addr); Wire.write(buf, sz); Wire.endTransmission(true); @@ -64,7 +70,20 @@ void loop_task() { } } -//! Application entrypoint +/** + * \ingroup pb_drv_arduino + * \brief Application entrypoint + * + * This function overrides the default (weak) implementation of the \c main() + * function in the Arduino framework. No additional setup is required to use + * this driver. + * + * \note I should really be able to use Arduino's initVariant function for + * this, but I can't seem to get it to link properly using the CMake setup in + * this repository. Overriding the main() function seems to work, and the + * USBCON thing in the default Arduino main() function isn't needed because + * puzzle modules are likely not using USB. + */ int main(void) { init(); // call arduino internal setup setup(); // call regular arduino setup @@ -74,11 +93,3 @@ int main(void) { return 0; } -/** - * \note I should really be able to use Arduino's initVariant function for - * this, but I can't seem to get it to link properly using the CMake setup in - * this repository. Overriding the main() function seems to work, and the - * USBCON thing in the default Arduino main() function isn't needed because - * puzzle modules are likely not using USB. - */ - diff --git a/lib/pbdrv/drv/index.dox b/lib/pbdrv/drv/index.dox new file mode 100644 index 0000000..89b9247 --- /dev/null +++ b/lib/pbdrv/drv/index.dox @@ -0,0 +1,19 @@ +// vim:ft=doxygen +/** +\ingroup pbdrv-mod +\defgroup pb_drv Drivers +\brief Platform-specific \ref pbdrv-mod implementations + +Like \ref pb_ext "extensions", drivers provide platform-specific +implementations for various functions used in \ref pbdrv-mod. + +If there is no existing driver for your target, you may implement the following +in order to use \ref pbdrv-mod: + +- The \c pb_i2c_recv() function must be **called** for every received I2C + message +- The \c pb_i2c_send() function must be **implemented** using the + platform/device-specific I2C write function + +*/ + diff --git a/lib/pbdrv/drv/rp2040/include.cmake b/lib/pbdrv/drv/rp2040/include.cmake new file mode 100644 index 0000000..6d25e96 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/include.cmake @@ -0,0 +1,11 @@ +if(NOT PICO_PLATFORM STREQUAL "rp2040") + return() +endif() + +target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.c") +target_link_libraries(pbdrv-mod PRIVATE hardware_i2c_headers pico_i2c_slave_headers) +target_include_directories(pbdrv-mod INTERFACE "${CMAKE_CURRENT_LIST_DIR}") + +# pico-stdlib is compatible with C stdlib +include("${CMAKE_CURRENT_LIST_DIR}/../../ext/stdlib/include.cmake") + diff --git a/lib/pbdrv/drv/rp2040/index.dox b/lib/pbdrv/drv/rp2040/index.dox new file mode 100644 index 0000000..eb01d15 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/index.dox @@ -0,0 +1,31 @@ +// vim:ft=doxygen +/** +\ingroup pb_drv +\defgroup pb_drv_rp2040 RP2040 +\brief Raspberry Pi Pico and Pico W driver + +This driver is known to work with the following MCUs: +- Raspberry Pi Pico W + +\note While the RP2040's datasheet claims it supports multi-master +configurations by implementing bus arbitration, it does not natively support +a mode where it is configured as a (multi-)master with a slave address, such +that it can be addressed by other multi-masters. + +\note This driver includes a workaround that uses both I2C peripherals on the +RP2040. To use this driver, make sure you initialize both I2C peripherals, and +connect their respective SDA and SCL pins to the same I2C bus. + +\par Usage +- Link the \c pbdrv-mod library with your main executable +- Call the \c pb_setup() function (from \c <pb-mod.h>) during setup + +\note This driver is automatically enabled if the variable \c PICO_PLATFORM is +equal to \c "rp2040" in your CMakeLists.txt (it is by default when using the +pico-sdk CMake library). + +\note This driver automatically includes the \ref pb_ext_stdlib +"stdlib extension" as the pico-sdk implements the C standard library. + +*/ + diff --git a/lib/pbdrv/drv/rp2040/mod.c b/lib/pbdrv/drv/rp2040/mod.c new file mode 100644 index 0000000..1535da9 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/mod.c @@ -0,0 +1,49 @@ +#include "pb.h" + +#include "pb.h" +#include "pb-types.h" +#include "pb-mod.h" +#include "pb-send.h" +#include "pb-buf.h" + +#include <hardware/i2c.h> +#include <hardware/gpio.h> +#include <pico/i2c_slave.h> + +#define PB_I2C_S i2c0 +#define PB_I2C_M i2c1 + +#define BUF_SIZE 256 + +uint8_t i2c_msg_buf[BUF_SIZE]; +size_t i2c_msg_buf_sz = 0; + +// This function is called from the I2C ISR +static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) { + switch (event) { + case I2C_SLAVE_RECEIVE: { + if (i2c_msg_buf_sz == BUF_SIZE) return; + i2c_msg_buf[i2c_msg_buf_sz++] = i2c_read_byte_raw(PB_I2C_S); + break; + } + case I2C_SLAVE_FINISH: { + pb_i2c_recv(i2c_msg_buf, i2c_msg_buf_sz); + i2c_msg_buf_sz = 0; + break; + } + default: break; + } +} + +void pb_setup() { + i2c_init(PB_I2C_S, PB_CLOCK_SPEED_HZ); + i2c_init(PB_I2C_M, PB_CLOCK_SPEED_HZ); + + i2c_slave_init(PB_I2C_S, PB_MOD_ADDR, &recv_event); +} + +__weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { + // false to write stop condition to i2c bus + i2c_write_timeout_us(PB_I2C_M, addr, buf, sz, false, PB_TIMEOUT_US); +} + diff --git a/lib/pbdrv/drv/rp2040/pb-mod.h b/lib/pbdrv/drv/rp2040/pb-mod.h new file mode 100644 index 0000000..96edc70 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/pb-mod.h @@ -0,0 +1,21 @@ +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup pb_drv_rp2040 + * \brief Puzzle bus driver setup + * + * This function must be called from a setup/init function to initialize the + * I2C peripherals used by this driver. + */ +void pb_setup(); + +#ifdef __cplusplus +} +#endif + +#include "../../pb-mod.h" + diff --git a/lib/pbdrv/ext/freertos/include.cmake b/lib/pbdrv/ext/freertos/include.cmake index e7ab7fd..e205c8f 100644 --- a/lib/pbdrv/ext/freertos/include.cmake +++ b/lib/pbdrv/ext/freertos/include.cmake @@ -1,9 +1,7 @@ target_sources(pbdrv PRIVATE "${CMAKE_CURRENT_LIST_DIR}/pb-mem.c") -target_link_libraries(pbdrv +target_link_libraries(pbdrv PUBLIC freertos_kernel freertos_kernel_include freertos_config ) -target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/pb-mod.c") - diff --git a/lib/pbdrv/ext/freertos/index.dox b/lib/pbdrv/ext/freertos/index.dox new file mode 100644 index 0000000..7d72918 --- /dev/null +++ b/lib/pbdrv/ext/freertos/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup pb_ext +\defgroup pb_ext_freertos FreeRTOS +\brief FreeRTOS memory management +*/ diff --git a/lib/pbdrv/ext/freertos/pb-mem.c b/lib/pbdrv/ext/freertos/pb-mem.c index b18d79f..6647f05 100644 --- a/lib/pbdrv/ext/freertos/pb-mem.c +++ b/lib/pbdrv/ext/freertos/pb-mem.c @@ -3,24 +3,29 @@ #include "../../pb-mem.h" #include "../../pb-types.h" +/// \ingroup pb_ext_freertos inline void * pb_malloc(size_t sz) { return pvPortMalloc(sz); } +/// \ingroup pb_ext_freertos inline void pb_free(void * ptr) { vPortFree(ptr); } +/// \ingroup pb_ext_freertos __weak inline void * pb_realloc(void * ptr, size_t sz) { return NULL; // shit out of luck (don't use mpack_writer_init_growable) } +/// \ingroup pb_ext_freertos __weak void * pb_memcpy(void * dest, const void * src, size_t sz) { for (size_t offset = 0; offset < sz; offset++) *((char*) dest + offset) = *((char*) src + offset); return dest; } +/// \ingroup pb_ext_freertos __weak int pb_memcmp(const void * a, const void * b, size_t sz) { for (size_t offset = 0; offset < sz; offset++) { int diff = *((char*) a + offset) - *((char*) b + offset); diff --git a/lib/pbdrv/ext/freertos/pb-mod.c b/lib/pbdrv/ext/freertos/pb-mod.c deleted file mode 100644 index 75495be..0000000 --- a/lib/pbdrv/ext/freertos/pb-mod.c +++ /dev/null @@ -1,9 +0,0 @@ -#include <FreeRTOS.h> -#include <task.h> - -#include "../../pb-types.h" - -__weak void pb_mod_blocking_delay_ms(unsigned long ms) { - vTaskDelay(ms / portTICK_PERIOD_MS); -} - diff --git a/lib/pbdrv/ext/index.dox b/lib/pbdrv/ext/index.dox new file mode 100644 index 0000000..f7d2bc6 --- /dev/null +++ b/lib/pbdrv/ext/index.dox @@ -0,0 +1,24 @@ +// vim:ft=doxygen +/** +\ingroup pbdrv +\ingroup pbdrv-mod +\defgroup pb_ext Extensions +\brief Platform-specific \ref pbdrv implementations + +Extensions provide platform-specific implementations for various functions used +in \ref pbdrv, and allows \ref pbdrv to remain completely portable. Extensions +are used in both \ref pbdrv and \ref pbdrv-mod. + +In order to use an extension, include the appropriate CMake lists file for your +target platform after the \ref pbdrv include: + +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# use stdlib extension (for use with C standard library) +include(lib/pbdrv/ext/stdlib/include.cmake) + +``` + +*/ diff --git a/lib/pbdrv/ext/stdlib/index.dox b/lib/pbdrv/ext/stdlib/index.dox new file mode 100644 index 0000000..756af1e --- /dev/null +++ b/lib/pbdrv/ext/stdlib/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup pb_ext +\defgroup pb_ext_stdlib stdlib +\brief C stdlib memory management +*/ diff --git a/lib/pbdrv/ext/stdlib/pb-mem.c b/lib/pbdrv/ext/stdlib/pb-mem.c index b260c2c..328efbb 100644 --- a/lib/pbdrv/ext/stdlib/pb-mem.c +++ b/lib/pbdrv/ext/stdlib/pb-mem.c @@ -3,22 +3,27 @@ #include "../../pb-mem.h" +/// \ingroup pb_ext_stdlib inline void * pb_malloc(size_t sz) { return malloc(sz); } +/// \ingroup pb_ext_stdlib inline void pb_free(void * ptr) { free(ptr); } +/// \ingroup pb_ext_stdlib inline void * pb_realloc(void * ptr, size_t sz) { return realloc(ptr, sz); } +/// \ingroup pb_ext_stdlib void * pb_memcpy(void * dest, const void * src, size_t sz) { return memcpy(dest, src, sz); } +/// \ingroup pb_ext_stdlib int pb_memcmp(const void * a, const void * b, size_t sz) { return memcmp(a, b, sz); } diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox new file mode 100644 index 0000000..8ddcb6a --- /dev/null +++ b/lib/pbdrv/index.dox @@ -0,0 +1,73 @@ +// vim:ft=doxygen +/** + +\defgroup pbdrv pbdrv +\brief Standalone puzzle bus driver + +\ref pbdrv is a standalone portable static library for handling (i.e. +(de)serialization) of puzzle bus messages. \ref pbdrv is meant for use within +applications that handle puzzle bus messages, but are not puzzle modules +themselves. For a complete puzzle module driver, please see \ref pbdrv-mod. + +If you order to use \ref pbdrv, you need to include this folder in your +CMakeLists.txt file, include the \ref pb_ext "extension" for your target +platform, and link the \c pbdrv library with your executable. + +\par Example +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# <use extension> + +# link with executable +target_link_libraries(main pbdrv) +``` + + +\defgroup pbdrv-mod pbdrv-mod +\brief Puzzle module driver (superset of \ref pbdrv) + +pbdrv-mod is a superset of \ref pbdrv, and includes functions specific to +puzzle bus modules. \ref pbdrv-mod compiles to an object file instead of a +static library because it may depend on functions that rely on external +libraries. \ref pbdrv-mod is still considered standalone, but requires either +using an existing \ref pb_drv "driver", or (partially) implementing the driver +functions. + +Like \ref pbdrv, \ref pbdrv-mod can be used by including this folder in your +CMakeLists.txt file and linking the library with your executable. Please see +the \ref pb_drv "drivers" page for target-specific usage instructions. + +\par Example +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# link with executable +target_link_libraries(main pbdrv-mod) +``` + +\note In most cases, the \ref pb_hook "hooks" should be sufficient to realize +extensions or custom behavior not provided by \ref pbdrv-mod. + +\note Most \c pb_* functions have a weak implementation, which may be +overwritten by a custom implementation. This allows you to use the default +implementation where possible, and only implement extensions required for your +puzzle module. + +\see pbdrv + +\{ + +\defgroup pb_hook Hook +\brief Functions for (partially) overriding default behavior + +Hooks are functions that allow the user to implement custom behavior (i.e. +extend or conditionally replace the default handlers), without needing to +completely overwrite the built-in handlers or understand the internals of \ref +pbdrv-mod. + +\} + +*/ diff --git a/lib/pbdrv/pb-buf.h b/lib/pbdrv/pb-buf.h index 78ee380..8b4bb10 100644 --- a/lib/pbdrv/pb-buf.h +++ b/lib/pbdrv/pb-buf.h @@ -6,14 +6,30 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_buf Buffer + * \brief Binary data buffer type used in \ref pbdrv + * \{ + */ + //! binary buffer struct typedef struct { - char * data; //! pointer to data - size_t size; //! size of data + char * data; //!< pointer to data + size_t size; //!< size of data } pb_buf_t; +/** + * \brief free a \c pb_buf_t + * + * This function calls \c pb_free() on the \c data member of a \c pb_buf_t + * struct if it is not equal to \c NULL. + */ void pb_buf_free(pb_buf_t * buf); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-mem.h b/lib/pbdrv/pb-mem.h index 72be214..4d0f995 100644 --- a/lib/pbdrv/pb-mem.h +++ b/lib/pbdrv/pb-mem.h @@ -6,13 +6,68 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_mem Memory + * \brief Platform-specific memory management functions + * + * \note This header only declares the memory management functions, and it is + * up to \ref pb_ext "extensions" to implement the underlying memory management + * functions. + * + * TODO: ref to extensions + * + * \{ + */ + +/** + * \brief Allocate a contiguous chunk of memory + * \param sz Requested size of memory area + * \return Pointer to memory area, or \c NULL on failure + * \note The allocated memory must be free'd again using \c pb_free() + */ void * pb_malloc(size_t sz); +/** + * \brief Free a chunk of memory previously allocated with \c pb_malloc() + * \param ptr Pointer to memory area + */ void pb_free(void * ptr); +/** + * \brief Resize the memory area \c ptr to size \c sz + * \param ptr Pointer to allocated memory area + * \param sz Requested new size of memory area + * \return Pointer to memory area, or \c NULL on failure + * \warning This function is not available on FreeRTOS, and should be avoided + * if possible. MPack's \c mpack_writer_init_growable() is known to use \c + * realloc(), and should not be used for this reason. + */ void * pb_realloc(void * ptr, size_t sz); +/** + * \brief copy a memory region + * \param dest Pointer to destination memory + * \param src Pointer to source memory + * \param sz Number of bytes to copy + * \return Pointer to \c dest + * + * This function has a portable implementation, and is always available. + */ void * pb_memcpy(void * dest, const void * src, size_t sz); +/** + * \brief compare two memory regions + * \param a Pointer to first memory region + * \param b Pointer to second memory region + * \param sz Number of bytes to compare + * \return 0 if the memory regions are identical, or the difference between the + * first non-matching byte + * + * This function has a portable implementation, and is always available. + */ int pb_memcmp(const void * a, const void * b, size_t sz); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index ae36d22..91e1d1f 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -1,38 +1,100 @@ #pragma once -/** - * \file puzzle bus driver implementation - * - * Most \c pb_* functions have a weak implementation, which may be - * overwritten by a custom implementation. This allows you to use the default - * implementation where possible, and only implement extensions required for - * your puzzle module. Please see spec.adoc for more information about how to - * use the puzzle bus driver library. - */ - #include "pb-types.h" #ifdef __cplusplus extern "C" { #endif -//! puzzle module name (optional, default = "???") +/** + * \ingroup pbdrv-mod + * \defgroup pb_mod Module + * \brief Puzzle module metadata and auxiliary utility functions + * \{ + */ + +/** + * \brief Puzzle module name + * \note This constant is optional to define, its default value is "???" + */ extern const char * PB_MOD_NAME; -//! puzzle module bus address (required) +/** + * \brief Puzzle module bus address + * \warning This variable **must** be defined by the user + */ extern const i2c_addr_t PB_MOD_ADDR; +/// \} + +/** + * \ingroup pbdrv-mod + * \defgroup pb_i2c I2C + * \brief I2C send/receive handlers + * + * \{ + */ + +/** + * \brief Handle a received message from the I2C bus (puzzle bus) + * + * This function attempts to parse an I2C message as a puzzle bus message, and + * calls the appropriate handler for the message if it is considered valid. + * Invalid messages are silently ignored. + * + * \param buf pointer to message content + * \param sz size of \p buf + * + * \note This function should not be directly called from an ISR. Please use + * FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based + * deferred function call mechanism instead. + */ void pb_i2c_recv(const uint8_t * buf, size_t sz); +/** + * \brief Send a message in master-mode on the I2C bus (puzzle bus) + * + * This function sends an I2C message to the address specified by \p i2c_addr. + * + * \param i2c_addr address of slave controller + * \param buf pointer to message content + * \param sz size of \p buf + */ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); -pb_global_state_t pb_hook_mod_state_read(); -void pb_hook_mod_state_write(pb_global_state_t state); +/// \} + +/// \ingroup pb_hook +/// \{ /** - * \brief platform-specific blocking delay function + * \defgroup pb_hook_mod_state State + * \brief Provide your own global state variable * - * FIXME: this should be removed (see handover: RP2040 I2C limitations) + * If your puzzle module defines its own global \c pb_global_state_t, you can + * tell the driver to use it by implementing these functions. These functions + * are also used internally by the driver. + * + * \{ */ -void pb_mod_blocking_delay_ms(unsigned long ms); + +/** + * \brief global state read hook + * \return current value of global state enum + * + * The default implementation of this function uses an internal global state + * variable in \ref pbdrv. + */ +pb_global_state_t pb_hook_mod_state_read(); +/** + * \brief global state write hook + * \param state new value of global state enum + * + * The default implementation of this function uses an internal global state + * variable in \ref pbdrv. + */ +void pb_hook_mod_state_write(pb_global_state_t state); + +/// \} +/// \} #ifdef __cplusplus } diff --git a/lib/pbdrv/pb-msg.h b/lib/pbdrv/pb-msg.h index f27d4c4..ff5bcde 100644 --- a/lib/pbdrv/pb-msg.h +++ b/lib/pbdrv/pb-msg.h @@ -7,10 +7,53 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_msg Message + * \brief Message (de)serialization + * \{ + */ + +/** + * \brief Serialize a message into a binary buffer + * + * \note This function allocates a \c pb_buf_t that should be free'd using \c + * pb_buf_free() + * + * \param msg Message to serialize + * + * \warning The type of \c msg->cmd is inferred from \c msg->type. If the + * message is not correctly formatted, this function may cause undefined + * behavior. If possible, use functions from \ref pb_send instead. + * + * \return \c pb_buf_t containing the serialized message, or an empty struct if + * serialization failed + */ pb_buf_t pb_msg_write(const pb_msg_t * msg); +/** + * \brief Read a binary buffer and attempt to deserialize it as a puzzle bus + * message + * + * \note This function allocates a \c pb_msg_t pointer that should be free'd + * using \c pb_msg_free() + * + * \param buf Binary data to interpret as puzzle bus message + * + * \return \c pb_msg_t pointer containing the deserialized message, or NULL if + * serialization failed + */ pb_msg_t * pb_msg_read(const pb_buf_t * buf); +/** + * \brief Recursively free fields of a \c pb_msg_t + * + * \note The \p msg pointer itself is also free'd by this function. You should + * set it to NULL afterwards to avoid confusion. + */ void pb_msg_free(pb_msg_t * msg); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-route.c b/lib/pbdrv/pb-route.c index ee47700..5a7bd67 100644 --- a/lib/pbdrv/pb-route.c +++ b/lib/pbdrv/pb-route.c @@ -56,19 +56,27 @@ __weak void pb_route_cmd_prop_req(pb_msg_t * msg) {} __weak void pb_route_cmd_prop_res(pb_msg_t * msg) {} __weak void pb_route_cmd_prop_set(pb_msg_t * msg) {} +//! last known global state of last STATE REQ sender (i.e. main controller) static pb_global_state_t _main_state = PB_GS_NOINIT; -__weak void pb_hook_main_state_update(pb_global_state_t state) {} +__weak void pb_hook_ev_main_state_update(pb_global_state_t state) {} +__weak void pb_hook_ev_module_init() { + pb_hook_mod_state_write(PB_GS_IDLE); +} __weak void pb_route_cmd_state_req(pb_msg_t * msg) { pb_global_state_t own_state = pb_hook_mod_state_read(); - pb_buf_t buf = pb_send_state_res(own_state); - pb_send_reply(msg, &buf); - pb_buf_free(&buf); // notify of new global state variable pb_cmd_state_t * cmd = msg->cmd; - if (cmd->state != _main_state) - pb_hook_main_state_update(cmd->state); + if (cmd->state != _main_state) { + // first STATE REQ = module init OK + if (_main_state == PB_GS_NOINIT) pb_hook_ev_module_init(); + pb_hook_ev_main_state_update(cmd->state); + } _main_state = cmd->state; + + pb_buf_t buf = pb_send_state_res(); + pb_send_reply(msg, &buf); + pb_buf_free(&buf); } __weak void pb_route_cmd_state_res(pb_msg_t * msg) {} @@ -85,9 +93,6 @@ __weak void pb_route_cmd_magic_req(pb_msg_t * msg) { // // return early if magic doesn't match if (pb_memcmp(cmd->magic, pb_cmd_magic_req, sizeof(pb_cmd_magic_req)) != 0) return; - // FIXME: this should be removed (see handover: RP2040 I2C limitations) - pb_mod_blocking_delay_ms(2000); - pb_buf_t buf = pb_send_magic_res(); pb_send_reply(msg, &buf); pb_buf_free(&buf); diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index 41c009a..2a28c0b 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -6,31 +6,190 @@ extern "C" { #endif -void pb_route_msg(pb_msg_t * msg); +/** + * \ingroup pbdrv-mod + * \defgroup pb_route Routing + * \internal + * \brief Parsed message handler routing + * + * These functions form a tree-shaped call graph, and are used to handle + * specific commands received from \c pb_i2c_recv(). + * + * \{ + */ -bool pb_hook_route_msg(pb_msg_t * msg); +/** + * \brief Handle a message with type {\ref PB_CMD_PROP "PROP", \ref + * PB_CMD_STATE "STATE", \ref PB_CMD_MAGIC "MAGIC"} + * + * Calls the next handler depending on \c msg->type. + */ +void pb_route_msg(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action {\ref + * pb_route_cmd_prop_req "REQ", \ref pb_route_cmd_prop_res "RES", \ref + * pb_route_cmd_prop_set "SET"} + * + * Calls the next handler depending on \c msg->action. + */ void pb_route_cmd_prop(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action {\ref + * pb_route_cmd_state_req "REQ", \ref pb_route_cmd_state_res "RES", \ref + * pb_route_cmd_state_set "SET"} + * + * Calls the next handler depending on \c msg->action. + */ void pb_route_cmd_state(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action {\ref + * pb_route_cmd_magic_req "REQ", \ref pb_route_cmd_magic_res "RES"} + * + * Calls the next handler depending on \c msg->action. + * + * \note Messages with type \c MAGIC and action \c SET will be silently + * ignored, as there is no such command. + */ void pb_route_cmd_magic(pb_msg_t * msg); -bool pb_hook_route_cmd_prop(pb_msg_t * msg); -bool pb_hook_route_cmd_state(pb_msg_t * msg); -bool pb_hook_route_cmd_magic(pb_msg_t * msg); - +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_res(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_SET "SET" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_set(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function does the following: + * - Call \c pb_hook_ev_module_init() if this is the first received \c STATE \c + * REQ command. + * - Call \c pb_hook_ev_main_state_update() if the main controller state has + * changed. + * - Reply with a \c STATE \c RES message. + */ void pb_route_cmd_state_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as only the main + * controller handles this type of command. + */ void pb_route_cmd_state_res(pb_msg_t * msg); +// TODO: add link to pb_route_cmd_state_res handler in main/i2c.c +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_SET "SET" + * + * The default implementation of this function does the following: + * - Write the global state variable using \c pb_hook_mod_state_write(). + */ void pb_route_cmd_state_set(pb_msg_t * msg); -void pb_hook_main_state_update(pb_global_state_t state); - +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function does the following: + * - Verify the size of the magic string + * - Verify the content of the magic string + * - Reply with a \c MAGIC \c RES message. + */ void pb_route_cmd_magic_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as only the main + * controller handles this type of command. (\ref main_route_cmd_magic_res + * "link") + */ void pb_route_cmd_magic_res(pb_msg_t * msg); +/// \} + +/** + * \ingroup pb_hook + * \defgroup pb_hook_route Routing + * \brief Conditionally use substitute or extend the built-in message handlers + * \{ + */ + +/** + * \brief \c pb_route_msg() hook + * + * The default implementation of this function immediately returns false. + * + * \return \c true if execution should continue to the default handler, or \c + * false if it should stop (i.e. the message was handled). + */ +bool pb_hook_route_msg(pb_msg_t * msg); + +//! \c pb_route_cmd_prop() hook \copydetails pb_hook_route_msg +bool pb_hook_route_cmd_prop(pb_msg_t * msg); +//! \c pb_route_cmd_state() hook \copydetails pb_hook_route_msg +bool pb_hook_route_cmd_state(pb_msg_t * msg); +//! \c pb_route_cmd_magic() hook \copydetails pb_hook_route_msg +bool pb_hook_route_cmd_magic(pb_msg_t * msg); + +/// \} + +/** + * \ingroup pb_hook + * \defgroup pb_hook_ev Events + * \brief Functions called on puzzle bus-related events + * \{ + */ + +/** + * \brief Main controller state update hook + * + * The default implementation of this function is empty. + * + * \param state New state of main controller + * + * \note This function is also called when the first \c STATE \c REQ command is + * received, as the main controller state variable used to check if the state + * actually changed is initialized to \ref PB_GS_NOINIT. In this case, this + * function is called *after* \c pb_hook_ev_module_init(). + */ +void pb_hook_ev_main_state_update(pb_global_state_t state); +/** + * \brief Module initialized hook + * + * The default implementation of this function calls \c + * pb_hook_mod_state_write() with \ref PB_GS_IDLE. + * + * This function is called when the first \c STATE \c REQ command is received, + * indicating this puzzle module has been registered successfully by the main + * controller, and is now part of an active play session. + */ +void pb_hook_ev_module_init(); + +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-send.c b/lib/pbdrv/pb-send.c index 66c43c1..dc34c44 100644 --- a/lib/pbdrv/pb-send.c +++ b/lib/pbdrv/pb-send.c @@ -2,7 +2,7 @@ #include "pb-mod.h" #include "pb-msg.h" -__weak void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply) { +__weak void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply) { return pb_i2c_send(msg->sender, (uint8_t *) reply->data, reply->size); } @@ -21,10 +21,10 @@ pb_buf_t pb_send_read_req(uint8_t propid) { return pb_msg_write(&msg); } -pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) { +pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size) { pb_cmd_prop_t cmd = { .propid = propid, - .value = value, + .value = (uint8_t *) value, ._value_size = size, }; pb_msg_t msg = { @@ -36,10 +36,10 @@ pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) { return pb_msg_write(&msg); } -pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size) { +pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size) { pb_cmd_prop_t cmd = { .propid = propid, - .value = value, + .value = (uint8_t *) value, ._value_size = size, }; pb_msg_t msg = { @@ -64,9 +64,9 @@ pb_buf_t pb_send_state_req() { return pb_msg_write(&msg); } -pb_buf_t pb_send_state_res(pb_global_state_t state) { +pb_buf_t pb_send_state_res() { pb_cmd_state_t cmd = { - .state = state, + .state = pb_hook_mod_state_read(), }; pb_msg_t msg = { .type = PB_CMD_STATE, diff --git a/lib/pbdrv/pb-send.h b/lib/pbdrv/pb-send.h index 2f8be1e..7e21eda 100644 --- a/lib/pbdrv/pb-send.h +++ b/lib/pbdrv/pb-send.h @@ -7,17 +7,126 @@ extern "C" { #endif -void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply); +/** + * \ingroup pbdrv-mod + * \defgroup pb_send Send + * \brief Functions for directly creating serialized message buffers + * \{ + */ +/** + * \brief Utility function for replying to a message + * + * \param msg Message to reply to + * \param reply Data to send as reply + * + * This function uses \c pb_i2c_send() to send \p reply to \p msg->sender. + */ +void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply); + +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_REQ "REQ" + * message + * + * \param propid Property ID to request + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_read_req(uint8_t propid); -pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size); -pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_RES "RES" + * message + * + * \param propid Requested property ID + * \param value Pointer to structured data in property + * \param size Size of \p value + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ +pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_SET "SET" + * message + * + * \param propid Property ID to write + * \param value Pointer to data to write to property + * \param size Size of \p value + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ +pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_REQ + * "REQ" message + * + * The current module's state is obtained using \c pb_hook_mod_state_read(). + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_state_req(); -pb_buf_t pb_send_state_res(pb_global_state_t state); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_RES + * "RES" message + * + * The current module's state is obtained using \c pb_hook_mod_state_read(). + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ +pb_buf_t pb_send_state_res(); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_SET + * "SET" message + * + * \param state Requested new state + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_state_set(pb_global_state_t state); +/** + * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_REQ + * "REQ" message + * + * The magic string is equal to \ref pb_cmd_magic_req. + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_magic_req(); +/** + * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_RES + * "RES" message + * + * The magic string is equal to \ref pb_cmd_magic_res. + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_magic_res(); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-serial.h b/lib/pbdrv/pb-serial.h index d3d0007..79f08d7 100644 --- a/lib/pbdrv/pb-serial.h +++ b/lib/pbdrv/pb-serial.h @@ -8,23 +8,77 @@ extern "C" { #endif -#define __pb_cmd(name) \ - pb_ser_r_t pb_ser_r_##name; \ - pb_ser_w_t pb_ser_w_##name; \ - pb_ser_free_t pb_ser_free_##name; +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_ser Serial + * \internal + * \brief Internal (de)serialization functions using mpack + * + * \{ + */ +/** + * \brief Write (serialize) message fields using mpack + * + * \param writer Pointer to \c mpack_writer_t instance + * \param msg Pointer to message struct to read from + */ typedef void pb_ser_w_t(mpack_writer_t * writer, const pb_msg_t * msg); -pb_ser_w_t pb_ser_w; - +/** + * \brief Read (deserialize) message fields using mpack + * + * \param reader Pointer to \c mpack_reader_t instance + * \param msg Pointer to message struct to write to + */ typedef void pb_ser_r_t(mpack_reader_t * reader, pb_msg_t * msg); -pb_ser_r_t pb_ser_r; - +/** + * \brief Recursively free message struct fields + * + * \param msg Pointer to message struct to free + */ typedef void pb_ser_free_t(pb_msg_t * msg); + +/** + * \brief Write the \ref pb_msg_t header fields and call another function for + * \p msg->cmd. + * \see pb_ser_w_t + */ +pb_ser_w_t pb_ser_w; +/** + * \brief Read the \ref pb_msg_t header fields and call another function for \p + * msg->cmd. + * \see pb_ser_r_t + */ +pb_ser_r_t pb_ser_r; +/** + * \brief Call another function for \p msg->cmd. + * \see pb_ser_free_t + */ pb_ser_free_t pb_ser_free; -__pb_cmd(cmd_prop) -__pb_cmd(cmd_state) -__pb_cmd(cmd_magic) +//! Write the \ref pb_cmd_prop_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_prop; +//! Read the \ref pb_cmd_prop_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_prop; +//! Free the \ref pb_cmd_prop_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_prop; + +//! Write the \ref pb_cmd_state_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_state; +//! Read the \ref pb_cmd_state_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_state; +//! Free the \ref pb_cmd_state_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_state; + +//! Write the \ref pb_cmd_magic_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_magic; +//! Read the \ref pb_cmd_magic_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_magic; +//! Free the \ref pb_cmd_magic_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_magic; + +/// \} #ifdef __cplusplus } diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h index 861fa85..44b590b 100644 --- a/lib/pbdrv/pb-types.h +++ b/lib/pbdrv/pb-types.h @@ -8,63 +8,125 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_types Types + * \brief Datatypes used within \ref pbdrv + * + * \{ + */ + #ifdef __GNUC__ #define __weak __attribute__((weak)) #endif #ifndef __weak #error Could not determine weak attribute for current compiler +//! Mark function as weak (allow user to override implementation) #define __weak #endif //! I2C address (10 or 7 bit) typedef uint16_t i2c_addr_t; -//! puzzle bus command types -enum pb_cmd_id { - PB_CMD_PROP, //!< puzzle module property - PB_CMD_STATE, //!< global state - PB_CMD_MAGIC, //!< magic (handshake) -}; -typedef enum pb_cmd_id pb_cmd_id_t; +//! Puzzle bus command types +typedef enum { + /** + * \brief puzzle module property (\ref pb_route_cmd_prop_req "REQ", \ref + * pb_route_cmd_prop_res "RES", \ref pb_route_cmd_prop_set "SET") + * + * The \c PROP command type is used for exchanging arbitrary data between + * puzzle modules and/or the puzzle box client (pbc) over the TCP bridge. + * These properties are not used by the puzzle framework. + */ + PB_CMD_PROP, + /** + * \brief puzzle module global state variable (\ref pb_route_cmd_state_req + * "REQ", \ref pb_route_cmd_state_res "RES", \ref pb_route_cmd_state_set + * "SET") + * + * The \c STATE command is used by puzzle modules to inform the main + * controller about their global state. The main controller aggregates the + * states of all connected puzzle modules and exchanges this aggregated state + * with the puzzle modules to indicate when the entire puzzle box is solved. + */ + PB_CMD_STATE, + /** + * \brief magic (handshake) (\ref pb_route_cmd_magic_req "REQ", \ref + * pb_route_cmd_magic_res "RES") + * + * The \c MAGIC command effectively serves as a 'secret handshake' (using a + * _magic_ value) which is used to distinguish between puzzle modules and + * unrelated I2C devices. + */ + PB_CMD_MAGIC, +} pb_cmd_id_t; -//! puzzle bus command action types -enum pb_action { +//! Puzzle bus command action types +typedef enum { PB_ACTION_REQ, //!< request PB_ACTION_RES, //!< response PB_ACTION_SET, //!< (over)write -}; -typedef enum pb_action pb_action_t; +} pb_action_t; -//! puzzle bus global states -enum pb_global_state { +//! Puzzle module global states +typedef enum { PB_GS_NOINIT, //!< uninitialized (only used by puzzle modules) PB_GS_IDLE, //!< puzzle not started yet PB_GS_PLAYING, //!< puzzle actively being solved PB_GS_SOLVED, //!< puzzle completed -}; -typedef enum pb_global_state pb_global_state_t; +} pb_global_state_t; -//! magic sent from main controller to puzzle module +/** + * \brief Magic sent from main controller to puzzle module (="puzbus") + * + * The size of this array can be obtained by \c sizeof(pb_cmd_magic_req). + */ static const char pb_cmd_magic_req[] = { 0x70, 0x75, 0x7a, 0x62, 0x75, 0x73 }; -//! magic reply from puzzle module back to main controller +/** + * \brief Magic reply from puzzle module back to main controller (="gaming") + * + * The size of this array can be obtained by \c sizeof(pb_cmd_magic_res). + */ static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 }; -//! puzzle bus message header (shared by all commands) +//! puzzle bus message header / container (shared by all commands) typedef struct { - pb_cmd_id_t type; //!< command type - pb_action_t action; //!< command action - i2c_addr_t sender; //!< i2c address of sender - void * cmd; //!< command data (type dependant) + /** + * \brief Command type (see \ref pb_cmd_id_t) + * + * This is used to identify what the message is about. + */ + pb_cmd_id_t type; + /** + * \brief Command action (see \ref pb_action_t) + * + * This is used to specify what should happen as a result of this message. + */ + pb_action_t action; + /** + * \brief I2C address of sender + * + * This is used to facilitate the 'network' features, as the sender of an I2C + * write is unknown. + */ + i2c_addr_t sender; + /** + * \brief Command data (dependent on \p type) + * + * Struct containing command type-specific data. + */ + void * cmd; } pb_msg_t; -//! PB_CMD_PROP data +//! \ref PB_CMD_PROP data typedef struct { uint8_t propid; //!< id of state property uint8_t * value; //!< new or current value - size_t _value_size; //!< [META] size of \p value + size_t _value_size; //!< size of \p value } pb_cmd_prop_t; -//! PB_CMD_STATE data +//! \ref PB_CMD_STATE data typedef struct { pb_global_state_t state; //!< global state } pb_cmd_state_t; @@ -75,12 +137,14 @@ typedef struct { pb_global_state_t state; //!< global state } pb_puzzle_module_t; -//! PB_CMD_MAGIC data +//! \ref PB_CMD_MAGIC data typedef struct { char * magic; //!< magic value - size_t _magic_size; //!< [META] size of \p magic + size_t _magic_size; //!< size of \p magic } pb_cmd_magic_t; +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h index 0f2e9d1..cef04d8 100644 --- a/lib/pbdrv/pb.h +++ b/lib/pbdrv/pb.h @@ -1,23 +1,43 @@ #pragma once +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb Bus + * \brief Constants for the puzzle bus hardware + * \{ + */ + +//! I2C bus speed in hertz (100 KHz) #define PB_CLOCK_SPEED_HZ 100000 +//! I2C bus timeout delay in milliseconds #define PB_TIMEOUT_MS 10 +//! I2C bus timeout delay in microseconds #define PB_TIMEOUT_US (1e3 * PB_TIMEOUT_MS) -// Adafruit NeoTrellis modules +//! Adafruit NeoTrellis module 1 I2C address #define PB_ADDR_ADA_NEO_1 0x2E +//! Adafruit NeoTrellis module 2 I2C address #define PB_ADDR_ADA_NEO_2 0x2F +//! Adafruit NeoTrellis module 3 I2C address #define PB_ADDR_ADA_NEO_3 0x30 +//! Adafruit NeoTrellis module 4 I2C address #define PB_ADDR_ADA_NEO_4 0x32 -// Main controller +//! Main controller I2C address #define PB_ADDR_MOD_MAIN 0x08 -// Puzzle modules +//! NeoTrellis puzzle module I2C address #define PB_ADDR_MOD_NEOTRELLIS 0x21 +//! Software puzzle module I2C address #define PB_ADDR_MOD_SOFTWARE 0x22 +//! Hardware puzzle module I2C address #define PB_ADDR_MOD_HARDWARE 0x23 +//! Vault puzzle module I2C address #define PB_ADDR_MOD_VAULT 0x24 -// #define BUSADDR_MOD_AUTOMATION 0x25 +//! Automation puzzle module I2C address +#define BUSADDR_MOD_AUTOMATION 0x25 +//! Dummy puzzle module I2C address #define PB_ADDR_MOD_DUMMY 0x69 +/// \} diff --git a/lib/pbdrv/spec.adoc b/lib/pbdrv/spec.adoc deleted file mode 100644 index 3172e84..0000000 --- a/lib/pbdrv/spec.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= Puzzle module specification - -This folder contains an implementation of the puzzle bus protocol -specification, and is targeted at puzzle module developers. This document -describes the required implementation steps for integrating a new game into the -puzzle module framework. - -== The bus - -The puzzle bus carries data over a standard I^2^C bus. Additional details about -this bus can be found in the link:../../docs/design.adoc[Design document]. - -The following details are important to puzzle module developers, as they may -cause unexpected behavior: - -- *Addresses influence the puzzle box's behavior*. The order of puzzles is - determined by the puzzle module address. Two puzzle modules may use the same - address, but this will mean that they cannot be used simultaniously in the - same puzzle box. Known addresses are documented in link:bus.h[]. -- *The read/write bit of an I^2^C frame determines how it's handled*. I^2^C - *read* frames are treated as requests, while *write* frames are treated as - responses. - -== Puzzle bus driver (pbdrv) - -The library in this folder is a partial implementation of the puzzle bus -specification *for puzzle modules*. Most functions in the driver are marked -with the 'weak' attribute, which allows you to override them by providing an -implementation. - -In order to utilize this driver, the following must be done: - -- The ``pbdrv_i2c_recv`` function must be *called* for every received *I^2^C - read* frame -- The ``pbdrv_i2c_send`` function must be *implemented* with the - platform-specific *I^2^C write* function - -This is enough to get the puzzle module registered. You may also want to -implement some of the following integrations: - -- If your game uses the global state variable, you should implement the - <<sec:state-global,global state hooks>> to point the driver to your own - global state variable, and be notified of reads/writes to it. -- If you want to expose additional game state variables over the puzzle bus, - you should implement the <<sec:state-aux,auxiliary state hooks>>. -- If you want to implement custom puzzle bus commands, you can implement the - <<sec:cmd,command hook>>. - -All other kinds of integrations/hooks can likely be realized by overriding the -default implementations, but this is discouraged. - -[[sec:state-global]] -== Global state - -If your puzzle module defines its own global ``enum pb_state``, you can tell -the driver to use it by implementing the ``pbdrv_hook_state_read`` and -``pbdrv_hook_state_write`` functions. These functions are also used by the -default implementation of the read/write commands to address 0 (global state). - -Example: - -```c -pb_state_t global_state = PB_GS_NOINIT; - -pb_state_t pbdrv_hook_mod_state_read() { - return global_state; -} - -void pbdrv_hook_mod_state_write(pb_state_t state) { - global_state = state; -} -``` - -[[sec:state-aux]] -== Auxiliary state - -You can expose additional state variables by implementing the -``pbdrv_hook_read`` and ``pbdrv_hook_write`` functions. These functions should -return ``true`` for state addresses you want to override. - -Example: - -```c -#define CUSTOM_VAR_ADDR 0x01 -uint8_t my_custom_variable = 10; - -bool pbdrv_hook_read(uint16_t i2c_addr, uint8_t addr) { - switch (addr) { - case CUSTOM_VAR_ADDR: { - char res[] = { PB_CMD_READ, addr, my_custom_variable }; - pbdrv_i2c_send(i2c_addr, res, sizeof(res)); - break; - } - default: return false; - } - - return true; -} - -bool pbdrv_hook_write(uint16_t i2c_addr, uint8_t addr, const char * buf, size_t sz) { - switch (addr) { - case CUSTOM_VAR_ADDR: { - if (sz != 1) return false; - my_custom_variable = buf[0]; - break; - } - default: return false; - } - - return true; -} -``` - -[[sec:cmd]] -== Custom commands - -Similar to the auxiliary state, custom commands can be added by implementing -the ``pbdrv_hook_cmd`` function, which should return ``true`` for the -command(s) that you want to overwrite. - -Example: - -```c -bool pbdrv_hook_cmd(uint16_t i2c_addr, enum pb_cmd cmd, const char * buf, size_t sz) { - if (cmd == 0x54) { - printf("custom command received!\n"); - return true; - } - - return false; -} -``` - |