doc for all units

units/usart/_internal.h

@@ -1,6 +1,9 @@
 //
 // Created by MightyPork on 2018/01/14.
 //
+// Internal defines and consts used by the USART unit.
+// Can be included only by the USART c files.
+//
 
 #ifndef GEX_F072_UUSART_INTERNAL_H
 #define GEX_F072_UUSART_INTERNAL_H
@@ -31,51 +34,60 @@ struct priv {
     bool lsb_first;     //!< bit order
     uint8_t width;      //!< word width - 7, 8, 9 (this includes parity)
 
-    bool data_inv;  //!< Invert data bytes
-    bool rx_inv;    //!< Invert the RX pin levels
-    bool tx_inv;    //!< Invert the TX pin levels
+    bool data_inv;      //!< Invert data bytes
+    bool rx_inv;        //!< Invert the RX pin levels
+    bool tx_inv;        //!< Invert the TX pin levels
 
-    bool de_output; //!< Generate the Driver Enable signal for RS485
+    bool de_output;   //!< Generate the Driver Enable signal for RS485
     bool de_polarity; //!< DE active level
-    uint8_t de_assert_time;   //!< Time to assert the DE signal before transmit
-    uint8_t de_clear_time; //!< Time to clear the DE signal after transmit
+    uint8_t de_assert_time; //!< Time to assert the DE signal before transmit
+    uint8_t de_clear_time;  //!< Time to clear the DE signal after transmit
 
-    USART_TypeDef *periph;
+    USART_TypeDef *periph; //!<  USART peripheral
 
-    DMA_TypeDef *dma;
-    DMA_Channel_TypeDef *dma_rx;
-    DMA_Channel_TypeDef *dma_tx;
-    uint8_t dma_rx_chnum;
-    uint8_t dma_tx_chnum;
+    DMA_TypeDef *dma;      //!< DMA peripheral
+    uint8_t dma_rx_chnum; //!< DMA rx channel number (resolved dynamically based on availability)
+    uint8_t dma_tx_chnum; //!< DMA tx channel number (resolved dynamically based on availability)
+    DMA_Channel_TypeDef *dma_rx; //!< DMA rx channel instance
+    DMA_Channel_TypeDef *dma_tx; //!< DMA tx channel instance
 
     // DMA stuff
-    volatile uint8_t *rx_buffer;
-    volatile uint16_t rx_buf_readpos;
+    volatile uint8_t *rx_buffer;      //!< Receive buffer (malloc'd). Has configured TC and TH interrupts.
+    volatile uint16_t rx_buf_readpos; //!< Start of the next read (sending to USB)
+    volatile uint16_t rx_last_dmapos; //!< Last position of the DMA cyclic write. Used to detect timeouts and for partial data capture from the buffer
 
-    volatile uint8_t *tx_buffer;
-    volatile uint16_t tx_buf_nr;
-    volatile uint16_t tx_buf_nw;
-    volatile uint16_t tx_buf_chunk;
-    volatile bool tx_dma_busy;
+    volatile uint8_t *tx_buffer;    //!< Transmit buffer (malloc'd)
+    volatile uint16_t tx_buf_nr;    //!< Next Read index
+    volatile uint16_t tx_buf_nw;    //!< Next Write index
+    volatile uint16_t tx_buf_chunk; //!< Size of the currently being transmitted chunk (for advancing the pointers)
+    volatile bool tx_dma_busy;      //!< Flag that the Tx DMA request is ongoing
 
-    volatile uint16_t rx_last_dmapos;
 };
 
 /** Allocate data structure and set defaults */
 error_t UUSART_preInit(Unit *unit);
+
 // ------------------------------------------------------------------------
+
 /** Load from a binary buffer stored in Flash */
 void UUSART_loadBinary(Unit *unit, PayloadParser *pp);
+
 /** Write to a binary buffer for storing in Flash */
 void UUSART_writeBinary(Unit *unit, PayloadBuilder *pb);
+
 // ------------------------------------------------------------------------
+
 /** Parse a key-value pair from the INI file */
 error_t UUSART_loadIni(Unit *unit, const char *key, const char *value);
+
 /** Generate INI file section for the unit */
 void UUSART_writeIni(Unit *unit, IniWriter *iw);
+
 // ------------------------------------------------------------------------
+
 /** Tear down the unit */
 void UUSART_deInit(Unit *unit);
+
 /** Finalize unit set-up */
 error_t UUSART_init(Unit *unit);
 
@@ -97,13 +109,6 @@ void UUSART_DMA_HandleRxFromIRQ(Unit *unit, uint16_t endpos);
  */
 uint16_t UUSART_DMA_TxQueue(struct priv *priv, const uint8_t *buffer, uint16_t len);
 
-/**
- * Handle rx timeout, grab what is received and send it immediately.
- *
- * @param unit
- */
-void UUSART_DMA_HandleRxTimeout(Unit *unit);
-
 // ------------------------------------------------------------------------
 
 

units/usart/unit_usart.c

@@ -19,14 +19,6 @@ static void UUSART_SendReceivedDataToMaster(Job *job)
     uint32_t readpos = job->d32;
     uint32_t count = job->len;
 
-    // Debug: print to debug port
-//    PUTS("Job rx >");
-//    PUTSN((char *) priv->rx_buffer + readpos, (uint16_t) count);
-//    PUTS("<\r\n");
-
-    // Debug: Write out
-//    UU_USART_Write(unit, (const uint8_t *) (priv->rx_buffer + readpos), count);
-
     // TODO modify TF to allow writing in multiple chunks to avoid this useless buffer copying
     PayloadBuilder pb = pb_start(unit_tmp512, UNIT_TMP_LEN, NULL);
     pb_u8(&pb, unit->callsign);
@@ -68,6 +60,9 @@ void UUSART_DMA_HandleRxFromIRQ(Unit *unit, uint16_t endpos)
     priv->rx_buf_readpos = endpos;
 }
 
+/**
+ * Timed tick (ISR) - check timeout
+ */
 void UUSART_Tick(Unit *unit)
 {
     assert_param(unit);

units/usart/unit_usart.h

@@ -1,6 +1,11 @@
 //
 // Created by MightyPork on 2018/01/02.
 //
+// USART driver using DMA buffers.
+// Provides a wide range of config options and supports driving a RS485 driver.
+//
+// The implementation is complex and split to multiple files for easier maintenance
+//
 
 #ifndef GEX_F072_UNIT_USART_H
 #define GEX_F072_UNIT_USART_H