[76386c1] | 1 | /****************************************************************************** |
---|
| 2 | * |
---|
| 3 | * Copyright 2013 Altera Corporation. All Rights Reserved. |
---|
| 4 | * |
---|
| 5 | * Redistribution and use in source and binary forms, with or without |
---|
| 6 | * modification, are permitted provided that the following conditions are met: |
---|
| 7 | * |
---|
| 8 | * 1. Redistributions of source code must retain the above copyright notice, |
---|
| 9 | * this list of conditions and the following disclaimer. |
---|
| 10 | * |
---|
| 11 | * 2. Redistributions in binary form must reproduce the above copyright notice, |
---|
| 12 | * this list of conditions and the following disclaimer in the documentation |
---|
| 13 | * and/or other materials provided with the distribution. |
---|
| 14 | * |
---|
| 15 | * 3. The name of the author may not be used to endorse or promote products |
---|
| 16 | * derived from this software without specific prior written permission. |
---|
| 17 | * |
---|
| 18 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR |
---|
| 19 | * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
---|
| 20 | * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO |
---|
| 21 | * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
---|
| 22 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT |
---|
| 23 | * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
---|
| 24 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
---|
| 25 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING |
---|
| 26 | * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY |
---|
| 27 | * OF SUCH DAMAGE. |
---|
| 28 | * |
---|
| 29 | ******************************************************************************/ |
---|
| 30 | |
---|
| 31 | /****************************************************************************** |
---|
| 32 | * |
---|
| 33 | * !!!! Customer Be Aware, Exception!!! |
---|
| 34 | * |
---|
| 35 | * 1. Qspi Direct Access Mode is not working! |
---|
| 36 | * |
---|
| 37 | * This is because the qspi flash memory installed on our DevKit board, Micro |
---|
| 38 | * part N25Q00xx, 8 Gb, is not completely compatible with our embedded Synopsis |
---|
| 39 | * QSPI controller IP. Therefore there is no viable direct access code offered |
---|
| 40 | * in the lib. All the memory rea/write functionality is offered with indirect |
---|
| 41 | * access only. |
---|
| 42 | * |
---|
| 43 | * Should you install a different flash memory part in your custom board, and |
---|
| 44 | * wondering wether direct access mode works, please contact with us. |
---|
| 45 | * |
---|
| 46 | ******************************************************************************/ |
---|
| 47 | |
---|
| 48 | /*! \file |
---|
| 49 | * Altera - QSPI Flash Controller Module |
---|
| 50 | */ |
---|
| 51 | |
---|
| 52 | #ifndef __ALT_QSPI_H__ |
---|
| 53 | #define __ALT_QSPI_H__ |
---|
| 54 | |
---|
| 55 | #include "hwlib.h" |
---|
| 56 | |
---|
| 57 | #ifdef __cplusplus |
---|
| 58 | extern "C" |
---|
| 59 | { |
---|
| 60 | #endif /* __cplusplus */ |
---|
| 61 | |
---|
| 62 | /******************************************************************************/ |
---|
| 63 | /*! \addtogroup ALT_QSPI QSPI Flash Controller Module |
---|
| 64 | * |
---|
| 65 | * This module defines a low level driver API for the hardware processor system |
---|
| 66 | * (HPS) quad serial peripheral interface (QSPI) flash controller for access to |
---|
| 67 | * serial NOR flash devices. The quad SPI flash controller supports standard SPI |
---|
| 68 | * flash devices as well as high-performance dual and quad SPI flash |
---|
| 69 | * devices. |
---|
| 70 | * |
---|
| 71 | * @{ |
---|
| 72 | */ |
---|
| 73 | |
---|
| 74 | /******************************************************************************/ |
---|
| 75 | /*! \addtogroup ALT_QSPI_CSR General Control and Status Functions |
---|
| 76 | * |
---|
| 77 | * The declarations and functions in this group provide general purpose control |
---|
| 78 | * and status functions for the QSPI Flash Controller. |
---|
| 79 | * |
---|
| 80 | * @{ |
---|
| 81 | */ |
---|
| 82 | |
---|
| 83 | /******************************************************************************/ |
---|
| 84 | /*! |
---|
| 85 | * Initialize the QSPI flash controller for use. |
---|
| 86 | * |
---|
| 87 | * \internal |
---|
| 88 | * Implementation Notes: |
---|
| 89 | * * The QSPI Controller has been designed to wake up in a state that is |
---|
| 90 | * suitable for performing basic reads and writes using the direct access |
---|
| 91 | * controller. |
---|
| 92 | * * Bring out of reset |
---|
| 93 | * * QSPI reference clock validation |
---|
| 94 | * * See Programmer's Guide, Configuring the QSPI Controller for use after |
---|
| 95 | * reset, in QSPI_FLASH_CTRL for full initialization details. |
---|
| 96 | * \endinternal |
---|
| 97 | * |
---|
| 98 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 99 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 100 | */ |
---|
| 101 | ALT_STATUS_CODE alt_qspi_init(void); |
---|
| 102 | |
---|
| 103 | /******************************************************************************/ |
---|
| 104 | /*! |
---|
| 105 | * Uninitialize the QSPI flash controller. |
---|
| 106 | * |
---|
| 107 | * Uninitialize the QSPI flash controller by cancelling any indirect transfers |
---|
| 108 | * in progress and putting the QSPI controller into reset. |
---|
| 109 | * |
---|
| 110 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 111 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 112 | */ |
---|
| 113 | ALT_STATUS_CODE alt_qspi_uninit(void); |
---|
| 114 | |
---|
| 115 | /******************************************************************************/ |
---|
| 116 | /*! |
---|
| 117 | * Disable the QSPI Controller. |
---|
| 118 | * |
---|
| 119 | * Disable the QSPI once the current transfer of the data word (FF_W) is |
---|
| 120 | * complete. All output enables are inactive and all pins are set to input |
---|
| 121 | * mode. |
---|
| 122 | * |
---|
| 123 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 124 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 125 | */ |
---|
| 126 | ALT_STATUS_CODE alt_qspi_disable(void); |
---|
| 127 | |
---|
| 128 | /******************************************************************************/ |
---|
| 129 | /*! |
---|
| 130 | * Enable the QSPI Controller. |
---|
| 131 | * |
---|
| 132 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 133 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 134 | */ |
---|
| 135 | ALT_STATUS_CODE alt_qspi_enable(void); |
---|
| 136 | |
---|
| 137 | /******************************************************************************/ |
---|
| 138 | /*! |
---|
| 139 | * This type definition enumerates the interrupt status conditions for the QSPI |
---|
| 140 | * controller. |
---|
| 141 | * |
---|
| 142 | * The enumerations serve as masks for the QSPI controller events that can be |
---|
| 143 | * set when the designated conditions occur and the corresponding event is |
---|
| 144 | * enabled. When any of these event source conditions are true, the \b |
---|
| 145 | * ALT_INT_INTERRUPT_QSPI_IRQ interrupt output is asserted high. |
---|
| 146 | * |
---|
| 147 | * Interrupt sources are cleared when software calls alt_qspi_int_clear(). The |
---|
| 148 | * interrupt sources are individually maskable using alt_qspi_int_disable() and |
---|
| 149 | * alt_qspi_int_enable(). |
---|
| 150 | */ |
---|
| 151 | typedef enum ALT_QSPI_INT_STATUS_e |
---|
| 152 | { |
---|
| 153 | /*! |
---|
| 154 | * Mode fail M - indicates the voltage on pin n_ss_in is inconsistent with |
---|
| 155 | * the SPI mode. Set = 1 if n_ss_in is low in master mode (multi-master |
---|
| 156 | * contention). These conditions will clear the spi_enable bit and disable |
---|
| 157 | * the SPI. |
---|
| 158 | * * 0 = no mode fault has been detected. |
---|
| 159 | * * 1 = a mode fault has occurred. |
---|
| 160 | */ |
---|
| 161 | ALT_QSPI_INT_STATUS_MODE_FAIL = (0x1 << 0), |
---|
| 162 | |
---|
| 163 | /*! |
---|
| 164 | * Underflow Detected. |
---|
| 165 | * * 0 = no underflow has been detected. |
---|
| 166 | * * 1 = underflow is detected and an attempt to transfer data is made |
---|
| 167 | * when the small TX FIFO is empty. This may occur when AHB write |
---|
| 168 | * data is being supplied too slowly to keep up with the requested |
---|
| 169 | * write operation. |
---|
| 170 | */ |
---|
| 171 | ALT_QSPI_INT_STATUS_UFL = (0x1 << 1), |
---|
| 172 | |
---|
| 173 | /*! |
---|
| 174 | * Controller has completed last triggered indirect operation. |
---|
| 175 | */ |
---|
| 176 | ALT_QSPI_INT_STATUS_IDAC_OP_COMPLETE = (0x1 << 2), |
---|
| 177 | |
---|
| 178 | /*! |
---|
| 179 | * Indirect operation was requested but could not be accepted. Two indirect |
---|
| 180 | * operations already in storage. |
---|
| 181 | */ |
---|
| 182 | ALT_QSPI_INT_STATUS_IDAC_OP_REJECT = (0x1 << 3), |
---|
| 183 | |
---|
| 184 | /*! |
---|
| 185 | * Write to protected area was attempted and rejected. |
---|
| 186 | */ |
---|
| 187 | ALT_QSPI_INT_STATUS_WR_PROT_VIOL = (0x1 << 4), |
---|
| 188 | |
---|
| 189 | /*! |
---|
| 190 | * Illegal AHB Access Detected. AHB write wrapping bursts and the use of |
---|
| 191 | * SPLIT/RETRY accesses will cause this interrupt to trigger. |
---|
| 192 | */ |
---|
| 193 | ALT_QSPI_INT_STATUS_ILL_AHB_ACCESS = (0x1 << 5), |
---|
| 194 | |
---|
| 195 | /*! |
---|
| 196 | * Indirect Transfer Watermark Level Breached. |
---|
| 197 | */ |
---|
| 198 | ALT_QSPI_INT_STATUS_IDAC_WTRMK_TRIG = (0x1 << 6), |
---|
| 199 | |
---|
| 200 | /*! |
---|
| 201 | * Receive Overflow. This should only occur in Legacy SPI mode. |
---|
| 202 | * |
---|
| 203 | * Set if an attempt is made to push the RX FIFO when it is full. This bit |
---|
| 204 | * is reset only by a system reset and cleared only when this register is |
---|
| 205 | * read. If a new push to the RX FIFO occurs coincident with a register read |
---|
| 206 | * this flag will remain set. |
---|
| 207 | * * 0 = no overflow has been detected. |
---|
| 208 | * * 1 = an overflow has occurred. |
---|
| 209 | */ |
---|
| 210 | ALT_QSPI_INT_STATUS_RX_OVF = (0x1 << 7), |
---|
| 211 | |
---|
| 212 | /*! |
---|
| 213 | * Small TX FIFO not full (current FIFO status). Can be ignored in non-SPI |
---|
| 214 | * legacy mode. |
---|
| 215 | * * 0 = FIFO has >= THRESHOLD entries. |
---|
| 216 | * * 1 = FIFO has < THRESHOLD entries. |
---|
| 217 | */ |
---|
| 218 | ALT_QSPI_INT_STATUS_TX_FIFO_NOT_FULL = (0x1 << 8), |
---|
| 219 | |
---|
| 220 | /*! |
---|
| 221 | * Small TX FIFO full (current FIFO status). Can be ignored in non-SPI |
---|
| 222 | * legacy mode. |
---|
| 223 | * * 0 = FIFO is not full. |
---|
| 224 | * * 1 = FIFO is full. |
---|
| 225 | */ |
---|
| 226 | ALT_QSPI_INT_STATUS_TX_FIFO_FULL = (0x1 << 9), |
---|
| 227 | |
---|
| 228 | /*! |
---|
| 229 | * Small RX FIFO not empty (current FIFO status). Can be ignored in non-SPI |
---|
| 230 | * legacy mode. |
---|
| 231 | * * 0 = FIFO has < RX THRESHOLD entries. |
---|
| 232 | * * 1 = FIFO has >= THRESHOLD entries. |
---|
| 233 | */ |
---|
| 234 | ALT_QSPI_INT_STATUS_RX_FIFO_NOT_EMPTY = (0x1 << 10), |
---|
| 235 | |
---|
| 236 | /*! |
---|
| 237 | * Small RX FIFO full (current FIFO status). Can be ignored in non-SPI |
---|
| 238 | * legacy mode. |
---|
| 239 | * * 0 = FIFO is not full. |
---|
| 240 | * * 1 = FIFO is full. |
---|
| 241 | */ |
---|
| 242 | ALT_QSPI_INT_STATUS_RX_FIFO_FULL = (0x1 << 11), |
---|
| 243 | |
---|
| 244 | /*! |
---|
| 245 | * Indirect Read partition of SRAM is full and unable to immediately |
---|
| 246 | * complete indirect operation. |
---|
| 247 | */ |
---|
| 248 | ALT_QSPI_INT_STATUS_IDAC_RD_FULL = (0x1 << 12) |
---|
| 249 | |
---|
| 250 | } ALT_QSPI_INT_STATUS_t; |
---|
| 251 | |
---|
| 252 | /******************************************************************************/ |
---|
| 253 | /*! |
---|
| 254 | * Returns the QSPI controller interrupt status register value. |
---|
| 255 | * |
---|
| 256 | * This function returns the current value of the QSPI controller interrupt |
---|
| 257 | * status register value which reflects the current QSPI controller status |
---|
| 258 | * conditions. |
---|
| 259 | * |
---|
| 260 | * \returns The current value of the QSPI controller interrupt status |
---|
| 261 | * register value which reflects the current QSPI controller status |
---|
| 262 | * conditions as defined by the \ref ALT_QSPI_INT_STATUS_t mask. |
---|
| 263 | * If the corresponding bit is set then the condition is asserted. |
---|
| 264 | */ |
---|
| 265 | uint32_t alt_qspi_int_status_get(void); |
---|
| 266 | |
---|
| 267 | /******************************************************************************/ |
---|
| 268 | /*! |
---|
| 269 | * Clears the specified QSPI controller interrupt status conditions identified |
---|
| 270 | * in the mask. |
---|
| 271 | * |
---|
| 272 | * This function clears one or more of the status conditions as contributors to |
---|
| 273 | * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. |
---|
| 274 | * |
---|
| 275 | * \param mask |
---|
| 276 | * Specifies the QSPI interrupt status conditions to clear. \e |
---|
| 277 | * mask is a mask of logically OR'ed \ref ALT_QSPI_INT_STATUS_t |
---|
| 278 | * values that designate the status conditions to clear. |
---|
| 279 | * |
---|
| 280 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 281 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 282 | */ |
---|
| 283 | ALT_STATUS_CODE alt_qspi_int_clear(const uint32_t mask); |
---|
| 284 | |
---|
| 285 | /******************************************************************************/ |
---|
| 286 | /*! |
---|
| 287 | * Disable the specified QSPI controller interrupt status conditions identified |
---|
| 288 | * in the mask. |
---|
| 289 | * |
---|
| 290 | * This function disables one or more of the status conditions as contributors |
---|
| 291 | * to the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. |
---|
| 292 | * |
---|
| 293 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 294 | * alt_qspi_is_idle(). |
---|
| 295 | * |
---|
| 296 | * NOTE: A cleared bit for any status condition in the mask value does not have |
---|
| 297 | * the effect of enabling it as a contributor to the \b |
---|
| 298 | * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function |
---|
| 299 | * alt_qspi_int_enable() is used to enable status source conditions. |
---|
| 300 | * |
---|
| 301 | * \param mask |
---|
| 302 | * Specifies the status conditions to disable as interrupt source |
---|
| 303 | * contributors. \e mask is a mask of logically OR'ed |
---|
| 304 | * \ref ALT_QSPI_INT_STATUS_t values that designate the status |
---|
| 305 | * conditions to disable. |
---|
| 306 | * |
---|
| 307 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 308 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 309 | */ |
---|
| 310 | ALT_STATUS_CODE alt_qspi_int_disable(const uint32_t mask); |
---|
| 311 | |
---|
| 312 | /******************************************************************************/ |
---|
| 313 | /*! |
---|
| 314 | * Enable the specified QSPI controller interrupt status conditions identified |
---|
| 315 | * in the mask. |
---|
| 316 | * |
---|
| 317 | * This function enables one or more of the status conditions as contributors to |
---|
| 318 | * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. |
---|
| 319 | * |
---|
| 320 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 321 | * alt_qspi_is_idle(). |
---|
| 322 | * |
---|
| 323 | * NOTE: A cleared bit for any status condition in the mask value does not have |
---|
| 324 | * the effect of disabling it as a contributor to the \b |
---|
| 325 | * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function |
---|
| 326 | * alt_qspi_int_disable() is used to disable status source conditions. |
---|
| 327 | * |
---|
| 328 | * \param mask |
---|
| 329 | * Specifies the status conditions to enable as interrupt source |
---|
| 330 | * contributors. \e mask is a mask of logically OR'ed |
---|
| 331 | * \ref ALT_QSPI_INT_STATUS_t values that designate the status |
---|
| 332 | * conditions to enable. |
---|
| 333 | * |
---|
| 334 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 335 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 336 | */ |
---|
| 337 | ALT_STATUS_CODE alt_qspi_int_enable(const uint32_t mask); |
---|
| 338 | |
---|
| 339 | /******************************************************************************/ |
---|
| 340 | /*! |
---|
| 341 | * Returns true the serial interface and QSPI pipeline is IDLE. |
---|
| 342 | * |
---|
| 343 | * \returns Returns true the serial interface and QSPI pipeline is IDLE. |
---|
| 344 | */ |
---|
| 345 | bool alt_qspi_is_idle(void); |
---|
| 346 | |
---|
| 347 | /*! @} */ |
---|
| 348 | |
---|
| 349 | /******************************************************************************/ |
---|
| 350 | /*! \addtogroup ALT_QSPI_GP_BLKIO General Purpose Block I/O |
---|
| 351 | * |
---|
| 352 | * The functions in this group provide general purpose block read and |
---|
| 353 | * write flash functions. |
---|
| 354 | * |
---|
| 355 | * \internal |
---|
| 356 | * These functions use Indirect Read/Write transfers to read and write block |
---|
| 357 | * data to the flash device. An outline of the operational flow for these |
---|
| 358 | * operations can be found in: |
---|
| 359 | * //depot/soc/hhp_sw/baremetal_fw/drivers/qspi/qspi.c |
---|
| 360 | * |
---|
| 361 | * The general flow for an indirect block read is to call |
---|
| 362 | * qspi_configure_mode_indirect_read_start() to initiate the read transfer from |
---|
| 363 | * the flash device into the SRAM buffer and follow with a call to either |
---|
| 364 | * qpsi_write_sram_fifo_poll() or qspi_read_sram_fifo_irq() to copy the data |
---|
| 365 | * from SRAM into the user's buffer. |
---|
| 366 | * |
---|
| 367 | * The general flow for an indirect block write is to call |
---|
| 368 | * qspi_configure_mode_indirect_write_start() to initiate the write transfer |
---|
| 369 | * from the SRAM buffer to the flash device and follow with a call to either |
---|
| 370 | * qpsi_write_sram_fifo_poll() or qspi_write_sram_fifo_irq() to fill the SRAM |
---|
| 371 | * buffer with the user's data as space becomes available. |
---|
| 372 | * \endinternal |
---|
| 373 | * |
---|
| 374 | * @{ |
---|
| 375 | */ |
---|
| 376 | |
---|
| 377 | /******************************************************************************/ |
---|
| 378 | /*! |
---|
| 379 | * Read a block of data from the specified flash address. |
---|
| 380 | * |
---|
| 381 | * Reads a block of \e n data bytes from the flash \e src address into the user |
---|
| 382 | * supplied \e dest buffer. The memory address, flash address, and size must be |
---|
| 383 | * word aligned. |
---|
| 384 | * |
---|
| 385 | * \param dest |
---|
| 386 | * The address of a caller supplied destination buffer large enough |
---|
| 387 | * to contain the requested block of flash data. |
---|
| 388 | * |
---|
| 389 | * \param src |
---|
| 390 | * The flash device address to start reading data from. |
---|
| 391 | * |
---|
| 392 | * \param size |
---|
| 393 | * The requested number of data bytes to read from the flash device. |
---|
| 394 | * |
---|
| 395 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 396 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 397 | */ |
---|
| 398 | ALT_STATUS_CODE alt_qspi_read(void * dest, uint32_t src, size_t size); |
---|
| 399 | |
---|
| 400 | /******************************************************************************/ |
---|
| 401 | /*! |
---|
| 402 | * Write a block of data to the specified flash address. |
---|
| 403 | * |
---|
| 404 | * Writes a block of \e n data bytes to the flash \e dest address from the |
---|
| 405 | * designated \e src buffer. The applicable destination flash address range |
---|
| 406 | * should have been erased prior to calling this function. The flash address, |
---|
| 407 | * memory address, and size must be word aligned. |
---|
| 408 | * |
---|
| 409 | * \param dest |
---|
| 410 | * The destination flash address to begin writing data to. |
---|
| 411 | * |
---|
| 412 | * \param src |
---|
| 413 | * The source address to start writing data from. |
---|
| 414 | * |
---|
| 415 | * \param size |
---|
| 416 | * The requested number of data bytes to write to the flash device. |
---|
| 417 | * |
---|
| 418 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 419 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 420 | */ |
---|
| 421 | ALT_STATUS_CODE alt_qspi_write(uint32_t dest, const void * src, size_t size); |
---|
| 422 | |
---|
| 423 | /*! @} */ |
---|
| 424 | |
---|
| 425 | /******************************************************************************/ |
---|
| 426 | /*! \addtogroup ALT_QSPI_DEV_CFG Flash Device Configuration |
---|
| 427 | * |
---|
| 428 | * The declarations and functions in this group are used to configure the QSPI |
---|
| 429 | * controller interface to external flash devices. |
---|
| 430 | * |
---|
| 431 | * The following steps describe how to initialize and configure the |
---|
| 432 | * QSPI controller to operate with a flash device. |
---|
| 433 | * |
---|
| 434 | * * Wait until any pending QSPI operations have completed. |
---|
| 435 | * * Disable the QSPI controller using alt_qspi_disable(). |
---|
| 436 | * * Configure the device for optimal read transaction performance using |
---|
| 437 | * alt_qspi_device_read_config_set(). |
---|
| 438 | * * Configure the device for optimal write transaction performance using |
---|
| 439 | * alt_qspi_device_write_config_set(). |
---|
| 440 | * * Enable (alt_qspi_mode_bit_disable()) or disable |
---|
| 441 | * (alt_qspi_mode_bit_disable()) the mode bits per the device |
---|
| 442 | * requirements. If mode bits are enabled, then configure the mode |
---|
| 443 | * bit values using alt_qspi_mode_bit_config_set(). |
---|
| 444 | * * Configure the device size and write protection information using |
---|
| 445 | * alt_qspi_device_size_config_set(). |
---|
| 446 | * * Configure the QSPI device delay and timing settings using |
---|
| 447 | * alt_qspi_device_write_config_set(). |
---|
| 448 | * * Configure the baud divisor setting to define the required clock frequency |
---|
| 449 | * to the device using alt_qspi_baud_rate_div_set(). |
---|
| 450 | * * Enable the QSPI controller using alt_qspi_enable(). |
---|
| 451 | * |
---|
| 452 | * @{ |
---|
| 453 | */ |
---|
| 454 | |
---|
| 455 | /******************************************************************************/ |
---|
| 456 | /*! |
---|
| 457 | * This type enumerates the operational modes the QSPI controller can be |
---|
| 458 | * configured for. It may apply to instruction, address, and/or data width |
---|
| 459 | * interactions between the QSPI controller and the flash device. |
---|
| 460 | */ |
---|
| 461 | typedef enum ALT_QSPI_MODE_e |
---|
| 462 | { |
---|
| 463 | ALT_QSPI_MODE_SINGLE = 0, /*!< Use Standard Single SPI (SIO-SPI) mode (bits |
---|
| 464 | * always transferred into the device on DQ0 |
---|
| 465 | * only). Supported by all SPI flash devices. |
---|
| 466 | */ |
---|
| 467 | ALT_QSPI_MODE_DUAL = 1, /*!< Use Dual SPI (DIO-SPI) SPI mode where bits are |
---|
| 468 | * transferred on DQ0 and DQ1. |
---|
| 469 | */ |
---|
| 470 | ALT_QSPI_MODE_QUAD = 2 /*!< Use Dual SPI (QIO-SPI) SPI mode where bits are |
---|
| 471 | * transferred on DQ0, DQ1, DQ3, and DQ3. |
---|
| 472 | */ |
---|
| 473 | } ALT_QSPI_MODE_t; |
---|
| 474 | |
---|
| 475 | /******************************************************************************/ |
---|
| 476 | /*! |
---|
| 477 | * This type enumerates the mode configurations available for driving the |
---|
| 478 | * ss_n[3:0] device chip selects. The chip selects may be controlled as either |
---|
| 479 | * in a '1 of 4' or '4 to 16 decode' mode. |
---|
| 480 | */ |
---|
| 481 | typedef enum ALT_QSPI_CS_MODE_e |
---|
| 482 | { |
---|
| 483 | ALT_QSPI_CS_MODE_SINGLE_SELECT = 0, /*!< Select 1 of 4 chip select ss_n[3:0] |
---|
| 484 | */ |
---|
| 485 | ALT_QSPI_CS_MODE_DECODE = 1 /*!< Select external 4 to 16 decode of |
---|
| 486 | * ss_n[3:0]. |
---|
| 487 | */ |
---|
| 488 | } ALT_QSPI_CS_MODE_t; |
---|
| 489 | |
---|
| 490 | /******************************************************************************/ |
---|
| 491 | /*! |
---|
| 492 | * This type enumerates the QSPI controller master baud rate divisor selections. |
---|
| 493 | */ |
---|
| 494 | typedef enum ALT_QSPI_BAUD_DIV_e |
---|
| 495 | { |
---|
| 496 | ALT_QSPI_BAUD_DIV_2 = 0x0, /*!< Divide by 2 */ |
---|
| 497 | ALT_QSPI_BAUD_DIV_4 = 0x1, /*!< Divide by 4 */ |
---|
| 498 | ALT_QSPI_BAUD_DIV_6 = 0x2, /*!< Divide by 6 */ |
---|
| 499 | ALT_QSPI_BAUD_DIV_8 = 0x3, /*!< Divide by 8 */ |
---|
| 500 | ALT_QSPI_BAUD_DIV_10 = 0x4, /*!< Divide by 10 */ |
---|
| 501 | ALT_QSPI_BAUD_DIV_12 = 0x5, /*!< Divide by 12 */ |
---|
| 502 | ALT_QSPI_BAUD_DIV_14 = 0x6, /*!< Divide by 14 */ |
---|
| 503 | ALT_QSPI_BAUD_DIV_16 = 0x7, /*!< Divide by 16 */ |
---|
| 504 | ALT_QSPI_BAUD_DIV_18 = 0x8, /*!< Divide by 18 */ |
---|
| 505 | ALT_QSPI_BAUD_DIV_20 = 0x9, /*!< Divide by 20 */ |
---|
| 506 | ALT_QSPI_BAUD_DIV_22 = 0xA, /*!< Divide by 22 */ |
---|
| 507 | ALT_QSPI_BAUD_DIV_24 = 0xB, /*!< Divide by 24 */ |
---|
| 508 | ALT_QSPI_BAUD_DIV_26 = 0xC, /*!< Divide by 26 */ |
---|
| 509 | ALT_QSPI_BAUD_DIV_28 = 0xD, /*!< Divide by 28 */ |
---|
| 510 | ALT_QSPI_BAUD_DIV_30 = 0xE, /*!< Divide by 30 */ |
---|
| 511 | ALT_QSPI_BAUD_DIV_32 = 0xF /*!< Divide by 32 */ |
---|
| 512 | } ALT_QSPI_BAUD_DIV_t; |
---|
| 513 | |
---|
| 514 | /******************************************************************************/ |
---|
| 515 | /*! |
---|
| 516 | * Device Size Configuration |
---|
| 517 | * |
---|
| 518 | * This type defines the structure used to specify flash device size and write |
---|
| 519 | * protect regions. |
---|
| 520 | */ |
---|
| 521 | typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s |
---|
| 522 | { |
---|
| 523 | uint32_t block_size; /*!< Number of bytes per device block. The |
---|
| 524 | * number is specified as a power of 2. |
---|
| 525 | * That is 0 = 1 byte, 1 = 2 bytes, ... |
---|
| 526 | * 16 = 65535 bytes, etc. |
---|
| 527 | */ |
---|
| 528 | uint32_t page_size; /*!< Number of bytes per device page. This |
---|
| 529 | * is required by the controller for |
---|
| 530 | * performing flash writes up to and |
---|
| 531 | * across page boundaries. |
---|
| 532 | */ |
---|
| 533 | uint32_t addr_size; /*!< Number of bytes used for the flash |
---|
| 534 | * address. The value is \e n + 1 |
---|
| 535 | * based. That is 0 = 1 byte, 1 = 2 bytes, |
---|
| 536 | * 2 = 3 bytes, 3 = 4 bytes. |
---|
| 537 | */ |
---|
| 538 | uint32_t lower_wrprot_block; /*!< The block number that defines the lower |
---|
| 539 | * block in the range of blocks that is |
---|
| 540 | * protected from writing. This field |
---|
| 541 | * is ignored it write protection is |
---|
| 542 | * disabled. |
---|
| 543 | */ |
---|
| 544 | uint32_t upper_wrprot_block; /*!< The block number that defines the upper |
---|
| 545 | * block in the range of blocks that is |
---|
| 546 | * protected from writing. This field |
---|
| 547 | * is ignored it write protection is |
---|
| 548 | * disabled. |
---|
| 549 | */ |
---|
| 550 | bool wrprot_enable; /*!< The write region enable value. A value |
---|
| 551 | * of \b true enables write protection |
---|
| 552 | * on the region specified by the |
---|
| 553 | * \e lower_wrprot_block and |
---|
| 554 | * \e upper_wrprot_block range. |
---|
| 555 | */ |
---|
| 556 | } ALT_QSPI_DEV_SIZE_CONFIG_t; |
---|
| 557 | |
---|
| 558 | /******************************************************************************/ |
---|
| 559 | /*! |
---|
| 560 | * This type enumerates the QSPI clock phase activity options outside the SPI |
---|
| 561 | * word. |
---|
| 562 | */ |
---|
| 563 | typedef enum ALT_QSPI_CLK_PHASE_e |
---|
| 564 | { |
---|
| 565 | ALT_QSPI_CLK_PHASE_ACTIVE = 0, /*!< The SPI clock is active outside the |
---|
| 566 | * word |
---|
| 567 | */ |
---|
| 568 | ALT_QSPI_CLK_PHASE_INACTIVE = 1 /*!< The SPI clock is inactive outside the |
---|
| 569 | * word |
---|
| 570 | */ |
---|
| 571 | } ALT_QSPI_CLK_PHASE_t; |
---|
| 572 | |
---|
| 573 | /******************************************************************************/ |
---|
| 574 | /*! |
---|
| 575 | * This type enumerates the QSPI clock polarity options outside the SPI word. |
---|
| 576 | */ |
---|
| 577 | typedef enum ALT_QSPI_CLK_POLARITY_e |
---|
| 578 | { |
---|
| 579 | ALT_QSPI_CLK_POLARITY_LOW = 0, /*!< SPI clock is quiescent low outside the |
---|
| 580 | * word. |
---|
| 581 | */ |
---|
| 582 | ALT_QSPI_CLK_POLARITY_HIGH = 1 /*!< SPI clock is quiescent high outside the |
---|
| 583 | * word. |
---|
| 584 | */ |
---|
| 585 | } ALT_QSPI_CLK_POLARITY_t; |
---|
| 586 | |
---|
| 587 | /******************************************************************************/ |
---|
| 588 | /*! |
---|
| 589 | * QSPI Controller Timing Configuration |
---|
| 590 | * |
---|
| 591 | * This type defines the structure used to configure timing paramaters used by |
---|
| 592 | * the QSPI controller to communicate with a target flash device. |
---|
| 593 | * |
---|
| 594 | * All timing values are defined in cycles of the SPI master ref clock. |
---|
| 595 | */ |
---|
| 596 | typedef struct ALT_QSPI_TIMING_CONFIG_s |
---|
| 597 | { |
---|
| 598 | ALT_QSPI_CLK_PHASE_t clk_phase; /*!< Selects whether the clock is in an |
---|
| 599 | * active or inactive phase outside the |
---|
| 600 | * SPI word. |
---|
| 601 | */ |
---|
| 602 | |
---|
| 603 | ALT_QSPI_CLK_POLARITY_t clk_pol; /*!< Selects whether the clock is quiescent |
---|
| 604 | * low or high outside the SPI word. |
---|
| 605 | */ |
---|
| 606 | |
---|
| 607 | uint32_t cs_da; /*!< Chip Select De-Assert. Added delay in |
---|
| 608 | * master reference clocks for the length |
---|
| 609 | * that the master mode chip select |
---|
| 610 | * outputs are de-asserted between |
---|
| 611 | * transactions. If CSDA = \e X, then the |
---|
| 612 | * chip select de-assert time will be: 1 |
---|
| 613 | * sclk_out + 1 ref_clk + \e X ref_clks. |
---|
| 614 | */ |
---|
| 615 | uint32_t cs_dads; /*!< Chip Select De-Assert Different |
---|
| 616 | * Slaves. Delay in master reference |
---|
| 617 | * clocks between one chip select being |
---|
| 618 | * de-activated and the activation of |
---|
| 619 | * another. This is used to ensure a quiet |
---|
| 620 | * period between the selection of two |
---|
| 621 | * different slaves. CSDADS is only |
---|
| 622 | * relevant when switching between 2 |
---|
| 623 | * different external flash devices. If |
---|
| 624 | * CSDADS = \e X, then the delay will be: |
---|
| 625 | * 1 sclk_out + 3 ref_clks + \e X |
---|
| 626 | * ref_clks. |
---|
| 627 | */ |
---|
| 628 | uint32_t cs_eot; /*!< Chip Select End Of Transfer. Delay in |
---|
| 629 | * master reference clocks between last |
---|
| 630 | * bit of current transaction and |
---|
| 631 | * de-asserting the device chip select |
---|
| 632 | * (n_ss_out). By default (when CSEOT=0), |
---|
| 633 | * the chip select will be de-asserted on |
---|
| 634 | * the last falling edge of sclk_out at |
---|
| 635 | * the completion of the current |
---|
| 636 | * transaction. If CSEOT = \e X, then chip |
---|
| 637 | * selected will de-assert \e X ref_clks |
---|
| 638 | * after the last falling edge of |
---|
| 639 | * sclk_out. |
---|
| 640 | */ |
---|
| 641 | uint32_t cs_sot; /*!< Chip Select Start Of Transfer. Delay in |
---|
| 642 | * master reference clocks between setting |
---|
| 643 | * n_ss_out low and first bit transfer. By |
---|
| 644 | * default (CSSOT=0), chip select will be |
---|
| 645 | * asserted half a SCLK period before the |
---|
| 646 | * first rising edge of sclk_out. If CSSOT |
---|
| 647 | * = \e X, chip select will be asserted |
---|
| 648 | * half an sclk_out period before the |
---|
| 649 | * first rising edge of sclk_out + \e X |
---|
| 650 | * ref_clks. |
---|
| 651 | */ |
---|
| 652 | |
---|
| 653 | uint32_t rd_datacap; /*!< The additional number of read data |
---|
| 654 | * capture cycles (ref_clk) that should be |
---|
| 655 | * applied to the internal read data |
---|
| 656 | * capture circuit. The large |
---|
| 657 | * clock-to-out delay of the flash memory |
---|
| 658 | * together with trace delays as well as |
---|
| 659 | * other device delays may impose a |
---|
| 660 | * maximum flash clock frequency which is |
---|
| 661 | * less than the flash memory device |
---|
| 662 | * itself can operate at. To compensate, |
---|
| 663 | * software should set this register to a |
---|
| 664 | * value that guarantees robust data |
---|
| 665 | * captures. |
---|
| 666 | */ |
---|
| 667 | } ALT_QSPI_TIMING_CONFIG_t; |
---|
| 668 | |
---|
| 669 | /******************************************************************************/ |
---|
| 670 | /*! |
---|
| 671 | * Device Instruction Configuration |
---|
| 672 | * |
---|
| 673 | * This type defines a structure for specifying the optimal instruction set |
---|
| 674 | * configuration to use with a target flash device. |
---|
| 675 | */ |
---|
| 676 | typedef struct ALT_QSPI_DEV_INST_CONFIG_s |
---|
| 677 | { |
---|
| 678 | uint32_t op_code; /*!< The read or write op code to use |
---|
| 679 | * for the device transaction. |
---|
| 680 | */ |
---|
| 681 | ALT_QSPI_MODE_t inst_type; /*!< Instruction mode type for the |
---|
| 682 | * controller to use with the |
---|
| 683 | * device. The instruction type |
---|
| 684 | * applies to all instructions |
---|
| 685 | * (reads and writes) issued from |
---|
| 686 | * either the Direct Access |
---|
| 687 | * Controller or the Indirect |
---|
| 688 | * Acces Controller. |
---|
| 689 | */ |
---|
| 690 | ALT_QSPI_MODE_t addr_xfer_type; /*!< Address transfer mode type. The |
---|
| 691 | * value of this field is ignored |
---|
| 692 | * if the \e inst_type data member |
---|
| 693 | * is set to anything other than |
---|
| 694 | * ALT_QSPI_MODE_SINGLE. In that |
---|
| 695 | * case, the addr_xfer_type |
---|
| 696 | * assumes the same mode as the \e |
---|
| 697 | * inst_type. |
---|
| 698 | */ |
---|
| 699 | ALT_QSPI_MODE_t data_xfer_type; /*!< Data transfer mode type. The |
---|
| 700 | * value of this field is ignored |
---|
| 701 | * if the \e inst_type data member |
---|
| 702 | * is set to anything other than |
---|
| 703 | * ALT_QSPI_MODE_SINGLE. In that |
---|
| 704 | * case, the data_xfer_type |
---|
| 705 | * assumes the same mode as the \e |
---|
| 706 | * inst_type. |
---|
| 707 | */ |
---|
| 708 | uint32_t dummy_cycles; /*!< Number of dummy clock cycles |
---|
| 709 | * required by device for a read |
---|
| 710 | * or write instruction. |
---|
| 711 | */ |
---|
| 712 | |
---|
| 713 | } ALT_QSPI_DEV_INST_CONFIG_t; |
---|
| 714 | |
---|
| 715 | /******************************************************************************/ |
---|
| 716 | /*! |
---|
| 717 | * Get the current value of the QSPI master baud rate divisor. |
---|
| 718 | * |
---|
| 719 | * \returns The value of the QSPI master baud rate divisor. |
---|
| 720 | */ |
---|
| 721 | ALT_QSPI_BAUD_DIV_t alt_qspi_baud_rate_div_get(void); |
---|
| 722 | |
---|
| 723 | /******************************************************************************/ |
---|
| 724 | /*! |
---|
| 725 | * Set the current value of the QSPI master baud rate divisor. |
---|
| 726 | * |
---|
| 727 | * Sets the value of the QSPI master baud rate divisor. |
---|
| 728 | * |
---|
| 729 | * \param baud_rate_div |
---|
| 730 | * The master baud rate divisor. Valid range includes |
---|
| 731 | * even values 2 to 32. |
---|
| 732 | * |
---|
| 733 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 734 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 735 | */ |
---|
| 736 | ALT_STATUS_CODE alt_qspi_baud_rate_div_set(const ALT_QSPI_BAUD_DIV_t baud_rate_div); |
---|
| 737 | |
---|
| 738 | /******************************************************************************/ |
---|
| 739 | /*! |
---|
| 740 | * Get the current QSPI device peripheral chip select output and decode function |
---|
| 741 | * configuration values. |
---|
| 742 | * |
---|
| 743 | * \param cs |
---|
| 744 | * [out] The chip select line output values. |
---|
| 745 | * |
---|
| 746 | * \param cs_mode |
---|
| 747 | * [out] The decode mode to use for the chip selects. |
---|
| 748 | * |
---|
| 749 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 750 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 751 | */ |
---|
| 752 | ALT_STATUS_CODE alt_qspi_chip_select_config_get(uint32_t* cs, ALT_QSPI_CS_MODE_t* cs_mode); |
---|
| 753 | |
---|
| 754 | /******************************************************************************/ |
---|
| 755 | /*! |
---|
| 756 | * Set the QSPI device peripheral chip select outputs and decode function |
---|
| 757 | * configuration. |
---|
| 758 | * |
---|
| 759 | * The chip select lines output values operate according to the selected chip |
---|
| 760 | * select decode mode. If \e cs_mode is ALT_QSPI_CS_MODE_SINGLE_SELECT then |
---|
| 761 | * cs[3:0] are output thus: |
---|
| 762 | * |
---|
| 763 | * cs[3:0] | n_ss_out[3:0] |
---|
| 764 | * :---------|:---------------------------- |
---|
| 765 | * xxx0 | 1110 |
---|
| 766 | * xx01 | 1101 |
---|
| 767 | * x011 | 1011 |
---|
| 768 | * 0111 | 0111 |
---|
| 769 | * 1111 | 1111 (no peripheral selected) |
---|
| 770 | * |
---|
| 771 | * Otherwise if \e cs_mode is ALT_QSPI_CS_MODE_DECODE then cs[3:0] directly |
---|
| 772 | * drives n_ss_out[3:0]. |
---|
| 773 | * |
---|
| 774 | * \param cs |
---|
| 775 | * The chip select line output values. |
---|
| 776 | * |
---|
| 777 | * \param cs_mode |
---|
| 778 | * The decode mode to use for the chip selects. |
---|
| 779 | * |
---|
| 780 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 781 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 782 | */ |
---|
| 783 | ALT_STATUS_CODE alt_qspi_chip_select_config_set(const uint32_t cs, |
---|
| 784 | const ALT_QSPI_CS_MODE_t cs_mode); |
---|
| 785 | |
---|
| 786 | /******************************************************************************/ |
---|
| 787 | /*! |
---|
| 788 | * Disable the mode bits from being sent after the address bytes. |
---|
| 789 | * |
---|
| 790 | * Prevent the mode bits defined in the Mode Bit Configuration register from |
---|
| 791 | * being sent following the address bytes. |
---|
| 792 | * |
---|
| 793 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 794 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 795 | */ |
---|
| 796 | ALT_STATUS_CODE alt_qspi_mode_bit_disable(void); |
---|
| 797 | |
---|
| 798 | /******************************************************************************/ |
---|
| 799 | /*! |
---|
| 800 | * Enable the mode bits to be sent after the address bytes. |
---|
| 801 | * |
---|
| 802 | * Ensure the mode bits defined in the Mode Bit Configuration register to |
---|
| 803 | * be sent following the address bytes. |
---|
| 804 | * |
---|
| 805 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 806 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 807 | */ |
---|
| 808 | ALT_STATUS_CODE alt_qspi_mode_bit_enable(void); |
---|
| 809 | |
---|
| 810 | /******************************************************************************/ |
---|
| 811 | /*! |
---|
| 812 | * Get the current value of the Mode Bit Configuration register. |
---|
| 813 | * |
---|
| 814 | * \returns The 8 bit value that is sent to the device following the address |
---|
| 815 | * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable()) |
---|
| 816 | */ |
---|
| 817 | uint32_t alt_qspi_mode_bit_config_get(void); |
---|
| 818 | |
---|
| 819 | /******************************************************************************/ |
---|
| 820 | /*! |
---|
| 821 | * Set the value of the Mode Bit Configuration register. |
---|
| 822 | * |
---|
| 823 | * Set the value of the 8 bits that are sent to the device following the address |
---|
| 824 | * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable()) |
---|
| 825 | * |
---|
| 826 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 827 | * alt_qspi_is_idle(). |
---|
| 828 | * |
---|
| 829 | * \param mode_bits |
---|
| 830 | * The 8 bit value sent to the device following the address bytes. |
---|
| 831 | * |
---|
| 832 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 833 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 834 | */ |
---|
| 835 | ALT_STATUS_CODE alt_qspi_mode_bit_config_set(const uint32_t mode_bits); |
---|
| 836 | |
---|
| 837 | /******************************************************************************/ |
---|
| 838 | /*! |
---|
| 839 | * Get the current flash device size and write protection configuration. |
---|
| 840 | * |
---|
| 841 | * \param cfg |
---|
| 842 | * [out] Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure to |
---|
| 843 | * contain the returned flash device size and write protection |
---|
| 844 | * configuration. |
---|
| 845 | * |
---|
| 846 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 847 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 848 | */ |
---|
| 849 | ALT_STATUS_CODE alt_qspi_device_size_config_get(ALT_QSPI_DEV_SIZE_CONFIG_t * cfg); |
---|
| 850 | |
---|
| 851 | /******************************************************************************/ |
---|
| 852 | /*! |
---|
| 853 | * Set the flash device size and write protection configuration. |
---|
| 854 | * |
---|
| 855 | * \param cfg |
---|
| 856 | * Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the |
---|
| 857 | * flash device size and write protection configuration. |
---|
| 858 | * |
---|
| 859 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 860 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 861 | */ |
---|
| 862 | ALT_STATUS_CODE alt_qspi_device_size_config_set(const ALT_QSPI_DEV_SIZE_CONFIG_t * cfg); |
---|
| 863 | |
---|
| 864 | /******************************************************************************/ |
---|
| 865 | /*! |
---|
| 866 | * Get the current QSPI device read instruction configuration. |
---|
| 867 | * |
---|
| 868 | * \param cfg |
---|
| 869 | * [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to |
---|
| 870 | * contain the returned QSPI controller instruction configuration |
---|
| 871 | * used when performing read transactions with the device. |
---|
| 872 | * |
---|
| 873 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 874 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 875 | */ |
---|
| 876 | ALT_STATUS_CODE alt_qspi_device_read_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg); |
---|
| 877 | |
---|
| 878 | /******************************************************************************/ |
---|
| 879 | /*! |
---|
| 880 | * Set the QSPI device read instruction configuration. |
---|
| 881 | * |
---|
| 882 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 883 | * alt_qspi_is_idle(). |
---|
| 884 | * |
---|
| 885 | * \param cfg |
---|
| 886 | * Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the |
---|
| 887 | * desired op code, transfer widths, and dummy cycles for the QSPI |
---|
| 888 | * controller to use when performing read transactions with the |
---|
| 889 | * device. |
---|
| 890 | * |
---|
| 891 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 892 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 893 | */ |
---|
| 894 | ALT_STATUS_CODE alt_qspi_device_read_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg); |
---|
| 895 | |
---|
| 896 | /******************************************************************************/ |
---|
| 897 | /*! |
---|
| 898 | * Get the current QSPI device write instruction configuration. |
---|
| 899 | * |
---|
| 900 | * \param cfg |
---|
| 901 | * [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to |
---|
| 902 | * contain the returned QSPI controller instruction configuration |
---|
| 903 | * used when performing write transactions with the device. |
---|
| 904 | * |
---|
| 905 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 906 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 907 | */ |
---|
| 908 | ALT_STATUS_CODE alt_qspi_device_write_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg); |
---|
| 909 | |
---|
| 910 | /******************************************************************************/ |
---|
| 911 | /*! |
---|
| 912 | * Set the QSPI device write instruction configuration. |
---|
| 913 | * |
---|
| 914 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 915 | * alt_qspi_is_idle(). |
---|
| 916 | * |
---|
| 917 | * \param cfg |
---|
| 918 | * Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the |
---|
| 919 | * desired op code, transfer widths, and dummy cycles for the QSPI |
---|
| 920 | * controller to use when performing write transactions with the |
---|
| 921 | * device. |
---|
| 922 | * |
---|
| 923 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 924 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 925 | */ |
---|
| 926 | ALT_STATUS_CODE alt_qspi_device_write_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg); |
---|
| 927 | |
---|
| 928 | /******************************************************************************/ |
---|
| 929 | /*! |
---|
| 930 | * Get the QSPI device delay and timing configuration parameters. |
---|
| 931 | * |
---|
| 932 | * This function returns the settings of the chip select delay and timing |
---|
| 933 | * configurations. |
---|
| 934 | * |
---|
| 935 | * \param cfg |
---|
| 936 | * [out] Pointer to a ALT_QSPI_TIMING_CONFIG_t structure to return |
---|
| 937 | * the device timing and delay settings. |
---|
| 938 | * |
---|
| 939 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 940 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 941 | */ |
---|
| 942 | ALT_STATUS_CODE alt_qspi_timing_config_get(ALT_QSPI_TIMING_CONFIG_t * cfg); |
---|
| 943 | |
---|
| 944 | /******************************************************************************/ |
---|
| 945 | /*! |
---|
| 946 | * Set the QSPI device delay and timing configuration parameters. |
---|
| 947 | * |
---|
| 948 | * This function allows the user to configure how the chip select is driven |
---|
| 949 | * after each flash access. This is required as each device may have different |
---|
| 950 | * timing requirements. As the serial clock frequency is increased, these |
---|
| 951 | * timing parameters become more important and can be adjusted to meet the |
---|
| 952 | * requirements of a specific flash device. All timings are defined in cycles |
---|
| 953 | * of the SPI master ref clock. |
---|
| 954 | * |
---|
| 955 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 956 | * alt_qspi_is_idle(). |
---|
| 957 | * |
---|
| 958 | * \param cfg |
---|
| 959 | * Pointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the |
---|
| 960 | * desired timing and delay settings. |
---|
| 961 | * |
---|
| 962 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 963 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 964 | */ |
---|
| 965 | ALT_STATUS_CODE alt_qspi_timing_config_set(const ALT_QSPI_TIMING_CONFIG_t * cfg); |
---|
| 966 | |
---|
| 967 | /*! @} */ |
---|
| 968 | |
---|
| 969 | /******************************************************************************/ |
---|
| 970 | /*! \addtogroup ALT_QSPI_DAC Direct Access Mode |
---|
| 971 | * |
---|
| 972 | * In direct access mode, an access to the AHB data slave triggers a read or |
---|
| 973 | * write command to the flash memory. To use the direct access mode, enable the |
---|
| 974 | * direct access controller with the alt_qspi_direct_enable() function. An |
---|
| 975 | * external master, for example a processor, triggers the direct access |
---|
| 976 | * controller with a read or write operation to the AHB data slave |
---|
| 977 | * interface. The data slave exposes a 1MB window into the flash device. You can |
---|
| 978 | * remap this window to any 1MB location within the flash device address range. |
---|
| 979 | * |
---|
| 980 | * To remap the AHB data slave to access other 1MB regions of the flash device, |
---|
| 981 | * enable address remapping by calling alt_qspi_ahb_address_remap_enable(). All |
---|
| 982 | * incoming data slave accesses remap to the offset specified in the remap |
---|
| 983 | * address register which is configured by alt_qspi_ahb_remap_address_set(). |
---|
| 984 | * |
---|
| 985 | * The 20 LSBs of incoming addresses are used for accessing the 1MB region and |
---|
| 986 | * the higher bits are ignored. |
---|
| 987 | * |
---|
| 988 | * The quad SPI controller does not issue any error status for accesses that lie |
---|
| 989 | * outside the connected flash memory space. |
---|
| 990 | * |
---|
| 991 | * @{ |
---|
| 992 | */ |
---|
| 993 | |
---|
| 994 | /******************************************************************************/ |
---|
| 995 | /*! |
---|
| 996 | * Disable the QSPI Direct Access Controller. |
---|
| 997 | * |
---|
| 998 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 999 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1000 | */ |
---|
| 1001 | ALT_STATUS_CODE alt_qspi_direct_disable(void); |
---|
| 1002 | |
---|
| 1003 | /******************************************************************************/ |
---|
| 1004 | /*! |
---|
| 1005 | * Enable the QSPI Direct Access Controller. |
---|
| 1006 | * |
---|
| 1007 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1008 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1009 | */ |
---|
| 1010 | ALT_STATUS_CODE alt_qspi_direct_enable(void); |
---|
| 1011 | |
---|
| 1012 | /******************************************************************************/ |
---|
| 1013 | /*! |
---|
| 1014 | * Get the current AHB address remap value. |
---|
| 1015 | * |
---|
| 1016 | * Returns the current value of the AHB remap address register. |
---|
| 1017 | * |
---|
| 1018 | * \returns The value used to remap an incoming AHB address to a |
---|
| 1019 | * different address used by the flash device. |
---|
| 1020 | */ |
---|
| 1021 | uint32_t alt_qspi_ahb_remap_address_get(void); |
---|
| 1022 | |
---|
| 1023 | /******************************************************************************/ |
---|
| 1024 | /*! |
---|
| 1025 | * Set the AHB address remap value. |
---|
| 1026 | * |
---|
| 1027 | * Sets the value of the AHB remap address register. |
---|
| 1028 | * |
---|
| 1029 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 1030 | * alt_qspi_is_idle(). |
---|
| 1031 | * |
---|
| 1032 | * \param ahb_remap_addr |
---|
| 1033 | * The value used to remap an incoming AHB address to a different |
---|
| 1034 | * address used by the flash device. |
---|
| 1035 | * |
---|
| 1036 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1037 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1038 | */ |
---|
| 1039 | ALT_STATUS_CODE alt_qspi_ahb_remap_address_set(const uint32_t ahb_remap_addr); |
---|
| 1040 | |
---|
| 1041 | /******************************************************************************/ |
---|
| 1042 | /*! |
---|
| 1043 | * Disable AHB address remapping. |
---|
| 1044 | * |
---|
| 1045 | * Disables remapping of incoming AHB addresses so they are sent unmodified to |
---|
| 1046 | * the flash device. The incoming AHB address maps directly to the address |
---|
| 1047 | * serially sent to the flash device. |
---|
| 1048 | * |
---|
| 1049 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1050 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1051 | */ |
---|
| 1052 | ALT_STATUS_CODE alt_qspi_ahb_address_remap_disable(void); |
---|
| 1053 | |
---|
| 1054 | /******************************************************************************/ |
---|
| 1055 | /*! |
---|
| 1056 | * Enable AHB address remapping. |
---|
| 1057 | * |
---|
| 1058 | * Enables remapping of incoming AHB addresses so they are modified to |
---|
| 1059 | * \<address\> + \e N, where \e N is the configured remap address value. |
---|
| 1060 | * |
---|
| 1061 | * See: alt_qspi_ahb_remap_address_set(). |
---|
| 1062 | * |
---|
| 1063 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1064 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1065 | */ |
---|
| 1066 | ALT_STATUS_CODE alt_qspi_ahb_address_remap_enable(void); |
---|
| 1067 | |
---|
| 1068 | /*! @} */ |
---|
| 1069 | |
---|
| 1070 | /******************************************************************************/ |
---|
| 1071 | /*! \addtogroup ALT_QSPI_INDAC Indirect Access Mode |
---|
| 1072 | * |
---|
| 1073 | * In indirect access mode, flash data is temporarily buffered in the QSPI |
---|
| 1074 | * controller's SRAM. Software controls and triggers indirect accesses through |
---|
| 1075 | * the APB register slave interface. The controller transfers data through the |
---|
| 1076 | * AHB data slave interface. |
---|
| 1077 | * |
---|
| 1078 | * An indirect read operation reads data from the flash memory, places the data |
---|
| 1079 | * into the SRAM, and transfers the data to an external master through the AHB |
---|
| 1080 | * data slave interface. |
---|
| 1081 | * |
---|
| 1082 | * An indirect write operation programs data from the SRAM to the flash memory. |
---|
| 1083 | * |
---|
| 1084 | * @{ |
---|
| 1085 | */ |
---|
| 1086 | |
---|
| 1087 | /******************************************************************************/ |
---|
| 1088 | /*! |
---|
| 1089 | * Starts an indirect read transfer. |
---|
| 1090 | * |
---|
| 1091 | * Initiates an indirect read transfer of the requested number of bytes from the |
---|
| 1092 | * designated flash address. |
---|
| 1093 | * |
---|
| 1094 | * After calling this function, flash data may be read from the QSPI SRAM buffer |
---|
| 1095 | * as it becomes available via one of the following methods: |
---|
| 1096 | * * Directly from the AHB data slave interface at the configured AHB trigger |
---|
| 1097 | * address. If the requested data is not immediately available in the SRAM |
---|
| 1098 | * buffer then AHB wait states will be applied until the data has been read |
---|
| 1099 | * from flash into the SRAM buffer. Alternatively, data may be read from the |
---|
| 1100 | * AHB data slave as the SRAM is filled. The availability of data in the SRAM |
---|
| 1101 | * buffer may be determined by an SRAM watermark interrupt notification or by |
---|
| 1102 | * polling the SRAM fill level. |
---|
| 1103 | * * Configuring and enabling the QSPI DMA peripheral controller. |
---|
| 1104 | * |
---|
| 1105 | * The following is a list of restrictions: |
---|
| 1106 | * * flash_addr must be word aligned. |
---|
| 1107 | * * num_bytes must be word aligned. |
---|
| 1108 | * * The transfer must not cross the 3-byte addressing boundary. This |
---|
| 1109 | * restriction may be device specific and may be lifted in the future. |
---|
| 1110 | * |
---|
| 1111 | * \param flash_addr |
---|
| 1112 | * The flash source address to read data from. |
---|
| 1113 | * |
---|
| 1114 | * \param num_bytes |
---|
| 1115 | * The number of bytes to read from the flash source address. |
---|
| 1116 | * |
---|
| 1117 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1118 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1119 | */ |
---|
| 1120 | ALT_STATUS_CODE alt_qspi_indirect_read_start(const uint32_t flash_addr, |
---|
| 1121 | const size_t num_bytes); |
---|
| 1122 | |
---|
| 1123 | /******************************************************************************/ |
---|
| 1124 | /*! |
---|
| 1125 | * Finish the indirect read operation that was completed or canceled. This |
---|
| 1126 | * function should be called before another indirect read is started. |
---|
| 1127 | * |
---|
| 1128 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1129 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1130 | */ |
---|
| 1131 | ALT_STATUS_CODE alt_qspi_indirect_read_finish(void); |
---|
| 1132 | |
---|
| 1133 | /******************************************************************************/ |
---|
| 1134 | /*! |
---|
| 1135 | * Cancel all indirect read transfers in progress. |
---|
| 1136 | * |
---|
| 1137 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1138 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1139 | */ |
---|
| 1140 | ALT_STATUS_CODE alt_qspi_indirect_read_cancel(void); |
---|
| 1141 | |
---|
| 1142 | /******************************************************************************/ |
---|
| 1143 | /*! |
---|
| 1144 | * Get the current indirect read SRAM fill level value. |
---|
| 1145 | * |
---|
| 1146 | * Returns the SRAM fill level for the indirect read partition in units of SRAM |
---|
| 1147 | * words (4 bytes). |
---|
| 1148 | * |
---|
| 1149 | * \returns The SRAM fill level for the indirect read partition in units of |
---|
| 1150 | * SRAM words (4 bytes). |
---|
| 1151 | */ |
---|
| 1152 | uint32_t alt_qspi_indirect_read_fill_level(void); |
---|
| 1153 | |
---|
| 1154 | /******************************************************************************/ |
---|
| 1155 | /*! |
---|
| 1156 | * Get the current indirect read watermark value. |
---|
| 1157 | * |
---|
| 1158 | * The watermark value (in bytes) represents the minimum fill level of the SRAM |
---|
| 1159 | * before a DMA peripheral access is permitted. When the SRAM fill level passes |
---|
| 1160 | * the watermark, an interrupt source is also generated. This can be disabled by |
---|
| 1161 | * writing a value of all zeroes. |
---|
| 1162 | * |
---|
| 1163 | * \returns The current indirect read watermark value. |
---|
| 1164 | */ |
---|
| 1165 | uint32_t alt_qspi_indirect_read_watermark_get(void); |
---|
| 1166 | |
---|
| 1167 | /******************************************************************************/ |
---|
| 1168 | /*! |
---|
| 1169 | * Set the indirect read watermark value. |
---|
| 1170 | * |
---|
| 1171 | * The watermark value (in bytes) represents the minimum fill level of the SRAM |
---|
| 1172 | * before a DMA peripheral access is permitted. When the SRAM fill level passes |
---|
| 1173 | * the watermark, an interrupt source is also generated. This can be disabled by |
---|
| 1174 | * writing a value of all zeroes. The watermark can only be set when no indirect |
---|
| 1175 | * read is in progress. |
---|
| 1176 | * |
---|
| 1177 | * \param watermark |
---|
| 1178 | * The watermark value (in bytes). |
---|
| 1179 | * |
---|
| 1180 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1181 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1182 | */ |
---|
| 1183 | ALT_STATUS_CODE alt_qspi_indirect_read_watermark_set(const uint32_t watermark); |
---|
| 1184 | |
---|
| 1185 | /******************************************************************************/ |
---|
| 1186 | /*! |
---|
| 1187 | * Returns true when an indirect read has completed otherwise false. |
---|
| 1188 | * |
---|
| 1189 | * \internal |
---|
| 1190 | * Returns Indirect Read Transfer Control Register bit 5 "Indirect Completion Status". |
---|
| 1191 | * \endinternal |
---|
| 1192 | * |
---|
| 1193 | * \returns Returns true when an indirect read has completed otherwise false. |
---|
| 1194 | */ |
---|
| 1195 | bool alt_qspi_indirect_read_is_complete(void); |
---|
| 1196 | |
---|
| 1197 | /******************************************************************************/ |
---|
| 1198 | /*! |
---|
| 1199 | * Starts an indirect write transfer. |
---|
| 1200 | * |
---|
| 1201 | * Initiates an indirect write transfer of the requested number of bytes to the |
---|
| 1202 | * designated flash address. |
---|
| 1203 | * |
---|
| 1204 | * After calling this function, flash data may be written to the QSPI SRAM |
---|
| 1205 | * buffer there is space via one of the following methods: |
---|
| 1206 | * * Directly from the AHB data slave interface at the configured AHB trigger |
---|
| 1207 | * address. If the requested space is not immediately available in the SRAM |
---|
| 1208 | * buffer then AHB wait states will be applied until the space becomes |
---|
| 1209 | * available. Alternatively, the data may be written to the AHB data slave |
---|
| 1210 | * as the SRAM is drained. The space in the SRAM buffer may be determined by |
---|
| 1211 | * an SRAM watermark interrupt notification or by polling the SRAM fill |
---|
| 1212 | * level and subtracting that value from the SRAM space devoted to writes. |
---|
| 1213 | * * Configuring and enabling the QSPI DMA peripheral controller. |
---|
| 1214 | * |
---|
| 1215 | * The following is a list of restrictions: |
---|
| 1216 | * * flash_addr must be word aligned. |
---|
| 1217 | * * num_bytes must be word aligned. |
---|
| 1218 | * * num_bytes must be 256 or below. This is due to a device specific |
---|
| 1219 | * limitation and may be lifted in the future. |
---|
| 1220 | * * The transfer must not cross the page (256 byte) addressing boundary. This |
---|
| 1221 | * restriction may be device specific and may be lifted in the future. |
---|
| 1222 | * |
---|
| 1223 | * \param flash_addr |
---|
| 1224 | * The flash destination address to write data to. |
---|
| 1225 | * |
---|
| 1226 | * \param num_bytes |
---|
| 1227 | * The number of bytes to write to the flash. |
---|
| 1228 | * |
---|
| 1229 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1230 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1231 | */ |
---|
| 1232 | ALT_STATUS_CODE alt_qspi_indirect_write_start(const uint32_t flash_addr, |
---|
| 1233 | const size_t num_bytes); |
---|
| 1234 | |
---|
| 1235 | /******************************************************************************/ |
---|
| 1236 | /*! |
---|
| 1237 | * Finish the indirect write operation that was completed or canceled. This |
---|
| 1238 | * function should be called before another indirect write is started. |
---|
| 1239 | * |
---|
| 1240 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1241 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1242 | */ |
---|
| 1243 | ALT_STATUS_CODE alt_qspi_indirect_write_finish(void); |
---|
| 1244 | |
---|
| 1245 | /******************************************************************************/ |
---|
| 1246 | /*! |
---|
| 1247 | * Cancel all indirect write transfers in progress. |
---|
| 1248 | * |
---|
| 1249 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1250 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1251 | */ |
---|
| 1252 | ALT_STATUS_CODE alt_qspi_indirect_write_cancel(void); |
---|
| 1253 | |
---|
| 1254 | /******************************************************************************/ |
---|
| 1255 | /*! |
---|
| 1256 | * Get the current indirect write SRAM fill level value. |
---|
| 1257 | * |
---|
| 1258 | * Returns the SRAM fill level for the indirect write partition in units of SRAM |
---|
| 1259 | * words (4 bytes). |
---|
| 1260 | * |
---|
| 1261 | * \returns The SRAM fill level for the indirect write partition in units of |
---|
| 1262 | * SRAM words (4 bytes). |
---|
| 1263 | */ |
---|
| 1264 | uint32_t alt_qspi_indirect_write_fill_level(void); |
---|
| 1265 | |
---|
| 1266 | /******************************************************************************/ |
---|
| 1267 | /*! |
---|
| 1268 | * Get the current indirect write watermark value. |
---|
| 1269 | * |
---|
| 1270 | * The watermark value (in bytes) represents the maximum fill level of the SRAM |
---|
| 1271 | * before a DMA peripheral access is permitted. When the SRAM fill level falls |
---|
| 1272 | * below the watermark, an interrupt is also generated. This can be disabled by |
---|
| 1273 | * writing a value of all ones. |
---|
| 1274 | * |
---|
| 1275 | * \returns The current indirect write watermark value. |
---|
| 1276 | */ |
---|
| 1277 | uint32_t alt_qspi_indirect_write_watermark_get(void); |
---|
| 1278 | |
---|
| 1279 | /******************************************************************************/ |
---|
| 1280 | /*! |
---|
| 1281 | * Set the indirect write watermark value. |
---|
| 1282 | * |
---|
| 1283 | * The watermark value (in bytes) represents the maximum fill level of the SRAM |
---|
| 1284 | * before a DMA peripheral access is permitted. When the SRAM fill level falls |
---|
| 1285 | * below the watermark, an interrupt is also generated. This can be disabled by |
---|
| 1286 | * writing a value of all ones. The watermark can only be set when no indirect |
---|
| 1287 | * write is in progress. |
---|
| 1288 | * |
---|
| 1289 | * \param watermark |
---|
| 1290 | * The watermark value (in bytes). |
---|
| 1291 | * |
---|
| 1292 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1293 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1294 | */ |
---|
| 1295 | ALT_STATUS_CODE alt_qspi_indirect_write_watermark_set(const uint32_t watermark); |
---|
| 1296 | |
---|
| 1297 | /******************************************************************************/ |
---|
| 1298 | /*! |
---|
| 1299 | * Returns true when an indirect write has completed otherwise false. |
---|
| 1300 | * |
---|
| 1301 | * \internal |
---|
| 1302 | * Returns Indirect Write Transfer Control Register bit 5 "Indirect Completion |
---|
| 1303 | * Status". |
---|
| 1304 | * \endinternal |
---|
| 1305 | * |
---|
| 1306 | * \returns Returns true when an indirect write has completed otherwise |
---|
| 1307 | * false. |
---|
| 1308 | */ |
---|
| 1309 | bool alt_qspi_indirect_write_is_complete(void); |
---|
| 1310 | |
---|
| 1311 | /******************************************************************************/ |
---|
| 1312 | /*! \addtogroup ALT_QSPI_CFG_SRAM SRAM Partition |
---|
| 1313 | * |
---|
| 1314 | * The SRAM local memory buffer is a 128 by 32-bit (512 total bytes) memory. The |
---|
| 1315 | * SRAM has two partitions, with the lower partition reserved for indirect read |
---|
| 1316 | * operations and the upper partition for indirect write operations. The size of |
---|
| 1317 | * the partitions is specified in the SRAM partition register, based on 32-bit |
---|
| 1318 | * word sizes. For example, to specify four bytes of storage, write the value 1. |
---|
| 1319 | * The value written to the indirect read partition size field ( addr ) defines |
---|
| 1320 | * the number of entries reserved for indirect read operations. For example, write |
---|
| 1321 | * the value 32 (0x20) to partition the 128-entry SRAM to 32 entries (25%) for |
---|
| 1322 | * read usage and 96 entries (75%) for write usage. |
---|
| 1323 | * |
---|
| 1324 | * The functions in this section provide accces to configure the SRAM read |
---|
| 1325 | * partition allocation. |
---|
| 1326 | * |
---|
| 1327 | * @{ |
---|
| 1328 | */ |
---|
| 1329 | |
---|
| 1330 | /*! |
---|
| 1331 | * The size of the onboard SRAM in bytes. |
---|
| 1332 | */ |
---|
| 1333 | #define ALT_QSPI_SRAM_FIFO_SIZE (512) |
---|
| 1334 | |
---|
| 1335 | /* |
---|
| 1336 | * The size of the onboard SRAM in entries. Each entry is word (32-bit) sized. |
---|
| 1337 | */ |
---|
| 1338 | #define ALT_QSPI_SRAM_FIFO_ENTRY_COUNT (512 / sizeof(uint32_t)) |
---|
| 1339 | |
---|
| 1340 | /******************************************************************************/ |
---|
| 1341 | /*! |
---|
| 1342 | * Get the entry count (words) of the indirect read partition in the QSPI |
---|
| 1343 | * controller SRAM. |
---|
| 1344 | * |
---|
| 1345 | * There is an additional word of read memory not in the SRAM but used to |
---|
| 1346 | * buffer the SRAM and the AHB. As such, the total on board memory buffer for |
---|
| 1347 | * indirect read is 1 more than the value reported by this function. |
---|
| 1348 | * |
---|
| 1349 | * \returns The count of 32-bit words of the indirect read partition in the |
---|
| 1350 | * QSPI controller SRAM. |
---|
| 1351 | * |
---|
| 1352 | * \internal |
---|
| 1353 | * The documentation states that the number of locations allocated to indirect |
---|
| 1354 | * read = SRAM_PARTITION_REG + 1. Cadence clarified that the +1 comes from an |
---|
| 1355 | * additional register slice for read's, implemented in FLOPs, which was done |
---|
| 1356 | * to avoid connection the SRAM directly to the AHB interface. This was done |
---|
| 1357 | * for performance / timing reasons. The +1 will not be included in the return |
---|
| 1358 | * value but documented as an additional entry. |
---|
| 1359 | * \endinternal |
---|
| 1360 | */ |
---|
| 1361 | uint32_t alt_qspi_sram_partition_get(void); |
---|
| 1362 | |
---|
| 1363 | /******************************************************************************/ |
---|
| 1364 | /*! |
---|
| 1365 | * Set the entry count (words) of the indirect read partition in the QSPI |
---|
| 1366 | * controller SRAM. |
---|
| 1367 | * |
---|
| 1368 | * Note: It is recommended that setting SRAM partition to 0 or 127 should be |
---|
| 1369 | * avoided although it is not prohibited. |
---|
| 1370 | * |
---|
| 1371 | * \param read_part_size |
---|
| 1372 | * The count of 32-bit words to allocate to the indirect read |
---|
| 1373 | * partition in the QSPI controller SRAM. |
---|
| 1374 | * |
---|
| 1375 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1376 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1377 | */ |
---|
| 1378 | ALT_STATUS_CODE alt_qspi_sram_partition_set(const uint32_t read_part_size); |
---|
| 1379 | |
---|
| 1380 | /*! @} */ |
---|
| 1381 | |
---|
| 1382 | /*! @} */ |
---|
| 1383 | |
---|
| 1384 | /******************************************************************************/ |
---|
| 1385 | /*! \addtogroup ALT_QSPI_ERASE Flash Erase |
---|
| 1386 | * |
---|
| 1387 | * The functions in this group are used to erase selected portions of a flash |
---|
| 1388 | * device. |
---|
| 1389 | * @{ |
---|
| 1390 | */ |
---|
| 1391 | |
---|
| 1392 | /******************************************************************************/ |
---|
| 1393 | /*! |
---|
| 1394 | * This function erases the designated flash device subsector. |
---|
| 1395 | * |
---|
| 1396 | * This function erases the flash device subsector containing the designated |
---|
| 1397 | * flash address. Any address within the subsector is valid. |
---|
| 1398 | * |
---|
| 1399 | * \param addr |
---|
| 1400 | * A flash address contained within the the subsector to be erased. |
---|
| 1401 | * |
---|
| 1402 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1403 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1404 | */ |
---|
| 1405 | ALT_STATUS_CODE alt_qspi_erase_subsector(const uint32_t addr); |
---|
| 1406 | |
---|
| 1407 | /******************************************************************************/ |
---|
| 1408 | /*! |
---|
| 1409 | * This function erases the designated flash device sector. |
---|
| 1410 | * |
---|
| 1411 | * This function erases the flash device sector containing the designated flash |
---|
| 1412 | * address. Any address within the sector is valid. |
---|
| 1413 | * |
---|
| 1414 | * \param addr |
---|
| 1415 | * A flash address contained within the the sector to be erased. |
---|
| 1416 | * |
---|
| 1417 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1418 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1419 | */ |
---|
| 1420 | ALT_STATUS_CODE alt_qspi_erase_sector(const uint32_t addr); |
---|
| 1421 | |
---|
| 1422 | /******************************************************************************/ |
---|
| 1423 | /*! |
---|
| 1424 | * This function erases the entire flash device. |
---|
| 1425 | * |
---|
| 1426 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1427 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1428 | */ |
---|
| 1429 | ALT_STATUS_CODE alt_qspi_erase_chip(void); |
---|
| 1430 | |
---|
| 1431 | /*! @} */ |
---|
| 1432 | |
---|
| 1433 | /******************************************************************************/ |
---|
| 1434 | /*! \addtogroup ALT_QSPI_DMA DMA Peripheral Interface |
---|
| 1435 | * |
---|
| 1436 | * The DMA peripheral request controller is only used for the indirect mode of |
---|
| 1437 | * operation where data is temporarily stored in the SRAM. The QSPI flash |
---|
| 1438 | * controller uses the DMA peripheral request interface to trigger the external |
---|
| 1439 | * DMA into performing data transfers between memory and the QSPI |
---|
| 1440 | * controller. |
---|
| 1441 | * |
---|
| 1442 | * There are two DMA peripheral request interfaces, one for indirect reads and |
---|
| 1443 | * one for indirect writes. The DMA peripheral request controller can issue two |
---|
| 1444 | * types of DMA requests, single or burst, to the external DMA. The number of |
---|
| 1445 | * bytes for each single or burst request is specified using the |
---|
| 1446 | * alt_qspi_dma_config_set(). The DMA peripheral request controller splits the |
---|
| 1447 | * total amount of data to be transferred into a number of DMA burst and single |
---|
| 1448 | * requests by dividing the total number of bytes by the number of bytes |
---|
| 1449 | * specified in the burst request, and then dividing the remainder by the number |
---|
| 1450 | * of bytes in a single request. |
---|
| 1451 | * |
---|
| 1452 | * When programming the DMA controller, the burst request size must match the |
---|
| 1453 | * burst request size set in the quad SPI controller to avoid quickly reaching |
---|
| 1454 | * an overflow or underflow condition. |
---|
| 1455 | * @{ |
---|
| 1456 | */ |
---|
| 1457 | |
---|
| 1458 | /******************************************************************************/ |
---|
| 1459 | /*! |
---|
| 1460 | * Disable the QSPI DMA peripheral interface. |
---|
| 1461 | * |
---|
| 1462 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1463 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1464 | */ |
---|
| 1465 | ALT_STATUS_CODE alt_qspi_dma_disable(void); |
---|
| 1466 | |
---|
| 1467 | /******************************************************************************/ |
---|
| 1468 | /*! |
---|
| 1469 | * Enable the QSPI DMA peripheral interface. |
---|
| 1470 | * |
---|
| 1471 | * Enable the QSPI DMA handshaking logic. When enabled the QSPI will trigger DMA |
---|
| 1472 | * transfer requests via the DMA peripheral interface. |
---|
| 1473 | * |
---|
| 1474 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1475 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1476 | */ |
---|
| 1477 | ALT_STATUS_CODE alt_qspi_dma_enable(void); |
---|
| 1478 | |
---|
| 1479 | /******************************************************************************/ |
---|
| 1480 | /*! |
---|
| 1481 | * Get the current DMA peripheral configuration. |
---|
| 1482 | * |
---|
| 1483 | * This function returns the QSPI DMA peripheral interface single and burst type |
---|
| 1484 | * transfer size configurations. |
---|
| 1485 | * |
---|
| 1486 | * \param single_type_sz |
---|
| 1487 | * [out] The number of bytes for each DMA single type |
---|
| 1488 | * request. Value must be a power of 2 between 1 and 32728. |
---|
| 1489 | * |
---|
| 1490 | * \param burst_type_sz |
---|
| 1491 | * [out] The number of bytes for each DMA burst type request. Value |
---|
| 1492 | * must be a power of 2 between 1 and 32728. |
---|
| 1493 | * |
---|
| 1494 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1495 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1496 | */ |
---|
| 1497 | ALT_STATUS_CODE alt_qspi_dma_config_get(uint32_t * single_type_sz, |
---|
| 1498 | uint32_t * burst_type_sz); |
---|
| 1499 | |
---|
| 1500 | /******************************************************************************/ |
---|
| 1501 | /*! |
---|
| 1502 | * Set the DMA peripheral configuration. |
---|
| 1503 | * |
---|
| 1504 | * This function configures the QSPI DMA peripheral interface single and burst |
---|
| 1505 | * type transfer sizes. The DMA configruation should be setup while the |
---|
| 1506 | * controller is idle. Because all transfers are required to be word aligned, |
---|
| 1507 | * the smallest DMA request is 4 bytes. |
---|
| 1508 | * |
---|
| 1509 | * This API requires that the QSPI controller be idle, as determined by |
---|
| 1510 | * alt_qspi_is_idle(). |
---|
| 1511 | * |
---|
| 1512 | * \param single_type_sz |
---|
| 1513 | * The number of bytes for each DMA single type request. Value must |
---|
| 1514 | * be a power of 2 between 4 and 32768. |
---|
| 1515 | * |
---|
| 1516 | * \param burst_type_sz |
---|
| 1517 | * The number of bytes for each DMA burst type request. Value must |
---|
| 1518 | * be a power of 2 between 4 and 32768. Bursts must be equal or |
---|
| 1519 | * larger than single requests. |
---|
| 1520 | * |
---|
| 1521 | * \retval ALT_E_SUCCESS Indicates successful completion. |
---|
| 1522 | * \retval ALT_E_ERROR Indicates an error occurred. |
---|
| 1523 | */ |
---|
| 1524 | ALT_STATUS_CODE alt_qspi_dma_config_set(const uint32_t single_type_sz, |
---|
| 1525 | const uint32_t burst_type_sz); |
---|
| 1526 | |
---|
| 1527 | |
---|
| 1528 | /*! @} */ |
---|
| 1529 | |
---|
| 1530 | /*! @} */ |
---|
| 1531 | |
---|
| 1532 | #ifdef __cplusplus |
---|
| 1533 | } |
---|
| 1534 | #endif /* __cplusplus */ |
---|
| 1535 | #endif /* __ALT_QSPI_H__ */ |
---|