/**************************************************************************************************
    Filename:
    Revised:        $Date: 2007-03-26 16:18:09 -0700 (Mon, 26 Mar 2007) $
    Revision:       $Revision: 13860 $

    Description:

    Describe the purpose and contents of the file.

    Copyright (c) 2006 by Texas Instruments, Inc.
    All Rights Reserved.  Permission to use, reproduce, copy, prepare
    derivative works, modify, distribute, perform, display or sell this
    software and/or its documentation for any purpose is prohibited
    without the express written consent of Texas Instruments, Inc.
**************************************************************************************************/



/* ------------------------------------------------------------------------------------------------
 *                                           Includes
 * ------------------------------------------------------------------------------------------------
 */

/* hal */
#include "hal_types.h"
#include "hal_mcu.h"

/* high-level specific */
#include "mac_spec.h"

/* exported low-level */
#include "mac_low_level.h"

/* low-level specific */
#include "mac_backoff_timer.h"
#include "mac_tx.h"

/* target specific */
#include "mac_radio_defs.h"

/* debug */
#include "mac_assert.h"


/* ------------------------------------------------------------------------------------------------
 *                                            Defines
 * ------------------------------------------------------------------------------------------------
 */
#define COMPARE_STATE_ROLLOVER_BV                 BV(0)
#define COMPARE_STATE_TRIGGER_BV                  BV(1)
#define COMPARE_STATE_ARM_BV                      BV(2)

#define COMPARE_STATE_TRIGGER                     COMPARE_STATE_TRIGGER_BV
#define COMPARE_STATE_ROLLOVER                    COMPARE_STATE_ROLLOVER_BV
#define COMPARE_STATE_ROLLOVER_AND_TRIGGER        (COMPARE_STATE_ROLLOVER_BV | COMPARE_STATE_TRIGGER_BV)
#define COMPARE_STATE_ROLLOVER_AND_ARM_TRIGGER    (COMPARE_STATE_ROLLOVER_BV | COMPARE_STATE_ARM_BV)


/*
 *  The datasheet mentions a small delay on both receive and transmit side of approximately
 *  two microseconds.  The precise characterization is given below.
 *  (This data is not given in rev 1.03 datasheet)
 */
#define RX_TX_PROP_DELAY_AVG_USEC         ((MAC_RADIO_RX_TX_PROP_DELAY_MIN_USEC + MAC_RADIO_RX_TX_PROP_DELAY_MAX_USEC) / 2)
#define RX_TX_PROP_DELAY_AVG_TIMER_TICKS  ((uint16)(MAC_RADIO_TIMER_TICKS_PER_USEC() * RX_TX_PROP_DELAY_AVG_USEC + 0.5))

/*
 *  For slotted receives, the SFD signal is expected to occur on a specifc symbol boundary.
 *  This does *not* correspond to the backoff boundary.  The SFD signal occurs at an
 *  offset from the backoff boundary.  This is done for efficiency of related algorithms.
 *
 *  Once transmit is strobed there is a fixed delay until the SFD signal occurs.  The frame
 *  does not start over-the-air transmit until after an internal radio delay of 12 symbols.
 *  Once transmitting over-the-air, the preamble is sent (8 symbols) followed by the
 *  SFD field (2 symbols). After the SFD field completes, the SFD signal occurs.  This
 *  adds up to a total of 22 symbols from strobe to SFD signal.
 *
 *  Since 22 symbols spans more than a backoff (20 symbols) the modulus operation is used
 *  to find the symbol offset which is 2 symbols.
 *
 *  This math is derived formally via the pre-processor.
 */
#define SYMBOLS_FROM_STROBE_TO_PREAMBLE   12 /* from datasheet */
#define SYMBOLS_FROM_PREAMBLE_TO_SFD      (MAC_SPEC_PREAMBLE_FIELD_LENGTH + MAC_SPEC_SFD_FIELD_LENGTH)
#define SYMBOLS_FROM_STROBE_TO_SFD        (SYMBOLS_FROM_STROBE_TO_PREAMBLE + SYMBOLS_FROM_PREAMBLE_TO_SFD)
#define SYMBOLS_EXPECTED_AT_SFD           (SYMBOLS_FROM_STROBE_TO_SFD % MAC_A_UNIT_BACKOFF_PERIOD)

/* after all that formal math, make sure the result is as expected */
#if (SYMBOLS_EXPECTED_AT_SFD != 2)
#error "ERROR! Internal problem with pre-processor math of slotted alignment."
#endif


/*
 *  The expected SFD signal occurs at the symbol offset *plus* a small internal propagation delay
 *  internal to the radio.  This delay is given as the sum of a receive side delay and a transmit
 *  side delay.  When this delay is subtracted from the internal timer, the internal time base
 *  actually becomes the actual receive time *minus* the transmit delay.  This works out though.
 *  The transmit logic does *not* take into account this delay.  Since the timer is skewed by the
 *  transmit delay already, the transmits go out precisely on time.
 */
