/*
|
* Copyright (c) 2019-2025 Beijing Hanwei Innovation Technology Ltd. Co. and
|
* its subsidiaries and affiliates (collectly called MKSEMI).
|
*
|
* All rights reserved.
|
*
|
* Redistribution and use in source and binary forms, with or without
|
* modification, are permitted provided that the following conditions are met:
|
*
|
* 1. Redistributions of source code must retain the above copyright notice,
|
* this list of conditions and the following disclaimer.
|
*
|
* 2. Redistributions in binary form, except as embedded into an MKSEMI
|
* integrated circuit in a product or a software update for such product,
|
* must reproduce the above copyright notice, this list of conditions and
|
* the following disclaimer in the documentation and/or other materials
|
* provided with the distribution.
|
*
|
* 3. Neither the name of MKSEMI nor the names of its contributors may be used
|
* to endorse or promote products derived from this software without
|
* specific prior written permission.
|
*
|
* 4. This software, with or without modification, must only be used with a
|
* MKSEMI integrated circuit.
|
*
|
* 5. Any software provided in binary form under this license must not be
|
* reverse engineered, decompiled, modified and/or disassembled.
|
*
|
* THIS SOFTWARE IS PROVIDED BY MKSEMI "AS IS" AND ANY EXPRESS OR IMPLIED
|
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
* MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
* DISCLAIMED. IN NO EVENT SHALL MKSEMI OR CONTRIBUTORS BE LIABLE FOR ANY
|
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
*/
|
|
#ifndef MK_UWB_H_
|
#define MK_UWB_H_
|
#include "mk_common.h"
|
#include "mk_mac.h"
|
#include "mk_phy.h"
|
|
/**
|
* @addtogroup MK8000_UWB
|
* @{
|
*/
|
|
#ifndef RANGING_EN
|
#if defined(FIRA_RANGING_EN) || defined(CCC_RANGING_EN) || defined(CUSTOM_RANGING_EN) || defined(UL_TDOA_EN)
|
#define RANGING_EN (1)
|
#else
|
#define RANGING_EN (0)
|
#endif
|
#endif
|
|
/* Receiver antenna mode: Port Num in use (2 bits) | Ant Num in use (2 bits) | Index (2 bits) | Main Rx Ant (2 bits) */
|
// 4-Antennas, for high band (CH5/CH9)
|
#define RX_4PORTS_ANT_3_0_1_2 0xF3
|
// 4-Antennas, for low band (CH2/CH3)
|
#define RX_4PORTS_ANT_2_3_0_1 0xF2
|
|
// 3-Antennas, Add for dynamic main rx antenna selection, select 3 from 4 ports - Skip ANT2 (CH5/CH9) from algorithm - main ANT3
|
#define RX_4PORTS_ANT_3_0_1 0xE3
|
// 3-Antennas, Add for dynamic main rx antenna selection, select 3 from 4 ports - Skip ANT3 (CH2/CH3) from algorithm - main ANT2
|
#define RX_4PORTS_ANT_2_0_1 0xE2
|
|
// 3-Antennas, Add for PDoA
|
#define RX_3PORTS_ANT_3_0_1 0xA3
|
// 3-Antennas, for AoA
|
#define RX_3PORTS_ANT_1_2_3 0xA1
|
// 3-Antennas, Add for PDoA
|
#define RX_3PORTS_ANT_0_1_2 0xA0
|
|
// 2-Antennas
|
#define RX_2PORTS_ANT_3_0 0x53
|
// 2-Antennas
|
#define RX_2PORTS_ANT_2_3 0x52
|
// 2-Antennas
|
#define RX_2PORTS_ANT_1_2 0x51
|
|
// 1-Antenna
|
#define RX_1PORT_ANT_3 0x03
|
// 1-Antenna
|
#define RX_1PORT_ANT_2 0x02
|
// 1-Antenna
|
#define RX_1PORT_ANT_1 0x01
|
// 1-Antenna
|
#define RX_1PORT_ANT_0 0x00
|
|
/* Receiver antenna port Num = 1, 2, 3, 4 */
|
#define RX_ANT_PORTS_NUM (((RX_ANT_PORTS_COMBINATION >> 6) & 0x3) + 1)
|
/* Receiver main antenna port = 0, 1, 2, 3 */
|
#define RX_MAIN_ANT_PORT (RX_ANT_PORTS_COMBINATION & 0x3)
|
|
/* Antenna pattern */
|
#define ANT_PATTERN_LINEAR 0
|
#define ANT_PATTERN_SQUARE 1
|
#define ANT_PATTERN_TRIANGLE_REGULAR 2
|
#define ANT_PATTERN_TRIANGLE_L 3
|
|
#ifndef ANT_PATTERN
|
#define ANT_PATTERN (ANT_PATTERN_LINEAR)
|
#endif
|
|
#ifndef UWB_CH_NUM
|
#define UWB_CH_NUM 9
|
#endif
|
|
#ifndef RX_ANT_PORTS_COMBINATION
|
#define RX_ANT_PORTS_COMBINATION RX_1PORT_ANT_3
|
#endif
|
|
#if (UWB_CH_NUM == 5) || (UWB_CH_NUM == 9)
|
#if ((RX_ANT_PORTS_NUM == 4) && (RX_MAIN_ANT_PORT == 2)) || ((RX_ANT_PORTS_NUM == 3) && (RX_MAIN_ANT_PORT == 0))
|
#error "RX main antenna is mismatch with high band channel"
|
#endif
|
#elif (UWB_CH_NUM == 2) || (UWB_CH_NUM == 3)
|
#if ((RX_ANT_PORTS_NUM == 4 || RX_ANT_PORTS_NUM == 3 || RX_ANT_PORTS_NUM == 2) && (RX_MAIN_ANT_PORT == 3))
|
#error "RX main antenna is mismatch with low band channel"
|
#endif
|
#endif
|
|
/** UWB Channel number */
|
enum CH_NUM_T
|
{
|
CH_2 = 2, // 4G
|
CH_5 = 5, // 6.5G
|
CH_9 = 9, // 8G
|
};
|
|
/** UWB TX power level */
|
enum TX_PWR_LVL_T
|
{
|
TX_PWR_LVL_0 = 0,
|
TX_PWR_LVL_1,
|
TX_PWR_LVL_2,
|
TX_PWR_LVL_3,
|
TX_PWR_LVL_4,
|
TX_PWR_LVL_5,
|
TX_PWR_LVL_6,
|
TX_PWR_LVL_7,
|
TX_PWR_LVL_8,
|
TX_PWR_LVL_9,
|
TX_PWR_LVL_10,
|
TX_PWR_LVL_11,
|
TX_PWR_LVL_12,
|
TX_PWR_LVL_13,
|
TX_PWR_LVL_14,
|
TX_PWR_LVL_15, // max power level
|
};
|
|
/** UWB RX antenna port */
|
enum UWB_RX_ANT_T
|
{
|
UWB_RX_ANT_0 = 0x00,
|
UWB_RX_ANT_1 = 0x01,
|
UWB_RX_ANT_2 = 0x02,
|
UWB_RX_ANT_3 = 0x03,
|
UWB_RX_ANT_ALL = 0xFF,
|
};
|
|
enum ANT_LAYOUT_T
|
{
|
ANT_LAYOUT_HORIZONTAL = 0,
|
ANT_LAYOUT_VERTICAL,
|
};
|
|
/**
|
* @brief Enumeration for UWB transmission modes.
|
*/
|
enum UWB_TX_MODE_T
|
{
|
TX_MODE_IMMEDIATE = 0, /*!< Immediate transmission mode */
|
TX_MODE_DEFER = 1, /*!< Deferred transmission mode */
|
TX_MODE_CSMACA = 2, /*!< CSMA-CA transmission mode */
|
};
|
|
/**
|
* @brief Enumeration for UWB reception modes.
|
*/
|
enum UWB_RX_MODE_T
|
{
|
RX_MODE_IMMEDIATE = 0, /*!< Immediate reception mode */
|
RX_MODE_DEFER = 1, /*!< Deferred reception mode */
|
};
|
|
#ifdef __cplusplus
|
extern "C" {
|
#endif
|
|
/**
|
* @brief Open UWB transceiver.
|
*/
|
int uwb_open(void);
|
|
/**
|
* @brief Close UWB transceiver.
|
*/
|
int uwb_close(void);
|
|
/**
|
* @brief Open antenna port.
|
* @param[in] antenna_idx Antenna port to be open @ref UWB_RX_ANT_T
|
*/
|
void uwb_rx_antenna_open(enum UWB_RX_ANT_T antenna_idx);
|
|
/**
|
* @brief Switch UWB channel.
|
* @param[in] ch_num Channel number
|
*/
|
void uwb_channel_switch(uint8_t ch_num);
|
|
/**
|
* @brief Set UWB pulse shape.
|
* @param[in] pulse_shape Pulse shape (0x0 - Symmetrical pulse, 0x1/0x2 - Precursor-Free)
|
* @note This API is used for CCC pulse shape setting
|
*/
|
void uwb_pulse_shape_set(uint8_t pulse_shape);
|
|
/**
|
* @brief Set UWB pulse width.
|
* @param[in] width Pulse width (0x0 - 2ns(500M), 0x3 - 0.92ns(900M), 0x2 - 0.75ns(1.3G))
|
* @note This API is used for UWB pulse width setting, it will change the setting of pulse shaping
|
*/
|
void uwb_pulse_width_set(uint8_t width);
|
|
/**
|
* @brief Set UWB TX power.
|
* @param[in] tx_power_level TX power level
|
*/
|
void uwb_tx_power_set(uint8_t tx_power_level);
|
|
/**
|
* @brief Get UWB TX power.
|
* @param[in] ch_num Channel number
|
* @param[in] tx_power_level TX power level
|
* @return UWB power in dBm
|
*/
|
int8_t uwb_tx_power_get(uint8_t ch_num, uint8_t tx_power_level);
|
|
/**
|
* @brief Set calibration parameters.
|
* @param[in] ch_num channel number.
|
*/
|
void uwb_calibration_params_set(uint8_t ch_num);
|
|
/**
|
* @brief Configure UWB transceiver work at TX or RX mode.
|
* @param[in] mode Work mode, PHY_TX or PHY_RX or both.
|
* @param[in] tx_power_level TX power level
|
* @param[in] ppdu_params PHY protocol data unit parameters @ref UWB_CONFIG_T
|
*/
|
void uwb_configure(uint8_t mode, uint8_t tx_power_level, struct UWB_CONFIG_T *ppdu_params);
|
|
/**
|
* @brief Switch the PHY parameter sets.
|
* @param[in] mode Work mode, PHY_TX or PHY_RX or both.
|
* @param[in] sets PHY parameter sets to be set
|
*/
|
void uwb_params_sets_switch(uint8_t mode, void *sets);
|
|
/**
|
* @brief UWB transmit a packet.
|
* @param[in] pkt_data Pointer to packet data to be sent
|
* @param[in] pkt_len Packet length
|
* @param[in] scheduled_mode Transmission scheduling mode @ref UWB_TX_MODE_T
|
* @param[in] tgt_time Target time to send packet, if target time equals 0 means send immediately.
|
* @return programmed TX event number, the maximum TX event number depends on configuration from mac_init()
|
*/
|
int uwb_tx(uint8_t *pkt_data, uint16_t pkt_len, uint8_t scheduled_mode, uint32_t target_time);
|
|
/**
|
* @brief Receive a UWB packet.
|
* @param[in] scheduled_mode Reception scheduling mode @ref UWB_RX_MODE_T
|
* @param[in] tgt_time Target time to receive packet
|
* @param[in] timeout Maximum receive window, unit: PHY timer count 1/124.8M
|
* @return programmed RX event number, the maximum RX event number depends on configuration from mac_init()
|
*/
|
int uwb_rx(uint8_t scheduled_mode, uint32_t target_time, uint32_t timeout);
|
|
/**
|
* @brief UWB loopback.
|
* @param[in] pkt_data Pointer to packet data to be sent
|
* @param[in] pkt_len Packet length
|
* @param[in] scheduled_mode Transmission scheduling mode @ref UWB_TX_MODE_T
|
* @param[in] tgt_time Target time to send packet, if target time equals 0 means send immediately.
|
* @return programmed TX event number, the maximum TX event number depends on configuration from mac_init()
|
*/
|
int uwb_loopback(uint8_t *pkt_data, uint16_t pkt_len, uint8_t scheduled_mode, uint32_t target_time);
|
|
/**
|
* @brief Force switch off UWB Rx.
|
* @param[in] int_rpt_dis Discard current RX interrupt report
|
*/
|
void uwb_rx_force_off(bool int_rpt_dis);
|
|
/**
|
* @brief Configure UWB transceiver work at TX carrier only mode.
|
* @param[out] on Enable or disable TX carrier only mode
|
* @param[out] ch_num Channel number
|
* @param[out] tx_power_level TX power level
|
*/
|
void uwb_tx_carrier_only(uint8_t on, uint8_t ch_num, uint8_t tx_power_level);
|
|
/**
|
* @brief Configure UWB transceiver work at blocking TX mode for testing purpose.
|
* @param[in] pkt_data Pointer to packet data to be sent
|
* @param[in] pkt_len Packet length
|
* @param[in] timeout_us Blocking time, 0 means infinite loop
|
*/
|
void uwb_blocking_tx_start(const uint8_t *pkt_data, uint16_t pkt_len, uint32_t timeout_ms);
|
|
/**
|
* @brief Configure UWB transceiver work at blocking RX mode for testing purpose.
|
* @param[in] timeout_us Blocking time, 0 means infinite loop
|
* @param[in] callback Callback to report receiving result
|
*/
|
void uwb_blocking_rx_start(uint32_t timeout_us, drv_callback_t callback);
|
|
/**
|
* @brief Stop blocking TX or RX mode.
|
*/
|
void uwb_blocking_trx_stop(void);
|
|
/**
|
* @brief Update UWB loopback time, the result is the avarage value of the count times
|
* @note This API will change UWB configuration, please call uwb_configure() to restore the configuration.
|
* @param[in] count Loopback count, one loopback test time is around 2ms
|
* @param[in] ppdu_params PHY protocol data unit parameters @ref UWB_CONFIG_T
|
*/
|
void uwb_loopback_time_update(uint16_t count, struct UWB_CONFIG_T *ppdu_params);
|
|
/**
|
* @brief Find a suitable Vdd core voltage value and measure the UWB TX and RX loopback time for antenna delay calibration
|
* @note This API should be called after power_init(), suggests to do loopback calibration before antenna delay calibration.
|
* @param[in] wr_nvm_en Enable calibration result written into NVM
|
* @param[in] count Loopback count, one loopback test time is around 2ms
|
* @param[in] ppdu_params PHY protocol data unit parameters @ref UWB_CONFIG_T
|
*/
|
void uwb_loopback_calibration(uint8_t wr_nvm_en, uint16_t count, struct UWB_CONFIG_T *ppdu_params);
|
|
#ifdef __cplusplus
|
}
|
#endif
|
|
/**
|
* @}
|
*/
|
|
#endif /* MK_UWB_H_ */
|
