1 //***************************************************************************** 2 // 3 //! @file am_hal_access.h 4 //! 5 //! @brief This file controls peripheral access in Apollo4. 6 //! 7 //! @addtogroup access_4p Access - Peripheral Access 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, 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_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_ACCESS_H 48 #define AM_HAL_ACCESS_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 //***************************************************************************** 56 // 57 // Global definitions 58 // 59 //***************************************************************************** 60 #define AM_HAL_ACCESS_STRUCT_SIZE 5 61 62 //***************************************************************************** 63 // 64 //! @brief Error codes. 65 // 66 //***************************************************************************** 67 typedef enum 68 { 69 AM_HAL_ACCESS_NOT_ALLOWED = AM_HAL_STATUS_MODULE_SPECIFIC_START 70 } 71 am_hal_access_error_e; 72 73 //***************************************************************************** 74 // 75 //! @brief Enumerated list of peripherals with controlled access. 76 // 77 //***************************************************************************** 78 typedef struct 79 { 80 const uint32_t *pui32Shared; 81 const uint32_t *pui32MCUAllowed; 82 const uint32_t *pui32DSP0Allowed; 83 const uint32_t *pui32DSP1Allowed; 84 uint32_t *pui32MCUClaimed; 85 uint32_t *pui32DSP0Claimed; 86 uint32_t *pui32DSP1Claimed; 87 } 88 am_hal_access_t; 89 90 //***************************************************************************** 91 // 92 //! @brief Enumerated list of peripherals with controlled access. 93 // 94 //***************************************************************************** 95 typedef enum 96 { 97 AM_HAL_ACCESS_GPIO_0, 98 AM_HAL_ACCESS_GPIO_1, 99 AM_HAL_ACCESS_GPIO_2, 100 AM_HAL_ACCESS_GPIO_3, 101 AM_HAL_ACCESS_GPIO_4, 102 AM_HAL_ACCESS_GPIO_5, 103 AM_HAL_ACCESS_GPIO_6, 104 AM_HAL_ACCESS_GPIO_7, 105 AM_HAL_ACCESS_GPIO_8, 106 AM_HAL_ACCESS_GPIO_9, 107 AM_HAL_ACCESS_GPIO_10, 108 AM_HAL_ACCESS_GPIO_11, 109 AM_HAL_ACCESS_GPIO_12, 110 AM_HAL_ACCESS_GPIO_13, 111 AM_HAL_ACCESS_GPIO_14, 112 AM_HAL_ACCESS_GPIO_15, 113 AM_HAL_ACCESS_GPIO_16, 114 AM_HAL_ACCESS_GPIO_17, 115 AM_HAL_ACCESS_GPIO_18, 116 AM_HAL_ACCESS_GPIO_19, 117 AM_HAL_ACCESS_GPIO_20, 118 AM_HAL_ACCESS_GPIO_21, 119 AM_HAL_ACCESS_GPIO_22, 120 AM_HAL_ACCESS_GPIO_23, 121 AM_HAL_ACCESS_GPIO_24, 122 AM_HAL_ACCESS_GPIO_25, 123 AM_HAL_ACCESS_GPIO_26, 124 AM_HAL_ACCESS_GPIO_27, 125 AM_HAL_ACCESS_GPIO_28, 126 AM_HAL_ACCESS_GPIO_29, 127 AM_HAL_ACCESS_GPIO_30, 128 AM_HAL_ACCESS_GPIO_31, 129 AM_HAL_ACCESS_GPIO_32, 130 AM_HAL_ACCESS_GPIO_33, 131 AM_HAL_ACCESS_GPIO_34, 132 AM_HAL_ACCESS_GPIO_35, 133 AM_HAL_ACCESS_GPIO_36, 134 AM_HAL_ACCESS_GPIO_37, 135 AM_HAL_ACCESS_GPIO_38, 136 AM_HAL_ACCESS_GPIO_39, 137 AM_HAL_ACCESS_GPIO_40, 138 AM_HAL_ACCESS_GPIO_41, 139 AM_HAL_ACCESS_GPIO_42, 140 AM_HAL_ACCESS_GPIO_43, 141 AM_HAL_ACCESS_GPIO_44, 142 AM_HAL_ACCESS_GPIO_45, 143 AM_HAL_ACCESS_GPIO_46, 144 AM_HAL_ACCESS_GPIO_47, 145 AM_HAL_ACCESS_GPIO_48, 146 AM_HAL_ACCESS_GPIO_49, 147 AM_HAL_ACCESS_GPIO_50, 148 AM_HAL_ACCESS_GPIO_51, 149 AM_HAL_ACCESS_GPIO_52, 150 AM_HAL_ACCESS_GPIO_53, 151 AM_HAL_ACCESS_GPIO_54, 152 AM_HAL_ACCESS_GPIO_55, 153 AM_HAL_ACCESS_GPIO_56, 154 AM_HAL_ACCESS_GPIO_57, 155 AM_HAL_ACCESS_GPIO_58, 156 AM_HAL_ACCESS_GPIO_59, 157 AM_HAL_ACCESS_GPIO_60, 158 AM_HAL_ACCESS_GPIO_61, 159 AM_HAL_ACCESS_GPIO_62, 160 AM_HAL_ACCESS_GPIO_63, 161 } 162 am_hal_access_periph_e; 163 164 #define AM_HAL_ACCESS_GPIO_BASE AM_HAL_ACCESS_GPIO_0 165 166 //***************************************************************************** 167 // 168 // External functions. 169 // 170 //***************************************************************************** 171 172 //***************************************************************************** 173 // 174 //! @brief Initialize the central access structure. 175 //! 176 //! @param pvHandle is the handle for this structure. 177 //! 178 //! This initializes a local set of pointers to the global peripheral access 179 //! structure. 180 //! 181 //! @return Status code. 182 // 183 //***************************************************************************** 184 extern uint32_t am_hal_access_initialize(void **pvHandle); 185 186 //***************************************************************************** 187 // 188 //! @brief De-initialize the central access structure. 189 //! 190 //! @param pvHandle is the handle for this structure. 191 //! 192 //! This function de-initializes the local set of pointers for the global 193 //! peripheral access structure. 194 //! 195 //! @return Status code. 196 // 197 //***************************************************************************** 198 extern uint32_t am_hal_access_deinitialize(void *pvHandle); 199 200 //***************************************************************************** 201 // 202 //! @brief De-initialize the central access structure. 203 //! 204 //! @param pvHandle is the handle for this access structure. 205 //! @param psGlobalAccess is the structure describing access permissions. 206 //! 207 //! This function sets up a series of pointers that the HAL can use to check 208 //! and aquire permission to access specific peripherals. 209 //! 210 //! @return Status code. 211 // 212 //***************************************************************************** 213 extern uint32_t am_hal_access_config(void *pvHandle, 214 am_hal_access_t *psGlobalAccess); 215 216 //***************************************************************************** 217 // 218 //! @brief Obtain access to a peripheral 219 //! 220 //! @param pvHandle is the handle for this access structure. 221 //! @param ePeripheral is the peripheral to obtain access for. 222 //! @param ui32TimeoutUS timeout in microseconds 223 //! 224 //! This function attempts to gain access to a particular peripheral. It 225 //! ensures that no other caller can successfully make the same request until 226 //! control is released. 227 //! 228 //! @return Status code. 229 // 230 //***************************************************************************** 231 extern uint32_t am_hal_access_get(void *pvHandle, 232 am_hal_access_periph_e ePeripheral, 233 uint32_t ui32TimeoutUS); 234 235 //***************************************************************************** 236 // 237 //! @brief Release control of a peripheral. 238 //! 239 //! @param pvHandle is the handle for this access structure. 240 //! @param ePeripheral is the peripheral to obtain access for. 241 //! @param ui32TimeoutUS timeout in microseconds 242 //! 243 //! This function releases control of a peripheral, allowing it to be used by 244 //! other callers. 245 //! 246 //! @return Status code. 247 // 248 //***************************************************************************** 249 extern uint32_t am_hal_access_release(void *pvHandle, 250 am_hal_access_periph_e ePeripheral, 251 uint32_t ui32TimeoutUS); 252 253 #ifdef __cplusplus 254 } 255 #endif 256 257 #endif // AM_HAL_ACCESS_H 258 259 //***************************************************************************** 260 // 261 // End Doxygen group. 262 //! @} 263 // 264 //***************************************************************************** 265 266
