From f5c8353245756e717ba1b86ced4ee56dc57be374 Mon Sep 17 00:00:00 2001 From: Stefano Calabretti Date: Wed, 23 Feb 2022 13:21:34 +0100 Subject: [PATCH] Add documentation --- Inc/mmr_can.h | 19 ++++++++ Inc/mmr_can_events.h | 11 +++++ Inc/mmr_can_header.h | 16 +++++-- Inc/mmr_can_includes.h | 10 +++++ Inc/mmr_can_message_id.h | 14 ++++++ Inc/mmr_can_optimize.h | 6 +++ Inc/mmr_can_queue.h | 14 ------ Inc/mmr_can_scs_manager.h | 95 +++++++++++++++++++++++++++++++++++++-- Inc/mmr_can_types.h | 6 +++ Inc/mmr_can_util.h | 6 +++ Src/mmr_can_send.c | 26 +++++------ 11 files changed, 189 insertions(+), 34 deletions(-) delete mode 100644 Inc/mmr_can_queue.h diff --git a/Inc/mmr_can.h b/Inc/mmr_can.h index d248046..b68e16c 100644 --- a/Inc/mmr_can.h +++ b/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); diff --git a/Inc/mmr_can_events.h b/Inc/mmr_can_events.h index b8dba1f..be7cd88 100644 --- a/Inc/mmr_can_events.h +++ b/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_ diff --git a/Inc/mmr_can_header.h b/Inc/mmr_can_header.h index 134e825..f7a1743 100644 --- a/Inc/mmr_can_header.h +++ b/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); diff --git a/Inc/mmr_can_includes.h b/Inc/mmr_can_includes.h index b299c3e..233f6bc 100644 --- a/Inc/mmr_can_includes.h +++ b/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_ diff --git a/Inc/mmr_can_message_id.h b/Inc/mmr_can_message_id.h index 0f332f1..26844f9 100644 --- a/Inc/mmr_can_message_id.h +++ b/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_ diff --git a/Inc/mmr_can_optimize.h b/Inc/mmr_can_optimize.h index 341b77c..10c5841 100644 --- a/Inc/mmr_can_optimize.h +++ b/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_ diff --git a/Inc/mmr_can_queue.h b/Inc/mmr_can_queue.h deleted file mode 100644 index 11f3b0a..0000000 --- a/Inc/mmr_can_queue.h +++ /dev/null @@ -1,14 +0,0 @@ -#ifndef INC_MMR_CAN_QUEUE_H_ -#define INC_MMR_CAN_QUEUE_H_ - -#include -#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_ */ diff --git a/Inc/mmr_can_scs_manager.h b/Inc/mmr_can_scs_manager.h index ee77d17..e72f2e9 100644 --- a/Inc/mmr_can_scs_manager.h +++ b/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, diff --git a/Inc/mmr_can_types.h b/Inc/mmr_can_types.h index 3b7f115..657e379 100644 --- a/Inc/mmr_can_types.h +++ b/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_ diff --git a/Inc/mmr_can_util.h b/Inc/mmr_can_util.h index 723dfa3..ef043da 100644 --- a/Inc/mmr_can_util.h +++ b/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_ diff --git a/Src/mmr_can_send.c b/Src/mmr_can_send.c index 5d00e7d..f92599d 100644 --- a/Src/mmr_can_send.c +++ b/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); }