*      data from the AES module. The function _culDmaToAes(...)_ is used to set
*      up a DMA descriptor for transferring data to be converted to the AES
*      module.
*
* Parameters:
*
* @param  DMA_DESC* pDmaChannel
*         Pointer to the DMA descriptor to be used for DMA transfer of data
*         converted by the AES module.
* @param  BYTE*	 pDstAddr
*         Pointer to the start address where the converted data is to be stored.
*         The length of this data field should be a multiplum of 16 bytes, as
*         the AES module operates on blocks of 16 bytes (128 bit).
* @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 EAL = TRUE; must also be included.
*
* @return BOOL
*         Function returns TRUE if the configuration was successful.
*
******************************************************************************/
BOOL culDmaFromAes(DMA_DESC* pDmaChannel, BYTE __xdata* pDstAddr, WORD length, BOOL generateInterrupt);


/******************************************************************************
* @fn  culDmaFromRadio
*
* @brief
*      This function configures DMA transfer from the radio Rx FiFo. The first
*      byte of the data to be transferred contains the number of bytes to be
*      transfer. The Rx FiFo may contain up to 128 bytes. When done, the DMA
*      channel may generate an interrupt.
*
* Parameters:
*
* @param  DMA_DESC*	 pDmaChannel
*         A pointer to the DMA channel structure to be used for the transfer.
* @param  BYTE*	 pDstAddr
*         The start address in __xdata space to where the data is to be stored.
* @param  BOOL	 generateInterrupt
*         If TRUE, the DMA channel will generate an interrupt request upon
*         completion.
*
* @return void
*
******************************************************************************/
void culDmaFromRadio(DMA_DESC* pDmaChannel, BYTE* pDstAddr, BOOL generateInterrupt);



/******************************************************************************
* @fn  culDmaToRadio
*
* @brief
*      This function configures DMA transfer to the radio Tx FiFo.
*
* Parameters:
*
* @param  DMA_DESC*  pDmaChannel
*         A pointer to the DMA channel structure to be used for the transfer.
* @param  WORD       length
* @param  BYTE*      pSrcAddr
*         The start address in __xdata space of the data to be transferred.
* @param  BOOL       generateInterrupt
*         If TRUE, the DMA channel will generate an interrupt request upon
*         completion.
*
* @return void
*
******************************************************************************/
void culDmaToRadio(DMA_DESC* pDmaChannel, WORD length, BYTE * pSrcAddr, BOOL generateInterrupt);


/******************************************************************************
* @fn  culDmaToUart0
*
* @brief       Description of the function.
*      This function configures a DMA transfer to UART0.
*
* Parameters:
*
* @param  DMA_DESC*	 pDmaChannel
*         A pointer to the DMA channel structure to be used for the transfer.
* @param  WORD	 length
*         The number of bytes to be transferred.
* @param  BYTE*	 pSrcAddr
*         The start address in __xdata space of the data to be transferred.
* @param  BOOL	 generateInterrupt
*         If TRUE, the DMA channel will generate an interrupt request upon completion.
*
* @return void
*
******************************************************************************/
void culDmaToUart0(DMA_DESC* pDmaChannel, WORD length, BYTE * pSrcAddr, BOOL generateInterrupt);



/******************************************************************************
*******************      TIMER4 administrator functions    ********************
******************************************************************************/

// Structure for the TIMER administrator entry table
typedef struct {
    BYTE        counter;
    BYTE        timeout;
    FUNCTION*   callBackFunction;
} TIMER4_TABLE_ENTRY;

#define TIMER_ADM_TABLE_LENGTH   3


/******************************************************************************
* @fn  culTimer4AdmInit
*
* @brief
*      This function sets up the timer 4 administration. The table is cleared,
*      timer 4 is set up to generate interrupts at a 1m-second interval,
*      timer 4 interrupt is enabled and the timer is turned on.
*
* Parameters:
*
* @param  void
*
* @return void
*
******************************************************************************/
void culTimer4AdmInit(void);


/******************************************************************************
* @fn  T4_Adm_IRQ
*
* @brief
*     This interrupt routine is run each time timer 4 generates an interrupt
*     request (every m-second). The table is parsed through, and the counters
*     are incremented. If a counter is equal to the timeout value in the table,
*     the _callBackFunction_ is called and the counter is reset. At the end,
*     the interrupt flags are cleared.
*
* Parameters:
*
* @param  void
*
* @return void
*
******************************************************************************/
__interrupt void T4_Adm_IRQ (void);


