aboutsummaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorLoek Le Blansch <loek@pipeframe.xyz>2024-06-26 15:10:58 +0200
committerLoek Le Blansch <loek@pipeframe.xyz>2024-06-26 15:10:58 +0200
commit8026f5ea83190fb3fde81525fe0f5878e213ac1c (patch)
treeac8e000a16b86448b3c9160cada5dbeaa37c636b /lib
parentcdd1034144da2f606d8f2a57061f694cdaa96cc1 (diff)
add more cross-references and update old docs
Diffstat (limited to 'lib')
-rw-r--r--lib/pbdrv/drv/arduino/mod.cpp12
-rw-r--r--lib/pbdrv/pb-mod.h14
-rw-r--r--lib/pbdrv/pb-route.h28
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);
/// \}