1 /* --COPYRIGHT--,BSD 2 * Copyright (c) 2017, 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 * --/COPYRIGHT--*/ 32 #ifndef __DMA_H__ 33 #define __DMA_H__ 34 35 //***************************************************************************** 36 // 37 //! \addtogroup dma_api 38 //! @{ 39 // 40 //***************************************************************************** 41 42 //***************************************************************************** 43 // 44 // If building with a C++ compiler, make all of the definitions in this header 45 // have a C binding. 46 // 47 //***************************************************************************** 48 #ifdef __cplusplus 49 extern "C" 50 { 51 #endif 52 53 #include <stdbool.h> 54 #include <ti/devices/msp432p4xx/inc/msp.h> 55 #include <ti/devices/msp432p4xx/driverlib/interrupt.h> 56 57 //***************************************************************************** 58 // 59 // A structure that defines an entry in the channel control table. These 60 // fields are used by the DMA controller and normally it is not necessary for 61 // software to directly read or write fields in the table. 62 // 63 //***************************************************************************** 64 typedef struct _DMA_ControlTable 65 { 66 // 67 // The ending source address of the data transfer. 68 // 69 volatile void *srcEndAddr; 70 71 // 72 // The ending destination address of the data transfer. 73 // 74 volatile void *dstEndAddr; 75 76 // 77 // The channel control mode. 78 // 79 volatile uint32_t control; 80 81 // 82 // An unused location. 83 // 84 volatile uint32_t spare; 85 } DMA_ControlTable; 86 87 //***************************************************************************** 88 // 89 //! A helper macro for building scatter-gather task table entries. 90 //! 91 //! This macro is intended to be used to help populate a table of DMA tasks 92 //! for a scatter-gather transfer. This macro will calculate the values for 93 //! the fields of a task structure entry based on the input parameters. 94 //! 95 //! There are specific requirements for the values of each parameter. No 96 //! checking is done so it is up to the caller to ensure that correct values 97 //! are used for the parameters. 98 //! 99 //! The \b transferCount parameter is the number of items that will be 100 //! transferred by this task. It must be in the range 1-1024. 101 //! 102 //! The \b itemSize parameter is the bit size of the transfer data. It must 103 //! be one of \b UDMA_SIZE_8, \b UDMA_SIZE_16, or \b UDMA_SIZE_32. 104 //! 105 //! The \e srcIncrement parameter is the increment size for the source data. 106 //! It must be one of \b UDMA_SRC_INC_8, \b UDMA_SRC_INC_16, 107 //! \b UDMA_SRC_INC_32, or \b UDMA_SRC_INC_NONE. 108 //! 109 //! The \b srcAddr parameter is a void pointer to the beginning of the source 110 //! data. 111 //! 112 //! The \b dstIncrement parameter is the increment size for the destination 113 //! data. It must be one of \b UDMA_DST_INC_8, \b UDMA_DST_INC_16, 114 //! \b UDMA_DST_INC_32, or \b UDMA_DST_INC_NONE. 115 //! 116 //! The \b dstAddr parameter is a void pointer to the beginning of the 117 //! location where the data will be transferred. 118 //! 119 //! The \b arbSize parameter is the arbitration size for the transfer, and 120 //! must be one of \b UDMA_ARB_1, \b UDMA_ARB_2, \b UDMA_ARB_4, and so on 121 //! up to \b UDMA_ARB_1024. This is used to select the arbitration size in 122 //! powers of 2, from 1 to 1024. 123 //! 124 //! The \e mode parameter is the mode to use for this transfer task. It 125 //! must be one of \b UDMA_MODE_BASIC, \b UDMA_MODE_AUTO, 126 //! \b UDMA_MODE_MEM_SCATTER_GATHER, or \b UDMA_MODE_PER_SCATTER_GATHER. Note 127 //! that normally all tasks will be one of the scatter-gather modes while the 128 //! last task is a task list will be AUTO or BASIC. 129 //! 130 //! This macro is intended to be used to initialize individual entries of 131 //! a structure of DMA_ControlTable type, like this: 132 //! 133 //! \code{.c} 134 //! DMA_ControlTable MyTaskList[] = 135 //! { 136 //! DMA_TaskStructEntry(Task1Count, UDMA_SIZE_8, 137 //! UDMA_SRC_INC_8, MySourceBuf, 138 //! UDMA_DST_INC_8, MyDestBuf, 139 //! UDMA_ARB_8, UDMA_MODE_MEM_SCATTER_GATHER), 140 //! DMA_TaskStructEntry(Task2Count, ... ), 141 //! } 142 //! \endcode 143 //! 144 //! \param transferCount is the count of items to transfer for this task. 145 //! \param itemSize is the bit size of the items to transfer for this task. 146 //! \param srcIncrement is the bit size increment for source data. 147 //! \param srcAddr is the starting address of the data to transfer. 148 //! \param dstIncrement is the bit size increment for destination data. 149 //! \param dstAddr is the starting address of the destination data. 150 //! \param arbSize is the arbitration size to use for the transfer task. 151 //! \param mode is the transfer mode for this task. 152 //! 153 //! \return Nothing; this is not a function. 154 // 155 //***************************************************************************** 156 #define DMA_TaskStructEntry(transferCount, \ 157 itemSize, \ 158 srcIncrement, \ 159 srcAddr, \ 160 dstIncrement, \ 161 dstAddr, \ 162 arbSize, \ 163 mode) \ 164 { \ 165 (((srcIncrement) == UDMA_SRC_INC_NONE) ? (void *)(srcAddr) : \ 166 ((void *)(&((uint8_t *)(srcAddr))[((transferCount) << \ 167 ((srcIncrement) >> 26)) - 1]))), \ 168 (((dstIncrement) == UDMA_DST_INC_NONE) ? (void *)(dstAddr) : \ 169 ((void *)(&((uint8_t *)(dstAddr))[((transferCount) << \ 170 ((dstIncrement) >> 30)) - 1]))), \ 171 (srcIncrement) | (dstIncrement) | (itemSize) | (arbSize) | \ 172 (((transferCount) - 1) << 4) | \ 173 ((((mode) == UDMA_MODE_MEM_SCATTER_GATHER) || \ 174 ((mode) == UDMA_MODE_PER_SCATTER_GATHER)) ? \ 175 (mode) | UDMA_MODE_ALT_SELECT : (mode)), 0 \ 176 } 177 178 //***************************************************************************** 179 // 180 // Flags that can be passed to DMA_enableChannelAttribute(), 181 // DMA_disableChannelAttribute(), and returned from DMA_getChannelAttribute(). 182 // 183 //***************************************************************************** 184 #define UDMA_ATTR_USEBURST 0x00000001 185 #define UDMA_ATTR_ALTSELECT 0x00000002 186 #define UDMA_ATTR_HIGH_PRIORITY 0x00000004 187 #define UDMA_ATTR_REQMASK 0x00000008 188 #define UDMA_ATTR_ALL 0x0000000F 189 190 //***************************************************************************** 191 // 192 // DMA control modes that can be passed to DMAModeSet() and returned 193 // DMAModeGet(). 194 // 195 //***************************************************************************** 196 #define UDMA_MODE_STOP 0x00000000 197 #define UDMA_MODE_BASIC 0x00000001 198 #define UDMA_MODE_AUTO 0x00000002 199 #define UDMA_MODE_PINGPONG 0x00000003 200 #define UDMA_MODE_MEM_SCATTER_GATHER \ 201 0x00000004 202 #define UDMA_MODE_PER_SCATTER_GATHER \ 203 0x00000006 204 #define UDMA_MODE_ALT_SELECT 0x00000001 205 206 //***************************************************************************** 207 // 208 // Channel configuration values that can be passed to DMAControlSet(). 209 // 210 //***************************************************************************** 211 #define UDMA_DST_INC_8 0x00000000 212 #define UDMA_DST_INC_16 0x40000000 213 #define UDMA_DST_INC_32 0x80000000 214 #define UDMA_DST_INC_NONE 0xc0000000 215 #define UDMA_SRC_INC_8 0x00000000 216 #define UDMA_SRC_INC_16 0x04000000 217 #define UDMA_SRC_INC_32 0x08000000 218 #define UDMA_SRC_INC_NONE 0x0c000000 219 #define UDMA_SIZE_8 0x00000000 220 #define UDMA_SIZE_16 0x11000000 221 #define UDMA_SIZE_32 0x22000000 222 #define UDMA_DST_PROT_PRIV 0x00200000 223 #define UDMA_SRC_PROT_PRIV 0x00040000 224 #define UDMA_ARB_1 0x00000000 225 #define UDMA_ARB_2 0x00004000 226 #define UDMA_ARB_4 0x00008000 227 #define UDMA_ARB_8 0x0000c000 228 #define UDMA_ARB_16 0x00010000 229 #define UDMA_ARB_32 0x00014000 230 #define UDMA_ARB_64 0x00018000 231 #define UDMA_ARB_128 0x0001c000 232 #define UDMA_ARB_256 0x00020000 233 #define UDMA_ARB_512 0x00024000 234 #define UDMA_ARB_1024 0x00028000 235 #define UDMA_NEXT_USEBURST 0x00000008 236 237 //***************************************************************************** 238 // 239 // Flags to be OR'd with the channel ID to indicate if the primary or alternate 240 // control structure should be used. 241 // 242 //***************************************************************************** 243 #define UDMA_PRI_SELECT 0x00000000 244 #define UDMA_ALT_SELECT 0x00000008 245 246 //***************************************************************************** 247 // 248 // Values that can be passed to DMA_assignChannel() to select peripheral 249 // mapping for each channel. The channels named RESERVED may be assigned 250 // to a peripheral in future parts. 251 // 252 //***************************************************************************** 253 // 254 // Channel 0 255 // 256 #define DMA_CH0_RESERVED0 0x00000000 257 #define DMA_CH0_EUSCIA0TX 0x01000000 258 #define DMA_CH0_EUSCIB0TX0 0x02000000 259 #define DMA_CH0_EUSCIB3TX1 0x03000000 260 #define DMA_CH0_EUSCIB2TX2 0x04000000 261 #define DMA_CH0_EUSCIB1TX3 0x05000000 262 #define DMA_CH0_TIMERA0CCR0 0x06000000 263 #define DMA_CH0_AESTRIGGER0 0x07000000 264 265 // 266 // Channel 1 267 // 268 #define DMA_CH1_RESERVED0 0x00000001 269 #define DMA_CH1_EUSCIA0RX 0x01000001 270 #define DMA_CH1_EUSCIB0RX0 0x02000001 271 #define DMA_CH1_EUSCIB3RX1 0x03000001 272 #define DMA_CH1_EUSCIB2RX2 0x04000001 273 #define DMA_CH1_EUSCIB1RX3 0x05000001 274 #define DMA_CH1_TIMERA0CCR2 0x06000001 275 #define DMA_CH1_AESTRIGGER1 0x07000001 276 277 // 278 // Channel 2 279 // 280 #define DMA_CH2_RESERVED0 0x00000002 281 #define DMA_CH2_EUSCIA1TX 0x01000002 282 #define DMA_CH2_EUSCIB1TX0 0x02000002 283 #define DMA_CH2_EUSCIB0TX1 0x03000002 284 #define DMA_CH2_EUSCIB3TX2 0x04000002 285 #define DMA_CH2_EUSCIB2TX3 0x05000002 286 #define DMA_CH2_TIMERA1CCR0 0x06000002 287 #define DMA_CH2_AESTRIGGER2 0x07000002 288 289 // 290 // Channel 3 291 // 292 #define DMA_CH3_RESERVED0 0x00000003 293 #define DMA_CH3_EUSCIA1RX 0x01000003 294 #define DMA_CH3_EUSCIB1RX0 0x02000003 295 #define DMA_CH3_EUSCIB0RX1 0x03000003 296 #define DMA_CH3_EUSCIB3RX2 0x04000003 297 #define DMA_CH3_EUSCIB2RX3 0x05000003 298 #define DMA_CH3_TIMERA1CCR2 0x06000003 299 #define DMA_CH3_RESERVED1 0x07000003 300 301 // 302 // Channel 4 303 // 304 #define DMA_CH4_RESERVED0 0x00000004 305 #define DMA_CH4_EUSCIA2TX 0x01000004 306 #define DMA_CH4_EUSCIB2TX0 0x02000004 307 #define DMA_CH4_EUSCIB1TX1 0x03000004 308 #define DMA_CH4_EUSCIB0TX2 0x04000004 309 #define DMA_CH4_EUSCIB3TX3 0x05000004 310 #define DMA_CH4_TIMERA2CCR0 0x06000004 311 #define DMA_CH4_RESERVED1 0x07000004 312 313 // 314 // Channel 5 315 // 316 #define DMA_CH5_RESERVED0 0x00000005 317 #define DMA_CH5_EUSCIA2RX 0x01000005 318 #define DMA_CH5_EUSCIB2RX0 0x02000005 319 #define DMA_CH5_EUSCIB1RX1 0x03000005 320 #define DMA_CH5_EUSCIB0RX2 0x04000005 321 #define DMA_CH5_EUSCIB3RX3 0x05000005 322 #define DMA_CH5_TIMERA2CCR2 0x06000005 323 #define DMA_CH5_RESERVED1 0x07000005 324 325 // 326 // Channel 6 327 // 328 #define DMA_CH6_RESERVED0 0x00000006 329 #define DMA_CH6_EUSCIA3TX 0x01000006 330 #define DMA_CH6_EUSCIB3TX0 0x02000006 331 #define DMA_CH6_EUSCIB2TX1 0x03000006 332 #define DMA_CH6_EUSCIB1TX2 0x04000006 333 #define DMA_CH6_EUSCIB0TX3 0x05000006 334 #define DMA_CH6_TIMERA3CCR0 0x06000006 335 #define DMA_CH6_EXTERNALPIN 0x07000006 336 337 // 338 // Channel 7 339 // 340 #define DMA_CH7_RESERVED0 0x00000007 341 #define DMA_CH7_EUSCIA3RX 0x01000007 342 #define DMA_CH7_EUSCIB3RX0 0x02000007 343 #define DMA_CH7_EUSCIB2RX1 0x03000007 344 #define DMA_CH7_EUSCIB1RX2 0x04000007 345 #define DMA_CH7_EUSCIB0RX3 0x05000007 346 #define DMA_CH7_TIMERA3CCR2 0x06000007 347 #define DMA_CH7_ADC14 0x07000007 348 349 // 350 // Different interrupt handlers to pass into DMA_registerInterrupt and 351 // DMA_unregisterInterrupt and other Int functions 352 // 353 #define DMA_INT0 INT_DMA_INT0 354 #define DMA_INT1 INT_DMA_INT1 355 #define DMA_INT2 INT_DMA_INT2 356 #define DMA_INT3 INT_DMA_INT3 357 #define DMA_INTERR INT_DMA_ERR 358 359 #define DMA_CHANNEL_0 0 360 #define DMA_CHANNEL_1 1 361 #define DMA_CHANNEL_2 2 362 #define DMA_CHANNEL_3 3 363 #define DMA_CHANNEL_4 4 364 #define DMA_CHANNEL_5 5 365 #define DMA_CHANNEL_6 6 366 #define DMA_CHANNEL_7 7 367 368 //***************************************************************************** 369 // 370 // API Function prototypes 371 // 372 //***************************************************************************** 373 374 //***************************************************************************** 375 // 376 //! Enables the DMA controller for use. 377 //! 378 //! This function enables the DMA controller. The DMA controller must be 379 //! enabled before it can be configured and used. 380 //! 381 //! \return None. 382 // 383 //***************************************************************************** 384 extern void DMA_enableModule(void); 385 386 //***************************************************************************** 387 // 388 //! Disables the DMA controller for use. 389 //! 390 //! This function disables the DMA controller. Once disabled, the DMA 391 //! controller cannot operate until re-enabled with DMA_enableModule(). 392 //! 393 //! \return None. 394 // 395 //***************************************************************************** 396 extern void DMA_disableModule(void); 397 398 //***************************************************************************** 399 // 400 //! Gets the DMA error status. 401 //! 402 //! This function returns the DMA error status. It should be called from 403 //! within the DMA error interrupt handler to determine if a DMA error 404 //! occurred. 405 //! 406 //! \return Returns non-zero if a DMA error is pending. 407 // 408 //***************************************************************************** 409 extern uint32_t DMA_getErrorStatus(void); 410 411 //***************************************************************************** 412 // 413 //! Clears the DMA error interrupt. 414 //! 415 //! This function clears a pending DMA error interrupt. This function should 416 //! be called from within the DMA error interrupt handler to clear the 417 //! interrupt. 418 //! 419 //! \return None. 420 // 421 //***************************************************************************** 422 extern void DMA_clearErrorStatus(void); 423 424 //***************************************************************************** 425 // 426 //! Enables a DMA channel for operation. 427 //! 428 //! \param channelNum is the channel number to enable. 429 //! 430 //! When a DMA transfer is completed, the channel is automatically disabled by 431 //! the DMA controller. Therefore, this function should be called prior to 432 //! starting up any new transfer. 433 //! 434 //! \return None. 435 // 436 //***************************************************************************** 437 extern void DMA_enableChannel(uint32_t channelNum); 438 439 //***************************************************************************** 440 // 441 //! Disables a DMA channel for operation. 442 //! 443 //! \param channelNum is the channel number to disable. 444 //! 445 //! This function disables a specific DMA channel. Once disabled, a channel 446 //! cannot respond to DMA transfer requests until re-enabled via 447 //! DMA_enableChannel(). 448 //! 449 //! \return None. 450 // 451 //***************************************************************************** 452 extern void DMA_disableChannel(uint32_t channelNum); 453 454 //***************************************************************************** 455 // 456 //! Checks if a DMA channel is enabled for operation. 457 //! 458 //! \param channelNum is the channel number to check. 459 //! 460 //! This function checks to see if a specific DMA channel is enabled. This 461 //! function can be used to check the status of a transfer, as the channel is 462 //! automatically disabled at the end of a transfer. 463 //! 464 //! \return Returns \b true if the channel is enabled, \b false if disabled. 465 // 466 //***************************************************************************** 467 extern bool DMA_isChannelEnabled(uint32_t channelNum); 468 469 //***************************************************************************** 470 // 471 //! Sets the base address for the channel control table. 472 //! 473 //! \param controlTable is a pointer to the 1024-byte-aligned base address 474 //! of the DMA channel control table. 475 //! 476 //! This function configures the base address of the channel control table. 477 //! This table resides in system memory and holds control information for each 478 //! DMA channel. The table must be aligned on a 1024-byte boundary. The base 479 //! address must be configured before any of the channel functions can be used. 480 //! 481 //! The size of the channel control table depends on the number of DMA 482 //! channels and the transfer modes that are used. Refer to the introductory 483 //! text and the microcontroller datasheet for more information about the 484 //! channel control table. 485 //! 486 //! \return None. 487 // 488 //***************************************************************************** 489 extern void DMA_setControlBase(void *controlTable); 490 491 //***************************************************************************** 492 // 493 //! Gets the base address for the channel control table. 494 //! 495 //! This function gets the base address of the channel control table. This 496 //! table resides in system memory and holds control information for each DMA 497 //! channel. 498 //! 499 //! \return Returns a pointer to the base address of the channel control table. 500 // 501 //***************************************************************************** 502 extern void* DMA_getControlBase(void); 503 504 //***************************************************************************** 505 // 506 //! Gets the base address for the channel control table alternate structures. 507 //! 508 //! This function gets the base address of the second half of the channel 509 //! control table that holds the alternate control structures for each channel. 510 //! 511 //! \return Returns a pointer to the base address of the second half of the 512 //! channel control table. 513 // 514 //***************************************************************************** 515 extern void* DMA_getControlAlternateBase(void); 516 517 //***************************************************************************** 518 // 519 //! Requests a DMA channel to start a transfer. 520 //! 521 //! \param channelNum is the channel number on which to request a DMA 522 //! transfer. 523 //! 524 //! This function allows software to request a DMA channel to begin a 525 //! transfer. This function could be used for performing a memory-to-memory 526 //! transfer, or if for some reason a transfer needs to be initiated by 527 //! software instead of the peripheral associated with that channel. 528 //! 529 //! \return None. 530 // 531 //***************************************************************************** 532 extern void DMA_requestChannel(uint32_t channelNum); 533 534 //***************************************************************************** 535 // 536 //! Enables attributes of a DMA channel. 537 //! 538 //! \param channelNum is the channel to configure. 539 //! \param attr is a combination of attributes for the channel. 540 //! 541 //! This function is used to enable attributes of a DMA channel. 542 //! 543 //! The \e attr parameter is the logical OR of any of the following: 544 //! 545 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst 546 //! mode. 547 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure 548 //! for this channel (it is very unlikely that this flag should be used). 549 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority. 550 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the 551 //! peripheral for this channel. 552 //! 553 //! \return None. 554 // 555 //***************************************************************************** 556 extern void DMA_enableChannelAttribute(uint32_t channelNum, uint32_t attr); 557 558 //***************************************************************************** 559 // 560 //! Disables attributes of a DMA channel. 561 //! 562 //! \param channelNum is the channel to configure. 563 //! \param attr is a combination of attributes for the channel. 564 //! 565 //! This function is used to disable attributes of a DMA channel. 566 //! 567 //! The \e attr parameter is the logical OR of any of the following: 568 //! 569 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst 570 //! mode. 571 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure 572 //! for this channel. 573 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority. 574 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the 575 //! peripheral for this channel. 576 //! 577 //! \return None. 578 // 579 //***************************************************************************** 580 extern void DMA_disableChannelAttribute(uint32_t channelNum, uint32_t attr); 581 582 //***************************************************************************** 583 // 584 //! Gets the enabled attributes of a DMA channel. 585 //! 586 //! \param channelNum is the channel to configure. 587 //! 588 //! This function returns a combination of flags representing the attributes of 589 //! the DMA channel. 590 //! 591 //! \return Returns the logical OR of the attributes of the DMA channel, which 592 //! can be any of the following: 593 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst 594 //! mode. 595 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure 596 //! for this channel. 597 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority. 598 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the 599 //! peripheral for this channel. 600 // 601 //***************************************************************************** 602 extern uint32_t DMA_getChannelAttribute(uint32_t channelNum); 603 604 //***************************************************************************** 605 // 606 //! Sets the control parameters for a DMA channel control structure. 607 //! 608 //! \param channelStructIndex is the logical OR of the DMA channel number 609 //! with \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT. 610 //! \param control is logical OR of several control values to set the control 611 //! parameters for the channel. 612 //! 613 //! This function is used to set control parameters for a DMA transfer. These 614 //! parameters are typically not changed often. 615 //! 616 //! The \e channelStructIndex parameter should be the logical OR of the 617 //! channel number with one of \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT to 618 //! choose whether the primary or alternate data structure is used. 619 //! 620 //! The \e control parameter is the logical OR of five values: the data size, 621 //! the source address increment, the destination address increment, the 622 //! arbitration size, and the use burst flag. The choices available for each 623 //! of these values is described below. 624 //! 625 //! Choose the data size from one of \b UDMA_SIZE_8, \b UDMA_SIZE_16, or 626 //! \b UDMA_SIZE_32 to select a data size of 8, 16, or 32 bits. 627 //! 628 //! Choose the source address increment from one of \b UDMA_SRC_INC_8, 629 //! \b UDMA_SRC_INC_16, \b UDMA_SRC_INC_32, or \b UDMA_SRC_INC_NONE to select 630 //! an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or 631 //! to select non-incrementing. 632 //! 633 //! Choose the destination address increment from one of \b UDMA_DST_INC_8, 634 //! \b UDMA_DST_INC_16, \b UDMA_DST_INC_32, or \b UDMA_SRC_INC_8 to select 635 //! an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or 636 //! to select non-incrementing. 637 //! 638 //! The arbitration size determines how many items are transferred before 639 //! the DMA controller re-arbitrates for the bus. Choose the arbitration size 640 //! from one of \b UDMA_ARB_1, \b UDMA_ARB_2, \b UDMA_ARB_4, \b UDMA_ARB_8, 641 //! through \b UDMA_ARB_1024 to select the arbitration size from 1 to 1024 642 //! items, in powers of 2. 643 //! 644 //! The value \b UDMA_NEXT_USEBURST is used to force the channel to only 645 //! respond to burst requests at the tail end of a scatter-gather transfer. 646 //! 647 //! \note The address increment cannot be smaller than the data size. 648 //! 649 //! \return None. 650 // 651 //***************************************************************************** 652 extern void DMA_setChannelControl(uint32_t channelStructIndex, 653 uint32_t control); 654 655 //***************************************************************************** 656 // 657 //! Sets the transfer parameters for a DMA channel control structure. 658 //! 659 //! \param channelStructIndex is the logical OR of the DMA channel number 660 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT. 661 //! \param mode is the type of DMA transfer. 662 //! \param srcAddr is the source address for the transfer. 663 //! \param dstAddr is the destination address for the transfer. 664 //! \param transferSize is the number of data items to transfer. 665 //! 666 //! This function is used to configure the parameters for a DMA transfer. 667 //! These parameters are typically changed often. The function 668 //! DMA_setChannelControl() MUST be called at least once for this channel prior 669 //! to calling this function. 670 //! 671 //! The \e channelStructIndex parameter should be the logical OR of the 672 //! channel number with one of \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT to 673 //! choose whether the primary or alternate data structure is used. 674 //! 675 //! The \e mode parameter should be one of the following values: 676 //! 677 //! - \b UDMA_MODE_STOP stops the DMA transfer. The controller sets the mode 678 //! to this value at the end of a transfer. 679 //! - \b UDMA_MODE_BASIC to perform a basic transfer based on request. 680 //! - \b UDMA_MODE_AUTO to perform a transfer that always completes once 681 //! started even if the request is removed. 682 //! - \b UDMA_MODE_PINGPONG to set up a transfer that switches between the 683 //! primary and alternate control structures for the channel. This mode 684 //! allows use of ping-pong buffering for DMA transfers. 685 //! - \b UDMA_MODE_MEM_SCATTER_GATHER to set up a memory scatter-gather 686 //! transfer. 687 //! - \b UDMA_MODE_PER_SCATTER_GATHER to set up a peripheral scatter-gather 688 //! transfer. 689 //! 690 //! The \e srcAddr and \e dstAddr parameters are pointers to the first 691 //! location of the data to be transferred. These addresses should be aligned 692 //! according to the item size. The compiler takes care of this alignment if 693 //! the pointers are pointing to storage of the appropriate data type. 694 //! 695 //! The \e transferSize parameter is the number of data items, not the number 696 //! of bytes. 697 //! 698 //! The two scatter-gather modes, memory and peripheral, are actually different 699 //! depending on whether the primary or alternate control structure is 700 //! selected. This function looks for the \b UDMA_PRI_SELECT and 701 //! \b UDMA_ALT_SELECT flag along with the channel number and sets the 702 //! scatter-gather mode as appropriate for the primary or alternate control 703 //! structure. 704 //! 705 //! The channel must also be enabled using DMA_enableChannel() after calling 706 //! this function. The transfer does not begin until the channel has been 707 //! configured and enabled. Note that the channel is automatically disabled 708 //! after the transfer is completed, meaning that DMA_enableChannel() must be 709 //! called again after setting up the next transfer. 710 //! 711 //! \note Great care must be taken to not modify a channel control structure 712 //! that is in use or else the results are unpredictable, including the 713 //! possibility of undesired data transfers to or from memory or peripherals. 714 //! For BASIC and AUTO modes, it is safe to make changes when the channel is 715 //! disabled, or the DMA_getChannelMode() returns \b UDMA_MODE_STOP. For 716 //! PINGPONG or one of the SCATTER_GATHER modes, it is safe to modify the 717 //! primary or alternate control structure only when the other is being used. 718 //! The DMA_getChannelMode() function returns \b UDMA_MODE_STOP when a 719 //! channel control structure is inactive and safe to modify. 720 //! 721 //! \return None. 722 // 723 //***************************************************************************** 724 extern void DMA_setChannelTransfer(uint32_t channelStructIndex, uint32_t mode, 725 void *srcAddr, void *dstAddr, uint32_t transferSize); 726 727 //***************************************************************************** 728 // 729 //! Configures a DMA channel for scatter-gather mode. 730 //! 731 //! \param channelNum is the DMA channel number. 732 //! \param taskCount is the number of scatter-gather tasks to execute. 733 //! \param taskList is a pointer to the beginning of the scatter-gather 734 //! task list. 735 //! \param isPeriphSG is a flag to indicate it is a peripheral scatter-gather 736 //! transfer (else it is memory scatter-gather transfer) 737 //! 738 //! This function is used to configure a channel for scatter-gather mode. 739 //! The caller must have already set up a task list and must pass a pointer to 740 //! the start of the task list as the \e taskList parameter. The 741 //! \e taskCount parameter is the count of tasks in the task list, not the 742 //! size of the task list. The flag \e bIsPeriphSG should be used to indicate 743 //! if scatter-gather should be configured for peripheral or memory 744 //! operation. 745 //! 746 //! \sa DMA_TaskStructEntry 747 //! 748 //! \return None. 749 // 750 //***************************************************************************** 751 extern void DMA_setChannelScatterGather(uint32_t channelNum, uint32_t taskCount, 752 void *taskList, uint32_t isPeriphSG); 753 754 //***************************************************************************** 755 // 756 //! Gets the current transfer size for a DMA channel control structure. 757 //! 758 //! \param channelStructIndex is the logical OR of the DMA channel number 759 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT. 760 //! 761 //! This function is used to get the DMA transfer size for a channel. The 762 //! transfer size is the number of items to transfer, where the size of an item 763 //! might be 8, 16, or 32 bits. If a partial transfer has already occurred, 764 //! then the number of remaining items is returned. If the transfer is 765 //! complete, then 0 is returned. 766 //! 767 //! \return Returns the number of items remaining to transfer. 768 // 769 //***************************************************************************** 770 extern uint32_t DMA_getChannelSize(uint32_t channelStructIndex); 771 772 //***************************************************************************** 773 // 774 //! Gets the transfer mode for a DMA channel control structure. 775 //! 776 //! \param channelStructIndex is the logical OR of the DMA channel number 777 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT. 778 //! 779 //! This function is used to get the transfer mode for the DMA channel and 780 //! to query the status of a transfer on a channel. When the transfer is 781 //! complete the mode is \b UDMA_MODE_STOP. 782 //! 783 //! \return Returns the transfer mode of the specified channel and control 784 //! structure, which is one of the following values: \b UDMA_MODE_STOP, 785 //! \b UDMA_MODE_BASIC, \b UDMA_MODE_AUTO, \b UDMA_MODE_PINGPONG, 786 //! \b UDMA_MODE_MEM_SCATTER_GATHER, or \b UDMA_MODE_PER_SCATTER_GATHER. 787 // 788 //***************************************************************************** 789 extern uint32_t DMA_getChannelMode(uint32_t channelStructIndex); 790 791 //***************************************************************************** 792 // 793 //! Assigns a peripheral mapping for a DMA channel. 794 //! 795 //! \param mapping is a macro specifying the peripheral assignment for 796 //! a channel. 797 //! 798 //! This function assigns a peripheral mapping to a DMA channel. It is 799 //! used to select which peripheral is used for a DMA channel. The parameter 800 //! \e mapping should be one of the macros named \b UDMA_CHn_tttt from the 801 //! header file \e dma.h. For example, to assign DMA channel 0 to the 802 //! eUSCI AO RX channel, the parameter should be the macro 803 //! \b UDMA_CH1_EUSCIA0RX. 804 //! 805 //! Please consult the data sheet for a table showing all the 806 //! possible peripheral assignments for the DMA channels for a particular 807 //! device. 808 //! 809 //! \return None. 810 // 811 //***************************************************************************** 812 extern void DMA_assignChannel(uint32_t mapping); 813 814 //***************************************************************************** 815 // 816 //! Initializes a software transfer of the corresponding DMA channel. This is 817 //! done if the user wants to force a DMA on the specified channel without the 818 //! hardware precondition. Specific channels can be configured using the 819 //! DMA_assignChannel function. 820 //! 821 //! \param channel is the channel to trigger the interrupt 822 //! 823 //! 824 //! \return None 825 // 826 //***************************************************************************** 827 extern void DMA_requestSoftwareTransfer(uint32_t channel); 828 829 //***************************************************************************** 830 // 831 //! Assigns a specific DMA channel to the corresponding interrupt handler. For 832 //! MSP432 devices, there are three configurable interrupts, and one master 833 //! interrupt. This function will assign a specific DMA channel to the 834 //! provided configurable DMA interrupt. 835 //! 836 //! Note that once a channel is assigned to a configurable interrupt, it will be 837 //! masked in hardware from the master DMA interrupt (interruptNumber zero). This 838 //! function can also be used in conjunction with the DMAIntTrigger function 839 //! to provide the feature to software trigger specific channel interrupts. 840 //! 841 //! \param interruptNumber is the configurable interrupt to assign the given 842 //! channel. Valid values are: 843 //! - \b DMA_INT1 the first configurable DMA interrupt handler 844 //! - \b DMA_INT2 the second configurable DMA interrupt handler 845 //! - \b DMA_INT3 the third configurable DMA interrupt handler 846 //! 847 //! \param channel is the channel to assign the interrupt 848 //! 849 //! \return None. 850 // 851 //***************************************************************************** 852 extern void DMA_assignInterrupt(uint32_t interruptNumber, uint32_t channel); 853 854 //***************************************************************************** 855 // 856 //! Enables the specified interrupt for the DMA controller. Note for interrupts 857 //! one through three, specific channels have to be mapped to the interrupt 858 //! using the DMA_assignInterrupt function. 859 //! 860 //! \param interruptNumber identifies which DMA interrupt is to be enabled. 861 //! This interrupt should be one of the following: 862 //! 863 //! - \b DMA_INT0 the master DMA interrupt handler 864 //! - \b DMA_INT1 the first configurable DMA interrupt handler 865 //! - \b DMA_INT2 the second configurable DMA interrupt handler 866 //! - \b DMA_INT3 the third configurable DMA interrupt handler 867 //! - \b DMA_INTERR the third configurable DMA interrupt handler 868 //! 869 //! 870 //! \return None. 871 // 872 //***************************************************************************** 873 extern void DMA_enableInterrupt(uint32_t interruptNumber); 874 875 //***************************************************************************** 876 // 877 //! Disables the specified interrupt for the DMA controller. 878 //! 879 //! \param interruptNumber identifies which DMA interrupt is to be disabled. 880 //! This interrupt should be one of the following: 881 //! 882 //! - \b DMA_INT0 the master DMA interrupt handler 883 //! - \b DMA_INT1 the first configurable DMA interrupt handler 884 //! - \b DMA_INT2 the second configurable DMA interrupt handler 885 //! - \b DMA_INT3 the third configurable DMA interrupt handler 886 //! - \b DMA_INTERR the third configurable DMA interrupt handler 887 //! 888 //! Note for interrupts that are associated with a specific DMA channel 889 //! (DMA_INT1 - DMA_INT3), this function will also enable that specific 890 //! channel for interrupts. 891 //! 892 //! \return None. 893 // 894 //***************************************************************************** 895 extern void DMA_disableInterrupt(uint32_t interruptNumber); 896 897 //***************************************************************************** 898 // 899 //! Gets the DMA controller channel interrupt status for interrupt zero. 900 //! 901 //! This function is used to get the interrupt status of the DMA controller. 902 //! The returned value is a 32-bit bit mask that indicates which channels are 903 //! requesting an interrupt. This function can be used from within an 904 //! interrupt handler to determine or confirm which DMA channel has requested 905 //! an interrupt. 906 //! 907 //! Note that this will only apply to interrupt zero for the DMA 908 //! controller as only one interrupt can be associated with interrupts one 909 //! through three. If an interrupt is assigned to an interrupt other 910 //! than interrupt zero, it will be masked by this function. 911 //! 912 //! \return Returns a 32-bit mask which indicates requesting DMA channels. 913 //! There is a bit for each channel and a 1 indicates that the channel 914 //! is requesting an interrupt. Multiple bits can be set. 915 // 916 //***************************************************************************** 917 extern uint32_t DMA_getInterruptStatus(void); 918 919 //***************************************************************************** 920 // 921 //! Clears the DMA controller channel interrupt mask for interrupt zero. 922 //! 923 //! \param channel is the channel interrupt to clear. 924 //! 925 //! This function is used to clear the interrupt status of the DMA controller. 926 //! Note that only interrupts that weren't assigned to DMA interrupts one 927 //! through three using the DMA_assignInterrupt function will be affected by 928 //! thisfunctions. For other DMA interrupts, only one channel can be associated 929 //! and therefore clearing in unnecessary. 930 //! 931 //! \return None 932 // 933 //***************************************************************************** 934 extern void DMA_clearInterruptFlag(uint32_t intChannel); 935 936 //***************************************************************************** 937 // 938 //! Registers an interrupt handler for the DMA controller. 939 //! 940 //! \param interruptNumber identifies which DMA interrupt is to be registered. 941 //! \param intHandler is a pointer to the function to be called when the 942 //! interrupt is called. 943 //! 944 //! This function registers and enables the handler to be called when the DMA 945 //! controller generates an interrupt. The \e interrupt parameter should be 946 //! one of the following: 947 //! 948 //! - \b DMA_INT0 the master DMA interrupt handler 949 //! - \b DMA_INT1 the first configurable DMA interrupt handler 950 //! - \b DMA_INT2 the second configurable DMA interrupt handler 951 //! - \b DMA_INT3 the third configurable DMA interrupt handler 952 //! - \b DMA_INTERR the third configurable DMA interrupt handler 953 //! 954 //! \sa Interrupt_registerInterrupt() for important information about 955 //! registering interrupt handlers. 956 //! 957 //! \return None. 958 // 959 //***************************************************************************** 960 extern void DMA_registerInterrupt(uint32_t intChannel, 961 void (*intHandler)(void)); 962 963 //***************************************************************************** 964 // 965 //! Unregisters an interrupt handler for the DMA controller. 966 //! 967 //! \param interruptNumber identifies which DMA interrupt to unregister. 968 //! 969 //! This function disables and unregisters the handler to be called for the 970 //! specified DMA interrupt. The \e interrupt parameter should be one of 971 //! \b the parameters as documented for the function 972 //! DMA_registerInterrupt(). 973 //! 974 //! Note fore interrupts that are associated with a specific DMA channel 975 //! (DMA_INT1 - DMA_INT3), this function will also disable that specific 976 //! channel for interrupts. 977 //! 978 //! \sa Interrupt_registerInterrupt() for important information about 979 //! registering interrupt handlers. 980 //! 981 //! \return None. 982 // 983 //***************************************************************************** 984 extern void DMA_unregisterInterrupt(uint32_t intChannel); 985 986 //***************************************************************************** 987 // 988 // Mark the end of the C bindings section for C++ compilers. 989 // 990 //***************************************************************************** 991 #ifdef __cplusplus 992 } 993 #endif 994 995 //***************************************************************************** 996 // 997 // Close the Doxygen group. 998 //! @} 999 // 1000 //***************************************************************************** 1001 1002 #endif // __UDMA_H__ 1003