/******************************************************************************
* @fn  culTimer4AdmSet
*
* @brief
*      This function arranges calling of the _callBackFunction_ at a desired
*      time interval in m-seconds. Up to _TIMER_ADM_TABLE_LENGTH_ different
*      functions can be set up to be run at different time intervals. This way
*      timer 4 is configured to run many interrupt routines at different time
*      intervals, thus leaving the other timers free to be configured as desired.
*
* Parameters:
*
* @param  DWORD	 timeout
*         The number of m-seconds between each time the _callBackFunction_
*         is run.
* @param  FUNCTION*	 callBackFunction
*         Pointer to the function to be run at the given interval. The
*         _callBackFunction_ must be of the type _void callBackFunction(void)_,
*         i.e. no arguments and no return value.
*
* @return BYTE
*         The entry number in the table. The value 0xFF indicates that an
*         error has occured and that the registration was unsuccessful. The
*         returned value must be used as an argument when the entry is to be
*         cleared using the function _culTimer4AdmClear(...)_.
*
******************************************************************************/
BYTE culTimer4AdmSet(DWORD timeout, FUNCTION* callBackFunction);



/******************************************************************************
* @fn  culTimer4AdmClear
*
* @brief
*      This function clears the table entry _entry_ from the table of functions
*      to be called at different timeouts.
*
* Parameters:
*
* @param  BYTE	 entry
*         The index number of the entry in the table that is to be cleared.
*         This value must be identical to the returned value from the function
*         _culTimer4AdmSet(...)_.
*
* @return void
*
******************************************************************************/
void culTimer4AdmClear(BYTE entry);



/******************************************************************************
* @fn  culTimer4AdmReset
*
* @brief
*      This function resets the counter of the entry in question.
*
* Parameters:
*
* @param  BYTE	 entry
*         The index number of the entry in the table that is reset. This value
*         must be identical to the returned value from the function
*         _culTimer4AdmSet(...)_.
*
* @return void
*
******************************************************************************/
void culTimer4AdmReset(BYTE entry);


/******************************************************************************
*******************      Simple Packet Protocol (SPP)      ********************
******************************************************************************/
#define SPP_MAX_PAYLOAD_LENGTH          122
#define SPP_HEADER_AND_FOOTER_LENGTH    5
#define SPP_FOOTER_LENGTH               2
#define SPP_ACK_LENGTH                  1

typedef struct{
    BYTE payloadLength;
    BYTE destAddress;
    BYTE flags;
    BYTE *payload;
}SPP_TX_STRUCT;

typedef struct{
    BYTE payloadLength;
    BYTE destAddress;
    BYTE srcAddress;
    BYTE flags;
    BYTE payload[SPP_MAX_PAYLOAD_LENGTH + SPP_FOOTER_LENGTH];
}SPP_RX_STRUCT;

#define BROADCAST_ADDRESS               0
#define WAIT_UNTIL_RECEIVE              0

#define SEQUENCE_BIT                    0x80
#define RETRANSMISSION                  0x04
#define ACK                             0x02
#define DO_ACK                          0x01
#define DO_NOT_ACK                      0x00


#define ACK_TIMEOUT                     15
#define ACK_RETRIES                     3

// TX status flags
#define TX_IN_PROGRESS                  0x80
#define TX_SUCCESSFUL                   0x40
#define DEST_UNREACHABLE                0x20
#define TX_IDLE                         0x00

// RX status flags
#define RX_IN_PROGRESS                  0x80
#define PACKET_RECEIVED                 0x40
#define RX_WAIT                         0x20
#define RX_COMPLETE                     0x10
#define RX_IDLE                         0x00

// sppSend return values
#define CHANNEL_BUSY                    0x04
#define TOO_LONG                        0x08



/******************************************************************************
* @fn  sppInit
*
* @brief
*      This function initialises the Simple Packet Protocol (SPP). Two DMA
*      channels are requested from the DMA administrator and set up to transfer
*      data to and from the Rx FiFo and Tx FiFo respectively. The Timer 4
*      administrator is also set up, and this unit will be used to generate
*      interrupts when a packet is not ACK'ed by the recipient whithin some time.