git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Cyclone_V_SoC_DK/Altera_Code/HardwareLibrary/include/alt_globaltmr.h

   1 /*! \file\r
   2  *  Altera - Module Description\r
   3  */\r
   4 \r
   5 /******************************************************************************\r
   6 *\r
   7 * Copyright 2013 Altera Corporation. All Rights Reserved.\r
   8 *\r
   9 * Redistribution and use in source and binary forms, with or without\r
  10 * modification, are permitted provided that the following conditions are met:\r
  11 *\r
  12 * 1. Redistributions of source code must retain the above copyright notice,\r
  13 * this list of conditions and the following disclaimer.\r
  14 *\r
  15 * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  16 * this list of conditions and the following disclaimer in the documentation\r
  17 * and/or other materials provided with the distribution.\r
  18 *\r
  19 * 3. The name of the author may not be used to endorse or promote products\r
  20 * derived from this software without specific prior written permission.\r
  21 *\r
  22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR\r
  23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  24 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO\r
  25 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,\r
  26 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT\r
  27 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\r
  28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\r
  29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING\r
  30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY\r
  31 * OF SUCH DAMAGE.\r
  32 *\r
  33 ******************************************************************************/\r
  34 \r
  35 #ifndef __ALT_GBLTMR_H__\r
  36 #define __ALT_GBLTMR_H__\r
  37 \r
  38 #include <stdint.h>\r
  39 #include <stdbool.h>\r
  40 #include "hwlib.h"\r
  41 \r
  42 #ifdef __cplusplus\r
  43 extern "C"\r
  44 {\r
  45 #endif  /* __cplusplus */\r
  46 \r
  47 \r
  48 /******************************************************************************/\r
  49 /*! \addtogroup GBLTMR_MGR The Global Timer Manager API\r
  50  *\r
  51  * This functional group handles setting and reading various parameters of the\r
  52  * global 64-bit incrementing counter. There is one 64-bit continuously\r
  53  * incrementing counter for all CPU cores and it is clocked by PERIPHCLK.\r
  54  * This section manages the comparator value, compare enable,\r
  55  * auto-increment value, auto-increment enable, and interrupt enable for the\r
  56  * CPU that this code is running on (referenced as \b CPU_GLOBAL_TMR).\r
  57  * @{\r
  58  */\r
  59 /******************************************************************************/\r
  60 /*! Uninitialize the Global timer module\r
  61  *\r
  62  */\r
  63 ALT_STATUS_CODE alt_globaltmr_uninit(void);\r
  64 \r
  65 /******************************************************************************/\r
  66 /*! Initialize the Global timer module\r
  67  *\r
  68  */\r
  69 ALT_STATUS_CODE alt_globaltmr_init(void);\r
  70 \r
  71 /******************************************************************************/\r
  72 /*!\r
  73  * Stops the global timer counter compare function for this CPU and disables\r
  74  * its interrupt. It does\r
  75  * not stop the global timer itself. This function is identical to calling\r
  76  * \b alt_gpt_tmr_stop() with a tmr_id of \b CPU_GLOBAL_TMR.\r
  77  *\r
  78  *\r
  79  *\r
  80  * \retval      ALT_E_SUCCESS   The operation was successful.\r
  81  * \retval      ALT_E_ERROR     The operation failed.\r
  82  */\r
  83 ALT_STATUS_CODE alt_globaltmr_stop(void);\r
  84 \r
  85 /******************************************************************************/\r
  86 /*!\r
  87  * Starts the global timer compare function for this CPU, enables its interrupt\r
  88  * function and, if free-running mode is selected also enables its\r
  89  * auto-increment function. If the global timer is not yet running, it starts\r
  90  * the timer. This function is identical to calling \b alt_gpt_tmr_start()\r
  91  * with a tmr_id of \b CPU_GLOBAL_TMR.\r
  92  *\r
  93  *\r
  94  *\r
  95  * \retval      ALT_E_SUCCESS   The operation was successful.\r
  96  * \retval      ALT_E_ERROR     The operation failed.\r
  97  */\r
  98 ALT_STATUS_CODE alt_globaltmr_start(void);\r
  99 \r
 100 /******************************************************************************/\r
 101 /*!\r
 102  * Returns the current counter value of the 64-bit global timer.\r
 103  *\r
 104  *\r
 105  * \param       highword\r
 106  *              Location used to return the most significant 32-bit word of\r
 107  *              the current global timer count.\r
 108  * \param       lowword\r
 109  *              Location used to return the least significant 32-bit word\r
 110  *              of the current global timer count.\r
 111  *\r
 112  *\r
 113  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 114  * \retval      ALT_E_ERROR     The operation failed.\r
 115  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 116  */\r
 117 ALT_STATUS_CODE alt_globaltmr_get(uint32_t* highword, uint32_t* lowword);\r
 118 \r
 119 /******************************************************************************/\r
 120 /*!\r
 121  * Returns the current counter value of the 64-bit global timer. This function\r
 122  * is identical to alt_globaltmr_get() except that the value is returned as a\r
 123  * 64-bit unsigned integer rather than as two 32-bit words.\r
 124  *\r
 125  *\r
 126  *\r
 127  * \retval      uint64_t\r
 128  *              The current value of the 64-bit counter.\r
 129  */\r
 130 uint64_t alt_globaltmr_get64(void);\r
 131 \r
 132 /******************************************************************************/\r
 133 /*!\r
 134  * Returns the 32 low-order bits of the global timer. This\r
 135  * is identical to calling \b alt_gpt_counter_get() with a tmr_id equal\r
 136  * to \b CPU_GLOBAL_TMR. Use alt_globaltmr_get()  or alt_globaltmr_get64() to\r
 137  * obtain the full 64-bit timer value.\r
 138  *\r
 139  *\r
 140  *\r
 141  * \retval      uint32_t The current 32-bit counter value.\r
 142  */\r
 143 uint32_t alt_globaltmr_counter_get_low32(void);\r
 144 \r
 145 /******************************************************************************/\r
 146 /*!\r
 147  * Returns the 32 higher-order bits of the global timer. Use alt_globaltmr_get()\r
 148  * or alt_globaltmr_get64() to obtain the full 64-bit timer value.\r
 149  *\r
 150  *\r
 151  *\r
 152  * \retval      uint32_t The current 32-bit counter value.\r
 153  */\r
 154 uint32_t alt_globaltmr_counter_get_hi32(void);\r
 155 \r
 156 /******************************************************************************/\r
 157 /*!\r
 158  * Sets the value of the 64-bit global timer comparator for this CPU. The\r
 159  * global timer increments its count and when it reaches this value or above,\r
 160  * it triggers the following actions. If the interrupt is enabled, it forwards\r
 161  * an interrupt request to the core. If free-run mode is selected, it adds the\r
 162  * auto-increment value to the value of the global counter and the resulting\r
 163  * sum is saved as the new comparator value.\r
 164  *\r
 165  *\r
 166  * \param       highword\r
 167  *              The 32 MSBits of the new comparator value.\r
 168  * \param       loword\r
 169  *              The 32 LSBits of the new comparator value.\r
 170  *\r
 171  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 172  * \retval      ALT_E_ERROR     The operation failed.\r
 173  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 174  */\r
 175 ALT_STATUS_CODE alt_globaltmr_comp_set(uint32_t highword, uint32_t loword);\r
 176 \r
 177 /******************************************************************************/\r
 178 /*!\r
 179  * Sets the value of the 64-bit global timer comparator for this CPU. The\r
 180  * global timer increments its count and when it reaches this value or above,\r
 181  * it triggers the following actions. If the interrupt is enabled, it forwards\r
 182  * an interrupt request to the core. If free-run mode is selected, it adds the\r
 183  * auto-increment value to the value of the global counter and the resulting\r
 184  * sum is saved as the new comparator value.\r
 185  *\r
 186  *\r
 187  * \param       compval\r
 188  *              The new comparator value to set.\r
 189  *\r
 190  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 191  * \retval      ALT_E_ERROR     The operation failed.\r
 192  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 193  */\r
 194 ALT_STATUS_CODE alt_globaltmr_comp_set64(uint64_t compval);\r
 195 \r
 196 /******************************************************************************/\r
 197 /*!\r
 198  * Returns the current 64-bit global timer comparator value  for this CPU. The\r
 199  * global timer increments its count and when it reaches this value or above,\r
 200  * it triggers the following actions. If the interrupt is enabled, it forwards\r
 201  * an interrupt request to the core. If free-run mode is selected, it adds the\r
 202  * auto-increment value to the value of the global counter and the resulting\r
 203  * sum is saved as the new comparator value. This value will increase by the\r
 204  * auto-increment value each time the global timer reaches the comparator\r
 205  * value.\r
 206  *\r
 207  *\r
 208  * \param       highword\r
 209  *              Pointer to location to store the 32 MSBits of the comparator value.\r
 210  * \param       lowword\r
 211  *              Pointer to location to store the 32 LSBits of the comparator value.\r
 212  *\r
 213  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 214  * \retval      ALT_E_ERROR     The operation failed.\r
 215  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 216  */\r
 217 ALT_STATUS_CODE alt_globaltmr_comp_get(uint32_t *highword, uint32_t *lowword);\r
 218 \r
 219 /******************************************************************************/\r
 220 /*!\r
 221  * Returns the current 64-bit global timer comparator value  for this CPU. The\r
 222  * global timer increments its count and when it reaches this value or above,\r
 223  * it triggers the following actions. If the interrupt is enabled, it forwards\r
 224  * an interrupt request to the core. If free-run mode is selected, it adds the\r
 225  * auto-increment value to the value of the global counter and the resulting\r
 226  * sum is saved as the new comparator value. This value will increase by the\r
 227  * auto-increment value each time the global timer reaches the comparator\r
 228  * value. This function is identical to alt_globaltmr_comp_get() except that the\r
 229  * value is returned in a 64-bit unsigned integer rather than as two 32-bit\r
 230  * words.\r
 231  *\r
 232  *\r
 233  * \retval      uint64_t\r
 234  *              The 64-bit value of the global timer comparator.\r
 235  */\r
 236 uint64_t alt_globaltmr_comp_get64(void);\r
 237 \r
 238 \r
 239 /******************************************************************************/\r
 240 /*!\r
 241  * Enables the comparison function of the global timer for this CPU.\r
 242  *\r
 243  *\r
 244  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 245  * \retval      ALT_E_ERROR     The operation failed.\r
 246  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 247  */\r
 248 ALT_STATUS_CODE alt_globaltmr_comp_mode_start(void);\r
 249 \r
 250 /******************************************************************************/\r
 251 /*!\r
 252  * Disables the comparison function of the global timer for this CPU.\r
 253  *\r
 254  *\r
 255  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 256  * \retval      ALT_E_ERROR     The operation failed.\r
 257  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 258  */\r
 259 ALT_STATUS_CODE alt_globaltmr_comp_mode_stop(void);\r
 260 \r
 261 /******************************************************************************/\r
 262 /*!\r
 263  * Returns the comparison mode selection of the global\r
 264  * timer for this CPU.\r
 265  *\r
 266  *\r
 267  * \retval      FALSE           Comparison mode is not enabled.\r
 268  * \retval      TRUE            Comparison mode is enabled.\r
 269  */\r
 270 bool alt_globaltmr_is_comp_mode(void);\r
 271 \r
 272 \r
 273 /******************************************************************************/\r
 274 /*!\r
 275  * Returns the clock prescaler value of the global timer.\r
 276  *\r
 277  *\r
 278  * \retval      uint32_t    The prescaler value. Valid range is 0-255.\r
 279  *                          Actual clock divisor ratio is this number plus one.\r
 280  */\r
 281 uint32_t alt_globaltmr_prescaler_get(void);\r
 282 \r
 283 \r
 284 /******************************************************************************/\r
 285 /*!\r
 286  * Sets the clock prescaler value of the global timer.\r
 287  *\r
 288  *\r
 289  * \param       val\r
 290  *              The 8-bit prescaler value to load. Valid range is 0-255.\r
 291  *              Actual clock divisor ratio is this number plus one.\r
 292  *\r
 293  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 294  * \retval      ALT_E_ERROR     The operation failed.\r
 295  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 296  */\r
 297 ALT_STATUS_CODE alt_globaltmr_prescaler_set(uint32_t val);\r
 298 \r
 299 /******************************************************************************/\r
 300 /*!\r
 301  * Sets a 32-bit global timer auto-increment value in the global\r
 302  * timer block for this CPU. The global timer continually increments its count\r
 303  * and when it reaches the value set in the comparator register or above, if\r
 304  * both comparison and free-run modes are selected, it adds the value set by this\r
 305  * function to the comparator value and saves it as the new comparator value.\r
 306  * This count then sets the time delay until the next global timer compare\r
 307  * value is reached.\r
 308  *\r
 309  *\r
 310  * \param       inc\r
 311  *              Auto-increment value to set.\r
 312  *\r
 313  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 314  * \retval      ALT_E_ERROR     The operation failed.\r
 315  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 316  */\r
 317 ALT_STATUS_CODE alt_globaltmr_autoinc_set(uint32_t inc);\r
 318 \r
 319 /******************************************************************************/\r
 320 /*!\r
 321  * Returns the global timer auto-increment value for this CPU. When the global\r
 322  * timer reaches the comparator value, if both comparison and free-run modes\r
 323  * are selected this value is added to the previous comparator value and saved\r
 324  * as the new comparator value.\r
 325  *\r
 326  *\r
 327  * \retval      uint32_t\r
 328  *              The current comparator auto-increment value.\r
 329  */\r
 330 uint32_t alt_globaltmr_autoinc_get(void);\r
 331 \r
 332 /******************************************************************************/\r
 333 /*!\r
 334  * Enables the auto-increment function of the global timer for this CPU.\r
 335  *\r
 336  *\r
 337  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 338  * \retval      ALT_E_ERROR     The operation failed.\r
 339  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 340  */\r
 341 ALT_STATUS_CODE alt_globaltmr_autoinc_mode_start(void);\r
 342 \r
 343 /******************************************************************************/\r
 344 /*!\r
 345  * Disables the auto-increment function of the global timer for this CPU.\r
 346  *\r
 347  *\r
 348  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 349  * \retval      ALT_E_ERROR     The operation failed.\r
 350  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 351  */\r
 352 ALT_STATUS_CODE alt_globaltmr_autoinc_mode_stop(void);\r
 353 \r
 354 /******************************************************************************/\r
 355 /*!\r
 356  * Returns the auto-increment selection of the global timer for this CPU.\r
 357  *\r
 358  *\r
 359  * \retval      FALSE           Auto-increment mode is not enabled.\r
 360  * \retval      TRUE            Auto-increment mode is enabled.\r
 361  */\r
 362 bool alt_globaltmr_is_autoinc_mode(void);\r
 363 \r
 364 /******************************************************************************/\r
 365 /*!\r
 366  * Returns the maximum counter value available for \b CPU_GLOBAL_TMR. \n\r
 367  * The value returned does not factor in the value of the clock prescaler.\r
 368  *\r
 369  *\r
 370  *\r
 371  *\r
 372  * \retval      uint32_t    The maximum counter value available for this timer.\r
 373  * \retval      0           An error occurred.\r
 374  *\r
 375  */\r
 376 uint32_t alt_globaltmr_maxcounter_get(void);\r
 377 \r
 378 /******************************************************************************/\r
 379 /*!\r
 380  * Disables the interrupt from the global timer module. Identical to calling\r
 381  * alt_gpt_int_disable() with tmr_id of \b CPU_GLOBAL_TMR.\r
 382  *\r
 383  *\r
 384  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 385  * \retval      ALT_E_ERROR     The operation failed.\r
 386  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 387  */\r
 388 ALT_STATUS_CODE alt_globaltmr_int_disable(void);\r
 389 \r
 390 /******************************************************************************/\r
 391 \r
 392 #if 0\r
 393 /*!\r
 394  *\r
 395  * Enables the interrupt of the global timer\r
 396  * module. Identical to calling alt_gpt_int_enable() with tmr_id of\r
 397  * \b CPU_GLOBAL_TMR. If global timer is not already running, this function\r
 398  * returns an error.\r
 399  *\r
 400  *\r
 401  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 402  * \retval      ALT_E_ERROR     The operation failed.\r
 403  */\r
 404 ALT_STATUS_CODE alt_globaltmr_int_enable(void);\r
 405 \r
 406 #else\r
 407 /*!\r
 408  *\r
 409  * Enables the interrupt of the global timer\r
 410  * module. Identical to calling alt_gpt_int_enable() with tmr_id of\r
 411  * \b CPU_GLOBAL_TMR. If global timer is not already running, this function\r
 412  * attempts to start it.\r
 413  *\r
 414  *\r
 415  *\r
 416  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 417  * \retval      ALT_E_ERROR     The operation failed.\r
 418  */\r
 419 ALT_STATUS_CODE alt_globaltmr_int_enable(void);\r
 420 \r
 421 #endif\r
 422 \r
 423 /******************************************************************************/\r
 424 /*!\r
 425  * Return \b TRUE if the interrupt of the global timer module is enabled\r
 426  * and \b FALSE if the interrupt is disabled or masked. Identical to calling\r
 427  * alt_gpt_int_is_enabled() with tmr_id of\r
 428  * \b CPU_GLOBAL_TMR.\r
 429  *\r
 430  * \internal - note that there's more to this than just enabling the\r
 431  * interrupt and clearing the status.\r
 432  * \endinternal\r
 433  *\r
 434  *\r
 435  * \retval      TRUE            The timer interrupt is currently enabled.\r
 436  * \retval      FALSE           The timer interrupt is currently disabled.\r
 437  */\r
 438 bool alt_globaltmr_int_is_enabled(void);\r
 439 \r
 440 /******************************************************************************/\r
 441 /*!\r
 442  * Clear the pending interrupt status of the global timer module. Identical to\r
 443  * calling alt_gpt_int_clear_pending() with tmr_id of\r
 444  * \b CPU_GLOBAL_TMR.\r
 445  *\r
 446  *\r
 447  * \retval      ALT_E_SUCCESS   The operation was successful.\r
 448  * \retval      ALT_E_ERROR     The operation failed.\r
 449  * \retval      ALT_E_BAD_ARG   Invalid input argument.\r
 450  */\r
 451 ALT_STATUS_CODE alt_globaltmr_int_clear_pending(void);\r
 452 \r
 453 /******************************************************************************/\r
 454 /*!\r
 455  * Read the state (pending or not) of the interrupt of the global timer\r
 456  * module without changing the interrupt state. Identical to\r
 457  * calling alt_gpt_int_is_pending() with tmr_id of\r
 458  * \b CPU_GLOBAL_TMR.\r
 459  *\r
 460  *\r
 461  *\r
 462  * \retval      TRUE            The timer interrupt is currently pending.\r
 463  * \retval      FALSE           The timer interrupt is not currently pending.\r
 464  */\r
 465 bool alt_globaltmr_int_is_pending(void);\r
 466 \r
 467 /******************************************************************************/\r
 468 /*!\r
 469  * Read the state of the interrupt of the global timer\r
 470  * module and if the interrupt is set, clear it. Identical to\r
 471  * calling alt_gpt_int_is_pending_and_clear()  with tmr_id of\r
 472  * \b CPU_GLOBAL_TMR.\r
 473  *\r
 474  *\r
 475  *\r
 476  * \retval      TRUE            The timer interrupt was pending.\r
 477  * \retval      FALSE           The timer interrupt was not pending.\r
 478  */\r
 479 bool alt_globaltmr_int_if_pending_clear(void);\r
 480 \r
 481 /*! @} */\r
 482 /*! @} */\r
 483 /*! @} */\r
 484 \r
 485 #ifdef __cplusplus\r
 486 }\r
 487 #endif  /* __cplusplus */\r
 488 #endif  /* __ALT_GBLTMR_H__ */\r