LXR |
|
|
|
|||
File indexing completed on 2025-05-11 08:22:43
0001 /** 0002 * @file 0003 * 0004 * @ingroup RTEMSBSPsARMCycVContrib 0005 */ 0006 0007 /****************************************************************************** 0008 * 0009 * Copyright 2013 Altera Corporation. All Rights Reserved. 0010 * 0011 * Redistribution and use in source and binary forms, with or without 0012 * modification, are permitted provided that the following conditions are met: 0013 * 0014 * 1. Redistributions of source code must retain the above copyright notice, 0015 * this list of conditions and the following disclaimer. 0016 * 0017 * 2. Redistributions in binary form must reproduce the above copyright notice, 0018 * this list of conditions and the following disclaimer in the documentation 0019 * and/or other materials provided with the distribution. 0020 * 0021 * 3. The name of the author may not be used to endorse or promote products 0022 * derived from this software without specific prior written permission. 0023 * 0024 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR 0025 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 0026 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO 0027 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 0028 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 0029 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 0030 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 0031 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 0032 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 0033 * OF SUCH DAMAGE. 0034 * 0035 ******************************************************************************/ 0036 0037 /****************************************************************************** 0038 * 0039 * !!!! Customer Be Aware, Exception!!! 0040 * 0041 * 1. Qspi Direct Access Mode is not working! 0042 * 0043 * This is because the qspi flash memory installed on our DevKit board, Micro 0044 * part N25Q00xx, 8 Gb, is not completely compatible with our embedded Synopsis 0045 * QSPI controller IP. Therefore there is no viable direct access code offered 0046 * in the lib. All the memory rea/write functionality is offered with indirect 0047 * access only. 0048 * 0049 * Should you install a different flash memory part in your custom board, and 0050 * wondering wether direct access mode works, please contact with us. 0051 * 0052 ******************************************************************************/ 0053 0054 /*! \file 0055 * Altera - QSPI Flash Controller Module 0056 */ 0057 0058 #ifndef __ALT_QSPI_H__ 0059 #define __ALT_QSPI_H__ 0060 0061 #include <bsp/hwlib.h> 0062 0063 #ifdef __cplusplus 0064 extern "C" 0065 { 0066 #endif /* __cplusplus */ 0067 0068 /******************************************************************************/ 0069 /*! \addtogroup ALT_QSPI QSPI Flash Controller Module 0070 * 0071 * This module defines a low level driver API for the hardware processor system 0072 * (HPS) quad serial peripheral interface (QSPI) flash controller for access to 0073 * serial NOR flash devices. The quad SPI flash controller supports standard SPI 0074 * flash devices as well as high-performance dual and quad SPI flash 0075 * devices. 0076 * 0077 * @{ 0078 */ 0079 0080 /******************************************************************************/ 0081 /*! \addtogroup ALT_QSPI_CSR General Control and Status Functions 0082 * 0083 * The declarations and functions in this group provide general purpose control 0084 * and status functions for the QSPI Flash Controller. 0085 * 0086 * @{ 0087 */ 0088 0089 /******************************************************************************/ 0090 /*! 0091 * Initialize the QSPI flash controller for use. 0092 * 0093 * \internal 0094 * Implementation Notes: 0095 * * The QSPI Controller has been designed to wake up in a state that is 0096 * suitable for performing basic reads and writes using the direct access 0097 * controller. 0098 * * Bring out of reset 0099 * * QSPI reference clock validation 0100 * * See Programmer's Guide, Configuring the QSPI Controller for use after 0101 * reset, in QSPI_FLASH_CTRL for full initialization details. 0102 * \endinternal 0103 * 0104 * \retval ALT_E_SUCCESS Indicates successful completion. 0105 * \retval ALT_E_ERROR Indicates an error occurred. 0106 */ 0107 ALT_STATUS_CODE alt_qspi_init(void); 0108 0109 /******************************************************************************/ 0110 /*! 0111 * Uninitialize the QSPI flash controller. 0112 * 0113 * Uninitialize the QSPI flash controller by cancelling any indirect transfers 0114 * in progress and putting the QSPI controller into reset. 0115 * 0116 * \retval ALT_E_SUCCESS Indicates successful completion. 0117 * \retval ALT_E_ERROR Indicates an error occurred. 0118 */ 0119 ALT_STATUS_CODE alt_qspi_uninit(void); 0120 0121 /******************************************************************************/ 0122 /*! 0123 * Disable the QSPI Controller. 0124 * 0125 * Disable the QSPI once the current transfer of the data word (FF_W) is 0126 * complete. All output enables are inactive and all pins are set to input 0127 * mode. 0128 * 0129 * \retval ALT_E_SUCCESS Indicates successful completion. 0130 * \retval ALT_E_ERROR Indicates an error occurred. 0131 */ 0132 ALT_STATUS_CODE alt_qspi_disable(void); 0133 0134 /******************************************************************************/ 0135 /*! 0136 * Enable the QSPI Controller. 0137 * 0138 * \retval ALT_E_SUCCESS Indicates successful completion. 0139 * \retval ALT_E_ERROR Indicates an error occurred. 0140 */ 0141 ALT_STATUS_CODE alt_qspi_enable(void); 0142 0143 /******************************************************************************/ 0144 /*! 0145 * This type definition enumerates the interrupt status conditions for the QSPI 0146 * controller. 0147 * 0148 * The enumerations serve as masks for the QSPI controller events that can be 0149 * set when the designated conditions occur and the corresponding event is 0150 * enabled. When any of these event source conditions are true, the \b 0151 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt output is asserted high. 0152 * 0153 * Interrupt sources are cleared when software calls alt_qspi_int_clear(). The 0154 * interrupt sources are individually maskable using alt_qspi_int_disable() and 0155 * alt_qspi_int_enable(). 0156 */ 0157 typedef enum ALT_QSPI_INT_STATUS_e 0158 { 0159 /*! 0160 * Mode fail M - indicates the voltage on pin n_ss_in is inconsistent with 0161 * the SPI mode. Set = 1 if n_ss_in is low in master mode (multi-master 0162 * contention). These conditions will clear the spi_enable bit and disable 0163 * the SPI. 0164 * * 0 = no mode fault has been detected. 0165 * * 1 = a mode fault has occurred. 0166 */ 0167 ALT_QSPI_INT_STATUS_MODE_FAIL = (0x1 << 0), 0168 0169 /*! 0170 * Underflow Detected. 0171 * * 0 = no underflow has been detected. 0172 * * 1 = underflow is detected and an attempt to transfer data is made 0173 * when the small TX FIFO is empty. This may occur when AHB write 0174 * data is being supplied too slowly to keep up with the requested 0175 * write operation. 0176 */ 0177 ALT_QSPI_INT_STATUS_UFL = (0x1 << 1), 0178 0179 /*! 0180 * Controller has completed last triggered indirect operation. 0181 */ 0182 ALT_QSPI_INT_STATUS_IDAC_OP_COMPLETE = (0x1 << 2), 0183 0184 /*! 0185 * Indirect operation was requested but could not be accepted. Two indirect 0186 * operations already in storage. 0187 */ 0188 ALT_QSPI_INT_STATUS_IDAC_OP_REJECT = (0x1 << 3), 0189 0190 /*! 0191 * Write to protected area was attempted and rejected. 0192 */ 0193 ALT_QSPI_INT_STATUS_WR_PROT_VIOL = (0x1 << 4), 0194 0195 /*! 0196 * Illegal AHB Access Detected. AHB write wrapping bursts and the use of 0197 * SPLIT/RETRY accesses will cause this interrupt to trigger. 0198 */ 0199 ALT_QSPI_INT_STATUS_ILL_AHB_ACCESS = (0x1 << 5), 0200 0201 /*! 0202 * Indirect Transfer Watermark Level Breached. 0203 */ 0204 ALT_QSPI_INT_STATUS_IDAC_WTRMK_TRIG = (0x1 << 6), 0205 0206 /*! 0207 * Receive Overflow. This should only occur in Legacy SPI mode. 0208 * 0209 * Set if an attempt is made to push the RX FIFO when it is full. This bit 0210 * is reset only by a system reset and cleared only when this register is 0211 * read. If a new push to the RX FIFO occurs coincident with a register read 0212 * this flag will remain set. 0213 * * 0 = no overflow has been detected. 0214 * * 1 = an overflow has occurred. 0215 */ 0216 ALT_QSPI_INT_STATUS_RX_OVF = (0x1 << 7), 0217 0218 /*! 0219 * Small TX FIFO not full (current FIFO status). Can be ignored in non-SPI 0220 * legacy mode. 0221 * * 0 = FIFO has >= THRESHOLD entries. 0222 * * 1 = FIFO has < THRESHOLD entries. 0223 */ 0224 ALT_QSPI_INT_STATUS_TX_FIFO_NOT_FULL = (0x1 << 8), 0225 0226 /*! 0227 * Small TX FIFO full (current FIFO status). Can be ignored in non-SPI 0228 * legacy mode. 0229 * * 0 = FIFO is not full. 0230 * * 1 = FIFO is full. 0231 */ 0232 ALT_QSPI_INT_STATUS_TX_FIFO_FULL = (0x1 << 9), 0233 0234 /*! 0235 * Small RX FIFO not empty (current FIFO status). Can be ignored in non-SPI 0236 * legacy mode. 0237 * * 0 = FIFO has < RX THRESHOLD entries. 0238 * * 1 = FIFO has >= THRESHOLD entries. 0239 */ 0240 ALT_QSPI_INT_STATUS_RX_FIFO_NOT_EMPTY = (0x1 << 10), 0241 0242 /*! 0243 * Small RX FIFO full (current FIFO status). Can be ignored in non-SPI 0244 * legacy mode. 0245 * * 0 = FIFO is not full. 0246 * * 1 = FIFO is full. 0247 */ 0248 ALT_QSPI_INT_STATUS_RX_FIFO_FULL = (0x1 << 11), 0249 0250 /*! 0251 * Indirect Read partition of SRAM is full and unable to immediately 0252 * complete indirect operation. 0253 */ 0254 ALT_QSPI_INT_STATUS_IDAC_RD_FULL = (0x1 << 12) 0255 0256 } ALT_QSPI_INT_STATUS_t; 0257 0258 /******************************************************************************/ 0259 /*! 0260 * Returns the QSPI controller interrupt status register value. 0261 * 0262 * This function returns the current value of the QSPI controller interrupt 0263 * status register value which reflects the current QSPI controller status 0264 * conditions. 0265 * 0266 * \returns The current value of the QSPI controller interrupt status 0267 * register value which reflects the current QSPI controller status 0268 * conditions as defined by the \ref ALT_QSPI_INT_STATUS_t mask. 0269 * If the corresponding bit is set then the condition is asserted. 0270 */ 0271 uint32_t alt_qspi_int_status_get(void); 0272 0273 /******************************************************************************/ 0274 /*! 0275 * Clears the specified QSPI controller interrupt status conditions identified 0276 * in the mask. 0277 * 0278 * This function clears one or more of the status conditions as contributors to 0279 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. 0280 * 0281 * \param mask 0282 * Specifies the QSPI interrupt status conditions to clear. \e 0283 * mask is a mask of logically OR'ed \ref ALT_QSPI_INT_STATUS_t 0284 * values that designate the status conditions to clear. 0285 * 0286 * \retval ALT_E_SUCCESS Indicates successful completion. 0287 * \retval ALT_E_ERROR Indicates an error occurred. 0288 */ 0289 ALT_STATUS_CODE alt_qspi_int_clear(const uint32_t mask); 0290 0291 /******************************************************************************/ 0292 /*! 0293 * Disable the specified QSPI controller interrupt status conditions identified 0294 * in the mask. 0295 * 0296 * This function disables one or more of the status conditions as contributors 0297 * to the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. 0298 * 0299 * This API requires that the QSPI controller be idle, as determined by 0300 * alt_qspi_is_idle(). 0301 * 0302 * NOTE: A cleared bit for any status condition in the mask value does not have 0303 * the effect of enabling it as a contributor to the \b 0304 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function 0305 * alt_qspi_int_enable() is used to enable status source conditions. 0306 * 0307 * \param mask 0308 * Specifies the status conditions to disable as interrupt source 0309 * contributors. \e mask is a mask of logically OR'ed 0310 * \ref ALT_QSPI_INT_STATUS_t values that designate the status 0311 * conditions to disable. 0312 * 0313 * \retval ALT_E_SUCCESS Indicates successful completion. 0314 * \retval ALT_E_ERROR Indicates an error occurred. 0315 */ 0316 ALT_STATUS_CODE alt_qspi_int_disable(const uint32_t mask); 0317 0318 /******************************************************************************/ 0319 /*! 0320 * Enable the specified QSPI controller interrupt status conditions identified 0321 * in the mask. 0322 * 0323 * This function enables one or more of the status conditions as contributors to 0324 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. 0325 * 0326 * This API requires that the QSPI controller be idle, as determined by 0327 * alt_qspi_is_idle(). 0328 * 0329 * NOTE: A cleared bit for any status condition in the mask value does not have 0330 * the effect of disabling it as a contributor to the \b 0331 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function 0332 * alt_qspi_int_disable() is used to disable status source conditions. 0333 * 0334 * \param mask 0335 * Specifies the status conditions to enable as interrupt source 0336 * contributors. \e mask is a mask of logically OR'ed 0337 * \ref ALT_QSPI_INT_STATUS_t values that designate the status 0338 * conditions to enable. 0339 * 0340 * \retval ALT_E_SUCCESS Indicates successful completion. 0341 * \retval ALT_E_ERROR Indicates an error occurred. 0342 */ 0343 ALT_STATUS_CODE alt_qspi_int_enable(const uint32_t mask); 0344 0345 /******************************************************************************/ 0346 /*! 0347 * Returns true the serial interface and QSPI pipeline is IDLE. 0348 * 0349 * \returns Returns true the serial interface and QSPI pipeline is IDLE. 0350 */ 0351 bool alt_qspi_is_idle(void); 0352 0353 /*! @} */ 0354 0355 /******************************************************************************/ 0356 /*! \addtogroup ALT_QSPI_GP_BLKIO General Purpose Block I/O 0357 * 0358 * The functions in this group provide general purpose block read and 0359 * write flash functions. 0360 * 0361 * \internal 0362 * These functions use Indirect Read/Write transfers to read and write block 0363 * data to the flash device. An outline of the operational flow for these 0364 * operations can be found in: 0365 * //depot/soc/hhp_sw/baremetal_fw/drivers/qspi/qspi.c 0366 * 0367 * The general flow for an indirect block read is to call 0368 * qspi_configure_mode_indirect_read_start() to initiate the read transfer from 0369 * the flash device into the SRAM buffer and follow with a call to either 0370 * qpsi_write_sram_fifo_poll() or qspi_read_sram_fifo_irq() to copy the data 0371 * from SRAM into the user's buffer. 0372 * 0373 * The general flow for an indirect block write is to call 0374 * qspi_configure_mode_indirect_write_start() to initiate the write transfer 0375 * from the SRAM buffer to the flash device and follow with a call to either 0376 * qpsi_write_sram_fifo_poll() or qspi_write_sram_fifo_irq() to fill the SRAM 0377 * buffer with the user's data as space becomes available. 0378 * \endinternal 0379 * 0380 * @{ 0381 */ 0382 0383 /******************************************************************************/ 0384 /*! 0385 * Read a block of data from the specified flash address. 0386 * 0387 * Reads a block of \e n data bytes from the flash \e src address into the user 0388 * supplied \e dest buffer. The memory address, flash address, and size must be 0389 * word aligned. 0390 * 0391 * \param dest 0392 * The address of a caller supplied destination buffer large enough 0393 * to contain the requested block of flash data. 0394 * 0395 * \param src 0396 * The flash device address to start reading data from. 0397 * 0398 * \param size 0399 * The requested number of data bytes to read from the flash device. 0400 * 0401 * \retval ALT_E_SUCCESS Indicates successful completion. 0402 * \retval ALT_E_ERROR Indicates an error occurred. 0403 */ 0404 ALT_STATUS_CODE alt_qspi_read(void * dest, uint32_t src, size_t size); 0405 0406 /******************************************************************************/ 0407 /*! 0408 * Write a block of data to the specified flash address. 0409 * 0410 * Writes a block of \e n data bytes to the flash \e dest address from the 0411 * designated \e src buffer. The applicable destination flash address range 0412 * should have been erased prior to calling this function. The flash address, 0413 * memory address, and size must be word aligned. 0414 * 0415 * \param dest 0416 * The destination flash address to begin writing data to. 0417 * 0418 * \param src 0419 * The source address to start writing data from. 0420 * 0421 * \param size 0422 * The requested number of data bytes to write to the flash device. 0423 * 0424 * \retval ALT_E_SUCCESS Indicates successful completion. 0425 * \retval ALT_E_ERROR Indicates an error occurred. 0426 */ 0427 ALT_STATUS_CODE alt_qspi_write(uint32_t dest, const void * src, size_t size); 0428 0429 /*! @} */ 0430 0431 /******************************************************************************/ 0432 /*! \addtogroup ALT_QSPI_DEV_CFG Flash Device Configuration 0433 * 0434 * The declarations and functions in this group are used to configure the QSPI 0435 * controller interface to external flash devices. 0436 * 0437 * The following steps describe how to initialize and configure the 0438 * QSPI controller to operate with a flash device. 0439 * 0440 * * Wait until any pending QSPI operations have completed. 0441 * * Disable the QSPI controller using alt_qspi_disable(). 0442 * * Configure the device for optimal read transaction performance using 0443 * alt_qspi_device_read_config_set(). 0444 * * Configure the device for optimal write transaction performance using 0445 * alt_qspi_device_write_config_set(). 0446 * * Enable (alt_qspi_mode_bit_disable()) or disable 0447 * (alt_qspi_mode_bit_disable()) the mode bits per the device 0448 * requirements. If mode bits are enabled, then configure the mode 0449 * bit values using alt_qspi_mode_bit_config_set(). 0450 * * Configure the device size and write protection information using 0451 * alt_qspi_device_size_config_set(). 0452 * * Configure the QSPI device delay and timing settings using 0453 * alt_qspi_device_write_config_set(). 0454 * * Configure the baud divisor setting to define the required clock frequency 0455 * to the device using alt_qspi_baud_rate_div_set(). 0456 * * Enable the QSPI controller using alt_qspi_enable(). 0457 * 0458 * @{ 0459 */ 0460 0461 /******************************************************************************/ 0462 /*! 0463 * This type enumerates the operational modes the QSPI controller can be 0464 * configured for. It may apply to instruction, address, and/or data width 0465 * interactions between the QSPI controller and the flash device. 0466 */ 0467 typedef enum ALT_QSPI_MODE_e 0468 { 0469 ALT_QSPI_MODE_SINGLE = 0, /*!< Use Standard Single SPI (SIO-SPI) mode (bits 0470 * always transferred into the device on DQ0 0471 * only). Supported by all SPI flash devices. 0472 */ 0473 ALT_QSPI_MODE_DUAL = 1, /*!< Use Dual SPI (DIO-SPI) SPI mode where bits are 0474 * transferred on DQ0 and DQ1. 0475 */ 0476 ALT_QSPI_MODE_QUAD = 2 /*!< Use Dual SPI (QIO-SPI) SPI mode where bits are 0477 * transferred on DQ0, DQ1, DQ3, and DQ3. 0478 */ 0479 } ALT_QSPI_MODE_t; 0480 0481 /******************************************************************************/ 0482 /*! 0483 * This type enumerates the mode configurations available for driving the 0484 * ss_n[3:0] device chip selects. The chip selects may be controlled as either 0485 * in a '1 of 4' or '4 to 16 decode' mode. 0486 */ 0487 typedef enum ALT_QSPI_CS_MODE_e 0488 { 0489 ALT_QSPI_CS_MODE_SINGLE_SELECT = 0, /*!< Select 1 of 4 chip select ss_n[3:0] 0490 */ 0491 ALT_QSPI_CS_MODE_DECODE = 1 /*!< Select external 4 to 16 decode of 0492 * ss_n[3:0]. 0493 */ 0494 } ALT_QSPI_CS_MODE_t; 0495 0496 /******************************************************************************/ 0497 /*! 0498 * This type enumerates the QSPI controller master baud rate divisor selections. 0499 */ 0500 typedef enum ALT_QSPI_BAUD_DIV_e 0501 { 0502 ALT_QSPI_BAUD_DIV_2 = 0x0, /*!< Divide by 2 */ 0503 ALT_QSPI_BAUD_DIV_4 = 0x1, /*!< Divide by 4 */ 0504 ALT_QSPI_BAUD_DIV_6 = 0x2, /*!< Divide by 6 */ 0505 ALT_QSPI_BAUD_DIV_8 = 0x3, /*!< Divide by 8 */ 0506 ALT_QSPI_BAUD_DIV_10 = 0x4, /*!< Divide by 10 */ 0507 ALT_QSPI_BAUD_DIV_12 = 0x5, /*!< Divide by 12 */ 0508 ALT_QSPI_BAUD_DIV_14 = 0x6, /*!< Divide by 14 */ 0509 ALT_QSPI_BAUD_DIV_16 = 0x7, /*!< Divide by 16 */ 0510 ALT_QSPI_BAUD_DIV_18 = 0x8, /*!< Divide by 18 */ 0511 ALT_QSPI_BAUD_DIV_20 = 0x9, /*!< Divide by 20 */ 0512 ALT_QSPI_BAUD_DIV_22 = 0xA, /*!< Divide by 22 */ 0513 ALT_QSPI_BAUD_DIV_24 = 0xB, /*!< Divide by 24 */ 0514 ALT_QSPI_BAUD_DIV_26 = 0xC, /*!< Divide by 26 */ 0515 ALT_QSPI_BAUD_DIV_28 = 0xD, /*!< Divide by 28 */ 0516 ALT_QSPI_BAUD_DIV_30 = 0xE, /*!< Divide by 30 */ 0517 ALT_QSPI_BAUD_DIV_32 = 0xF /*!< Divide by 32 */ 0518 } ALT_QSPI_BAUD_DIV_t; 0519 0520 /******************************************************************************/ 0521 /*! 0522 * Device Size Configuration 0523 * 0524 * This type defines the structure used to specify flash device size and write 0525 * protect regions. 0526 */ 0527 typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s 0528 { 0529 uint32_t block_size; /*!< Number of bytes per device block. The 0530 * number is specified as a power of 2. 0531 * That is 0 = 1 byte, 1 = 2 bytes, ... 0532 * 16 = 65535 bytes, etc. 0533 */ 0534 uint32_t page_size; /*!< Number of bytes per device page. This 0535 * is required by the controller for 0536 * performing flash writes up to and 0537 * across page boundaries. 0538 */ 0539 uint32_t addr_size; /*!< Number of bytes used for the flash 0540 * address. The value is \e n + 1 0541 * based. That is 0 = 1 byte, 1 = 2 bytes, 0542 * 2 = 3 bytes, 3 = 4 bytes. 0543 */ 0544 uint32_t lower_wrprot_block; /*!< The block number that defines the lower 0545 * block in the range of blocks that is 0546 * protected from writing. This field 0547 * is ignored it write protection is 0548 * disabled. 0549 */ 0550 uint32_t upper_wrprot_block; /*!< The block number that defines the upper 0551 * block in the range of blocks that is 0552 * protected from writing. This field 0553 * is ignored it write protection is 0554 * disabled. 0555 */ 0556 bool wrprot_enable; /*!< The write region enable value. A value 0557 * of \b true enables write protection 0558 * on the region specified by the 0559 * \e lower_wrprot_block and 0560 * \e upper_wrprot_block range. 0561 */ 0562 } ALT_QSPI_DEV_SIZE_CONFIG_t; 0563 0564 /******************************************************************************/ 0565 /*! 0566 * This type enumerates the QSPI clock phase activity options outside the SPI 0567 * word. 0568 */ 0569 typedef enum ALT_QSPI_CLK_PHASE_e 0570 { 0571 ALT_QSPI_CLK_PHASE_ACTIVE = 0, /*!< The SPI clock is active outside the 0572 * word 0573 */ 0574 ALT_QSPI_CLK_PHASE_INACTIVE = 1 /*!< The SPI clock is inactive outside the 0575 * word 0576 */ 0577 } ALT_QSPI_CLK_PHASE_t; 0578 0579 /******************************************************************************/ 0580 /*! 0581 * This type enumerates the QSPI clock polarity options outside the SPI word. 0582 */ 0583 typedef enum ALT_QSPI_CLK_POLARITY_e 0584 { 0585 ALT_QSPI_CLK_POLARITY_LOW = 0, /*!< SPI clock is quiescent low outside the 0586 * word. 0587 */ 0588 ALT_QSPI_CLK_POLARITY_HIGH = 1 /*!< SPI clock is quiescent high outside the 0589 * word. 0590 */ 0591 } ALT_QSPI_CLK_POLARITY_t; 0592 0593 /******************************************************************************/ 0594 /*! 0595 * QSPI Controller Timing Configuration 0596 * 0597 * This type defines the structure used to configure timing paramaters used by 0598 * the QSPI controller to communicate with a target flash device. 0599 * 0600 * All timing values are defined in cycles of the SPI master ref clock. 0601 */ 0602 typedef struct ALT_QSPI_TIMING_CONFIG_s 0603 { 0604 ALT_QSPI_CLK_PHASE_t clk_phase; /*!< Selects whether the clock is in an 0605 * active or inactive phase outside the 0606 * SPI word. 0607 */ 0608 0609 ALT_QSPI_CLK_POLARITY_t clk_pol; /*!< Selects whether the clock is quiescent 0610 * low or high outside the SPI word. 0611 */ 0612 0613 uint32_t cs_da; /*!< Chip Select De-Assert. Added delay in 0614 * master reference clocks for the length 0615 * that the master mode chip select 0616 * outputs are de-asserted between 0617 * transactions. If CSDA = \e X, then the 0618 * chip select de-assert time will be: 1 0619 * sclk_out + 1 ref_clk + \e X ref_clks. 0620 */ 0621 uint32_t cs_dads; /*!< Chip Select De-Assert Different 0622 * Slaves. Delay in master reference 0623 * clocks between one chip select being 0624 * de-activated and the activation of 0625 * another. This is used to ensure a quiet 0626 * period between the selection of two 0627 * different slaves. CSDADS is only 0628 * relevant when switching between 2 0629 * different external flash devices. If 0630 * CSDADS = \e X, then the delay will be: 0631 * 1 sclk_out + 3 ref_clks + \e X 0632 * ref_clks. 0633 */ 0634 uint32_t cs_eot; /*!< Chip Select End Of Transfer. Delay in 0635 * master reference clocks between last 0636 * bit of current transaction and 0637 * de-asserting the device chip select 0638 * (n_ss_out). By default (when CSEOT=0), 0639 * the chip select will be de-asserted on 0640 * the last falling edge of sclk_out at 0641 * the completion of the current 0642 * transaction. If CSEOT = \e X, then chip 0643 * selected will de-assert \e X ref_clks 0644 * after the last falling edge of 0645 * sclk_out. 0646 */ 0647 uint32_t cs_sot; /*!< Chip Select Start Of Transfer. Delay in 0648 * master reference clocks between setting 0649 * n_ss_out low and first bit transfer. By 0650 * default (CSSOT=0), chip select will be 0651 * asserted half a SCLK period before the 0652 * first rising edge of sclk_out. If CSSOT 0653 * = \e X, chip select will be asserted 0654 * half an sclk_out period before the 0655 * first rising edge of sclk_out + \e X 0656 * ref_clks. 0657 */ 0658 0659 uint32_t rd_datacap; /*!< The additional number of read data 0660 * capture cycles (ref_clk) that should be 0661 * applied to the internal read data 0662 * capture circuit. The large 0663 * clock-to-out delay of the flash memory 0664 * together with trace delays as well as 0665 * other device delays may impose a 0666 * maximum flash clock frequency which is 0667 * less than the flash memory device 0668 * itself can operate at. To compensate, 0669 * software should set this register to a 0670 * value that guarantees robust data 0671 * captures. 0672 */ 0673 } ALT_QSPI_TIMING_CONFIG_t; 0674 0675 /******************************************************************************/ 0676 /*! 0677 * Device Instruction Configuration 0678 * 0679 * This type defines a structure for specifying the optimal instruction set 0680 * configuration to use with a target flash device. 0681 */ 0682 typedef struct ALT_QSPI_DEV_INST_CONFIG_s 0683 { 0684 uint32_t op_code; /*!< The read or write op code to use 0685 * for the device transaction. 0686 */ 0687 ALT_QSPI_MODE_t inst_type; /*!< Instruction mode type for the 0688 * controller to use with the 0689 * device. The instruction type 0690 * applies to all instructions 0691 * (reads and writes) issued from 0692 * either the Direct Access 0693 * Controller or the Indirect 0694 * Acces Controller. 0695 */ 0696 ALT_QSPI_MODE_t addr_xfer_type; /*!< Address transfer mode type. The 0697 * value of this field is ignored 0698 * if the \e inst_type data member 0699 * is set to anything other than 0700 * ALT_QSPI_MODE_SINGLE. In that 0701 * case, the addr_xfer_type 0702 * assumes the same mode as the \e 0703 * inst_type. 0704 */ 0705 ALT_QSPI_MODE_t data_xfer_type; /*!< Data transfer mode type. The 0706 * value of this field is ignored 0707 * if the \e inst_type data member 0708 * is set to anything other than 0709 * ALT_QSPI_MODE_SINGLE. In that 0710 * case, the data_xfer_type 0711 * assumes the same mode as the \e 0712 * inst_type. 0713 */ 0714 uint32_t dummy_cycles; /*!< Number of dummy clock cycles 0715 * required by device for a read 0716 * or write instruction. 0717 */ 0718 0719 } ALT_QSPI_DEV_INST_CONFIG_t; 0720 0721 /******************************************************************************/ 0722 /*! 0723 * Get the current value of the QSPI master baud rate divisor. 0724 * 0725 * \returns The value of the QSPI master baud rate divisor. 0726 */ 0727 ALT_QSPI_BAUD_DIV_t alt_qspi_baud_rate_div_get(void); 0728 0729 /******************************************************************************/ 0730 /*! 0731 * Set the current value of the QSPI master baud rate divisor. 0732 * 0733 * Sets the value of the QSPI master baud rate divisor. 0734 * 0735 * \param baud_rate_div 0736 * The master baud rate divisor. Valid range includes 0737 * even values 2 to 32. 0738 * 0739 * \retval ALT_E_SUCCESS Indicates successful completion. 0740 * \retval ALT_E_ERROR Indicates an error occurred. 0741 */ 0742 ALT_STATUS_CODE alt_qspi_baud_rate_div_set(const ALT_QSPI_BAUD_DIV_t baud_rate_div); 0743 0744 /******************************************************************************/ 0745 /*! 0746 * Get the current QSPI device peripheral chip select output and decode function 0747 * configuration values. 0748 * 0749 * \param cs 0750 * [out] The chip select line output values. 0751 * 0752 * \param cs_mode 0753 * [out] The decode mode to use for the chip selects. 0754 * 0755 * \retval ALT_E_SUCCESS Indicates successful completion. 0756 * \retval ALT_E_ERROR Indicates an error occurred. 0757 */ 0758 ALT_STATUS_CODE alt_qspi_chip_select_config_get(uint32_t* cs, ALT_QSPI_CS_MODE_t* cs_mode); 0759 0760 /******************************************************************************/ 0761 /*! 0762 * Set the QSPI device peripheral chip select outputs and decode function 0763 * configuration. 0764 * 0765 * The chip select lines output values operate according to the selected chip 0766 * select decode mode. If \e cs_mode is ALT_QSPI_CS_MODE_SINGLE_SELECT then 0767 * cs[3:0] are output thus: 0768 * 0769 * cs[3:0] | n_ss_out[3:0] 0770 * :---------|:---------------------------- 0771 * xxx0 | 1110 0772 * xx01 | 1101 0773 * x011 | 1011 0774 * 0111 | 0111 0775 * 1111 | 1111 (no peripheral selected) 0776 * 0777 * Otherwise if \e cs_mode is ALT_QSPI_CS_MODE_DECODE then cs[3:0] directly 0778 * drives n_ss_out[3:0]. 0779 * 0780 * \param cs 0781 * The chip select line output values. 0782 * 0783 * \param cs_mode 0784 * The decode mode to use for the chip selects. 0785 * 0786 * \retval ALT_E_SUCCESS Indicates successful completion. 0787 * \retval ALT_E_ERROR Indicates an error occurred. 0788 */ 0789 ALT_STATUS_CODE alt_qspi_chip_select_config_set(const uint32_t cs, 0790 const ALT_QSPI_CS_MODE_t cs_mode); 0791 0792 /******************************************************************************/ 0793 /*! 0794 * Disable the mode bits from being sent after the address bytes. 0795 * 0796 * Prevent the mode bits defined in the Mode Bit Configuration register from 0797 * being sent following the address bytes. 0798 * 0799 * \retval ALT_E_SUCCESS Indicates successful completion. 0800 * \retval ALT_E_ERROR Indicates an error occurred. 0801 */ 0802 ALT_STATUS_CODE alt_qspi_mode_bit_disable(void); 0803 0804 /******************************************************************************/ 0805 /*! 0806 * Enable the mode bits to be sent after the address bytes. 0807 * 0808 * Ensure the mode bits defined in the Mode Bit Configuration register to 0809 * be sent following the address bytes. 0810 * 0811 * \retval ALT_E_SUCCESS Indicates successful completion. 0812 * \retval ALT_E_ERROR Indicates an error occurred. 0813 */ 0814 ALT_STATUS_CODE alt_qspi_mode_bit_enable(void); 0815 0816 /******************************************************************************/ 0817 /*! 0818 * Get the current value of the Mode Bit Configuration register. 0819 * 0820 * \returns The 8 bit value that is sent to the device following the address 0821 * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable()) 0822 */ 0823 uint32_t alt_qspi_mode_bit_config_get(void); 0824 0825 /******************************************************************************/ 0826 /*! 0827 * Set the value of the Mode Bit Configuration register. 0828 * 0829 * Set the value of the 8 bits that are sent to the device following the address 0830 * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable()) 0831 * 0832 * This API requires that the QSPI controller be idle, as determined by 0833 * alt_qspi_is_idle(). 0834 * 0835 * \param mode_bits 0836 * The 8 bit value sent to the device following the address bytes. 0837 * 0838 * \retval ALT_E_SUCCESS Indicates successful completion. 0839 * \retval ALT_E_ERROR Indicates an error occurred. 0840 */ 0841 ALT_STATUS_CODE alt_qspi_mode_bit_config_set(const uint32_t mode_bits); 0842 0843 /******************************************************************************/ 0844 /*! 0845 * Get the current flash device size and write protection configuration. 0846 * 0847 * \param cfg 0848 * [out] Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure to 0849 * contain the returned flash device size and write protection 0850 * configuration. 0851 * 0852 * \retval ALT_E_SUCCESS Indicates successful completion. 0853 * \retval ALT_E_ERROR Indicates an error occurred. 0854 */ 0855 ALT_STATUS_CODE alt_qspi_device_size_config_get(ALT_QSPI_DEV_SIZE_CONFIG_t * cfg); 0856 0857 /******************************************************************************/ 0858 /*! 0859 * Set the flash device size and write protection configuration. 0860 * 0861 * \param cfg 0862 * Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the 0863 * flash device size and write protection configuration. 0864 * 0865 * \retval ALT_E_SUCCESS Indicates successful completion. 0866 * \retval ALT_E_ERROR Indicates an error occurred. 0867 */ 0868 ALT_STATUS_CODE alt_qspi_device_size_config_set(const ALT_QSPI_DEV_SIZE_CONFIG_t * cfg); 0869 0870 /******************************************************************************/ 0871 /*! 0872 * Get the current QSPI device read instruction configuration. 0873 * 0874 * \param cfg 0875 * [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to 0876 * contain the returned QSPI controller instruction configuration 0877 * used when performing read transactions with the device. 0878 * 0879 * \retval ALT_E_SUCCESS Indicates successful completion. 0880 * \retval ALT_E_ERROR Indicates an error occurred. 0881 */ 0882 ALT_STATUS_CODE alt_qspi_device_read_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg); 0883 0884 /******************************************************************************/ 0885 /*! 0886 * Set the QSPI device read instruction configuration. 0887 * 0888 * This API requires that the QSPI controller be idle, as determined by 0889 * alt_qspi_is_idle(). 0890 * 0891 * \param cfg 0892 * Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the 0893 * desired op code, transfer widths, and dummy cycles for the QSPI 0894 * controller to use when performing read transactions with the 0895 * device. 0896 * 0897 * \retval ALT_E_SUCCESS Indicates successful completion. 0898 * \retval ALT_E_ERROR Indicates an error occurred. 0899 */ 0900 ALT_STATUS_CODE alt_qspi_device_read_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg); 0901 0902 /******************************************************************************/ 0903 /*! 0904 * Get the current QSPI device write instruction configuration. 0905 * 0906 * \param cfg 0907 * [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to 0908 * contain the returned QSPI controller instruction configuration 0909 * used when performing write transactions with the device. 0910 * 0911 * \retval ALT_E_SUCCESS Indicates successful completion. 0912 * \retval ALT_E_ERROR Indicates an error occurred. 0913 */ 0914 ALT_STATUS_CODE alt_qspi_device_write_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg); 0915 0916 /******************************************************************************/ 0917 /*! 0918 * Set the QSPI device write instruction configuration. 0919 * 0920 * This API requires that the QSPI controller be idle, as determined by 0921 * alt_qspi_is_idle(). 0922 * 0923 * \param cfg 0924 * Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the 0925 * desired op code, transfer widths, and dummy cycles for the QSPI 0926 * controller to use when performing write transactions with the 0927 * device. 0928 * 0929 * \retval ALT_E_SUCCESS Indicates successful completion. 0930 * \retval ALT_E_ERROR Indicates an error occurred. 0931 */ 0932 ALT_STATUS_CODE alt_qspi_device_write_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg); 0933 0934 /******************************************************************************/ 0935 /*! 0936 * Get the QSPI device delay and timing configuration parameters. 0937 * 0938 * This function returns the settings of the chip select delay and timing 0939 * configurations. 0940 * 0941 * \param cfg 0942 * [out] Pointer to a ALT_QSPI_TIMING_CONFIG_t structure to return 0943 * the device timing and delay settings. 0944 * 0945 * \retval ALT_E_SUCCESS Indicates successful completion. 0946 * \retval ALT_E_ERROR Indicates an error occurred. 0947 */ 0948 ALT_STATUS_CODE alt_qspi_timing_config_get(ALT_QSPI_TIMING_CONFIG_t * cfg); 0949 0950 /******************************************************************************/ 0951 /*! 0952 * Set the QSPI device delay and timing configuration parameters. 0953 * 0954 * This function allows the user to configure how the chip select is driven 0955 * after each flash access. This is required as each device may have different 0956 * timing requirements. As the serial clock frequency is increased, these 0957 * timing parameters become more important and can be adjusted to meet the 0958 * requirements of a specific flash device. All timings are defined in cycles 0959 * of the SPI master ref clock. 0960 * 0961 * This API requires that the QSPI controller be idle, as determined by 0962 * alt_qspi_is_idle(). 0963 * 0964 * \param cfg 0965 * Pointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the 0966 * desired timing and delay settings. 0967 * 0968 * \retval ALT_E_SUCCESS Indicates successful completion. 0969 * \retval ALT_E_ERROR Indicates an error occurred. 0970 */ 0971 ALT_STATUS_CODE alt_qspi_timing_config_set(const ALT_QSPI_TIMING_CONFIG_t * cfg); 0972 0973 /*! @} */ 0974 0975 /******************************************************************************/ 0976 /*! \addtogroup ALT_QSPI_DAC Direct Access Mode 0977 * 0978 * In direct access mode, an access to the AHB data slave triggers a read or 0979 * write command to the flash memory. To use the direct access mode, enable the 0980 * direct access controller with the alt_qspi_direct_enable() function. An 0981 * external master, for example a processor, triggers the direct access 0982 * controller with a read or write operation to the AHB data slave 0983 * interface. The data slave exposes a 1MB window into the flash device. You can 0984 * remap this window to any 1MB location within the flash device address range. 0985 * 0986 * To remap the AHB data slave to access other 1MB regions of the flash device, 0987 * enable address remapping by calling alt_qspi_ahb_address_remap_enable(). All 0988 * incoming data slave accesses remap to the offset specified in the remap 0989 * address register which is configured by alt_qspi_ahb_remap_address_set(). 0990 * 0991 * The 20 LSBs of incoming addresses are used for accessing the 1MB region and 0992 * the higher bits are ignored. 0993 * 0994 * The quad SPI controller does not issue any error status for accesses that lie 0995 * outside the connected flash memory space. 0996 * 0997 * @{ 0998 */ 0999 1000 /******************************************************************************/ 1001 /*! 1002 * Disable the QSPI Direct Access Controller. 1003 * 1004 * \retval ALT_E_SUCCESS Indicates successful completion. 1005 * \retval ALT_E_ERROR Indicates an error occurred. 1006 */ 1007 ALT_STATUS_CODE alt_qspi_direct_disable(void); 1008 1009 /******************************************************************************/ 1010 /*! 1011 * Enable the QSPI Direct Access Controller. 1012 * 1013 * \retval ALT_E_SUCCESS Indicates successful completion. 1014 * \retval ALT_E_ERROR Indicates an error occurred. 1015 */ 1016 ALT_STATUS_CODE alt_qspi_direct_enable(void); 1017 1018 /******************************************************************************/ 1019 /*! 1020 * Get the current AHB address remap value. 1021 * 1022 * Returns the current value of the AHB remap address register. 1023 * 1024 * \returns The value used to remap an incoming AHB address to a 1025 * different address used by the flash device. 1026 */ 1027 uint32_t alt_qspi_ahb_remap_address_get(void); 1028 1029 /******************************************************************************/ 1030 /*! 1031 * Set the AHB address remap value. 1032 * 1033 * Sets the value of the AHB remap address register. 1034 * 1035 * This API requires that the QSPI controller be idle, as determined by 1036 * alt_qspi_is_idle(). 1037 * 1038 * \param ahb_remap_addr 1039 * The value used to remap an incoming AHB address to a different 1040 * address used by the flash device. 1041 * 1042 * \retval ALT_E_SUCCESS Indicates successful completion. 1043 * \retval ALT_E_ERROR Indicates an error occurred. 1044 */ 1045 ALT_STATUS_CODE alt_qspi_ahb_remap_address_set(const uint32_t ahb_remap_addr); 1046 1047 /******************************************************************************/ 1048 /*! 1049 * Disable AHB address remapping. 1050 * 1051 * Disables remapping of incoming AHB addresses so they are sent unmodified to 1052 * the flash device. The incoming AHB address maps directly to the address 1053 * serially sent to the flash device. 1054 * 1055 * \retval ALT_E_SUCCESS Indicates successful completion. 1056 * \retval ALT_E_ERROR Indicates an error occurred. 1057 */ 1058 ALT_STATUS_CODE alt_qspi_ahb_address_remap_disable(void); 1059 1060 /******************************************************************************/ 1061 /*! 1062 * Enable AHB address remapping. 1063 * 1064 * Enables remapping of incoming AHB addresses so they are modified to 1065 * \<address\> + \e N, where \e N is the configured remap address value. 1066 * 1067 * See: alt_qspi_ahb_remap_address_set(). 1068 * 1069 * \retval ALT_E_SUCCESS Indicates successful completion. 1070 * \retval ALT_E_ERROR Indicates an error occurred. 1071 */ 1072 ALT_STATUS_CODE alt_qspi_ahb_address_remap_enable(void); 1073 1074 /*! @} */ 1075 1076 /******************************************************************************/ 1077 /*! \addtogroup ALT_QSPI_INDAC Indirect Access Mode 1078 * 1079 * In indirect access mode, flash data is temporarily buffered in the QSPI 1080 * controller's SRAM. Software controls and triggers indirect accesses through 1081 * the APB register slave interface. The controller transfers data through the 1082 * AHB data slave interface. 1083 * 1084 * An indirect read operation reads data from the flash memory, places the data 1085 * into the SRAM, and transfers the data to an external master through the AHB 1086 * data slave interface. 1087 * 1088 * An indirect write operation programs data from the SRAM to the flash memory. 1089 * 1090 * @{ 1091 */ 1092 1093 /******************************************************************************/ 1094 /*! 1095 * Starts an indirect read transfer. 1096 * 1097 * Initiates an indirect read transfer of the requested number of bytes from the 1098 * designated flash address. 1099 * 1100 * After calling this function, flash data may be read from the QSPI SRAM buffer 1101 * as it becomes available via one of the following methods: 1102 * * Directly from the AHB data slave interface at the configured AHB trigger 1103 * address. If the requested data is not immediately available in the SRAM 1104 * buffer then AHB wait states will be applied until the data has been read 1105 * from flash into the SRAM buffer. Alternatively, data may be read from the 1106 * AHB data slave as the SRAM is filled. The availability of data in the SRAM 1107 * buffer may be determined by an SRAM watermark interrupt notification or by 1108 * polling the SRAM fill level. 1109 * * Configuring and enabling the QSPI DMA peripheral controller. 1110 * 1111 * The following is a list of restrictions: 1112 * * flash_addr must be word aligned. 1113 * * num_bytes must be word aligned. 1114 * * The transfer must not cross the 3-byte addressing boundary. This 1115 * restriction may be device specific and may be lifted in the future. 1116 * 1117 * \param flash_addr 1118 * The flash source address to read data from. 1119 * 1120 * \param num_bytes 1121 * The number of bytes to read from the flash source address. 1122 * 1123 * \retval ALT_E_SUCCESS Indicates successful completion. 1124 * \retval ALT_E_ERROR Indicates an error occurred. 1125 */ 1126 ALT_STATUS_CODE alt_qspi_indirect_read_start(const uint32_t flash_addr, 1127 const size_t num_bytes); 1128 1129 /******************************************************************************/ 1130 /*! 1131 * Finish the indirect read operation that was completed or canceled. This 1132 * function should be called before another indirect read is started. 1133 * 1134 * \retval ALT_E_SUCCESS Indicates successful completion. 1135 * \retval ALT_E_ERROR Indicates an error occurred. 1136 */ 1137 ALT_STATUS_CODE alt_qspi_indirect_read_finish(void); 1138 1139 /******************************************************************************/ 1140 /*! 1141 * Cancel all indirect read transfers in progress. 1142 * 1143 * \retval ALT_E_SUCCESS Indicates successful completion. 1144 * \retval ALT_E_ERROR Indicates an error occurred. 1145 */ 1146 ALT_STATUS_CODE alt_qspi_indirect_read_cancel(void); 1147 1148 /******************************************************************************/ 1149 /*! 1150 * Get the current indirect read SRAM fill level value. 1151 * 1152 * Returns the SRAM fill level for the indirect read partition in units of SRAM 1153 * words (4 bytes). 1154 * 1155 * \returns The SRAM fill level for the indirect read partition in units of 1156 * SRAM words (4 bytes). 1157 */ 1158 uint32_t alt_qspi_indirect_read_fill_level(void); 1159 1160 /******************************************************************************/ 1161 /*! 1162 * Get the current indirect read watermark value. 1163 * 1164 * The watermark value (in bytes) represents the minimum fill level of the SRAM 1165 * before a DMA peripheral access is permitted. When the SRAM fill level passes 1166 * the watermark, an interrupt source is also generated. This can be disabled by 1167 * writing a value of all zeroes. 1168 * 1169 * \returns The current indirect read watermark value. 1170 */ 1171 uint32_t alt_qspi_indirect_read_watermark_get(void); 1172 1173 /******************************************************************************/ 1174 /*! 1175 * Set the indirect read watermark value. 1176 * 1177 * The watermark value (in bytes) represents the minimum fill level of the SRAM 1178 * before a DMA peripheral access is permitted. When the SRAM fill level passes 1179 * the watermark, an interrupt source is also generated. This can be disabled by 1180 * writing a value of all zeroes. The watermark can only be set when no indirect 1181 * read is in progress. 1182 * 1183 * \param watermark 1184 * The watermark value (in bytes). 1185 * 1186 * \retval ALT_E_SUCCESS Indicates successful completion. 1187 * \retval ALT_E_ERROR Indicates an error occurred. 1188 */ 1189 ALT_STATUS_CODE alt_qspi_indirect_read_watermark_set(const uint32_t watermark); 1190 1191 /******************************************************************************/ 1192 /*! 1193 * Returns true when an indirect read has completed otherwise false. 1194 * 1195 * \internal 1196 * Returns Indirect Read Transfer Control Register bit 5 "Indirect Completion Status". 1197 * \endinternal 1198 * 1199 * \returns Returns true when an indirect read has completed otherwise false. 1200 */ 1201 bool alt_qspi_indirect_read_is_complete(void); 1202 1203 /******************************************************************************/ 1204 /*! 1205 * Starts an indirect write transfer. 1206 * 1207 * Initiates an indirect write transfer of the requested number of bytes to the 1208 * designated flash address. 1209 * 1210 * After calling this function, flash data may be written to the QSPI SRAM 1211 * buffer there is space via one of the following methods: 1212 * * Directly from the AHB data slave interface at the configured AHB trigger 1213 * address. If the requested space is not immediately available in the SRAM 1214 * buffer then AHB wait states will be applied until the space becomes 1215 * available. Alternatively, the data may be written to the AHB data slave 1216 * as the SRAM is drained. The space in the SRAM buffer may be determined by 1217 * an SRAM watermark interrupt notification or by polling the SRAM fill 1218 * level and subtracting that value from the SRAM space devoted to writes. 1219 * * Configuring and enabling the QSPI DMA peripheral controller. 1220 * 1221 * The following is a list of restrictions: 1222 * * flash_addr must be word aligned. 1223 * * num_bytes must be word aligned. 1224 * * num_bytes must be 256 or below. This is due to a device specific 1225 * limitation and may be lifted in the future. 1226 * * The transfer must not cross the page (256 byte) addressing boundary. This 1227 * restriction may be device specific and may be lifted in the future. 1228 * 1229 * \param flash_addr 1230 * The flash destination address to write data to. 1231 * 1232 * \param num_bytes 1233 * The number of bytes to write to the flash. 1234 * 1235 * \retval ALT_E_SUCCESS Indicates successful completion. 1236 * \retval ALT_E_ERROR Indicates an error occurred. 1237 */ 1238 ALT_STATUS_CODE alt_qspi_indirect_write_start(const uint32_t flash_addr, 1239 const size_t num_bytes); 1240 1241 /******************************************************************************/ 1242 /*! 1243 * Finish the indirect write operation that was completed or canceled. This 1244 * function should be called before another indirect write is started. 1245 * 1246 * \retval ALT_E_SUCCESS Indicates successful completion. 1247 * \retval ALT_E_ERROR Indicates an error occurred. 1248 */ 1249 ALT_STATUS_CODE alt_qspi_indirect_write_finish(void); 1250 1251 /******************************************************************************/ 1252 /*! 1253 * Cancel all indirect write transfers in progress. 1254 * 1255 * \retval ALT_E_SUCCESS Indicates successful completion. 1256 * \retval ALT_E_ERROR Indicates an error occurred. 1257 */ 1258 ALT_STATUS_CODE alt_qspi_indirect_write_cancel(void); 1259 1260 /******************************************************************************/ 1261 /*! 1262 * Get the current indirect write SRAM fill level value. 1263 * 1264 * Returns the SRAM fill level for the indirect write partition in units of SRAM 1265 * words (4 bytes). 1266 * 1267 * \returns The SRAM fill level for the indirect write partition in units of 1268 * SRAM words (4 bytes). 1269 */ 1270 uint32_t alt_qspi_indirect_write_fill_level(void); 1271 1272 /******************************************************************************/ 1273 /*! 1274 * Get the current indirect write watermark value. 1275 * 1276 * The watermark value (in bytes) represents the maximum fill level of the SRAM 1277 * before a DMA peripheral access is permitted. When the SRAM fill level falls 1278 * below the watermark, an interrupt is also generated. This can be disabled by 1279 * writing a value of all ones. 1280 * 1281 * \returns The current indirect write watermark value. 1282 */ 1283 uint32_t alt_qspi_indirect_write_watermark_get(void); 1284 1285 /******************************************************************************/ 1286 /*! 1287 * Set the indirect write watermark value. 1288 * 1289 * The watermark value (in bytes) represents the maximum fill level of the SRAM 1290 * before a DMA peripheral access is permitted. When the SRAM fill level falls 1291 * below the watermark, an interrupt is also generated. This can be disabled by 1292 * writing a value of all ones. The watermark can only be set when no indirect 1293 * write is in progress. 1294 * 1295 * \param watermark 1296 * The watermark value (in bytes). 1297 * 1298 * \retval ALT_E_SUCCESS Indicates successful completion. 1299 * \retval ALT_E_ERROR Indicates an error occurred. 1300 */ 1301 ALT_STATUS_CODE alt_qspi_indirect_write_watermark_set(const uint32_t watermark); 1302 1303 /******************************************************************************/ 1304 /*! 1305 * Returns true when an indirect write has completed otherwise false. 1306 * 1307 * \internal 1308 * Returns Indirect Write Transfer Control Register bit 5 "Indirect Completion 1309 * Status". 1310 * \endinternal 1311 * 1312 * \returns Returns true when an indirect write has completed otherwise 1313 * false. 1314 */ 1315 bool alt_qspi_indirect_write_is_complete(void); 1316 1317 /******************************************************************************/ 1318 /*! \addtogroup ALT_QSPI_CFG_SRAM SRAM Partition 1319 * 1320 * The SRAM local memory buffer is a 128 by 32-bit (512 total bytes) memory. The 1321 * SRAM has two partitions, with the lower partition reserved for indirect read 1322 * operations and the upper partition for indirect write operations. The size of 1323 * the partitions is specified in the SRAM partition register, based on 32-bit 1324 * word sizes. For example, to specify four bytes of storage, write the value 1. 1325 * The value written to the indirect read partition size field ( addr ) defines 1326 * the number of entries reserved for indirect read operations. For example, write 1327 * the value 32 (0x20) to partition the 128-entry SRAM to 32 entries (25%) for 1328 * read usage and 96 entries (75%) for write usage. 1329 * 1330 * The functions in this section provide accces to configure the SRAM read 1331 * partition allocation. 1332 * 1333 * @{ 1334 */ 1335 1336 /*! 1337 * The size of the onboard SRAM in bytes. 1338 */ 1339 #define ALT_QSPI_SRAM_FIFO_SIZE (512) 1340 1341 /* 1342 * The size of the onboard SRAM in entries. Each entry is word (32-bit) sized. 1343 */ 1344 #define ALT_QSPI_SRAM_FIFO_ENTRY_COUNT (512 / sizeof(uint32_t)) 1345 1346 /******************************************************************************/ 1347 /*! 1348 * Get the entry count (words) of the indirect read partition in the QSPI 1349 * controller SRAM. 1350 * 1351 * There is an additional word of read memory not in the SRAM but used to 1352 * buffer the SRAM and the AHB. As such, the total on board memory buffer for 1353 * indirect read is 1 more than the value reported by this function. 1354 * 1355 * \returns The count of 32-bit words of the indirect read partition in the 1356 * QSPI controller SRAM. 1357 * 1358 * \internal 1359 * The documentation states that the number of locations allocated to indirect 1360 * read = SRAM_PARTITION_REG + 1. Cadence clarified that the +1 comes from an 1361 * additional register slice for read's, implemented in FLOPs, which was done 1362 * to avoid connection the SRAM directly to the AHB interface. This was done 1363 * for performance / timing reasons. The +1 will not be included in the return 1364 * value but documented as an additional entry. 1365 * \endinternal 1366 */ 1367 uint32_t alt_qspi_sram_partition_get(void); 1368 1369 /******************************************************************************/ 1370 /*! 1371 * Set the entry count (words) of the indirect read partition in the QSPI 1372 * controller SRAM. 1373 * 1374 * Note: It is recommended that setting SRAM partition to 0 or 127 should be 1375 * avoided although it is not prohibited. 1376 * 1377 * \param read_part_size 1378 * The count of 32-bit words to allocate to the indirect read 1379 * partition in the QSPI controller SRAM. 1380 * 1381 * \retval ALT_E_SUCCESS Indicates successful completion. 1382 * \retval ALT_E_ERROR Indicates an error occurred. 1383 */ 1384 ALT_STATUS_CODE alt_qspi_sram_partition_set(const uint32_t read_part_size); 1385 1386 /*! @} */ 1387 1388 /*! @} */ 1389 1390 /******************************************************************************/ 1391 /*! \addtogroup ALT_QSPI_ERASE Flash Erase 1392 * 1393 * The functions in this group are used to erase selected portions of a flash 1394 * device. 1395 * @{ 1396 */ 1397 1398 /******************************************************************************/ 1399 /*! 1400 * This function erases the designated flash device subsector. 1401 * 1402 * This function erases the flash device subsector containing the designated 1403 * flash address. Any address within the subsector is valid. 1404 * 1405 * \param addr 1406 * A flash address contained within the the subsector to be erased. 1407 * 1408 * \retval ALT_E_SUCCESS Indicates successful completion. 1409 * \retval ALT_E_ERROR Indicates an error occurred. 1410 */ 1411 ALT_STATUS_CODE alt_qspi_erase_subsector(const uint32_t addr); 1412 1413 /******************************************************************************/ 1414 /*! 1415 * This function erases the designated flash device sector. 1416 * 1417 * This function erases the flash device sector containing the designated flash 1418 * address. Any address within the sector is valid. 1419 * 1420 * \param addr 1421 * A flash address contained within the the sector to be erased. 1422 * 1423 * \retval ALT_E_SUCCESS Indicates successful completion. 1424 * \retval ALT_E_ERROR Indicates an error occurred. 1425 */ 1426 ALT_STATUS_CODE alt_qspi_erase_sector(const uint32_t addr); 1427 1428 /******************************************************************************/ 1429 /*! 1430 * This function erases the entire flash device. 1431 * 1432 * \retval ALT_E_SUCCESS Indicates successful completion. 1433 * \retval ALT_E_ERROR Indicates an error occurred. 1434 */ 1435 ALT_STATUS_CODE alt_qspi_erase_chip(void); 1436 1437 /*! @} */ 1438 1439 /******************************************************************************/ 1440 /*! \addtogroup ALT_QSPI_DMA DMA Peripheral Interface 1441 * 1442 * The DMA peripheral request controller is only used for the indirect mode of 1443 * operation where data is temporarily stored in the SRAM. The QSPI flash 1444 * controller uses the DMA peripheral request interface to trigger the external 1445 * DMA into performing data transfers between memory and the QSPI 1446 * controller. 1447 * 1448 * There are two DMA peripheral request interfaces, one for indirect reads and 1449 * one for indirect writes. The DMA peripheral request controller can issue two 1450 * types of DMA requests, single or burst, to the external DMA. The number of 1451 * bytes for each single or burst request is specified using the 1452 * alt_qspi_dma_config_set(). The DMA peripheral request controller splits the 1453 * total amount of data to be transferred into a number of DMA burst and single 1454 * requests by dividing the total number of bytes by the number of bytes 1455 * specified in the burst request, and then dividing the remainder by the number 1456 * of bytes in a single request. 1457 * 1458 * When programming the DMA controller, the burst request size must match the 1459 * burst request size set in the quad SPI controller to avoid quickly reaching 1460 * an overflow or underflow condition. 1461 * @{ 1462 */ 1463 1464 /******************************************************************************/ 1465 /*! 1466 * Disable the QSPI DMA peripheral interface. 1467 * 1468 * \retval ALT_E_SUCCESS Indicates successful completion. 1469 * \retval ALT_E_ERROR Indicates an error occurred. 1470 */ 1471 ALT_STATUS_CODE alt_qspi_dma_disable(void); 1472 1473 /******************************************************************************/ 1474 /*! 1475 * Enable the QSPI DMA peripheral interface. 1476 * 1477 * Enable the QSPI DMA handshaking logic. When enabled the QSPI will trigger DMA 1478 * transfer requests via the DMA peripheral interface. 1479 * 1480 * \retval ALT_E_SUCCESS Indicates successful completion. 1481 * \retval ALT_E_ERROR Indicates an error occurred. 1482 */ 1483 ALT_STATUS_CODE alt_qspi_dma_enable(void); 1484 1485 /******************************************************************************/ 1486 /*! 1487 * Get the current DMA peripheral configuration. 1488 * 1489 * This function returns the QSPI DMA peripheral interface single and burst type 1490 * transfer size configurations. 1491 * 1492 * \param single_type_sz 1493 * [out] The number of bytes for each DMA single type 1494 * request. Value must be a power of 2 between 1 and 32728. 1495 * 1496 * \param burst_type_sz 1497 * [out] The number of bytes for each DMA burst type request. Value 1498 * must be a power of 2 between 1 and 32728. 1499 * 1500 * \retval ALT_E_SUCCESS Indicates successful completion. 1501 * \retval ALT_E_ERROR Indicates an error occurred. 1502 */ 1503 ALT_STATUS_CODE alt_qspi_dma_config_get(uint32_t * single_type_sz, 1504 uint32_t * burst_type_sz); 1505 1506 /******************************************************************************/ 1507 /*! 1508 * Set the DMA peripheral configuration. 1509 * 1510 * This function configures the QSPI DMA peripheral interface single and burst 1511 * type transfer sizes. The DMA configruation should be setup while the 1512 * controller is idle. Because all transfers are required to be word aligned, 1513 * the smallest DMA request is 4 bytes. 1514 * 1515 * This API requires that the QSPI controller be idle, as determined by 1516 * alt_qspi_is_idle(). 1517 * 1518 * \param single_type_sz 1519 * The number of bytes for each DMA single type request. Value must 1520 * be a power of 2 between 4 and 32768. 1521 * 1522 * \param burst_type_sz 1523 * The number of bytes for each DMA burst type request. Value must 1524 * be a power of 2 between 4 and 32768. Bursts must be equal or 1525 * larger than single requests. 1526 * 1527 * \retval ALT_E_SUCCESS Indicates successful completion. 1528 * \retval ALT_E_ERROR Indicates an error occurred. 1529 */ 1530 ALT_STATUS_CODE alt_qspi_dma_config_set(const uint32_t single_type_sz, 1531 const uint32_t burst_type_sz); 1532 1533 1534 /*! @} */ 1535 1536 /*! @} */ 1537 1538 #ifdef __cplusplus 1539 } 1540 #endif /* __cplusplus */ 1541 #endif /* __ALT_QSPI_H__ */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|