Arbitrary Length Transmit and Receive - DMA

This sample demonstrates arbitrary length data communication with a PC terminal using UART and DMA .

The SoC receives data from the PC terminal using DMA. Simultaneously, the UART_FLAG_RX_IDLE case gets the arbitrary length of data, handles the data, and sets received_flag to indicate that the reception is complete.

The SoC sends the data back to the PC terminal using DMA when the received_flag is set.

Requirements

The sample supports the following development kits:

Development Kits

Hardware Platforms

Board Name

RTL87x2G HDK

RTL87x2G EVB

For more requirements, please refer to Quick Start.

Wiring

Connect P3_0 to the RX pin of the FT232 and P3_1 to the TX pin of the FT232.

Building and Downloading

This sample can be found in the SDK folder:

Project file: samples\peripheral\uart\unfixedlen_gdma\proj\rtl87x2g\mdk

Project file: samples\peripheral\uart\unfixedlen_gdma\proj\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

  1. Open sample project file.

  2. To build the target, follow the steps listed on the Generating App Image in Quick Start.

  3. After a successful compilation, the app bin app_MP_xxx.bin will be generated in the directory mdk\bin or gcc\bin.

  4. To download app bin into EVB board, follow the steps listed on the MP Tool Download in Quick Start.

  5. Press reset button on EVB board and it will start running.

Experimental Verification

Preparation Phase

  1. Start a PC terminal like PuTTY or UartAssist and connect to the used COM port with the following UART settings:

  • Baud rate: 115200

  • 8 data bits

  • 1 stop bit

  • No parity

  • No hardware flow control

Testing Phase

  1. After resetting the EVB, observe the log information as shown in the Debug Analyzer.

    Start uart tx rx unfixedlen by gdma test!

  2. Type strings on the PC terminal and observe that the same string appears on the PC terminal. Simultaneously, observe that received data and interrupt information appear in the Debug Analyzer. Assuming the input data length on the PC terminal is number, the interrupt log for different cases is as follows:

    GDMA0_Channel4_Handler  /* time = (number / block_size) > 0 triggers time interrupts and print logs. */

UART_FLAG_RX_IDLE       /* time = (number % block_size) > 0 and meeting the UART_FLAG_RX_IDLE interrupt condition triggers time interrupts and print logs. */
value is 0x..
value is 0x..
value is 0x..
...

UART_TX_GDMA_Handler    /* Once received_flag is set, the SoC uses GDMA to send number length data back to the PC terminal. Upon completion, it triggers the interrupt and prints logs. */

Code Overview

This chapter will be introduced according to the following several parts:

  1. Source Code Directory.

  2. Peripheral initialization will be introduced in chapter Initialization.

  3. Functional implementation after initialization will be introduced in chapter Functional Implementation .

Source Code Directory

  • Project directory: sdk\samples\peripheral\uart\unfixedlen_gdma\proj

  • Source code directory: sdk\samples\peripheral\uart\unfixedlen_gdma\src

Source files are currently categorized into several groups as below.

└── Project: output_toggle
    └── secure_only_app
        └── Device                   includes startup code
            ├── startup_rtl.c
            └── system_rtl.c
        ├── CMSIS                    includes CMSIS header files
        ├── CMSE Library             Non-secure callable lib
        ├── lib                      includes all binary symbol files that user application is built on
            └── rtl87x2g_io.lib
        ├── peripheral               includes all peripheral drivers and module code used by the application
            ├── rtl_gdma.c
            ├── rtl_nvic.c
            ├── rtl_pinmux.c
            ├── rtl_rcc.c
            └── rtl_uart.c
        └── APP                      includes the ble_peripheral user application implementation
            ├── io_uart.c
            └── main_ns.c

Initialization

The initialization process includes board_uart_init and driver_uart_init .

board_uart_init contains the PAD and PINMUX settings:

  1. Config PAD: Set the pin as PINMUX mode, PowerOn, internal Pull-Up.

  2. Config PINMUX: Assign pins for UART3_TX, UART3_RX functions respectively.

driver_uart_init contains the initialization of the UART peripheral.

  1. Enable PCC Clock.

  2. Set the baud rate to 115200, no parity, 1-bit stop bit, 8-bits data length.

  3. Enable UART DMA transmission.

  4. Set UART_TxWaterLevel to 1, the recommended setting is GDMA_MSize .

  5. Set UART_RxWaterLevel to 1, the recommended setting is GDMA_MSize .

  6. Enable UART TX DMA, RX DMA.

  7. Enable UART receive idle interrupt UART_INT_RX_IDLE .

