/******************************************************************************
*                                                                             *
*        **********                                                           *
*       ************                                                          *
*      ***        ***                                                         *
*     ***    ++    ***                                                        *
*     ***   +  +   ***                      CHIPCON                           *
*     ***   +                                                                 *
*     ***   +  +   ***                                                        *
*     ***    ++    ***                                                        *
*      ***        ***                                                         *
*       ************                                                          *
*        **********                                                           *
*                                                                             *
*******************************************************************************

Filename:     cul.h
Target:       cc2430
Author:       EFU/ KJA
Revised:      16/12-2005
Revision:     1.0

Description:
Chipcon Utility Library

Provides utility functions for DMA administration, timer administration, SPP
handling, etc.

******************************************************************************/
#ifndef CUL_H
#define CUL_H


#include "hal.h"


typedef void FUNCTION(void);

/******************************************************************************
*******************     DMA administration functions         ******************
******************************************************************************/

// The number of DMA channels available for the DMA administrator
#define DMA_ADM_NUMBER_OF_CHANNELS      5

// Structure for the DMA administration table
typedef struct {
    BYTE        assigned;
    FUNCTION*   callBackFunction;
} DMA_TABLE_ENTRY;



/******************************************************************************
* @fn  culDmaInit
*
* @brief
*      This function resets the table for assigning DMA channels 1 to 4, the
*      table consisting of the DMA descriptors 1 to 4 and clears all interrupt
*      flags and disarms all DMA channels 1 to 4. The configuration for
*      channel 0 is left unchanged. The address of the DMA descriptors is set
*      in register DMA1CFG.
*
* Parameters:
*
* @param  void
*
* @return void
*
******************************************************************************/
void culDmaInit(void);

/******************************************************************************
* @fn  dma_IRQ
*
* @brief
*     This interrupt routine is run each time the DMA generates an interrupt.
*     According to the interrupt flag of the DMA channel, the corresponding
*     callBackFunction is called. The interrupt flags are cleared.
*
* Parameters:
*
* @param  void
*
* @return void
*
******************************************************************************/
__interrupt void dma_IRQ (void);

/******************************************************************************
* @fn  culDmaAlloc
*
* @brief
*      This function administrates the allocation of the DMA channels 1 to 4.
*      This function, along with culDmaFreeChannel(...), keeps track of the
*      availability of the DMA channels. When this function is called, the
*      table _dmaTable_ is searched for an unused channel. If an unused channel
*      is found, the channel is reserved and the number of the assigned channel
*      is handed to the calling function. A pointer to the descriptor of the
*      assigned DMA channel is returned. At the time of editing the table, all
*      interrupts are disabled in order to avoid that the table is edited by an
*      interrupt routine before the table is updated. If no DMA channel is
*      available, the function returns 0 and the channel number pointed to by
*      _pDmaChannelNumber_ is set to 0.
*
*      This function leaves to the caller to arm the DMA channel and initiate
*      the transfer. Alternatively, the function culDmaSetUpChannel(...) could
*      be used to simplify the use of the DMA.
*
*      NOTE:   If the number pointed to by _pDmaChannelNumber_ is set to 0 by
*              this function, the allocation was unsuccessful. This must not be
*              interpreted as if DMA channel 0 has been  used.
*
* Parameters:
*
* @param  UINT8*    pDmaChannelNumber
*         Pointer to where the assigned DMA channel number is to be stored. If
*         this value is set to 0 by this function, no DMA channel was assigned.
*         (NOT that DMA channel 0 was used!)
* @param  FUNCTION* callBackFunction
*         This parameter is a pointer to the function to be called from an
*         interrupt routine when the DMA transfer is finished. The function
*         must be a [void <functionName>(void)] type. The configuration of
*         the interrupt routine must be performed manually. If no function
*         is to be called, please set this parameter to NULL (0x00);
*
* @return DMA_DESC*
*         Pointer to the assigned DMA structure. The calling function must set
*         this descriptor occording to the desired DMA transfer.
*
******************************************************************************/
DMA_DESC* culDmaAllocChannel(UINT8* pDmaChannelNumber, FUNCTION* callBackFunction);

/******************************************************************************
* @fn  culDmaFreeChannel
*
* @brief
*      This function frees a channel assigned by culDmaAlloc(...). When a
*      DMA channel no longer is in use, this function should be called with
*      the channel number as a parameter in order to make the  DMA channel
*      available for other functionality.
*
*      NOTE: Be careful not to free a channel which is still in use.
*
* Parameters:
*
* @param  BYTE	 dmaChannelNumber - Describe value.
*         Number of the channel to be freed. This number should be identical
*         to the number returned by culDmaAlloc(...) when the channel was
*         requested.
*
* @return void
*
******************************************************************************/
void culDmaFreeChannel(BYTE dmaChannelNumber);


