MT7687 API Reference  LinkIt SDK v4
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

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

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]channelGDMA 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]channelGDMA master name definition in enum hal_gdma_channel_t.
[out]running_statusis 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]channelGDMA 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]channelGDMA master name definition in enum hal_gdma_channel_t.
[in]callbackis the callback function given by the application, that is called at the GDMA interrupt service routine.
[in]user_datais 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]channelGDMA master name definition in enum hal_gdma_channel_t.
[in]destination_addressis the address to copy the source data into.
[in]source_addressis the address where application's source data is stored.
[in]data_lengthis 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]channelGDMA master name definition in enum hal_gdma_channel_t.
[in]destination_addressis the address to copy the source data into.
[in]source_addressis the address where application's source data is stored.
[in]data_lengthis 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]channelGDMA 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()