source: rtems/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_qspi.h @ 76386c1

4.115
Last change on this file since 76386c1 was 76386c1, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 26, 2014 at 2:00:44 PM

bsp/altera-cyclone-v: Add DMA support hwlib files

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