Add documentation

Inc/mmr_can.h

@@ -1,3 +1,9 @@
+/**
+ * @file mmr_can.h
+ * @brief
+ * Main header for the mmr_can library.
+ */
+
 #ifndef INC_MMR_CAN_H_
 #define INC_MMR_CAN_H_
 
@@ -30,7 +36,13 @@
 #define MMR_CAN_MAX_DATA_LENGTH 8
 #endif
 
+
 typedef uint32_t (*MmrCanTickProvider)();
+
+/**
+ * @brief
+ * A buffer large enough to hold a CAN payload.
+ */
 typedef uint8_t CanRxBuffer[MMR_CAN_MAX_DATA_LENGTH];
 
 
@@ -156,8 +168,15 @@ typedef struct {
   MMR_CAN_FilterConfig(phcan, MMR_CAN_GetDefaultFilterSettings())
 
 
+/**
+ * @brief
+ * A function that provides the current tick.
+ * Used to track the delay between message
+ * and acknowledgment. 
+ */
 extern MmrCanTickProvider __mmr_can_tickProvider;
 
+
 void MMR_CAN_Init(MmrCanTickProvider tickProvider);
 HalStatus MMR_CAN_BasicSetupAndStart(CanHandle *hcan);
 HalStatus MMR_CAN_FilterConfig(CanHandle *hcan, MmrCanFilterSettings settings);

Inc/mmr_can_events.h

@@ -1,3 +1,14 @@
+/**
+ * @file mmr_can_events.h
+ * @brief
+ * This header provides a set of utilities for working
+ * with interrupts.
+ * 
+ * The recommended way of readings the CAN bus is
+ * via polling, altought interrupt may be used for
+ * monitoring critical messages.
+ */
+
 #ifndef INC_MMR_CAN_EVENTS_H_
 #define INC_MMR_CAN_EVENTS_H_
 

Inc/mmr_can_header.h

@@ -1,3 +1,13 @@
+/**
+ * @file mmr_can_header.h
+ * @brief
+ * This file defines the header used for the can message,
+ * along with its utilities.
+ * 
+ * With header is intended the ExtendedId portion
+ * of the can message.
+ */
+
 #ifndef INC_MMR_CAN_HEADER_H_
 #define INC_MMR_CAN_HEADER_H_
 
@@ -49,7 +59,7 @@ typedef struct {
 
 /**
  * @brief
- * Converts an MmrCanHeader to bits.
+ * Serializes an MmrCanHeader to bits.
  * That is, a 32bits integer with the first
  * 3 bits set to zero and the remaining 29 containing the
  * extended id
@@ -58,8 +68,8 @@ uint32_t MMR_CAN_HeaderToBits(MmrCanHeader header);
 
 /**
  * @brief
- * Converts a 32bits integer to an MmrCanHeader.
- * The left-most 3 bits must be of padding.
+ * Deserializes a 32bits integer to an MmrCanHeader.
+ * The 3 left-most bits must be of padding.
  */
 MmrCanHeader MMR_CAN_HeaderFromBits(uint32_t bits);
 

Inc/mmr_can_includes.h

@@ -1,3 +1,13 @@
+/**
+ * @file mmr_can_includes.h
+ * @brief
+ * This header contains the include macros
+ * related to the external can_bus drivers.
+ * 
+ * These may be changed based on the board that is
+ * being used.
+ */
+
 #ifndef INC_MMR_CAN_INCLUDES_H_
 #define INC_MMR_CAN_INCLUDES_H_
 

Inc/mmr_can_message_id.h

@@ -1,3 +1,17 @@
+/**
+ * @file mmr_can_message_id.h
+ * @brief
+ * This header contains the message id declarations.
+ * 
+ * Message ids identify a message, allowing the receiver
+ * to take appropriate action when parsing one.
+ * 
+ * For example, a can packet with message id set to
+ * MMR_CAN_MESSAGE_ID_POINT might be interpreted as
+ * a message carrying a struct Point { int x; int y; };,
+ * and thus deserialized accordingly.
+ */
+
 #ifndef INC_MMR_CAN_MESSAGE_ID_H_
 #define INC_MMR_CAN_MESSAGE_ID_H_
 

Inc/mmr_can_optimize.h

@@ -1,3 +1,9 @@
+/**
+ * @file mmr_can_optimize.h
+ * @brief
+ * Low level optimization utilities.
+ */
+
 #ifndef INC_MMR_CAN_OPTIMIZE_H_
 #define INC_MMR_CAN_OPTIMIZE_H_
 

Inc/mmr_can_queue.h

@@ -1,14 +0,0 @@
-#ifndef INC_MMR_CAN_QUEUE_H_
-#define INC_MMR_CAN_QUEUE_H_
-
-#include <stdint.h>
-#include "mmr_can.h"
-
-#define MMR_CAN_QUEUE_SIZE 10
-
-typedef struct {
-  MmrCanMessage messages[MMR_CAN_QUEUE_SIZE];
-  size_t count;
-} MmrCanQueue;
-
-#endif /* INC_MMR_CAN_QUEUE_H_ */

Inc/mmr_can_scs_manager.h

@@ -1,3 +1,10 @@
+/**
+ * @file mmr_can_scs_manager.h
+ * @brief
+ * Provides utilities for managing the scs messages,
+ * such as transmission, retransmission and timeout error.
+ */
+
 #ifndef INC_MMR_CAN_SCS_MANAGER_H_
 #define INC_MMR_CAN_SCS_MANAGER_H_
 
@@ -5,8 +12,9 @@
 
 
 /**
- * Scs_timer represents the max number of counter
- * that need to checked w/current time
+ * @brief
+ * The maximum number of scs messages that
+ * can be tracked at any given time.
  */
 #ifndef MMR_CAN_SCS_ENTRIES_COUNT
 #define MMR_CAN_SCS_ENTRIES_COUNT 5
@@ -24,6 +32,7 @@
 
 
 /**
+ * @brief
  * It depends on how many bits the board devotes to the timer
  * Check the datasheet
  */
@@ -31,31 +40,111 @@ typedef uint32_t TimerRange;
 
 
 /**
- * @brief Represents the base-struct to manage a single RTR
+ * @brief
+ * Represents the base-struct to manage a single RTR
  * and allows to interface with the associated SCS's timer
  */
 typedef struct {
+  /**
+   * @brief
+   * The header used to index this entry.
+   */
   MmrCanHeader header;
+
+  /**
+   * @brief
+   * The time at which this message was sent,
+   * represented as milliseconds since the board
+   * was turned on.
+   */
   TimerRange counter;
+
+  /**
+   * @brief
+   * Number of retransmissions for this message.
+   * 
+   * == 0 -> No retransmission occurred.
+   * >= 1 -> The scs was retransmitted.
+   */
   int rtr;
 } MmrCanScsEntry;
 
 
+/**
+ * @brief
+ * The results of an scsCheck operation.
+ */
 typedef enum {
+  /**
+   * @brief No timeout error.
+   */
   MMR_CAN_SCS_CHECK_OK,
+
+  /**
+   * @brief The message should be retransmitted.
+   */
   MMR_CAN_SCS_CHECK_RTR,
+
+  /**
+   * @brief
+   * The message has timed out and has already been
+   * retransmitted, fail.
+   */
   MMR_CAN_SCS_CHECK_ERROR,
 } MmrCanScsCheckResult;
 
 
+/**
+ * @brief 
+ * Tries to handle an acknowledgment for a particular scs.
+ * 
+ * This function MUST be called every time a
+ * message is received, as it might potentially be an
+ * ACK.
+ * 
+ * @param header The header to check.
+ * @return true The message was an ACK and was cleared accordingly.
+ * @return false The message wasn't an ACK.
+ */
 bool MMR_CAN_MaybeHandleAck(MmrCanHeader header);
+
+/**
+ * @brief
+ * Checks the array with the stored scs messages and
+ * retransmits the message if no ack was received.
+ * 
+ * This function MUST be called at every loop.
+ * 
+ * @param hcan The interface to use.
+ * @return HalStatus
+ *  The result of the operation.
+ *  HAL_ERROR should immediately be handled as a safe state.
+ */
 HalStatus MMR_CAN_HandleNextScs(CanHandle *hcan);
 
+/**
+ * @brief
+ * Send an acknowledgment packet based on the
+ * given scs header.
+ * 
+ * @param hcan The can interface to use.
+ * @param originalHeader The scs header to acknowledge. 
+ * @return HalStatus The result of the operation.
+ */
 HalStatus MMR_CAN_SendAck(
   CanHandle *hcan,
   MmrCanHeader originalHeader
 );
 
+/**
+ * @brief
+ * Sends an Scs message.
+ * 
+ * @param hcan The can interface to use.
+ * @param scsId The MMR_CAN_MESSAGE_ID_SCS_xx id.
+ * @param senderId The id of this board.
+ * @return HalStatus The result of the operation.
+ */
 HalStatus MMR_CAN_SendScs(
   CanHandle *hcan,
   MmrCanMessageId scsId,

Inc/mmr_can_types.h

@@ -1,3 +1,9 @@
+/**
+ * @file mmr_can_types.h
+ * @brief
+ * Basic type definitions for the can.
+ */
+
 #ifndef INC_MMR_CAN_TYPES_H_
 #define INC_MMR_CAN_TYPES_H_
 

Inc/mmr_can_util.h

@@ -1,3 +1,9 @@
+/**
+ * @file mmr_can_util.h
+ * @brief
+ * Utility functions and macros.
+ */
+
 #ifndef INC_MMR_CAN_UTIL_H_
 #define INC_MMR_CAN_UTIL_H_
 

Src/mmr_can_send.c

@@ -14,6 +14,7 @@ typedef struct {
 } TransmissionParams;
 
 
+static TransmissionParams buildParams(CanHandle *hcan, MmrCanPacket packet);
 static HalStatus send(TransmissionParams *tp);
 static HalStatus sendNormal(TransmissionParams *tp);
 static HalStatus sendMulti(TransmissionParams *tp);
@@ -28,17 +29,8 @@ static CanMailbox __mailbox;
 
 
 HalStatus MMR_CAN_Send(CanHandle *hcan, MmrCanPacket packet) {
-  TransmissionParams tp = {
-    .handle = hcan,
-    .packet = &packet,
-    .headers.mmr = packet.header,
-    .headers.tx = {
-      .IDE = CAN_ID_EXT,
-      .RTR = CAN_RTR_DATA,
-      .DLC = packet.length,
-      .TransmitGlobalTime = DISABLE,
-    },
-  };
+  TransmissionParams tp =
+    buildParams(hcan, packet);
 
   syncHeaders(&tp);
   return packet.length <= MMR_CAN_MAX_DATA_LENGTH
@@ -48,7 +40,15 @@ HalStatus MMR_CAN_Send(CanHandle *hcan, MmrCanPacket packet) {
 
 
 HalStatus MMR_CAN_SendNoTamper(CanHandle *hcan, MmrCanPacket packet) {
-  TransmissionParams tp = {
+  TransmissionParams tp =
+    buildParams(hcan, packet);
+
+  return send(&tp);
+}
+
+
+static TransmissionParams buildParams(CanHandle *hcan, MmrCanPacket packet) {
+  return (TransmissionParams) {
     .handle = hcan,
     .packet = &packet,
     .headers.mmr = packet.header,
@@ -59,8 +59,6 @@ HalStatus MMR_CAN_SendNoTamper(CanHandle *hcan, MmrCanPacket packet) {
       .TransmitGlobalTime = DISABLE,
     },
   };
-
-  return send(&tp);
 }