source: rtems/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_dma.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: 36.4 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#ifndef __ALT_DMA_H__
32#define __ALT_DMA_H__
33
34#include "hwlib.h"
35#include "alt_dma_common.h"
36#include "alt_dma_program.h"
37
38#ifdef __cplusplus
39extern "C"
40{
41#endif /* __cplusplus */
42
43/*!
44 * \addtogroup ALT_DMA DMA Controller API
45 *
46 * This module defines the API for configuration and use of the general purpose
47 * DMA controller for the SoC. The DMA controller is an instance of the ARM
48 * Corelink DMA Controller (DMA-330).
49 *
50 * References:
51 *  * ARM DDI 0424C, CoreLink DMA Controller DMA-330 Technical Reference
52 *    Manual.
53 *  * ARM DAI 0239A, Application Note 239 Example Programs for the CoreLink
54 *    DMA Controller DMA-330.
55 *  * Altera, Cyclone V Device Handbook Volume 3: Hard Processor System
56 *    Technical Reference Manual, DMA Controller.
57 *
58 * @{
59 */
60
61/*!
62 * \addtogroup ALT_DMA_COMPILE DMA API Compile Options
63 *
64 * This API provides control over the compile time inclusion of selected
65 * modules. This can allow for a smaller resulting binary.
66 *
67 * @{
68 */
69
70#ifndef ALT_DMA_PERIPH_PROVISION_16550_SUPPORT
71#define ALT_DMA_PERIPH_PROVISION_16550_SUPPORT (1)
72#endif
73
74#ifndef ALT_DMA_PERIPH_PROVISION_QSPI_SUPPORT
75#define ALT_DMA_PERIPH_PROVISION_QSPI_SUPPORT (1)
76#endif
77
78/*!
79 * @}
80 */
81
82/*!
83 * \addtogroup ALT_DMA_CSR DMA API for Configuration, Control, and Status
84 *
85 * This API provides functions for configuration, control, and status queries
86 * of the DMA controller.
87 *
88 * @{
89 */
90
91/*!
92 * This type definition enumerates the operational states that the DMA manager
93 * may have.
94 */
95typedef enum ALT_DMA_MANAGER_STATE_e
96{
97    ALT_DMA_MANAGER_STATE_STOPPED     = 0, /*!< Stopped */
98    ALT_DMA_MANAGER_STATE_EXECUTING   = 1, /*!< Executing */
99    ALT_DMA_MANAGER_STATE_CACHE_MISS  = 2, /*!< Cache Miss */
100    ALT_DMA_MANAGER_STATE_UPDATING_PC = 3, /*!< Updating PC */
101    ALT_DMA_MANAGER_STATE_WFE         = 4, /*!< Waiting for Event */
102    ALT_DMA_MANAGER_STATE_FAULTING    = 15 /*!< Faulting */
103}
104ALT_DMA_MANAGER_STATE_t;
105
106/*!
107 * This type definition enumerates the operational states that a DMA channel
108 * may have.
109 */
110typedef enum ALT_DMA_CHANNEL_STATE_e
111{
112    ALT_DMA_CHANNEL_STATE_STOPPED             = 0,  /*!< Stopped */
113    ALT_DMA_CHANNEL_STATE_EXECUTING           = 1,  /*!< Executing */
114    ALT_DMA_CHANNEL_STATE_CACHE_MISS          = 2,  /*!< Cache Miss */
115    ALT_DMA_CHANNEL_STATE_UPDATING_PC         = 3,  /*!< Updating PC */
116    ALT_DMA_CHANNEL_STATE_WFE                 = 4,  /*!< Waiting for Event */
117    ALT_DMA_CHANNEL_STATE_AT_BARRIER          = 5,  /*!< At Barrier */
118    ALT_DMA_CHANNEL_STATE_WFP                 = 7,  /*!< Waiting for Peripheral */
119    ALT_DMA_CHANNEL_STATE_KILLING             = 8,  /*!< Killing */
120    ALT_DMA_CHANNEL_STATE_COMPLETING          = 9,  /*!< Completing */
121    ALT_DMA_CHANNEL_STATE_FAULTING_COMPLETING = 14, /*!< Faulting Completing */
122    ALT_DMA_CHANNEL_STATE_FAULTING            = 15  /*!< Faulting */
123}
124ALT_DMA_CHANNEL_STATE_t;
125
126/*!
127 * This type definition enumerates the possible fault status that the DMA
128 * manager can have as a register mask.
129 */
130typedef enum ALT_DMA_MANAGER_FAULT_e
131{
132    /*!
133     * The DMA manager abort occured because of an instruction issued through
134     * the debug interface.
135     */
136    ALT_DMA_MANAGER_FAULT_DBG_INSTR       = (int32_t)(1UL << 30),
137
138    /*!
139     * The DMA manager instruction fetch AXI bus response was not OKAY.
140     */
141    ALT_DMA_MANAGER_FAULT_INSTR_FETCH_ERR = (int32_t)(1UL << 16),
142
143    /*!
144     * The DMA manager attempted to execute DMAWFE or DMASEV with
145     * inappropriate security permissions.
146     */
147    ALT_DMA_MANAGER_FAULT_MGR_EVNT_ERR    = (int32_t)(1UL <<  5),
148
149    /*!
150     * The DMA manager attempted to execute DMAGO with inappropriate security
151     * permissions.
152     */
153    ALT_DMA_MANAGER_FAULT_DMAGO_ERR       = (int32_t)(1UL <<  4),
154
155    /*!
156     * The DMA manager attempted to execute an instruction operand that was
157     * not valid for the DMA configuration.
158     */
159    ALT_DMA_MANAGER_FAULT_OPERAND_INVALID = (int32_t)(1UL <<  1),
160
161    /*!
162     * The DMA manager attempted to execute an undefined instruction.
163     */
164    ALT_DMA_MANAGER_FAULT_UNDEF_INSTR     = (int32_t)(1UL <<  0)
165}
166ALT_DMA_MANAGER_FAULT_t;
167
168/*!
169 * This type definition enumerates the possible fault status that a channel
170 * may have as a register mask.
171 */
172typedef enum ALT_DMA_CHANNEL_FAULT_e
173{
174    /*!
175     * The DMA channel has locked up due to resource starvation.
176     */
177    ALT_DMA_CHANNEL_FAULT_LOCKUP_ERR          = (int32_t)(1UL << 31),
178
179    /*!
180     * The DMA channel abort occured because of an instruction issued through
181     * the debug interface.
182     */
183    ALT_DMA_CHANNEL_FAULT_DBG_INSTR           = (int32_t)(1UL << 30),
184
185    /*!
186     * The DMA channel data read AXI bus reponse was not OKAY.
187     */
188    ALT_DMA_CHANNEL_FAULT_DATA_READ_ERR       = (int32_t)(1UL << 18),
189
190    /*!
191     * The DMA channel data write AXI bus response was not OKAY.
192     */
193    ALT_DMA_CHANNEL_FAULT_DATA_WRITE_ERR      = (int32_t)(1UL << 17),
194
195    /*!
196     * The DMA channel instruction fetch AXI bus response was not OKAY.
197     */
198    ALT_DMA_CHANNEL_FAULT_INSTR_FETCH_ERR     = (int32_t)(1UL << 16),
199
200    /*!
201     * The DMA channel MFIFO did not have the data for the DMAST instruction.
202     */
203    ALT_DMA_CHANNEL_FAULT_ST_DATA_UNAVAILABLE = (int32_t)(1UL << 13),
204
205    /*!
206     * The DMA channel MFIFO is too small to hold the DMALD instruction data,
207     * or too small to servic the DMAST instruction request.
208     */
209    ALT_DMA_CHANNEL_FAULT_MFIFO_ERR           = (int32_t)(1UL << 12),
210
211    /*!
212     * The DMA channel in non-secure state attempted to perform a secure read
213     * or write.
214     */
215    ALT_DMA_CHANNEL_FAULT_CH_RDWR_ERR         = (int32_t)(1UL <<  7),
216
217    /*!
218     * The DMA channel in non-secure state attempted to execute the DMAWFP,
219     * DMALDP, DMASTP, or DMAFLUSHP instruction involving a secure peripheral.
220     */
221    ALT_DMA_CHANNEL_FAULT_CH_PERIPH_ERR       = (int32_t)(1UL <<  6),
222
223    /*!
224     * The DMA channel in non-secure state attempted to execute the DMAWFE or
225     * DMASEV instruction for a secure event or secure interrupt (if
226     * applicable).
227     */
228    ALT_DMA_CHANNEL_FAULT_CH_EVNT_ERR         = (int32_t)(1UL <<  5),
229
230    /*!
231     * The DMA channel attempted to execute an instruction operand that was
232     * not valid for the DMA configuration.
233     */
234    ALT_DMA_CHANNEL_FAULT_OPERAND_INVALID     = (int32_t)(1UL <<  1),
235
236    /*!
237     * The DMA channel attempted to execute an undefined instruction.
238     */
239    ALT_DMA_CHANNEL_FAULT_UNDEF_INSTR         = (int32_t)(1UL <<  0)
240}
241ALT_DMA_CHANNEL_FAULT_t;
242
243/*!
244 * This type definition enumerates the possible DMA event-interrupt behavior
245 * option selections when a DMASEV instruction is executed.
246 */
247typedef enum ALT_DMA_EVENT_SELECT_e
248{
249    /*!
250     * If the DMA controller executes DMASEV for the event-interrupt resource
251     * then the DMA sends the event to all of the channel threads.
252     */
253    ALT_DMA_EVENT_SELECT_SEND_EVT,
254
255    /*!
256     * If the DMA controller executes DMASEV for the event-interrupt resource
257     * then the DMA sets the \b irq[N] HIGH.
258     */
259    ALT_DMA_EVENT_SELECT_SIG_IRQ
260}
261ALT_DMA_EVENT_SELECT_t;
262
263/*!
264 * This type enumerates the DMA peripheral interface MUX selection options
265 * available.
266 */
267typedef enum ALT_DMA_PERIPH_MUX_e
268{
269    /*!
270     * Accept the reset default MUX selection
271     */ 
272    ALT_DMA_PERIPH_MUX_DEFAULT = 0,
273
274    /*!
275     * Select FPGA as the peripheral interface
276     */
277    ALT_DMA_PERIPH_MUX_FPGA    = 1,
278
279    /*!
280     * Select CAN as the peripheral interface
281     */
282    ALT_DMA_PERIPH_MUX_CAN     = 2
283}
284ALT_DMA_PERIPH_MUX_t;
285
286/*!
287 * This type defines the structure used to specify the configuration of the
288 * security states and peripheral interface MUX selections for the DMA
289 * controller.
290 */
291typedef struct ALT_DMA_CFG_s
292{
293    /*!
294     * DMA Manager security state configuration.
295     */
296    ALT_DMA_SECURITY_t manager_sec;
297
298    /*!
299     * DMA interrupt output security state configurations. Security state
300     * configurations are 0-based index-aligned with the enumeration values
301     * ALT_DMA_EVENT_0 through ALT_DMA_EVENT_7 of the ALT_DMA_EVENT_t type.
302     */
303    ALT_DMA_SECURITY_t irq_sec[8];
304
305    /*!
306     * Peripheral request interface security state configurations. Security
307     * state configurations are 0-based index-aligned with the enumeration
308     * values of the ALT_DMA_PERIPH_t type.
309     */
310    ALT_DMA_SECURITY_t periph_sec[32];
311
312    /*!
313     * DMA Peripheral Register Interface MUX Selections. MUX selections are
314     * 0-based index-aligned with the enumeration values
315     * ALT_DMA_PERIPH_FPGA_4_OR_CAN0_IF1 through
316     * ALT_DMA_PERIPH_FPGA_7_OR_CAN1_IF2 of the ALT_DMA_PERIPH_t type.
317     */
318    ALT_DMA_PERIPH_MUX_t periph_mux[4];
319}
320ALT_DMA_CFG_t;
321
322/*!
323 * Initialize the DMA controller.
324 *
325 * Initializes the DMA controller by setting the necessary control values to
326 * establish the security state and MUXed peripheral request interface selection
327 * configurations before taking the DMA controller out of reset.
328 *
329 * After the DMA is initialized, the following conditions hold true:
330 *  * All DMA channel threads are in the Stopped state.
331 *  * All DMA channel threads are available for allocation.
332 *  * DMA Manager thread is waiting for an instruction from either APB
333 *    interface.
334 *  * The security state configurations of the DMA Manager, interrupt outputs,
335 *    and peripheral request interfaces are established and immutable until the
336 *    DMA is reset.
337 *  * The MUXed peripheral request interface selection configurations are
338 *    established and immutable until the DMA is reset.
339 *
340 * \param       dma_cfg
341 *              A pointer to a ALT_DMA_CFG_t structure containing the desired
342 *              DMA controller security state and peripheral request interface
343 *              MUX selections.
344 *
345 * \retval      ALT_E_SUCCESS   The operation was successful.
346 * \retval      ALT_E_ERROR     The operation failed.
347 */
348ALT_STATUS_CODE alt_dma_init(const ALT_DMA_CFG_t * dma_cfg);
349
350/*!
351 * Uninitializes the DMA controller.
352 *
353 * Uninitializes the DMA controller by killing any running channel threads and
354 * putting the DMA controller into reset.
355 *
356 * \retval      ALT_E_SUCCESS   The operation was successful.
357 * \retval      ALT_E_ERROR     The operation failed.
358 */
359ALT_STATUS_CODE alt_dma_uninit(void);
360
361/*!
362 * Allocate a DMA channel resource for use.
363 *
364 * \param       channel
365 *              A DMA controller channel.
366 *
367 * \retval      ALT_E_SUCCESS   The operation was successful.
368 * \retval      ALT_E_ERROR     The operation failed.
369 */
370ALT_STATUS_CODE alt_dma_channel_alloc(ALT_DMA_CHANNEL_t channel);
371
372/*!
373 * Allocate a free DMA channel resource for use if there are any.
374 *
375 * \param       allocated
376 *              [out] A pointer to an output parameter that will contain the
377 *              channel allocated.
378 *
379 * \retval      ALT_E_SUCCESS   The operation was successful.
380 * \retval      ALT_E_ERROR     The operation failed. An unallocated channel
381 *                              may not be available at the time of the API
382 *                              call.
383 */
384ALT_STATUS_CODE alt_dma_channel_alloc_any(ALT_DMA_CHANNEL_t * allocated);
385
386/*!
387 * Free a DMA channel resource for reuse.
388 *
389 * \param       channel
390 *              The DMA controller channel resource to free.
391 *
392 * \retval      ALT_E_SUCCESS   The operation was successful.
393 * \retval      ALT_E_ERROR     The operation failed. The channel may not be in
394 *                              the STOPPED state.
395 */
396ALT_STATUS_CODE alt_dma_channel_free(ALT_DMA_CHANNEL_t channel);
397
398/*!
399 * Start execution of a DMA microcode program on the specified DMA channel
400 * thread resource.
401 *
402 * \param       channel
403 *              The DMA channel thread used to execute the microcode program.
404 *
405 * \param       pgm
406 *              The DMA microcode program.
407 *
408 * \retval      ALT_E_SUCCESS   The operation was successful.
409 * \retval      ALT_E_ERROR     The operation failed.
410 */
411ALT_STATUS_CODE alt_dma_channel_exec(ALT_DMA_CHANNEL_t channel,
412                                     ALT_DMA_PROGRAM_t * pgm);
413
414/*!
415 * Kill (abort) execution of any microcode program executing on the specified
416 * DMA channel thread resource.
417 *
418 * Terminates the channel thread of execution by issuing a DMAKILL instruction
419 * using the DMA APB slave interface.
420 *
421 * \param       channel
422 *              The DMA channel thread to abort any executing microcode program
423 *              on.
424 *
425 * \retval      ALT_E_SUCCESS   The operation was successful.
426 * \retval      ALT_E_ERROR     The operation failed.
427 * \retval      ALT_E_TMO       Timeout waiting for the channel to change into
428 *                              KILLING or STOPPED state.
429 */
430ALT_STATUS_CODE alt_dma_channel_kill(ALT_DMA_CHANNEL_t channel);
431
432/*!
433 * Returns the current register value for the given DMA channel.
434 *
435 * \param       channel
436 *              The DMA channel thread to abort any executing microcode program
437 *              on.
438 *
439 * \param       reg
440 *              Register to get the value for.
441 *
442 * \param       val
443 *              [out] The current value of the requested register.
444 *
445 * \retval      ALT_E_SUCCESS   The operation was successful.
446 * \retval      ALT_E_ERROR     The operation failed.
447 * \retval      ALT_E_BAD_ARG   The specified channel or register is invalid.
448 */
449ALT_STATUS_CODE alt_dma_channel_reg_get(ALT_DMA_CHANNEL_t channel,
450                                        ALT_DMA_PROGRAM_REG_t reg, uint32_t * val);
451
452/*!
453 * Signals the occurrence of an event or interrupt, using the specified event
454 * number.
455 *
456 * Causes the CPU to issue a DMASEV instruction using the DMA APB slave
457 * interface.
458 *
459 * The Interrupt Enable Register (INTEN) register is used to control if each
460 * event-interrupt resource is either an event or an interrupt. The INTEN
461 * register sets the event-interrupt resource to function as an:
462 *  * Event - The DMAC generates an event for the specified event-interrupt
463 *            resource. When the DMAC executes a DMAWFE instruction for the
464 *            same event-interrupt resource then it clears the event.
465 *  * Interrupt - The DMAC sets the \b IRQ[N] signal high, where
466 *                \e evt_num is the number of the specified event
467 *                resource. The interrupt must be cleared after being handled.
468 *
469 * When the configured to generate an event, this function may be used to
470 * restart one or more waiting DMA channels (i.e. having executed a DMAWFE
471 * instruction).
472 *
473 * See the following sections from the \e ARM DDI 0424C, CoreLink DMA Controller
474 * DMA-330 Technical Reference Manual for implementation details and use cases:
475 *  * 2.5.1, Issuing Instructions to the DMAC using a Slave Interface
476 *  * 2.7, Using Events and Interrupts
477 *
478 * \param       evt_num   
479 *              A DMA event-interrupt resource. Allowable event values may be
480 *              ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 but ALT_DMA_EVENT_ABORT is
481 *              not.
482 *
483 * \retval      ALT_E_SUCCESS   The operation was successful.
484 * \retval      ALT_E_ERROR     The operation failed.
485 * \retval      ALT_E_BAD_ARG   The given event number is invalid.
486 */
487ALT_STATUS_CODE alt_dma_send_event(ALT_DMA_EVENT_t evt_num);
488
489/*!
490 * Returns the current operational state of the DMA manager thread.
491 *
492 * \param       state
493 *              [out] Pointer to an output parameter to contain the DMA
494 *              channel thread state.
495 *
496 * \retval      ALT_E_SUCCESS   The operation was successful.
497 * \retval      ALT_E_ERROR     The operation failed.
498 */
499ALT_STATUS_CODE alt_dma_manager_state_get(ALT_DMA_MANAGER_STATE_t * state);
500
501/*!
502 * Returns the current operational state of the specified DMA channel thread.
503 *
504 * \param       channel
505 *              The DMA channel thread to return the operational state of.
506 *
507 * \param       state
508 *              [out] Pointer to an output parameter to contain the DMA
509 *              channel thread state.
510 *
511 * \retval      ALT_E_SUCCESS   The operation was successful.
512 * \retval      ALT_E_ERROR     The operation failed.
513 * \retval      ALT_E_BAD_ARG   The given channel identifier is invalid.
514 */
515ALT_STATUS_CODE alt_dma_channel_state_get(ALT_DMA_CHANNEL_t channel,
516                                          ALT_DMA_CHANNEL_STATE_t * state);
517
518/*!
519 * Return the current fault status of the DMA manager thread.
520 *
521 * \param       fault
522 *              [out] Pointer to an output parameter to contain the DMA
523 *              manager fault status.
524 *
525 * \retval      ALT_E_SUCCESS   The operation was successful.
526 * \retval      ALT_E_ERROR     The operation failed.
527 */
528ALT_STATUS_CODE alt_dma_manager_fault_status_get(ALT_DMA_MANAGER_FAULT_t * fault);
529
530/*!
531 * Return the current fault status of the specified DMA channel thread.
532 *
533 * \param       channel
534 *              The DMA channel thread to return the fault status of.
535 *
536 * \param       fault
537 *              [out] Pointer to an output parameter to contain the DMA
538 *              channel fault status.
539 *
540 * \retval      ALT_E_SUCCESS   The operation was successful.
541 * \retval      ALT_E_ERROR     The operation failed.
542 * \retval      ALT_E_BAD_ARG   The given channel identifier is invalid.
543 */
544ALT_STATUS_CODE alt_dma_channel_fault_status_get(ALT_DMA_CHANNEL_t channel,
545                                                 ALT_DMA_CHANNEL_FAULT_t * fault);
546
547/*!
548 * Select whether the DMA controller sends the specific event to all channel
549 * threads or signals an interrupt using the corressponding \b irq when a DMASEV
550 * instruction is executed for the specified event-interrupt resource number.
551 *
552 * \param       evt_num
553 *              The event-interrupt resource number. Valid values are
554 *              ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
555 *
556 * \param       opt
557 *              The desired behavior selection for \e evt_num when a DMASEV is
558 *              executed.
559 *
560 * \retval      ALT_E_SUCCESS   The operation was successful.
561 * \retval      ALT_E_ERROR     The operation failed.
562 * \retval      ALT_E_BAD_ARG   The given selection identifier is invalid.
563 */
564ALT_STATUS_CODE alt_dma_event_int_select(ALT_DMA_EVENT_t evt_num,
565                                         ALT_DMA_EVENT_SELECT_t opt);
566
567/*!
568 * Returns the status of the specified event-interrupt resource.
569 *
570 * Returns ALT_E_TRUE if event is active or \b irq[N] is HIGH and returns
571 * ALT_E_FALSE if event is inactive or \b irq[N] is LOW.
572 *
573 * \param       evt_num
574 *              The event-interrupt resource number. Valid values are
575 *              ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
576 *
577 * \retval      ALT_E_TRUE      Event is active or \b irq[N] is HIGH.
578 * \retval      ALT_E_FALSE     Event is inactive or \b irq[N] is LOW.
579 * \retval      ALT_E_ERROR     The operation failed.
580 * \retval      ALT_E_BAD_ARG   The given event identifier is invalid.
581 */
582ALT_STATUS_CODE alt_dma_event_int_status_get_raw(ALT_DMA_EVENT_t evt_num);
583
584/*!
585 * Returns the status of the specified interrupt resource.
586 *
587 * Returns ALT_E_TRUE if interrupt is active and therfore \b irq[N] is HIGH and
588 * returns ALT_E_FALSE if interrupt is inactive and therfore \b irq[N] is LOW.
589 *
590 * \param       irq_num
591 *              The interrupt resource number. Valid values are
592 *              ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
593 *
594 * \retval      ALT_E_TRUE      Event is active or \b irq[N] is HIGH.
595 * \retval      ALT_E_FALSE     Event is inactive or \b irq[N] is LOW.
596 * \retval      ALT_E_ERROR     The operation failed.
597 * \retval      ALT_E_BAD_ARG   The given event identifier is invalid.
598 */
599ALT_STATUS_CODE alt_dma_int_status_get(ALT_DMA_EVENT_t irq_num);
600
601/*!
602 * Clear the active (HIGH) status of the specified interrupt resource.
603 *
604 * If the specified interrupt is HIGH, then sets \b irq[N] to LOW if the
605 * event-interrupt resource is configured (see: alt_dma_event_int_enable())
606 * to signal an interrupt. Otherwise, the status of \b irq[N] does not change.
607 *
608 * \param       irq_num
609 *              The interrupt resource number. Valid values are
610 *              ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT.
611 *
612 * \retval      ALT_E_SUCCESS   The operation was successful.
613 * \retval      ALT_E_ERROR     The operation failed.
614 * \retval      ALT_E_BAD_ARG   The given event identifier is invalid.
615 */
616ALT_STATUS_CODE alt_dma_int_clear(ALT_DMA_EVENT_t irq_num);
617
618/*!
619 * @}
620 */
621
622/*!
623 * \addtogroup ALT_DMA_STD_OPS DMA API for Standard Operations
624 *
625 * The functions in this group provide common DMA operations for common bulk
626 * data transfers between:
627 *  * Memory to Memory
628 *  * Zero to Memory
629 *  * Memory to Peripheral
630 *  * Peripheral to Memory
631 *
632 * All DMA operations are asynchronous. The following are the ways to receive
633 * notification of a DMA transfer complete operation:
634 *  * Use alt_dma_channel_state_get() and poll for the
635 *    ALT_DMA_CHANNEL_STATE_STOPPED status.
636 *  * In conjunction with the interrupt API, use DMA events to signal an
637 *    interrupt. The event first must be configured to signal an interrupt
638 *    using alt_dma_event_int_select(). Configure the DMA program to send an
639 *    event.
640 *  * Construct a custom program which waits for a particular event number by
641 *    assemblying a DMAWFE using alt_dma_program_DMAWFE(). Then run the custom
642 *    program on a different channel. The custom program will wait until the
643 *    DMA program sends the event. Configure the DMA program to send an event.
644 *
645 * Cache related maintenance on the source and/or destinatino buffer are not
646 * handled the DMA API and are the responsibility of the programmer. This is
647 * because the DMA API does not have visibility into the current configuration
648 * of the MMU or know about any special considerations regarding the source
649 * and/or destination memory. The following are some example scenarios and
650 * cache maintenance related precautions that may need to be taken:
651 *  * alt_dma_memory_to_memory(): Source buffer should be cleaned or purged,
652 *    destination buffer should be invalidated.
653 *  * alt_dma_zero_to_memory(): Destination buffer should be invalidated.
654 *  * alt_dma_memory_to_register(): Source buffer should be cleaned or purged.
655 *  * alt_dma_register_to_memory(): Destination buffer should be invalidated.
656 *  * alt_dma_memory_to_periph(): Source buffer should be cleaned or purged.
657 *  * alt_dma_periph_to_memory(): Destination buffer should be invalidated.
658 *
659 * @{
660 */
661
662/*!
663 * Uses the DMA engine to asynchronously copy the specified memory from the
664 * given source address to the given destination address.
665 *
666 * Overlapping memory regions are not supported.
667 *
668 * \param       channel
669 *              The DMA channel thread to use for the transfer.
670 *
671 * \param       program
672 *              An allocated DMA program buffer to use for the life of the
673 *              transfer.
674 *
675 * \param       dest
676 *              The destination memory address to copy to.
677 *
678 * \param       src
679 *              The source memory address to copy from.
680 *
681 * \param       size
682 *              The size of the transfer in bytes.
683 *
684 * \param       send_evt
685 *              If set to true, the DMA engine will be instructed to send an
686 *              event upon completion or fault.
687 *
688 * \param       evt
689 *              If send_evt is true, the event specified will be sent.
690 *              Otherwise the parameter is ignored.
691 *
692 * \retval      ALT_E_SUCCESS   The operation was successful.
693 * \retval      ALT_E_ERROR     The operation failed.
694 * \retval      ALT_E_BAD_ARG   The given channel or event identifier (if
695 *                              used) is invalid, or the memory regions
696 *                              specified are overlapping.
697 */
698ALT_STATUS_CODE alt_dma_memory_to_memory(ALT_DMA_CHANNEL_t channel,
699                                         ALT_DMA_PROGRAM_t * program,
700                                         void * dest,
701                                         const void * src,
702                                         size_t size,
703                                         bool send_evt,
704                                         ALT_DMA_EVENT_t evt);
705
706/*!
707 * Uses the DMA engine to asynchronously zero out the specified memory buffer.
708 *
709 * \param       channel
710 *              The DMA channel thread to use for the transfer.
711 *
712 * \param       program
713 *              An allocated DMA program buffer to use for the life of the
714 *              transfer.
715 *
716 * \param       buf
717 *              The buffer memory address to zero out.
718 *
719 * \param       size
720 *              The size of the buffer in bytes.
721 *
722 * \param       send_evt
723 *              If set to true, the DMA engine will be instructed to send an
724 *              event upon completion or fault.
725 *
726 * \param       evt
727 *              If send_evt is true, the event specified will be sent.
728 *              Otherwise the parameter is ignored.
729 *
730 * \retval      ALT_E_SUCCESS   The operation was successful.
731 * \retval      ALT_E_ERROR     The operation failed.
732 * \retval      ALT_E_BAD_ARG   The given channel or event identifier (if
733 *                              used) is invalid.
734 */
735ALT_STATUS_CODE alt_dma_zero_to_memory(ALT_DMA_CHANNEL_t channel,
736                                       ALT_DMA_PROGRAM_t * program,
737                                       void * buf,
738                                       size_t size,
739                                       bool send_evt,
740                                       ALT_DMA_EVENT_t evt);
741
742/*!
743 * Uses the DMA engine to asynchronously transfer the contents of a memory
744 * buffer to a keyhole register.
745 *
746 * \param       channel
747 *              The DMA channel thread to use for the transfer.
748 *
749 * \param       program
750 *              An allocated DMA program buffer to use for the life of the
751 *              transfer.
752 *
753 * \param       dst_reg
754 *              The address of the register to write buffer to.
755 *
756 * \param       src_buf
757 *              The address of the memory buffer for the data.
758 *
759 * \param       count
760 *              The number of transfers to make.
761 *
762 * \param       register_width_bits
763 *              The width of the register to transfer to in bits. Valid values
764 *              are 8, 16, 32, and 64.
765 *
766 * \param       send_evt
767 *              If set to true, the DMA engine will be instructed to send an
768 *              event upon completion or fault.
769 *
770 * \param       evt
771 *              If send_evt is true, the event specified will be sent.
772 *              Otherwise the parameter is ignored.
773 *
774 * \retval      ALT_E_SUCCESS   The operation was successful.
775 * \retval      ALT_E_ERROR     The operation failed.
776 * \retval      ALT_E_BAD_ARG   The given channel, event identifier (if used),
777 *                              or register width are invalid, or if the
778 *                              destination register or source buffer is
779 *                              unaligned to the register width.
780 */
781ALT_STATUS_CODE alt_dma_memory_to_register(ALT_DMA_CHANNEL_t channel,
782                                           ALT_DMA_PROGRAM_t * program,
783                                           void * dst_reg,
784                                           const void * src_buf,
785                                           size_t count,
786                                           uint32_t register_width_bits,
787                                           bool send_evt,
788                                           ALT_DMA_EVENT_t evt);
789
790/*!
791 * Uses the DMA engine to asynchronously transfer the contents of a keyhole
792 * register to a memory buffer.
793 *
794 * \param       channel
795 *              The DMA channel thread to use for the transfer.
796 *
797 * \param       program
798 *              An allocated DMA program buffer to use for the life of the
799 *              transfer.
800 *
801 * \param       dst_buf
802 *              The address of the memory buffer to copy to.
803 *
804 * \param       src_reg
805 *              The address of the keyhole register to read from.
806 *
807 * \param       count
808 *              The number of transfers to make.
809 *
810 * \param       register_width_bits
811 *              The width of the register to transfer to in bits. Valid values
812 *              are 8, 16, 32, and 64.
813 *
814 * \param       send_evt
815 *              If set to true, the DMA engine will be instructed to send an
816 *              event upon completion or fault.
817 *
818 * \param       evt
819 *              If send_evt is true, the event specified will be sent.
820 *              Otherwise the parameter is ignored.
821 *
822 * \retval      ALT_E_SUCCESS   The operation was successful.
823 * \retval      ALT_E_ERROR     The operation failed.
824 * \retval      ALT_E_BAD_ARG   The given channel, event identifier (if used),
825 *                              or register width are invalid, or if the
826 *                              destination buffer or source register is
827 *                              unaligned to the register width.
828 */
829ALT_STATUS_CODE alt_dma_register_to_memory(ALT_DMA_CHANNEL_t channel,
830                                           ALT_DMA_PROGRAM_t * program,
831                                           void * dst_buf,
832                                           const void * src_reg,
833                                           size_t count,
834                                           uint32_t register_width_bits,
835                                           bool send_evt,
836                                           ALT_DMA_EVENT_t evt);
837
838/*!
839 * Uses the DMA engine to asynchronously copy memory from the given source
840 * address to the specified peripheral. Because different peripheral has
841 * different characteristics, individual peripherals need to be explicitly
842 * supported.
843 *
844 * The following lists the peripheral IDs supported by this API:
845 *  * ALT_DMA_PERIPH_QSPI_FLASH_TX
846 *  * ALT_DMA_PERIPH_UART0_TX
847 *  * ALT_DMA_PERIPH_UART1_TX
848 *
849 * \param       channel
850 *              The DMA channel thread to use for the transfer.
851 *
852 * \param       program
853 *              An allocated DMA program buffer to use for the life of the
854 *              transfer.
855 *
856 * \param       dest
857 *              The destination peripheral to copy memory to.
858 *
859 * \param       src
860 *              The source memory address to copy from.
861 *
862 * \param       size
863 *              The size of the transfer in bytes.
864 *
865 * \param       periph_info
866 *              A pointer to a peripheral specific data structure. The
867 *              following list shows what data structure should be used for
868 *              peripherals:
869 *               * ALT_DMA_PERIPH_QSPI_FLASH_TX: This parameter is ignored.
870 *               * ALT_DMA_PERIPH_UART0_TX: Use a pointer to the
871 *                 ALT_16550_HANDLE_t used to interact with that UART.
872 *               * ALT_DMA_PERIPH_UART1_TX: Use a pointer to the
873 *                 ALT_16550_HANDLE_t used to interact with that UART.
874 *
875 * \param       send_evt
876 *              If set to true, the DMA engine will be instructed to send an
877 *              event upon completion or fault.
878 *
879 * \param       evt
880 *              If send_evt is true, the event specified will be sent.
881 *              Otherwise the parameter is ignored.
882 *
883 * \retval      ALT_E_SUCCESS   The operation was successful.
884 * \retval      ALT_E_ERROR     The operation failed.
885 * \retval      ALT_E_BAD_ARG   The given channel, peripheral, or event
886 *                              identifier (if used) is invalid.
887 *
888 * \internal
889 * Priority peripheral IDs to be supported:
890 *  * ALT_DMA_PERIPH_FPGA_0
891 *  * ALT_DMA_PERIPH_FPGA_1
892 *  * ALT_DMA_PERIPH_FPGA_2
893 *  * ALT_DMA_PERIPH_FPGA_3
894 *  * ALT_DMA_PERIPH_FPGA_4
895 *  * ALT_DMA_PERIPH_FPGA_5
896 *  * ALT_DMA_PERIPH_FPGA_6
897 *  * ALT_DMA_PERIPH_FPGA_7
898 *  * ALT_DMA_PERIPH_I2C0_TX
899 *  * ALT_DMA_PERIPH_I2C1_TX
900 *  * ALT_DMA_PERIPH_I2C2_TX
901 *  * ALT_DMA_PERIPH_I2C3_TX
902 *  * ALT_DMA_PERIPH_SPI0_MASTER_TX
903 *  * ALT_DMA_PERIPH_SPI0_SLAVE_TX
904 *  * ALT_DMA_PERIPH_SPI1_MASTER_TX
905 *  * ALT_DMA_PERIPH_SPI1_SLAVE_TX
906 * \endinternal
907 */
908ALT_STATUS_CODE alt_dma_memory_to_periph(ALT_DMA_CHANNEL_t channel,
909                                         ALT_DMA_PROGRAM_t * program,
910                                         ALT_DMA_PERIPH_t dest,
911                                         const void * src,
912                                         size_t size,
913                                         void * periph_info,
914                                         bool send_evt,
915                                         ALT_DMA_EVENT_t evt);
916
917/*!
918 * Uses the DMA engine to copy memory from the specified peripheral to the
919 * given destination address. Because different peripheral has different
920 * characteristics, individual peripherals need to be explicitly supported.
921 *
922 * The following lists the peripheral IDs supported by this API:
923 *  * ALT_DMA_PERIPH_QSPI_FLASH_RX
924 *  * ALT_DMA_PERIPH_UART0_RX
925 *  * ALT_DMA_PERIPH_UART1_RX
926 *
927 * \param       channel
928 *              The DMA channel thread to use for the transfer.
929 *
930 * \param       program
931 *              An allocated DMA program buffer to use for the life of the
932 *              transfer.
933 *
934 * \param       dest
935 *              The destination memory address to copy to.
936 *
937 * \param       src
938 *              The source peripheral to copy memory from.
939 *
940 * \param       size
941 *              The size of the transfer in bytes.
942 *
943 * \param       periph_info
944 *              A pointer to a peripheral specific data structure. The
945 *              following list shows what data structure should be used for
946 *              peripherals:
947 *               * ALT_DMA_PERIPH_QSPI_FLASH_RX: This parameter is ignored.
948 *               * ALT_DMA_PERIPH_UART0_RX: Use a pointer to the
949 *                 ALT_16550_HANDLE_t used to interact with that UART.
950 *               * ALT_DMA_PERIPH_UART1_RX: Use a pointer to the
951 *                 ALT_16550_HANDLE_t used to interact with that UART.
952 *
953 * \param       send_evt
954 *              If set to true, the DMA engine will be instructed to send an
955 *              event upon completion or fault.
956 *
957 * \param       evt
958 *              If send_evt is true, the event specified will be sent.
959 *              Otherwise the parameter is ignored.
960 *
961 * \retval      ALT_E_SUCCESS   The operation was successful.
962 * \retval      ALT_E_ERROR     The operation failed.
963 * \retval      ALT_E_BAD_ARG   The given channel, peripheral, or event
964 *                              identifier (if used) is invalid.
965*
966 * \internal
967 * Priority peripheral IDs to be supported:
968 *  * ALT_DMA_PERIPH_FPGA_0
969 *  * ALT_DMA_PERIPH_FPGA_1
970 *  * ALT_DMA_PERIPH_FPGA_2
971 *  * ALT_DMA_PERIPH_FPGA_3
972 *  * ALT_DMA_PERIPH_FPGA_4
973 *  * ALT_DMA_PERIPH_FPGA_5
974 *  * ALT_DMA_PERIPH_FPGA_6
975 *  * ALT_DMA_PERIPH_FPGA_7
976 *  * ALT_DMA_PERIPH_I2C0_RX
977 *  * ALT_DMA_PERIPH_I2C1_RX
978 *  * ALT_DMA_PERIPH_I2C2_RX
979 *  * ALT_DMA_PERIPH_I2C3_RX
980 *  * ALT_DMA_PERIPH_SPI0_MASTER_RX
981 *  * ALT_DMA_PERIPH_SPI0_SLAVE_RX
982 *  * ALT_DMA_PERIPH_SPI1_MASTER_RX
983 *  * ALT_DMA_PERIPH_SPI1_SLAVE_RX
984 * \endinternal
985 */
986ALT_STATUS_CODE alt_dma_periph_to_memory(ALT_DMA_CHANNEL_t channel,
987                                         ALT_DMA_PROGRAM_t * program,
988                                         void * dest,
989                                         ALT_DMA_PERIPH_t src,
990                                         size_t size,
991                                         void * periph_info,
992                                         bool send_evt,
993                                         ALT_DMA_EVENT_t evt);
994
995/*!
996 * @}
997 */
998
999/*!
1000 * @}
1001 */
1002
1003#ifdef __cplusplus
1004}
1005#endif  /* __cplusplus */
1006
1007#endif  /* __ALT_DMA_H__ */
Note: See TracBrowser for help on using the repository browser.