text: /*
   * Copyright (c) 2016, Texas Instruments Incorporated
   * All rights reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * *  Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * *  Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in the
   *    documentation and/or other materials provided with the distribution.
   *
   * *  Neither the name of Texas Instruments Incorporated nor the names of
   *    its contributors may be used to endorse or promote products derived
   *    from this software without specific prior written permission.
   *
   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
   * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
   * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
   * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
   * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   */
  /** ============================================================================
   *  @file       UDMACC32XX.h
   *
   *  @brief      uDMA driver implementation for CC32XX.
   *
   *  This driver is intended for use only by TI-RTOS drivers that use the uDMA
   *  peripheral (e.g., SPI and I2S).  This driver is mainly used for Power
   *  management of the UDMA peripheral.
   *
   *  The application should only define the memory for the control table and
   *  set up the UDMACC32XX_HWAttrs and UDMACC32XX_Config structures.
   *
   *  The UDMACC32XX header file should be included in an application as follows:
   *  @code
   *  #include <ti/drivers/dma/UDMACC32XX.h>
   *  @endcode
   *
   *  ============================================================================
   */
  
  #ifndef ti_drivers_dma_UDMACC32XX__include
  #define ti_drivers_dma_UDMACC32XX__include
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #include <stdint.h>
  #include <stdbool.h>
  #include <ti/drivers/dpl/HwiP.h>
  
  /*!
   *  @brief      UDMA error function pointer
   */
  typedef void (*UDMACC32XX_ErrorFxn)(uintptr_t arg);
  
  /*!
   *  @brief      UDMACC32XX Hardware attributes
   *
   *  This structure contains the base address of the uDMA control
   *  table, and uDMA error interrupt attributes.
   *
   *  The control table is used by the uDMA controller to store channel
   *  control structures.  The control table can be located anywhere in
   *  system memory, but must be contiguous and aligned on a 1024-byte boundary.
   *
   *  dmaErrorFxn is the uDMA peripheral's error interrupt handler.
   *
   *  intPriority is priority of the uDMA peripheral's error interrupt, as
   *  defined by the underlying OS.  It is passed unmodified to the
   *  underlying OS's interrupt handler creation code, so you need to
   *  refer to the OS documentation for usage.  For example, for
   *  SYS/BIOS applications, refer to the ti.sysbios.family.arm.m3.Hwi
   *  documentation for SYS/BIOS usage of interrupt priorities.  If the
   *  driver uses the ti.dpl interface instead of making OS
   *  calls directly, then the HwiP port handles the interrupt priority
   *  in an OS specific way.  In the case of the SYS/BIOS port,
   *  intPriority is passed unmodified to Hwi_create().
   *
   *  A sample structure is shown below:
   *  @code
   *
   *  #include <ti/devices/cc32xx/driverlib/udma.h>
   *
   *  #if defined(__TI_COMPILER_VERSION__)
   *  #pragma DATA_ALIGN(dmaControlTable, 1024)
   *  #elif defined(__IAR_SYSTEMS_ICC__)
   *  #pragma data_alignment=1024
   *  #elif defined(__GNUC__)
   *  __attribute__ ((aligned (1024)))
   *  #endif
   *
   *  static tDMAControlTable dmaControlTable[64];
   *
   *  #include <ti/drivers/dma/UDMACC32XX.h>
   *
   *  UDMACC32XX_Object udmaCC32XXObject;
   *
   *  const UDMACC32XX_HWAttrs udmaCC32XXHWAttrs = {
   *          .controlBaseAddr = (void *)dmaControlTable,
   *          .dmaErrorFxn = UDMACC32XX_errorFxn,
   *          .intNum = INT_UDMAERR,
   *          .intPriority = (~0)
   *  };
   *  @endcode
   *
   */
  typedef struct UDMACC32XX_HWAttrs {
      void           *controlBaseAddr; /*!< uDMA control registers base address */
      UDMACC32XX_ErrorFxn dmaErrorFxn; /*!< uDMA error interrupt handler */
      uint8_t         intNum;          /*!< uDMA error interrupt number */
      uint8_t         intPriority;     /*!< uDMA error interrupt priority. */
  } UDMACC32XX_HWAttrs;
  
  /*!
   *  @brief      UDMACC32XX Global configuration
   *
   *  The UDMACC32XX_Config structure contains pointers used by the UDMACC32XX
   *  driver.
   *
   *  This structure needs to be defined before calling UDMACC32XX_init() and
   *  it must not be changed thereafter.
   */
  typedef struct UDMACC32XX_Config {
      void              *object;            /*!< Pointer to UDMACC32XX object */
      void const        *hwAttrs;           /*!< Pointer to hardware attributes */
  } UDMACC32XX_Config;
  
  /*!
   *  @brief      A handle that is returned from a UDMACC32XX_open() call.
   */
  typedef struct UDMACC32XX_Config      *UDMACC32XX_Handle;
  
  /*!
   *  @brief  UDMACC32XX object
   *
   *  The application must not access any member variables of this structure!
   */
  typedef struct UDMACC32XX_Object {
      bool             isOpen;          /* Flag for open/close status */
      HwiP_Handle      hwiHandle;       /* DMA error Hwi */
  } UDMACC32XX_Object;
  
  /*!
   *  @brief  Function to close the DMA driver.
   *
   *  This function releases Power dependency on UDMA that was previously
   *  set with a call to UDMACC32XX_open(). If there is only one outstanding
   *  UDMACC32XX_open() call (i.e. all but one UDMACC32XX_open() calls have
   *  been matched by a corresponding call to UDMACC32XX_close()), this
   *  function will disable the UDMA.
   *
   *  @pre    UDMACC32XX_open() has to be called first.
   *          Calling context: Task
   *
   *  @param  handle  A UDMACC32XX_Handle returned from UDMACC32XX_open()
   *
   *  @return none
   *
   *  @sa     UDMACC32XX_open
   */
  extern void UDMACC32XX_close(UDMACC32XX_Handle handle);
  
  /*!
   *  @brief  Function to initialize the CC32XX DMA driver
   *
   *  The function will set the isOpen flag to false, and should be called prior
   *  to opening the DMA driver.
   *
   *  @return none
   *
   *  @sa     UDMACC32XX_open()
   */
  extern void UDMACC32XX_init();
  
  /*!
   *  @brief  Function to initialize the CC32XX DMA peripheral
   *
   *  UDMACC32XX_open() can be called multiple times.  Each time the
   *  function is called, it will set a dependency on the peripheral and
   *  enable the clock.  The Power dependency count on the UDMA will be
   *  equal to the number of outstanding calls to UDMACC32XX_open().
   *  Calling UDMACC32XX_close() will decrement the Power dependency count,
   *  and the last call to UDMACC32XX_close() will disable the UDMA.
   *
   *  @pre    UDMACC32XX_init() has to be called first.
   *          Calling context: Task
   *
   *  @return UDMACC32XX_Handle on success or NULL if an error has occurred.
   *
   *  @sa     UDMACC32XX_close()
   */
  extern UDMACC32XX_Handle UDMACC32XX_open();
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* ti_drivers_dma_UDMACC32XX__include */
  