/******************************************************************************
* @fn  culDmaSetUpChannel
*
* @brief
*      This function is used to initiate a DMA transfer. The function requests
*      an available DMA channel by using culDmaAlloc(...). The DMA descriptor
*      is copied into the list of assigned DMA desriptors. The channel is then
*      armed (meaning that the channel is active but not nescessarily started.)
*      If the Boolean expression _immediately_ is true, the DMA data transfer
*      is started. The number of the DMA channel used is returned. This
*      identifier should be used with the function culDmaFreeChannel(...) when
*      the DMA channel is no longer needed in order to make the channel
*      available for other transfers.
*
* Parameters:
*
* @param  DMA_DESC*	 pDmaDescriptor
*         Pointer to the DMA descriptor structure the channel data is to be
*         fetched from. The data at this pointer is copied into the list of
*         active DMA channels.
* @param  BOOL	 immediately
*         If this value is TRUE, the DMA transfer is started as soon as the
*         channel setup is complete. If FALSE, the channel will wait for either
*         a DMA trigger or that the transfer is initiated manually (through
*         the register DMAREQ).
* @param  FUNCTION*	 callBackFunction
*         This parameter is a pointer to the function to be called from an
*         interrupt routine when the DMA transfer is finished. The function
*         must be a [void <functionName>(void)] type. The configuration of
*         the interrupt routine must be performed manually. If no function is
*         to be called, please set this parameter to NULL (0x00);
*
* @return BYTE
*         The returned value indicates the DMA channel number used for the
*         transfer. If 0 is returned, the function call was unsuccessful,
*         most probably because all DMA channels were occupied.
*
*         NOTE: The return value 0 (0x00) does NOT indicate that DMA
*               channel 0 was used.
*
******************************************************************************/
BYTE culDmaSetUpChannel(DMA_DESC* pDmaDescriptor, BOOL immediately, FUNCTION* callBackFunction);


/******************************************************************************
* @fn  culSetDmaChannel0CallBack
*
* @brief
*      This function sets the callbackfunction to be called when DMA channel
*      0 finishes its transfer. This function is used in order to avoid
*      changing the DMA ISR.
*
* Parameters:
*
* @param  FUNCTION*	 pCallBackFunction
*
* @return void
*
******************************************************************************/
void culSetDmaChannel0CallBack(FUNCTION* pCallBackFunction);


/******************************************************************************
* @fn  culClearDmaChannel0CallBack
*
* @brief
*      This function clears the callbackfunction to be called when DMA
*      channel 0 finishes.
*
* Parameters:
*
* @param  void
*
* @return void
*
******************************************************************************/
void culClearDmaChannel0CallBack(void);


/******************************************************************************
* @fn  culDMAToFlash
*
* @brief       Description of the function.
*      This function configures DMA transfer of _length_ bytes starting from
*      _srcAddr_ to the flash. The flash address to be written must be set in
*      the register FADDR. The flash write address consists of 15 bits dividing
*      the 128 KB flash memory into 4 byte segments. Hence, each flash write must
*      contain at least 4 bytes (zero-padded if nescessary). The flash controller
*      issues a DMA trigger each time a new byte is desired.
*
* Parameters:
*
* @param  DMA_DESC*	pDmaChannel
*         A pointer to the DMA channel structure to be used for the transfer.
* @param  BYTE*      pSrcAddr
*         The start address in __xdata space of the data to be transferred.
* @param  WORD	      length
*         The number of bytes to be transferred.
* @param  BOOL	      generateInterrupt
*         If TRUE, the DMA channel will generate an interrupt request upon
*         completion.
*
* @return void
*
******************************************************************************/
void culDMAToFlash(DMA_DESC* pDmaChannel, BYTE __xdata* , WORD length, BOOL generateInterrupt);


/******************************************************************************
* @fn  culDmaToAes
*
* @brief
*      This function configures a DMA descriptor for transferring data to be
*      converted by the AES module. The function _culDmaFromAes(...)_ is used
*      to set up a DMA descriptor for transferring converted data from the AES
*      module.
*
* Parameters:
*
* @param  DMA_DESC*	 pDmaChannel
*         Pointer to the DMA descriptor to be used for DMA transfer of data to
*         be converted.
* @param  BYTE*	  pSrcAddr
*         Pointer to the start address of the data to be transferred to the AES
*         module. The length of the data to be converted should be a multiplum
*         of 16 bytes, as the AES module operates on blocks of 16 bytes
*         (128 bit). The data should be zero-padded at the end if nescessary, to
*         make the total byte count a multiplum of 16 bytes.
* @param  WORD	 length
*         Number of bytes to be converted in total. This number should be a
*         multiplum of 16 bytes, as the AES module operates on blocks of 16
*         bytes (128 bit).
* @param  BOOL	 generateInterrupt
*         If this parameter is TRUE the DMA channel will generate an interrupt
*         request when done. In order to generate an interrupt, the lines
*         INT_ENABLE(INUM_DMA, INT_ON); and EA = TRUE; must also be included.
*