GDMA

This section introduces the General Direct Memeory Access(GDMA) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GDMA function groups, enums, structures and functions. More...

Overview

This section introduces the General Direct Memeory Access(GDMA) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, GDMA function groups, enums, structures and functions.

Terms and acronyms

Terms	Details
GDMA	General Direct Memeory Access. GDMA is an operation in which data is copied (transported) from one resource to another in a computer system without the involvement of the CPU.

For more information, please refer to GDMA in Wikipedia .|

Supported features

• Support polling and interrupt modes GDMA can copy data from source memory to destination memory, instead of from memory to I/O-device or I/O-device to memory.
  • Polling mode: In the polling mode, the execution status of the GDMA hardware returns valid during the transaction and invalid once the data transaction is finished. The status is retrieved only after the transaction is finished.
  • Interrupt mode: In this mode, the GDMA hardware generates an interrupt once the transaction is complete.
    
    

Software architecture of the GDMA

The software architecture of GDMA driver is shown below.

1. GDMA polling mode architecture :
   Call the function hal_gdma_init() to initialize the GDMA source clock.
   Call the function hal_gdma_start_polling() to transfer data.
   Call the function hal_gdma_stop() to stop the GDMA data transfer.
   Call the function hal_gdma_get_running_status() to get the status, either busy or idle. The application can also de-initialize the GDMA by calling hal_gdma_deinit().
   Polling mode architecture is similar to the polling mode architecture in HAL. See HAL Driver Model for polling mode architecture.
2. GDMA interrupt mode architecture :
   Call the function hal_gdma_init() to initialize the GDMA source clock.
   Call the function hal_gdma_register_callback() to register user's callback, and then call the function hal_gdma_start_interrupt() to transfer data.
   Call the function hal_gdma_stop() to stop GDMA data transfer.
   Call the function hal_gdma_get_running_status() to get the status, either busy or idle.
   Call the function hal_gdma_deinit() to de-initialize GDMA to its original state.
   Interrupt mode architecture is similar to the interrupt mode architecture in HAL. See HAL Driver Model for interrupt mode architecture.

How to use this driver

• Use GDMA with polling mode.
  
  • Step1: Call hal_gdma_init() to initialize GDMA source clock.
  • Step2: Call hal_gdma_start_polling() to transfer data.
  • Step3: Call hal_gdma_get_running_status() to get the status, either busy or idle.
  • Step4: Call hal_gdma_stop() to stop GDMA.
  • Step5: Call hal_gdma_deinit() to de-initialize GDMA.

    Note 1. To use DMA:
           - Memory should be non-cacheable.
           - Memory address should be 4 bytes aligned.
    Note 2. To get non-cacheable memory:
           - Define a global data array and add a memory attribute.
                      ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN, if the array has no initial value.
                      ATTR_RWDATA_IN_NONCACHED_RAM_4BYTE_ALIGN, if the array has an initial value.
             Example:  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  source_address[data_length];
                      ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  destination_address[data_length];
            - Apply memory dynamically with an API void* PvPortMallocNC(size_t xWantedSize).
             Example:  char *source_address= PvPortMallocNC(data_length);
                       char *destination_address= PvPortMallocNC(data_length);
    Note 3. To apply UART/SPI/I2C's in DMA mode, please follow Note 2.
    
       static uint32_t dma_length = 64;
       ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  source_address[64];
       ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  destination_address[64];
       hal_gdma_running_status_t running_status;
    
       if(HAL_GDMA_STATUS_OK != hal_gdma_init(HAL_GDMA_CHANNEL0)) { // Initialize the GDMA source clock.
             // Error handle.
       }
       if(HAL_GDMA_STATUS_OK != hal_gdma_start_polling(HAL_GDMA_CHANNEL0, destination_address, source_address, data_length)) {
             // Error handle.
       }
    
       hal_gdma_get_running_status(HAL_GDMA_CHANNEL0,&running_status);
       //...
       hal_gdma_stop(HAL_GDMA_CHANNEL0); // Stop GDMA.
       hal_gdma_deinit(HAL_GDMA_CHANNEL0);   // De-initialize the GDMA.

