1 /***************************************************************************//**
2  * @file
3  * @brief System API (Generic)
4  *******************************************************************************
5  * # License
6  * <b>Copyright 2024 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 #ifndef _SL_HAL_SYSTEM_GENERIC_H
32 #define _SL_HAL_SYSTEM_GENERIC_H
33 
34 #include "sl_enum.h"
35 #include <stdint.h>
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 /***************************************************************************//**
42  * @addtogroup system SYSTEM - System Utils
43  * @{
44  ******************************************************************************/
45 
46 /*******************************************************************************
47  ********************************   ENUMS   ************************************
48  ******************************************************************************/
49 
50 /// Family security capability.
SL_ENUM(sl_hal_system_security_capability_t)51 SL_ENUM(sl_hal_system_security_capability_t) {
52   /// Unknown security capability.
53   SL_SYSTEM_SECURITY_CAPABILITY_UNKNOWN,
54   /// Security capability not applicable.
55   SL_SYSTEM_SECURITY_CAPABILITY_NA,
56   /// Basic security capability.
57   SL_SYSTEM_SECURITY_CAPABILITY_BASIC,
58   /// Root of Trust security capability.
59   SL_SYSTEM_SECURITY_CAPABILITY_ROT,
60   /// Secure Element security capability.
61   SL_SYSTEM_SECURITY_CAPABILITY_SE,
62   /// Secure Vault security capability.
63   SL_SYSTEM_SECURITY_CAPABILITY_VAULT
64 };
65 
66 /// Floating point co-processor access modes.
SL_ENUM_GENERIC(sl_hal_system_fpu_access_t,uint32_t)67 SL_ENUM_GENERIC(sl_hal_system_fpu_access_t, uint32_t) {
68   /// Access denied, any attempted access generates a NOCP UsageFault.
69   SL_SYSTEM_FPU_ACCESS_DENIED          = (0x0 << 20),
70   /// Privileged access only, an unprivileged access generates a NOCP UsageFault.
71   SL_SYSTEM_FPU_ACCESS_PRIVILEGED_ONLY = (0x5 << 20),
72   /// Reserved.
73   SL_SYSTEM_FPU_ACCESS_RESERVED        = (0xA << 20),
74   /// Full access.
75   SL_SYSTEM_FPU_ACCESS_FULL            = (0xF << 20)
76 };
77 
78 /*******************************************************************************
79  *******************************   STRUCTS   ***********************************
80  ******************************************************************************/
81 
82 /// Chip revision details.
83 typedef struct {
84   uint8_t minor;        ///< Minor revision number.
85   uint8_t major;        ///< Major revision number.
86   uint16_t part_number; ///< Device part number. (0xFFFF if unavailable)
87   uint16_t family;      ///< Device family number. (0xFFFF if unavailable)
88 } sl_hal_system_chip_revision_t;
89 
90 /// ADC Calibration DEVINFO Structures.
91 typedef struct sl_hal_system_devinfo_adc_cal_data_t {
92   uint8_t trim_vros0;
93   uint8_t trim_vros1;
94   uint8_t trim_gain_4x;
95   uint8_t trim_gain_0x3_int;
96 } sl_hal_system_devinfo_adc_cal_data_t;
97 
98 typedef struct sl_hal_system_devinfo_adc_offset_t {
99   uint8_t trim_off_1x;
100   uint8_t trim_off_2x;
101   uint8_t trim_off_4x;
102   uint8_t dummy_byte;
103 } sl_hal_system_devinfo_adc_offset_t;
104 
105 typedef struct sl_hal_system_devinfo_adc_t {
106   sl_hal_system_devinfo_adc_cal_data_t cal_data;
107   sl_hal_system_devinfo_adc_offset_t   offset;
108 } sl_hal_system_devinfo_adc_t;
109 
110 /// Temperature DEVINFO Structure.
111 typedef struct sl_hal_system_devinfo_temperature_t {
112   uint16_t emu_temp_room;
113   uint16_t cal_temp;
114 } sl_hal_system_devinfo_temperature_t;
115 
116 /// Chip features Structure.
117 typedef struct sl_hal_system_features {
118   char feature1;
119   char feature2;
120   char feature3;
121 } sl_hal_system_features_t;
122 
123 /*******************************************************************************
124  **************************   GLOBAL CONSTANTS   *******************************
125  ******************************************************************************/
126 
127 extern const sl_hal_system_devinfo_adc_t SL_HAL_SYSTEM_DEVINFO_ADC_RESET_VALUES;
128 
129 extern const sl_hal_system_devinfo_temperature_t SL_HAL_SYSTEM_DEVINFO_TEMPERATURE_RESET_VALUES;
130 
131 /*******************************************************************************
132  *****************************   PROTOTYPES   **********************************
133  ******************************************************************************/
134 
135 /*******************************************************************************
136  * @brief
137  *   Get the chip revision.
138  *
139  * @param [out]
140  *   rev Pointer to return the chip revision to.
141  *
142  * @warning
143  *   The chip revision structure may be returned with either the partnumber or
144  *   family unpopulated (0xFFFF) depending on the device.
145  ******************************************************************************/
146 void sl_hal_system_get_chip_revision(sl_hal_system_chip_revision_t *rev);
147 
148 /***************************************************************************//**
149  * @brief
150  *   Get DEVINFO revision.
151  *
152  * @return
153  *   Revision of the DEVINFO contents.
154  ******************************************************************************/
155 uint8_t sl_hal_system_get_devinfo_rev(void);
156 
157 /***************************************************************************//**
158  * @brief
159  *    Get the default factory calibration value for HFRCO oscillator.
160  *
161  * @return
162  *    HFRCOCAL default value.
163  ******************************************************************************/
164 uint32_t sl_hal_system_get_hfrco_default_calibration(void);
165 
166 /***************************************************************************//**
167  * @brief
168  *    Get the speed factory calibration value for HFRCO oscillator.
169  *
170  * @return
171  *    HFRCOCAL speed value.
172  ******************************************************************************/
173 uint32_t sl_hal_system_get_hfrco_speed_calibration(void);
174 
175 /***************************************************************************//**
176  * @brief Get the HFRCO calibration based on the frequency band.
177  *
178  * @param[in] frequency
179  *    Frequency for which to retrieve calibration.
180  *
181  * @return
182  *    HFRCOCAL value for the given band.
183  *
184  * @note
185  *    Those calibrations are only valid for the HFRCO oscillator when used with
186  *    the DPLL module.
187  ******************************************************************************/
188 uint32_t sl_hal_system_get_hfrcodpll_band_calibration(uint32_t frequency);
189 
190 /***************************************************************************//**
191  * @brief
192  *    Get a factory calibration value for HFRCOCEM23 oscillator.
193  *
194  * @return
195  *    HFRCOEM23 calibration value.
196  ******************************************************************************/
197 uint32_t sl_hal_system_get_hfrcoem23_calibration(void);
198 
199 /***************************************************************************//**
200  * @brief
201  *    Get a factory calibration value for HFXOCAL.
202  *
203  * @return
204  *    HFXOCAL value.
205  ******************************************************************************/
206 uint32_t sl_hal_system_get_hfxocal(void);
207 
208 /***************************************************************************//**
209  * @brief
210  *   Get family security capability.
211  *
212  * @note
213  *   This function retrieves the family security capability based on the
214  *   device number.
215  *
216  * @return
217  *   Security capability of MCU.
218  ******************************************************************************/
219 sl_hal_system_security_capability_t sl_hal_system_get_security_capability(void);
220 
221 /***************************************************************************//**
222  * @brief
223  *   Get the unique number for this device.
224  *
225  * @return
226  *   Unique number for this device.
227  ******************************************************************************/
228 uint64_t sl_hal_system_get_unique(void);
229 
230 /***************************************************************************//**
231  * @brief
232  *   Get the production revision for this part.
233  *
234  * @return
235  *   Production revision for this part.
236  ******************************************************************************/
237 uint8_t sl_hal_system_get_prod_rev(void);
238 
239 /***************************************************************************//**
240  * @brief
241  *   Get the SRAM Base Address.
242  *
243  * @return
244  *   Base address SRAM (32-bit unsigned integer).
245  ******************************************************************************/
246 uint32_t sl_hal_system_get_sram_base_address(void);
247 
248 /***************************************************************************//**
249  * @brief
250  *   Get the SRAM size (in KB).
251  *
252  * @note
253  *   This function retrieves SRAM size by reading the chip device
254  *   info structure. If your binary is made for one specific device only,
255  *   use SRAM_SIZE instead.
256  *
257  * @return
258  *   Size of internal SRAM (in KB).
259  ******************************************************************************/
260 uint16_t sl_hal_system_get_sram_size(void);
261 
262 /***************************************************************************//**
263  * @brief
264  *   Get the flash size (in KB).
265  *
266  * @note
267  *   This function retrieves flash size by reading the chip device info structure or
268  *   DEVINFO->EMBMSIZE (embedded flash. not the case for S3 for now) or
269  *   user config (external flash).
270  *
271  * @return
272  *   Size of flash (in KB).
273  ******************************************************************************/
274 uint16_t sl_hal_system_get_flash_size(void);
275 
276 /***************************************************************************//**
277  * @brief
278  *   Get the flash page size in bytes.
279  *
280  * @note
281  *   This function retrieves flash page size by reading the SE or
282  *   user config (external flash)
283  *
284  * @return
285  *   Page size of flash in bytes.
286  ******************************************************************************/
287 uint32_t sl_hal_system_get_flash_page_size(void);
288 
289 /***************************************************************************//**
290  * @brief
291  *   Get the MCU part number.
292  *
293  * @return
294  *   The part number of MCU.
295  ******************************************************************************/
296 uint16_t sl_hal_system_get_part_number(void);
297 
298 /***************************************************************************//**
299  * @brief
300  *   Get the SoC or MCU features.
301  *
302  * @return
303  *   The features of the current SoC or MCU.
304  *
305  * @note The features can be decoded by referring to the SoC or MCU datasheet.
306  ******************************************************************************/
307 sl_hal_system_features_t sl_hal_system_get_part_features(void);
308 
309 /***************************************************************************//**
310  * @brief
311  *   Get the temperature information.
312  *
313  * @param[out] info
314  *   Pointer to variable where to store the temperature info.
315  ******************************************************************************/
316 void sl_hal_system_get_temperature_info(sl_hal_system_devinfo_temperature_t *info);
317 
318 /***************************************************************************//**
319  * @brief
320  *   Set floating point co-processor (FPU) access mode.
321  *
322  * @param[in] accessMode
323  *   Floating point co-processor access mode.
324  ******************************************************************************/
325 void sl_hal_system_fpu_set_access_mode(sl_hal_system_fpu_access_t access_mode);
326 
327 /***************************************************************************//**
328  * @brief Get the ADC calibration info.
329  *
330  * @param[out] info
331  *   Pointer to variable where to store the adc calibration info.
332  ******************************************************************************/
333 void sl_hal_system_get_adc_calibration_info(sl_hal_system_devinfo_adc_t *info);
334 
335 /** @} (end addtogroup system) */
336 
337 #ifdef __cplusplus
338 }
339 #endif
340 
341 #endif /* #ifndef _SL_HAL_SYSTEM_GENERIC_H */
342