docs: documentation for interval routines

CloudyPadmal · CloudyPadmal · commit 588ac8182bed · 2021-11-13T22:17:33.000+01:00
diff --git a/pslab-core.X/helpers/buffer.c b/pslab-core.X/helpers/buffer.c
@@ -26,7 +26,7 @@ response_t BUFFER_FetchInt(void) {
     LED_SetLow();
     uint16_t i;
     for (i = 0; i < counter; i++) {
-        UART1_WriteInt(BUFFER[i + 2 * channel * (BUFFER_SIZE / 4)]);
+        UART1_WriteInt(BUFFER[i + channel * (BUFFER_SIZE / 4)]);
     }
     LED_SetHigh();
     
diff --git a/pslab-core.X/helpers/buffer.h b/pslab-core.X/helpers/buffer.h
@@ -12,8 +12,7 @@ extern "C" {
     extern int16_t volatile __attribute__((section(".adc_buffer"), far)) BUFFER[BUFFER_SIZE];
     
     /**
-    * @brief
-    * Send buffer contents.
+    * @brief Send buffer contents.
     * 
     * @description
     * This command function takes two arguments over serial:
@@ -26,8 +25,34 @@ extern "C" {
     */
     response_t BUFFER_Retrieve(void);
     
+    /**
+    * @brief Send buffer content as integers.
+    * 
+    * @description
+    * This command function takes two arguments over serial:
+    * 1. The starting index in the buffer from which to send values.
+    * 2. The number of values to be sent.
+    *
+    * It returns the requested data over serial.
+    * It sends an acknowledge byte (SUCCESS)
+    * 
+    * @return SUCCESS
+    */
     response_t BUFFER_FetchInt(void);
     
+    /**
+    * @brief Send buffer content as longs.
+    * 
+    * @description
+    * This command function takes two arguments over serial:
+    * 1. The starting index in the buffer from which to send values.
+    * 2. The number of values to be sent.
+    *
+    * It returns the requested data over serial.
+    * It sends an acknowledge byte (SUCCESS)
+    * 
+    * @return SUCCESS
+    */
     response_t BUFFER_FetchLong(void);
 
 #ifdef	__cplusplus
diff --git a/pslab-core.X/helpers/interval.c b/pslab-core.X/helpers/interval.c
@@ -1,15 +1,15 @@
 #include "../bus/uart/uart1.h"
+#include "../registers/comparators/cmp4.h"
+#include "../registers/comparators/cvr.h"
 #include "../registers/comparators/ic1.h"
 #include "../registers/comparators/ic2.h"
 #include "../registers/comparators/ic3.h"
 #include "../registers/comparators/ic4.h"
 #include "../registers/comparators/ic_params.h"
 #include "../registers/memory/dma.h"
+#include "../registers/system/interrupt_manager.h"
 #include "../registers/system/pin_manager.h"
 #include "../registers/timers/tmr2.h"
-#include "../registers/comparators/cvr.h"
-#include "../registers/comparators/cmp4.h"
-#include "../registers/system/interrupt_manager.h"
 #include "buffer.h"
 
 static uint8_t DIGITAL_STATES = 0;
@@ -77,10 +77,7 @@ void INTERVAL_CaptureOne(uint16_t count, uint8_t channel, uint8_t mode, uint8_t
 
 void INTERVAL_CaptureTwo(uint16_t count, uint8_t mode, uint8_t channel) {
 
-    DMA_ChannelDisable(DMA_CHANNEL_0);
-    DMA_ChannelDisable(DMA_CHANNEL_1);
-    DMA_ChannelDisable(DMA_CHANNEL_2);
-    DMA_ChannelDisable(DMA_CHANNEL_3);
+    DMA_DisableAllChannels();
     
     DMA_PrepareChannel0(count, __builtin_dmapage(&BUFFER), 
             __builtin_dmaoffset(&BUFFER), DMA_PERIPHERAL_IRQ_IC1);
@@ -93,10 +90,7 @@ void INTERVAL_CaptureTwo(uint16_t count, uint8_t mode, uint8_t channel) {
     
     DMA_InterruptEnable(DMA_CHANNEL_0);
 
-    IC1_Initialize();
-    IC2_Initialize();
-    IC3_Initialize();
-    IC4_Initialize();
+    IC_PARAMS_InitiateAll();
 
     SetDMA_MODE(DMA_MODES_TWO_CHANNEL);
 
@@ -107,10 +101,7 @@ void INTERVAL_CaptureTwo(uint16_t count, uint8_t mode, uint8_t channel) {
     IC_PARAMS_CombineOddEvenModules();
     IC_PARAMS_UseSourceTo(IC_PARAMS_SOURCE_TASK_TRIGGER);
 
-    DMA_ChannelEnable(DMA_CHANNEL_0);
-    DMA_ChannelEnable(DMA_CHANNEL_1);
-    DMA_ChannelEnable(DMA_CHANNEL_2);
-    DMA_ChannelEnable(DMA_CHANNEL_3);
+    DMA_EnableAllChannels();
 
     IC1_SetCaptureMode(mode & 0xF);
     IC2_SetCaptureMode(mode & 0xF);
@@ -133,10 +124,7 @@ void INTERVAL_CaptureThree(uint16_t count, uint16_t mode, uint8_t trig) {
     
     DMA_InterruptEnable(DMA_CHANNEL_0);
 
-    IC1_Initialize();
-    IC2_Initialize();
-    IC3_Initialize();
-    IC4_Initialize();
+    IC_PARAMS_InitiateAll();
     
     SetDMA_MODE(DMA_MODES_THREE_CHANNEL);
     
@@ -173,10 +161,7 @@ void INTERVAL_CaptureThree(uint16_t count, uint16_t mode, uint8_t trig) {
 
 void INTERVAL_CaptureFour(uint16_t count, uint16_t mode, uint8_t prescaler) {
     
-    DMA_ChannelDisable(DMA_CHANNEL_0);
-    DMA_ChannelDisable(DMA_CHANNEL_1);
-    DMA_ChannelDisable(DMA_CHANNEL_2);
-    DMA_ChannelDisable(DMA_CHANNEL_3);
+    DMA_DisableAllChannels();
     
     DMA_PrepareChannel0(count, __builtin_dmapage(&BUFFER), 
             __builtin_dmaoffset(&BUFFER), DMA_PERIPHERAL_IRQ_IC1);
@@ -189,10 +174,7 @@ void INTERVAL_CaptureFour(uint16_t count, uint16_t mode, uint8_t prescaler) {
 
     DMA_InterruptEnable(DMA_CHANNEL_0);
 
-    IC1_Initialize();
-    IC2_Initialize();
-    IC3_Initialize();
-    IC4_Initialize();
+    IC_PARAMS_InitiateAll();
     
     SetDMA_MODE(DMA_MODES_FOUR_CHANNEL);
     
@@ -208,10 +190,7 @@ void INTERVAL_CaptureFour(uint16_t count, uint16_t mode, uint8_t prescaler) {
     IC_PARAMS_SetCaptureTimer(IC_PARAMS_CAPTURE_TIMER2);
     IC_PARAMS_UseSourceTo(IC_PARAMS_SOURCE_TASK_TRIGGER);
     
-    DMA_ChannelEnable(DMA_CHANNEL_0);
-    DMA_ChannelEnable(DMA_CHANNEL_1);
-    DMA_ChannelEnable(DMA_CHANNEL_2);
-    DMA_ChannelEnable(DMA_CHANNEL_3);
+    DMA_EnableAllChannels();
 
     IC1_SetCaptureMode(mode & 0xF);
     IC2_SetCaptureMode((mode >> 4) & 0xF);
@@ -220,6 +199,7 @@ void INTERVAL_CaptureFour(uint16_t count, uint16_t mode, uint8_t prescaler) {
 }
 
 response_t INTERVAL_GetState(void) {
+    
     UART1_WriteInt(__builtin_dmaoffset(&BUFFER));
     UART1_WriteInt(DMA0STAL);
     UART1_WriteInt(DMA1STAL);
diff --git a/pslab-core.X/helpers/interval.h b/pslab-core.X/helpers/interval.h
@@ -8,12 +8,83 @@
 extern "C" {
 #endif
     
+    /**
+     * @brief Setup input capture on one channel
+     * 
+     * @description
+     * This routing will configure IC1,2 and DMA0,1 modules to listen to logic
+     * level changes on a pin defined by the channel byte and log timer values
+     * in BUFFER 1st and 2nd quarters. If trigger is set by the trig byte, this
+     * will use IC4 module to listen to the trigger observation and time log will
+     * then start.
+     * It will combine both IC1 and IC2 modules to form a 32-bit timer which will
+     * have support for more data points than `CaptureThree` and `CaptureFour`
+     * routines.
+     * 
+     * @param count : number of data points to capture
+     * @param channel : the pin that needs to be monitored
+     * @param mode : logic level variation. Refer to `IC_PARAMS_CAPTURE_MODE`
+     * @param trig : en/disable trigger using IC4
+     *              | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+     *              |    TRIG PIN   | X | TRIG MODE |
+     * 
+     * @return None
+     */
     void INTERVAL_CaptureOne(uint16_t count, uint8_t channel, uint8_t mode, uint8_t trig);
 
+    /**
+     * @brief Setup input capture on two channels
+     * 
+     * @description
+     * This routing will configure IC1,2,3,4 and DMA0,1,2,3 modules to listen to 
+     * logic level changes on pins defined by the channel byte and log timer 
+     * values in BUFFER.
+     * It will combine both IC1, IC2 and IC3, IC4 modules to form a 32-bit timer 
+     * which will have support for more data points than `CaptureThree` and 
+     * `CaptureFour` routines.
+     * 
+     * @param count : number of data points to capture
+     * @param mode : logic level variation. Refer to `IC_PARAMS_CAPTURE_MODE`
+     * @param channel : the pin that needs to be monitored
+     * 
+     * @return None
+     */
     void INTERVAL_CaptureTwo(uint16_t count, uint8_t mode, uint8_t channel);
     
+    /**
+     * @brief Setup input capture on three channels
+     * 
+     * @description
+     * This routing will use IC1,2,3 modules with DMA0,1,2 channels to capture
+     * logic level variations in LA1, LA2 and LA3 pins. These pins are fixed.
+     * If trigger is set by the trig byte, this will use IC4 module to listen to
+     * the trigger observation and time log will then start.
+     * 
+     * @param count : number of data points to capture
+     * @param mode : logic level variation. Refer to `IC_PARAMS_CAPTURE_MODE`
+     * @param trig : en/disable trigger using IC4
+     *              | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+     *              |    TRIG PIN   | X | TRIG MODE |
+     * 
+     * @return None
+     */
     void INTERVAL_CaptureThree(uint16_t count, uint16_t mode, uint8_t trig);
     
+    /**
+     * @brief Setup input capture on four channels
+     * 
+     * @description
+     * This routing will use IC1,2,3,4 modules with DMA0,1,2,3 channels to capture
+     * logic level variations in LA1, LA2, LA3 and LA4 pins. These pins are fixed.
+     * Timer 2 will be used as the timer source unlike the other three capture
+     * methods that use peripheral clock as the timer source.
+     * 
+     * @param count : number of data points to capture
+     * @param mode : logic level variation. Refer to `IC_PARAMS_CAPTURE_MODE`
+     * @param prescaler : pre-scaler value for timer 2 module
+     * 
+     * @return None
+     */
     void INTERVAL_CaptureFour(uint16_t count, uint16_t mode, uint8_t prescaler);
     
     response_t INTERVAL_GetState(void);
diff --git a/pslab-core.X/registers/memory/dma.c b/pslab-core.X/registers/memory/dma.c
@@ -251,3 +251,17 @@ void DMA_PrepareChannel3(uint16_t count, uint16_t high_address, uint16_t low_add
     DMA_FlagInterruptClear(DMA_CHANNEL_3);
     DMA_InterruptDisable(DMA_CHANNEL_3);
 }
+
+void DMA_EnableAllChannels(void) {
+    DMA_ChannelEnable(DMA_CHANNEL_0);
+    DMA_ChannelEnable(DMA_CHANNEL_1);
+    DMA_ChannelEnable(DMA_CHANNEL_2);
+    DMA_ChannelEnable(DMA_CHANNEL_3);
+}
+
+void DMA_DisableAllChannels(void) {
+    DMA_ChannelDisable(DMA_CHANNEL_0);
+    DMA_ChannelDisable(DMA_CHANNEL_1);
+    DMA_ChannelDisable(DMA_CHANNEL_2);
+    DMA_ChannelDisable(DMA_CHANNEL_3);
+}
diff --git a/pslab-core.X/registers/memory/dma.h b/pslab-core.X/registers/memory/dma.h
@@ -967,6 +967,12 @@ extern "C" {
      */
     void DMA_PrepareChannel3(uint16_t count, uint16_t high_address, uint16_t low_address, 
                                             DMA_PERIPHERAL_IRQ_NUMBER trigger);
+    
+    // Enable all four channels in one go
+    void DMA_EnableAllChannels(void);
+    
+    // Disable all four channels in one go
+    void DMA_DisableAllChannels(void);
 
     // Getters and Setters
     void SetDMA_MODE(DMA_MODES mode);

Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ response_t BUFFER_FetchInt(void) {`
`26`	`26`	`LED_SetLow();`
`27`	`27`	`uint16_t i;`
`28`	`28`	`for (i = 0; i < counter; i++) {`
`29`		`- UART1_WriteInt(BUFFER[i + 2 * channel * (BUFFER_SIZE / 4)]);`
	`29`	`+ UART1_WriteInt(BUFFER[i + channel * (BUFFER_SIZE / 4)]);`
`30`	`30`	`}`
`31`	`31`	`LED_SetHigh();`
`32`	`32`