1 /* 2 * Copyright (c) 2016-2019, Texas Instruments Incorporated 3 * 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 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /** ============================================================================ 33 * @file UDMACC32XX.h 34 * 35 * @brief uDMA driver implementation for CC32XX. 36 * 37 * This driver is intended for use only by drivers that use the uDMA 38 * peripheral (e.g., SPI and I2S). This driver is mainly used for Power 39 * management of the UDMA peripheral. 40 * 41 * The application should only define the memory for the control table and 42 * set up the UDMACC32XX_HWAttrs and UDMACC32XX_Config structures. 43 * 44 * The UDMACC32XX header file should be included in an application as follows: 45 * @code 46 * #include <ti/drivers/dma/UDMACC32XX.h> 47 * @endcode 48 * 49 * ============================================================================ 50 */ 51 52 #ifndef ti_drivers_dma_UDMACC32XX__include 53 #define ti_drivers_dma_UDMACC32XX__include 54 55 #include <stdint.h> 56 #include <stdbool.h> 57 #include <ti/drivers/dpl/HwiP.h> 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /*! 64 * @brief UDMA error function pointer 65 */ 66 typedef void (*UDMACC32XX_ErrorFxn)(uintptr_t arg); 67 68 /*! 69 * @brief UDMACC32XX Hardware attributes 70 * 71 * This structure contains the base address of the uDMA control 72 * table, and uDMA error interrupt attributes. 73 * 74 * The control table is used by the uDMA controller to store channel 75 * control structures. The control table can be located anywhere in 76 * system memory, but must be contiguous and aligned on a 1024-byte boundary. 77 * 78 * dmaErrorFxn is the uDMA peripheral's error interrupt handler. 79 * 80 * intPriority is priority of the uDMA peripheral's error interrupt, as 81 * defined by the underlying OS. It is passed unmodified to the 82 * underlying OS's interrupt handler creation code, so you need to 83 * refer to the OS documentation for usage. If the 84 * driver uses the ti.dpl interface instead of making OS 85 * calls directly, then the HwiP port handles the interrupt priority 86 * in an OS specific way. In the case of the SYS/BIOS port, 87 * intPriority is passed unmodified to Hwi_create(). 88 * 89 * A sample structure is shown below: 90 * @code 91 * 92 * #include <ti/devices/cc32xx/driverlib/udma.h> 93 * 94 * static tDMAControlTable dmaControlTable[64] __attribute__ ((aligned (1024))); 95 * 96 * #include <ti/drivers/dma/UDMACC32XX.h> 97 * 98 * UDMACC32XX_Object udmaCC32XXObject; 99 * 100 * const UDMACC32XX_HWAttrs udmaCC32XXHWAttrs = { 101 * .controlBaseAddr = (void *)dmaControlTable, 102 * .dmaErrorFxn = UDMACC32XX_errorFxn, 103 * .intNum = INT_UDMAERR, 104 * .intPriority = (~0) 105 * }; 106 * @endcode 107 * 108 */ 109 typedef struct { 110 void *controlBaseAddr; /*!< uDMA control registers base address */ 111 UDMACC32XX_ErrorFxn dmaErrorFxn; /*!< uDMA error interrupt handler */ 112 uint8_t intNum; /*!< uDMA error interrupt number */ 113 uint8_t intPriority; /*!< uDMA error interrupt priority. */ 114 } UDMACC32XX_HWAttrs; 115 116 /*! 117 * @brief UDMACC32XX Global configuration 118 * 119 * The UDMACC32XX_Config structure contains pointers used by the UDMACC32XX 120 * driver. 121 * 122 * This structure needs to be defined before calling UDMACC32XX_init() and 123 * it must not be changed thereafter. 124 */ 125 typedef struct { 126 void *object; /*!< Pointer to UDMACC32XX object */ 127 void const *hwAttrs; /*!< Pointer to hardware attributes */ 128 } UDMACC32XX_Config; 129 130 /*! 131 * @brief A handle that is returned from a UDMACC32XX_open() call. 132 */ 133 typedef UDMACC32XX_Config *UDMACC32XX_Handle; 134 135 /*! 136 * @brief UDMACC32XX object 137 * 138 * The application must not access any member variables of this structure! 139 */ 140 typedef struct { 141 bool isOpen; /* Flag for open/close status */ 142 HwiP_Handle hwiHandle; /* DMA error Hwi */ 143 } UDMACC32XX_Object; 144 145 /*! 146 * @brief Function to close the DMA driver. 147 * 148 * This function releases Power dependency on UDMA that was previously 149 * set with a call to UDMACC32XX_open(). If there is only one outstanding 150 * UDMACC32XX_open() call (i.e. all but one UDMACC32XX_open() calls have 151 * been matched by a corresponding call to UDMACC32XX_close()), this 152 * function will disable the UDMA. 153 * 154 * @pre UDMACC32XX_open() has to be called first. 155 * Calling context: Task 156 * 157 * @param handle A UDMACC32XX_Handle returned from UDMACC32XX_open() 158 * 159 * @return none 160 * 161 * @sa UDMACC32XX_open 162 */ 163 extern void UDMACC32XX_close(UDMACC32XX_Handle handle); 164 165 /*! 166 * @brief Function to initialize the CC32XX DMA driver 167 * 168 * The function will set the isOpen flag to false, and should be called prior 169 * to opening the DMA driver. 170 * 171 * @return none 172 * 173 * @sa UDMACC32XX_open() 174 */ 175 extern void UDMACC32XX_init(); 176 177 /*! 178 * @brief Function to initialize the CC32XX DMA peripheral 179 * 180 * UDMACC32XX_open() can be called multiple times. Each time the 181 * function is called, it will set a dependency on the peripheral and 182 * enable the clock. The Power dependency count on the UDMA will be 183 * equal to the number of outstanding calls to UDMACC32XX_open(). 184 * Calling UDMACC32XX_close() will decrement the Power dependency count, 185 * and the last call to UDMACC32XX_close() will disable the UDMA. 186 * 187 * @pre UDMACC32XX_init() has to be called first. 188 * Calling context: Task 189 * 190 * @return UDMACC32XX_Handle on success or NULL if an error has occurred. 191 * 192 * @sa UDMACC32XX_close() 193 */ 194 extern UDMACC32XX_Handle UDMACC32XX_open(); 195 196 #ifdef __cplusplus 197 } 198 #endif 199 200 #endif /* ti_drivers_dma_UDMACC32XX__include */ 201