RCC_PeriphClockCmd(APBPeriph_UART3, APBPeriph_UART3_CLOCK, ENABLE);
...
UART_InitStruct.UART_Div            = BaudRate_Table[BAUD_RATE_115200].div;
UART_InitStruct.UART_Ovsr           = BaudRate_Table[BAUD_RATE_115200].ovsr;
UART_InitStruct.UART_OvsrAdj        = BaudRate_Table[BAUD_RATE_115200].ovsr_adj;
...
UART_InitStruct.UART_IdleTime       = UART_RX_IDLE_2BYTE; //idle interrupt wait time
UART_InitStruct.UART_TxWaterLevel   = 1; /* Better to equal: GDMA_MSize */
UART_InitStruct.UART_RxWaterLevel   = 1; /* Better to equal: GDMA_MSize */
UART_InitStruct.TxDmaEn             = ENABLE;
UART_InitStruct.RxDmaEn             = ENABLE;
UART_InitStruct.dmaEn               = UART_DMA_ENABLE;
UART_Init(UART_DEMO, &UART_InitStruct);

UART_INTConfig(UART_DEMO, UART_INT_RX_IDLE | UART_INT_LINE_STS, ENABLE);
...

driver_gdma3_init contains the initialization of GDMA TX peripheral.

  1. Use GDMA channel 3.

  2. The GDMA transfer direction is Memory to Peripheral.

  3. The source address is set to GDMA_Tx_Buf and the destination address is set to (&(UART_DEMO->UART_RBR_THR)).

  4. Enable the GDMA channel 3 total transfer completion interrupt GDMA_INT_Transfer.

GDMA_InitStruct.GDMA_ChannelNum          = UART_TX_GDMA_CHANNEL_NUM;
GDMA_InitStruct.GDMA_DIR                 = GDMA_DIR_MemoryToPeripheral;
...
GDMA_InitStruct.GDMA_SourceAddr          = (uint32_t)GDMA_Tx_Buf;
GDMA_InitStruct.GDMA_DestinationAddr     = (uint32_t)(&(UART_DEMO->UART_RBR_THR));
GDMA_InitStruct.GDMA_DestHandshake       = GDMA_Handshake_UART3_TX;
GDMA_Init(UART_TX_GDMA_CHANNEL, &GDMA_InitStruct);
/* Enable transfer finish interrupt */
GDMA_INTConfig(UART_TX_GDMA_CHANNEL_NUM, GDMA_INT_Transfer, ENABLE);
...

driver_gdma4_init contains the initialization of GDMA RX peripheral.

  1. Use GDMA channel 4.

  2. The GDMA transfer direction is peripheral to memory.

  3. The source address is set to (&(UART_DEMO->UART_RBR_THR)) and the destination address is set to GDMA_Rx_Buf.

  4. Enable the GDMA channel 4 total transfer completion interrupt GDMA_INT_Transfer.

  5. Enable GDMA channel 4 transfer.

GDMA_InitStruct.GDMA_ChannelNum          = UART_RX_GDMA_CHANNEL_NUM;
GDMA_InitStruct.GDMA_DIR                 = GDMA_DIR_PeripheralToMemory;
GDMA_InitStruct.GDMA_BufferSize          = GDMA_BLOCK_SIZE;
...
GDMA_InitStruct.GDMA_SourceAddr          = (uint32_t)(&(UART_DEMO->UART_RBR_THR));
GDMA_InitStruct.GDMA_DestinationAddr     = (uint32_t)GDMA_Rx_Buf;
GDMA_InitStruct.GDMA_SourceHandshake     = GDMA_Handshake_UART3_RX;

GDMA_Init(UART_RX_GDMA_CHANNEL, &GDMA_InitStruct);
/* Enable transfer finish interrupt */
GDMA_INTConfig(UART_RX_GDMA_CHANNEL_NUM, GDMA_INT_Transfer, ENABLE);
...
GDMA_Cmd(UART_RX_GDMA_CHANNEL_NUM, ENABLE);

Functional Implementation

Typing characters on the PC terminal initiates the GDMA transfer from the UART RX FIFO to memory.

