git.sur5r.net Git - freertos/blob

   1 /*******************************************************************************\r
   2  * (c) Copyright 2010-2013 Microsemi SoC Products Group.  All rights reserved.\r
   3  * \r
   4  *  SmartFusion2 MSS HPDMA bare metal software driver public API.\r
   5  *\r
   6  * SVN $Revision: 5583 $\r
   7  * SVN $Date: 2013-04-04 12:29:18 +0100 (Thu, 04 Apr 2013) $\r
   8  */\r
   9 \r
  10 /*=========================================================================*//**\r
  11   @mainpage SmartFusion2 MSS HPDMA Bare Metal Driver.\r
  12 \r
  13   @section intro_sec Introduction\r
  14   The SmartFusion2 Microcontroller Subsystem (MSS) includes a High Performance\r
  15   Direct Memory Access (HPDMA) controller which performs fast data transfer\r
  16   between any MSS memory connected to the AHB bus matrix and MSS DDR-Bridge\r
  17   memory. This software driver provides a set of functions for controlling the\r
  18   MSS HPDMA as part of a bare metal system where no operating system is\r
  19   available. The driver can be adapted for use as part of an operating system\r
  20   but the implementation of the adaptation layer between the driver and the\r
  21   operating system's driver model is outside the scope of the driver.\r
  22   \r
  23   @section hw_dependencies Hardware Flow Dependencies\r
  24   The configuration of all features of the MSS HPDMA is covered by this driver.\r
  25   There are no dependencies on the hardware flow when configuring the MSS HPDMA.\r
  26   The base address, register addresses and interrupt number assignment for the\r
  27   MSS HPDMA blocks are defined as constants in the SmartFusion2 CMSIS HAL. You\r
  28   must ensure that the latest SmartFusion2 CMSIS HAL is included in the project\r
  29   settings of the software tool chain used to build your project and that it is\r
  30   generated into your project.\r
  31   \r
  32   @section theory_op Theory of Operation\r
  33   The MSS HPDMA driver functions are grouped into the following categories:\r
  34     - Initialization of the MSS HPDMA driver and hardware\r
  35     - Data transfer control \r
  36     - Data transfer status\r
  37     - Interrupt handling\r
  38     \r
  39   Initialization\r
  40   The MSS HPDMA driver is initialized through a call to the MSS_HPDMA_init()\r
  41   function. The MSS_HPDMA_init() function must be called before any other MSS\r
  42   HPDMA driver functions can be called.\r
  43   \r
  44   Data Transfer Control\r
  45   The driver provides the following functions to control HPDMA data transfers:\r
  46     - MSS_HPDMA_start()  \96 This function starts a HPDMA data transfer. You must\r
  47                            provide the source and destination addresses along\r
  48                            with transfer size and transfer direction.\r
  49     - MSS_HPDMA_pause()  \96 This function pauses the HPDMA transfer that is\r
  50                            currently in progress.\r
  51     - MSS_HPDMA_resume() \96 This function resumes a HPDMA transfer that was\r
  52                            previously paused.\r
  53     - MSS_HPDMA_abort()  \96 This function aborts the HPDMA transfer that is\r
  54                            currently in progress.\r
  55     \r
  56   Data Transfer Status\r
  57   The status of the HPDMA transfer initiated by the last call to\r
  58   MSS_HPDMA_start() can be retrieved using the MSS_HPDMA_get_transfer_status()\r
  59   function.\r
  60   \r
  61   Interrupt Handling\r
  62   The MSS_HPDMA_set_handler() function is used to register a handler function\r
  63   that will be called by the driver when the HPDMA transfer completes. You must\r
  64   create and register a transfer completion handler function to suit your\r
  65   application.\r
  66 \r
  67  *//*=========================================================================*/\r
  68 #ifndef MSS_HPDMA_H_\r
  69 #define MSS_HPDMA_H_\r
  70 \r
  71 #ifdef __cplusplus\r
  72 extern "C" {\r
  73 #endif \r
  74 \r
  75 #include "../../CMSIS/m2sxxx.h"\r
  76 \r
  77 /*-------------------------------------------------------------------------*//**\r
  78   The HPDMA_TO_DDR constant is used to specify the data transfer direction. It\r
  79   indicates a transfer from memory connected to the AHB bus matrix to MSS\r
  80   DDR-Bridge memory. It is used as a parameter by the MSS_HPDMA_start()\r
  81   function.\r
  82  */\r
  83 #define HPDMA_TO_DDR        0u\r
  84 \r
  85 /*-------------------------------------------------------------------------*//**\r
  86   The HPDMA_FROM_DDR constant is used to specify the data transfer direction. It\r
  87   indicates a transter from MSS DDR-Bridge memory to memory connected to the AHB\r
  88   bus matrix. It is used as a parameter by the MSS_HPDMA_start() function.\r
  89  */\r
  90 #define HPDMA_FROM_DDR      1u\r
  91 \r
  92 /*-------------------------------------------------------------------------*//**\r
  93   The hpdma_status_t type is used to communicate the status of the HPDMA\r
  94   transfer initiated by the most recent call to HPDMA_start(). It indicates if\r
  95   a transfer is still currently in progress or the outcome of the latest\r
  96   transfer. This type is returned by the MSS_HPDMA_get_transfer_status()\r
  97   function and used as parameter to handler functions registered with the MSS\r
  98   HPDMA driver by the application.\r
  99   \r
 100   - HPDMA_IN_PROGRESS       - A HPDMA transfer is taking place.\r
 101   - HPDMA_COMPLETED         - The most recent HPDMA transfer initiated by a call\r
 102                               to HPDMA_start() has completed successfully.\r
 103   - HPDMA_SOURCE_ERROR      - The most recent HPDMA transfer failed because of a\r
 104                               problem with the source address passed to\r
 105                               HPDMA_start().\r
 106   - HPDMA_DESTINATION_ERROR - The most recent HPDMA transfer failed because of a\r
 107                               problem with the destination address passed to\r
 108                               HPDMA_start().\r
 109   - HPDMA_WORD_ALIGN_ERROR  - The most recent HPDMA transfer failed because the\r
 110                               transfer size was not word aligned. This means\r
 111                               that the transfer size passed to HPDMA_start() was\r
 112                               not a multiple of four.\r
 113  */\r
 114 typedef enum\r
 115 {\r
 116     HPDMA_IN_PROGRESS,\r
 117     HPDMA_COMPLETED,\r
 118     HPDMA_SOURCE_ERROR,\r
 119     HPDMA_DESTINATION_ERROR,\r
 120     HPDMA_WORD_ALIGN_ERROR\r
 121 } hpdma_status_t;\r
 122 \r
 123 /*-------------------------------------------------------------------------*//**\r
 124   This type definition specifies the prototype of a function that can be\r
 125   registered with this driver as a HPDMA transfer completion handler function\r
 126   through a call to MSS_HPDMA_set_handler(). The HPDMA transfer completion\r
 127   handler will be called by the driver when a HPDMA transfer completes. The MSS\r
 128   HPDMA driver passes the outcome of the transfer to the completion handler in\r
 129   the form of a hpdma_status_t parameter indicating if the transfer was\r
 130   successful or the type of error that occurred during the transfer.\r
 131  */\r
 132 typedef void (*mss_hpdma_handler_t)(hpdma_status_t status);\r
 133 \r
 134 /*-------------------------------------------------------------------------*//**\r
 135   The MSS_HPDMA_init() function initializes the MSS HPDMA driver. It resets the\r
 136   HPDMA controller. It clears all pending HPDMA interrupts. It initializes\r
 137   internal data structures used by the MSS HPDMA driver. It disables interrupts\r
 138   related to HPDMA data transfers.\r
 139 \r
 140   @param\r
 141     This function has no parameters.\r
 142 \r
 143   @return\r
 144     This function does not return a value.\r
 145  */\r
 146 void\r
 147 MSS_HPDMA_init\r
 148 (\r
 149     void\r
 150 );\r
 151 \r
 152 /*-------------------------------------------------------------------------*//**\r
 153   The MSS_HPDMA_start() function starts a HPDMA data transfer. Its parameters\r
 154   specify the source and destination addresses of the transfer as well as its\r
 155   size and direction. HPDMA data transfers always use DDR memory as the source\r
 156   or destination of the transfer. The HPDMA controller transfers data in 32-bit\r
 157   chunks located on 32-bit word aligned address boundaries.\r
 158 \r
 159   @param src_addr\r
 160     The parameter src_addr is the address of the data that will be transferred\r
 161     by the HPDMA. This address must be 32-bit word aligned. The memory location\r
 162     specified by this address must be located in DDR memory if the transfer_dir\r
 163     parameter is set to HPDM_FROM_DDR.\r
 164 \r
 165   @param dest_addr\r
 166     The parameter dest_addr is the address of the location at which the data\r
 167     will be transferred. This address must be 32-bit word aligned. The memory\r
 168     location specified by this address must be located in DDR memory if the\r
 169     transfer_dir parameter is set to HPDM_TO_DDR.\r
 170 \r
 171   @param transfer_size\r
 172     The parameter transfer_size specifies the size in bytes of the requested\r
 173     transfer. The value of transfer_size must be a multiple of four.\r
 174 \r
 175   @param transfer_dir\r
 176      The parameter transfer_dir is used for specifying the data transfer\r
 177      direction. Allowed values for transfer_dir are as follows:\r
 178         - HPDMA_TO_DDR\r
 179         - HPDMA_FROM_DDR\r
 180 \r
 181   @return\r
 182     This function does not return a value.\r
 183  */\r
 184 void\r
 185 MSS_HPDMA_start\r
 186 (\r
 187     uint32_t src_addr,\r
 188     uint32_t dest_addr,\r
 189     uint32_t transfer_size,\r
 190     uint8_t transfer_dir\r
 191 );\r
 192 \r
 193 /*-------------------------------------------------------------------------*//**\r
 194   The MSS_HPDMA_pause() function pauses the current HPDMA transfer. The HPDMA\r
 195   transfer can be resumed later  by calling MSS_HPDMA_resume().\r
 196 \r
 197   @param\r
 198     This function has no parameters.\r
 199     \r
 200   @return\r
 201     This function does not return a value.\r
 202  */\r
 203 void\r
 204 MSS_HPDMA_pause\r
 205 (\r
 206     void\r
 207 );\r
 208 \r
 209 /*-------------------------------------------------------------------------*//**\r
 210   The MSS_HPDMA_pause() function resumes the current HPDMA transfer after it was\r
 211   previously paused through a call to MSS_HPDMA_pause().\r
 212 \r
 213   @param\r
 214     This function has no parameters.\r
 215     \r
 216   @return\r
 217     This function does not return a value.\r
 218  */\r
 219 void\r
 220 MSS_HPDMA_resume\r
 221 (\r
 222     void\r
 223 );\r
 224 \r
 225 /*-------------------------------------------------------------------------*//**\r
 226   The MSS_HPDMA_abort() function aborts the current HPDMA transfer.\r
 227 \r
 228   @param\r
 229     This function has no parameters.\r
 230     \r
 231   @return\r
 232     This function does not return a value.\r
 233  */\r
 234 void\r
 235 MSS_HPDMA_abort\r
 236 (\r
 237     void\r
 238 );\r
 239 \r
 240 /*-------------------------------------------------------------------------*//**\r
 241  The MSS_HPDMA_get_transfer_status() function returns the status of the HPDMA\r
 242  transfer initiated by a call to MSS_HPDMA_start(). \r
 243 \r
 244   @param\r
 245     This function has no parameters.\r
 246     \r
 247   @return\r
 248     The MSS_HPDMA_get_transfer_status() function returns the status of the HPDMA\r
 249     transfer as a value of  type hpdma_status_t. The possible return values are:\r
 250         - HPDMA_IN_PROGRESS\r
 251         - HPDMA_COMPLETED\r
 252         - HPDMA_SOURCE_ERROR\r
 253         - HPDMA_DESTINATION_ERROR\r
 254         - HPDMA_WORD_ALIGN_ERROR\r
 255       \r
 256   The example code below demonstrates the use of the\r
 257   MSS_HPDMA_get_transfer_status() function to detect the completion of the\r
 258   transfer of the content of eNVM into MDDR memory.\r
 259   @code\r
 260     void copy_envm_to_mddr(void)\r
 261     {\r
 262         MSS_HPDMA_start(ENVM_BASE_ADDR,\r
 263                         MDDR_BASE_ADDR,\r
 264                         ENVM_SIZE_BYTE,\r
 265                         HPDMA_TO_DDR);\r
 266         \r
 267         do {\r
 268             xfer_state = MSS_HPDMA_get_transfer_status();\r
 269         } while(HPDMA_IN_PROGRESS == xfer_state);\r
 270     }\r
 271   @endcode\r
 272  */\r
 273 hpdma_status_t\r
 274 MSS_HPDMA_get_transfer_status\r
 275 (\r
 276     void\r
 277 );\r
 278 \r
 279 /*-------------------------------------------------------------------------*//**\r
 280   The MSS_HPDMA_set_handler() function is used to register a handler function\r
 281   that will be called by the driver when the HPDMA transfer completes. You must\r
 282   create and register a transfer completion handler function to suit your\r
 283   application. The MSS HPDMA driver passes the outcome of the transfer to the\r
 284   completion handler in the form of a hpdma_status_t parameter indicating if the\r
 285   transfer was successful or the type of error that occurred during the transfer\r
 286   if the transfer failed.\r
 287 \r
 288   @param handler\r
 289     The handler parameter is a pointer to a handler function provided by your\r
 290     application. This handler is of type mss_hpdma_handler_t. The handler\r
 291     function must take one parameter of type hpdma_status_t and must not return\r
 292     a value.\r
 293 \r
 294   @return\r
 295     This function does not return a value.\r
 296     \r
 297   This example code demonstrates the use of the MSS_HPDMA_set_handler()\r
 298   function:\r
 299   @code\r
 300     void transfer_complete_handler(hpdma_status_t status);\r
 301 \r
 302     volatile uint32_t g_xfer_in_progress = 0;\r
 303 \r
 304     void demo_transfer(void)\r
 305     {\r
 306         MSS_HPDMA_init();\r
 307         \r
 308         MSS_HPDMA_set_handler(transfer_complete_handler);\r
 309         \r
 310         g_xfer_in_progress = 1;\r
 311         MSS_HPDMA_start((uint32_t)0x20000000,\r
 312                         (uint32_t)0x00000000,\r
 313                         20,\r
 314                         HPDMA_FROM_DDR);\r
 315         \r
 316         while(g_xfer_in_progress)\r
 317         {\r
 318             ;\r
 319         }\r
 320     }\r
 321 \r
 322     void transfer_complete_handler(hpdma_status_t status)\r
 323     {\r
 324         g_xfer_in_progress = 0;\r
 325         \r
 326         switch(status)\r
 327         {\r
 328             case HPDMA_COMPLETED:\r
 329                 display("Transfer complete");\r
 330             break;\r
 331 \r
 332             case HPDMA_SOURCE_ERROR:\r
 333                 display("Transfer failed: source error");\r
 334             break;\r
 335 \r
 336             case HPDMA_DESTINATION_ERROR:\r
 337                 display("Transfer failed: destination error");\r
 338             break;\r
 339 \r
 340             case HPDMA_WORD_ALIGN_ERROR:\r
 341                 display("Transfer failed: word alignment error");\r
 342             break;\r
 343 \r
 344             default:\r
 345                 display("Unexpected status");\r
 346             break;\r
 347         }\r
 348     }\r
 349   @endcode\r
 350  */\r
 351 void\r
 352 MSS_HPDMA_set_handler\r
 353 (\r
 354     mss_hpdma_handler_t handler\r
 355 );\r
 356 \r
 357 #ifdef __cplusplus\r
 358 }\r
 359 #endif\r
 360 \r
 361 #endif /* MSS_HPDMA_H_ */\r