Comment L4 PHAL

common/phal_L4/adc/adc.h

@@ -1,7 +1,7 @@
 /**
  * @file adc.h
  * @author Luke Oxley ([email protected])
- * @brief 
+ * @brief ADC HAL for STM32L4 MCU
  * @version 0.1
  * @date 2021-12-27
  */
@@ -13,7 +13,7 @@
 #include <stdbool.h>
 
 #define PHAL_ADC_INIT_TIMEOUT 1000000
-#define PHAL_ADC_CR_BITS_RS 0b10000000000000000000000000111111
+#define PHAL_ADC_CR_BITS_RS 0x8000003F
 
 typedef enum {
     ADC_RES_12_BIT = 0b00,
@@ -38,29 +38,36 @@ typedef enum {
 } ADCClkPrescaler_t;
 
 typedef enum {
-    ADC_DMA_OFF      = 0b00,
-    ADC_DMA_ONE_SHOT = 0b01,
-    ADC_DMA_CIRCULAR = 0b11
+    ADC_DMA_OFF      = 0b00,    //!< ADC performs no conversion
+    ADC_DMA_ONE_SHOT = 0b01,    //!< ADC performs single conversion
+    ADC_DMA_CIRCULAR = 0b11     //!< ADC conitinuously converts
 } ADCDMAMode_t;
 
+/** Data bit alignment within the conversion */
 typedef enum {
     ADC_DATA_ALIGN_RIGHT = 0b0,
     ADC_DATA_ALIGN_LEFT = 0b1
 } ADCDataAlign_t;
 
+/** Top-level ADC configuration */
 typedef struct {
-    ADCClkPrescaler_t clock_prescaler; // required to have high enough prescaler to operate within ADC maximum freq
-    ADCResolution_t resolution; // bit resolution of readings
-    ADCDataAlign_t data_align;
+    ADCClkPrescaler_t clock_prescaler; //!< required to have high enough prescaler to operate within ADC maximum freq
+    ADCResolution_t resolution;        //!< Bit resolution of readings
+    ADCDataAlign_t data_align;         //!< Data bit alignment within the conversion
     //uint32_t ext_trig_conv;
     //uint32_t ext_trig_conv_edge;
-    bool cont_conv_mode;
+    bool cont_conv_mode;               //!< ADC restarts conversions once complete
     //bool discont_conv_mode;
-    bool overrun; // set true if data register can be overwritten before being read
+    bool overrun;                      //!< Set true if data register can be overwritten before being read
     //uint32_t nbr_of_disc_conv;
-    ADCDMAMode_t dma_mode;
+    ADCDMAMode_t dma_mode;             //!< ADC DMA mode
 } ADCInitConfig_t;
 
+/** 
+ * Duration of the sample in ADC clock cycles.
+ * A longer conversion time allows the internal
+ * measurement capacitor to fully charge.
+*/
 typedef enum {
     ADC_CHN_SMP_CYCLES_2_5   = 0b000,
     ADC_CHN_SMP_CYCLES_6_5   = 0b001,
@@ -72,10 +79,11 @@ typedef enum {
     ADC_CHN_SMP_CYCLES_640_5 = 0b111,
 } ADCChannelSampleCycles_t;
 
+/** ADC configuration for one channel */
 typedef struct {
-    uint32_t channel; // not the GPIO channel, use the ADC channel (ie. PA0 = channel 5)
-    uint32_t rank; // order at which the channels will be polled, starting at 1
-    ADCChannelSampleCycles_t sampling_time; // 2_5 works, set higher for large imedances
+    uint32_t channel;                       //!< not the GPIO channel, use the ADC channel (ie. PA0 = channel 5)
+    uint32_t rank;                          //!< order at which the channels will be polled, starting at 1
+    ADCChannelSampleCycles_t sampling_time; //!< Set higher for large impedances
     //uint32_t single_diff;
     //uint32_t offset_num;
     //uint32_t offset;

common/phal_L4/can/can.c

@@ -1,5 +1,5 @@
 /**
- * @file hal_can_f4.c
+ * @file can.c
  * @author Adam Busch ([email protected])
  * @brief Basic CAN Peripheral HAL library for setting up CAN peripheral and sending messages
  * @version 0.1

common/phal_L4/can/can.h

@@ -16,35 +16,42 @@
 
 #include <stdbool.h>
 
-#define PHAL_CAN_TX_TIMEOUT   (5000U)
-#define PHAL_CAN_INIT_TIMEOUT (5000U)
+#define PHAL_CAN_TX_TIMEOUT   (5000U) //!< in milliseconds
+#define PHAL_CAN_INIT_TIMEOUT (5000U) //!< in milliseconds
 
-// Bit timing recovered from http://www.bittiming.can-wiki.info/
+/** Bit timing recovered from http://www.bittiming.can-wiki.info/ */
 #define PHAL_CAN_16MHz_500k (0x001c0001)
 #define PHAL_CAN_20MHz_500k (0x00050004)
 #define PHAL_CAN_40MHz_500k (0x001c0004)
 #define PHAL_CAN_80MHz_500k (0x001c0009)
 
 typedef struct
 {
-  CAN_TypeDef* Bus; /*!< Specifies the bus. */
-  uint16_t StdId; /*!< Specifies the standard identifier. */
-  uint32_t ExtId; /*!< Specifies the extended identifier. */
-  uint32_t IDE; /*!< Specifies the type of identifier for the message that will be transmitted.  */
-  uint32_t DLC; /*!< Specifies the length of the frame that will be transmitted. */
-  uint8_t Data[8]; /*!< Contains the data to be transmitted. */
+  CAN_TypeDef* Bus; //!< Specifies the bus.
+  uint16_t StdId;   //!< Specifies the standard identifier.
+  uint32_t ExtId;   //!< Specifies the extended identifier.
+  uint32_t IDE;     //!< Specifies the type of identifier for the message that will be transmitted.
+  uint32_t DLC;     //!< Specifies the length of the frame that will be transmitted.
+  uint8_t Data[8];  //!< Contains the data to be transmitted. */
 } CanMsgTypeDef_t;
 
 /**
  * @brief Initilize CAN peripheral to 500k. 
  * 
+ * @param bus The CAN peripheral to initialize (i.e. CAN1)
  * @param test_mode Initilize CAN peripheral for self test mode
  * 
  * @return true Peripheral sucessfully initalized
  * @return false Peripheral stalled during initilization
  */
 bool PHAL_initCAN(CAN_TypeDef* bus, bool test_mode);
 
+/**
+ * @brief De-initialize the CAN peripheral
+ * 
+ * @param bus The CAN peripheral to de-initialize (i.e. CAN1)
+ * @return Perihperal succesfully de-initialized
+ */
 bool PHAL_deinitCAN(CAN_TypeDef* bus);
 
 /**

common/phal_L4/dma/dma.h

@@ -1,3 +1,13 @@
+/**
+ * @file dma.h
+ * @author Dawson Moore ([email protected])
+ * @brief Basic DMA Peripheral HAL library for setting up DMA transfers
+ * @version 0.1
+ * @date 2022-01-10
+ * 
+ * @copyright Copyright (c) 2021
+ * 
+ */
 #ifndef _DMA_H_
 #define _DMA_H_
 
@@ -11,30 +21,31 @@
 
 #include <stdbool.h>
 
+/** Top-level DMA configuration */
 typedef struct {
-    uint32_t    periph_addr;
-    uint32_t    mem_addr;
-    uint16_t    tx_size;
+    uint32_t    periph_addr; //!< Address of the peripheral location (or other memory location in mem-to-mem) to transfer from/to
+    uint32_t    mem_addr;    //!< Address of the memory location to transfer from/to
+    uint16_t    tx_size;     //!< Number of transfers to complete in sizes set by mem / periph size
 
     bool        increment;
-    bool        circular;
-    uint8_t     dir;
-    bool        mem_inc;
-    bool        periph_inc;
-    bool        mem_to_mem;
-    uint8_t     priority;
-    uint8_t     mem_size;
-    uint8_t     periph_size;
-    bool        tx_isr_en;
-    uint8_t     dma_chan_request; /* Table 44 of Family Reference  */
-    uint8_t     channel_idx;
+    bool        circular;    //!< Continuously transfer
+    uint8_t     dir;         //!< If set to 0, transfers from periph_addr to mem_addr. If 1, opposite direction.
+    bool        mem_inc;     //!< Increment mem_addr after each transfer
+    bool        periph_inc;  //!< Increment periph_addr after each transfer
+    bool        mem_to_mem;  //!< If both locations are memory locations
+    uint8_t     priority;    //!< Transfer priority
+    uint8_t     mem_size;    //!< Size to read from mem_addr    (00 = 8 bits, 01 = 16 bits, 10 = 32 bits)
+    uint8_t     periph_size; //!< Size to read form periph_addr (00 = 8 bits, 01 = 16 bits, 10 = 32 bits)
+    bool        tx_isr_en;   //!< Enable the TX ISR
+    uint8_t     dma_chan_request; //!< Table 44 of Family Reference  */
+    uint8_t     channel_idx; //!< DMA Channel (Table 44 of Family Reference)
 
     DMA_TypeDef* periph;
     DMA_Channel_TypeDef* channel;
     DMA_Request_TypeDef* request;
 } dma_init_t;
 
-/*
+/**
  * @brief Initialize DMA peripheral to set m2m, p2p, or p2m with set size
  *        and length of txfer
  * 
@@ -44,35 +55,35 @@ typedef struct {
  */
 bool PHAL_initDMA(dma_init_t* init);
 
-/*
+/**
  * @brief Start txfer after sucessful DMA peripheral initialization
  * 
  * @param init -> Address of initialization structure
  */
 void PHAL_startTxfer(dma_init_t* init);
 
-/*
+/**
  * @brief Stop txfer
  * 
  * @param init -> Address of initialization structure
  */
 void PHAL_stopTxfer(dma_init_t* init);
 
-/*
+/**
  * @brief Re-enable DMA txfer after error ISR fires
  * 
  * @param init -> Address of initialization structure
  */
 void PHAL_reEnable(dma_init_t* init);
 
-/*
+/**
  * @brief Set memory address for DMA transfer. In Mem to Mem this acts as the source address
  * 
  * @param init -> Address of initialization structure
  */
 void PHAL_DMA_setMemAddress(dma_init_t* init, const uint32_t address);
 
-/*
+/**
  * @brief Set transfer length for DMA transaction
  * 
  * @param init -> Address of initialization structure