2 * -------------------------------------------
3 * MSP432 DriverLib - v3_10_00_09
4 * -------------------------------------------
6 * --COPYRIGHT--,BSD,BSD
7 * Copyright (c) 2014, Texas Instruments Incorporated
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
14 * * Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
17 * * Redistributions in binary form must reproduce the above copyright
18 * notice, this list of conditions and the following disclaimer in the
19 * documentation and/or other materials provided with the distribution.
21 * * Neither the name of Texas Instruments Incorporated nor the names of
22 * its contributors may be used to endorse or promote products derived
23 * from this software without specific prior written permission.
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
26 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
27 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
29 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
32 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
34 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
35 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 //*****************************************************************************
42 //! \addtogroup dma_api
45 //*****************************************************************************
47 //*****************************************************************************
49 // If building with a C++ compiler, make all of the definitions in this header
52 //*****************************************************************************
61 //*****************************************************************************
63 // A structure that defines an entry in the channel control table. These
64 // fields are used by the DMA controller and normally it is not necessary for
65 // software to directly read or write fields in the table.
67 //*****************************************************************************
68 typedef struct _DMA_ControlTable
71 // The ending source address of the data transfer.
73 volatile void *srcEndAddr;
76 // The ending destination address of the data transfer.
78 volatile void *dstEndAddr;
81 // The channel control mode.
83 volatile uint32_t control;
86 // An unused location.
88 volatile uint32_t spare;
91 //*****************************************************************************
93 //! A helper macro for building scatter-gather task table entries.
95 //! This macro is intended to be used to help populate a table of DMA tasks
96 //! for a scatter-gather transfer. This macro will calculate the values for
97 //! the fields of a task structure entry based on the input parameters.
99 //! There are specific requirements for the values of each parameter. No
100 //! checking is done so it is up to the caller to ensure that correct values
101 //! are used for the parameters.
103 //! The \b transferCount parameter is the number of items that will be
104 //! transferred by this task. It must be in the range 1-1024.
106 //! The \b itemSize parameter is the bit size of the transfer data. It must
107 //! be one of \b UDMA_SIZE_8, \b UDMA_SIZE_16, or \b UDMA_SIZE_32.
109 //! The \e srcIncrement parameter is the increment size for the source data.
110 //! It must be one of \b UDMA_SRC_INC_8, \b UDMA_SRC_INC_16,
111 //! \b UDMA_SRC_INC_32, or \b UDMA_SRC_INC_NONE.
113 //! The \b srcAddr parameter is a void pointer to the beginning of the source
116 //! The \b dstIncrement parameter is the increment size for the destination
117 //! data. It must be one of \b UDMA_DST_INC_8, \b UDMA_DST_INC_16,
118 //! \b UDMA_DST_INC_32, or \b UDMA_DST_INC_NONE.
120 //! The \b dstAddr parameter is a void pointer to the beginning of the
121 //! location where the data will be transferred.
123 //! The \b arbSize parameter is the arbitration size for the transfer, and
124 //! must be one of \b UDMA_ARB_1, \b UDMA_ARB_2, \b UDMA_ARB_4, and so on
125 //! up to \b UDMA_ARB_1024. This is used to select the arbitration size in
126 //! powers of 2, from 1 to 1024.
128 //! The \e mode parameter is the mode to use for this transfer task. It
129 //! must be one of \b UDMA_MODE_BASIC, \b UDMA_MODE_AUTO,
130 //! \b UDMA_MODE_MEM_SCATTER_GATHER, or \b UDMA_MODE_PER_SCATTER_GATHER. Note
131 //! that normally all tasks will be one of the scatter-gather modes while the
132 //! last task is a task list will be AUTO or BASIC.
134 //! This macro is intended to be used to initialize individual entries of
135 //! a structure of DMA_ControlTable type, like this:
138 //! DMA_ControlTable MyTaskList[] =
140 //! DMA_TaskStructEntry(Task1Count, UDMA_SIZE_8,
141 //! UDMA_SRC_INC_8, MySourceBuf,
142 //! UDMA_DST_INC_8, MyDestBuf,
143 //! UDMA_ARB_8, UDMA_MODE_MEM_SCATTER_GATHER),
144 //! DMA_TaskStructEntry(Task2Count, ... ),
148 //! \param transferCount is the count of items to transfer for this task.
149 //! \param itemSize is the bit size of the items to transfer for this task.
150 //! \param srcIncrement is the bit size increment for source data.
151 //! \param srcAddr is the starting address of the data to transfer.
152 //! \param dstIncrement is the bit size increment for destination data.
153 //! \param dstAddr is the starting address of the destination data.
154 //! \param arbSize is the arbitration size to use for the transfer task.
155 //! \param mode is the transfer mode for this task.
157 //! \return Nothing; this is not a function.
159 //*****************************************************************************
160 #define DMA_TaskStructEntry(transferCount, \
169 (((srcIncrement) == UDMA_SRC_INC_NONE) ? (void *)(srcAddr) : \
170 ((void *)(&((uint8_t *)(srcAddr))[((transferCount) << \
171 ((srcIncrement) >> 26)) - 1]))), \
172 (((dstIncrement) == UDMA_DST_INC_NONE) ? (void *)(dstAddr) : \
173 ((void *)(&((uint8_t *)(dstAddr))[((transferCount) << \
174 ((dstIncrement) >> 30)) - 1]))), \
175 (srcIncrement) | (dstIncrement) | (itemSize) | (arbSize) | \
176 (((transferCount) - 1) << 4) | \
177 ((((mode) == UDMA_MODE_MEM_SCATTER_GATHER) || \
178 ((mode) == UDMA_MODE_PER_SCATTER_GATHER)) ? \
179 (mode) | UDMA_MODE_ALT_SELECT : (mode)), 0 \
182 //*****************************************************************************
184 // Flags that can be passed to DMA_enableChannelAttribute(),
185 // DMA_disableChannelAttribute(), and returned from DMA_getChannelAttribute().
187 //*****************************************************************************
188 #define UDMA_ATTR_USEBURST 0x00000001
189 #define UDMA_ATTR_ALTSELECT 0x00000002
190 #define UDMA_ATTR_HIGH_PRIORITY 0x00000004
191 #define UDMA_ATTR_REQMASK 0x00000008
192 #define UDMA_ATTR_ALL 0x0000000F
194 //*****************************************************************************
196 // DMA control modes that can be passed to DMAModeSet() and returned
199 //*****************************************************************************
200 #define UDMA_MODE_STOP 0x00000000
201 #define UDMA_MODE_BASIC 0x00000001
202 #define UDMA_MODE_AUTO 0x00000002
203 #define UDMA_MODE_PINGPONG 0x00000003
204 #define UDMA_MODE_MEM_SCATTER_GATHER \
206 #define UDMA_MODE_PER_SCATTER_GATHER \
208 #define UDMA_MODE_ALT_SELECT 0x00000001
210 //*****************************************************************************
212 // Channel configuration values that can be passed to DMAControlSet().
214 //*****************************************************************************
215 #define UDMA_DST_INC_8 0x00000000
216 #define UDMA_DST_INC_16 0x40000000
217 #define UDMA_DST_INC_32 0x80000000
218 #define UDMA_DST_INC_NONE 0xc0000000
219 #define UDMA_SRC_INC_8 0x00000000
220 #define UDMA_SRC_INC_16 0x04000000
221 #define UDMA_SRC_INC_32 0x08000000
222 #define UDMA_SRC_INC_NONE 0x0c000000
223 #define UDMA_SIZE_8 0x00000000
224 #define UDMA_SIZE_16 0x11000000
225 #define UDMA_SIZE_32 0x22000000
226 #define UDMA_DST_PROT_PRIV 0x00200000
227 #define UDMA_SRC_PROT_PRIV 0x00040000
228 #define UDMA_ARB_1 0x00000000
229 #define UDMA_ARB_2 0x00004000
230 #define UDMA_ARB_4 0x00008000
231 #define UDMA_ARB_8 0x0000c000
232 #define UDMA_ARB_16 0x00010000
233 #define UDMA_ARB_32 0x00014000
234 #define UDMA_ARB_64 0x00018000
235 #define UDMA_ARB_128 0x0001c000
236 #define UDMA_ARB_256 0x00020000
237 #define UDMA_ARB_512 0x00024000
238 #define UDMA_ARB_1024 0x00028000
239 #define UDMA_NEXT_USEBURST 0x00000008
241 //*****************************************************************************
243 // Flags to be OR'd with the channel ID to indicate if the primary or alternate
244 // control structure should be used.
246 //*****************************************************************************
247 #define UDMA_PRI_SELECT 0x00000000
248 #define UDMA_ALT_SELECT 0x00000008
250 //*****************************************************************************
252 // Values that can be passed to DMA_assignChannel() to select peripheral
253 // mapping for each channel. The channels named RESERVED may be assigned
254 // to a peripheral in future parts.
256 //*****************************************************************************
260 #define DMA_CH0_RESERVED0 0x00000000
261 #define DMA_CH0_EUSCIA0TX 0x01000000
262 #define DMA_CH0_EUSCIB0TX0 0x02000000
263 #define DMA_CH0_EUSCIB3TX1 0x03000000
264 #define DMA_CH0_EUSCIB2TX2 0x04000000
265 #define DMA_CH0_EUSCIB1TX3 0x05000000
266 #define DMA_CH0_TIMERA0CCR0 0x06000000
267 #define DMA_CH0_AESTRIGGER0 0x07000000
272 #define DMA_CH1_RESERVED0 0x00000001
273 #define DMA_CH1_EUSCIA0RX 0x01000001
274 #define DMA_CH1_EUSCIB0RX0 0x02000001
275 #define DMA_CH1_EUSCIB3RX1 0x03000001
276 #define DMA_CH1_EUSCIB2RX2 0x04000001
277 #define DMA_CH1_EUSCIB1RX3 0x05000001
278 #define DMA_CH1_TIMERA0CCR2 0x06000001
279 #define DMA_CH1_AESTRIGGER1 0x07000001
284 #define DMA_CH2_RESERVED0 0x00000002
285 #define DMA_CH2_EUSCIA1TX 0x01000002
286 #define DMA_CH2_EUSCIB1TX0 0x02000002
287 #define DMA_CH2_EUSCIB0TX1 0x03000002
288 #define DMA_CH2_EUSCIB3TX2 0x04000002
289 #define DMA_CH2_EUSCIB2TX3 0x05000002
290 #define DMA_CH2_TIMERA1CCR0 0x06000002
291 #define DMA_CH2_AESTRIGGER2 0x07000002
296 #define DMA_CH3_RESERVED0 0x00000003
297 #define DMA_CH3_EUSCIA1RX 0x01000003
298 #define DMA_CH3_EUSCIB1RX0 0x02000003
299 #define DMA_CH3_EUSCIB0RX1 0x03000003
300 #define DMA_CH3_EUSCIB3RX2 0x04000003
301 #define DMA_CH3_EUSCIB2RX3 0x05000003
302 #define DMA_CH3_TIMERA1CCR2 0x06000003
303 #define DMA_CH3_RESERVED1 0x07000003
308 #define DMA_CH4_RESERVED0 0x00000004
309 #define DMA_CH4_EUSCIA2TX 0x01000004
310 #define DMA_CH4_EUSCIB2TX0 0x02000004
311 #define DMA_CH4_EUSCIB1TX1 0x03000004
312 #define DMA_CH4_EUSCIB0TX2 0x04000004
313 #define DMA_CH4_EUSCIB3TX3 0x05000004
314 #define DMA_CH4_TIMERA2CCR0 0x06000004
315 #define DMA_CH4_RESERVED1 0x07000004
320 #define DMA_CH5_RESERVED0 0x00000005
321 #define DMA_CH5_EUSCIA2RX 0x01000005
322 #define DMA_CH5_EUSCIB2RX0 0x02000005
323 #define DMA_CH5_EUSCIB1RX1 0x03000005
324 #define DMA_CH5_EUSCIB0RX2 0x04000005
325 #define DMA_CH5_EUSCIB3RX3 0x05000005
326 #define DMA_CH5_TIMERA2CCR2 0x06000005
327 #define DMA_CH5_RESERVED1 0x07000005
332 #define DMA_CH6_RESERVED0 0x00000006
333 #define DMA_CH6_EUSCIA3TX 0x01000006
334 #define DMA_CH6_EUSCIB3TX0 0x02000006
335 #define DMA_CH6_EUSCIB2TX1 0x03000006
336 #define DMA_CH6_EUSCIB1TX2 0x04000006
337 #define DMA_CH6_EUSCIB0TX3 0x05000006
338 #define DMA_CH6_TIMERA3CCR0 0x06000006
339 #define DMA_CH6_EXTERNALPIN 0x07000006
344 #define DMA_CH7_RESERVED0 0x00000007
345 #define DMA_CH7_EUSCIA3RX 0x01000007
346 #define DMA_CH7_EUSCIB3RX0 0x02000007
347 #define DMA_CH7_EUSCIB2RX1 0x03000007
348 #define DMA_CH7_EUSCIB1RX2 0x04000007
349 #define DMA_CH7_EUSCIB0RX3 0x05000007
350 #define DMA_CH7_TIMERA3CCR2 0x06000007
351 #define DMA_CH7_ADC14 0x07000007
354 // Different interrupt handlers to pass into DMA_registerInterrupt and
355 // DMA_unregisterInterrupt and other Int functions
357 #define DMA_INT0 INT_DMA_INT0
358 #define DMA_INT1 INT_DMA_INT1
359 #define DMA_INT2 INT_DMA_INT2
360 #define DMA_INT3 INT_DMA_INT3
361 #define DMA_INTERR INT_DMA_ERR
363 #define DMA_CHANNEL_0 0
364 #define DMA_CHANNEL_1 1
365 #define DMA_CHANNEL_2 2
366 #define DMA_CHANNEL_3 3
367 #define DMA_CHANNEL_4 4
368 #define DMA_CHANNEL_5 5
369 #define DMA_CHANNEL_6 6
370 #define DMA_CHANNEL_7 7
372 //*****************************************************************************
374 // API Function prototypes
376 //*****************************************************************************
378 //*****************************************************************************
380 //! Enables the DMA controller for use.
382 //! This function enables the DMA controller. The DMA controller must be
383 //! enabled before it can be configured and used.
387 //*****************************************************************************
388 extern void DMA_enableModule(void);
390 //*****************************************************************************
392 //! Disables the DMA controller for use.
394 //! This function disables the DMA controller. Once disabled, the DMA
395 //! controller cannot operate until re-enabled with DMA_enableModule().
399 //*****************************************************************************
400 extern void DMA_disableModule(void);
402 //*****************************************************************************
404 //! Gets the DMA error status.
406 //! This function returns the DMA error status. It should be called from
407 //! within the DMA error interrupt handler to determine if a DMA error
410 //! \return Returns non-zero if a DMA error is pending.
412 //*****************************************************************************
413 extern uint32_t DMA_getErrorStatus(void);
415 //*****************************************************************************
417 //! Clears the DMA error interrupt.
419 //! This function clears a pending DMA error interrupt. This function should
420 //! be called from within the DMA error interrupt handler to clear the
425 //*****************************************************************************
426 extern void DMA_clearErrorStatus(void);
428 //*****************************************************************************
430 //! Enables a DMA channel for operation.
432 //! \param channelNum is the channel number to enable.
434 //! This function enables a specific DMA channel for use. This function must
435 //! be used to enable a channel before it can be used to perform a DMA
438 //! When a DMA transfer is completed, the channel is automatically disabled by
439 //! the DMA controller. Therefore, this function should be called prior to
440 //! starting up any new transfer.
444 //*****************************************************************************
445 extern void DMA_enableChannel(uint32_t channelNum);
447 //*****************************************************************************
449 //! Disables a DMA channel for operation.
451 //! \param channelNum is the channel number to disable.
453 //! This function disables a specific DMA channel. Once disabled, a channel
454 //! cannot respond to DMA transfer requests until re-enabled via
455 //! DMA_enableChannel().
459 //*****************************************************************************
460 extern void DMA_disableChannel(uint32_t channelNum);
462 //*****************************************************************************
464 //! Checks if a DMA channel is enabled for operation.
466 //! \param channelNum is the channel number to check.
468 //! This function checks to see if a specific DMA channel is enabled. This
469 //! function can be used to check the status of a transfer, as the channel is
470 //! automatically disabled at the end of a transfer.
472 //! \return Returns \b true if the channel is enabled, \b false if disabled.
474 //*****************************************************************************
475 extern bool DMA_isChannelEnabled(uint32_t channelNum);
477 //*****************************************************************************
479 //! Sets the base address for the channel control table.
481 //! \param controlTable is a pointer to the 1024-byte-aligned base address
482 //! of the DMA channel control table.
484 //! This function configures the base address of the channel control table.
485 //! This table resides in system memory and holds control information for each
486 //! DMA channel. The table must be aligned on a 1024-byte boundary. The base
487 //! address must be configured before any of the channel functions can be used.
489 //! The size of the channel control table depends on the number of DMA
490 //! channels and the transfer modes that are used. Refer to the introductory
491 //! text and the microcontroller datasheet for more information about the
492 //! channel control table.
496 //*****************************************************************************
497 extern void DMA_setControlBase(void *controlTable);
499 //*****************************************************************************
501 //! Gets the base address for the channel control table.
503 //! This function gets the base address of the channel control table. This
504 //! table resides in system memory and holds control information for each DMA
507 //! \return Returns a pointer to the base address of the channel control table.
509 //*****************************************************************************
510 extern void* DMA_getControlBase(void);
512 //*****************************************************************************
514 //! Gets the base address for the channel control table alternate structures.
516 //! This function gets the base address of the second half of the channel
517 //! control table that holds the alternate control structures for each channel.
519 //! \return Returns a pointer to the base address of the second half of the
520 //! channel control table.
522 //*****************************************************************************
523 extern void* DMA_getControlAlternateBase(void);
525 //*****************************************************************************
527 //! Requests a DMA channel to start a transfer.
529 //! \param channelNum is the channel number on which to request a DMA
532 //! This function allows software to request a DMA channel to begin a
533 //! transfer. This function could be used for performing a memory-to-memory
534 //! transfer, or if for some reason a transfer needs to be initiated by
535 //! software instead of the peripheral associated with that channel.
539 //*****************************************************************************
540 extern void DMA_requestChannel(uint32_t channelNum);
542 //*****************************************************************************
544 //! Enables attributes of a DMA channel.
546 //! \param channelNum is the channel to configure.
547 //! \param attr is a combination of attributes for the channel.
549 //! This function is used to enable attributes of a DMA channel.
551 //! The \e attr parameter is the logical OR of any of the following:
553 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst
555 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure
556 //! for this channel (it is very unlikely that this flag should be used).
557 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
558 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the
559 //! peripheral for this channel.
563 //*****************************************************************************
564 extern void DMA_enableChannelAttribute(uint32_t channelNum, uint32_t attr);
566 //*****************************************************************************
568 //! Disables attributes of a DMA channel.
570 //! \param channelNum is the channel to configure.
571 //! \param attr is a combination of attributes for the channel.
573 //! This function is used to disable attributes of a DMA channel.
575 //! The \e attr parameter is the logical OR of any of the following:
577 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst
579 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure
580 //! for this channel.
581 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
582 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the
583 //! peripheral for this channel.
587 //*****************************************************************************
588 extern void DMA_disableChannelAttribute(uint32_t channelNum, uint32_t attr);
590 //*****************************************************************************
592 //! Gets the enabled attributes of a DMA channel.
594 //! \param channelNum is the channel to configure.
596 //! This function returns a combination of flags representing the attributes of
599 //! \return Returns the logical OR of the attributes of the DMA channel, which
600 //! can be any of the following:
601 //! - \b UDMA_ATTR_USEBURST is used to restrict transfers to use only burst
603 //! - \b UDMA_ATTR_ALTSELECT is used to select the alternate control structure
604 //! for this channel.
605 //! - \b UDMA_ATTR_HIGH_PRIORITY is used to set this channel to high priority.
606 //! - \b UDMA_ATTR_REQMASK is used to mask the hardware request signal from the
607 //! peripheral for this channel.
609 //*****************************************************************************
610 extern uint32_t DMA_getChannelAttribute(uint32_t channelNum);
612 //*****************************************************************************
614 //! Sets the control parameters for a DMA channel control structure.
616 //! \param channelStructIndex is the logical OR of the DMA channel number
617 //! with \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT.
618 //! \param control is logical OR of several control values to set the control
619 //! parameters for the channel.
621 //! This function is used to set control parameters for a DMA transfer. These
622 //! parameters are typically not changed often.
624 //! The \e channelStructIndex parameter should be the logical OR of the
625 //! channel number with one of \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT to
626 //! choose whether the primary or alternate data structure is used.
628 //! The \e control parameter is the logical OR of five values: the data size,
629 //! the source address increment, the destination address increment, the
630 //! arbitration size, and the use burst flag. The choices available for each
631 //! of these values is described below.
633 //! Choose the data size from one of \b UDMA_SIZE_8, \b UDMA_SIZE_16, or
634 //! \b UDMA_SIZE_32 to select a data size of 8, 16, or 32 bits.
636 //! Choose the source address increment from one of \b UDMA_SRC_INC_8,
637 //! \b UDMA_SRC_INC_16, \b UDMA_SRC_INC_32, or \b UDMA_SRC_INC_NONE to select
638 //! an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or
639 //! to select non-incrementing.
641 //! Choose the destination address increment from one of \b UDMA_DST_INC_8,
642 //! \b UDMA_DST_INC_16, \b UDMA_DST_INC_32, or \b UDMA_SRC_INC_8 to select
643 //! an address increment of 8-bit bytes, 16-bit half-words, 32-bit words, or
644 //! to select non-incrementing.
646 //! The arbitration size determines how many items are transferred before
647 //! the DMA controller re-arbitrates for the bus. Choose the arbitration size
648 //! from one of \b UDMA_ARB_1, \b UDMA_ARB_2, \b UDMA_ARB_4, \b UDMA_ARB_8,
649 //! through \b UDMA_ARB_1024 to select the arbitration size from 1 to 1024
650 //! items, in powers of 2.
652 //! The value \b UDMA_NEXT_USEBURST is used to force the channel to only
653 //! respond to burst requests at the tail end of a scatter-gather transfer.
655 //! \note The address increment cannot be smaller than the data size.
659 //*****************************************************************************
660 extern void DMA_setChannelControl(uint32_t channelStructIndex,
663 //*****************************************************************************
665 //! Sets the transfer parameters for a DMA channel control structure.
667 //! \param channelStructIndex is the logical OR of the DMA channel number
668 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT.
669 //! \param mode is the type of DMA transfer.
670 //! \param srcAddr is the source address for the transfer.
671 //! \param dstAddr is the destination address for the transfer.
672 //! \param transferSize is the number of data items to transfer.
674 //! This function is used to configure the parameters for a DMA transfer.
675 //! These parameters are typically changed often. The function
676 //! DMA_setChannelControl() MUST be called at least once for this channel prior
677 //! to calling this function.
679 //! The \e channelStructIndex parameter should be the logical OR of the
680 //! channel number with one of \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT to
681 //! choose whether the primary or alternate data structure is used.
683 //! The \e mode parameter should be one of the following values:
685 //! - \b UDMA_MODE_STOP stops the DMA transfer. The controller sets the mode
686 //! to this value at the end of a transfer.
687 //! - \b UDMA_MODE_BASIC to perform a basic transfer based on request.
688 //! - \b UDMA_MODE_AUTO to perform a transfer that always completes once
689 //! started even if the request is removed.
690 //! - \b UDMA_MODE_PINGPONG to set up a transfer that switches between the
691 //! primary and alternate control structures for the channel. This mode
692 //! allows use of ping-pong buffering for DMA transfers.
693 //! - \b UDMA_MODE_MEM_SCATTER_GATHER to set up a memory scatter-gather
695 //! - \b UDMA_MODE_PER_SCATTER_GATHER to set up a peripheral scatter-gather
698 //! The \e srcAddr and \e dstAddr parameters are pointers to the first
699 //! location of the data to be transferred. These addresses should be aligned
700 //! according to the item size. The compiler takes care of this alignment if
701 //! the pointers are pointing to storage of the appropriate data type.
703 //! The \e transferSize parameter is the number of data items, not the number
706 //! The two scatter-gather modes, memory and peripheral, are actually different
707 //! depending on whether the primary or alternate control structure is
708 //! selected. This function looks for the \b UDMA_PRI_SELECT and
709 //! \b UDMA_ALT_SELECT flag along with the channel number and sets the
710 //! scatter-gather mode as appropriate for the primary or alternate control
713 //! The channel must also be enabled using DMA_enableChannel() after calling
714 //! this function. The transfer does not begin until the channel has been
715 //! configured and enabled. Note that the channel is automatically disabled
716 //! after the transfer is completed, meaning that DMA_enableChannel() must be
717 //! called again after setting up the next transfer.
719 //! \note Great care must be taken to not modify a channel control structure
720 //! that is in use or else the results are unpredictable, including the
721 //! possibility of undesired data transfers to or from memory or peripherals.
722 //! For BASIC and AUTO modes, it is safe to make changes when the channel is
723 //! disabled, or the DMA_getChannelMode() returns \b UDMA_MODE_STOP. For
724 //! PINGPONG or one of the SCATTER_GATHER modes, it is safe to modify the
725 //! primary or alternate control structure only when the other is being used.
726 //! The DMA_getChannelMode() function returns \b UDMA_MODE_STOP when a
727 //! channel control structure is inactive and safe to modify.
731 //*****************************************************************************
732 extern void DMA_setChannelTransfer(uint32_t channelStructIndex, uint32_t mode,
733 void *srcAddr, void *dstAddr, uint32_t transferSize);
735 //*****************************************************************************
737 //! Configures a DMA channel for scatter-gather mode.
739 //! \param channelNum is the DMA channel number.
740 //! \param taskCount is the number of scatter-gather tasks to execute.
741 //! \param taskList is a pointer to the beginning of the scatter-gather
743 //! \param isPeriphSG is a flag to indicate it is a peripheral scatter-gather
744 //! transfer (else it is memory scatter-gather transfer)
746 //! This function is used to configure a channel for scatter-gather mode.
747 //! The caller must have already set up a task list and must pass a pointer to
748 //! the start of the task list as the \e taskList parameter. The
749 //! \e taskCount parameter is the count of tasks in the task list, not the
750 //! size of the task list. The flag \e bIsPeriphSG should be used to indicate
751 //! if scatter-gather should be configured for peripheral or memory
754 //! \sa DMA_TaskStructEntry
758 //*****************************************************************************
759 extern void DMA_setChannelScatterGather(uint32_t channelNum, uint32_t taskCount,
760 void *taskList, uint32_t isPeriphSG);
762 //*****************************************************************************
764 //! Gets the current transfer size for a DMA channel control structure.
766 //! \param channelStructIndex is the logical OR of the DMA channel number
767 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT.
769 //! This function is used to get the DMA transfer size for a channel. The
770 //! transfer size is the number of items to transfer, where the size of an item
771 //! might be 8, 16, or 32 bits. If a partial transfer has already occurred,
772 //! then the number of remaining items is returned. If the transfer is
773 //! complete, then 0 is returned.
775 //! \return Returns the number of items remaining to transfer.
777 //*****************************************************************************
778 extern uint32_t DMA_getChannelSize(uint32_t channelStructIndex);
780 //*****************************************************************************
782 //! Gets the transfer mode for a DMA channel control structure.
784 //! \param channelStructIndex is the logical OR of the DMA channel number
785 //! with either \b UDMA_PRI_SELECT or \b UDMA_ALT_SELECT.
787 //! This function is used to get the transfer mode for the DMA channel and
788 //! to query the status of a transfer on a channel. When the transfer is
789 //! complete the mode is \b UDMA_MODE_STOP.
791 //! \return Returns the transfer mode of the specified channel and control
792 //! structure, which is one of the following values: \b UDMA_MODE_STOP,
793 //! \b UDMA_MODE_BASIC, \b UDMA_MODE_AUTO, \b UDMA_MODE_PINGPONG,
794 //! \b UDMA_MODE_MEM_SCATTER_GATHER, or \b UDMA_MODE_PER_SCATTER_GATHER.
796 //*****************************************************************************
797 extern uint32_t DMA_getChannelMode(uint32_t channelStructIndex);
799 //*****************************************************************************
801 //! Assigns a peripheral mapping for a DMA channel.
803 //! \param mapping is a macro specifying the peripheral assignment for
806 //! This function assigns a peripheral mapping to a DMA channel. It is
807 //! used to select which peripheral is used for a DMA channel. The parameter
808 //! \e mapping should be one of the macros named \b UDMA_CHn_tttt from the
809 //! header file \e dma.h. For example, to assign DMA channel 0 to the
810 //! eUSCI AO RX channel, the parameter should be the macro
811 //! \b UDMA_CH1_EUSCIA0RX.
813 //! Please consult the data sheet for a table showing all the
814 //! possible peripheral assignments for the DMA channels for a particular
819 //*****************************************************************************
820 extern void DMA_assignChannel(uint32_t mapping);
822 //*****************************************************************************
824 //! Initializes a software transfer of the corresponding DMA channel. This is
825 //! done if the user wants to force a DMA on the specified channel without the
826 //! hardware precondition. Specific channels can be configured using the
827 //! DMA_assignChannel function.
829 //! \param channel is the channel to trigger the interrupt
834 //*****************************************************************************
835 extern void DMA_requestSoftwareTransfer(uint32_t channel);
837 //*****************************************************************************
839 //! Assigns a specific DMA channel to the corresponding interrupt handler. For
840 //! MSP432 devices, there are three configurable interrupts, and one master
841 //! interrupt. This function will assign a specific DMA channel to the
842 //! provided configurable DMA interrupt.
844 //! Note that once a channel is assigned to a configurable interrupt, it will be
845 //! masked in hardware from the master DMA interrupt (interruptNumber zero). This
846 //! function can also be used in conjunction with the DMAIntTrigger function
847 //! to provide the feature to software trigger specific channel interrupts.
849 //! \param interruptNumber is the configurable interrupt to assign the given
850 //! channel. Valid values are:
851 //! - \b DMA_INT1 the first configurable DMA interrupt handler
852 //! - \b DMA_INT2 the second configurable DMA interrupt handler
853 //! - \b DMA_INT3 the third configurable DMA interrupt handler
855 //! \param channel is the channel to assign the interrupt
859 //*****************************************************************************
860 extern void DMA_assignInterrupt(uint32_t interruptNumber, uint32_t channel);
862 //*****************************************************************************
864 //! Enables the specified interrupt for the DMA controller. Note for interrupts
865 //! one through three, specific channels have to be mapped to the interrupt
866 //! using the DMA_assignInterrupt function.
868 //! \param interruptNumber identifies which DMA interrupt is to be enabled.
869 //! This interrupt should be one of the following:
871 //! - \b DMA_INT0 the master DMA interrupt handler
872 //! - \b DMA_INT1 the first configurable DMA interrupt handler
873 //! - \b DMA_INT2 the second configurable DMA interrupt handler
874 //! - \b DMA_INT3 the third configurable DMA interrupt handler
875 //! - \b DMA_INTERR the third configurable DMA interrupt handler
880 //*****************************************************************************
881 extern void DMA_enableInterrupt(uint32_t interruptNumber);
883 //*****************************************************************************
885 //! Disables the specified interrupt for the DMA controller.
887 //! \param interruptNumber identifies which DMA interrupt is to be disabled.
888 //! This interrupt should be one of the following:
890 //! - \b DMA_INT0 the master DMA interrupt handler
891 //! - \b DMA_INT1 the first configurable DMA interrupt handler
892 //! - \b DMA_INT2 the second configurable DMA interrupt handler
893 //! - \b DMA_INT3 the third configurable DMA interrupt handler
894 //! - \b DMA_INTERR the third configurable DMA interrupt handler
896 //! Note for interrupts that are associated with a specific DMA channel
897 //! (DMA_INT1 - DMA_INT3), this function will also enable that specific
898 //! channel for interrupts.
902 //*****************************************************************************
903 extern void DMA_disableInterrupt(uint32_t interruptNumber);
905 //*****************************************************************************
907 //! Gets the DMA controller channel interrupt status for interrupt zero.
909 //! This function is used to get the interrupt status of the DMA controller.
910 //! The returned value is a 32-bit bit mask that indicates which channels are
911 //! requesting an interrupt. This function can be used from within an
912 //! interrupt handler to determine or confirm which DMA channel has requested
915 //! Note that this will only apply to interrupt zero for the DMA
916 //! controller as only one interrupt can be associated with interrupts one
917 //! through three. If an interrupt is assigned to an interrupt other
918 //! than interrupt zero, it will be masked by this function.
920 //! \return Returns a 32-bit mask which indicates requesting DMA channels.
921 //! There is a bit for each channel and a 1 indicates that the channel
922 //! is requesting an interrupt. Multiple bits can be set.
924 //*****************************************************************************
925 extern uint32_t DMA_getInterruptStatus(void);
927 //*****************************************************************************
929 //! Clears the DMA controller channel interrupt mask for interrupt zero.
931 //! \param channel is the channel interrupt to clear.
933 //! This function is used to clear the interrupt status of the DMA controller.
934 //! Note that only interrupts that weren't assigned to DMA interrupts one
935 //! through three using the DMA_assignInterrupt function will be affected by
936 //! thisfunctions. For other DMA interrupts, only one channel can be associated
937 //! and therefore clearing in unnecessary.
941 //*****************************************************************************
942 extern void DMA_clearInterruptFlag(uint32_t intChannel);
944 //*****************************************************************************
946 //! Registers an interrupt handler for the DMA controller.
948 //! \param interruptNumber identifies which DMA interrupt is to be registered.
949 //! \param intHandler is a pointer to the function to be called when the
950 //! interrupt is called.
952 //! This function registers and enables the handler to be called when the DMA
953 //! controller generates an interrupt. The \e interrupt parameter should be
954 //! one of the following:
956 //! - \b DMA_INT0 the master DMA interrupt handler
957 //! - \b DMA_INT1 the first configurable DMA interrupt handler
958 //! - \b DMA_INT2 the second configurable DMA interrupt handler
959 //! - \b DMA_INT3 the third configurable DMA interrupt handler
960 //! - \b DMA_INTERR the third configurable DMA interrupt handler
962 //! \sa Interrupt_registerInterrupt() for important information about
963 //! registering interrupt handlers.
967 //*****************************************************************************
968 extern void DMA_registerInterrupt(uint32_t intChannel,
969 void (*intHandler)(void));
971 //*****************************************************************************
973 //! Unregisters an interrupt handler for the DMA controller.
975 //! \param interruptNumber identifies which DMA interrupt to unregister.
977 //! This function disables and unregisters the handler to be called for the
978 //! specified DMA interrupt. The \e interrupt parameter should be one of
979 //! \b the parameters as documented for the function
980 //! DMA_registerInterrupt().
982 //! Note fore interrupts that are associated with a specific DMA channel
983 //! (DMA_INT1 - DMA_INT3), this function will also disable that specific
984 //! channel for interrupts.
986 //! \sa Interrupt_registerInterrupt() for important information about
987 //! registering interrupt handlers.
991 //*****************************************************************************
992 extern void DMA_unregisterInterrupt(uint32_t intChannel);
994 //*****************************************************************************
996 // Mark the end of the C bindings section for C++ compilers.
998 //*****************************************************************************
1003 //*****************************************************************************
1005 // Close the Doxygen group.
1008 //*****************************************************************************
1010 #endif // __UDMA_H__