1 //***************************************************************************** 2 // 3 // am_hal_ios.h 4 //! @file 5 //! 6 //! @brief Functions for interfacing with the IO Slave module 7 //! 8 //! @addtogroup ios2 IO Slave (SPI/I2C) 9 //! @ingroup apollo2hal 10 //! @{ 11 // 12 //***************************************************************************** 13 14 //***************************************************************************** 15 // 16 // Copyright (c) 2017, Ambiq Micro 17 // All rights reserved. 18 // 19 // Redistribution and use in source and binary forms, with or without 20 // modification, are permitted provided that the following conditions are met: 21 // 22 // 1. Redistributions of source code must retain the above copyright notice, 23 // this list of conditions and the following disclaimer. 24 // 25 // 2. Redistributions in binary form must reproduce the above copyright 26 // notice, this list of conditions and the following disclaimer in the 27 // documentation and/or other materials provided with the distribution. 28 // 29 // 3. Neither the name of the copyright holder nor the names of its 30 // contributors may be used to endorse or promote products derived from this 31 // software without specific prior written permission. 32 // 33 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 34 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 35 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 36 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 37 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 38 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 39 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 40 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 41 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 42 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 43 // POSSIBILITY OF SUCH DAMAGE. 44 // 45 // This is part of revision 1.2.11 of the AmbiqSuite Development Package. 46 // 47 //***************************************************************************** 48 #ifndef AM_HAL_IOS_H 49 #define AM_HAL_IOS_H 50 51 52 //***************************************************************************** 53 // 54 //! @name Interface Configuration 55 //! @brief Macro definitions for configuring the physical interface of the IO 56 //! Slave 57 //! 58 //! These macros may be used with the am_hal_ios_config_t structure to set the 59 //! physical parameters of the SPI/I2C slave module. 60 //! 61 //! @{ 62 // 63 //***************************************************************************** 64 #define AM_HAL_IOS_USE_SPI AM_REG_IOSLAVE_CFG_IFCSEL_SPI 65 #define AM_HAL_IOS_SPIMODE_0 AM_REG_IOSLAVE_CFG_SPOL_SPI_MODES_0_3 66 #define AM_HAL_IOS_SPIMODE_1 AM_REG_IOSLAVE_CFG_SPOL_SPI_MODES_1_2 67 #define AM_HAL_IOS_SPIMODE_2 AM_REG_IOSLAVE_CFG_SPOL_SPI_MODES_1_2 68 #define AM_HAL_IOS_SPIMODE_3 AM_REG_IOSLAVE_CFG_SPOL_SPI_MODES_0_3 69 70 #define AM_HAL_IOS_USE_I2C AM_REG_IOSLAVE_CFG_IFCSEL_I2C 71 #define AM_HAL_IOS_I2C_ADDRESS(n) AM_REG_IOSLAVE_CFG_I2CADDR(n) 72 73 #define AM_HAL_IOS_LSB_FIRST AM_REG_IOSLAVE_CFG_LSB(1) 74 //! @} 75 76 //***************************************************************************** 77 // 78 //! @name Register Access Interrupts 79 //! @brief Macro definitions for register access interrupts. 80 //! 81 //! These macros may be used with any of the 82 //! 83 //! @{ 84 // 85 //***************************************************************************** 86 #define AM_HAL_IOS_ACCESS_INT_00 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 31) 87 #define AM_HAL_IOS_ACCESS_INT_01 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 30) 88 #define AM_HAL_IOS_ACCESS_INT_02 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 29) 89 #define AM_HAL_IOS_ACCESS_INT_03 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 28) 90 #define AM_HAL_IOS_ACCESS_INT_04 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 27) 91 #define AM_HAL_IOS_ACCESS_INT_05 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 26) 92 #define AM_HAL_IOS_ACCESS_INT_06 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 25) 93 #define AM_HAL_IOS_ACCESS_INT_07 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 24) 94 #define AM_HAL_IOS_ACCESS_INT_08 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 23) 95 #define AM_HAL_IOS_ACCESS_INT_09 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 22) 96 #define AM_HAL_IOS_ACCESS_INT_0A AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 21) 97 #define AM_HAL_IOS_ACCESS_INT_0B AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 20) 98 #define AM_HAL_IOS_ACCESS_INT_0C AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 19) 99 #define AM_HAL_IOS_ACCESS_INT_0D AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 18) 100 #define AM_HAL_IOS_ACCESS_INT_0E AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 17) 101 #define AM_HAL_IOS_ACCESS_INT_0F AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 16) 102 #define AM_HAL_IOS_ACCESS_INT_13 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 15) 103 #define AM_HAL_IOS_ACCESS_INT_17 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 14) 104 #define AM_HAL_IOS_ACCESS_INT_1B AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 13) 105 #define AM_HAL_IOS_ACCESS_INT_1F AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 12) 106 #define AM_HAL_IOS_ACCESS_INT_23 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 11) 107 #define AM_HAL_IOS_ACCESS_INT_27 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 10) 108 #define AM_HAL_IOS_ACCESS_INT_2B AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 9) 109 #define AM_HAL_IOS_ACCESS_INT_2F AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 8) 110 #define AM_HAL_IOS_ACCESS_INT_33 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 7) 111 #define AM_HAL_IOS_ACCESS_INT_37 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 6) 112 #define AM_HAL_IOS_ACCESS_INT_3B AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 5) 113 #define AM_HAL_IOS_ACCESS_INT_3F AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 4) 114 #define AM_HAL_IOS_ACCESS_INT_43 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 3) 115 #define AM_HAL_IOS_ACCESS_INT_47 AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 2) 116 #define AM_HAL_IOS_ACCESS_INT_4B AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 1) 117 #define AM_HAL_IOS_ACCESS_INT_4F AM_REG_IOSLAVE_REGACCINTEN_REGACC((uint32_t)1 << 0) 118 #define AM_HAL_IOS_ACCESS_INT_ALL 0xFFFFFFFF 119 //! @} 120 121 //***************************************************************************** 122 // 123 //! @name I/O Slave Interrupts 124 //! @brief Macro definitions for I/O slave (IOS) interrupts. 125 //! 126 //! These macros may be used with any of the 127 //! 128 //! @{ 129 // 130 //***************************************************************************** 131 #define AM_HAL_IOS_INT_FSIZE AM_REG_IOSLAVE_INTEN_FSIZE_M 132 #define AM_HAL_IOS_INT_FOVFL AM_REG_IOSLAVE_INTEN_FOVFL_M 133 #define AM_HAL_IOS_INT_FUNDFL AM_REG_IOSLAVE_INTEN_FUNDFL_M 134 #define AM_HAL_IOS_INT_FRDERR AM_REG_IOSLAVE_INTEN_FRDERR_M 135 #define AM_HAL_IOS_INT_GENAD AM_REG_IOSLAVE_INTEN_GENAD_M 136 #define AM_HAL_IOS_INT_IOINTW AM_REG_IOSLAVE_INTEN_IOINTW_M 137 #define AM_HAL_IOS_INT_XCMPWR AM_REG_IOSLAVE_INTEN_XCMPWR_M 138 #define AM_HAL_IOS_INT_XCMPWF AM_REG_IOSLAVE_INTEN_XCMPWF_M 139 #define AM_HAL_IOS_INT_XCMPRR AM_REG_IOSLAVE_INTEN_XCMPRR_M 140 #define AM_HAL_IOS_INT_XCMPRF AM_REG_IOSLAVE_INTEN_XCMPRF_M 141 #define AM_HAL_IOS_INT_ALL 0xFFFFFFFF 142 //! @} 143 144 //***************************************************************************** 145 // 146 //! @name I/O Slave Interrupts triggers 147 //! @brief Macro definitions for I/O slave (IOS) interrupts. 148 //! 149 //! These macros may be used with am_hal_ios_int_set and am_hal_ios_int_clear 150 //! 151 //! @{ 152 // 153 //***************************************************************************** 154 #define AM_HAL_IOS_IOINTCTL_INT0 (0x01) 155 #define AM_HAL_IOS_IOINTCTL_INT1 (0x02) 156 #define AM_HAL_IOS_IOINTCTL_INT2 (0x04) 157 #define AM_HAL_IOS_IOINTCTL_INT3 (0x08) 158 #define AM_HAL_IOS_IOINTCTL_INT4 (0x10) 159 #define AM_HAL_IOS_IOINTCTL_INT5 (0x20) 160 //! @} 161 162 //***************************************************************************** 163 // 164 // External variable definitions 165 // 166 //***************************************************************************** 167 168 //***************************************************************************** 169 // 170 //! @brief LRAM pointer 171 //! 172 //! Pointer to the base of the IO Slave LRAM. 173 // 174 //***************************************************************************** 175 extern volatile uint8_t * const am_hal_ios_pui8LRAM; 176 177 //***************************************************************************** 178 // 179 //! @brief Configuration structure for the IO slave module. 180 //! 181 //! This structure may be used along with the am_hal_ios_config() function to 182 //! select key parameters of the IO Slave module. See the descriptions of each 183 //! parameter within this structure for more information on what they control. 184 // 185 //***************************************************************************** 186 typedef struct 187 { 188 // 189 //! Interface Selection 190 //! 191 //! This word selects the physical behavior of the IO Slave port. For SPI 192 //! mode, this word should be the logical OR of one or more of the 193 //! following: 194 //! 195 //! AM_HAL_IOS_USE_SPI 196 //! AM_HAL_IOS_SPIMODE_0 197 //! AM_HAL_IOS_SPIMODE_1 198 //! AM_HAL_IOS_SPIMODE_2 199 //! AM_HAL_IOS_SPIMODE_3 200 //! 201 //! For I2C mode, use the logical OR of one or more of these values instead 202 //! (where n is the 7 or 10-bit I2C address to use): 203 //! 204 //! AM_HAL_IOS_USE_I2C 205 //! AM_HAL_IOS_I2C_ADDRESS(n) 206 //! 207 //! Also, in any mode, you may OR in this value to reverse the order of 208 //! incoming data bits. 209 //! 210 //! AM_HAL_IOS_LSB_FIRST 211 // 212 uint32_t ui32InterfaceSelect; 213 214 // 215 //! Read-Only section 216 //! 217 //! The IO Slave LRAM is split into three main sections. The first section 218 //! is a "Direct Write" section, which may be accessed for reads or write 219 //! either directly through the Apollo CPU, or over the SPI/I2C bus. The 220 //! "Direct Write" section always begins at LRAM offset 0x0. At the end of 221 //! the normal "Direct Write" space, there is a "Read Only" space, which is 222 //! read/write accessible to the Apollo CPU, but read-only over the I2C/SPI 223 //! Bus. This word selects the base address of this "Read Only" space. 224 //! 225 //! This value may be set to any multiple of 8 between 0x0 and 0x78, 226 //! inclusive. For the configuration to be valid, \e ui32ROBase must also 227 //! be less than or equal to \e ui32FIFOBase 228 //! 229 //! @note The address given here is in units of BYTES. Since the location 230 //! of the "Read Only" space may only be set in 8-byte increments, this 231 //! value must be a multiple of 8. 232 //! 233 //! For the avoidance of doubt this means 0x80 is 128 bytes. These functions 234 //! will shift right by 8 internally. 235 // 236 uint32_t ui32ROBase; 237 238 // 239 //! FIFO section 240 //! 241 //! After the "Direct Access" and "Read Only" sections is a section of LRAM 242 //! allocated to a FIFO. This section is accessible by the Apollo CPU 243 //! through the FIFO control registers, and accessible on the SPI/I2C bus 244 //! through the 0x7F address. This word selects the base address of the 245 //! FIFO space. The FIFO will extend from the address specified here to the 246 //! address specified in \e ui32RAMBase. 247 //! 248 //! This value may be set to any multiple of 8 between 0x0 and 0x78, 249 //! inclusive. For the configuration to be valid, \e ui32FIFOBase must also 250 //! be greater than or equal to \e ui32ROBase. 251 //! 252 //! @note The address given here is in units of BYTES. Since the location 253 //! of the "FIFO" space may only be set in 8-byte increments, this value 254 //! must be a multiple of 8. 255 //! 256 //! For the avoidance of doubt this means 0x80 is 128 bytes. These functions 257 //! will shift right by 8 internally. 258 // 259 uint32_t ui32FIFOBase; 260 261 // 262 //! RAM section 263 //! 264 //! At the end of the IOS LRAM, the user may allocate a "RAM" space that 265 //! can only be accessed by the Apollo CPU. This space will not interact 266 //! with the SPI/I2C bus at all, and may be used as general-purpose memory. 267 //! Unlike normal SRAM, this section of LRAM will retain its state through 268 //! Deep Sleep, so it may be used as a data retention space for 269 //! ultra-low-power applications. 270 //! 271 //! This value may be set to any multiple of 8 between 0x0 and 0x100, 272 //! inclusive. For the configuration to be valid, \e ui32RAMBase must also 273 //! be greater than or equal to \e ui32FIFOBase. 274 //! 275 //! @note The address given here is in units of BYTES. Since the location 276 //! of the "FIFO" space may only be set in 8-byte increments, this value 277 //! must be a multiple of 8. 278 //! 279 //! For the avoidance of doubt this means 0x80 is 128 bytes. These functions 280 //! will shift right by 8 internally. 281 // 282 uint32_t ui32RAMBase; 283 284 // 285 //! FIFO threshold 286 //! 287 //! The IO Slave module will trigger an interrupt when the number of 288 //! entries in the FIFO drops below this number of bytes. 289 // 290 uint32_t ui32FIFOThreshold; 291 292 // 293 // Pointer to an SRAM 294 // 295 uint8_t *pui8SRAMBuffer; 296 } 297 am_hal_ios_config_t; 298 299 #ifdef __cplusplus 300 extern "C" 301 { 302 #endif 303 //***************************************************************************** 304 // 305 // External function definitions 306 // 307 //***************************************************************************** 308 extern void am_hal_ios_enable(uint32_t ui32Module); 309 extern void am_hal_ios_disable(uint32_t ui32Module); 310 311 // these interrupts drive the HOST side IOS interrupt pins 312 extern void am_hal_ios_host_int_set(uint32_t ui32Interrupt); 313 extern void am_hal_ios_host_int_clear(uint32_t ui32Interrupt); 314 extern uint32_t am_hal_ios_host_int_get(void); 315 extern uint32_t am_hal_ios_host_int_enable_get(void); 316 317 extern void am_hal_ios_lram_write(uint32_t ui32Offset, uint8_t ui8Value); 318 extern uint8_t am_hal_ios_lram_read(uint32_t ui32Offset); 319 320 // the following interrupts go back to the NVIC 321 extern void am_hal_ios_config(am_hal_ios_config_t *psConfig); 322 extern void am_hal_ios_access_int_enable(uint32_t ui32Interrupt); 323 extern uint32_t am_hal_ios_access_int_enable_get(void); 324 extern void am_hal_ios_access_int_disable(uint32_t ui32Interrupt); 325 extern void am_hal_ios_access_int_clear(uint32_t ui32Interrupt); 326 extern void am_hal_ios_access_int_set(uint32_t ui32Interrupt); 327 extern uint32_t am_hal_ios_access_int_status_get(bool bEnabledOnly); 328 extern void am_hal_ios_int_enable(uint32_t ui32Interrupt); 329 extern uint32_t am_hal_ios_int_enable_get(void); 330 extern void am_hal_ios_int_disable(uint32_t ui32Interrupt); 331 extern void am_hal_ios_int_clear(uint32_t ui32Interrupt); 332 extern void am_hal_ios_int_set(uint32_t ui32Interrupt); 333 extern uint32_t am_hal_ios_int_status_get(bool bEnabledOnly); 334 335 extern void am_hal_ios_fifo_buffer_init(uint8_t *pui8Buffer, uint32_t ui32NumBytes); 336 extern uint32_t am_hal_ios_fifo_space_left(void); 337 extern uint32_t am_hal_ios_fifo_space_used(void); 338 extern void am_hal_ios_fifo_service(uint32_t ui32Status); 339 // Returns the number of bytes actually written 340 extern uint32_t am_hal_ios_fifo_write(uint8_t *pui8Data, uint32_t ui32NumBytes); 341 extern void am_hal_ios_fifo_write_simple(uint8_t *pui8Data, 342 uint32_t ui32NumBytes); 343 extern void am_hal_ios_fifo_ptr_set(uint32_t ui32Offset); 344 extern void am_hal_ios_update_fifoctr(void); 345 346 extern void am_hal_ios_read_poll_complete(void); 347 extern void am_hal_ios_pwrctrl_enable(void); 348 extern void am_hal_ios_pwrctrl_disable(void); 349 350 351 #ifdef __cplusplus 352 } 353 #endif 354 355 #endif // AM_HAL_IOS_H 356 357 //***************************************************************************** 358 // 359 // End Doxygen group. 360 //! @} 361 // 362 //***************************************************************************** 363