Scs (#3)

* Add send scs * Create scs dict * Fix compilation errors * Fix compile error * Change default include * Add Timer SCS manager * Remove unused files * Fix bugs * Add documentation * Add SCS manager bozza * Refactor * Use same naming convention * Add tick provider * Update header * Fix header bit translation * Test HandleNext OK * Remove linting * Remove indents * Add documentation * Improve docs * Remove pointer * Remove mailbox * Remove useless comment * Add newline * Fix compile errors * Separate scs entries from manager * Refactor * Fix include guards Co-authored-by: nicolagutierrez <nicolagutierrez.ng@gmail.com>
2022-02-23 21:08:47 +01:00
parent 7aa61ed9ad
commit 4d5c1934a4
20 changed files with 717 additions and 313 deletions
@@ -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_

@@ -8,6 +14,7 @@
 #include "mmr_can_types.h"
 #include "mmr_can_optimize.h"
 #include "mmr_can_binary_literals.h"
+#include "mmr_can_scs.h"

 #ifndef MMR_CAN_RX_FIFO
 #define MMR_CAN_RX_FIFO CAN_RX_FIFO0
@@ -29,6 +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];


@@ -65,9 +79,42 @@ typedef struct {
 } MmrCanFilterSettings;


+/**
+ * @brief
+ * A packet that can be sent over a CAN
+ * network.
+ *
+ * @example
+ * typedef struct {
+ *   int x;
+ *   int y;
+ * } Point;
+ *
+ * HalStatus send(Point point) {
+ *   MmrCanPacket packet = {
+ *     .header = {
+ *       .priority = MMR_CAN_MESSAGE_PRIORITY_NORMAL,
+ *       .messageId = MMR_CAN_EXAMPLES_POINT,
+ *       .senderId = 0xXXX,
+ *     },
+ *     .data = (uint8_t*)&point,
+ *     .length = sizeof(point),
+ *   };
+ *
+ *   return MMR_CAN_Send(&hcan, packet);
+ * }
+ *
+ * int main() {
+ *   Point p = {10, 20};
+ *   if (send(p) != HAL_OK) {
+ *     Error_Handler();
+ *   }
+ *
+ *   // 'p' has been sent.
+ * }
+ */
 typedef struct {
  MmrCanHeader header;
-  CanMailbox *mailbox;
  uint8_t *data;
  uint8_t length;
 } MmrCanPacket;
