AMiRo-OS

/*! ------------------------------------------------------------------------------------------------------------------

 * @file    deca_device.c

 * @brief   Decawave device configuration and control functions

 *

 * @attention

 *

 * Copyright 2013 (c) Decawave Ltd, Dublin, Ireland.

 *

 * All rights reserved.

 *

 */

#include <assert.h>

#include <stdlib.h>

#include "deca_types.h"

#include "deca_param_types.h"

#include "deca_regs.h"

#include "deca_device_api.h"

// Defines for enable_clocks function

#define FORCE_SYS_XTI  0

#define ENABLE_ALL_SEQ 1

#define FORCE_SYS_PLL  2

#define READ_ACC_ON    7

#define READ_ACC_OFF   8

#define FORCE_OTP_ON   11

#define FORCE_OTP_OFF  12

#define FORCE_TX_PLL   13

#define FORCE_LDE      14

// Defines for ACK request bitmask in DATA and MAC COMMAND frame control (first byte) - Used to detect AAT bit wrongly set.

#define FCTRL_ACK_REQ_MASK 0x20

// Frame control maximum length in bytes.

#define FCTRL_LEN_MAX 2

// #define DWT_API_ERROR_CHECK     // define so API checks config input parameters

// -------------------------------------------------------------------------------------------------------------------

//

// Internal functions for controlling and configuring the device

//

// -------------------------------------------------------------------------------------------------------------------

// Enable and Configure specified clocks

void _dwt_enableclocks(int clocks) ;

// Configure the ucode (FP algorithm) parameters

void _dwt_configlde(int prf);

// Load ucode from OTP/ROM

void _dwt_loaducodefromrom(void);

// Read non-volatile memory

uint32 _dwt_otpread(uint16 address);

// Program the non-volatile memory

uint32 _dwt_otpprogword32(uint32 data, uint16 address);

// Upload the device configuration into always on memory

void _dwt_aonarrayupload(void);

// -------------------------------------------------------------------------------------------------------------------

/*!

 * Static data for DW1000 DecaWave Transceiver control

 */

// -------------------------------------------------------------------------------------------------------------------

// Structure to hold device data

typedef struct

{

    uint32      partID ;            // IC Part ID - read during initialisation

    uint32      lotID ;             // IC Lot ID - read during initialisation

    uint8       vBatP ;             // IC V bat read during production and stored in OTP (Vmeas @ 3V3)

    uint8       tempP ;             // IC V temp read during production and stored in OTP (Tmeas @ 23C)

    uint8       longFrames ;        // Flag in non-standard long frame mode

    uint8       otprev ;            // OTP revision number (read during initialisation)

    uint32      txFCTRL ;           // Keep TX_FCTRL register config

    uint32      sysCFGreg ;         // Local copy of system config register

    uint8       dblbuffon;          // Double RX buffer mode flag

    uint8       wait4resp ;         // wait4response was set with last TX start command

    uint16      sleep_mode;         // Used for automatic reloading of LDO tune and microcode at wake-up

    uint16      otp_mask ;          // Local copy of the OTP mask used in dwt_initialise call

    dwt_cb_data_t cbData;           // Callback data structure

    dwt_cb_t    cbTxDone;           // Callback for TX confirmation event

    dwt_cb_t    cbRxOk;             // Callback for RX good frame event

    dwt_cb_t    cbRxTo;             // Callback for RX timeout events

    dwt_cb_t    cbRxErr;            // Callback for RX error events

} dwt_local_data_t ;

static dwt_local_data_t dw1000local[DWT_NUM_DW_DEV] ; // Static local device data, can be an array to support multiple DW1000 testing applications/platforms

static dwt_local_data_t *pdw1000local = dw1000local ; // Static local data structure pointer

/*! ------------------------------------------------------------------------------------------------------------------

 * @fn dwt_apiversion()

 *

 * @brief This function returns the version of the API as defined by DW1000_DRIVER_VERSION

 *

 * input parameters

 *

 * output parameters

 *

 * returns version (DW1000_DRIVER_VERSION)

 */

