1 //***************************************************************************** 2 // 3 //! @file am_hal_security.h 4 //! 5 //! @brief Functions for on-chip security features 6 //! 7 //! @addtogroup security Security - On-Chip Security Functionality 8 //! @ingroup apollo3_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_SECURITY_H 49 #define AM_HAL_SECURITY_H 50 51 // 52 //! @brief Location of SBL install address for this device 53 //! 54 //! @note Important Note: 55 //! Some caution should be observed when using AM_HAL_SBL_ADDRESS as an address. 56 //! GCC considers use of this address to be a NULL pointer. When compiled with 57 //! high optimization (-O3) and used to read the location with, for example, 58 //! code such as *((volatile uint32_t *)(AM_HAL_SBL_ADDRESS)), GCC will insert 59 //! an instruction it calls "UDF" (undefined), op-code 0xDEFF, which will cause 60 //! a fault on execution to trap the "invalid" null-ptr usage. 61 //! This does not appear to be an issue with IAR and Keil ARM5. 62 //! It is likely an issue with Keil ARM6. 63 // 64 #define AM_HAL_SBL_ADDRESS 0x00000000 65 66 typedef struct 67 { 68 bool bInfo0Valid; 69 uint32_t info0Version; 70 uint32_t sblVersion; 71 uint32_t sblVersionAddInfo; 72 } am_hal_security_info_t; 73 74 //! LOCK Definitions 75 typedef enum 76 { 77 AM_HAL_SECURITY_LOCKTYPE_CUSTOMER = 0x1, 78 AM_HAL_SECURITY_LOCKTYPE_RECOVERY = 0x9D, 79 } am_hal_security_locktype_t; 80 81 typedef union 82 { 83 uint32_t keyword[4]; 84 struct 85 { 86 uint32_t key0; 87 uint32_t key1; 88 uint32_t key2; 89 uint32_t key3; 90 } keys; 91 } am_hal_security_128bkey_t; 92 93 #ifdef __cplusplus 94 extern "C" 95 { 96 #endif 97 98 //***************************************************************************** 99 // 100 //! @brief Get Device Security Info 101 //! 102 //! @param pSecInfo - Pointer to structure for returned security info 103 //! 104 //! This will retrieve the security information for the device 105 //! 106 //! @return Returns AM_HAL_STATUS_SUCCESS on success 107 // 108 //***************************************************************************** 109 uint32_t am_hal_security_get_info(am_hal_security_info_t *pSecInfo); 110 111 //***************************************************************************** 112 // 113 //! @brief Set the key for specified lock 114 //! 115 //! @param lockType - The lock type to be operated upon 116 //! @param pKey - Pointer to 128b key value 117 //! 118 //! This will program the lock registers for the specified lock and key 119 //! 120 //! @return Returns AM_HAL_STATUS_SUCCESS on success 121 // 122 //***************************************************************************** 123 uint32_t am_hal_security_set_key(am_hal_security_locktype_t lockType, am_hal_security_128bkey_t *pKey); 124 125 //***************************************************************************** 126 // 127 //! @brief Get the current status of the specified lock 128 //! 129 //! @param lockType - The lock type to be operated upon 130 //! @param pbUnlockStatus - Pointer to return variable with lock status 131 //! 132 //! This will get the lock status for specified lock 133 //! Note that except for customer lock, other locks are self-locking on status read 134 //! 135 //! @return Returns AM_HAL_STATUS_SUCCESS on success 136 // 137 //***************************************************************************** 138 uint32_t am_hal_security_get_lock_status(am_hal_security_locktype_t lockType, bool *pbUnlockStatus); 139 140 //***************************************************************************** 141 // 142 //! @brief Initialize CRC32 engine 143 //! 144 //! This will initialize the hardware engine to compute CRC32 on an arbitrary data payload 145 //! 146 //! @return Returns AM_HAL_STATUS_SUCCESS on success 147 // 148 //***************************************************************************** 149 uint32_t am_hal_crc32_init(void); 150 151 //***************************************************************************** 152 // 153 //! @brief Accumulate CRC32 for a specified payload 154 //! 155 //! @param ui32StartAddr - The start address of the payload 156 //! @param ui32SizeBytes - The length of payload in bytes 157 //! @param pui32Crc - Pointer to accumulated CRC 158 //! 159 //! This will use the hardware engine to compute CRC32 on an arbitrary data payload 160 //! 161 //! @return Returns AM_HAL_STATUS_SUCCESS on success 162 // 163 //***************************************************************************** 164 uint32_t am_hal_crc32_accum(uint32_t ui32StartAddr, uint32_t ui32SizeBytes, uint32_t *pui32Crc) ; 165 166 //***************************************************************************** 167 // 168 //! @brief Compute CRC32 for a specified payload 169 //! 170 //! @param ui32StartAddr - The start address of the payload 171 //! @param ui32SizeBytes - The length of payload in bytes 172 //! @param pui32Crc - Pointer to return computed CRC 173 //! 174 //! This will use the hardware engine to compute CRC32 on an arbitrary data payload 175 //! 176 //! @return Returns AM_HAL_STATUS_SUCCESS on success 177 // 178 //***************************************************************************** 179 uint32_t am_hal_crc32(uint32_t ui32StartAddr, uint32_t ui32SizeBytes, uint32_t *pui32Crc) ; 180 181 //***************************************************************************** 182 // 183 //! @brief Helper function to Perform exit operations for a secondary bootloader 184 //! 185 //! @param pImage - The address of the image to give control to 186 //! 187 //! This function does the necessary security operations while exiting from a 188 //! a secondary bootloader program. If still open, it locks the info0 key region, 189 //! as well as further updates to the flash protection register. 190 //! It also checks if it needs to halt to honor a debugger request. 191 //! If an image address is specified, control is transferred to the same on exit. 192 //! 193 //! @return Returns AM_HAL_STATUS_SUCCESS on success, if no image address specified 194 //! If an image address is provided, a successful execution results in transfer to 195 //! the image - and this function does not return. 196 // 197 //***************************************************************************** 198 uint32_t am_hal_bootloader_exit(uint32_t *pImage); 199 200 #ifdef __cplusplus 201 } 202 #endif 203 204 #endif // AM_HAL_SECURITY_H 205 //***************************************************************************** 206 // 207 // End Doxygen group. 208 //! @} 209 // 210 //***************************************************************************** 211
