Linux UWB Stack实现——MCPS接口
本专栏主要介绍在Linux内核中的UWB Stack的实现，整体基于IEEE 802.15.4框架，采用Qorvo UWB芯片DW3000，开源协议版本为GPLv2。
在本篇文章中，主要介绍MCPS接口的定义，MCPS（MAC Common Part Sublayer，MAC公共部分子层）。
关于mcps802154.h
为MCPS接口相关定义，主要包括一些一些结构体的定义，主要包括底层驱动的连接，收发数据帧等，相关结构体定义如下：
struct mcps802154_llhw，不带MCPS的底层硬件，必须使用mcps802154_alloc_llhw()函数进行分配，然后底层驱动程序应对其进行初始化。struct mcps802154_tx_frame_info，用于传输帧的信息。struct mcps802154_rx_info，使能接收机的信息。struct mcps802154_rx_frame_info，接收到数据帧的信息。struct mcps802154_sts_params，HPR UWB的STS参数。struct mcps802154_ops，MCPS从底层驱动程序的回调函数。
mcps802154_llhw
struct mcps802154_llhw {
/**
* @dtu_freq_hz: Inverse of device time unit duration, in Hz.
*/
int dtu_freq_hz;
/**
* @symbol_dtu: Symbol duration in device time unit, can change if radio
* parameters are changed. Can be set to 1 if device time unit is the
* symbol.
*/
int symbol_dtu;
/**
* @cca_dtu: CCA duration in device time unit, can change if radio
* parameters or CCA modes are changed.
*/
int cca_dtu;
/**
* @shr_dtu: Synchronisation header duration in device time unit, can
* change if radio parameters are changed. If ranging is supported, this
* is the difference between the RMARKER and the first frame symbol.
*/
int shr_dtu;
/**
* @dtu_rctu: Duration of one device time unit in ranging counter time
* unit (RDEV only).
*/
int dtu_rctu;
/**
* @rstu_dtu: Duration of ranging slot time unit in device time unit
* (ERDEV only).
*/
int rstu_dtu;
/**
* @anticip_dtu: Reasonable delay between reading the current timestamp
* and doing an operation in device time unit.
*/
int anticip_dtu;
/**
* @idle_dtu: Duration long enough to prefer entering the idle mode
* rather than trying to find a valid access.
*/
int idle_dtu;
/**
* @flags: Low-level hardware flags, see &enum mcps802154_llhw_flags.
*/
u32 flags;
/**
* @hw: Pointer to IEEE802154 hardware exposed by MCPS. The low-level
* driver needs to update this and hw->phy according to supported
* hardware features and radio parameters. More specifically:
*
* * &ieee802154_hw.extra_tx_headroom
* * in &ieee802154_hw.flags:
*
* * IEEE802154_HW_TX_OMIT_CKSUM
* * IEEE802154_HW_RX_OMIT_CKSUM
* * IEEE802154_HW_RX_DROP_BAD_CKSUM
*
* * &wpan_phy.flags
* * &wpan_phy_supported
* * &wpan_phy.symbol_duration
*/
struct ieee802154_hw *hw;
/**
* @priv: Driver private data.
*/
void *priv;
};
mcps802154_tx_frame_info
enum mcps802154_tx_frame_info_flags {
MCPS802154_TX_FRAME_TIMESTAMP_DTU = BIT(0),
MCPS802154_TX_FRAME_CCA = BIT(1),
MCPS802154_TX_FRAME_RANGING = BIT(2),
MCPS802154_TX_FRAME_KEEP_RANGING_CLOCK = BIT(3),
MCPS802154_TX_FRAME_SP1 = BIT(4),
MCPS802154_TX_FRAME_SP2 = BIT(5),
MCPS802154_TX_FRAME_SP3 = BIT(4) | BIT(5),
MCPS802154_TX_FRAME_STS_MODE_MASK = BIT(4) | BIT(5),
};
struct mcps802154_tx_frame_info {
/**
* @timestamp_dtu: If timestamped, date of transmission start.
*/
u32 timestamp_dtu;
/**
* @rx_enable_after_tx_dtu: If positive, enable receiver this number of
* device time unit after the end of the transmitted frame.
*/
int rx_enable_after_tx_dtu;
/**
* @rx_enable_after_tx_timeout_dtu: When receiver is enabled after the
* end of the transmitted frame: if negative, no timeout, if zero, use
* a default timeout value, else this is the timeout value in device
* time unit.
*/
int rx_enable_after_tx_timeout_dtu;
/**
* @flags: See &enum mcps802154_tx_frame_info_flags.
*/
u8 flags;
/**
* @ant_id: antenna index to use for transmit.
*/
int ant_id;
};
mcps802154_rx_info
enum mcps802154_rx_info_flags {
MCPS802154_RX_INFO_TIMESTAMP_DTU = BIT(0),
MCPS802154_RX_INFO_AACK = BIT(1),
MCPS802154_RX_INFO_RANGING = BIT(2),
MCPS802154_RX_INFO_KEEP_RANGING_CLOCK = BIT(3),
MCPS802154_RX_INFO_SP1 = BIT(4),
MCPS802154_RX_INFO_SP2 = BIT(5),
MCPS802154_RX_INFO_SP3 = BIT(4) | BIT(5),
MCPS802154_RX_INFO_STS_MODE_MASK = BIT(4) | BIT(5),
};
struct mcps802154_rx_info {
/**
* @timestamp_dtu: If timestamped, date to enable the receiver.
*/
u32 timestamp_dtu;
/**
* @timeout_dtu: 负数，无超时；0，默认超时；正数为设定的超时时间
*/
int timeout_dtu;
/**
* @flags: See &enum mcps802154_rx_info_flags.
*/
u8 flags;
/**
* @ant_pair_id: 用于接收的天线配对索引
*/
u8 ant_pair_id;
};
mcps802154_rx_frame_info
接收帧信息相关。
接收帧信息标志包括测距时间戳、LQI、RSSI、测距FOM、PDOA、STS等相关的接收帧标志。
- RCTU（Ranging Count Time Unit，测距计数单元），用于测距应用，基础时间单位约为15 ps，仅支持测距的设备支持。
- DTU，Device Time Unit，设备时钟单元。
enum mcps802154_rx_frame_info_flags {
MCPS802154_RX_FRAME_INFO_TIMESTAMP_DTU = BIT(0),
MCPS802154_RX_FRAME_INFO_TIMESTAMP_RCTU = BIT(1),
MCPS802154_RX_FRAME_INFO_LQI = BIT(2),
MCPS802154_RX_FRAME_INFO_RSSI = BIT(3),
MCPS802154_RX_FRAME_INFO_RANGING_FOM = BIT(4),
MCPS802154_RX_FRAME_INFO_RANGING_OFFSET = BIT(5),
MCPS802154_RX_FRAME_INFO_RANGING_PDOA = BIT(6),
MCPS802154_RX_FRAME_INFO_RANGING_PDOA_FOM = BIT(7),
MCPS802154_RX_FRAME_INFO_RANGING_STS_TIMESTAMP_RCTU = BIT(8),
MCPS802154_RX_FRAME_INFO_RANGING_STS_FOM = BIT(9),
MCPS802154_RX_FRAME_INFO_AACK = BIT(10),
};
struct mcps802154_rx_frame_info {
/**
* @timestamp_dtu: Timestamp of start of frame in device time unit.
*/
u32 timestamp_dtu;
/**
* @timestamp_rctu: Timestamp of RMARKER in ranging count time unit
* (RDEV only).
*/
u64 timestamp_rctu;
/**
* @frame_duration_dtu: Duration of the whole frame in device time unit
* or 0 if unknown.
*/
int frame_duration_dtu;
int rssi;
/**
* @ranging_tracking_interval_rctu: Interval on which tracking offset
* was measured (RDEV only).
*/
int ranging_tracking_interval_rctu;
/**
* @ranging_offset_rctu: Difference between the transmitter and the
* receiver clock measure over the tracking interval, if positive, the
* transmitter operates at a higher frequency (RDEV only).
*/
int ranging_offset_rctu;
/**
* @ranging_pdoa_rad_q11: Phase difference of arrival, unit is radian
* multiplied by 2048 (RDEV only).
*/
int ranging_pdoa_rad_q11;
/**
* @ranging_pdoa_spacing_mm_q11: Spacing between antennas, unit is mm
* multiplied by 2048 (RDEV only).
*/
int ranging_pdoa_spacing_mm_q11;
/**
* @ranging_sts_timestamp_diffs_rctu: For each SRMARKERx, difference
* between the measured timestamp and the expected timestamp relative to
* RMARKER in ranging count time unit (ERDEV only). When STS mode is
* 1 or 3, SRMARKER0 is the same as RMARKER and difference is always 0.
*/
s16 ranging_sts_timestamp_diffs_rctu[MCPS802154_STS_N_SEGS_MAX + 1];
/**
* @lqi: Link quality indicator (LQI).
*/
u8 lqi;
/**
* @ranging_fom: Ranging figure of merit (FoM, RDEV only). Should be
* formatted according to 802.15.4.
*/
u8 ranging_fom;
/**
* @ranging_pdoa_fom: Phase difference of arrival figure of merit (FoM,
* RDEV only). Range is 0 to 255, with 0 being an invalid measure and
* 255 being a 100% confidence.
*/
u8 ranging_pdoa_fom;
/**
* @ranging_sts_fom: Table of figures of merit measuring the correlation
* strength between the received STS segment and the expected one (FoM,
* ERDEV only). Range is 0 to 255, with 0 being an invalid measure and
* 255 being a 100% confidence.
*/
u8 ranging_sts_fom[MCPS802154_STS_N_SEGS_MAX];
/**
* @flags: See &enum mcps802154_rx_frame_info_flags.
*/
u16 flags;
};
mcps802154_sts_params
HRP UWB的STS参数，包括用在DRBG中生成STS的Value与key，以及STS段的数量以及每个段内STS的长度（FiRa、CCC的标准中通常使用1个STS段，长度为64个Symbol）。
另外，针对SP2模式帧格式，定义了STS与payload之间的附加gap信息。
struct mcps802154_sts_params {
/**
* @v: Value V used in DRBG for generating the STS. The 32 LSB are the
* VCounter which is incremented every 128 generated pulse.
*/
u8 v[AES_BLOCK_SIZE];
/**
* @key: STS AES key used in DRBG for generating the STS.
*/
u8 key[AES_KEYSIZE_128];
int n_segs;
int seg_len;
/**
* @sp2_tx_gap_4chips: For SP2 frame format, additional gap in unit of
* 4 chips between the end of the payload and the start of the STS, used
* for TX.
*/
int sp2_tx_gap_4chips;
/**
* @sp2_rx_gap_4chips: For SP2 frame format, additional gap in unit of
* 4 chips between the end of the payload and the start of the STS, used
* for RX. A0 and A1 bits in PHR are used to index the array.
*/
int sp2_rx_gap_4chips[MCPS802154_STS_N_SEGS_MAX];
};
mcps802154_ops
定义了底层驱动相关的实现接口回调，包括初始化底层设备、停止、发送、接收等常规操作接口。
struct mcps802154_ops {
/**
* @start: Initialize device. Reception should not be activated.
*/
int (*start)(struct mcps802154_llhw *llhw);
/**
* @stop: Stop device. Should stop any transmission or reception and put
* the device in a low power mode.
*/
void (*stop)(struct mcps802154_llhw *llhw);
/**
* @tx_frame: Transmit a frame. skb应包含从IEEE 802.15.4帧头开始的数据。底层驱动将根据设定发送帧信息发送。接收机应在没有收到帧的情况下自动关闭。
*
* @next_delay_dtu : 表示预期发送帧开始和下一动作之间的延迟时间
*
*/
int (*tx_frame)(struct mcps802154_llhw *llhw, struct sk_buff *skb,
const struct mcps802154_tx_frame_info *info,
int next_delay_dtu);
/**
* @rx_enable: 使能接收机。
* @next_delay_dtu: 表示预期从开始接受帧或帧接收超时之间的时间。
*/
int (*rx_enable)(struct mcps802154_llhw *llhw,
const struct mcps802154_rx_info *info,
int next_delay_dtu);
/**
* @rx_disable: Disable receiver
*/
int (*rx_disable)(struct mcps802154_llhw *llhw);
/**
* @rx_get_frame: Get previously received frame. MCPS calls this handler
* after a frame reception has been signaled by the low-level driver.
*
* The received buffer is owned by MCPS after this call. Only the
* requested information need to be filled in the information structure.
*
*/
int (*rx_get_frame)(struct mcps802154_llhw *llhw, struct sk_buff **skb,
struct mcps802154_rx_frame_info *info);
/**
* @rx_get_error_frame: Get information on rejected frame. MCPS can call
* this handler after a frame rejection has been signaled by the
* low-level driver.
*/
int (*rx_get_error_frame)(struct mcps802154_llhw *llhw,
struct mcps802154_rx_frame_info *info);
/**
* @idle: Put the device into idle mode without time limit or until the
* given timestamp. The driver should call &mcps802154_timer_expired()
* before the given timestamp so that an action can be programmed at the
* given timestamp.
*
* The &mcps802154_timer_expired() function must not be called
* immediately from this callback, but should be scheduled to be called
* later.
*
* If the driver is late, the regular handling of late actions will take
* care of the situation.
*/
int (*idle)(struct mcps802154_llhw *llhw, bool timestamp,
u32 timestamp_dtu);
/**
* @reset: Reset device after an unrecoverable error.
*/
int (*reset)(struct mcps802154_llhw *llhw);
/**
* @get_current_timestamp_dtu: Get current timestamp in device time
* unit.
*
* If the device is currently in a low power state, the eventual wake up
* delay should be added to the returned timestamp.
*
* If the current timestamp can not be determined precisely, it should
* return a pessimistic value, i.e. rounded up.
*/
int (*get_current_timestamp_dtu)(struct mcps802154_llhw *llhw,
u32 *timestamp_dtu);
/**
* @timestamp_dtu_to_rctu: Convert a timestamp in device time unit to
* a timestamp in ranging counter time unit.
*/
u64 (*timestamp_dtu_to_rctu)(struct mcps802154_llhw *llhw,
u32 timestamp_dtu);
/**
* @timestamp_rctu_to_dtu: Convert a timestamp in ranging counter time
* unit to a timestamp in device time unit.
*/
u32 (*timestamp_rctu_to_dtu)(struct mcps802154_llhw *llhw,
u64 timestamp_rctu);
/**
* @tx_timestamp_dtu_to_rmarker_rctu: Compute the RMARKER timestamp in
* ranging counter time unit for a frame transmitted at given timestamp
* in device time unit (RDEV only).
*
* Return: The RMARKER timestamp.
*/
u64 (*tx_timestamp_dtu_to_rmarker_rctu)(struct mcps802154_llhw *llhw,
u32 tx_timestamp_dtu,
int ant_id);
/**
* @difference_timestamp_rctu: Compute the difference between two
* timestamp values.
*
* Return: The difference between A and B.
*/
s64 (*difference_timestamp_rctu)(struct mcps802154_llhw *llhw,
u64 timestamp_a_rctu,
u64 timestamp_b_rctu);
/**
* @compute_frame_duration_dtu: Compute the duration of a frame with
* given payload length (header and checksum included) using the current
* radio parameters.
*
* Return: The duration in device time unit.
*/
int (*compute_frame_duration_dtu)(struct mcps802154_llhw *llhw,
int payload_bytes);
/**
* @set_channel: Set channel parameters.
*/
int (*set_channel)(struct mcps802154_llhw *llhw, u8 page, u8 channel,
u8 preamble_code);
/**
* @set_hrp_uwb_params: Set radio parameters for HRP UWB.
*
* The parameters in &mcps802154_llhw can change according to radio
* parameters.
*/
int (*set_hrp_uwb_params)(struct mcps802154_llhw *llhw, int prf,
int psr, int sfd_selector, int phr_rate,
int data_rate);
/**
* @set_sts_params: Set STS parameters (ERDEV only).
*/
int (*set_sts_params)(struct mcps802154_llhw *llhw,
const struct mcps802154_sts_params *params);
/**
* @set_hw_addr_filt: Set hardware filter parameters.
*/
int (*set_hw_addr_filt)(struct mcps802154_llhw *llhw,
struct ieee802154_hw_addr_filt *filt,
unsigned long changed);
/**
* @set_txpower: Set transmission power.
*/
int (*set_txpower)(struct mcps802154_llhw *llhw, s32 mbm);
/**
* @set_cca_mode: Set CCA mode.
*
* The CCA duration in &mcps802154_llhw can change according to CCA
* mode.
*/
int (*set_cca_mode)(struct mcps802154_llhw *llhw,
const struct wpan_phy_cca *cca);
/**
* @set_cca_ed_level: Set CCA energy detection threshold.
*/
int (*set_cca_ed_level)(struct mcps802154_llhw *llhw, s32 mbm);
/**
* @set_promiscuous_mode: Set promiscuous mode.
*/
int (*set_promiscuous_mode)(struct mcps802154_llhw *llhw, bool on);
/**
* @set_scanning_mode: Set SW scanning mode.
*/
int (*set_scanning_mode)(struct mcps802154_llhw *llhw, bool on);
/**
* @set_calibration: Set calibration value.
*
* Set the calibration parameter specified by the key string with the
* value specified in the provided buffer. The provided length must
* match the length returned by the @get_calibration() callback.
*/
int (*set_calibration)(struct mcps802154_llhw *llhw, const char *key,
void *value, size_t length);
/**
* @get_calibration: Get calibration value.
*
* Get the calibration parameter specified by the key string into the
* provided buffer.
*
* Return: size of parameter written in buffer or error.
*/
int (*get_calibration)(struct mcps802154_llhw *llhw, const char *key,
void *value, size_t length);
/**
* @list_calibration: Returns list of accepted calibration key strings.
*/
const char *const *(*list_calibration)(struct mcps802154_llhw *llhw);
/**
* @vendor_cmd: 运行一个供应商特定命令。Run a vendor specific command.
*/
int (*vendor_cmd)(struct mcps802154_llhw *llhw, u32 vendor_id,
u32 subcmd, void *data, size_t data_len);
#ifdef CONFIG_MCPS802154_TESTMODE
/**
* @testmode_cmd: Run a testmode command.
*/
int (*testmode_cmd)(struct mcps802154_llhw *llhw, void *data, int len);
#endif
};