begriffs open source - cmsis-freertos/blob - Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/Capture.h

   1 /*
   2  * Copyright (c) 2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       Capture.h
  34  *
  35  *  @brief      Capture driver interface
  36  *
  37  *  The Capture header file should be included in an application as follows:
  38  *  @code
  39  *  #include <ti/drivers/Capture.h>
  40  *  @endcode
  41  *
  42  *  # Operation #
  43  *  The Capture driver facilitates the capture routines by using general purpose
  44  *  timers. Capture instances must be opened by calling Capture_open() while
  45  *  passing in a Capture index and parameters data structure.
  46  *
  47  *  When a capture instance is opened, the capture triggering edge and callback
  48  *  function are configured. The capture is stopped after calling Capture_open()
  49  *  until Capture_start() is called.
  50  *
  51  *  When Capture_open() is called, it tries to occupy the user-specified timer by
  52  *  calling Timer_open(). If that timer is already allocated for other modules,
  53  *  NULL is returned. Otherwise, the Capture_Handle is returned.
  54
  55  *  A capture is triggered based on the user-specified capture mode:
  56  *      - CAPTURE_MODE_RISING_RISING
  57  *      - CAPTURE_MODE_RISING_FALLING
  58  *      - CAPTURE_MODE_ANY_EDGE
  59  *  The user-specified callback function is called once the input signal matches
  60  *  the capture mode and the value passed into callback function is the interval
  61  *  between two triggering edge in the user-specified unit.
  62  *
  63  *  ## opening the driver ##
  64  *
  65  *  @code
  66  *  Capture_Handle      handle;
  67  *  Capture_Params      params;
  68  *
  69  *  Capture_Params_init(&params);
  70  *  params.mode  = CAPTURE_MODE_RISING_FALLING;
  71  *  params.callbackFxn = someCaptureCallbackFunction;
  72  *  params.periodUnit = CAPTURE_PERIOD_US;
  73  *  handle = Capture_open(someCapture_configIndexValue, &params);
  74  *  if (!handle)
  75  *  {
  76  *      System_printf("Capture did not open");
  77  *  }
  78  *
  79  *  ## starting the driver ##
  80
  81  *  @code
  82  *  status = Capture_start(handle);
  83  *  if (status == Capture_STATUS_ERROR)
  84  *  {
  85  *      System_printf("Capture cannot start");
  86  *  }
  87  *  @endcode
  88  *
  89  *  ## stoping the driver ##
  90  *
  91  *  @code
  92  *  Capture_stop(handle);
  93  *  @endcode
  94  *
  95  *  ## closing the driver ##
  96  *
  97  *  @code
  98  *  Capture_close(handle);
  99  *  @endcode
 100  *
 101  *  # Implementation #
 102  *
 103  *  This module serves as the main interface for TI-RTOS
 104  *  applications. Its purpose is to redirect the module's APIs to specific
 105  *  peripheral implementations which are specified using a pointer to a
 106  *  Capture_FxnTable.
 107  *
 108  *  The Capture driver interface module is joined (at link time) to a
 109  *  NULL-terminated array of Capture_Config data structures named *Capture_Config*.
 110  *  *Capture_Config* is implemented in the application with each entry being an
 111  *  instance of a Capture module. Each entry in *Capture_Config* contains a:
 112  *  - (Capture_FxnTable *) to a set of functions that implement a Capture module
 113  *  - (void *) data object that is associated with the Capture_FxnTable
 114  *  - (void *) hardware attributes that are associated to the Capture_FxnTable
 115  *
 116  *  # Instrumentation #
 117  *  The Capture driver interface produces log statements if instrumentation is
 118  *  enabled.
 119  *
 120  *  Diagnostics Mask | Log details |
 121  *  ---------------- | ----------- |
 122  *  Diags_USER1      | basic operations performed |
 123  *  Diags_USER2      | detailed operations performed |
 124  *
 125  *  ============================================================================
 126  */
 127 #ifndef ti_drivers_Capture__include
 128 #define ti_drivers_Capture__include
 129
 130 #ifdef __cplusplus
 131 extern "C"
 132 {
 133 #endif
 134
 135 #include <stdint.h>
 136 #include <stdbool.h>
 137
 138 /*!
 139  *  @brief      A handle that is returned from a Capture_open() call.
 140  */
 141 typedef struct Capture_Config_ *Capture_Handle;
 142
 143 /*!
 144  * Common Capture_control command code reservation offset.
 145  * Capture driver implementations should offset command codes with CAPTURE_CMD_RESERVED
 146  * growing positively
 147  *
 148  * Example implementation specific command codes:
 149  * @code
 150  * #define CAPTUREXYZ_CMD_COMMAND0      CAPTURE_CMD_RESERVED + 0
 151  * #define CAPTUREXYZ_CMD_COMMAND1      CAPTURE_CMD_RESERVED + 1
 152  * @endcode
 153  */
 154 #define CAPTURE_CMD_RESERVED             (32)
 155
 156 /*!
 157  * Common Capture_control status code reservation offset.
 158  * Capture driver implementations should offset status codes with
 159  * CAPTURE_STATUS_RESERVED growing negatively.
 160  *
 161  * Example implementation specific status codes:
 162  * @code
 163  * #define CAPTUREXYZ_STATUS_ERROR0     CAPTURE_STATUS_RESERVED - 0
 164  * #define CAPTUREXYZ_STATUS_ERROR1     CAPTURE_STATUS_RESERVED - 1
 165  * #define CAPTUREXYZ_STATUS_ERROR2     CAPTURE_STATUS_RESERVED - 2
 166  * @endcode
 167  */
 168 #define CAPTURE_STATUS_RESERVED         (-32)
 169
 170 /*!
 171  * @brief   Successful status code returned by Capture_control().
 172  *
 173  * Capture_control() returns TIMER_STATUS_SUCCESS if the control code was executed
 174  * successfully.
 175  */
 176 #define CAPTURE_STATUS_SUCCESS          (0)
 177
 178 /*!
 179  * @brief   Generic error status code returned by Capture_control().
 180  *
 181  * Capture_control() returns CAPTURE_STATUS_ERROR if the control code was not executed
 182  * successfully.
 183  */
 184 #define CAPTURE_STATUS_ERROR            (-1)
 185
 186 /*!
 187  * @brief   An error status code returned by Capture_control() for undefined
 188  * command codes.
 189  *
 190  * Capture_control() returns TIMER_STATUS_UNDEFINEDCMD if the control code is not
 191  * recognized by the driver implementation.
 192  */
 193 #define CAPTURE_STATUS_UNDEFINEDCMD    (-2)
 194
 195 /*!
 196  *  @brief Capture period unit enum
 197  *
 198  *  The Capture period unit needs to be passed in Capture_open() to
 199  *  specify the unit of two capture triggering interval.
 200  *
 201  */
 202 typedef enum Capture_Period_Unit_ {
 203     CAPTURE_PERIOD_US,      /* Period in microseconds */
 204     CAPTURE_PERIOD_HZ,      /* Period in frequency */
 205     CAPTURE_PERIOD_COUNTS,  /* Period in counts */
 206 } Capture_Period_Unit;
 207
 208 /*!
 209  *  @brief Capture mode enum
 210  *
 211  *  The Capture mode needs to be passed in Capture_open() to specify the capture
 212  *  triggering mode.
 213  *
 214  */
 215 typedef enum Capture_Mode_ {
 216     CAPTURE_MODE_RISING_RISING, /*!< capture is triggered at the rising edge followed by the rising edge */
 217     CAPTURE_MODE_FALLING_FALLING, /*!< capture is triggered at the falling edge followed by the falling edge */
 218     CAPTURE_MODE_ANY_EDGE
 219     /*!< capture is triggered at the falling edge followed by the rising edge */
 220 } Capture_Mode;
 221
 222 /*!
 223  *  @brief  Capture callback function
 224  *
 225  *  User definable callback function prototype. The Capture driver will call the
 226  *  defined function and pass in the Capture driver's handle and the pointer to the
 227  *  user-specified the argument.
 228  *
 229  *  @param  handle         Capture_Handle
 230  *
 231  *  @param  interval       Interval of two triggering edge in Capture_Period_Unit
 232  *
 233  */
 234 typedef void (*Capture_CallBackFxn)(Capture_Handle handle, uint32_t interval);
 235
 236 /*!
 237  *  @brief Capture Parameters
 238  *
 239  *  Capture parameters are used to with the Capture_open() call. Default values for
 240  *  these parameters are set using Capture_Params_init().
 241  *
 242  */
 243 typedef struct Capture_Params_ {
 244     Capture_Mode mode; /*!< Capture triggering mode */
 245     Capture_CallBackFxn callbackFxn; /*!< Callback function pointer */
 246     Capture_Period_Unit periodUnit; /*!< Period unit */
 247 } Capture_Params;
 248
 249 /*!
 250  *  @brief      A function pointer to a driver specific implementation of
 251  *              Capture_close().
 252  */
 253 typedef void (*Capture_CloseFxn)(Capture_Handle handle);
 254
 255 /*!
 256  *  @brief      A function pointer to a driver specific implementation of
 257  *              Capture_control().
 258  */
 259 typedef int_fast16_t (*Capture_ControlFxn)(Capture_Handle handle,
 260         uint_fast16_t cmd, void *arg);
 261
 262 /*!
 263  *  @brief      A function pointer to a driver specific implementation of
 264  *              Capture_init().
 265  */
 266 typedef void (*Capture_InitFxn)(Capture_Handle handle);
 267
 268 /*!
 269  *  @brief      A function pointer to a driver specific implementation of
 270  *              Capture_open().
 271  */
 272 typedef Capture_Handle (*Capture_OpenFxn)(Capture_Handle handle,
 273         Capture_Params *params);
 274
 275 /*!
 276  *  @brief      A function pointer to a driver specific implementation of
 277  *              Capture_start().
 278  */
 279 typedef void (*Capture_StartFxn)(Capture_Handle handle);
 280
 281 /*!
 282  *  @brief      A function pointer to a driver specific implementation of
 283  *              Capture_stop().
 284  */
 285 typedef void (*Capture_StopFxn)(Capture_Handle handle);
 286
 287 /*!
 288  *  @brief      The definition of a Capture function table that contains the
 289  *              required set of functions to control a specific Capture driver
 290  *              implementation.
 291  */
 292 typedef struct Capture_FxnTable_ {
 293     /*! Function to close the specified peripheral */
 294     Capture_CloseFxn closeFxn;
 295
 296     /*! Function to send control commands to the specified peripheral */
 297     Capture_ControlFxn controlFxn;
 298
 299     /*! Function to initialize the specified peripheral */
 300     Capture_InitFxn initFxn;
 301
 302     /*! Function to open the specified peripheral */
 303     Capture_OpenFxn openFxn;
 304
 305     /*! Function to start the specified peripheral */
 306     Capture_StartFxn startFxn;
 307
 308     /*! Function to stop the specified peripheral */
 309     Capture_StopFxn stopFxn;
 310
 311 } Capture_FxnTable;
 312
 313 typedef struct Capture_Config_ {
 314     Capture_FxnTable const *fxnTablePtr;
 315     void *object;
 316     void const *hwAttrs;
 317 } Capture_Config;
 318
 319 /*!
 320  *  @brief  Function to close a Capture module specified by the Capture handle
 321  *
 322  *  The function takes care of timer resource allocation. The corresponding timer
 323  *  resource to the Capture_Handle is released to be an available timer resource.
 324  *
 325  *  @pre    Capture_open() had to be called first.
 326  *
 327  *  @param  handle  A Capture_Handle returned from Capture_open
 328  *
 329  *  @sa     Capture_open()
 330  */
 331 extern void Capture_close(Capture_Handle handle);
 332
 333 /*!
 334  *  @brief  Function performs implementation specific features on a given
 335  *          Capture_Handle.
 336  *
 337  *  @pre    Capture_open() must have been called first.
 338  *
 339  *  @param  handle      A Capture_Handle returned from Capture_open().
 340  *
 341  *  @param  cmd         A command value defined by the driver specific
 342  *                      implementation.
 343  *
 344  *  @param  arg         A pointer to an optional R/W (read/write) argument that
 345  *                      is accompanied with cmd.
 346  *
 347  *  @return A Capture_Status describing an error or success state. Negative values
 348  *          indicate an error occurred.
 349  *
 350  *  @sa     Capture_open()
 351  */
 352 extern int_fast16_t Capture_control(Capture_Handle handle, uint_fast16_t cmd,
 353     void *arg);
 354
 355 /*!
 356  *  @brief  Function to initialize Capture.
 357  */
 358 extern void Capture_init(void);
 359
 360 /*!
 361  *  @brief  Function to initialize a given Capture module specified by the
 362  *          particular index value. The parameter specifies which mode the Capture
 363  *          will operate.
 364  *
 365  *  The function takes care of timer resource allocation. If the particular timer
 366  *  passed by user has already been used by other modules, the return value is NULL.
 367  *  If the particular timer is available to use, Capture module owns it and returns
 368  *  a Capture_Handle.
 369  *
 370  *  @param  index         Logical instance number for the Capture indexed into
 371  *                        the Capture_config table
 372  *
 373  *  @param  params        Pointer to an parameter block, if NULL it will use
 374  *                        default values. All the fields in this structure are
 375  *                        RO (read-only).
 376  *
 377  *  @return A Capture_Handle on success or a NULL on an error if it has been
 378  *          opened already or used by other modules.
 379  *
 380  *  @sa     Capture_init()
 381  *  @sa     Capture_close()
 382  */
 383 extern Capture_Handle Capture_open(uint_least8_t index, Capture_Params *params);
 384
 385 /*!
 386  *  @brief  Function to initialize the Capture_Params struct to its defaults
 387  *
 388  *  @param  params      An pointer to Capture_Params structure for
 389  *                      initialization
 390  *
 391  *  Defaults values are:
 392  *      mode = CAPTURE_MODE_RISING_RISING
 393  *      callbackFxn = user_specified_callbackFxn
 394  *      periodUnit = Capture_PERIOD_COUNTS
 395  */
 396 extern void Capture_Params_init(Capture_Params *params);
 397
 398 /*!
 399  *  @brief  Function to start capture. The Capture running mode
 400  *          and interval period unit are specfied in the Capture_Params when calling
 401  *          Capture_open().
 402  *
 403  *  @param  handle        Capture_Handle
 404  *
 405  *  @return CAPTURE_STATUS_SUCCESS if Capture starts successfully.
 406  *          CAPTURE_STATUS_ERROR if Capture fails to start.
 407  *
 408  */
 409 extern void Capture_start(Capture_Handle handle);
 410
 411 /*!
 412  *  @brief  Function to stop Capture after Capture_start() is called with success.
 413  *
 414  *  @param  handle        Capture_Handle
 415  *
 416  */
 417 extern void Capture_stop(Capture_Handle handle);
 418
 419 #ifdef __cplusplus
 420 }
 421 #endif
 422
 423 #endif /* ti_drivers_Capture__include */