ifr_radio.h

00001 /*
00002  * Copyright (c) 2015, Freescale Semiconductor, Inc.
00003  * Copyright 2016-2017 NXP
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  * o Redistributions of source code must retain the above copyright notice, this list
00009  *   of conditions and the following disclaimer.
00010  *
00011  * o Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
00016  *   contributors may be used to endorse or promote products derived from this
00017  *   software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00020  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00023  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00026  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  */
00030 #ifndef __IFR_RADIO_H__
00031 /* clang-format off */
00032 #define __IFR_RADIO_H__
00033 /* clang-format on */
00034 
00035 #include <stdint.h>
00036 /* clang-format off */
00037 #define _FSL_XCVR_H_
00038 /* clang-format on */
00039 
00040 /*!
00041  * @addtogroup xcvr
00042  * @{
00043  */
00044 
00045 /*! @file*/
00046 
00047 /*******************************************************************************
00048  * Definitions
00049  ******************************************************************************/
00050 #define IFR_EOF_SYMBOL          (0xFEED0E0FU) /* < Denotes the "End of File" for IFR data */
00051 #define IFR_VERSION_HDR         (0xABCD0000U) /* < Constant value for upper 16 bits of IFR data header */
00052 #define IFR_VERSION_MASK        (0x0000FFFFU) /* < Mask for version number (lower 16 bits) of IFR data header */
00053 #define IFR_SW_ID_MIN           (0x00000000U) /* < Lower limit of SW trim IDs */
00054 #define IFR_SW_ID_MAX           (0x0000FFFFU) /* < Lower limit of SW trim IDs */
00055 
00056 #define IS_A_SW_ID(x)           ((IFR_SW_ID_MIN < (x)) && (IFR_SW_ID_MAX >= (x)))
00057 
00058 /* K3 valid registers support */
00059 #if (defined(CPU_K32W042S1M2CAx_M0P) || defined(CPU_K32W042S1M2VPJ_M0P))
00060 #define IS_VALID_REG_ADDR(x)    (((x) & 0xFFFF0000U) == 0x41000000U) /* Valid addresses are 0x410xxxxx */
00061 #endif /* (defined(CPU_K32W042S1M2CAx_M0P) || defined(CPU_K32W042S1M2VPJ_M0P)) */
00062 /* KW41 and KW35/36 valid registers support */
00063 #if (defined(CPU_MKW41Z256VHT4) || defined(CPU_MKW41Z512VHT4) || \
00064      defined(CPU_MKW31Z256VHT4) || defined(CPU_MKW31Z512VHT4) || \
00065      defined(CPU_MKW21Z256VHT4) || defined(CPU_MKW21Z512VHT4) || \
00066      defined(CPU_MKW35A512VFP4) || defined(CPU_MKW36A512VFP4) )
00067 
00068 #define IS_VALID_REG_ADDR(x)    (((x) & 0xFFFF0000U) == 0x40050000U) /* Valid addresses are 0x4005xxxx */
00069 #endif
00070 
00071 #define MAKE_MASK(size)         ((1 << (size)) - 1)
00072 #define MAKE_MASKSHFT(size, bitpos)  (MAKE_MASK(size) << (bitpos))
00073 
00074 #define IFR_TZA_CAP_TUNE_MASK           (0x0000000FU)
00075 #define IFR_TZA_CAP_TUNE_SHIFT          (0)
00076 #define IFR_BBF_CAP_TUNE_MASK           (0x000F0000U)
00077 #define IFR_BBF_CAP_TUNE_SHIFT          (16)
00078 #define IFR_RES_TUNE2_MASK              (0x00F00000U)
00079 #define IFR_RES_TUNE2_SHIFT             (20)
00080 
00081 /* \var  typedef uint8_t IFR_ERROR_T */
00082 /* \brief  The IFR error reporting type. */
00083 /* See #IFR_ERROR_T_enum for the enumeration definitions. */
00084 typedef uint8_t IFR_ERROR_T;
00085 
00086 /* \brief  The enumerations used to describe IFR errors. */
00087 enum IFR_ERROR_T_enum
00088 {
00089     IFR_SUCCESS = 0,
00090     INVALID_POINTER = 1, /* < NULL pointer error */
00091     INVALID_DEST_SIZE_SHIFT = 2, /* < the bits won't fit as specified in the destination */
00092 };
00093 
00094 /* \var  typedef uint16_t SW_TRIM_ID_T */
00095 /* \brief  The SW trim ID type. */
00096 /* See #SW_TRIM_ID_T_enum for the enumeration definitions. */
00097 typedef uint16_t SW_TRIM_ID_T;
00098 
00099 /* \brief  The enumerations used to define SW trim IDs. */
00100 enum SW_TRIM_ID_T_enum
00101 {
00102     Q_RELATIVE_GAIN_BY_PART = 0, /* < Q vs I relative gain trim ID */
00103     ADC_GAIN = 1, /* < ADC gain trim ID */
00104     ZB_FILT_TRIM = 2, /* < Baseband Bandwidth filter trim ID for BLE */
00105     BLE_FILT_TRIM = 3, /* < Baseband Bandwidth filter trim ID for BLE */
00106     TRIM_STATUS = 4, /* < Status result of the trim process (error indications) */
00107     TRIM_VERSION = 0xABCD, /* < Version number of the IFR trim algorithm/format. */
00108 };
00109 
00110 /* \var  typedef uint32_t IFR_TRIM_STATUS_T */
00111 /* \brief  The definition of failure bits stored in IFR trim status word. */
00112 /* See #IFR_TRIM_STATUS_T_enum for the enumeration definitions. */
00113 typedef uint32_t IFR_TRIM_STATUS_T;
00114 
00115 /* \brief  The enumerations used to describe trim algorithm failures in the status entry in IFR. */
00116 /* This enum represents multiple values which can be OR'd together in a single status word. */
00117 enum IFR_TRIM_STATUS_T_enum
00118 {
00119     TRIM_ALGORITHM_SUCCESS = 0,
00120     BGAP_VOLTAGE_TRIM_FAILED = 1, /* < algorithm failure in BGAP voltagetrim */
00121     IQMC_GAIN_ADJ_FAILED = 2, /* < algorithm failure in IQMC gain trim */
00122     IQMC_PHASE_ADJ_FAILED = 4, /* < algorithm failure in IQMC phase trim */
00123     IQMC_DC_GAIN_ADJ_FAILED = 8, /* < */
00124     ADC_GAIN_TRIM_FAILED = 10, /* <*/
00125     ZB_FILT_TRIM_FAILED = 20, /* < */
00126     BLE_FILT_TRIM_FAILED = 40, /* < */
00127 };
00128 
00129 /* \var  typedef struct IFR_SW_TRIM_TBL_ENTRY_T */
00130 /* \brief  Structure defining an entry in a table used to contain values to be passed back from IFR */
00131 /*  handling routine to XCVR driver software. */
00132 typedef struct
00133 {
00134     SW_TRIM_ID_T trim_id; /* < The assigned ID */
00135     uint32_t trim_value; /* < The value fetched from IFR.*/
00136     uint8_t valid; /* < validity of the trim_value field after IFR processing is complete (TRUE/FALSE).*/
00137 } IFR_SW_TRIM_TBL_ENTRY_T;
00138 
00139 /*******************************************************************************
00140  * API
00141  ******************************************************************************/
00142 /*!
00143  * @brief Reads a location in block 1 IFR for use by the radio.
00144  *
00145  * This function handles reading IFR data from flash memory for trim loading.
00146  *
00147  * @param read_addr the address in the IFR to be read.
00148  */ 
00149 uint32_t read_resource_ifr(uint32_t read_addr);
00150 
00151 /*!
00152  * @brief Reads a location in a simulated data array to support IFR handler testing.
00153  *
00154  * This function handles reading  data from a const table for testing the trim loading functions.
00155  *
00156  * @param read_addr the address in the IFR to be read.
00157  */ 
00158 uint32_t read_resource(uint16_t resource_id);
00159 
00160 /*!
00161  * @brief Main IFR handler function called by XCVR driver software to process trim table.
00162  *
00163  * This function handles reading  data from IFR and either loading to registers or storing to a SW trim values table.
00164  *
00165  * @param sw_trim_tbl pointer to the table used to store software trim values.
00166  * @param num_entries the number of entries that can be stored in the SW trim table.
00167  */ 
00168 void handle_ifr(IFR_SW_TRIM_TBL_ENTRY_T * sw_trim_tbl, uint16_t num_entries);
00169 
00170 /*!
00171  * @brief Handler function to read die_id from IFR locations..
00172  *
00173  * This function handles reading die ID value for debug and testing usage.
00174  *
00175  * @return the value of the die ID field.
00176  */ 
00177 uint32_t handle_ifr_die_id(void);
00178 
00179 /*!
00180  * @brief Handler function to read KW chip version from IFR locations..
00181  *
00182  * This function handles reading KW chip version for debug and testing usage.
00183  *
00184  * @return the value of the KW version field.
00185  */ 
00186 uint32_t handle_ifr_die_kw_type(void);
00187 
00188 /*!
00189  * @brief Debug function to dump the IFR contents to a RAM array.
00190  *
00191  * This function handles reading  data from IFR and storing to a RAM array for debug.
00192  *
00193  * @param dump_tbl pointer to the table used to store IFR entry values.
00194  * @param num_entries the number of entries that can be stored in the dump table.
00195  */ 
00196 void dump_ifr(uint32_t * dump_tbl, uint8_t num_entries);
00197 
00198 #endif /*__IFR_RADIO_H__ */
00199