1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /********************************************************************************************************************** 21 * File Name : r_cgc_api.h 22 * Description : API for the Clock Generation Circuit (CGC) module. 23 **********************************************************************************************************************/ 24 25 #ifndef DRV_CGC_API_H 26 #define DRV_CGC_API_H 27 28 /*******************************************************************************************************************//** 29 * @ingroup Interface_Library 30 * @defgroup CGC_API CGC Interface 31 * @brief Interface for clock generation. 32 * 33 * @section CGC_API_SUMMARY Summary 34 * 35 * The CGC interface provides the ability to configure and use all of the CGC module's capabilities. Among the 36 * capabilities is the selection of several clock sources to use as the system clock source. Additionally, the 37 * system clocks can be divided down to provide a wide range of frequencies for various system and peripheral needs. 38 * 39 * Clock stability can be checked and clocks may also be stopped to save power when not needed. The API has a function 40 * to return the frequency of the system and system peripheral clocks at run time. There is also a feature to detect 41 * when the main oscillator has stopped, with the option of calling a user provided callback function. 42 * 43 * Related SSP architecture topics: 44 * - @ref ssp-interfaces 45 * - @ref ssp-predefined-layers 46 * - @ref using-ssp-modules 47 * 48 * CGC Interface description: @ref ModuleCGConCGC 49 * 50 * 51 * @{ 52 **********************************************************************************************************************/ 53 54 /*********************************************************************************************************************** 55 * Includes 56 **********************************************************************************************************************/ 57 /* Includes board and MCU related header files. */ 58 #include "bsp_api.h" 59 60 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 61 SSP_HEADER 62 63 /********************************************************************************************************************** 64 * Macro definitions 65 **********************************************************************************************************************/ 66 /* Version Number of API. */ 67 #define CGC_API_VERSION_MAJOR (1U) 68 #define CGC_API_VERSION_MINOR (4U) 69 70 /********************************************************************************************************************** 71 * Typedef definitions 72 **********************************************************************************************************************/ 73 /** Events that can trigger a callback function */ 74 typedef enum e_cgc_event 75 { 76 CGC_EVENT_OSC_STOP_DETECT ///< Oscillator stop detection has caused the event. 77 } cgc_event_t; 78 79 /** Callback function parameter data */ 80 typedef struct st_cgc_callback_args 81 { 82 cgc_event_t event; ///< The event can be used to identify what caused the callback. 83 void const * p_context; ///< Placeholder for user data. 84 } cgc_callback_args_t; 85 86 87 /** System clock source identifiers - The source of ICLK, BCLK, FCLK, PCLKS A-D and UCLK prior to the system clock 88 * divider */ 89 typedef enum e_cgc_clock 90 { 91 CGC_CLOCK_HOCO = 0x00, ///< The high speed on chip oscillator. 92 CGC_CLOCK_MOCO = 0x01, ///< The middle speed on chip oscillator. 93 CGC_CLOCK_LOCO = 0x02, ///< The low speed on chip oscillator. 94 CGC_CLOCK_MAIN_OSC = 0x03, ///< The main oscillator. 95 CGC_CLOCK_SUBCLOCK = 0x04, ///< The subclock oscillator. 96 CGC_CLOCK_PLL = 0x05, ///< The PLL oscillator. 97 } cgc_clock_t; 98 99 /** PLL divider values */ 100 typedef enum e_cgc_pll_div 101 { 102 CGC_PLL_DIV_1 = 0x00, ///< PLL divider of 1. 103 CGC_PLL_DIV_2 = 0x01, ///< PLL divider of 2. 104 CGC_PLL_DIV_3 = 0x02, ///< PLL divider of 3 (S7G2 only). 105 CGC_PLL_DIV_4 = 0x03 ///< PLL divider of 4 (S3A7 only). 106 } cgc_pll_div_t; 107 108 /** System clock divider values - The individually selectable divider of each of the system clocks, ICLK, BCLK, FCLK, 109 * PCLKS A-D */ 110 typedef enum e_cgc_sys_clock_div 111 { 112 CGC_SYS_CLOCK_DIV_1 = 0x00, ///< System clock divided by 1. 113 CGC_SYS_CLOCK_DIV_2 = 0x01, ///< System clock divided by 2. 114 CGC_SYS_CLOCK_DIV_4 = 0x02, ///< System clock divided by 4. 115 CGC_SYS_CLOCK_DIV_8 = 0x03, ///< System clock divided by 8. 116 CGC_SYS_CLOCK_DIV_16 = 0x04, ///< System clock divided by 16. 117 CGC_SYS_CLOCK_DIV_32 = 0x05, ///< System clock divided by 32. 118 CGC_SYS_CLOCK_DIV_64 = 0x06, ///< System clock divided by 64. 119 } cgc_sys_clock_div_t; 120 121 /** Clock configuration structure - Used as an input parameter to the cgc_api_t::clockStart function for the PLL clock. */ 122 typedef struct st_cgc_clock_cfg 123 { 124 cgc_clock_t source_clock; ///< PLL source clock (S7G2 only). 125 cgc_pll_div_t divider; ///< PLL divider. 126 /*LDRA_INSPECTED 90 s float used because float32_t is not part of the C99 standard integer definitions. */ 127 float multiplier; ///< PLL multiplier. 128 } cgc_clock_cfg_t; 129 130 /** System clock identifiers - Used as an input parameter to the cgc_api_t::systemClockFreqGet function. */ 131 typedef enum e_cgc_system_clocks 132 { 133 CGC_SYSTEM_CLOCKS_PCLKA, ///< PCLKA - Peripheral module clock A. 134 CGC_SYSTEM_CLOCKS_PCLKB, ///< PCLKB - Peripheral module clock B. 135 CGC_SYSTEM_CLOCKS_PCLKC, ///< PCLKC - Peripheral module clock C. 136 CGC_SYSTEM_CLOCKS_PCLKD, ///< PCLKD - Peripheral module clock D. 137 CGC_SYSTEM_CLOCKS_BCLK, ///< BCLK - External bus Clock. 138 CGC_SYSTEM_CLOCKS_FCLK, ///< FCLK - FlashIF clock. 139 CGC_SYSTEM_CLOCKS_ICLK ///< ICLK - System clock. 140 } cgc_system_clocks_t; 141 142 /** Divider values for the CLKOUT output. */ 143 typedef enum e_cgc_clockout_dividers 144 { 145 CGC_CLOCKOUT_DIV_1 = 0x00, ///< Clockout source is divided by 1. 146 CGC_CLOCKOUT_DIV_2 = 0x01, ///< Clockout source is divided by 2. 147 CGC_CLOCKOUT_DIV_4 = 0x02, ///< Clockout source is divided by 4. 148 CGC_CLOCKOUT_DIV_8 = 0x03, ///< Clockout source is divided by 8. 149 CGC_CLOCKOUT_DIV_16 = 0x04, ///< Clockout source is divided by 16. 150 CGC_CLOCKOUT_DIV_32 = 0x05, ///< Clockout source is divided by 32. 151 CGC_CLOCKOUT_DIV_64 = 0x06, ///< Clockout source is divided by 64. 152 CGC_CLOCKOUT_DIV_128 = 0x07, ///< Clockout source is divided by 128. 153 } cgc_clockout_dividers_t; 154 155 /** Divider values for the external bus clock output. */ 156 typedef enum e_cgc_bclockout_dividers 157 { 158 CGC_BCLOCKOUT_DIV_1 = 0x00, ///< External bus clock source is divided by 1. 159 CGC_BCLOCKOUT_DIV_2 = 0x01, ///< External bus clock source is divided by 2. 160 } cgc_bclockout_dividers_t; 161 162 /** Clock configuration structure - Used as an input parameter to the cgc_api_t::systemClockSet and cgc_api_t::systemClockGet 163 * functions. */ 164 typedef struct st_cgc_system_clock_cfg 165 { 166 cgc_sys_clock_div_t pclka_div; ///< Divider value for PCLKA 167 cgc_sys_clock_div_t pclkb_div; ///< Divider value for PCLKB 168 cgc_sys_clock_div_t pclkc_div; ///< Divider value for PCLKC 169 cgc_sys_clock_div_t pclkd_div; ///< Divider value for PCLKD 170 cgc_sys_clock_div_t bclk_div; ///< Divider value for BCLK 171 cgc_sys_clock_div_t fclk_div; ///< Divider value for FCLK 172 cgc_sys_clock_div_t iclk_div; ///< Divider value for ICLK 173 } cgc_system_clock_cfg_t; 174 175 /** USB clock divider values */ 176 typedef enum e_cgc_usb_clock_div 177 { 178 CGC_USB_CLOCK_DIV_3 = 0x02, ///< Divide USB source clock by 3 179 CGC_USB_CLOCK_DIV_4 = 0x03, ///< Divide USB source clock by 4 180 CGC_USB_CLOCK_DIV_5 = 0x04, ///< Divide USB source clock by 5 181 } cgc_usb_clock_div_t; 182 183 184 /** Available period units for R_CGC_SystickUpdate() */ 185 typedef enum 186 { 187 CGC_SYSTICK_PERIOD_UNITS_MILLISECONDS = 1000, ///< Requested period in milliseconds 188 CGC_SYSTICK_PERIOD_UNITS_MICROSECONDS = 1000000 ///< Requested period in microseconds 189 } cgc_systick_period_units_t; 190 191 /** Clock options */ 192 typedef enum e_cgc_clock_change 193 { 194 CGC_CLOCK_CHANGE_NONE, ///< No change to the clock 195 CGC_CLOCK_CHANGE_STOP, ///< Stop the clock 196 CGC_CLOCK_CHANGE_START, ///< Start the clock 197 } cgc_clock_change_t; 198 199 /** Clock configuration */ 200 typedef struct st_cgc_clocks_cfg 201 { 202 cgc_clock_t system_clock; ///< System clock source enumeration 203 cgc_clock_cfg_t pll_cfg; ///< PLL configuration structure 204 cgc_system_clock_cfg_t sys_cfg; ///< Clock dividers structure 205 cgc_clock_change_t loco_state; ///< State of LOCO 206 cgc_clock_change_t moco_state; ///< State of MOCO 207 cgc_clock_change_t hoco_state; ///< State of HOCO 208 cgc_clock_change_t subosc_state; ///< State of Sub-oscillator 209 cgc_clock_change_t mainosc_state; ///< State of Main oscillator 210 cgc_clock_change_t pll_state; ///< State of PLL 211 } cgc_clocks_cfg_t; 212 213 /** CGC functions implemented at the HAL layer follow this API. */ 214 typedef struct 215 { 216 /** Initial configuration 217 * @par Implemented as 218 * - R_CGC_Init() 219 * @note The BSP module calls this function at startup. No further initialization is necessary. 220 */ 221 ssp_err_t (* init)(void); 222 223 /** Configure all system clocks. 224 * @par Implemented as 225 * - R_CGC_ClocksCfg() 226 * @note The BSP module calls this function at startup, but it can also be called from the application to change 227 * clocks at runtime. 228 * @param[in] p_clock_cfg Pointer to a structure that contains the dividers or multipliers to be used when 229 * configuring the PLL. 230 */ 231 ssp_err_t (* clocksCfg)(cgc_clocks_cfg_t const * const p_clock_cfg); 232 233 /** Start a clock. 234 * @par Implemented as 235 * - R_CGC_ClockStart() 236 * @pre Clock to be started must not be running prior to calling this function or an error will be returned. 237 * @param[in] clock_source Clock source to initialize. 238 * @param[in] p_clock_cfg Pointer to a structure that contains the dividers or multipliers to be used when 239 * configuring the PLL. 240 */ 241 ssp_err_t (* clockStart)(cgc_clock_t clock_source, cgc_clock_cfg_t * p_clock_cfg); 242 243 /** Stop a clock. 244 * @par Implemented as 245 * - R_CGC_ClockStop() 246 * @pre Clock to be stopped must not be stopped prior to calling this function or an error will be returned. 247 * @param[in] clock_source The clock source to stop. 248 */ 249 ssp_err_t (* clockStop)(cgc_clock_t clock_source); 250 251 /** Set the system clock. 252 * @par Implemented as 253 * - R_CGC_SystemClockSet() 254 * @pre The clock to be set as the system clock must be running prior to calling this function. 255 * @param[in] clock_source Clock source to set as system clock 256 * @param[in] p_clock_cfg Pointer to the clock dividers configuration passed by the caller. 257 */ 258 ssp_err_t (* systemClockSet)(cgc_clock_t clock_source, cgc_system_clock_cfg_t const * const p_clock_cfg); 259 260 /** Get the system clock information. 261 * @par Implemented as 262 * - R_CGC_SystemClockGet() 263 * @param[in] p_set_clock_cfg Pointer to clock configuration structure 264 * @param[out] clock_source Returns the current system clock. 265 * @param[out] p_clock_cfg Returns the current system clock dividers. 266 */ 267 ssp_err_t (* systemClockGet)(cgc_clock_t * p_clock_source, cgc_system_clock_cfg_t * p_set_clock_cfg); 268 269 /** Return the frequency of the selected clock. 270 * @par Implemented as 271 * - R_CGC_SystemClockFreqGet() 272 * @param[in] clock Specifies the internal clock whose frequency is returned. 273 * @param[out] p_freq_hz Returns the frequency in Hz referenced by this pointer. 274 */ 275 ssp_err_t (* systemClockFreqGet)(cgc_system_clocks_t clock, uint32_t * p_freq_hz); 276 277 /** Check the stability of the selected clock. 278 * @par Implemented as 279 * - R_CGC_ClockCheck() 280 * @param[in] clock_source Which clock source to check for stability. 281 */ 282 ssp_err_t (* clockCheck)(cgc_clock_t clock_source); 283 284 /** Configure the Main Oscillator stop detection. 285 * @par Implemented as 286 * - R_CGC_OscStopDetect() 287 * @param[in] p_callback Callback function that will be called by the NMI interrupt when an oscillation stop is 288 * detected. If the second argument is "false", then this argument can be NULL. 289 * @param[in] enable Enable/disable Oscillation Stop Detection. 290 */ 291 ssp_err_t (* oscStopDetect)(void (* p_callback)(cgc_callback_args_t * p_args), bool enable); 292 293 /** Clear the oscillator stop detection flag. 294 * @par Implemented as 295 * - R_CGC_OscStopStatusClear() 296 */ 297 ssp_err_t (* oscStopStatusClear)(void); 298 299 /** Configure the bus clock output secondary divider. The primary divider is set using the 300 * bsp clock configuration and the cgc_api_t::systemClockSet function (S7G2 and S3A7 only). 301 * 302 * @par Implemented as 303 * - R_CGC_BusClockOutCfg() 304 * @param[in] divider The divider of 1 or 2 of the clock source. 305 */ 306 ssp_err_t (* busClockOutCfg)(cgc_bclockout_dividers_t divider); 307 308 /** Enable the bus clock output (S7G2 and S3A7 only). 309 * @par Implemented as 310 * - R_CGC_BusClockOutEnable() 311 */ 312 ssp_err_t (* busClockOutEnable)(void); 313 314 /** Disable the bus clock output (S7G2 and S3A7 only). 315 * @par Implemented as 316 * - R_CGC_BusClockOutDisable() 317 */ 318 ssp_err_t (* busClockOutDisable)(void); 319 320 /** Configure clockOut. 321 * @par Implemented as 322 * - R_CGC_ClockOutCfg() 323 * @param[in] clock Clock source. 324 * @param[in] divider Divider of between 1 and 128 of the clock source. 325 */ 326 ssp_err_t (* clockOutCfg)(cgc_clock_t clock, cgc_clockout_dividers_t divider); 327 328 /** Enable clock output on the CLKOUT pin. The source of the clock is controlled by cgc_api_t::clockOutCfg. 329 * @par Implemented as 330 * - R_CGC_ClockOutEnable() 331 */ 332 ssp_err_t (* clockOutEnable)(void); 333 334 /** Disable clock output on the CLKOUT pin. The source of the clock is controlled by cgc_api_t::clockOutCfg. 335 * @par Implemented as 336 * - R_CGC_ClockOutDisable() 337 */ 338 ssp_err_t (* clockOutDisable)(void); 339 340 /** Configure the segment LCD Clock (S3A7 and S124 only). 341 * @par Implemented as 342 * - R_CGC_LCDClockCfg() 343 * @param[in] clock Segment LCD clock source. 344 */ 345 ssp_err_t (* lcdClockCfg)(cgc_clock_t clock); 346 347 /** Enable the LCD clock (S3A7 and S124 only). 348 * @par Implemented as 349 * - R_CGC_LCDClockEnable() 350 */ 351 ssp_err_t (* lcdClockEnable)(void); 352 353 /** Disables the LCD clock (S3A7 and S124 only). 354 * @par Implemented as 355 * - R_CGC_LCDClockDisable() 356 */ 357 ssp_err_t (* lcdClockDisable)(void); 358 359 /** Configure the 24-bit Sigma-Delta A/D Converter Clock (S1JA only). 360 * @par Implemented as 361 * - R_CGC_SDADCClockCfg() 362 * @param[in] clock SDADC clock source. 363 */ 364 ssp_err_t (* sdadcClockCfg)(cgc_clock_t clock); 365 366 /** Enable the SDADC clock (S1JA only). 367 * @par Implemented as 368 * - R_CGC_SDADCClockEnable() 369 */ 370 ssp_err_t (* sdadcClockEnable)(void); 371 372 /** Disables the SDADC clock (S1JA only). 373 * @par Implemented as 374 * - R_CGC_SDADCClockDisable() 375 */ 376 ssp_err_t (* sdadcClockDisable)(void); 377 378 /** Enables the SDRAM clock output (S7G2 only). 379 * @par Implemented as 380 * - R_CGC_SDRAMClockOutEnable() 381 */ 382 ssp_err_t (* sdramClockOutEnable)(void); 383 384 /** Disables the SDRAM clock (S7G2 only). 385 * @par Implemented as 386 * - R_CGC_SDRAMClockOutDisable() 387 * */ 388 ssp_err_t (* sdramClockOutDisable)(void); 389 390 /** Configures the USB clock (S7G2 only). 391 * @par Implemented as 392 * - R_CGC_USBClockCfg() 393 * @param[in] divider The divider of 3, 4 or 5, of the clock source. 394 */ 395 ssp_err_t (* usbClockCfg)(cgc_usb_clock_div_t divider); 396 397 /** Update the Systick timer. 398 * @par Implemented as 399 * - R_CGC_SystickUpdate() 400 * @param[in] period_count The duration for the systick period. 401 * @param[in] units The units for the provided period. 402 */ 403 ssp_err_t (* systickUpdate)(uint32_t period_count, cgc_systick_period_units_t units); 404 405 /** Gets the CGC driver version. 406 * @par Implemented as 407 * - R_CGC_VersionGet() 408 * @param[out] p_version Code and API version used. 409 */ 410 ssp_err_t (* versionGet)(ssp_version_t * p_version); 411 } cgc_api_t; 412 413 /** This structure encompasses everything that is needed to use an instance of this interface. */ 414 typedef struct st_cgc_instance 415 { 416 cgc_clock_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 417 cgc_api_t const * p_api; ///< Pointer to the API structure for this instance 418 } cgc_instance_t; 419 420 /*******************************************************************************************************************//** 421 * @} (end defgroup CGC_API) 422 **********************************************************************************************************************/ 423 424 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 425 SSP_FOOTER 426 427 #endif // ifndef DRV_CGC_API_H 428