1 /***************************************************************************//**
2  * @file
3  * @brief HFXO Manager API definition.
4  *******************************************************************************
5  * # License
6  * <b>Copyright 2019 Silicon Laboratories Inc. www.silabs.com</b>
7  *******************************************************************************
8  *
9  * SPDX-License-Identifier: Zlib
10  *
11  * The licensor of this software is Silicon Laboratories Inc.
12  *
13  * This software is provided 'as-is', without any express or implied
14  * warranty. In no event will the authors be held liable for any damages
15  * arising from the use of this software.
16  *
17  * Permission is granted to anyone to use this software for any purpose,
18  * including commercial applications, and to alter it and redistribute it
19  * freely, subject to the following restrictions:
20  *
21  * 1. The origin of this software must not be misrepresented; you must not
22  *    claim that you wrote the original software. If you use this software
23  *    in a product, an acknowledgment in the product documentation would be
24  *    appreciated but is not required.
25  * 2. Altered source versions must be plainly marked as such, and must not be
26  *    misrepresented as being the original software.
27  * 3. This notice may not be removed or altered from any source distribution.
28  *
29  ******************************************************************************/
30 
31 /***************************************************************************//**
32  * @addtogroup hfxo_manager HFXO Manager
33  * @brief HFXO Manager
34  * @details
35  * ## Overview
36  *
37  * HFXO Manager is a platform service module intended to manage the High
38  * Frequency Crystal Oscillator (HFXO) module and offer related functionalities
39  * and services.
40  * For the moment, this module is only supported on Silicon Labs series 2
41  * devices.
42  * Among others, it handles the HFXO startup failures. This is to support
43  * sleepy crystals (crystals where the ESR value could change unexpectedly up
44  * to 5 times its value during the startup). In case of a failure during the
45  * HFXO startup, the HFXO Manager will retry the startup process with more
46  * aggressive settings (sleepy crystal settings) to try waking up the crystal
47  * from its sleepy state so that the ESR value can fall back to normal values.
48  * Once the crystal is out of its sleepy state, the module will put back the
49  * normal settings ensuring the right oscillation frequency. This feature can
50  * be enabled/disabled via the configuration define
51  * SL_HFXO_MANAGER_SLEEPY_CRYSTAL_SUPPORT.
52  * The module catches startup failures through interrupts using the HFXO
53  * interrupt handler. If your application also needs the HFXO interrupt
54  * handler, the configuration define SL_HFXO_MANAGER_CUSTOM_HFXO_IRQ_HANDLER
55  * can be used to remove the HFXO interrupt handler definition from the HFXO
56  * Manager so that it can be defined in your application. In that case, your
57  * definition of the HFXO Interrupt Handler will need to call the
58  * sl_hfxo_manager_irq_handler() function so that HFXO Manager can continue
59  * to work properly.
60  * The HFXO Manager is also required by the Power Manager module for some
61  * internal features and therefore becomes mandatory every time the Power
62  * Manager is present.
63  *
64  *
65  * ## Initialization
66  *
67  * Two functions are required to initialize the module.
68  * sl_hfxo_manager_init_hardware() is to initialize the HFXO interrupts and
69  * must therefore be called before any other HFXO initialization functions like
70  * the emlib CMU_HFXOInit() or device_init function sl_device_init_hfxo().
71  * The second initialization function sl_hfxo_manager_init() is required for
72  * internal use and needs to be called before going to sleep.
73  *
74  * @{
75  ******************************************************************************/
76 
77 #ifndef SL_HFXO_MANAGER_H
78 #define SL_HFXO_MANAGER_H
79 
80 #include "sl_status.h"
81 #include <stdbool.h>
82 
83 #ifdef __cplusplus
84 extern "C" {
85 #endif
86 
87 /// @brief Sleepy Crystal settings
88 typedef struct sl_hfxo_manager_sleepy_xtal_settings {
89   uint32_t ana_ctune;         ///< Tuning Capacitance values for XI and XO during startup intermediate and steady stages
90   uint32_t core_bias_current; ///< Core Bias current value during all stages
91 } sl_hfxo_manager_sleepy_xtal_settings_t;
92 
93 /***************************************************************************//**
94  * HFXO Manager module hardware specific initialization.
95  ******************************************************************************/
96 void sl_hfxo_manager_init_hardware(void);
97 
98 /***************************************************************************//**
99  * Initialize HFXO Manager module.
100  *
101  * @return Status Code.
102  ******************************************************************************/
103 sl_status_t sl_hfxo_manager_init(void);
104 
105 /***************************************************************************//**
106  * Updates Sleepy Crystal settings.
107  *
108  * @param  settings  Pointer to settings structure
109  *
110  * @return Status Code.
111  *
112  * @note Those settings are temporarily used to force oscillation on sleepy
113  *       crystal.
114  *       Default values should be enough to wake-up sleepy crystals. Otherwise,
115  *       this function can be used.
116  ******************************************************************************/
117 sl_status_t sl_hfxo_manager_update_sleepy_xtal_settings(const sl_hfxo_manager_sleepy_xtal_settings_t *settings);
118 
119 /***************************************************************************//**
120  * When this callback function is called, it means that HFXO failed twice in
121  * a row to start with normal configurations. This may mean that there is a
122  * bad crystal. When getting this callback, HFXO is running but its properties
123  * (frequency, precision) are not guaranteed. This should be considered as an
124  * error situation.
125  ******************************************************************************/
126 void sl_hfxo_manager_notify_consecutive_failed_startups(void);
127 
128 /***************************************************************************//**
129  * HFXO Manager HFXO interrupt handler.
130  *
131  * @note  This function must be called by the HFXO interrupt handler in order
132  *        to support the HFXO Manager module.
133  *        This function handles the HFXO_IF_RDY, HFXO_IF_DNSERR and
134  *        HFXO_XTALCTRL_SKIPCOREBIASOPT interrupt flags.
135  ******************************************************************************/
136 void sl_hfxo_manager_irq_handler(void);
137 
138 /** @} (end addtogroup hfxo_manager) */
139 
140 #ifdef __cplusplus
141 }
142 #endif
143 
144 #endif // SL_HFXO_MANAGER_H
145