#define TIMER_TICKS_EXPECTED_AT_SFD   ((SYMBOLS_EXPECTED_AT_SFD * MAC_RADIO_TIMER_TICKS_PER_SYMBOL()) \
                                          + RX_TX_PROP_DELAY_AVG_TIMER_TICKS)


/* ------------------------------------------------------------------------------------------------
 *                                         Local Variables
 * ------------------------------------------------------------------------------------------------
 */
static uint32 backoffTimerRollover;
static uint32 backoffTimerTrigger;
static uint8 compareState;


/**************************************************************************************************
 * @fn          macBackoffTimerInit
 *
 * @brief       Intializes backoff timer.
 *
 * @param       none
 *
 * @return      none
 **************************************************************************************************
 */
void macBackoffTimerInit(void)
{
  compareState = COMPARE_STATE_ROLLOVER;
  MAC_RADIO_BACKOFF_SET_COUNT(0);
  macBackoffTimerSetRollover(MAC_BACKOFF_TIMER_DEFAULT_ROLLOVER);
  MAC_RADIO_BACKOFF_COMPARE_CLEAR_INTERRUPT();
  MAC_RADIO_BACKOFF_COMPARE_ENABLE_INTERRUPT();
}


/**************************************************************************************************
 * @fn          macBackoffTimerReset
 *
 * @brief       Resets backoff timer.
 *
 * @param       none
 *
 * @return      none
 **************************************************************************************************
 */
void macBackoffTimerReset(void)
{
  MAC_RADIO_BACKOFF_COMPARE_DISABLE_INTERRUPT();
  macBackoffTimerInit();
}


/**************************************************************************************************
 * @fn          macBackoffTimerSetRollover
 *
 * @brief       Set rollover count of backoff timer.
 *
 * @param       rolloverBackoff - backoff count where count is reset to zero
 *
 * @return      none
 **************************************************************************************************
 */
void macBackoffTimerSetRollover(uint32 rolloverBackoff)
{
  halIntState_t  s;

  MAC_ASSERT(rolloverBackoff > MAC_RADIO_BACKOFF_COUNT());  /* rollover value must be greater than count */

  HAL_ENTER_CRITICAL_SECTION(s);
  backoffTimerRollover = rolloverBackoff;
  MAC_RADIO_BACKOFF_SET_COMPARE(rolloverBackoff);
  HAL_EXIT_CRITICAL_SECTION(s);
}


/**************************************************************************************************
 * @fn          macBackoffTimerSetCount
 *
 * @brief       Sets the count of the backoff timer.
 *
 * @param       backoff - new count
 *
 * @return      none
 **************************************************************************************************
 */
void macBackoffTimerSetCount(uint32 backoff)
{
  halIntState_t  s;

  MAC_ASSERT(compareState == COMPARE_STATE_ROLLOVER);   /* trigger cannot be active if changing count */
  MAC_ASSERT(backoff < backoffTimerRollover);  /* count must be less than rollover value */

  HAL_ENTER_CRITICAL_SECTION(s);
  MAC_RADIO_BACKOFF_SET_COUNT(backoff);
  HAL_EXIT_CRITICAL_SECTION(s);
}


/**************************************************************************************************
 * @fn          macBackoffTimerCount
 *
 * @brief       Returns the current backoff count.
 *
 * @param       none
 *
 * @return      current backoff count
 **************************************************************************************************
 */
uint32 macBackoffTimerCount(void)
{
  halIntState_t  s;
  uint32 backoffCount;

  HAL_ENTER_CRITICAL_SECTION(s);
  backoffCount = MAC_RADIO_BACKOFF_COUNT();
  HAL_EXIT_CRITICAL_SECTION(s);
  
#ifdef MAC_RADIO_FEATURE_HARDWARE_OVERFLOW_NO_ROLLOVER
  /*
   *  Extra processing is required if the radio has a special hardware overflow
   *  count feature.  Unfortunately this feature does not provide for setting a
   *  rollover value.  This must be done manually.
   *
   *  This means there is a small window in time when reading the hardware count
   *  will be inaccurate.  It's possible it could be one more than the allowable
   *  count.  This happens if the count has just incremented beyond the maximum
   *  and is queried before the ISR has a chance to run and reset the backoff
   *  count back to zero.  (Pure software implementation of backoff count does
   *  not have this problem.)
   *
   *  To solve this, before returning a value for the backoff count, the value
   *  must be tested to see if it is beyond the maximum value.  If so, a rollover
   *  interrupt that will set backoff count to zero is imminent.  In that case,
   *  the correct backoff count of zero is returned.
   */
  if (backoffCount >= backoffTimerRollover)
  {
    return(0);
  }
#endif
  
  return(backoffCount);
}


/**************************************************************************************************
 * @fn          macBackoffTimerCapture
 *
 * @brief       Returns the most recently captured backoff count
 *