int32 dwt_apiversion(void)

{

    return DW1000_DRIVER_VERSION ;

}

/*! ------------------------------------------------------------------------------------------------------------------

 * @fn dwt_setlocaldataptr()

 *

 * @brief This function sets the local data structure pointer to point to the element in the local array as given by the index.

 *

 * input parameters

 * @param index    - selects the array element to point to. Must be within the array bounds, i.e. < DWT_NUM_DW_DEV

 *

 * output parameters

 *

 * returns DWT_SUCCESS for success, or DWT_ERROR for error

 */

int dwt_setlocaldataptr(unsigned int index)

{

    // Check the index is within the array bounds

    if (DWT_NUM_DW_DEV <= index) // return error if index outside the array bounds

    {

        return DWT_ERROR ;

    }

    pdw1000local = &dw1000local[index];

    return DWT_SUCCESS ;

}

/*! ------------------------------------------------------------------------------------------------------------------

 * @fn dwt_initialise()

 *

 * @brief This function initiates communications with the DW1000 transceiver

 * and reads its DEV_ID register (address 0x00) to verify the IC is one supported

 * by this software (e.g. DW1000 32-bit device ID value is 0xDECA0130).  Then it

 * does any initial once only device configurations needed for its use and initialises

 * as necessary any static data items belonging to this low-level driver.

 *

 * This function does not need to be called after DW1000 device is woken up from DEEPSLEEP,

 * the device will preserve register values e.g. LDO, UCODE, XTAL. However if needed this

 * function can be called to initialise internal structure  dw1000local[] if it has not been preserved

 * (e.g. if micro was in sleep and its RAM data (containing dw1000local structure was not preserved during sleep)

 *

 * NOTES:

 * 1. When DW1000 is powered on this function needs to be run before dwt_configuresleep,

 *    also the SPI frequency has to be < 3MHz

 * 2. It reads and applies LDO tune and crystal trim values from OTP memory

 * 3. If accurate RX timestamping is needed microcode/LDE must be loaded

 *

 * input parameters

 * @param config    -   specifies what configuration to load

 *                  DWT_LOADNONE         0x00 - do not load any values from OTP memory

 *                  DWT_LOADUCODE        0x01 - load the LDE microcode from ROM - enable accurate RX timestamp

 *                  DWT_DW_WAKE_UP       0x02 - just initialise dw1000local[] values (e.g. DW1000 has woken up)

 *                  DWT_DW_WUP_NO_UCODE  0x04 - if microcode/LDE algorithm has not already been loaded (on power up) e.g. when LDE is not used

 *                  DWT_READ_OTP_PID     0x10 - read part ID from OTP

 *                  DWT_READ_OTP_LID     0x20 - read lot ID from OTP

 *                  DWT_READ_OTP_BAT     0x40 - read ref voltage from OTP

 *                  DWT_READ_OTP_TMP     0x80 - read ref temperature from OTP

 * output parameters

 *

 * returns DWT_SUCCESS for success, or DWT_ERROR for error

 */

// OTP addresses definitions

#define LDOTUNE_ADDRESS (0x04)

#define PARTID_ADDRESS (0x06)

#define LOTID_ADDRESS  (0x07)

#define VBAT_ADDRESS   (0x08)

#define VTEMP_ADDRESS  (0x09)

#define XTRIM_ADDRESS  (0x1E)

int dwt_initialise(int config)