@@ -75,7 +122,37 @@ typedef struct {

 /**
 * @brief
- * Represents a CAN message
+ * A message received over a CAN network.
+ *
+ * @example
+ * typedef struct {
+ *   int x;
+ *   int y;
+ * } Point;
+ *
+ * HalStatus receive(Point *result) {
+ *   MmrCanMessage message = {
+ *     .store = result,
+ *   };
+ *
+ *   HalStatus result = MMR_CAN_Receive(&hcan, &message);
+ *   bool isAPoint = message.header.messageId == MMR_CAN_EXAMPLES_POINT;
+ *   if (!isAPoint) {
+ *     return HAL_ERROR;
+ *   }
+ *
+ *   return result;
+ * }
+ *
+ * int main() {
+ *   Point p = {};
+ *   if (receive(&p) != HAL_OK) {
+ *     Error_Handler();
+ *   }
+ *
+ *   // here 'p' has been populated and can
+ *   // be used.
+ * }
 */
 typedef struct {
  MmrCanHeader header;
@@ -87,12 +164,76 @@ 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;
+
+
+/**
+ * @brief
+ * Sets the tick provider.
+ * 
+ * @param tickProvider
+ *  The function to use when fetching the current tick.
+ */
+void MMR_CAN_SetTickProvider(MmrCanTickProvider tickProvider);
+
+/**
+ * @brief
+ * Returns the current tick by calling the
+ * configured tick provider.
+ */
+uint32_t MMR_CAN_GetCurrentTick();
+
+/**
+ * @brief
+ * Configures the filters with the default configuration
+ * and starts the can interface.
+ */
 HalStatus MMR_CAN_BasicSetupAndStart(CanHandle *hcan);
+
+/**
+ * @brief
+ * Configures the filters.
+ */
 HalStatus MMR_CAN_FilterConfig(CanHandle *hcan, MmrCanFilterSettings settings);
-CanFilterMask MMR_CAN_AlignStandardMask(CanFilterMask baseMask);
+
+/**
+ * @brief
+ * Provides the default configuration for
+ * the filters. 
+ */
 MmrCanFilterSettings MMR_CAN_GetDefaultFilterSettings();

+/**
+ * @brief
+ * Sends a can packet over the network.
+ * Based on the data length, the packet may be split
+ * into multiple frames.
+ * 
+ * It is not recommended to send more than 8 bytes, as the
+ * 'multiple frames' feature has not been fully implemented yet.
+ */
 HalStatus MMR_CAN_Send(CanHandle *hcan, MmrCanPacket packet);
+
+/**
+ * @brief
+ * Sends a can packet over the network as is, without
+ * changing the data that is provided.
+ * 
+ * This can prevent the sudden change of the header's message type when
+ * using MMR_CAN_Send.
+ */
+HalStatus MMR_CAN_SendNoTamper(CanHandle *hcan, MmrCanPacket packet);
+
+/**
+ * @brief
+ * Receives a can message from the network.
+ */
 HalStatus MMR_CAN_Receive(CanHandle *hcan, MmrCanMessage *result);

 #endif /* INC_MMR_CAN_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_

@@ -14,6 +25,14 @@ typedef struct {
 #define MMR_CAN_CreateEventList(handlers) \
  (const MmrCanEventList) { handlers, sizeofarray(handlers) }

+
+/**
+ * @brief
+ * Activates the CAN rx interrupts
+ *
+ * When one is fired, the callbacks provided inside the
+ * MmrCanEventList will be invoked
+ */
 HalStatus MMR_CAN_InitRxHandlers(CanHandle *hcan, const MmrCanEventList *rxEvents);


@@ -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_

@@ -12,17 +22,17 @@
 * portion of the CAN bus message (that is, the lower 5 bits
 * of the standard id)
 * 
- * They are used to check if a message is either standalone
- * or split into multiple frames
+ * They are used to check if a message is either standalone, an
+ * acknowledgement or split into multiple frames
 * 
- * When the priority and id fields are the same, multi-frame
- * messages have a higher priority over normal ones
+ * Constants with lower values have an higher priority.
 */
 typedef enum {
-  MMR_CAN_MESSAGE_ACK = B_(0001),
+  MMR_CAN_MESSAGE_TYPE_SCS = B_(0000),
+  MMR_CAN_MESSAGE_TYPE_ACK = B_(0001),
  MMR_CAN_MESSAGE_TYPE_MULTI_FRAME = B_(0010),
  MMR_CAN_MESSAGE_TYPE_MULTI_FRAME_END = B_(0011),
-  MMR_CAN_MESSAGE_TYPE_NORMAL = B_(1000),
+  MMR_CAN_MESSAGE_TYPE_NORMAL = B_(0100),
 } MmrCanMessageType;


@@ -40,16 +50,36 @@ typedef enum {
 */
 typedef struct {
  MmrCanMessagePriority priority : 3;
-  MmrCanMessageId messageId : 10;
-  uint32_t senderId : 12;
-  MmrCanMessageType messageType : 4;
+  uint16_t messageId : 10;
+  uint16_t senderId : 10;
+  uint8_t seqNumber : 3;
+  MmrCanMessageType messageType : 3;
 } MmrCanHeader;


-uint32_t *MMR_CAN_HeaderToBits(MmrCanHeader *header);
-MmrCanHeader *MMR_CAN_HeaderFromBits(uint32_t *bits);
+/**
+ * @brief
+ * 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
+ */
+uint32_t MMR_CAN_HeaderToBits(MmrCanHeader header);

-bool MMR_CAN_IsMultiFrame(MmrCanHeader *header);
-bool MMR_CAN_IsMultiFrameEnd(MmrCanHeader *header);
+/**
+ * @brief
+ * Deserializes a 32bits integer to an MmrCanHeader.
+ * The 3 left-most bits must be of padding.
+ */
+MmrCanHeader MMR_CAN_HeaderFromBits(uint32_t bits);
+
+
+/**
+ * @brief
+ * Tells wether the given header represents an SCS.
+ */
+bool MMR_CAN_IsHeaderScs(MmrCanHeader header);
+bool MMR_CAN_IsMultiFrame(MmrCanHeader header);
+bool MMR_CAN_IsMultiFrameEnd(MmrCanHeader header);

 #endif /* INC_MMR_CAN_HEADER_H_ */
@@ -1,7 +1,17 @@
+/**
+ * @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_

-#include "main.h"
+#include "stm32f3xx_hal.h"

 #ifndef CAN
 #define CAN
@@ -1,6 +1,21 @@
+/**
+ * @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_

+#include <stdint.h>
 #include <stdbool.h>
 #include "mmr_can_binary_literals.h"

@@ -23,11 +38,28 @@ typedef enum {
 } MmrCanMessageIdType;


+/**
+ * @brief
+ * Returns the 3 bits representing
+ * the MmrCanMessageIdType.
+ */
 uint8_t MMR_CAN_GetMessageIdType(MmrCanMessageId msgId);
+
+/**
+ * @brief
+ * Returns the 7 bits representing
+ * the message id's subtype.
+ */
 uint8_t MMR_CAN_GetMessageIdSubtype(MmrCanMessageId msgId);

+/**
+ * @brief
+ * Tells wether the provided message
+ * is of the given id type.
+ *
+ * E.g. if a message is an SCS.
+ */
 bool MMR_CAN_IsMessageIdOfType(MmrCanMessageId msgId, MmrCanMessageIdType type);
-bool MMR_CAN_IsMessageIdSCS(MmrCanMessageId msgId);


 enum MmrCanMessageId {
@@ -49,7 +81,7 @@ enum MmrCanMessageId {
  MMR_CAN_MESSAGE_ID_SCS_AS_READY,
  MMR_CAN_MESSAGE_ID_SCS_AS_DRIVING,
  MMR_CAN_MESSAGE_ID_SCS_AS_OFF,
-  
+
  MMR_CAN_MESSAGE_ID_SCS_AM_MANUAL_DRIVING,
  MMR_CAN_MESSAGE_ID_SCS_AM_ACCELERATION,
  MMR_CAN_MESSAGE_ID_SCS_AM_SKIDPAD,
@@ -1,7 +1,23 @@
+/**
+ * @file mmr_can_optimize.h
+ * @brief
+ * Low level optimization utilities.
+ */
+
 #ifndef INC_MMR_CAN_OPTIMIZE_H_
 #define INC_MMR_CAN_OPTIMIZE_H_

 #ifdef __GNUC__
+/**
+ * @brief
+ * Tells the compiler that the given method
+ * must always be inlined.
+ *
+ * @example
+ * static always_inline int min(int a, int b) {
+ *   return a < b ? a : b;
+ * }
+ */
 #define always_inline inline __attribute__((always_inline))
 #else
 #define always_inline inline
@@ -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_ */
@@ -0,0 +1,155 @@
+/**
+ * @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_H_
+#define INC_MMR_CAN_SCS_H_
+
+#include "mmr_can.h"
+
+
+/**
+ * @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
+#endif
+
+
+/**
+ * @brief 
+ * Maximum timeout before first retransmission,
+ * in milliseconds 
+ */
+#ifndef MMR_CAN_MAX_TIMEOUT
+#define MMR_CAN_MAX_TIMEOUT 500
+#endif
+
+
+/**
+ * @brief
+ * It depends on how many bits the board devotes to the timer
+ * Check the datasheet
+ */
+typedef uint32_t TimerRange;
+
+
+/**
+ * @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.
+ * 
+ * @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 originalHeader The scs header to acknowledge.
+ */
+HalStatus MMR_CAN_SendAck(
+  CanHandle *hcan,
+  MmrCanHeader originalHeader
+);
+
+/**
+ * @brief
+ * Sends an Scs message.
+ * 
+ * @param scsId The MMR_CAN_MESSAGE_ID_SCS_xx id.
+ * @param senderId The id of this board.
+ */
+HalStatus MMR_CAN_SendScs(
+  CanHandle *hcan,
+  MmrCanMessageId scsId,
+  CanId senderId
+);
+
+
+MmrCanScsEntry* MMR_CAN_GetNextScsEntry();
+MmrCanScsEntry* MMR_CAN_PutScsEntry(MmrCanHeader header);
+MmrCanScsEntry* MMR_CAN_ClearScsEntry(MmrCanHeader header);
+MmrCanScsEntry* MMR_CAN_FindScsEntry(MmrCanHeader header);
+
+#endif // !INC_MMR_CAN_SCS_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_

@@ -8,6 +14,7 @@ typedef uint32_t CanId;
 typedef uint32_t CanMailbox;

 /**
+ * @brief
 * A filter mask for the CANbus.
 * It acts like a subnet mask, filtering the ids that
 * do not match it.
@@ -20,12 +27,14 @@ typedef uint32_t CanMailbox;
 typedef uint32_t CanFilterMask;

 /**
+ * @brief
 * Stores a value from CAN_filter_FIFO
 * That is, CAN_FILTER_FIFOx
 */
 typedef uint8_t CanFilterFifo;

-/** 
+/**
+ * @brief
 * Represents a filter bank.
 * The values must be in the range [0, 27]
 */
@@ -1,19 +1,61 @@
+/**
+ * @file mmr_can_util.h
+ * @brief
+ * Utility functions and macros.
+ */
+
 #ifndef INC_MMR_CAN_UTIL_H_
 #define INC_MMR_CAN_UTIL_H_

 #include <stdint.h>
 #include <string.h>

+/**
+ * @brief
+ * Returns the size of the given array.
+ *
+ * This only works on static arrays declared
+ * within the current scope, that is:
+ * int main() {
+ *   int arr[] = {1, 2, 3};
+ *   int len = sizeofarray(arr);
+ * }
+ */
 #define sizeofarray(array) \
  (sizeof(array) / sizeof(*(array)))

+/**
+ * @brief
+ * Returns the length of a statically, non const ptr, declared
+ * string.
+ * That is:
+ * int main() {
+ *   char str[] = "abc";
+ *   int len = stringArrayLength(str);
+ * }
+ */
 #define stringArrayLength(array) \
  stringBufferLength((array), sizeofarray(array))

+/**
+ * @brief
+ * Returns the length of a string buffer.
+ * Its format must be in bytes, so it could be:
+ *   const char*
+ *   char*
+ *   uint8_t*
+ *   etc...
+ */
 #define stringBufferLength(pbuffer, maxLen) \
  strnlen((const char*)(pbuffer), maxLen)

-#define min(a, b) ((a) < (b) ? a : b);
+/**
+ * @brief
+ * Returns the minimum between the
+ * two given values.
+ * E.g. min(1, 2) == 1 // true
+ */
+#define min(a, b) ((a) < (b) ? a : b)
 #define mask(value, bits) (value & bits)
 #define convertTo(resultType, lvalue) (*interpretAs(resultType*, &(lvalue)))
 #define interpretAs(resultType, lvalue) ((resultType)(lvalue))
@@ -26,10 +68,10 @@
 * Either
 *  - Error: the computation resulted in error
 *  - Pending: the computation is still undergoing
- *  - Completed: the computation has completed succesfully
+ *  - Completed: the computation has completed successfully
 *               and its results can be read
 *
- * Asynchronous logig can be easily implemented using State Machines
+ * Asynchronous logic can be easily implemented using State Machines
 */
 typedef enum {
  MMR_ASYNC_RESULT_ERROR,