source: rtems/bsps/arm/altera-cyclone-v/contrib/hwlib/src/hwmgr/alt_qspi.h @ 9d41fca

5
Last change on this file since 9d41fca was 9d41fca, checked in by Sebastian Huber <sebastian.huber@…>, on 02/27/19 at 10:39:29

bsp/altera-cyclone-v: Adjust Doxygen file groups

Update #3707.
  • Property mode set to 100644
File size: 63.9 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup RTEMSBSPsARMCycVContrib
5 */
6
7/******************************************************************************
8*
9* Copyright 2013 Altera Corporation. All Rights Reserved.
10*
11* Redistribution and use in source and binary forms, with or without
12* modification, are permitted provided that the following conditions are met:
13*
14* 1. Redistributions of source code must retain the above copyright notice,
15* this list of conditions and the following disclaimer.
16*
17* 2. Redistributions in binary form must reproduce the above copyright notice,
18* this list of conditions and the following disclaimer in the documentation
19* and/or other materials provided with the distribution.
20*
21* 3. The name of the author may not be used to endorse or promote products
22* derived from this software without specific prior written permission.
23*
24* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
25* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
26* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
27* EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
28* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
29* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
32* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
33* OF SUCH DAMAGE.
34*
35******************************************************************************/
36
37/******************************************************************************
38*
39* !!!! Customer Be Aware, Exception!!!
40*
41* 1. Qspi Direct Access Mode is not working!
42*
43*    This is because the qspi flash memory installed on our DevKit board, Micro
44*    part N25Q00xx, 8 Gb, is not completely compatible with our embedded Synopsis
45*    QSPI controller IP. Therefore there is no viable direct access code offered
46*    in the lib.  All the memory rea/write functionality is offered with indirect
47*    access only.   
48*
49*    Should you install a different flash memory part in your custom board, and
50*    wondering wether direct access mode works, please contact with us.
51*
52******************************************************************************/
53
54/*! \file
55 *  Altera - QSPI Flash Controller Module
56 */
57
58#ifndef __ALT_QSPI_H__
59#define __ALT_QSPI_H__
60
61#include <bsp/hwlib.h>
62
63#ifdef __cplusplus
64extern "C"
65{
66#endif  /* __cplusplus */
67
68/******************************************************************************/
69/*! \addtogroup ALT_QSPI QSPI Flash Controller Module
70 *
71 * This module defines a low level driver API for the hardware processor system
72 * (HPS) quad serial peripheral interface (QSPI) flash controller for access to
73 * serial NOR flash devices. The quad SPI flash controller supports standard SPI
74 * flash devices as well as high-performance dual and quad SPI flash
75 * devices.
76 *
77 * @{
78 */
79
80/******************************************************************************/
81/*! \addtogroup ALT_QSPI_CSR General Control and Status Functions
82 *
83 * The declarations and functions in this group provide general purpose control
84 * and status functions for the QSPI Flash Controller.
85 *
86 * @{
87 */
88
89/******************************************************************************/
90/*!
91 * Initialize the QSPI flash controller for use.
92 *
93 * \internal
94 * Implementation Notes:
95 *  * The QSPI Controller has been designed to wake up in a state that is
96 *    suitable for performing basic reads and writes using the direct access
97 *    controller.
98 *  * Bring out of reset
99 *  * QSPI reference clock validation
100 *  * See Programmer's Guide, Configuring the QSPI Controller for use after
101 *    reset, in QSPI_FLASH_CTRL for full initialization details.
102 * \endinternal
103 *
104 * \retval      ALT_E_SUCCESS   Indicates successful completion.
105 * \retval      ALT_E_ERROR     Indicates an error occurred.
106 */
107ALT_STATUS_CODE alt_qspi_init(void);
108
109/******************************************************************************/
110/*!
111 * Uninitialize the QSPI flash controller.
112 *
113 * Uninitialize the QSPI flash controller by cancelling any indirect transfers
114 * in progress and putting the QSPI controller into reset.
115 *
116 * \retval      ALT_E_SUCCESS   Indicates successful completion.
117 * \retval      ALT_E_ERROR     Indicates an error occurred.
118 */
119ALT_STATUS_CODE alt_qspi_uninit(void);
120
121/******************************************************************************/
122/*!
123 * Disable the QSPI Controller.
124 *
125 * Disable the QSPI once the current transfer of the data word (FF_W) is
126 * complete. All output enables are inactive and all pins are set to input
127 * mode.
128 *
129 * \retval      ALT_E_SUCCESS   Indicates successful completion.
130 * \retval      ALT_E_ERROR     Indicates an error occurred.
131 */
132ALT_STATUS_CODE alt_qspi_disable(void);
133
134/******************************************************************************/
135/*!
136 * Enable the QSPI Controller.
137 *
138 * \retval      ALT_E_SUCCESS   Indicates successful completion.
139 * \retval      ALT_E_ERROR     Indicates an error occurred.
140 */
141ALT_STATUS_CODE alt_qspi_enable(void);
142
143/******************************************************************************/
144/*!
145 * This type definition enumerates the interrupt status conditions for the QSPI
146 * controller.
147 *
148 * The enumerations serve as masks for the QSPI controller events that can be
149 * set when the designated conditions occur and the corresponding event is
150 * enabled.  When any of these event source conditions are true, the \b
151 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt output is asserted high.
152 *
153 * Interrupt sources are cleared when software calls alt_qspi_int_clear(). The
154 * interrupt sources are individually maskable using alt_qspi_int_disable() and
155 * alt_qspi_int_enable().
156 */
157typedef enum ALT_QSPI_INT_STATUS_e
158{
159    /*!
160     * Mode fail M - indicates the voltage on pin n_ss_in is inconsistent with
161     * the SPI mode. Set = 1 if n_ss_in is low in master mode (multi-master
162     * contention). These conditions will clear the spi_enable bit and disable
163     * the SPI.
164     *  * 0 = no mode fault has been detected.
165     *  * 1 = a mode fault has occurred.
166     */
167    ALT_QSPI_INT_STATUS_MODE_FAIL         = (0x1 << 0),
168
169    /*!
170     * Underflow Detected.
171     *  * 0 = no underflow has been detected.
172     *  * 1 = underflow is detected and an attempt to transfer data is made
173     *        when the small TX FIFO is empty. This may occur when AHB write
174     *        data is being supplied too slowly to keep up with the requested
175     *        write operation.
176     */
177    ALT_QSPI_INT_STATUS_UFL               = (0x1 << 1),
178
179    /*!
180     * Controller has completed last triggered indirect operation.
181     */
182    ALT_QSPI_INT_STATUS_IDAC_OP_COMPLETE  = (0x1 << 2),
183
184    /*!
185     * Indirect operation was requested but could not be accepted. Two indirect
186     * operations already in storage.
187     */
188    ALT_QSPI_INT_STATUS_IDAC_OP_REJECT    = (0x1 << 3),
189
190    /*!
191     * Write to protected area was attempted and rejected.
192     */
193    ALT_QSPI_INT_STATUS_WR_PROT_VIOL      = (0x1 << 4),
194
195    /*!
196     * Illegal AHB Access Detected. AHB write wrapping bursts and the use of
197     * SPLIT/RETRY accesses will cause this interrupt to trigger.
198     */
199    ALT_QSPI_INT_STATUS_ILL_AHB_ACCESS    = (0x1 << 5),
200
201    /*!
202     * Indirect Transfer Watermark Level Breached.
203     */
204    ALT_QSPI_INT_STATUS_IDAC_WTRMK_TRIG   = (0x1 << 6),
205
206    /*!
207     * Receive Overflow. This should only occur in Legacy SPI mode.
208     *
209     * Set if an attempt is made to push the RX FIFO when it is full. This bit
210     * is reset only by a system reset and cleared only when this register is
211     * read. If a new push to the RX FIFO occurs coincident with a register read
212     * this flag will remain set.
213     *  * 0 = no overflow has been detected.
214     *  * 1 = an overflow has occurred.
215     */
216    ALT_QSPI_INT_STATUS_RX_OVF            = (0x1 << 7),
217
218    /*!
219     * Small TX FIFO not full (current FIFO status). Can be ignored in non-SPI
220     * legacy mode.
221     *  * 0 = FIFO has >= THRESHOLD entries.
222     *  * 1 = FIFO has < THRESHOLD entries.
223     */
224    ALT_QSPI_INT_STATUS_TX_FIFO_NOT_FULL  = (0x1 << 8),
225
226    /*!
227     * Small TX FIFO full (current FIFO status). Can be ignored in non-SPI
228     * legacy mode.
229     *  * 0 = FIFO is not full.
230     *  * 1 = FIFO is full.
231     */
232    ALT_QSPI_INT_STATUS_TX_FIFO_FULL      = (0x1 << 9),
233
234    /*!
235     * Small RX FIFO not empty (current FIFO status). Can be ignored in non-SPI
236     * legacy mode.
237     *  * 0 = FIFO has < RX THRESHOLD entries.
238     *  * 1 = FIFO has >= THRESHOLD entries.
239     */
240    ALT_QSPI_INT_STATUS_RX_FIFO_NOT_EMPTY = (0x1 << 10),
241
242    /*!
243     * Small RX FIFO full (current FIFO status). Can be ignored in non-SPI
244     * legacy mode.
245     *  * 0 = FIFO is not full.
246     *  * 1 = FIFO is full.
247     */
248    ALT_QSPI_INT_STATUS_RX_FIFO_FULL      = (0x1 << 11),
249
250    /*!
251     * Indirect Read partition of SRAM is full and unable to immediately
252     * complete indirect operation.
253     */
254    ALT_QSPI_INT_STATUS_IDAC_RD_FULL      = (0x1 << 12)
255
256} ALT_QSPI_INT_STATUS_t;
257
258/******************************************************************************/
259/*!
260 * Returns the QSPI controller interrupt status register value.
261 *
262 * This function returns the current value of the QSPI controller interrupt
263 * status register value which reflects the current QSPI controller status
264 * conditions.
265 *
266 * \returns     The current value of the QSPI controller interrupt status
267 *              register value which reflects the current QSPI controller status
268 *              conditions as defined by the \ref ALT_QSPI_INT_STATUS_t mask.
269 *              If the corresponding bit is set then the condition is asserted.
270 */
271uint32_t alt_qspi_int_status_get(void);
272
273/******************************************************************************/
274/*!
275 * Clears the specified QSPI controller interrupt status conditions identified
276 * in the mask.
277 *
278 * This function clears one or more of the status conditions as contributors to
279 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
280 *
281 * \param       mask
282 *              Specifies the QSPI interrupt status conditions to clear.  \e
283 *              mask is a mask of logically OR'ed \ref ALT_QSPI_INT_STATUS_t
284 *              values that designate the status conditions to clear.
285 *
286 * \retval      ALT_E_SUCCESS   Indicates successful completion.
287 * \retval      ALT_E_ERROR     Indicates an error occurred.
288 */
289ALT_STATUS_CODE alt_qspi_int_clear(const uint32_t mask);
290
291/******************************************************************************/
292/*!
293 * Disable the specified QSPI controller interrupt status conditions identified
294 * in the mask.
295 *
296 * This function disables one or more of the status conditions as contributors
297 * to the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
298 *
299 * This API requires that the QSPI controller be idle, as determined by
300 * alt_qspi_is_idle().
301 *
302 * NOTE: A cleared bit for any status condition in the mask value does not have
303 * the effect of enabling it as a contributor to the \b
304 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function
305 * alt_qspi_int_enable() is used to enable status source conditions.
306 *
307 * \param       mask
308 *              Specifies the status conditions to disable as interrupt source
309 *              contributors. \e mask is a mask of logically OR'ed
310 *              \ref ALT_QSPI_INT_STATUS_t values that designate the status
311 *              conditions to disable.
312 *
313 * \retval      ALT_E_SUCCESS   Indicates successful completion.
314 * \retval      ALT_E_ERROR     Indicates an error occurred.
315 */
316ALT_STATUS_CODE alt_qspi_int_disable(const uint32_t mask);
317
318/******************************************************************************/
319/*!
320 * Enable the specified QSPI controller interrupt status conditions identified
321 * in the mask.
322 *
323 * This function enables one or more of the status conditions as contributors to
324 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
325 *
326 * This API requires that the QSPI controller be idle, as determined by
327 * alt_qspi_is_idle().
328 *
329 * NOTE: A cleared bit for any status condition in the mask value does not have
330 * the effect of disabling it as a contributor to the \b
331 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function
332 * alt_qspi_int_disable() is used to disable status source conditions.
333 *
334 * \param       mask
335 *              Specifies the status conditions to enable as interrupt source
336 *              contributors. \e mask is a mask of logically OR'ed
337 *              \ref ALT_QSPI_INT_STATUS_t values that designate the status
338 *              conditions to enable.
339 *
340 * \retval      ALT_E_SUCCESS   Indicates successful completion.
341 * \retval      ALT_E_ERROR     Indicates an error occurred.
342 */
343ALT_STATUS_CODE alt_qspi_int_enable(const uint32_t mask);
344
345/******************************************************************************/
346/*!
347 * Returns true the serial interface and QSPI pipeline is IDLE.
348 *
349 * \returns     Returns true the serial interface and QSPI pipeline is IDLE.
350 */
351bool alt_qspi_is_idle(void);
352
353/*! @} */
354
355/******************************************************************************/
356/*! \addtogroup ALT_QSPI_GP_BLKIO General Purpose Block I/O
357 *
358 * The functions in this group provide general purpose block read and
359 * write flash functions.
360 *
361 * \internal
362 * These functions use Indirect Read/Write transfers to read and write block
363 * data to the flash device. An outline of the operational flow for these
364 * operations can be found in:
365 * //depot/soc/hhp_sw/baremetal_fw/drivers/qspi/qspi.c
366 *
367 * The general flow for an indirect block read is to call
368 * qspi_configure_mode_indirect_read_start() to initiate the read transfer from
369 * the flash device into the SRAM buffer and follow with a call to either
370 * qpsi_write_sram_fifo_poll() or qspi_read_sram_fifo_irq() to copy the data
371 * from SRAM into the user's buffer.
372 *
373 * The general flow for an indirect block write is to call
374 * qspi_configure_mode_indirect_write_start() to initiate the write transfer
375 * from the SRAM buffer to the flash device and follow with a call to either
376 * qpsi_write_sram_fifo_poll() or qspi_write_sram_fifo_irq() to fill the SRAM
377 * buffer with the user's data as space becomes available.
378 * \endinternal
379 *
380 * @{
381 */
382
383/******************************************************************************/
384/*!
385 * Read a block of data from the specified flash address.
386 *
387 * Reads a block of \e n data bytes from the flash \e src address into the user
388 * supplied \e dest buffer. The memory address, flash address, and size must be
389 * word aligned.
390 *
391 * \param       dest
392 *              The address of a caller supplied destination buffer large enough
393 *              to contain the requested block of flash data.
394 *
395 * \param       src
396 *              The flash device address to start reading data from.
397 *
398 * \param       size
399 *              The requested number of data bytes to read from the flash device.
400 *
401 * \retval      ALT_E_SUCCESS   Indicates successful completion.
402 * \retval      ALT_E_ERROR     Indicates an error occurred.
403 */
404ALT_STATUS_CODE alt_qspi_read(void * dest, uint32_t src, size_t size);
405
406/******************************************************************************/
407/*!
408 * Write a block of data to the specified flash address.
409 *
410 * Writes a block of \e n data bytes to the flash \e dest address from the
411 * designated \e src buffer. The applicable destination flash address range
412 * should have been erased prior to calling this function. The flash address,
413 * memory address, and size must be word aligned.
414 *
415 * \param       dest
416 *              The destination flash address to begin writing data to.
417 *
418 * \param       src
419 *              The source address to start writing data from.
420 *
421 * \param       size
422 *              The requested number of data bytes to write to the flash device.
423 *
424 * \retval      ALT_E_SUCCESS   Indicates successful completion.
425 * \retval      ALT_E_ERROR     Indicates an error occurred.
426 */
427ALT_STATUS_CODE alt_qspi_write(uint32_t dest, const void * src, size_t size);
428
429/*! @} */
430
431/******************************************************************************/
432/*! \addtogroup ALT_QSPI_DEV_CFG Flash Device Configuration
433 *
434 * The declarations and functions in this group are used to configure the QSPI
435 * controller interface to external flash devices.
436 *
437 * The following steps describe how to initialize and configure the
438 * QSPI controller to operate with a flash device.
439 *
440 * * Wait until any pending QSPI operations have completed.
441 * * Disable the QSPI controller using alt_qspi_disable().
442 * * Configure the device for optimal read transaction performance using
443 *   alt_qspi_device_read_config_set().
444 * * Configure the device for optimal write transaction performance using
445 *   alt_qspi_device_write_config_set().
446 * * Enable (alt_qspi_mode_bit_disable()) or disable
447 *   (alt_qspi_mode_bit_disable()) the mode bits per the device
448 *   requirements. If mode bits are enabled, then configure the mode
449 *   bit values using alt_qspi_mode_bit_config_set().
450 * * Configure the device size and write protection information using
451 *   alt_qspi_device_size_config_set().
452 * * Configure the QSPI device delay and timing settings using
453 *   alt_qspi_device_write_config_set().
454 * * Configure the baud divisor setting to define the required clock frequency
455 *   to the device using alt_qspi_baud_rate_div_set().
456 * * Enable the QSPI controller using alt_qspi_enable().
457 *
458 * @{
459 */
460
461/******************************************************************************/
462/*!
463 * This type enumerates the operational modes the QSPI controller can be
464 * configured for. It may apply to instruction, address, and/or data width
465 * interactions between the QSPI controller and the flash device.
466 */
467typedef enum ALT_QSPI_MODE_e
468{
469  ALT_QSPI_MODE_SINGLE = 0,     /*!< Use Standard Single SPI (SIO-SPI) mode (bits
470                                 *   always transferred into the device on DQ0
471                                 *   only). Supported by all SPI flash devices.
472                                 */
473  ALT_QSPI_MODE_DUAL   = 1,     /*!< Use Dual SPI (DIO-SPI) SPI mode where bits are
474                                 *   transferred on DQ0 and DQ1.
475                                 */
476  ALT_QSPI_MODE_QUAD   = 2      /*!< Use Dual SPI (QIO-SPI) SPI mode where bits are
477                                 *   transferred on DQ0, DQ1, DQ3, and DQ3.
478                                 */
479} ALT_QSPI_MODE_t;
480
481/******************************************************************************/
482/*!
483 * This type enumerates the mode configurations available for driving the
484 * ss_n[3:0] device chip selects.  The chip selects may be controlled as either
485 * in a '1 of 4' or '4 to 16 decode' mode.
486 */
487typedef enum ALT_QSPI_CS_MODE_e
488{
489  ALT_QSPI_CS_MODE_SINGLE_SELECT = 0,   /*!< Select 1 of 4 chip select ss_n[3:0]
490                                         */
491  ALT_QSPI_CS_MODE_DECODE        = 1    /*!< Select external 4 to 16 decode of
492                                         *   ss_n[3:0].
493                                         */
494} ALT_QSPI_CS_MODE_t;
495
496/******************************************************************************/
497/*!
498 * This type enumerates the QSPI controller master baud rate divisor selections.
499 */
500typedef enum ALT_QSPI_BAUD_DIV_e
501{
502  ALT_QSPI_BAUD_DIV_2            = 0x0, /*!< Divide by 2 */
503  ALT_QSPI_BAUD_DIV_4            = 0x1, /*!< Divide by 4 */
504  ALT_QSPI_BAUD_DIV_6            = 0x2, /*!< Divide by 6 */
505  ALT_QSPI_BAUD_DIV_8            = 0x3, /*!< Divide by 8 */
506  ALT_QSPI_BAUD_DIV_10           = 0x4, /*!< Divide by 10 */
507  ALT_QSPI_BAUD_DIV_12           = 0x5, /*!< Divide by 12 */
508  ALT_QSPI_BAUD_DIV_14           = 0x6, /*!< Divide by 14 */
509  ALT_QSPI_BAUD_DIV_16           = 0x7, /*!< Divide by 16 */
510  ALT_QSPI_BAUD_DIV_18           = 0x8, /*!< Divide by 18 */
511  ALT_QSPI_BAUD_DIV_20           = 0x9, /*!< Divide by 20 */
512  ALT_QSPI_BAUD_DIV_22           = 0xA, /*!< Divide by 22 */
513  ALT_QSPI_BAUD_DIV_24           = 0xB, /*!< Divide by 24 */
514  ALT_QSPI_BAUD_DIV_26           = 0xC, /*!< Divide by 26 */
515  ALT_QSPI_BAUD_DIV_28           = 0xD, /*!< Divide by 28 */
516  ALT_QSPI_BAUD_DIV_30           = 0xE, /*!< Divide by 30 */
517  ALT_QSPI_BAUD_DIV_32           = 0xF  /*!< Divide by 32 */
518} ALT_QSPI_BAUD_DIV_t;
519
520/******************************************************************************/
521/*!
522 * Device Size Configuration
523 *
524 * This type defines the structure used to specify flash device size and write
525 * protect regions.
526 */
527typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s
528{
529  uint32_t      block_size;         /*!< Number of bytes per device block. The
530                                     *   number is specified as a power of 2.
531                                     *   That is 0 = 1 byte, 1 = 2 bytes, ...
532                                     *   16 = 65535 bytes, etc.
533                                     */
534  uint32_t      page_size;          /*!< Number of bytes per device page.  This
535                                     *   is required by the controller for
536                                     *   performing flash writes up to and
537                                     *   across page boundaries.
538                                     */
539  uint32_t      addr_size;          /*!< Number of bytes used for the flash
540                                     *   address. The value is \e n + 1
541                                     *   based. That is 0 = 1 byte, 1 = 2 bytes,
542                                     *   2 = 3 bytes, 3 = 4 bytes.
543                                     */
544  uint32_t      lower_wrprot_block; /*!< The block number that defines the lower
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  uint32_t      upper_wrprot_block; /*!< The block number that defines the upper
551                                     *   block in the range of blocks that is
552                                     *   protected from writing. This field
553                                     *   is ignored it write protection is
554                                     *   disabled.
555                                     */
556  bool          wrprot_enable;      /*!< The write region enable value. A value
557                                     *   of \b true enables write protection
558                                     *   on the region specified by the
559                                     *   \e lower_wrprot_block and
560                                     *   \e upper_wrprot_block range.
561                                     */
562} ALT_QSPI_DEV_SIZE_CONFIG_t;
563
564/******************************************************************************/
565/*!
566 * This type enumerates the QSPI clock phase activity options outside the SPI
567 * word.
568 */
569typedef enum ALT_QSPI_CLK_PHASE_e
570{
571  ALT_QSPI_CLK_PHASE_ACTIVE     = 0,    /*!< The SPI clock is active outside the
572                                         *   word
573                                         */
574  ALT_QSPI_CLK_PHASE_INACTIVE   = 1     /*!< The SPI clock is inactive outside the
575                                         *   word
576                                         */
577} ALT_QSPI_CLK_PHASE_t;
578
579/******************************************************************************/
580/*!
581 * This type enumerates the QSPI clock polarity options outside the SPI word.
582 */
583typedef enum ALT_QSPI_CLK_POLARITY_e
584{
585  ALT_QSPI_CLK_POLARITY_LOW     = 0,    /*!< SPI clock is quiescent low outside the
586                                         *   word.
587                                         */
588  ALT_QSPI_CLK_POLARITY_HIGH    = 1     /*!< SPI clock is quiescent high outside the
589                                         *   word.
590                                         */
591} ALT_QSPI_CLK_POLARITY_t;
592
593/******************************************************************************/
594/*!
595 * QSPI Controller Timing Configuration
596 *
597 * This type defines the structure used to configure timing paramaters used by
598 * the QSPI controller to communicate with a target flash device.
599 *
600 * All timing values are defined in cycles of the SPI master ref clock.
601 */
602typedef struct ALT_QSPI_TIMING_CONFIG_s
603{
604  ALT_QSPI_CLK_PHASE_t      clk_phase;  /*!< Selects whether the clock is in an
605                                         *   active or inactive phase outside the
606                                         *   SPI word.
607                                         */
608
609  ALT_QSPI_CLK_POLARITY_t   clk_pol;    /*!< Selects whether the clock is quiescent
610                                         *   low or high outside the SPI word.
611                                         */
612
613  uint32_t                  cs_da;      /*!< Chip Select De-Assert. Added delay in
614                                         *   master reference clocks for the length
615                                         *   that the master mode chip select
616                                         *   outputs are de-asserted between
617                                         *   transactions. If CSDA = \e X, then the
618                                         *   chip select de-assert time will be: 1
619                                         *   sclk_out + 1 ref_clk + \e X ref_clks.
620                                         */
621  uint32_t                  cs_dads;    /*!< Chip Select De-Assert Different
622                                         *   Slaves. Delay in master reference
623                                         *   clocks between one chip select being
624                                         *   de-activated and the activation of
625                                         *   another. This is used to ensure a quiet
626                                         *   period between the selection of two
627                                         *   different slaves.  CSDADS is only
628                                         *   relevant when switching between 2
629                                         *   different external flash devices. If
630                                         *   CSDADS = \e X, then the delay will be:
631                                         *   1 sclk_out + 3 ref_clks + \e X
632                                         *   ref_clks.
633                                         */
634  uint32_t                  cs_eot;     /*!< Chip Select End Of Transfer. Delay in
635                                         *   master reference clocks between last
636                                         *   bit of current transaction and
637                                         *   de-asserting the device chip select
638                                         *   (n_ss_out). By default (when CSEOT=0),
639                                         *   the chip select will be de-asserted on
640                                         *   the last falling edge of sclk_out at
641                                         *   the completion of the current
642                                         *   transaction. If CSEOT = \e X, then chip
643                                         *   selected will de-assert \e X ref_clks
644                                         *   after the last falling edge of
645                                         *   sclk_out.
646                                         */
647  uint32_t                  cs_sot;     /*!< Chip Select Start Of Transfer. Delay in
648                                         *   master reference clocks between setting
649                                         *   n_ss_out low and first bit transfer. By
650                                         *   default (CSSOT=0), chip select will be
651                                         *   asserted half a SCLK period before the
652                                         *   first rising edge of sclk_out. If CSSOT
653                                         *   = \e X, chip select will be asserted
654                                         *   half an sclk_out period before the
655                                         *   first rising edge of sclk_out + \e X
656                                         *   ref_clks.
657                                         */
658
659  uint32_t                  rd_datacap; /*!< The additional number of read data
660                                         *   capture cycles (ref_clk) that should be
661                                         *   applied to the internal read data
662                                         *   capture circuit.  The large
663                                         *   clock-to-out delay of the flash memory
664                                         *   together with trace delays as well as
665                                         *   other device delays may impose a
666                                         *   maximum flash clock frequency which is
667                                         *   less than the flash memory device
668                                         *   itself can operate at. To compensate,
669                                         *   software should set this register to a
670                                         *   value that guarantees robust data
671                                         *   captures.
672                                         */
673} ALT_QSPI_TIMING_CONFIG_t;
674
675/******************************************************************************/
676/*!
677 * Device Instruction Configuration
678 *
679 * This type defines a structure for specifying the optimal instruction set
680 * configuration to use with a target flash device.
681 */
682typedef struct ALT_QSPI_DEV_INST_CONFIG_s
683{
684  uint32_t              op_code;            /*!< The read or write op code to use
685                                             *   for the device transaction.
686                                             */
687  ALT_QSPI_MODE_t       inst_type;          /*!< Instruction mode type for the
688                                             *   controller to use with the
689                                             *   device. The instruction type
690                                             *   applies to all instructions
691                                             *   (reads and writes) issued from
692                                             *   either the Direct Access
693                                             *   Controller or the Indirect
694                                             *   Acces Controller.
695                                             */
696  ALT_QSPI_MODE_t       addr_xfer_type;     /*!< Address transfer mode type. The
697                                             *   value of this field is ignored
698                                             *   if the \e inst_type data member
699                                             *   is set to anything other than
700                                             *   ALT_QSPI_MODE_SINGLE. In that
701                                             *   case, the addr_xfer_type
702                                             *   assumes the same mode as the \e
703                                             *   inst_type.
704                                             */
705  ALT_QSPI_MODE_t       data_xfer_type;     /*!< Data transfer mode type. The
706                                             *   value of this field is ignored
707                                             *   if the \e inst_type data member
708                                             *   is set to anything other than
709                                             *   ALT_QSPI_MODE_SINGLE. In that
710                                             *   case, the data_xfer_type
711                                             *   assumes the same mode as the \e
712                                             *   inst_type.
713                                             */
714  uint32_t              dummy_cycles;       /*!< Number of dummy clock cycles
715                                             *   required by device for a read
716                                             *   or write instruction.
717                                             */
718
719} ALT_QSPI_DEV_INST_CONFIG_t;
720
721/******************************************************************************/
722/*!
723 * Get the current value of the QSPI master baud rate divisor.
724 *
725 * \returns     The value of the QSPI master baud rate divisor.
726 */
727ALT_QSPI_BAUD_DIV_t alt_qspi_baud_rate_div_get(void);
728
729/******************************************************************************/
730/*!
731 * Set the current value of the QSPI master baud rate divisor.
732 *
733 * Sets the value of the QSPI master baud rate divisor.
734 *
735 * \param       baud_rate_div
736 *              The master baud rate divisor. Valid range includes
737 *              even values 2 to 32.
738 *
739 * \retval      ALT_E_SUCCESS   Indicates successful completion.
740 * \retval      ALT_E_ERROR     Indicates an error occurred.
741 */
742ALT_STATUS_CODE alt_qspi_baud_rate_div_set(const ALT_QSPI_BAUD_DIV_t baud_rate_div);
743
744/******************************************************************************/
745/*!
746 * Get the current QSPI device peripheral chip select output and decode function
747 * configuration values.
748 *
749 * \param       cs
750 *              [out] The chip select line output values.
751 *
752 * \param       cs_mode
753 *              [out] The decode mode to use for the chip selects.
754 *
755 * \retval      ALT_E_SUCCESS   Indicates successful completion.
756 * \retval      ALT_E_ERROR     Indicates an error occurred.
757 */
758ALT_STATUS_CODE alt_qspi_chip_select_config_get(uint32_t* cs, ALT_QSPI_CS_MODE_t* cs_mode);
759
760/******************************************************************************/
761/*!
762 * Set the QSPI device peripheral chip select outputs and decode function
763 * configuration.
764 *
765 * The chip select lines output values operate according to the selected chip
766 * select decode mode. If \e cs_mode is ALT_QSPI_CS_MODE_SINGLE_SELECT then
767 * cs[3:0] are output thus:
768 *
769 *  cs[3:0]  | n_ss_out[3:0]
770 * :---------|:----------------------------
771 *  xxx0     | 1110
772 *  xx01     | 1101
773 *  x011     | 1011
774 *  0111     | 0111
775 *  1111     | 1111 (no peripheral selected)
776 *
777 * Otherwise if \e cs_mode is ALT_QSPI_CS_MODE_DECODE then cs[3:0] directly
778 * drives n_ss_out[3:0].
779 *
780 * \param       cs
781 *              The chip select line output values.
782 *
783 * \param       cs_mode
784 *              The decode mode to use for the chip selects.
785 *
786 * \retval      ALT_E_SUCCESS   Indicates successful completion.
787 * \retval      ALT_E_ERROR     Indicates an error occurred.
788 */
789ALT_STATUS_CODE alt_qspi_chip_select_config_set(const uint32_t cs,
790                                                const ALT_QSPI_CS_MODE_t cs_mode);
791
792/******************************************************************************/
793/*!
794 * Disable the mode bits from being sent after the address bytes.
795 *
796 * Prevent the mode bits defined in the Mode Bit Configuration register from
797 * being sent following the address bytes.
798 *
799 * \retval      ALT_E_SUCCESS   Indicates successful completion.
800 * \retval      ALT_E_ERROR     Indicates an error occurred.
801 */
802ALT_STATUS_CODE alt_qspi_mode_bit_disable(void);
803
804/******************************************************************************/
805/*!
806 * Enable the mode bits to be sent after the address bytes.
807 *
808 * Ensure the mode bits defined in the Mode Bit Configuration register to
809 * be sent following the address bytes.
810 *
811 * \retval      ALT_E_SUCCESS   Indicates successful completion.
812 * \retval      ALT_E_ERROR     Indicates an error occurred.
813 */
814ALT_STATUS_CODE alt_qspi_mode_bit_enable(void);
815
816/******************************************************************************/
817/*!
818 * Get the current value of the Mode Bit Configuration register.
819 *
820 * \returns     The 8 bit value that is sent to the device following the address
821 *              bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())
822 */
823uint32_t alt_qspi_mode_bit_config_get(void);
824
825/******************************************************************************/
826/*!
827 * Set the value of the Mode Bit Configuration register.
828 *
829 * Set the value of the 8 bits that are sent to the device following the address
830 * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())
831 *
832 * This API requires that the QSPI controller be idle, as determined by
833 * alt_qspi_is_idle().
834 *
835 * \param       mode_bits
836 *              The 8 bit value sent to the device following the address bytes.
837 *
838 * \retval      ALT_E_SUCCESS   Indicates successful completion.
839 * \retval      ALT_E_ERROR     Indicates an error occurred.
840 */
841ALT_STATUS_CODE alt_qspi_mode_bit_config_set(const uint32_t mode_bits);
842
843/******************************************************************************/
844/*!
845 * Get the current flash device size and write protection configuration.
846 *
847 * \param       cfg
848 *              [out] Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure to
849 *              contain the returned flash device size and write protection
850 *              configuration.
851 *
852 * \retval      ALT_E_SUCCESS   Indicates successful completion.
853 * \retval      ALT_E_ERROR     Indicates an error occurred.
854 */
855ALT_STATUS_CODE alt_qspi_device_size_config_get(ALT_QSPI_DEV_SIZE_CONFIG_t * cfg);
856
857/******************************************************************************/
858/*!
859 * Set the flash device size and write protection configuration.
860 *
861 * \param       cfg
862 *              Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the
863 *              flash device size and write protection configuration.
864 *
865 * \retval      ALT_E_SUCCESS   Indicates successful completion.
866 * \retval      ALT_E_ERROR     Indicates an error occurred.
867 */
868ALT_STATUS_CODE alt_qspi_device_size_config_set(const ALT_QSPI_DEV_SIZE_CONFIG_t * cfg);
869
870/******************************************************************************/
871/*!
872 * Get the current QSPI device read instruction configuration.
873 *
874 * \param       cfg
875 *              [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to
876 *              contain the returned QSPI controller instruction configuration
877 *              used when performing read transactions with the device.
878 *
879 * \retval      ALT_E_SUCCESS   Indicates successful completion.
880 * \retval      ALT_E_ERROR     Indicates an error occurred.
881 */
882ALT_STATUS_CODE alt_qspi_device_read_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg);
883
884/******************************************************************************/
885/*!
886 * Set the QSPI device read instruction configuration.
887 *
888 * This API requires that the QSPI controller be idle, as determined by
889 * alt_qspi_is_idle().
890 *
891 * \param       cfg
892 *              Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the
893 *              desired op code, transfer widths, and dummy cycles for the QSPI
894 *              controller to use when performing read transactions with the
895 *              device.
896 *
897 * \retval      ALT_E_SUCCESS   Indicates successful completion.
898 * \retval      ALT_E_ERROR     Indicates an error occurred.
899 */
900ALT_STATUS_CODE alt_qspi_device_read_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg);
901
902/******************************************************************************/
903/*!
904 * Get the current QSPI device write instruction configuration.
905 *
906 * \param       cfg
907 *              [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to
908 *              contain the returned QSPI controller instruction configuration
909 *              used when performing write transactions with the device.
910 *
911 * \retval      ALT_E_SUCCESS   Indicates successful completion.
912 * \retval      ALT_E_ERROR     Indicates an error occurred.
913 */
914ALT_STATUS_CODE alt_qspi_device_write_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg);
915
916/******************************************************************************/
917/*!
918 * Set the QSPI device write instruction configuration.
919 *
920 * This API requires that the QSPI controller be idle, as determined by
921 * alt_qspi_is_idle().
922 *
923 * \param       cfg
924 *              Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the
925 *              desired op code, transfer widths, and dummy cycles for the QSPI
926 *              controller to use when performing write transactions with the
927 *              device.
928 *
929 * \retval      ALT_E_SUCCESS   Indicates successful completion.
930 * \retval      ALT_E_ERROR     Indicates an error occurred.
931 */
932ALT_STATUS_CODE alt_qspi_device_write_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg);
933
934/******************************************************************************/
935/*!
936 * Get the QSPI device delay and timing configuration parameters.
937 *
938 * This function returns the settings of the chip select delay and timing
939 * configurations.
940 *
941 * \param       cfg
942 *              [out] Pointer to a ALT_QSPI_TIMING_CONFIG_t structure to return
943 *              the device timing and delay settings.
944 *
945 * \retval      ALT_E_SUCCESS   Indicates successful completion.
946 * \retval      ALT_E_ERROR     Indicates an error occurred.
947 */
948ALT_STATUS_CODE alt_qspi_timing_config_get(ALT_QSPI_TIMING_CONFIG_t * cfg);
949
950/******************************************************************************/
951/*!
952 * Set the QSPI device delay and timing configuration parameters.
953 *
954 * This function allows the user to configure how the chip select is driven
955 * after each flash access. This is required as each device may have different
956 * timing requirements.  As the serial clock frequency is increased, these
957 * timing parameters become more important and can be adjusted to meet the
958 * requirements of a specific flash device.  All timings are defined in cycles
959 * of the SPI master ref clock.
960 *
961 * This API requires that the QSPI controller be idle, as determined by
962 * alt_qspi_is_idle().
963 *
964 * \param       cfg
965 *              Pointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the
966 *              desired timing and delay settings.
967 *
968 * \retval      ALT_E_SUCCESS   Indicates successful completion.
969 * \retval      ALT_E_ERROR     Indicates an error occurred.
970 */
971ALT_STATUS_CODE alt_qspi_timing_config_set(const ALT_QSPI_TIMING_CONFIG_t * cfg);
972
973/*! @} */
974
975/******************************************************************************/
976/*! \addtogroup ALT_QSPI_DAC Direct Access Mode
977 *
978 * In direct access mode, an access to the AHB data slave triggers a read or
979 * write command to the flash memory. To use the direct access mode, enable the
980 * direct access controller with the alt_qspi_direct_enable() function. An
981 * external master, for example a processor, triggers the direct access
982 * controller with a read or write operation to the AHB data slave
983 * interface. The data slave exposes a 1MB window into the flash device. You can
984 * remap this window to any 1MB location within the flash device address range.
985 *
986 * To remap the AHB data slave to access other 1MB regions of the flash device,
987 * enable address remapping by calling alt_qspi_ahb_address_remap_enable(). All
988 * incoming data slave accesses remap to the offset specified in the remap
989 * address register which is configured by alt_qspi_ahb_remap_address_set().
990 *
991 * The 20 LSBs of incoming addresses are used for accessing the 1MB region and
992 * the higher bits are ignored.
993 *
994 * The quad SPI controller does not issue any error status for accesses that lie
995 * outside the connected flash memory space.
996 *
997 * @{
998 */
999
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 */
1007ALT_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 */
1016ALT_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 */
1027uint32_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 */
1045ALT_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 */
1058ALT_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 */
1072ALT_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 */
1126ALT_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 */
1137ALT_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 */
1146ALT_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 */
1158uint32_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 */
1171uint32_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 */
1189ALT_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 */
1201bool 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 */
1238ALT_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 */
1249ALT_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 */
1258ALT_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 */
1270uint32_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 */
1283uint32_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 */
1301ALT_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 */
1315bool 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 */
1367uint32_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 */
1384ALT_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 */
1411ALT_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 */
1426ALT_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 */
1435ALT_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 */
1471ALT_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 */
1483ALT_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 */
1503ALT_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 */
1530ALT_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__ */
Note: See TracBrowser for help on using the repository browser.