{

    uint16 otp_xtaltrim_and_rev = 0;

    uint32 ldo_tune = 0;

    pdw1000local->dblbuffon = 0; // - set to 0 - meaning double buffer mode is off by default

    pdw1000local->wait4resp = 0; // - set to 0 - meaning wait for response not active

    pdw1000local->sleep_mode = 0; // - set to 0 - meaning sleep mode has not been configured

    pdw1000local->cbTxDone = NULL;

    pdw1000local->cbRxOk = NULL;

    pdw1000local->cbRxTo = NULL;

    pdw1000local->cbRxErr = NULL;

#if DWT_API_ERROR_CHECK

    pdw1000local->otp_mask = config ; // Save the READ_OTP config mask

#endif

    // Read and validate device ID, return -1 if not recognised

    if (DWT_DEVICE_ID != dwt_readdevid()) // MP IC ONLY (i.e. DW1000) FOR THIS CODE

    {

        return DWT_ERROR ;

    }

    if(!(DWT_DW_WAKE_UP & config)) // Don't reset the device if DWT_DW_WAKE_UP bit is set, e.g. when calling this API after wake up

    {

        dwt_softreset(); // Make sure the device is completely reset before starting initialisation

    }

    if(!((DWT_DW_WAKE_UP & config) && ((DWT_READ_OTP_TMP | DWT_READ_OTP_BAT | DWT_READ_OTP_LID | DWT_READ_OTP_PID | DWT_DW_WUP_RD_OTPREV)& config)))

    {

        _dwt_enableclocks(FORCE_SYS_XTI); // NOTE: set system clock to XTI - this is necessary to make sure the values read by _dwt_otpread are reliable

    }                                  // when not reading from OTP, clocks don't need to change.

    // Configure the CPLL lock detect

    dwt_write8bitoffsetreg(EXT_SYNC_ID, EC_CTRL_OFFSET, EC_CTRL_PLLLCK);

    // When DW1000 IC is initialised from power up, then the LDO value should be kicked from OTP, otherwise if this API is called after

    // DW1000 IC has been woken up (DWT_DW_WAKE_UP bit is set) this can be skipped as LDO would have already been automatically

    // kicked/loaded on wake up

    if(!(DWT_DW_WAKE_UP & config))

    {

        // Load LDO tune from OTP and kick it if there is a value actually programmed.

        ldo_tune = _dwt_otpread(LDOTUNE_ADDRESS);

        if((ldo_tune & 0xFF) != 0)

        {

            // Kick LDO tune

            dwt_write8bitoffsetreg(OTP_IF_ID, OTP_SF, OTP_SF_LDO_KICK); // Set load LDO kick bit

            pdw1000local->sleep_mode |= AON_WCFG_ONW_LLDO; // LDO tune must be kicked at wake-up

        }

    }

    else

    {   //if LDOTUNE reg contains value different from default it means it was kicked from OTP and thus set AON_WCFG_ONW_LLDO.

        if(dwt_read32bitoffsetreg(RF_CONF_ID, LDOTUNE) != LDOTUNE_DEFAULT)

            pdw1000local->sleep_mode |= AON_WCFG_ONW_LLDO;

    }

    if((!(DWT_DW_WAKE_UP & config)) || ((DWT_DW_WAKE_UP & config) && (DWT_DW_WUP_RD_OTPREV & config)))

    {

        // Read OTP revision number

        otp_xtaltrim_and_rev = _dwt_otpread(XTRIM_ADDRESS) & 0xffff;        // Read 32 bit value, XTAL trim val is in low octet-0 (5 bits)

        pdw1000local->otprev = (otp_xtaltrim_and_rev >> 8) & 0xff;          // OTP revision is the next byte

    }

    else

        pdw1000local->otprev = 0; // If OTP valuse are not used, if this API is called after DW1000 IC has been woken up

                                  // (DWT_DW_WAKE_UP bit is set), set otprev to 0

    if(!(DWT_DW_WAKE_UP & config))

    {

        // XTAL trim value is set in OTP for DW1000 module and EVK/TREK boards but that might not be the case in a custom design

        if ((otp_xtaltrim_and_rev & 0x1F) == 0) // A value of 0 means that the crystal has not been trimmed

        {

            otp_xtaltrim_and_rev = FS_XTALT_MIDRANGE ; // Set to mid-range if no calibration value inside

        }

        // Configure XTAL trim

        dwt_setxtaltrim((uint8)otp_xtaltrim_and_rev);

    }

    if(DWT_READ_OTP_PID & config)

    {

        // Load Part from OTP

        pdw1000local->partID = _dwt_otpread(PARTID_ADDRESS);

    }

    else

    {

        pdw1000local->partID = 0;

    }

    if(DWT_READ_OTP_LID & config)

    {

        // Load Lot ID from OTP

        pdw1000local->lotID = _dwt_otpread(LOTID_ADDRESS);

    }

    else

    {

        pdw1000local->lotID = 0;

    }

    if(DWT_READ_OTP_BAT & config)

    {

        // Load VBAT from OTP

        pdw1000local->vBatP = _dwt_otpread(VBAT_ADDRESS) & 0xff;

    }

    else

    {

        pdw1000local->vBatP = 0;

    }

    if(DWT_READ_OTP_TMP & config)

    {

        // Load TEMP from OTP

        pdw1000local->tempP = _dwt_otpread(VTEMP_ADDRESS) & 0xff;

    }

    else

    {

        pdw1000local->tempP = 0;

    }

    // Load leading edge detect code (LDE/microcode)

    if(!(DWT_DW_WAKE_UP & config))

    {

        if(DWT_LOADUCODE & config)

        {

            _dwt_loaducodefromrom();

            pdw1000local->sleep_mode |= AON_WCFG_ONW_LLDE; // microcode must be loaded at wake-up if loaded on initialisation

        }

        else // Should disable the LDERUN bit enable if LDE has not been loaded

        {

            uint16 rega = dwt_read16bitoffsetreg(PMSC_ID, PMSC_CTRL1_OFFSET+1) ;

            rega &= 0xFDFF ; // Clear LDERUN bit

            dwt_write16bitoffsetreg(PMSC_ID, PMSC_CTRL1_OFFSET+1, rega) ;

        }

    }

    else //if DWT_DW_WUP_NO_UCODE is set then assume that the UCODE was loaded from ROM (i.e. DWT_LOADUCODE was set on power up),

    {     //thus set AON_WCFG_ONW_LLDE, otherwise don't set the AON_WCFG_ONW_LLDE bit in the sleep_mode configuration

        if((DWT_DW_WUP_NO_UCODE & config) == 0)

        {

            pdw1000local->sleep_mode |= AON_WCFG_ONW_LLDE;

        }

    }

    _dwt_enableclocks(ENABLE_ALL_SEQ); // Enable clocks for sequencing

    // The 3 bits in AON CFG1 register must be cleared to ensure proper operation of the DW1000 in DEEPSLEEP mode.

    dwt_write8bitoffsetreg(AON_ID, AON_CFG1_OFFSET, 0x00);

    // Read system register / store local copy

    pdw1000local->sysCFGreg = dwt_read32bitreg(SYS_CFG_ID) ; // Read sysconfig register

    pdw1000local->longFrames = (pdw1000local->sysCFGreg & SYS_CFG_PHR_MODE_11) >> SYS_CFG_PHR_MODE_SHFT ; //configure longFrames

    pdw1000local->txFCTRL = dwt_read32bitreg(TX_FCTRL_ID) ;

    return DWT_SUCCESS ;

} // end dwt_initialise()

/*! ------------------------------------------------------------------------------------------------------------------

 * @fn dwt_otprevision()

 *

 * @brief This is used to return the read OTP revision

 *

 * NOTE: dwt_initialise() must be called prior to this function so that it can return a relevant value.

 *

 * input parameters

 *

 * output parameters

 *

 * returns the read OTP revision value

 */

uint8 dwt_otprevision(void)

{

    return pdw1000local->otprev ;

}

/*! ------------------------------------------------------------------------------------------------------------------

 * @fn dwt_setfinegraintxseq()

 *

 * @brief This function enables/disables the fine grain TX sequencing (enabled by default).

 *

 * input parameters