| /******************************************************************************* | |
| * (c) Copyright 2010-2013 Microsemi SoC Products Group. All rights reserved. | |
| * | |
| * SmartFusion2 MSS HPDMA bare metal software driver public API. | |
| * | |
| * SVN $Revision: 5583 $ | |
| * SVN $Date: 2013-04-04 12:29:18 +0100 (Thu, 04 Apr 2013) $ | |
| */ | |
| /*=========================================================================*//** | |
| @mainpage SmartFusion2 MSS HPDMA Bare Metal Driver. | |
| @section intro_sec Introduction | |
| The SmartFusion2 Microcontroller Subsystem (MSS) includes a High Performance | |
| Direct Memory Access (HPDMA) controller which performs fast data transfer | |
| between any MSS memory connected to the AHB bus matrix and MSS DDR-Bridge | |
| memory. This software driver provides a set of functions for controlling the | |
| MSS HPDMA as part of a bare metal system where no operating system is | |
| available. The driver can be adapted for use as part of an operating system | |
| but the implementation of the adaptation layer between the driver and the | |
| operating system's driver model is outside the scope of the driver. | |
| @section hw_dependencies Hardware Flow Dependencies | |
| The configuration of all features of the MSS HPDMA is covered by this driver. | |
| There are no dependencies on the hardware flow when configuring the MSS HPDMA. | |
| The base address, register addresses and interrupt number assignment for the | |
| MSS HPDMA blocks are defined as constants in the SmartFusion2 CMSIS HAL. You | |
| must ensure that the latest SmartFusion2 CMSIS HAL is included in the project | |
| settings of the software tool chain used to build your project and that it is | |
| generated into your project. | |
| @section theory_op Theory of Operation | |
| The MSS HPDMA driver functions are grouped into the following categories: | |
| - Initialization of the MSS HPDMA driver and hardware | |
| - Data transfer control | |
| - Data transfer status | |
| - Interrupt handling | |
| Initialization | |
| The MSS HPDMA driver is initialized through a call to the MSS_HPDMA_init() | |
| function. The MSS_HPDMA_init() function must be called before any other MSS | |
| HPDMA driver functions can be called. | |
| Data Transfer Control | |
| The driver provides the following functions to control HPDMA data transfers: | |
| - MSS_HPDMA_start() This function starts a HPDMA data transfer. You must | |
| provide the source and destination addresses along | |
| with transfer size and transfer direction. | |
| - MSS_HPDMA_pause() This function pauses the HPDMA transfer that is | |
| currently in progress. | |
| - MSS_HPDMA_resume() This function resumes a HPDMA transfer that was | |
| previously paused. | |
| - MSS_HPDMA_abort() This function aborts the HPDMA transfer that is | |
| currently in progress. | |
| Data Transfer Status | |
| The status of the HPDMA transfer initiated by the last call to | |
| MSS_HPDMA_start() can be retrieved using the MSS_HPDMA_get_transfer_status() | |
| function. | |
| Interrupt Handling | |
| The MSS_HPDMA_set_handler() function is used to register a handler function | |
| that will be called by the driver when the HPDMA transfer completes. You must | |
| create and register a transfer completion handler function to suit your | |
| application. | |
| *//*=========================================================================*/ | |
| #ifndef MSS_HPDMA_H_ | |
| #define MSS_HPDMA_H_ | |
| #ifdef __cplusplus | |
| extern "C" { | |
| #endif | |
| #include "../../CMSIS/m2sxxx.h" | |
| /*-------------------------------------------------------------------------*//** | |
| The HPDMA_TO_DDR constant is used to specify the data transfer direction. It | |
| indicates a transfer from memory connected to the AHB bus matrix to MSS | |
| DDR-Bridge memory. It is used as a parameter by the MSS_HPDMA_start() | |
| function. | |
| */ | |
| #define HPDMA_TO_DDR 0u | |
| /*-------------------------------------------------------------------------*//** | |
| The HPDMA_FROM_DDR constant is used to specify the data transfer direction. It | |
| indicates a transter from MSS DDR-Bridge memory to memory connected to the AHB | |
| bus matrix. It is used as a parameter by the MSS_HPDMA_start() function. | |
| */ | |
| #define HPDMA_FROM_DDR 1u | |
| /*-------------------------------------------------------------------------*//** | |
| The hpdma_status_t type is used to communicate the status of the HPDMA | |
| transfer initiated by the most recent call to HPDMA_start(). It indicates if | |
| a transfer is still currently in progress or the outcome of the latest | |
| transfer. This type is returned by the MSS_HPDMA_get_transfer_status() | |
| function and used as parameter to handler functions registered with the MSS | |
| HPDMA driver by the application. | |
| - HPDMA_IN_PROGRESS - A HPDMA transfer is taking place. | |
| - HPDMA_COMPLETED - The most recent HPDMA transfer initiated by a call | |
| to HPDMA_start() has completed successfully. | |
| - HPDMA_SOURCE_ERROR - The most recent HPDMA transfer failed because of a | |
| problem with the source address passed to | |
| HPDMA_start(). | |
| - HPDMA_DESTINATION_ERROR - The most recent HPDMA transfer failed because of a | |
| problem with the destination address passed to | |
| HPDMA_start(). | |
| - HPDMA_WORD_ALIGN_ERROR - The most recent HPDMA transfer failed because the | |
| transfer size was not word aligned. This means | |
| that the transfer size passed to HPDMA_start() was | |
| not a multiple of four. | |
| */ | |
| typedef enum | |
| { | |
| HPDMA_IN_PROGRESS, | |
| HPDMA_COMPLETED, | |
| HPDMA_SOURCE_ERROR, | |
| HPDMA_DESTINATION_ERROR, | |
| HPDMA_WORD_ALIGN_ERROR | |
| } hpdma_status_t; | |
| /*-------------------------------------------------------------------------*//** | |
| This type definition specifies the prototype of a function that can be | |
| registered with this driver as a HPDMA transfer completion handler function | |
| through a call to MSS_HPDMA_set_handler(). The HPDMA transfer completion | |
| handler will be called by the driver when a HPDMA transfer completes. The MSS | |
| HPDMA driver passes the outcome of the transfer to the completion handler in | |
| the form of a hpdma_status_t parameter indicating if the transfer was | |
| successful or the type of error that occurred during the transfer. | |
| */ | |
| typedef void (*mss_hpdma_handler_t)(hpdma_status_t status); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_init() function initializes the MSS HPDMA driver. It resets the | |
| HPDMA controller. It clears all pending HPDMA interrupts. It initializes | |
| internal data structures used by the MSS HPDMA driver. It disables interrupts | |
| related to HPDMA data transfers. | |
| @param | |
| This function has no parameters. | |
| @return | |
| This function does not return a value. | |
| */ | |
| void | |
| MSS_HPDMA_init | |
| ( | |
| void | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_start() function starts a HPDMA data transfer. Its parameters | |
| specify the source and destination addresses of the transfer as well as its | |
| size and direction. HPDMA data transfers always use DDR memory as the source | |
| or destination of the transfer. The HPDMA controller transfers data in 32-bit | |
| chunks located on 32-bit word aligned address boundaries. | |
| @param src_addr | |
| The parameter src_addr is the address of the data that will be transferred | |
| by the HPDMA. This address must be 32-bit word aligned. The memory location | |
| specified by this address must be located in DDR memory if the transfer_dir | |
| parameter is set to HPDM_FROM_DDR. | |
| @param dest_addr | |
| The parameter dest_addr is the address of the location at which the data | |
| will be transferred. This address must be 32-bit word aligned. The memory | |
| location specified by this address must be located in DDR memory if the | |
| transfer_dir parameter is set to HPDM_TO_DDR. | |
| @param transfer_size | |
| The parameter transfer_size specifies the size in bytes of the requested | |
| transfer. The value of transfer_size must be a multiple of four. | |
| @param transfer_dir | |
| The parameter transfer_dir is used for specifying the data transfer | |
| direction. Allowed values for transfer_dir are as follows: | |
| - HPDMA_TO_DDR | |
| - HPDMA_FROM_DDR | |
| @return | |
| This function does not return a value. | |
| */ | |
| void | |
| MSS_HPDMA_start | |
| ( | |
| uint32_t src_addr, | |
| uint32_t dest_addr, | |
| uint32_t transfer_size, | |
| uint8_t transfer_dir | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_pause() function pauses the current HPDMA transfer. The HPDMA | |
| transfer can be resumed later by calling MSS_HPDMA_resume(). | |
| @param | |
| This function has no parameters. | |
| @return | |
| This function does not return a value. | |
| */ | |
| void | |
| MSS_HPDMA_pause | |
| ( | |
| void | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_pause() function resumes the current HPDMA transfer after it was | |
| previously paused through a call to MSS_HPDMA_pause(). | |
| @param | |
| This function has no parameters. | |
| @return | |
| This function does not return a value. | |
| */ | |
| void | |
| MSS_HPDMA_resume | |
| ( | |
| void | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_abort() function aborts the current HPDMA transfer. | |
| @param | |
| This function has no parameters. | |
| @return | |
| This function does not return a value. | |
| */ | |
| void | |
| MSS_HPDMA_abort | |
| ( | |
| void | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_get_transfer_status() function returns the status of the HPDMA | |
| transfer initiated by a call to MSS_HPDMA_start(). | |
| @param | |
| This function has no parameters. | |
| @return | |
| The MSS_HPDMA_get_transfer_status() function returns the status of the HPDMA | |
| transfer as a value of type hpdma_status_t. The possible return values are: | |
| - HPDMA_IN_PROGRESS | |
| - HPDMA_COMPLETED | |
| - HPDMA_SOURCE_ERROR | |
| - HPDMA_DESTINATION_ERROR | |
| - HPDMA_WORD_ALIGN_ERROR | |
| The example code below demonstrates the use of the | |
| MSS_HPDMA_get_transfer_status() function to detect the completion of the | |
| transfer of the content of eNVM into MDDR memory. | |
| @code | |
| void copy_envm_to_mddr(void) | |
| { | |
| MSS_HPDMA_start(ENVM_BASE_ADDR, | |
| MDDR_BASE_ADDR, | |
| ENVM_SIZE_BYTE, | |
| HPDMA_TO_DDR); | |
| do { | |
| xfer_state = MSS_HPDMA_get_transfer_status(); | |
| } while(HPDMA_IN_PROGRESS == xfer_state); | |
| } | |
| @endcode | |
| */ | |
| hpdma_status_t | |
| MSS_HPDMA_get_transfer_status | |
| ( | |
| void | |
| ); | |
| /*-------------------------------------------------------------------------*//** | |
| The MSS_HPDMA_set_handler() function is used to register a handler function | |
| that will be called by the driver when the HPDMA transfer completes. You must | |
| create and register a transfer completion handler function to suit your | |
| application. The MSS HPDMA driver passes the outcome of the transfer to the | |
| completion handler in the form of a hpdma_status_t parameter indicating if the | |
| transfer was successful or the type of error that occurred during the transfer | |
| if the transfer failed. | |
| @param handler | |
| The handler parameter is a pointer to a handler function provided by your | |
| application. This handler is of type mss_hpdma_handler_t. The handler | |
| function must take one parameter of type hpdma_status_t and must not return | |
| a value. | |
| @return | |
| This function does not return a value. | |
| This example code demonstrates the use of the MSS_HPDMA_set_handler() | |
| function: | |
| @code | |
| void transfer_complete_handler(hpdma_status_t status); | |
| volatile uint32_t g_xfer_in_progress = 0; | |
| void demo_transfer(void) | |
| { | |
| MSS_HPDMA_init(); | |
| MSS_HPDMA_set_handler(transfer_complete_handler); | |
| g_xfer_in_progress = 1; | |
| MSS_HPDMA_start((uint32_t)0x20000000, | |
| (uint32_t)0x00000000, | |
| 20, | |
| HPDMA_FROM_DDR); | |
| while(g_xfer_in_progress) | |
| { | |
| ; | |
| } | |
| } | |
| void transfer_complete_handler(hpdma_status_t status) | |
| { | |
| g_xfer_in_progress = 0; | |
| switch(status) | |
| { | |
| case HPDMA_COMPLETED: | |
| display("Transfer complete"); | |
| break; | |
| case HPDMA_SOURCE_ERROR: | |
| display("Transfer failed: source error"); | |
| break; | |
| case HPDMA_DESTINATION_ERROR: | |
| display("Transfer failed: destination error"); | |
| break; | |
| case HPDMA_WORD_ALIGN_ERROR: | |
| display("Transfer failed: word alignment error"); | |
| break; | |
| default: | |
| display("Unexpected status"); | |
| break; | |
| } | |
| } | |
| @endcode | |
| */ | |
| void | |
| MSS_HPDMA_set_handler | |
| ( | |
| mss_hpdma_handler_t handler | |
| ); | |
| #ifdef __cplusplus | |
| } | |
| #endif | |
| #endif /* MSS_HPDMA_H_ */ |