First draft

doc/examples/OBC+TTC/shared/incp/service.h

@@ -0,0 +1,75 @@
+// serivce.h - Defines INCP service interface and functions to implement per subsystem.
+
+#pragma once
+
+#include "incp2.h"
+#include "messaging.h"
+#include "asn1/out/incp_generated.h"
+
+
+
+// ==========================
+// === RTOS SETUP RELATED ===
+// ==========================
+
+/// @brief [DO NOT CALL] Entry point for the receiver task of the INCP service.
+/// @param args Not used
+/// @remark Do not call directly, instead, pass it to the RTOS during task creation.
+void incp_receiver_task(void *args);
+
+
+
+// ========================
+// === INCP SERVICE API ===
+// ========================
+
+/// @brief Sends a datareq message of a given ID to a given subsystem.
+/// @param subsystem The subsystem to target.
+/// @param id The ID of the variable/report to request.
+/// @return ERR_SUCCESS if successfully transmitted, an adequate error otherwise.
+err_t incp_async_datareq(endpoint_t subsystem, U32 id);
+
+/// @brief Sends a ping message to a given subsystem.
+/// @param subsystem The subsystem to target.
+/// @param bytes The data to populate the ping with. Must NULL or contain 32 readable bytes.
+/// @return ERR_SUCCESS if successfully transmitted, an adequate error otherwise.
+err_t incp_async_ping(endpoint_t subsystem, uint8_t *bytes);
+
+
+
+// ==================================
+// === TO IMPLEMENT PER SUBSYSTEM ===
+// ==================================
+
+/// @brief Implement this function to send (through whatever means, that's a you problem) the given buffer to a given
+///        destination. 
+/// @param destination Where to send the buffer.
+/// @param buf The buffer to send.
+/// @param size The length of the data in the buffer.
+/// @return ERR_SUCCESS if successful, an adequate error otherwise.
+/// @remark Do not __attribute__((weak)) to force linker error.
+err_t impl_transmit(endpoint_t destination, void *buf, size_t size);
+
+/// @brief Implement this function to populate msg_buf with the requested variables.
+/// @param data The destination to write to. Includes the variable/report id, which should not be changed.
+/// @return ERR_SUCCESS if successful, an adequate error otherwise.
+/// @remark Do not __attribute__((weak)) to force linker error.
+err_t impl_populate_dataret(AnyData *data);
+
+
+
+// === Callbacks ===
+
+/// @brief Implement this function as the callback handler to a dataret message. Can (but shoudln't) be empty.
+/// @param source The subsystem that send the message.
+/// @param data The buffer that holds the data. (See remarks)
+/// @remark Do not copy this value by reference, it's validity is only ensured during the execution of this function.
+/// @remark Do not __attribute__((weak)) to force linker error if undefined.
+void impl_callback_dataret(endpoint_t source, AnyData *data);
+
+/// @brief Implement this function as the callback handler to a pong message. Can (but shoudln't) be empty.
+/// @param source The subsystem that send the message.
+/// @param pong The received pong. (See remarks)
+/// @remark Do not copy this value by reference, it's validity is only ensured during the execution of this function.
+/// @remark Do not __attribute__((weak)) to force linker error if undefined.
+void impl_callback_pong(endpoint_t source, PingMsg *pong);