Added comments and made some changed to how the NSToSDRAMClockCycles Calculation worked

Author: DannyCato

include/core/io/SDRAM.hpp

@@ -47,34 +47,37 @@ class SDRAM {
         POWER_DOWN    = 6,
     };
 
+    /**
+     * All the states that the SDRAM can be held in.
+     * NORMAL_MODE means normal operation with nothing special happening
+     * SELF_REFRESH_MODE means that all data cells are refreshed automatically, but the MCU does not know when
+     * POWER_DOWN_MODE means the off state
+     */
     enum class SDRAMState {
         NORMAL_MODE = 0,
         SELF_REFRESH_MODE,
         POWER_DOWN_MODE
     };
 
-    enum class SDRAMBank {
-        BANK1 = 0,
-        BANK2 = 1
-    };
-
     /**
      * Holds all SDRAM controller settings that map directly to
      * the HAL_SDRAM_Init configuration structure.
      *
+     * Values should be looked for in stm32f4xx_ll_fmc.h with macro prefix FMC_SDRAM...
+     *
      * Must be initialized before passing into the constructor
      */
     struct SDRAMInitConfig {
-        uint32_t sdBank;
-        uint32_t columnBitsNumber;
-        uint32_t rowBitsNumber;
-        uint32_t memoryDataWidth;
-        uint32_t internalBankNumber;
-        uint32_t casLatency;
-        uint32_t writeProtection;
-        uint32_t sdClockPeriod;
-        uint32_t readBurst;
-        uint32_t readPipeDelay;
+        uint32_t sdBank; // Bank number for the controller (0 or 1 usually)
+        uint32_t columnBitsNumber; // number of Horizontal Addressing Cells
+        uint32_t rowBitsNumber; // number of Vertical Addressing Cells
+        uint32_t memoryDataWidth; // How large the data is: 8, 16, or 32 bit
+        uint32_t internalBankNumber; // How many layers of columns and rows there are. Usually 1, 2, or 4
+        uint32_t casLatency; // How many SDRAM CLK Cycles from data fetch received to data available from the output
+        uint32_t writeProtection; // If you want bank protection on at initialization
+        uint32_t sdClockPeriod; // How many MCU controller clock cycles per SDRAM CLK Cycle. Usually 1, 2, or 3
+        uint32_t readBurst; // How many bytes to expect per read request.
+        uint32_t readPipeDelay; // Number of SDRAM CLK Cycles until data is available from read. Usually 1
     };
 
     /**
@@ -83,13 +86,13 @@ class SDRAM {
      * Must be initialized before passing into the constructor
      */
     struct SDRAMTimingConfig {
-        uint32_t loadToActiveDelay;
-        uint32_t exitSelfRefreshDelay;
-        uint32_t selfRefreshTime;
-        uint32_t rowCycleDelay;
-        uint32_t writeRecoveryTime;
-        uint32_t rpDelay;
-        uint32_t rcdDelay;
+        uint32_t loadToActiveDelay; // Time to update the load/operation register to SDRAM being read for commands
+        uint32_t exitSelfRefreshDelay; // How long to exit the self-refresh mode
+        uint32_t selfRefreshTime; // SDRAM CLK Cycles a row will be unavailable for while refreshing
+        uint32_t rowCycleDelay; // Number of SDRAM CLK Cycles until a new active command can be submitted to a bank
+        uint32_t writeRecoveryTime; // SDRAM CLK Cycles from write until a precharge can be given
+        uint32_t readToPrechargeDelay; // SDRAM CLK Cycles from read until a precharge
+        uint32_t rcdDelay; // SDRAM CLK Cycles from an active to read/write
     };
 
     struct SDRAMPinGroup {
@@ -111,24 +114,25 @@ class SDRAM {
 
     /**
      * Gets the Frequency of the SDRAM CLK
-     *
+     * @param mcuClkPerSdramClk Number of microcontroller clock cycles for every SDRAM Clock Cycle
      * @return the SDRAM clock frequency
      */
-    static uint32_t getSdramClockFrequency();
+    static uint32_t getSdramClockFrequency(uint8_t mcuClkPerSdramClk);
 
     /**
-     * Get how long one SDRAM Clock cycle is in picoseconds
-     *
-     * @return the SDRAM clock period in picoseconds
+     * Get how long one SDRAM Clock cycle is in femtoseconds
+     * @param mcuClkPerSdramClk Number of microcontroller clock cycles for every SDRAM Clock Cycle
+     * @return the SDRAM clock period in femtoseconds
      */
-    static uint32_t getSdramClockPeriodPS();
+    static uint32_t getSdramClockPeriodFS(uint8_t mcuClkPerSdramClk);
 
     /**
      * Transform a time given in nanoseconds into how many clock cycles fit in that range
-     *
+     * @param nanoseconds Number of nanoseconds
+     * @param mcuClkPerSdramClk Number of microcontroller clock cycles for every SDRAM Clock Cycle
      * @return the SDRAM clock period in nanoseconds
      */
-    static uint32_t NSToSdramClockCycles(uint32_t nanoseconds);
+    static uint32_t NSToSdramClockCycles(uint32_t nanoseconds, uint8_t mcuClkPerSdramClk);
 
     /**
      * Enable write protection for the sdram
@@ -192,12 +196,32 @@ class SDRAM {
     }
 
 protected:
+    /**
+     * Starting address of the RAM
+     */
     uint32_t* memoryAddress;
+    /**
+     * All the pins used by the RAM
+     */
     SDRAMPinGroup& pins;
+    /**
+     * Base config of the SDRAM
+     */
     SDRAMInitConfig initConfig;
+    /**
+     * Timing Config for the SDRAM Controller
+     */
     SDRAMTimingConfig timingConfig;
+    /**
+     * Associated Device that holds all the commands necessary to start up the device
+     */
     const SDRAMDevice& device;
 
+    /**
+     * Helper function to turn a HAL Status in than SDRAM::Status
+     * @param hal_status
+     * @return status returned by the HAL
+     */
     static constexpr Status HALStatusToSDRAMStatus(uint32_t hal_status) {
         return static_cast<Status>(hal_status);
     }
@@ -215,6 +239,6 @@ class SDRAMDevice {
 
 } // namespace core::io
 
-#endif
-
 #endif // STM32F4xx
+
+#endif // EVT_SDRAM_HPP

include/core/io/platform/f4xx/SDRAMf4xx.hpp

@@ -119,9 +119,18 @@ class SDRAMf4xx : public SDRAM {
      */
     static void InitHardware(SDRAMPinGroup& pins);
 
+    /**
+     * Address of the SDRAM register in memory within the overarching FMC
+     */
     FMC_SDRAM_TypeDef* sdramDevice;
 
+    /**
+     * SDRAM Initialization Config, passed to HAL for Low-Level initialization
+     */
     SDRAM_HandleTypeDef sdram;
+    /**
+     * SDRAM Timing Initialization Config
+     */
     FMC_SDRAM_TimingTypeDef sdramTiming;
 };
 

include/core/manager.hpp

@@ -333,8 +333,9 @@ SPI& getSPI(GPIO* CSPins[], uint8_t pinLength) {
  * Get an instance of SDRAM
  *
  * @tparam pins the array of pins that will be used by the SDRAM Controller
- * @param sdramDevice actual register of data
- * @param
+ * @param initConfig SDRAM controller config used to determine clock speed, address, and more
+ * @param timingConfig SDRAM controller config used for hardware level timing for sending commands
+ * @param sdramDevice the actual device being used, implementing the start-up command sequence
  */
 #ifdef SDRAM_SUPPORTED
 template<SDRAM::SDRAMPinGroup& pins>

src/core/io/SDRAM.cpp

@@ -2,19 +2,38 @@
 
 namespace core::io {
 
-SDRAM::SDRAM(uint32_t* memoryAddress, SDRAMPinGroup& pins, const SDRAMInitConfig& initConfig,
-             const SDRAMTimingConfig& timingConfig, const SDRAMDevice& device)
-    : memoryAddress(memoryAddress), pins(pins), initConfig(initConfig), timingConfig(timingConfig), device(device) {}
+    SDRAM::SDRAM(uint32_t* memoryAddress, SDRAMPinGroup& pins, const SDRAMInitConfig& initConfig,
+                 const SDRAMTimingConfig& timingConfig, const SDRAMDevice& device)
+        : memoryAddress(memoryAddress), pins(pins), initConfig(initConfig), timingConfig(timingConfig), device(device) {}
 
-uint32_t SDRAM::getSdramClockFrequency() {
-    return HAL_RCC_GetSysClockFreq() / 2;
-}
+    uint32_t SDRAM::getSdramClockFrequency(uint8_t mcuClkPerSdramClk) {
+        return HAL_RCC_GetSysClockFreq() / mcuClkPerSdramClk;
+    }
 
-uint32_t SDRAM::getSdramClockPeriodPS() {
-    return 1000000000UL / (getSdramClockFrequency() / 1000);
-}
+    uint32_t SDRAM::getSdramClockPeriodFS(uint8_t mcuClkPerSdramClk) {
+        return 1000000000UL / (getSdramClockFrequency(mcuClkPerSdramClk) / 1000000);
 
-uint32_t SDRAM::NSToSdramClockCycles(uint32_t nanoseconds) {
-    return (nanoseconds * 1000) / (getSdramClockPeriodPS() + 1);
-}
+        /**
+        1,000,000,000 / (getSdramClockFrequency(mcuClkPerSdramClk) / 1000000)
+        1,000,000,000 / ((HAL_RCC_GetSysClockFreq() / mcuClkPerSdramClk) / 1000000
+        Assume HAL_RCC_GetSysClockFreq() returns 100,000,000 Hz and mcuClkPerSdramClk = 2
+        1,000,000,000 / ((100,000,000Hz / 2) / 1000000)
+        1,000,000,000 / (50,000,000Hz / 1000000)
+        1,000,000,000 / 50Hz   (1 / Hz = s)
+        20,000,000 fs
+
+        Why put 1 billion as the numerator? It is the largest base 10 number that would fit in a
+        32-bit number. This gives maximum resolution for the following
+        function that uses it and keeps the calculation clean.
+
+        Why divide getSdramClockFrequency(...) by 1 million? This gives us how many megahertz
+        the clock is running at, which is the most imporant part of the clock speed in our case.
+        This makes the denominator of the outer division as small as possible, allowing us to get a high
+        amount of accuracy for femtoseconds per SDRAM clock period
+        */
+    }
+
+    uint32_t SDRAM::NSToSdramClockCycles(uint32_t nanoseconds, uint8_t mcuClkPerSdramClk) {
+        return (nanoseconds * 1000000) / (getSdramClockPeriodFS(mcuClkPerSdramClk) + 1);
+    } // Multiplied by 1,000,000 to get from nanoseconds to femtoseconds
 } // namespace core::io

src/core/io/platform/f4xx/SDRAMf4xx.cpp

@@ -29,7 +29,7 @@ SDRAMf4xx::SDRAMf4xx(SDRAMPinGroup& pins, const SDRAMInitConfig& sdramInitConfig
     sdramTiming.SelfRefreshTime      = sdramTimingConfig.selfRefreshTime;
     sdramTiming.RowCycleDelay        = sdramTimingConfig.rowCycleDelay;
     sdramTiming.WriteRecoveryTime    = sdramTimingConfig.writeRecoveryTime;
-    sdramTiming.RPDelay              = sdramTimingConfig.rpDelay;
+    sdramTiming.RPDelay              = sdramTimingConfig.readToPrechargeDelay;
     sdramTiming.RCDDelay             = sdramTimingConfig.rcdDelay;
 
     InitHardware(pins);
@@ -65,7 +65,7 @@ SDRAM::Status SDRAMf4xx::SendCommand(SDRAMCommand type, SDRAMCommandTarget targe
 
 SDRAM::Status SDRAMf4xx::ProgramRefreshRate(uint32_t rowCount, uint32_t refreshTime) {
     HAL_StatusTypeDef halStatus = FMC_SDRAM_ProgramRefreshRate(
-        this->sdramDevice, (((refreshTime * 1000) / rowCount) * (getSdramClockFrequency() / 1000000)) - 20);
+        this->sdramDevice, (((refreshTime * 1000) / rowCount) * (getSdramClockFrequency(TODO) / 1000000)) - 20);
 
     return SDRAM::HALStatusToSDRAMStatus(halStatus);
 }