• Use GDMA with interrupt mode.
  
  • Step1: Call hal_gdma_init() to initialize GDMA source clock.
  • Step2: call hal_gdma_register_callback() to register a callback function.
  • Step3: Call hal_gdma_start_interrupt() to transfer data.
  • Step4: Call hal_gdma_get_running_status() to get the status, either busy or idle.
  • Step5: Call hal_gdma_stop() to stop GDMA.
  • Step6: Call hal_gdma_deinit() to de-initialize GDMA.
  • Sample code:

    Note 1. To use DMA:
           - Memory should be non-cacheable.
           - Memory address should be 4 bytes aligned.
    Note 2. To get non-cacheable memory:
           - Define a global data array and add a memory attribute.
                      ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN, if the array has no initial value.
                      ATTR_RWDATA_IN_NONCACHED_RAM_4BYTE_ALIGN, if the array has an initial value.
             Example:  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  source_address[data_length];
                      ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  destination_address[data_length];
            - Apply memory dynamically with an API void* PvPortMallocNC(size_t xWantedSize).
             Example:  char *source_address= PvPortMallocNC(data_length);
                       char *destination_address= PvPortMallocNC(data_length);
    Note 3. To apply UART/SPI/I2C's in DMA mode, please follow Note 2.
    
       static uint32_t dma_length = 64;
       ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  source_address[64];
       ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN static uint8_t  destination_address[64];
       uint32_t user_data;
       user_data = 1;//this value will be passed to the application once the callback function is called
       hal_gdma_running_status_t running_status;
    
       if(HAL_GDMA_STATUS_OK != hal_gdma_init(HAL_GDMA_CHANNEL0)) { // Initialize the GDMA source clock.
             // Error handle.
       }
       if(HAL_GDMA_STATUS_OK != hal_gdma_register_callback(HAL_GDMA_CHANNEL0, callback,(void *) &user_data) {  // Register user's callback.
             // Error handle.
       }
       if(HAL_GDMA_STATUS_OK != hal_gdma_start_interrupt(HAL_GDMA_CHANNEL0,  destination_address, source_address, data_length)) { //Enable GDMA to start transferring data.
             // Error handle.
       }
       //...
       hal_gdma_get_running_status(HAL_GDMA_CHANNEL0, &running_status);
       //...
       hal_gdma_stop(HAL_GDMA_CHANNEL0); // Stop the GDMA.
       hal_gdma_deinit(HAL_GDMA_CHANNEL0);   //De-initialize the GDMA.

    // Callback function. This function should be registered with hal_gdma_register_callback().
      static void gdma_callback(hal_gdma_event_t event, void  *user_data)
      {  //gdma_callback will be triggered when gdma transfers finished.
         //add your code here, such as:
    
            hal_gdma_stop(HAL_GDMA_CHANNEL0);
            hal_gdma_deinit(HAL_GDMA_CHANNEL0);
            printf("\r\n ---gdma_example finished!!!---\r\n");
      }

Macros
#define	HAL_GDMA_WRAP_FLASH_ADDRESS_OFFSET   (28)
	the gdma access flash address should be 0x3000000 instead of 0x1000000. More...
#define	HAL_GDMA_WRAP_FLASH_ADDRESS_HIGH_BYTE_MASK   (0xfUL<<HAL_GDMA_WRAP_FLASH_ADDRESS_OFFSET)
	Description gdma wrap flash address high byte mask.
#define	HAL_GDMA_WRAP_FLASH_ADDRESS_MASK   (0x1UL<<HAL_GDMA_WRAP_FLASH_ADDRESS_OFFSET)
	Description gdma wrap flash address mask.
#define	HAL_GDMA_WRAP_FLASH_VIRTUAL_ADDRESS_MASK   (0x3UL<<HAL_GDMA_WRAP_FLASH_ADDRESS_OFFSET)
	Description gdma wrap flash virtual address mask.

Functions
hal_gdma_status_t	hal_gdma_init (hal_gdma_channel_t channel)
	This function initializes the GDMA based configuration. More...
hal_gdma_status_t	hal_gdma_deinit (hal_gdma_channel_t channel)
	This function resets GDMA registers and state. More...
hal_gdma_status_t	hal_gdma_start_polling (hal_gdma_channel_t channel, uint32_t destination_address, uint32_t source_address, uint32_t data_length)
	This function enables the GDMA to operate in a polling mode. More...
hal_gdma_status_t	hal_gdma_start_interrupt (hal_gdma_channel_t channel, uint32_t destination_address, uint32_t source_address, uint32_t data_length)
	This function enables the GDMA to operate in an interrupt mode, the application can register a callback when a GDMA interrupt occurs. More...
hal_gdma_status_t	hal_gdma_register_callback (hal_gdma_channel_t channel, hal_gdma_callback_t callback, void *user_data)
	This function registers a GDMA callback. More...
hal_gdma_status_t	hal_gdma_get_running_status (hal_gdma_channel_t channel, hal_gdma_running_status_t *running_status)
	This function gets the current state of the GDMA. More...
hal_gdma_status_t	hal_gdma_stop (hal_gdma_channel_t channel)
	This function stops the GDMA operation. More...

Modules
	Enum
	Typedef

Macro Definition Documentation

#define HAL_GDMA_WRAP_FLASH_ADDRESS_OFFSET   (28)

the gdma access flash address should be 0x3000000 instead of 0x1000000.

Description gdma wrap flash address offset

Function Documentation

hal_gdma_status_t hal_gdma_deinit

(

hal_gdma_channel_t

channel

)

This function resets GDMA registers and state.

Parameters

[in]

channel

GDMA master name definition in enum hal_gdma_channel_t.

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_init()

hal_gdma_status_t hal_gdma_get_running_status	(	hal_gdma_channel_t	channel,
		hal_gdma_running_status_t *	running_status
	)

This function gets the current state of the GDMA.

Parameters

[in]	channel	GDMA master name definition in enum hal_gdma_channel_t.
[out]	running_status	is the current running status. HAL_GDMA_BUSY, the GDMA is busy. HAL_GDMA_IDLE, the GDMA is idle and ready to transfer data.

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_start_interrupt()

hal_gdma_status_t hal_gdma_init

(

hal_gdma_channel_t

channel

)

This function initializes the GDMA based configuration.

Parameters

[in]

channel

GDMA definition in enum hal_gdma_channel_t

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_deinit()

hal_gdma_status_t hal_gdma_register_callback	(	hal_gdma_channel_t	channel,
		hal_gdma_callback_t	callback,
		void *	user_data
	)

This function registers a GDMA callback.

Parameters

[in]	channel	GDMA master name definition in enum hal_gdma_channel_t.
[in]	callback	is the callback function given by the application, that is called at the GDMA interrupt service routine.
[in]	user_data	is a user input provided by the application and is passed to the application once the callback function is called. See the last parameter of hal_gdma_callback_t.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_start_interrupt()

hal_gdma_status_t hal_gdma_start_interrupt	(	hal_gdma_channel_t	channel,
		uint32_t	destination_address,
		uint32_t	source_address,
		uint32_t	data_length
	)

This function enables the GDMA to operate in an interrupt mode, the application can register a callback when a GDMA interrupt occurs.

Parameters

[in]	channel	GDMA master name definition in enum hal_gdma_channel_t.
[in]	destination_address	is the address to copy the source data into.
[in]	source_address	is the address where application's source data is stored.
[in]	data_length	is the data length used in the transaction.

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_start_polling()

hal_gdma_status_t hal_gdma_start_polling	(	hal_gdma_channel_t	channel,
		uint32_t	destination_address,
		uint32_t	source_address,
		uint32_t	data_length
	)

This function enables the GDMA to operate in a polling mode.

Parameters

[in]	channel	GDMA master name definition in enum hal_gdma_channel_t.
[in]	destination_address	is the address to copy the source data into.
[in]	source_address	is the address where application's source data is stored.
[in]	data_length	is the data length used in the transaction.

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_start_interrupt()

hal_gdma_status_t hal_gdma_stop

(

hal_gdma_channel_t

channel

)

This function stops the GDMA operation.

Parameters

[in]

channel

GDMA master name definition in enum hal_gdma_channel_t.

Returns

To indicate whether this function call is successful or not. HAL_GDMA_STATUS_OK, the operation completed successfully.

Example

Sample code, please refer to How to use this driver

See also

hal_gdma_start_polling(), hal_gdma_start_interrupt()