diff --git a/app/src/incphub/README.md b/app/src/incphub/README.md index f61c3c4..cffc521 100644 --- a/app/src/incphub/README.md +++ b/app/src/incphub/README.md @@ -17,3 +17,13 @@ Set as a macro in compile flags if wishing to override the defaults ## Setup - incphub_task_preinit MUST be run before any calls to the client, likely even before the scheduler is started + +## Buffer ownership + +Buffers are allocated with incphub_get_msg_buffer, at which point they belong to the requesting task. + +When passed to incphub_send_XXX functions, they become owned by incphub + +When dispatched internally, the receiving task becomes the owner and must invoke incphub_release_msg_buffer when done + +When routed externally, after calling the transmitter function, incphub releases the buffer diff --git a/app/src/incphub/include/incphub/incphub_client.h b/app/src/incphub/include/incphub/incphub_client.h index e27ce20..a6f25a3 100644 --- a/app/src/incphub/include/incphub/incphub_client.h +++ b/app/src/incphub/include/incphub/incphub_client.h @@ -28,7 +28,7 @@ int incphub_init_client(incphub_cli_t **cli, ntl_port_t port); /// @return INCPHUB_OK on success, an error otherwise int incphub_get_msg_buffer(incphub_cli_t *cli, uint8_t **buffer_ptr, size_t length); -/// @brief Releases a buffer previously acquired with incphub_get_msg_buffer +/// @brief Releases a buffer received from incphub_await_msg /// @param cli Current client handle /// @param buffer The buffer to release /// @return INCPHUB_OK on success, an error otherwise @@ -36,7 +36,7 @@ int incphub_release_msg_buffer(incphub_cli_t *cli, uint8_t *buffer); /// @brief Attempts to send a message to the local interface /// @param cli Current client handle -/// @param buffer The message buffer +/// @param buffer The message buffer (gets consumed) /// @param length The message length /// @param dst_port The destination NTL port /// @return INCPHUB_OK on success, an error otherwise