1 /*********************************************************************************************************************** 2 * Copyright [2020-2022] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. 3 * 4 * This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products 5 * of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are 6 * sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use 7 * of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property 8 * right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas 9 * reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION 10 * IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT 11 * PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES 12 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR 13 * DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM 14 * EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION 15 * (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING, 16 * WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS, 17 * OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY 18 * OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. 19 **********************************************************************************************************************/ 20 21 #ifndef R_CGC_API_H 22 #define R_CGC_API_H 23 24 /*******************************************************************************************************************//** 25 * @ingroup RENESAS_INTERFACES 26 * @defgroup CGC_API CGC Interface 27 * @brief Interface for clock generation. 28 * 29 * @section CGC_API_SUMMARY Summary 30 * 31 * The CGC interface provides the ability to configure and use all of the CGC module's capabilities. Among the 32 * capabilities is the selection of several clock sources to use as the system clock source. Additionally, the 33 * system clocks can be divided down to provide a wide range of frequencies for various system and peripheral needs. 34 * 35 * Clock stability can be checked and clocks may also be stopped to save power when not needed. The API has a function 36 * to return the frequency of the system and system peripheral clocks at run time. There is also a feature to detect 37 * when the main oscillator has stopped, with the option of calling a user provided callback function. 38 * 39 * The CGC interface is implemented by: 40 * - @ref CGC 41 * 42 * @{ 43 **********************************************************************************************************************/ 44 45 /*********************************************************************************************************************** 46 * Includes 47 **********************************************************************************************************************/ 48 49 /* Includes board and MCU related header files. */ 50 #include "bsp_api.h" 51 52 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 53 FSP_HEADER 54 55 /********************************************************************************************************************** 56 * Macro definitions 57 **********************************************************************************************************************/ 58 59 /********************************************************************************************************************** 60 * Typedef definitions 61 **********************************************************************************************************************/ 62 63 /** Events that can trigger a callback function */ 64 typedef enum e_cgc_event 65 { 66 CGC_EVENT_OSC_STOP_DETECT ///< Oscillator stop detection has caused the event 67 } cgc_event_t; 68 69 /** Callback function parameter data */ 70 typedef struct st_cgc_callback_args 71 { 72 cgc_event_t event; ///< The event can be used to identify what caused the callback 73 void const * p_context; ///< Placeholder for user data 74 } cgc_callback_args_t; 75 76 /** System clock source identifiers - The source of ICLK, BCLK, FCLK, PCLKS A-D and UCLK prior to the system clock 77 * divider */ 78 typedef enum e_cgc_clock 79 { 80 CGC_CLOCK_HOCO = 0, ///< The high speed on chip oscillator 81 CGC_CLOCK_MOCO = 1, ///< The middle speed on chip oscillator 82 CGC_CLOCK_LOCO = 2, ///< The low speed on chip oscillator 83 CGC_CLOCK_MAIN_OSC = 3, ///< The main oscillator 84 CGC_CLOCK_SUBCLOCK = 4, ///< The subclock oscillator 85 CGC_CLOCK_PLL = 5, ///< The PLL oscillator 86 CGC_CLOCK_PLL2 = 6, ///< The PLL2 oscillator 87 } cgc_clock_t; 88 89 /** PLL divider values */ 90 typedef enum e_cgc_pll_div 91 { 92 CGC_PLL_DIV_1 = 0, ///< PLL divider of 1 93 CGC_PLL_DIV_2 = 1, ///< PLL divider of 2 94 CGC_PLL_DIV_3 = 2, ///< PLL divider of 3 (S7, S5 only) 95 CGC_PLL_DIV_4 = 3, ///< PLL divider of 4 (S3 only) 96 } cgc_pll_div_t; 97 98 /** PLL multiplier values */ 99 typedef enum e_cgc_pll_mul 100 { 101 CGC_PLL_MUL_8_0 = 0xF, ///< PLL multiplier of 8.0 102 CGC_PLL_MUL_9_0 = 0x11, ///< PLL multiplier of 9.0 103 CGC_PLL_MUL_10_0 = 0x13, ///< PLL multiplier of 10.0 104 CGC_PLL_MUL_10_5 = 0x14, ///< PLL multiplier of 10.5 105 CGC_PLL_MUL_11_0 = 0x15, ///< PLL multiplier of 11.0 106 CGC_PLL_MUL_11_5 = 0x16, ///< PLL multiplier of 11.5 107 CGC_PLL_MUL_12_0 = 0x17, ///< PLL multiplier of 12.0 108 CGC_PLL_MUL_12_5 = 0x18, ///< PLL multiplier of 12.5 109 CGC_PLL_MUL_13_0 = 0x19, ///< PLL multiplier of 13.0 110 CGC_PLL_MUL_13_5 = 0x1A, ///< PLL multiplier of 13.5 111 CGC_PLL_MUL_14_0 = 0x1B, ///< PLL multiplier of 14.0 112 CGC_PLL_MUL_14_5 = 0x1D, ///< PLL multiplier of 14.5 113 CGC_PLL_MUL_15_0 = 0x1D, ///< PLL multiplier of 15.0 114 CGC_PLL_MUL_15_5 = 0x1E, ///< PLL multiplier of 15.5 115 CGC_PLL_MUL_16_0 = 0x1F, ///< PLL multiplier of 16.0 116 CGC_PLL_MUL_16_5 = 0x20, ///< PLL multiplier of 16.5 117 CGC_PLL_MUL_17_0 = 0x21, ///< PLL multiplier of 17.0 118 CGC_PLL_MUL_17_5 = 0x22, ///< PLL multiplier of 17.5 119 CGC_PLL_MUL_18_0 = 0x23, ///< PLL multiplier of 18.0 120 CGC_PLL_MUL_18_5 = 0x24, ///< PLL multiplier of 18.5 121 CGC_PLL_MUL_19_0 = 0x25, ///< PLL multiplier of 19.0 122 CGC_PLL_MUL_19_5 = 0x26, ///< PLL multiplier of 19.5 123 CGC_PLL_MUL_20_0 = 0x27, ///< PLL multiplier of 20.0 124 CGC_PLL_MUL_20_5 = 0x28, ///< PLL multiplier of 20.5 125 CGC_PLL_MUL_21_0 = 0x29, ///< PLL multiplier of 21.0 126 CGC_PLL_MUL_21_5 = 0x2A, ///< PLL multiplier of 21.5 127 CGC_PLL_MUL_22_0 = 0x2B, ///< PLL multiplier of 22.0 128 CGC_PLL_MUL_22_5 = 0x2C, ///< PLL multiplier of 22.5 129 CGC_PLL_MUL_23_0 = 0x2D, ///< PLL multiplier of 23.0 130 CGC_PLL_MUL_23_5 = 0x2E, ///< PLL multiplier of 23.5 131 CGC_PLL_MUL_24_0 = 0x2F, ///< PLL multiplier of 24.0 132 CGC_PLL_MUL_24_5 = 0x30, ///< PLL multiplier of 24.5 133 CGC_PLL_MUL_25_0 = 0x31, ///< PLL multiplier of 25.0 134 CGC_PLL_MUL_25_5 = 0x32, ///< PLL multiplier of 25.5 135 CGC_PLL_MUL_26_0 = 0x33, ///< PLL multiplier of 26.0 136 CGC_PLL_MUL_26_5 = 0x34, ///< PLL multiplier of 26.5 137 CGC_PLL_MUL_27_0 = 0x35, ///< PLL multiplier of 27.0 138 CGC_PLL_MUL_27_5 = 0x36, ///< PLL multiplier of 27.5 139 CGC_PLL_MUL_28_0 = 0x37, ///< PLL multiplier of 28.0 140 CGC_PLL_MUL_28_5 = 0x38, ///< PLL multiplier of 28.5 141 CGC_PLL_MUL_29_0 = 0x39, ///< PLL multiplier of 29.0 142 CGC_PLL_MUL_29_5 = 0x3A, ///< PLL multiplier of 29.5 143 CGC_PLL_MUL_30_0 = 0x3B, ///< PLL multiplier of 30.0 144 CGC_PLL_MUL_31_0 = 0x3D, ///< PLL multiplier of 31.0 145 } cgc_pll_mul_t; 146 147 /** System clock divider vlues - The individually selectable divider of each of the system clocks, ICLK, BCLK, FCLK, 148 * PCLKS A-D. */ 149 typedef enum e_cgc_sys_clock_div 150 { 151 CGC_SYS_CLOCK_DIV_1 = 0, ///< System clock divided by 1 152 CGC_SYS_CLOCK_DIV_2 = 1, ///< System clock divided by 2 153 CGC_SYS_CLOCK_DIV_4 = 2, ///< System clock divided by 4 154 CGC_SYS_CLOCK_DIV_8 = 3, ///< System clock divided by 8 155 CGC_SYS_CLOCK_DIV_16 = 4, ///< System clock divided by 16 156 CGC_SYS_CLOCK_DIV_32 = 5, ///< System clock divided by 32 157 CGC_SYS_CLOCK_DIV_64 = 6, ///< System clock divided by 64 158 } cgc_sys_clock_div_t; 159 160 /** Clock configuration structure - Used as an input parameter to the @ref cgc_api_t::clockStart function for the PLL clock. */ 161 typedef struct st_cgc_pll_cfg 162 { 163 cgc_clock_t source_clock; ///< PLL source clock (main oscillator or HOCO) 164 cgc_pll_div_t divider; ///< PLL divider 165 cgc_pll_mul_t multiplier; ///< PLL multiplier 166 } cgc_pll_cfg_t; 167 168 /** Clock configuration structure - Used as an input parameter to the @ref cgc_api_t::systemClockSet and @ref cgc_api_t::systemClockGet 169 * functions. */ 170 typedef union u_cgc_divider_cfg 171 { 172 uint32_t sckdivcr_w; ///< (@ 0x4001E020) System clock Division control register 173 174 /* DEPRECATED: Anonymous structure. */ 175 struct 176 { 177 cgc_sys_clock_div_t pclkd_div : 3; ///< Divider value for PCLKD 178 uint32_t : 1; 179 cgc_sys_clock_div_t pclkc_div : 3; ///< Divider value for PCLKC 180 uint32_t : 1; 181 cgc_sys_clock_div_t pclkb_div : 3; ///< Divider value for PCLKB 182 uint32_t : 1; 183 cgc_sys_clock_div_t pclka_div : 3; ///< Divider value for PCLKA 184 uint32_t : 1; 185 cgc_sys_clock_div_t bclk_div : 3; ///< Divider value for BCLK 186 uint32_t : 5; 187 cgc_sys_clock_div_t iclk_div : 3; ///< Divider value for ICLK 188 uint32_t : 1; 189 cgc_sys_clock_div_t fclk_div : 3; ///< Divider value for FCLK 190 uint32_t : 1; 191 }; 192 193 struct 194 { 195 cgc_sys_clock_div_t pclkd_div : 3; ///< Divider value for PCLKD 196 uint32_t : 1; 197 cgc_sys_clock_div_t pclkc_div : 3; ///< Divider value for PCLKC 198 uint32_t : 1; 199 cgc_sys_clock_div_t pclkb_div : 3; ///< Divider value for PCLKB 200 uint32_t : 1; 201 cgc_sys_clock_div_t pclka_div : 3; ///< Divider value for PCLKA 202 uint32_t : 1; 203 cgc_sys_clock_div_t bclk_div : 3; ///< Divider value for BCLK 204 uint32_t : 5; 205 cgc_sys_clock_div_t iclk_div : 3; ///< Divider value for ICLK 206 uint32_t : 1; 207 cgc_sys_clock_div_t fclk_div : 3; ///< Divider value for FCLK 208 uint32_t : 1; 209 } sckdivcr_b; 210 } cgc_divider_cfg_t; 211 212 /** USB clock divider values */ 213 typedef enum e_cgc_usb_clock_div 214 { 215 CGC_USB_CLOCK_DIV_3 = 2, ///< Divide USB source clock by 3 216 CGC_USB_CLOCK_DIV_4 = 3, ///< Divide USB source clock by 4 217 CGC_USB_CLOCK_DIV_5 = 4, ///< Divide USB source clock by 5 218 } cgc_usb_clock_div_t; 219 220 /** Clock options */ 221 typedef enum e_cgc_clock_change 222 { 223 CGC_CLOCK_CHANGE_START = 0, ///< Start the clock 224 CGC_CLOCK_CHANGE_STOP = 1, ///< Stop the clock 225 CGC_CLOCK_CHANGE_NONE = 2, ///< No change to the clock 226 } cgc_clock_change_t; 227 228 /** CGC control block. Allocate an instance specific control block to pass into the CGC API calls. 229 * @par Implemented as 230 * - cgc_instance_ctrl_t 231 */ 232 typedef void cgc_ctrl_t; 233 234 /** Configuration options. */ 235 typedef struct s_cgc_cfg 236 { 237 void (* p_callback)(cgc_callback_args_t * p_args); 238 void const * p_context; 239 } cgc_cfg_t; 240 241 /** Clock configuration */ 242 typedef struct st_cgc_clocks_cfg 243 { 244 cgc_clock_t system_clock; ///< System clock source enumeration 245 cgc_pll_cfg_t pll_cfg; ///< PLL configuration structure 246 cgc_pll_cfg_t pll2_cfg; ///< PLL2 configuration structure 247 cgc_divider_cfg_t divider_cfg; ///< Clock dividers structure 248 cgc_clock_change_t loco_state; ///< State of LOCO 249 cgc_clock_change_t moco_state; ///< State of MOCO 250 cgc_clock_change_t hoco_state; ///< State of HOCO 251 cgc_clock_change_t mainosc_state; ///< State of Main oscillator 252 cgc_clock_change_t pll_state; ///< State of PLL 253 cgc_clock_change_t pll2_state; ///< State of PLL2 254 } cgc_clocks_cfg_t; 255 256 /** CGC functions implemented at the HAL layer follow this API. */ 257 typedef struct 258 { 259 /** Initial configuration 260 * @par Implemented as 261 * - @ref R_CGC_Open() 262 * @param[in] p_ctrl Pointer to instance control block 263 * @param[in] p_cfg Pointer to configuration 264 */ 265 fsp_err_t (* open)(cgc_ctrl_t * const p_ctrl, cgc_cfg_t const * const p_cfg); 266 267 /** Configure all system clocks. 268 * @par Implemented as 269 * - @ref R_CGC_ClocksCfg() 270 * @param[in] p_ctrl Pointer to instance control block 271 * @param[in] p_clock_cfg Pointer to desired configuration of system clocks 272 */ 273 fsp_err_t (* clocksCfg)(cgc_ctrl_t * const p_ctrl, cgc_clocks_cfg_t const * const p_clock_cfg); 274 275 /** Start a clock. 276 * @par Implemented as 277 * - @ref R_CGC_ClockStart() 278 * @param[in] p_ctrl Pointer to instance control block 279 * @param[in] clock_source Clock source to start 280 * @param[in] p_pll_cfg Pointer to PLL configuration, can be NULL if clock_source is not CGC_CLOCK_PLL or 281 * CGC_CLOCK_PLL2 282 */ 283 fsp_err_t (* clockStart)(cgc_ctrl_t * const p_ctrl, cgc_clock_t clock_source, 284 cgc_pll_cfg_t const * const p_pll_cfg); 285 286 /** Stop a clock. 287 * @par Implemented as 288 * - @ref R_CGC_ClockStop() 289 * @param[in] p_ctrl Pointer to instance control block 290 * @param[in] clock_source The clock source to stop 291 */ 292 fsp_err_t (* clockStop)(cgc_ctrl_t * const p_ctrl, cgc_clock_t clock_source); 293 294 /** Check the stability of the selected clock. 295 * @par Implemented as 296 * - @ref R_CGC_ClockCheck() 297 * @param[in] p_ctrl Pointer to instance control block 298 * @param[in] clock_source Which clock source to check for stability 299 */ 300 fsp_err_t (* clockCheck)(cgc_ctrl_t * const p_ctrl, cgc_clock_t clock_source); 301 302 /** Set the system clock. 303 * @par Implemented as 304 * - @ref R_CGC_SystemClockSet() 305 * @param[in] p_ctrl Pointer to instance control block 306 * @param[in] clock_source Clock source to set as system clock 307 * @param[in] p_divider_cfg Pointer to the clock divider configuration 308 */ 309 fsp_err_t (* systemClockSet)(cgc_ctrl_t * const p_ctrl, cgc_clock_t clock_source, 310 cgc_divider_cfg_t const * const p_divider_cfg); 311 312 /** Get the system clock information. 313 * @par Implemented as 314 * - @ref R_CGC_SystemClockGet() 315 * @param[in] p_ctrl Pointer to instance control block 316 * @param[out] p_clock_source Returns the current system clock 317 * @param[out] p_divider_cfg Returns the current system clock dividers 318 */ 319 fsp_err_t (* systemClockGet)(cgc_ctrl_t * const p_ctrl, cgc_clock_t * const p_clock_source, 320 cgc_divider_cfg_t * const p_divider_cfg); 321 322 /** Enable and optionally register a callback for Main Oscillator stop detection. 323 * @par Implemented as 324 * - @ref R_CGC_OscStopDetectEnable() 325 * @param[in] p_ctrl Pointer to instance control block 326 * @param[in] p_callback Callback function that will be called by the NMI interrupt when an oscillation stop is 327 * detected. If the second argument is "false", then this argument can be NULL. 328 * @param[in] enable Enable/disable Oscillation Stop Detection 329 */ 330 fsp_err_t (* oscStopDetectEnable)(cgc_ctrl_t * const p_ctrl); 331 332 /** Disable Main Oscillator stop detection. 333 * @par Implemented as 334 * - @ref R_CGC_OscStopDetectDisable() 335 * @param[in] p_ctrl Pointer to instance control block 336 */ 337 fsp_err_t (* oscStopDetectDisable)(cgc_ctrl_t * const p_ctrl); 338 339 /** Clear the oscillator stop detection flag. 340 * @par Implemented as 341 * - @ref R_CGC_OscStopStatusClear() 342 * @param[in] p_ctrl Pointer to instance control block 343 */ 344 fsp_err_t (* oscStopStatusClear)(cgc_ctrl_t * const p_ctrl); 345 346 /** 347 * Specify callback function and optional context pointer and working memory pointer. 348 * @par Implemented as 349 * - R_CGC_CallbackSet() 350 * 351 * @param[in] p_ctrl Pointer to the CGC control block. 352 * @param[in] p_callback Callback function 353 * @param[in] p_context Pointer to send to callback function 354 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 355 * Callback arguments allocated here are only valid during the callback. 356 */ 357 fsp_err_t (* callbackSet)(cgc_ctrl_t * const p_api_ctrl, void (* p_callback)(cgc_callback_args_t *), 358 void const * const p_context, cgc_callback_args_t * const p_callback_memory); 359 360 /** Close the CGC driver. 361 * @par Implemented as 362 * - @ref R_CGC_Close() 363 * @param[in] p_ctrl Pointer to instance control block 364 */ 365 fsp_err_t (* close)(cgc_ctrl_t * const p_ctrl); 366 } cgc_api_t; 367 368 /** This structure encompasses everything that is needed to use an instance of this interface. */ 369 typedef struct st_cgc_instance 370 { 371 cgc_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 372 cgc_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 373 cgc_api_t const * p_api; ///< Pointer to the API structure for this instance 374 } cgc_instance_t; 375 376 /*******************************************************************************************************************//** 377 * @} (end defgroup CGC_API) 378 **********************************************************************************************************************/ 379 380 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 381 FSP_FOOTER 382 383 #endif // R_CGC_API_H 384