Assuming the input data length on the PC terminal is number, the interrupt for different cases is as follows:

  • if number / block_size > 0, it triggers n_time GDMA_INT_Transfer interrupts.

  • if number % block_size > 0 and meets the UART_FLAG_RX_IDLE interrupt condition (If no data is put into RX FIFO within RX idle timeout period after reading all data in the RX FIFO), it triggers n_time UART_INT_RX_IDLE interrupts.

  1. When the UART_FLAG_RX_IDLE interrupt is triggered and the UART interrupt handling function UART3_Handler is entered.

    1. Suspend UART_RX_GDMA_CHANNEL channel transmission.

    2. Disable the UART_INT_RX_IDLE interrupt.

    3. Get the GDMA transfer length (i.e., the length of data received by GDMA) and save the received data into GDMA_Tx_Buf.

    4. Set the receive_flag to indicate that the reception is complete.

    5. Reinitialize the GDMA after resuming and disabling the GDMA transfer for the next data reception.

    6. Enable the UART_INT_RX_IDLE interrupt again after clearing the UART FIFO.

if (UART_GetFlagState(UART3, UART_FLAG_RX_IDLE) == SET)
{

  DBG_DIRECT("UART_FLAG_RX_IDLE");

  /*  Suspend GDMA_Channel2   */
  GDMA_SuspendCmd(UART_RX_GDMA_CHANNEL, ENABLE);
  UART_INTConfig(UART3, UART_INT_RX_IDLE, DISABLE);

  data_len = GDMA_GetTransferLen(UART_RX_GDMA_CHANNEL);
  if (data_len)
  {
      receive_offset += data_len;
      memcpy(GDMA_Tx_Buf + GDMA_BLOCK_SIZE * count, GDMA_Rx_Buf, data_len);
      ...
      GDMA_Cmd(UART_RX_GDMA_CHANNEL_NUM, DISABLE);
      GDMA_SuspendCmd(UART_RX_GDMA_CHANNEL, DISABLE);
      driver_gdma4_init();
      /* GDMA TX flag */
      receiveflg = true;
  }
  ......
  UART_ClearRxFIFO(UART3);
  UART_INTConfig(UART3, UART_INT_RX_IDLE, ENABLE);
}
...

  1. When the GDMA_INT_Transfer interrupt is triggered and the GDMA interrupt handling function GDMA0_Channel4_Handler is entered.

    1. Disable the GDMA RX channel and clear the GDMA channel 3 interrupt flag.

    2. Save the received data into GDMA_Tx_Buf.

    3. Reconfigure the destination address and enable the GDMA RX channel transmission.

GDMA_Cmd(UART_RX_GDMA_CHANNEL_NUM, DISABLE);
GDMA_ClearAllTypeINT(UART_RX_GDMA_CHANNEL_NUM);
...
memcpy(GDMA_Tx_Buf + GDMA_BLOCK_SIZE * (count - 1), GDMA_Rx_Buf, GDMA_BLOCK_SIZE);
...
GDMA_SetDestinationAddress(UART_RX_GDMA_CHANNEL, (uint32_t)GDMA_Rx_Buf);
GDMA_Cmd(UART_RX_GDMA_CHANNEL_NUM, ENABLE);

  1. Once the received_flag is set, execute GDMA_SetBufferSize() to update the GDMA TX Block Size, and execute GDMA_Cmd() to initiate the GDMA transfer from memory to the UART TX FIFO.

    1. Set the GDMA TX block size to the number which is typed on the PC terminal.

    2. Enable the GDMA TX channel again.

while (1)
{
    if (receiveflg)
    {
        GDMA_SetBufferSize(UART_TX_GDMA_CHANNEL, receive_offset);
        GDMA_Cmd(UART_TX_GDMA_CHANNEL_NUM, ENABLE);
        ...
    }
}

  1. When transfer data by GDMA is completed, the GDMA interrupt handling function GDMA0_Channel3_Handler is entered.

    1. Print the completion information of GDMA transport data.

    2. Disable GDMA TX channel transfer and clear the interrupt flag of GDMA_INT_Transfer of GDMA channel 3.

void GDMA0_Channel3_Handler(void)
{
    DBG_DIRECT("UART_TX_GDMA_Handler");
    GDMA_Cmd(UART_TX_GDMA_CHANNEL_NUM, DISABLE);
    GDMA_ClearAllTypeINT(UART_TX_GDMA_CHANNEL_NUM);
}