From 8026f5ea83190fb3fde81525fe0f5878e213ac1c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 26 Jun 2024 15:10:58 +0200 Subject: add more cross-references and update old docs --- lib/pbdrv/drv/arduino/mod.cpp | 12 ++++++------ lib/pbdrv/pb-mod.h | 14 ++++++++++++-- lib/pbdrv/pb-route.h | 28 +++++++++++++++++++++++++--- 3 files changed, 43 insertions(+), 11 deletions(-) diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp index 81735af..27237d2 100644 --- a/lib/pbdrv/drv/arduino/mod.cpp +++ b/lib/pbdrv/drv/arduino/mod.cpp @@ -40,12 +40,12 @@ static void pb_setup() { /** * \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. + * \warning In the Arduino driver, 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 i2c_addr, const uint8_t * buf, size_t sz) { if (pb_hook_i2c_send(i2c_addr, buf, sz)) return; diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index 21e8100..0050869 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -44,9 +44,13 @@ extern const i2c_addr_t PB_MOD_ADDR; * \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 + * \see pb_hook_i2c_recv() + * + * \warning Some platforms produce weird behavior when replying directly from + * the I2C ISR. Please verify if this function can be called directly on your + * target platform when writing a new driver. If it does not work as expected, * FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based - * deferred function call mechanism instead. + * deferred function call mechanism may be used as a workaround. */ void pb_i2c_recv(const uint8_t * buf, size_t sz); /** @@ -57,6 +61,8 @@ void pb_i2c_recv(const uint8_t * buf, size_t sz); * \param i2c_addr address of slave controller * \param buf pointer to message content * \param sz size of \p buf + * + * \see pb_hook_i2c_send() */ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); @@ -108,6 +114,8 @@ void pb_hook_mod_state_write(pb_global_state_t state); * * \return \c false if execution should continue to the default handler, or \c * true if it should stop (i.e. the message was handled). + * + * \see pb_i2c_recv() */ bool pb_hook_i2c_recv(const uint8_t * buf, size_t sz); /** @@ -117,6 +125,8 @@ bool pb_hook_i2c_recv(const uint8_t * buf, size_t sz); * * \return \c false if execution should continue to the default handler, or \c * true if it should stop (i.e. the message was handled). + * + * \see pb_i2c_send() */ bool pb_hook_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index 8b7bba5..5c28f4d 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -23,6 +23,8 @@ extern "C" { * PB_CMD_STATE "STATE", \ref PB_CMD_MAGIC "MAGIC"} * * Calls the next handler depending on \c msg->type. + * + * \see pb_hook_route_msg() */ void pb_route_msg(pb_msg_t * msg); @@ -32,6 +34,8 @@ void pb_route_msg(pb_msg_t * msg); * pb_route_cmd_prop_set "SET"} * * Calls the next handler depending on \c msg->action. + * + * \see pb_hook_route_cmd_prop() */ void pb_route_cmd_prop(pb_msg_t * msg); /** @@ -40,6 +44,8 @@ void pb_route_cmd_prop(pb_msg_t * msg); * pb_route_cmd_state_set "SET"} * * Calls the next handler depending on \c msg->action. + * + * \see pb_hook_route_cmd_state() */ void pb_route_cmd_state(pb_msg_t * msg); /** @@ -50,6 +56,8 @@ void pb_route_cmd_state(pb_msg_t * msg); * * \note Messages with type \c MAGIC and action \c SET will be silently * ignored, as there is no such command. + * + * \see pb_hook_route_cmd_magic() */ void pb_route_cmd_magic(pb_msg_t * msg); @@ -144,14 +152,28 @@ void pb_route_cmd_magic_res(pb_msg_t * msg); * * \return \c false if execution should continue to the default handler, or \c * true if it should stop (i.e. the message was handled). + * + * \see pb_route_msg() */ bool pb_hook_route_msg(pb_msg_t * msg); -//! \c pb_route_cmd_prop() hook \copydetails pb_hook_route_msg +/** + * \brief \c pb_route_cmd_prop() hook + * \copydetails pb_hook_route_msg + * \see pb_route_cmd_prop() + */ bool pb_hook_route_cmd_prop(pb_msg_t * msg); -//! \c pb_route_cmd_state() hook \copydetails pb_hook_route_msg +/** + * \brief \c pb_route_cmd_state() hook + * \copydetails pb_hook_route_msg + * \see pb_route_cmd_state() + */ bool pb_hook_route_cmd_state(pb_msg_t * msg); -//! \c pb_route_cmd_magic() hook \copydetails pb_hook_route_msg +/** + * \brief \c pb_route_cmd_magic() hook + * \copydetails pb_hook_route_msg + * \see pb_route_cmd_magic() + */ bool pb_hook_route_cmd_magic(pb_msg_t * msg); /// \} -- cgit v1.2.3