keil/include/drivers/mk_phy.h
@@ -1,5 +1,5 @@
/*
 * Copyright (c) 2019-2023 Beijing Hanwei Innovation Technology Ltd. Co. and
 * Copyright (c) 2019-2025 Beijing Hanwei Innovation Technology Ltd. Co. and
 * its subsidiaries and affiliates (collectly called MKSEMI).
 *
 * All rights reserved.
@@ -54,23 +54,27 @@
/** us to PHY timer count converter, x <= 3,441,480 us */
#define US_TO_PHY_TIMER_COUNT(x) ((x)*1248U / 10U)
/** us to PHY timer count converter, x <= 34,414,802 us */
#define US_TO_PHY_TIMER_COUNT_LL(x) ((uint32_t)((uint64_t)(x)*1248U / 10U))
/** ms to PHY timer count converter x <= 34,414 ms */
#define MS_TO_PHY_TIMER_COUNT(x) ((x)*124800U)
/** PHY timer count to us converter, resolution 10us */
#define PHY_TIMER_COUNT_TO_US(x) (((x) / 1248U) * 10U)
/** PHY timer count to us converter, allow long long type multiply operation to promote precision */
#define PHY_TIMER_COUNT_TO_US_LL(x) (uint32_t)(((uint64_t)(x)*10U / 1248U))
#define PHY_TIMER_COUNT_TO_US_LL(x) ((uint32_t)((uint64_t)(x)*10U / 1248U))
/** PHY timer count to ms converter */
#define PHY_TIMER_COUNT_TO_MS(x) ((x) / 124800U)
/** PHY timer count to MAC timer count converter */
#define PHY_TIMER_COUNT_TO_MAC_TIMER_COUNT(x) ((x) >> 1)
/** ms to MAC timer count converter x <= 68,829 ms */
#define MS_TO_MAC_TIMER_COUNT(x) ((x)*62400U)
/** RSTU to PHY timer count converter, x <= 41,297,762 RSTU */
#define RSTU_TO_PHY_TIMER_COUNT(x) ((x)*104U)
/** RSTU to us converter, x <= 429,496,729 RSTU */
/** RSTU to us converter */
#define RSTU_TO_US(x) ((x)*10U / 12U)
/** RSTU to ms converter */
#define RSTU_TO_MS(x) ((x) / 1200U)
@@ -78,21 +82,18 @@
/** Timestamp unit is 15.65ps */
#define TIMESTAMP_UNIT_TO_NS(x) ((x) * (1000 / 499.2 / 128))
/// MeanPRF 62.4M, Data rate 6.8M, x=preamble length, y=SFD length, z=payload length
/** MeanPRF 62.4M, Data rate 6.8M, x=preamble length, y=SFD length, z=payload length */
#define PHY_SP0_FRAME_TIME_US(x, y, z) ((((x) + (y)) * 508 + 21 * 512 + ((((z)*8) / 330) * (378) + (((z)*8) % 330) + 48) * 64) / 499 + 1)
/// MeanPRF 62.4M, Data rate 6.8M, x=preamble length, y=SFD length, z=payload length, s=STS length
/** MeanPRF 62.4M, Data rate 6.8M, x=preamble length, y=SFD length, z=payload length, s=STS length */
#define PHY_FRAME_TIME_US(x, y, z, s) ((((x) + (y)) * 508 + 21 * 512 + ((((z)*8) / 330) * (378) + (((z)*8) % 330) + 48) * 64 + (s)*512 + 1024) / 499 + 1)
/** sleep count to PHY timer count converter */
#define SLEEP_COUNT_TO_PHY_TIMER_COUNT(x) ((uint32_t)((float)(x) * (124800000.0f / 32768.0f)))
/** The maximum sleep time of PHY, 10s */
#define PHY_SLEEP_TIME_MS_MAX (10000U)
/** PHY timer count to sleep count converter */
#define PHY_TIMER_COUNT_TO_SLEEP_COUNT(x) ((uint32_t)((float)(x) * (32768.0f / 124800000.0f)))
/** The minimum sleep time of PHY, 2000us */
#define PHY_SLEEP_TIME_US_MIN (2000U)
/// Low power mode clock drift compensation for phy timer count, p = ppm, t = interval(ms)
/** Low power mode clock drift compensation for phy timer count, p = ppm, t = interval(ms) */
#define LPM_PPM_COMPENSATION(p, t) ((p)*2 * (t)*1248 / 10000)
#define TX_PAYLOAD_ADDR 0x02080000
@@ -154,6 +155,7 @@
/// Non-standard SFD
#define NON_STD_NSFD5_8 5
#define NON_STD_NSFD6_16 6
#define NON_STD_NSFD7_64 7
#define HPRF_PSDU_SIZE_1023 0
#define HPRF_PSDU_SIZE_2047 1
@@ -175,18 +177,25 @@
#define STS_PKT_CFG_3 3
/// STS_SEGNUM
/// BPRF: 0 - 1
/// HPRF: 0 - 1, 1 - 2, 2 - 3 (optional), 3 - 4 (optional)
/// BPRF: 0 - 1, 1 - 2 (optional), 2 - 3 (optional), 3 - 4 (optional)
#define STS_SEGNUM_BPRF_1 0
#define STS_SEGNUM_BPRF_2 1
#define STS_SEGNUM_BPRF_3 2
#define STS_SEGNUM_BPRF_4 3
/// HPRF: 0 - 1, 1 - 2, 2 - 3 (optional), 3 - 4 (optional)
#define STS_SEGNUM_HPRF_1 0
#define STS_SEGNUM_HPRF_2 1
#define STS_SEGNUM_HPRF_3 2
#define STS_SEGNUM_HPRF_4 3
/// STS_SEGLEN
/// BPRF: 2 - 64
/// HPRF: 0 - 16 (optional), 1 - 32, 2 - 64, 3 - 128, 4 - 256 (optional)
/// BPRF: 0 - 16 (optional), 1 - 32 (optional), 2 - 64, 3 - 128 (optional), 4 - 256 (optional)
#define STS_SEGLEN_BPRF_16 0
#define STS_SEGLEN_BPRF_32 1
#define STS_SEGLEN_BPRF_64 2
#define STS_SEGLEN_BPRF_128 3
#define STS_SEGLEN_BPRF_256 4
/// HPRF: 0 - 16 (optional), 1 - 32, 2 - 64, 3 - 128, 4 - 256 (optional)
#define STS_SEGLEN_HPRF_16 0
#define STS_SEGLEN_HPRF_32 1
#define STS_SEGLEN_HPRF_64 2
@@ -199,6 +208,7 @@
    PHY_IDLE = 0,
    PHY_TX = 1,
    PHY_RX = 2,
    PHY_TRX = 3,
};
/** PHY protocol data unit parameters */
@@ -217,8 +227,13 @@
    uint8_t sts_pkt_cfg;
    uint8_t sts_segnum;
    uint8_t sts_seglen;
    uint8_t rx_ant_id;
    uint8_t rx_main_ant;
    uint8_t fcs_type;
    uint8_t pulse_shape;
    uint8_t rx_ant_mode;
    uint32_t phy_params_container[128];
};
/** STS key configuration*/
@@ -308,8 +323,10 @@
extern "C" {
#endif
extern const float ch_center_freq_map[16];
extern const float uwb_ch_freq_table[16];
extern const uint8_t rx_ant_code[4];
extern struct UWB_CONFIG_T uwb_ppdu_params;
extern struct PHY_USER_CONFIG_T phy_user_params;
/**
@@ -318,6 +335,12 @@
 * @return 0 represent intialization successful
 */
int phy_init(enum IRQ_PRIORITY_LEVEL_T priority);
/**
 * @brief De-initialize PHY, disable PHY interrupt.
 * @return 0 represent de-intialization successful
 */
int phy_deinit(void);
/**
 * @brief Register PHY interrupt callback function.
@@ -333,28 +356,20 @@
void phy_trx_mode_set(uint8_t mode);
/**
 * @brief Enable PHY parameter sets.
 * @param[in] sets              PHY parameter sets to be enabled, if input NULL the default parameter sets will be used
 */
void phy_params_sets_enable(void *sets);
/**
 * @brief Generate PHY parameters Configuration.
 * @param[in] mode              Work mode, PHY_TX or PHY_RX or both
 * @param[in] high_pfm_en       Enable or disable high performance mode
 * @param[in] config            PHY protocol data unit parameters @ref UWB_CONFIG_T
 * @param[in] sets              Specify a buffer to store the parameter sets, if input NULL the default parameter sets buffer will be used,
 *                              the buffer size is 128 Words, i.e. uint32_t sets[128]
 * @return the pointer of input parameter sets, if input parameter sets is NULL, the default parameter sets pointer will be returned
 */
void *phy_params_generate(uint8_t mode, uint8_t high_pfm_en, const struct UWB_CONFIG_T *config, void *sets);
/**
 * @brief Configure PHY adv parameters.
 * @note This API should be called before uwb_configure()
 * @param[in] config            PHY advanced configuration parameters @ref PHY_ADV_CONFIG_T
 * @return 0 represent configure successfully
 */
int phy_adv_params_configure(struct PHY_ADV_CONFIG_T *adv_config);
/**
 * @brief Configure PHY parameters.
 * @param[in] mode              Work mode, PHY_TX or PHY_RX or both
 * @param[in] high_pfm_en       Enable or disable high performance mode
 * @param[in] config            PHY protocol data unit parameters @ref UWB_CONFIG_T
 */
void phy_params_configure(uint8_t mode, uint8_t high_pfm_en, struct UWB_CONFIG_T *config);
/**
 * @brief Configure PHY parameters for user scenarios.
@@ -370,14 +385,14 @@
 * @param[in] sets              PHY parameter sets to be set, if input NULL the default parameter sets will be set
 * @return 0 represent configure successfully
 */
int phy_tx_regs_config(void *sets);
int phy_tx_params_set(void *sets);
/**
 * @brief Configure PHY receiver registers.
 * @param[in] sets              PHY parameter sets to be set, if input NULL the default parameter sets will be set
 * @return 0 represent configure successfully
 */
int phy_rx_regs_config(void *sets);
int phy_rx_params_set(void *sets);
/**
 * @brief Set ranging bit in PHY header.
@@ -404,18 +419,6 @@
void phy_restore(void *sets);
/**
 * @brief Set receiver antenna mode.
 * @param[in] mode              Receiver antenna mode @ref macro definition RX_xPORTS_ANT_xxx
 */
void phy_rx_ant_mode_set(uint8_t mode);
/**
 * @brief Set AoA symbol count.
 * @param[in] cnt               AoA symbol count, 0x30 or 0x40
 */
void phy_aoa_sym_cnt_set(uint16_t cnt);
/**
 * @brief Set STS packet configuration.
 * @param[in] cfg               STS packet configuration, 0 ~ 3
 */
@@ -423,9 +426,24 @@
/**
 * @brief Set STS key configuration.
 * @note This API should be called after uwb_configure()
 * @param[in] sts               STS key configuration @ref UWB_STS_KEY_CONFIG_T
 */
void phy_sts_key_configure(struct UWB_STS_KEY_CONFIG_T *sts);
/**
 * @brief Update the STS IV counter.
 *
 * @note This function can operate in two modes:
 * 1. Auto-increment mode: Calculate step size based on PHY configuration and accumulate
 * 2. Direct set mode: Set counter directly using specified value
 *
 * @param action Operation mode selection:
 *               - Non-zero: Auto-increment mode, calculate step size dynamically
 *               - Zero: Direct set mode, use the value of iv_counter parameter
 * @param iv_counter Counter value used in direct set mode, ignored in auto-increment mode
 */
void phy_update_sts_iv_counter(uint8_t action, uint32_t iv_counter);
/**
 * @brief Set STS RX antenna switching mode (AoA).
@@ -458,8 +476,15 @@
int phy_timer_close(void);
/**
 * @brief Calculate time duation from start to end.
 * @param[in] start             Start time (124.8MHz clock)
 * @param[in] end               End time (124.8MHz clock)
 */
uint32_t phy_time_gap(uint32_t start, uint32_t end);
/**
 * @brief Set a target time for the PHY timer.
 * @param[in] target            Target time (124.8MHz clock).
 * @param[in] target            Target time (124.8MHz clock)
 * @param[in] callback          Callback function for the target time
 */
void phy_timer_target_set(uint32_t target, drv_callback_t callback);
@@ -481,6 +506,12 @@
 * @return  PHY timer left count (124.8MHz clock).
 */
uint32_t phy_timer_count_left(void);
/**
 * @brief Convert the PHY timer left count to sleep count.
 * @return  sleep count (32KHz clock).
 */
uint32_t phy_timer_lp_tick_left(void);
/**
 * @brief Pause the PHY timer.
@@ -561,6 +592,39 @@
 */
void enter_debug_mode(void);
/**
 * @brief Enable antenna port switching based on AGC gain
 * @param[in] en                    Enable or disable
 * @param[in] rf_gain               LNA gain
 * @param[in] bb_gain               Filter gain
 * @return Rx antenna ID
 */
uint8_t phy_rx_ant_sw(uint8_t en, uint8_t rf_gain, uint8_t bb_gain);
/**
 * @brief Set AGC threshold
 * @param[in] high_th               AGC high threshold
 * @param[in] low_th                AGC low threshold
 */
void phy_agc_th_set(uint8_t high_th, uint8_t low_th);
/**
 * @brief Set CE configuration
 * @param[in] sym_per_blk           symbol per block
 * @param[in] bd_th                 preamble detection threshold
 * @param[in] ce_avg                CE average index
 * @param[in] ce_start              CE start symbol
 */
void phy_preamble_ce_set(uint16_t sym_per_blk, uint32_t bd_th, uint8_t ce_avg, uint8_t ce_start);
/**
 * @brief Set preamble code index
 * @param[in] work_mode             PHY_TX mode or PHY_RX mode
 * @param[in] code_idx              Preamble code index
 * @return 0: sucess, -1: error
 */
int phy_preamble_code_idx_set(enum PHY_WORK_MODE_T work_mode, uint8_t code_idx);
#ifdef __cplusplus
}
#endif