fix(PeriphDrivers): Fix UART DMA Transactions and Enable Full Duplex

[Jake-Carter]

Description

Our UART DMA transactions were essentially unusable, and only happened to work if the transaction function happened to acquire DMA channel 0.

This PR fixes #761

It implements 2 features:

1. UART DMA "Auto handlers"
2. APIs for using application-defined DMA handlers and channels

DMA Auto Handlers

This behavior is disabled by default... but I would like to make this the default. Please comment.

Users now have the option to enable "auto handlers" for the UART DMA transactions with

MXC_UART_SetAutoDMAHandlers(MXC_UART_GET_UART(...), true);

When auto handlers are enabled, the drivers will automatically acquire a DMA channel, enable the IRQ, assign an internal handler function, then release the acquired channel when the transaction's finished. This makes UART DMA simpler to set up and use.

New APIs for Assigning DMA Channels

int MXC_UART_SetTXDMAChannel(mxc_uart_regs_t *uart, unsigned int channel);

int MXC_UART_GetTXDMAChannel(mxc_uart_regs_t *uart);

int MXC_UART_SetRXDMAChannel(mxc_uart_regs_t *uart, unsigned int channel);

int MXC_UART_GetRXDMAChannel(mxc_uart_regs_t *uart);

New APIs have been added for managing the UART DMA channels manually. The application code is responsible for acquiring a channel and assigning an appropriate handler. The application is also responsible for releasing the channel when necessary.

void UART_DMA_Handler(void)
{
    MXC_DMA_Handler();
}

int main()
{
    /* This section shows the setup required for using application-defined 
    UART DMA handlers.  The application code is responsible for acquiring 
    DMA channels, assigning the right IRQ to an ISR, calling the default
    DMA handler, and releasing acquired channels if necessary. */
    error = MXC_DMA_Init(DMA_INSTANCE);
    if (error) {
        printf("Failed to initialize DMA with error %i\n", error);
    }

    int channel = MXC_DMA_AcquireChannel(DMA_INSTANCE);
    if (channel < 0) {
        printf("Failed to acquire DMA Channel with error %i\n", error);
    }

    // Enable the IRQ for the acquired channel,
    // and set the ISR to the application-defined handler.
    IRQn_Type irq = MXC_DMA_CH_GET_IRQ(channel);
    NVIC_EnableIRQ(irq);
    MXC_NVIC_SetVector(irq, UART_DMA_Handler);

    // Tell the UART DMA transaction functions to use the acquired channel.
    MXC_UART_SetTXDMAChannel(MXC_UART_GET_UART(CONSOLE_UART), channel);

    // ...
}

 

Checklist Before Requesting Review

• PR Title follows correct guidelines.
• Description of changes and all other relevant information.
• (Optional) Link any related GitHub issues using a keyword
• (Optional) Provide info on any relevant functional testing/validation. For API changes or significant features, this is not optional.

[Jake-Carter]

For readability I've applied these changes for the ME14. Will port after review. The Rev B and C UART drivers may also need these fixes.

[EricB-ADI]

/clang-format-run

[Jacob-Scheiffler]

Looks good overall. Just a couple of minor comments we should discuss.

[lorne-maxim]

I'd like to avoid part specific code in the _revX.c files. Can this condition be based on MXC_DMA_INSTANCES instead?

[lorne-maxim]

These checks could be asserts. They are not really time critical, though, so I'll leave the final decision to you.

[Jake-Carter]

Thanks @lorne-maxim, updated in 831c893

[lorne-maxim]

Here is another place where ASSERT may be better. I see other places (not just in the code this PR touches) that could be ASSERTs also. IMO, anything that checks to see if a valid UART instance was passed in is better as an ASSERT.

[Jake-Carter]

34db845

[Jake-Carter]

@lorne-maxim I ended up purging the asserts except for once in the Init functions. The compiler should catch those cases as type-cast mismatch, so I think the checks for a valid UART instance in every function were overkill anyways...

It reduces our kid size pretty significantly, which is nice

[Jake-Carter]

Added API change tag for non-breaking additions of new functions