LXR |
|
|
|
|||
File indexing completed on 2025-05-11 08:22:44
0001 /** 0002 * @file 0003 * 0004 * @ingroup RTEMSBSPsARMCycVContrib 0005 */ 0006 0007 /****************************************************************************** 0008 * 0009 * Copyright 2013 Altera Corporation. All Rights Reserved. 0010 * 0011 * Redistribution and use in source and binary forms, with or without 0012 * modification, are permitted provided that the following conditions are met: 0013 * 0014 * 1. Redistributions of source code must retain the above copyright notice, 0015 * this list of conditions and the following disclaimer. 0016 * 0017 * 2. Redistributions in binary form must reproduce the above copyright notice, 0018 * this list of conditions and the following disclaimer in the documentation 0019 * and/or other materials provided with the distribution. 0020 * 0021 * 3. The name of the author may not be used to endorse or promote products 0022 * derived from this software without specific prior written permission. 0023 * 0024 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR 0025 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 0026 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO 0027 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 0028 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 0029 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 0030 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 0031 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 0032 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 0033 * OF SUCH DAMAGE. 0034 * 0035 ******************************************************************************/ 0036 0037 #ifndef __ALT_DMA_H__ 0038 #define __ALT_DMA_H__ 0039 0040 #include "hwlib.h" 0041 #include "alt_dma_common.h" 0042 #include "alt_dma_program.h" 0043 0044 #ifdef __cplusplus 0045 extern "C" 0046 { 0047 #endif /* __cplusplus */ 0048 0049 /*! 0050 * \addtogroup ALT_DMA DMA Controller API 0051 * 0052 * This module defines the API for configuration and use of the general purpose 0053 * DMA controller for the SoC. The DMA controller is an instance of the ARM 0054 * Corelink DMA Controller (DMA-330). 0055 * 0056 * References: 0057 * * ARM DDI 0424C, CoreLink DMA Controller DMA-330 Technical Reference 0058 * Manual. 0059 * * ARM DAI 0239A, Application Note 239 Example Programs for the CoreLink 0060 * DMA Controller DMA-330. 0061 * * Altera, Cyclone V Device Handbook Volume 3: Hard Processor System 0062 * Technical Reference Manual, DMA Controller. 0063 * 0064 * @{ 0065 */ 0066 0067 /*! 0068 * \addtogroup ALT_DMA_COMPILE DMA API Compile Options 0069 * 0070 * This API provides control over the compile time inclusion of selected 0071 * modules. This can allow for a smaller resulting binary. 0072 * 0073 * @{ 0074 */ 0075 0076 #ifndef ALT_DMA_PERIPH_PROVISION_16550_SUPPORT 0077 #define ALT_DMA_PERIPH_PROVISION_16550_SUPPORT (1) 0078 #endif 0079 0080 #ifndef ALT_DMA_PERIPH_PROVISION_QSPI_SUPPORT 0081 #define ALT_DMA_PERIPH_PROVISION_QSPI_SUPPORT (1) 0082 #endif 0083 0084 /*! 0085 * @} 0086 */ 0087 0088 /*! 0089 * \addtogroup ALT_DMA_CSR DMA API for Configuration, Control, and Status 0090 * 0091 * This API provides functions for configuration, control, and status queries 0092 * of the DMA controller. 0093 * 0094 * @{ 0095 */ 0096 0097 /*! 0098 * This type definition enumerates the operational states that the DMA manager 0099 * may have. 0100 */ 0101 typedef enum ALT_DMA_MANAGER_STATE_e 0102 { 0103 ALT_DMA_MANAGER_STATE_STOPPED = 0, /*!< Stopped */ 0104 ALT_DMA_MANAGER_STATE_EXECUTING = 1, /*!< Executing */ 0105 ALT_DMA_MANAGER_STATE_CACHE_MISS = 2, /*!< Cache Miss */ 0106 ALT_DMA_MANAGER_STATE_UPDATING_PC = 3, /*!< Updating PC */ 0107 ALT_DMA_MANAGER_STATE_WFE = 4, /*!< Waiting for Event */ 0108 ALT_DMA_MANAGER_STATE_FAULTING = 15 /*!< Faulting */ 0109 } 0110 ALT_DMA_MANAGER_STATE_t; 0111 0112 /*! 0113 * This type definition enumerates the operational states that a DMA channel 0114 * may have. 0115 */ 0116 typedef enum ALT_DMA_CHANNEL_STATE_e 0117 { 0118 ALT_DMA_CHANNEL_STATE_STOPPED = 0, /*!< Stopped */ 0119 ALT_DMA_CHANNEL_STATE_EXECUTING = 1, /*!< Executing */ 0120 ALT_DMA_CHANNEL_STATE_CACHE_MISS = 2, /*!< Cache Miss */ 0121 ALT_DMA_CHANNEL_STATE_UPDATING_PC = 3, /*!< Updating PC */ 0122 ALT_DMA_CHANNEL_STATE_WFE = 4, /*!< Waiting for Event */ 0123 ALT_DMA_CHANNEL_STATE_AT_BARRIER = 5, /*!< At Barrier */ 0124 ALT_DMA_CHANNEL_STATE_WFP = 7, /*!< Waiting for Peripheral */ 0125 ALT_DMA_CHANNEL_STATE_KILLING = 8, /*!< Killing */ 0126 ALT_DMA_CHANNEL_STATE_COMPLETING = 9, /*!< Completing */ 0127 ALT_DMA_CHANNEL_STATE_FAULTING_COMPLETING = 14, /*!< Faulting Completing */ 0128 ALT_DMA_CHANNEL_STATE_FAULTING = 15 /*!< Faulting */ 0129 } 0130 ALT_DMA_CHANNEL_STATE_t; 0131 0132 /*! 0133 * This type definition enumerates the possible fault status that the DMA 0134 * manager can have as a register mask. 0135 */ 0136 typedef enum ALT_DMA_MANAGER_FAULT_e 0137 { 0138 /*! 0139 * The DMA manager abort occured because of an instruction issued through 0140 * the debug interface. 0141 */ 0142 ALT_DMA_MANAGER_FAULT_DBG_INSTR = (int32_t)(1UL << 30), 0143 0144 /*! 0145 * The DMA manager instruction fetch AXI bus response was not OKAY. 0146 */ 0147 ALT_DMA_MANAGER_FAULT_INSTR_FETCH_ERR = (int32_t)(1UL << 16), 0148 0149 /*! 0150 * The DMA manager attempted to execute DMAWFE or DMASEV with 0151 * inappropriate security permissions. 0152 */ 0153 ALT_DMA_MANAGER_FAULT_MGR_EVNT_ERR = (int32_t)(1UL << 5), 0154 0155 /*! 0156 * The DMA manager attempted to execute DMAGO with inappropriate security 0157 * permissions. 0158 */ 0159 ALT_DMA_MANAGER_FAULT_DMAGO_ERR = (int32_t)(1UL << 4), 0160 0161 /*! 0162 * The DMA manager attempted to execute an instruction operand that was 0163 * not valid for the DMA configuration. 0164 */ 0165 ALT_DMA_MANAGER_FAULT_OPERAND_INVALID = (int32_t)(1UL << 1), 0166 0167 /*! 0168 * The DMA manager attempted to execute an undefined instruction. 0169 */ 0170 ALT_DMA_MANAGER_FAULT_UNDEF_INSTR = (int32_t)(1UL << 0) 0171 } 0172 ALT_DMA_MANAGER_FAULT_t; 0173 0174 /*! 0175 * This type definition enumerates the possible fault status that a channel 0176 * may have as a register mask. 0177 */ 0178 typedef enum ALT_DMA_CHANNEL_FAULT_e 0179 { 0180 /*! 0181 * The DMA channel has locked up due to resource starvation. 0182 */ 0183 ALT_DMA_CHANNEL_FAULT_LOCKUP_ERR = (int32_t)(1UL << 31), 0184 0185 /*! 0186 * The DMA channel abort occured because of an instruction issued through 0187 * the debug interface. 0188 */ 0189 ALT_DMA_CHANNEL_FAULT_DBG_INSTR = (int32_t)(1UL << 30), 0190 0191 /*! 0192 * The DMA channel data read AXI bus reponse was not OKAY. 0193 */ 0194 ALT_DMA_CHANNEL_FAULT_DATA_READ_ERR = (int32_t)(1UL << 18), 0195 0196 /*! 0197 * The DMA channel data write AXI bus response was not OKAY. 0198 */ 0199 ALT_DMA_CHANNEL_FAULT_DATA_WRITE_ERR = (int32_t)(1UL << 17), 0200 0201 /*! 0202 * The DMA channel instruction fetch AXI bus response was not OKAY. 0203 */ 0204 ALT_DMA_CHANNEL_FAULT_INSTR_FETCH_ERR = (int32_t)(1UL << 16), 0205 0206 /*! 0207 * The DMA channel MFIFO did not have the data for the DMAST instruction. 0208 */ 0209 ALT_DMA_CHANNEL_FAULT_ST_DATA_UNAVAILABLE = (int32_t)(1UL << 13), 0210 0211 /*! 0212 * The DMA channel MFIFO is too small to hold the DMALD instruction data, 0213 * or too small to servic the DMAST instruction request. 0214 */ 0215 ALT_DMA_CHANNEL_FAULT_MFIFO_ERR = (int32_t)(1UL << 12), 0216 0217 /*! 0218 * The DMA channel in non-secure state attempted to perform a secure read 0219 * or write. 0220 */ 0221 ALT_DMA_CHANNEL_FAULT_CH_RDWR_ERR = (int32_t)(1UL << 7), 0222 0223 /*! 0224 * The DMA channel in non-secure state attempted to execute the DMAWFP, 0225 * DMALDP, DMASTP, or DMAFLUSHP instruction involving a secure peripheral. 0226 */ 0227 ALT_DMA_CHANNEL_FAULT_CH_PERIPH_ERR = (int32_t)(1UL << 6), 0228 0229 /*! 0230 * The DMA channel in non-secure state attempted to execute the DMAWFE or 0231 * DMASEV instruction for a secure event or secure interrupt (if 0232 * applicable). 0233 */ 0234 ALT_DMA_CHANNEL_FAULT_CH_EVNT_ERR = (int32_t)(1UL << 5), 0235 0236 /*! 0237 * The DMA channel attempted to execute an instruction operand that was 0238 * not valid for the DMA configuration. 0239 */ 0240 ALT_DMA_CHANNEL_FAULT_OPERAND_INVALID = (int32_t)(1UL << 1), 0241 0242 /*! 0243 * The DMA channel attempted to execute an undefined instruction. 0244 */ 0245 ALT_DMA_CHANNEL_FAULT_UNDEF_INSTR = (int32_t)(1UL << 0) 0246 } 0247 ALT_DMA_CHANNEL_FAULT_t; 0248 0249 /*! 0250 * This type definition enumerates the possible DMA event-interrupt behavior 0251 * option selections when a DMASEV instruction is executed. 0252 */ 0253 typedef enum ALT_DMA_EVENT_SELECT_e 0254 { 0255 /*! 0256 * If the DMA controller executes DMASEV for the event-interrupt resource 0257 * then the DMA sends the event to all of the channel threads. 0258 */ 0259 ALT_DMA_EVENT_SELECT_SEND_EVT, 0260 0261 /*! 0262 * If the DMA controller executes DMASEV for the event-interrupt resource 0263 * then the DMA sets the \b irq[N] HIGH. 0264 */ 0265 ALT_DMA_EVENT_SELECT_SIG_IRQ 0266 } 0267 ALT_DMA_EVENT_SELECT_t; 0268 0269 /*! 0270 * This type enumerates the DMA peripheral interface MUX selection options 0271 * available. 0272 */ 0273 typedef enum ALT_DMA_PERIPH_MUX_e 0274 { 0275 /*! 0276 * Accept the reset default MUX selection 0277 */ 0278 ALT_DMA_PERIPH_MUX_DEFAULT = 0, 0279 0280 /*! 0281 * Select FPGA as the peripheral interface 0282 */ 0283 ALT_DMA_PERIPH_MUX_FPGA = 1, 0284 0285 /*! 0286 * Select CAN as the peripheral interface 0287 */ 0288 ALT_DMA_PERIPH_MUX_CAN = 2 0289 } 0290 ALT_DMA_PERIPH_MUX_t; 0291 0292 /*! 0293 * This type defines the structure used to specify the configuration of the 0294 * security states and peripheral interface MUX selections for the DMA 0295 * controller. 0296 */ 0297 typedef struct ALT_DMA_CFG_s 0298 { 0299 /*! 0300 * DMA Manager security state configuration. 0301 */ 0302 ALT_DMA_SECURITY_t manager_sec; 0303 0304 /*! 0305 * DMA interrupt output security state configurations. Security state 0306 * configurations are 0-based index-aligned with the enumeration values 0307 * ALT_DMA_EVENT_0 through ALT_DMA_EVENT_7 of the ALT_DMA_EVENT_t type. 0308 */ 0309 ALT_DMA_SECURITY_t irq_sec[8]; 0310 0311 /*! 0312 * Peripheral request interface security state configurations. Security 0313 * state configurations are 0-based index-aligned with the enumeration 0314 * values of the ALT_DMA_PERIPH_t type. 0315 */ 0316 ALT_DMA_SECURITY_t periph_sec[32]; 0317 0318 /*! 0319 * DMA Peripheral Register Interface MUX Selections. MUX selections are 0320 * 0-based index-aligned with the enumeration values 0321 * ALT_DMA_PERIPH_FPGA_4_OR_CAN0_IF1 through 0322 * ALT_DMA_PERIPH_FPGA_7_OR_CAN1_IF2 of the ALT_DMA_PERIPH_t type. 0323 */ 0324 ALT_DMA_PERIPH_MUX_t periph_mux[4]; 0325 } 0326 ALT_DMA_CFG_t; 0327 0328 /*! 0329 * Initialize the DMA controller. 0330 * 0331 * Initializes the DMA controller by setting the necessary control values to 0332 * establish the security state and MUXed peripheral request interface selection 0333 * configurations before taking the DMA controller out of reset. 0334 * 0335 * After the DMA is initialized, the following conditions hold true: 0336 * * All DMA channel threads are in the Stopped state. 0337 * * All DMA channel threads are available for allocation. 0338 * * DMA Manager thread is waiting for an instruction from either APB 0339 * interface. 0340 * * The security state configurations of the DMA Manager, interrupt outputs, 0341 * and peripheral request interfaces are established and immutable until the 0342 * DMA is reset. 0343 * * The MUXed peripheral request interface selection configurations are 0344 * established and immutable until the DMA is reset. 0345 * 0346 * \param dma_cfg 0347 * A pointer to a ALT_DMA_CFG_t structure containing the desired 0348 * DMA controller security state and peripheral request interface 0349 * MUX selections. 0350 * 0351 * \retval ALT_E_SUCCESS The operation was successful. 0352 * \retval ALT_E_ERROR The operation failed. 0353 */ 0354 ALT_STATUS_CODE alt_dma_init(const ALT_DMA_CFG_t * dma_cfg); 0355 0356 /*! 0357 * Uninitializes the DMA controller. 0358 * 0359 * Uninitializes the DMA controller by killing any running channel threads and 0360 * putting the DMA controller into reset. 0361 * 0362 * \retval ALT_E_SUCCESS The operation was successful. 0363 * \retval ALT_E_ERROR The operation failed. 0364 */ 0365 ALT_STATUS_CODE alt_dma_uninit(void); 0366 0367 /*! 0368 * Allocate a DMA channel resource for use. 0369 * 0370 * \param channel 0371 * A DMA controller channel. 0372 * 0373 * \retval ALT_E_SUCCESS The operation was successful. 0374 * \retval ALT_E_ERROR The operation failed. 0375 */ 0376 ALT_STATUS_CODE alt_dma_channel_alloc(ALT_DMA_CHANNEL_t channel); 0377 0378 /*! 0379 * Allocate a free DMA channel resource for use if there are any. 0380 * 0381 * \param allocated 0382 * [out] A pointer to an output parameter that will contain the 0383 * channel allocated. 0384 * 0385 * \retval ALT_E_SUCCESS The operation was successful. 0386 * \retval ALT_E_ERROR The operation failed. An unallocated channel 0387 * may not be available at the time of the API 0388 * call. 0389 */ 0390 ALT_STATUS_CODE alt_dma_channel_alloc_any(ALT_DMA_CHANNEL_t * allocated); 0391 0392 /*! 0393 * Free a DMA channel resource for reuse. 0394 * 0395 * \param channel 0396 * The DMA controller channel resource to free. 0397 * 0398 * \retval ALT_E_SUCCESS The operation was successful. 0399 * \retval ALT_E_ERROR The operation failed. The channel may not be in 0400 * the STOPPED state. 0401 */ 0402 ALT_STATUS_CODE alt_dma_channel_free(ALT_DMA_CHANNEL_t channel); 0403 0404 /*! 0405 * Start execution of a DMA microcode program on the specified DMA channel 0406 * thread resource. 0407 * 0408 * \param channel 0409 * The DMA channel thread used to execute the microcode program. 0410 * 0411 * \param pgm 0412 * The DMA microcode program. 0413 * 0414 * \retval ALT_E_SUCCESS The operation was successful. 0415 * \retval ALT_E_ERROR The operation failed. 0416 */ 0417 ALT_STATUS_CODE alt_dma_channel_exec(ALT_DMA_CHANNEL_t channel, 0418 ALT_DMA_PROGRAM_t * pgm); 0419 0420 /*! 0421 * Kill (abort) execution of any microcode program executing on the specified 0422 * DMA channel thread resource. 0423 * 0424 * Terminates the channel thread of execution by issuing a DMAKILL instruction 0425 * using the DMA APB slave interface. 0426 * 0427 * \param channel 0428 * The DMA channel thread to abort any executing microcode program 0429 * on. 0430 * 0431 * \retval ALT_E_SUCCESS The operation was successful. 0432 * \retval ALT_E_ERROR The operation failed. 0433 * \retval ALT_E_TMO Timeout waiting for the channel to change into 0434 * KILLING or STOPPED state. 0435 */ 0436 ALT_STATUS_CODE alt_dma_channel_kill(ALT_DMA_CHANNEL_t channel); 0437 0438 /*! 0439 * Returns the current register value for the given DMA channel. 0440 * 0441 * \param channel 0442 * The DMA channel thread to abort any executing microcode program 0443 * on. 0444 * 0445 * \param reg 0446 * Register to get the value for. 0447 * 0448 * \param val 0449 * [out] The current value of the requested register. 0450 * 0451 * \retval ALT_E_SUCCESS The operation was successful. 0452 * \retval ALT_E_ERROR The operation failed. 0453 * \retval ALT_E_BAD_ARG The specified channel or register is invalid. 0454 */ 0455 ALT_STATUS_CODE alt_dma_channel_reg_get(ALT_DMA_CHANNEL_t channel, 0456 ALT_DMA_PROGRAM_REG_t reg, uint32_t * val); 0457 0458 /*! 0459 * Signals the occurrence of an event or interrupt, using the specified event 0460 * number. 0461 * 0462 * Causes the CPU to issue a DMASEV instruction using the DMA APB slave 0463 * interface. 0464 * 0465 * The Interrupt Enable Register (INTEN) register is used to control if each 0466 * event-interrupt resource is either an event or an interrupt. The INTEN 0467 * register sets the event-interrupt resource to function as an: 0468 * * Event - The DMAC generates an event for the specified event-interrupt 0469 * resource. When the DMAC executes a DMAWFE instruction for the 0470 * same event-interrupt resource then it clears the event. 0471 * * Interrupt - The DMAC sets the \b IRQ[N] signal high, where 0472 * \e evt_num is the number of the specified event 0473 * resource. The interrupt must be cleared after being handled. 0474 * 0475 * When the configured to generate an event, this function may be used to 0476 * restart one or more waiting DMA channels (i.e. having executed a DMAWFE 0477 * instruction). 0478 * 0479 * See the following sections from the \e ARM DDI 0424C, CoreLink DMA Controller 0480 * DMA-330 Technical Reference Manual for implementation details and use cases: 0481 * * 2.5.1, Issuing Instructions to the DMAC using a Slave Interface 0482 * * 2.7, Using Events and Interrupts 0483 * 0484 * \param evt_num 0485 * A DMA event-interrupt resource. Allowable event values may be 0486 * ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 but ALT_DMA_EVENT_ABORT is 0487 * not. 0488 * 0489 * \retval ALT_E_SUCCESS The operation was successful. 0490 * \retval ALT_E_ERROR The operation failed. 0491 * \retval ALT_E_BAD_ARG The given event number is invalid. 0492 */ 0493 ALT_STATUS_CODE alt_dma_send_event(ALT_DMA_EVENT_t evt_num); 0494 0495 /*! 0496 * Returns the current operational state of the DMA manager thread. 0497 * 0498 * \param state 0499 * [out] Pointer to an output parameter to contain the DMA 0500 * channel thread state. 0501 * 0502 * \retval ALT_E_SUCCESS The operation was successful. 0503 * \retval ALT_E_ERROR The operation failed. 0504 */ 0505 ALT_STATUS_CODE alt_dma_manager_state_get(ALT_DMA_MANAGER_STATE_t * state); 0506 0507 /*! 0508 * Returns the current operational state of the specified DMA channel thread. 0509 * 0510 * \param channel 0511 * The DMA channel thread to return the operational state of. 0512 * 0513 * \param state 0514 * [out] Pointer to an output parameter to contain the DMA 0515 * channel thread state. 0516 * 0517 * \retval ALT_E_SUCCESS The operation was successful. 0518 * \retval ALT_E_ERROR The operation failed. 0519 * \retval ALT_E_BAD_ARG The given channel identifier is invalid. 0520 */ 0521 ALT_STATUS_CODE alt_dma_channel_state_get(ALT_DMA_CHANNEL_t channel, 0522 ALT_DMA_CHANNEL_STATE_t * state); 0523 0524 /*! 0525 * Return the current fault status of the DMA manager thread. 0526 * 0527 * \param fault 0528 * [out] Pointer to an output parameter to contain the DMA 0529 * manager fault status. 0530 * 0531 * \retval ALT_E_SUCCESS The operation was successful. 0532 * \retval ALT_E_ERROR The operation failed. 0533 */ 0534 ALT_STATUS_CODE alt_dma_manager_fault_status_get(ALT_DMA_MANAGER_FAULT_t * fault); 0535 0536 /*! 0537 * Return the current fault status of the specified DMA channel thread. 0538 * 0539 * \param channel 0540 * The DMA channel thread to return the fault status of. 0541 * 0542 * \param fault 0543 * [out] Pointer to an output parameter to contain the DMA 0544 * channel fault status. 0545 * 0546 * \retval ALT_E_SUCCESS The operation was successful. 0547 * \retval ALT_E_ERROR The operation failed. 0548 * \retval ALT_E_BAD_ARG The given channel identifier is invalid. 0549 */ 0550 ALT_STATUS_CODE alt_dma_channel_fault_status_get(ALT_DMA_CHANNEL_t channel, 0551 ALT_DMA_CHANNEL_FAULT_t * fault); 0552 0553 /*! 0554 * Select whether the DMA controller sends the specific event to all channel 0555 * threads or signals an interrupt using the corressponding \b irq when a DMASEV 0556 * instruction is executed for the specified event-interrupt resource number. 0557 * 0558 * \param evt_num 0559 * The event-interrupt resource number. Valid values are 0560 * ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT. 0561 * 0562 * \param opt 0563 * The desired behavior selection for \e evt_num when a DMASEV is 0564 * executed. 0565 * 0566 * \retval ALT_E_SUCCESS The operation was successful. 0567 * \retval ALT_E_ERROR The operation failed. 0568 * \retval ALT_E_BAD_ARG The given selection identifier is invalid. 0569 */ 0570 ALT_STATUS_CODE alt_dma_event_int_select(ALT_DMA_EVENT_t evt_num, 0571 ALT_DMA_EVENT_SELECT_t opt); 0572 0573 /*! 0574 * Returns the status of the specified event-interrupt resource. 0575 * 0576 * Returns ALT_E_TRUE if event is active or \b irq[N] is HIGH and returns 0577 * ALT_E_FALSE if event is inactive or \b irq[N] is LOW. 0578 * 0579 * \param evt_num 0580 * The event-interrupt resource number. Valid values are 0581 * ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT. 0582 * 0583 * \retval ALT_E_TRUE Event is active or \b irq[N] is HIGH. 0584 * \retval ALT_E_FALSE Event is inactive or \b irq[N] is LOW. 0585 * \retval ALT_E_ERROR The operation failed. 0586 * \retval ALT_E_BAD_ARG The given event identifier is invalid. 0587 */ 0588 ALT_STATUS_CODE alt_dma_event_int_status_get_raw(ALT_DMA_EVENT_t evt_num); 0589 0590 /*! 0591 * Returns the status of the specified interrupt resource. 0592 * 0593 * Returns ALT_E_TRUE if interrupt is active and therfore \b irq[N] is HIGH and 0594 * returns ALT_E_FALSE if interrupt is inactive and therfore \b irq[N] is LOW. 0595 * 0596 * \param irq_num 0597 * The interrupt resource number. Valid values are 0598 * ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT. 0599 * 0600 * \retval ALT_E_TRUE Event is active or \b irq[N] is HIGH. 0601 * \retval ALT_E_FALSE Event is inactive or \b irq[N] is LOW. 0602 * \retval ALT_E_ERROR The operation failed. 0603 * \retval ALT_E_BAD_ARG The given event identifier is invalid. 0604 */ 0605 ALT_STATUS_CODE alt_dma_int_status_get(ALT_DMA_EVENT_t irq_num); 0606 0607 /*! 0608 * Clear the active (HIGH) status of the specified interrupt resource. 0609 * 0610 * If the specified interrupt is HIGH, then sets \b irq[N] to LOW if the 0611 * event-interrupt resource is configured (see: alt_dma_event_int_enable()) 0612 * to signal an interrupt. Otherwise, the status of \b irq[N] does not change. 0613 * 0614 * \param irq_num 0615 * The interrupt resource number. Valid values are 0616 * ALT_DMA_EVENT_0 .. ALT_DMA_EVENT_7 and ALT_DMA_EVENT_ABORT. 0617 * 0618 * \retval ALT_E_SUCCESS The operation was successful. 0619 * \retval ALT_E_ERROR The operation failed. 0620 * \retval ALT_E_BAD_ARG The given event identifier is invalid. 0621 */ 0622 ALT_STATUS_CODE alt_dma_int_clear(ALT_DMA_EVENT_t irq_num); 0623 0624 /*! 0625 * @} 0626 */ 0627 0628 /*! 0629 * \addtogroup ALT_DMA_STD_OPS DMA API for Standard Operations 0630 * 0631 * The functions in this group provide common DMA operations for common bulk 0632 * data transfers between: 0633 * * Memory to Memory 0634 * * Zero to Memory 0635 * * Memory to Peripheral 0636 * * Peripheral to Memory 0637 * 0638 * All DMA operations are asynchronous. The following are the ways to receive 0639 * notification of a DMA transfer complete operation: 0640 * * Use alt_dma_channel_state_get() and poll for the 0641 * ALT_DMA_CHANNEL_STATE_STOPPED status. 0642 * * In conjunction with the interrupt API, use DMA events to signal an 0643 * interrupt. The event first must be configured to signal an interrupt 0644 * using alt_dma_event_int_select(). Configure the DMA program to send an 0645 * event. 0646 * * Construct a custom program which waits for a particular event number by 0647 * assemblying a DMAWFE using alt_dma_program_DMAWFE(). Then run the custom 0648 * program on a different channel. The custom program will wait until the 0649 * DMA program sends the event. Configure the DMA program to send an event. 0650 * 0651 * Cache related maintenance on the source and/or destinatino buffer are not 0652 * handled the DMA API and are the responsibility of the programmer. This is 0653 * because the DMA API does not have visibility into the current configuration 0654 * of the MMU or know about any special considerations regarding the source 0655 * and/or destination memory. The following are some example scenarios and 0656 * cache maintenance related precautions that may need to be taken: 0657 * * alt_dma_memory_to_memory(): Source buffer should be cleaned or purged, 0658 * destination buffer should be invalidated. 0659 * * alt_dma_zero_to_memory(): Destination buffer should be invalidated. 0660 * * alt_dma_memory_to_register(): Source buffer should be cleaned or purged. 0661 * * alt_dma_register_to_memory(): Destination buffer should be invalidated. 0662 * * alt_dma_memory_to_periph(): Source buffer should be cleaned or purged. 0663 * * alt_dma_periph_to_memory(): Destination buffer should be invalidated. 0664 * 0665 * @{ 0666 */ 0667 0668 /*! 0669 * Uses the DMA engine to asynchronously copy the specified memory from the 0670 * given source address to the given destination address. 0671 * 0672 * Overlapping memory regions are not supported. 0673 * 0674 * \param channel 0675 * The DMA channel thread to use for the transfer. 0676 * 0677 * \param program 0678 * An allocated DMA program buffer to use for the life of the 0679 * transfer. 0680 * 0681 * \param dest 0682 * The destination memory address to copy to. 0683 * 0684 * \param src 0685 * The source memory address to copy from. 0686 * 0687 * \param size 0688 * The size of the transfer in bytes. 0689 * 0690 * \param send_evt 0691 * If set to true, the DMA engine will be instructed to send an 0692 * event upon completion or fault. 0693 * 0694 * \param evt 0695 * If send_evt is true, the event specified will be sent. 0696 * Otherwise the parameter is ignored. 0697 * 0698 * \retval ALT_E_SUCCESS The operation was successful. 0699 * \retval ALT_E_ERROR The operation failed. 0700 * \retval ALT_E_BAD_ARG The given channel or event identifier (if 0701 * used) is invalid, or the memory regions 0702 * specified are overlapping. 0703 */ 0704 ALT_STATUS_CODE alt_dma_memory_to_memory(ALT_DMA_CHANNEL_t channel, 0705 ALT_DMA_PROGRAM_t * program, 0706 void * dest, 0707 const void * src, 0708 size_t size, 0709 bool send_evt, 0710 ALT_DMA_EVENT_t evt); 0711 0712 /*! 0713 * Uses the DMA engine to asynchronously zero out the specified memory buffer. 0714 * 0715 * \param channel 0716 * The DMA channel thread to use for the transfer. 0717 * 0718 * \param program 0719 * An allocated DMA program buffer to use for the life of the 0720 * transfer. 0721 * 0722 * \param buf 0723 * The buffer memory address to zero out. 0724 * 0725 * \param size 0726 * The size of the buffer in bytes. 0727 * 0728 * \param send_evt 0729 * If set to true, the DMA engine will be instructed to send an 0730 * event upon completion or fault. 0731 * 0732 * \param evt 0733 * If send_evt is true, the event specified will be sent. 0734 * Otherwise the parameter is ignored. 0735 * 0736 * \retval ALT_E_SUCCESS The operation was successful. 0737 * \retval ALT_E_ERROR The operation failed. 0738 * \retval ALT_E_BAD_ARG The given channel or event identifier (if 0739 * used) is invalid. 0740 */ 0741 ALT_STATUS_CODE alt_dma_zero_to_memory(ALT_DMA_CHANNEL_t channel, 0742 ALT_DMA_PROGRAM_t * program, 0743 void * buf, 0744 size_t size, 0745 bool send_evt, 0746 ALT_DMA_EVENT_t evt); 0747 0748 /*! 0749 * Uses the DMA engine to asynchronously transfer the contents of a memory 0750 * buffer to a keyhole register. 0751 * 0752 * \param channel 0753 * The DMA channel thread to use for the transfer. 0754 * 0755 * \param program 0756 * An allocated DMA program buffer to use for the life of the 0757 * transfer. 0758 * 0759 * \param dst_reg 0760 * The address of the register to write buffer to. 0761 * 0762 * \param src_buf 0763 * The address of the memory buffer for the data. 0764 * 0765 * \param count 0766 * The number of transfers to make. 0767 * 0768 * \param register_width_bits 0769 * The width of the register to transfer to in bits. Valid values 0770 * are 8, 16, 32, and 64. 0771 * 0772 * \param send_evt 0773 * If set to true, the DMA engine will be instructed to send an 0774 * event upon completion or fault. 0775 * 0776 * \param evt 0777 * If send_evt is true, the event specified will be sent. 0778 * Otherwise the parameter is ignored. 0779 * 0780 * \retval ALT_E_SUCCESS The operation was successful. 0781 * \retval ALT_E_ERROR The operation failed. 0782 * \retval ALT_E_BAD_ARG The given channel, event identifier (if used), 0783 * or register width are invalid, or if the 0784 * destination register or source buffer is 0785 * unaligned to the register width. 0786 */ 0787 ALT_STATUS_CODE alt_dma_memory_to_register(ALT_DMA_CHANNEL_t channel, 0788 ALT_DMA_PROGRAM_t * program, 0789 void * dst_reg, 0790 const void * src_buf, 0791 size_t count, 0792 uint32_t register_width_bits, 0793 bool send_evt, 0794 ALT_DMA_EVENT_t evt); 0795 0796 /*! 0797 * Uses the DMA engine to asynchronously transfer the contents of a keyhole 0798 * register to a memory buffer. 0799 * 0800 * \param channel 0801 * The DMA channel thread to use for the transfer. 0802 * 0803 * \param program 0804 * An allocated DMA program buffer to use for the life of the 0805 * transfer. 0806 * 0807 * \param dst_buf 0808 * The address of the memory buffer to copy to. 0809 * 0810 * \param src_reg 0811 * The address of the keyhole register to read from. 0812 * 0813 * \param count 0814 * The number of transfers to make. 0815 * 0816 * \param register_width_bits 0817 * The width of the register to transfer to in bits. Valid values 0818 * are 8, 16, 32, and 64. 0819 * 0820 * \param send_evt 0821 * If set to true, the DMA engine will be instructed to send an 0822 * event upon completion or fault. 0823 * 0824 * \param evt 0825 * If send_evt is true, the event specified will be sent. 0826 * Otherwise the parameter is ignored. 0827 * 0828 * \retval ALT_E_SUCCESS The operation was successful. 0829 * \retval ALT_E_ERROR The operation failed. 0830 * \retval ALT_E_BAD_ARG The given channel, event identifier (if used), 0831 * or register width are invalid, or if the 0832 * destination buffer or source register is 0833 * unaligned to the register width. 0834 */ 0835 ALT_STATUS_CODE alt_dma_register_to_memory(ALT_DMA_CHANNEL_t channel, 0836 ALT_DMA_PROGRAM_t * program, 0837 void * dst_buf, 0838 const void * src_reg, 0839 size_t count, 0840 uint32_t register_width_bits, 0841 bool send_evt, 0842 ALT_DMA_EVENT_t evt); 0843 0844 /*! 0845 * Uses the DMA engine to asynchronously copy memory from the given source 0846 * address to the specified peripheral. Because different peripheral has 0847 * different characteristics, individual peripherals need to be explicitly 0848 * supported. 0849 * 0850 * The following lists the peripheral IDs supported by this API: 0851 * * ALT_DMA_PERIPH_QSPI_FLASH_TX 0852 * * ALT_DMA_PERIPH_UART0_TX 0853 * * ALT_DMA_PERIPH_UART1_TX 0854 * 0855 * \param channel 0856 * The DMA channel thread to use for the transfer. 0857 * 0858 * \param program 0859 * An allocated DMA program buffer to use for the life of the 0860 * transfer. 0861 * 0862 * \param dest 0863 * The destination peripheral to copy memory to. 0864 * 0865 * \param src 0866 * The source memory address to copy from. 0867 * 0868 * \param size 0869 * The size of the transfer in bytes. 0870 * 0871 * \param periph_info 0872 * A pointer to a peripheral specific data structure. The 0873 * following list shows what data structure should be used for 0874 * peripherals: 0875 * * ALT_DMA_PERIPH_QSPI_FLASH_TX: This parameter is ignored. 0876 * * ALT_DMA_PERIPH_UART0_TX: Use a pointer to the 0877 * ALT_16550_HANDLE_t used to interact with that UART. 0878 * * ALT_DMA_PERIPH_UART1_TX: Use a pointer to the 0879 * ALT_16550_HANDLE_t used to interact with that UART. 0880 * 0881 * \param send_evt 0882 * If set to true, the DMA engine will be instructed to send an 0883 * event upon completion or fault. 0884 * 0885 * \param evt 0886 * If send_evt is true, the event specified will be sent. 0887 * Otherwise the parameter is ignored. 0888 * 0889 * \retval ALT_E_SUCCESS The operation was successful. 0890 * \retval ALT_E_ERROR The operation failed. 0891 * \retval ALT_E_BAD_ARG The given channel, peripheral, or event 0892 * identifier (if used) is invalid. 0893 * 0894 * \internal 0895 * Priority peripheral IDs to be supported: 0896 * * ALT_DMA_PERIPH_FPGA_0 0897 * * ALT_DMA_PERIPH_FPGA_1 0898 * * ALT_DMA_PERIPH_FPGA_2 0899 * * ALT_DMA_PERIPH_FPGA_3 0900 * * ALT_DMA_PERIPH_FPGA_4 0901 * * ALT_DMA_PERIPH_FPGA_5 0902 * * ALT_DMA_PERIPH_FPGA_6 0903 * * ALT_DMA_PERIPH_FPGA_7 0904 * * ALT_DMA_PERIPH_I2C0_TX 0905 * * ALT_DMA_PERIPH_I2C1_TX 0906 * * ALT_DMA_PERIPH_I2C2_TX 0907 * * ALT_DMA_PERIPH_I2C3_TX 0908 * * ALT_DMA_PERIPH_SPI0_MASTER_TX 0909 * * ALT_DMA_PERIPH_SPI0_SLAVE_TX 0910 * * ALT_DMA_PERIPH_SPI1_MASTER_TX 0911 * * ALT_DMA_PERIPH_SPI1_SLAVE_TX 0912 * \endinternal 0913 */ 0914 ALT_STATUS_CODE alt_dma_memory_to_periph(ALT_DMA_CHANNEL_t channel, 0915 ALT_DMA_PROGRAM_t * program, 0916 ALT_DMA_PERIPH_t dest, 0917 const void * src, 0918 size_t size, 0919 void * periph_info, 0920 bool send_evt, 0921 ALT_DMA_EVENT_t evt); 0922 0923 /*! 0924 * Uses the DMA engine to copy memory from the specified peripheral to the 0925 * given destination address. Because different peripheral has different 0926 * characteristics, individual peripherals need to be explicitly supported. 0927 * 0928 * The following lists the peripheral IDs supported by this API: 0929 * * ALT_DMA_PERIPH_QSPI_FLASH_RX 0930 * * ALT_DMA_PERIPH_UART0_RX 0931 * * ALT_DMA_PERIPH_UART1_RX 0932 * 0933 * \param channel 0934 * The DMA channel thread to use for the transfer. 0935 * 0936 * \param program 0937 * An allocated DMA program buffer to use for the life of the 0938 * transfer. 0939 * 0940 * \param dest 0941 * The destination memory address to copy to. 0942 * 0943 * \param src 0944 * The source peripheral to copy memory from. 0945 * 0946 * \param size 0947 * The size of the transfer in bytes. 0948 * 0949 * \param periph_info 0950 * A pointer to a peripheral specific data structure. The 0951 * following list shows what data structure should be used for 0952 * peripherals: 0953 * * ALT_DMA_PERIPH_QSPI_FLASH_RX: This parameter is ignored. 0954 * * ALT_DMA_PERIPH_UART0_RX: Use a pointer to the 0955 * ALT_16550_HANDLE_t used to interact with that UART. 0956 * * ALT_DMA_PERIPH_UART1_RX: Use a pointer to the 0957 * ALT_16550_HANDLE_t used to interact with that UART. 0958 * 0959 * \param send_evt 0960 * If set to true, the DMA engine will be instructed to send an 0961 * event upon completion or fault. 0962 * 0963 * \param evt 0964 * If send_evt is true, the event specified will be sent. 0965 * Otherwise the parameter is ignored. 0966 * 0967 * \retval ALT_E_SUCCESS The operation was successful. 0968 * \retval ALT_E_ERROR The operation failed. 0969 * \retval ALT_E_BAD_ARG The given channel, peripheral, or event 0970 * identifier (if used) is invalid. 0971 * 0972 * \internal 0973 * Priority peripheral IDs to be supported: 0974 * * ALT_DMA_PERIPH_FPGA_0 0975 * * ALT_DMA_PERIPH_FPGA_1 0976 * * ALT_DMA_PERIPH_FPGA_2 0977 * * ALT_DMA_PERIPH_FPGA_3 0978 * * ALT_DMA_PERIPH_FPGA_4 0979 * * ALT_DMA_PERIPH_FPGA_5 0980 * * ALT_DMA_PERIPH_FPGA_6 0981 * * ALT_DMA_PERIPH_FPGA_7 0982 * * ALT_DMA_PERIPH_I2C0_RX 0983 * * ALT_DMA_PERIPH_I2C1_RX 0984 * * ALT_DMA_PERIPH_I2C2_RX 0985 * * ALT_DMA_PERIPH_I2C3_RX 0986 * * ALT_DMA_PERIPH_SPI0_MASTER_RX 0987 * * ALT_DMA_PERIPH_SPI0_SLAVE_RX 0988 * * ALT_DMA_PERIPH_SPI1_MASTER_RX 0989 * * ALT_DMA_PERIPH_SPI1_SLAVE_RX 0990 * \endinternal 0991 */ 0992 ALT_STATUS_CODE alt_dma_periph_to_memory(ALT_DMA_CHANNEL_t channel, 0993 ALT_DMA_PROGRAM_t * program, 0994 void * dest, 0995 ALT_DMA_PERIPH_t src, 0996 size_t size, 0997 void * periph_info, 0998 bool send_evt, 0999 ALT_DMA_EVENT_t evt); 1000 1001 /*! 1002 * @} 1003 */ 1004 1005 /*! 1006 * @} 1007 */ 1008 1009 #ifdef __cplusplus 1010 } 1011 #endif /* __cplusplus */ 1012 1013 #endif /* __ALT_DMA_H__ */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|