nearlink_sdr.mac.qos

MAC 层服务质量管理 -- TXS-10002-2025 标准 6.5/7.2

实现异步/同步数据链路的数据传输质量控制:

• ARQ 自动重传请求: 序列号管理、ACK/NACK 反馈、重传决策 (6.5.1)

• HARQ 混合自动重传: 基于 TB 和 CBG 的反馈模式 (6.5.1.1)

• 流控: 发送缓冲区管理与流控信令 (控制信息 flow_ctrl 字段)

• 链路质量跟踪: MCS 反馈、FER 估计、AMC 建议 (控制信息 LQI 字段)

• 发送队列: 优先级分级与 PDU 管理

Module Contents

Classes

ArqState	ARQ 序列号与重传状态。
FeedbackMode	HARQ 反馈模式。
FlowController	发送流控管理器。
HarqController	混合自动重传请求控制器。
LinkQualityTracker	链路质量跟踪与 AMC 建议。
LinkType	数据链路类型。
Priority	数据传输优先级 (数值越小优先级越高)。
QosManager	QoS 服务质量管理器。
TxDecision	发送决策。
TxQueue	优先级发送队列。
TxQueueItem	发送队列项。

Data

MAX_CBG
MAX_SN_FT1
MAX_SN_FT2
MAX_SN_FT34

API

nearlink_sdr.mac.qos.MAX_CBG

8

nearlink_sdr.mac.qos.MAX_SN_FT1

2

nearlink_sdr.mac.qos.MAX_SN_FT2

2

nearlink_sdr.mac.qos.MAX_SN_FT34

32

class nearlink_sdr.mac.qos.ArqState

ARQ 序列号与重传状态。

标准 6.5.1.1 描述的异步数据链路传输流程:

• tx_sn: 当前发送序列号

• expected_rx_sn: 期望接收的对端序列号

• pending_ack: 当前等待 ACK 的数据是否未确认

• retransmit_count: 当前包的重传次数

• max_retransmit: 最大重传次数 (0 = 无限, 异步链路默认)

frame_type: int

2

link_type: nearlink_sdr.mac.qos.LinkType

None

tx_sn: int

0

expected_rx_sn: int

0

pending_ack: bool

False

retransmit_count: int

0

max_retransmit: int

0

property sn_modulus: int

on_tx_new(data: bytes) → int

发送新数据包, 返回使用的 SN。

on_ack_received() → None

收到 ACK: 翻转 SN, 清除重传状态。

on_nack_received() → nearlink_sdr.mac.qos.TxDecision

收到 NACK: 决定是否重传。

异步链路: 持续重传直到收到 ACK。 同步链路: 超出 max_retransmit 后丢弃。

on_no_feedback() → nearlink_sdr.mac.qos.TxDecision

未收到反馈: 与 NACK 处理相同。

on_rx_packet(rx_sn: int) → bool

接收数据包, 返回是否为新数据。

若 rx_sn == expected_rx_sn: 新数据, 反馈 ACK。 否则: 重复包, 仍反馈 ACK。

class nearlink_sdr.mac.qos.FeedbackMode

Bases: enum.IntEnum

HARQ 反馈模式。

Initialization

Initialize self. See help(type(self)) for accurate signature.

TB

0

CBG

1

class nearlink_sdr.mac.qos.FlowController

发送流控管理器。

根据发送缓冲区状态生成 flow_ctrl 指示字段:

• 0: 没有后续数据

• 1: 有后续数据待发送

同时实现简单的背压机制。

buffer_high_watermark: int

16

buffer_low_watermark: int

4

enqueue(count: int = 1) → None

数据入队。

dequeue(count: int = 1) → None

数据出队。

property flow_ctrl_bit: int

控制信息 flow_ctrl 字段值。

property is_paused: bool

是否处于背压暂停状态。

property buffer_count: int

class nearlink_sdr.mac.qos.HarqController

混合自动重传请求控制器。

管理 HARQ 反馈字段 (8 bit) 和 CBG 级部分重传逻辑。

TB 模式: harq_feedback 指示期望对端传输的数据包 SN。 CBG 模式: harq_feedback 每 bit 对应一个 CBG 的 ACK/NACK。

feedback_mode: nearlink_sdr.mac.qos.FeedbackMode

None

n_cbg: int

1

encode_harq_feedback(ack: bool, peer_sn: int = 0) → int

编码 HARQ 反馈字段 (8 bit)。

TB 模式: 返回期望对端传输的 SN。 CBG 模式: 返回 CBG ACK/NACK bitmap。

decode_harq_feedback(harq_field: int) → list[bool]

解码 HARQ 反馈字段。

TB 模式: 返回 [全部 ACK] 或 [全部 NACK]。 CBG 模式: 返回每个 CBG 的 ACK 状态。

update_cbg_status(cbg_ack: list[bool]) → None

更新 CBG 接收状态。

needs_cbg_retransmit() → bool

是否需要 CBG 级部分重传。

get_retransmit_cbg_mask() → int

获取需要重传的 CBG 掩码 (用于 B1 控制信息 data_length 字段)。

标准 6.5.1.1: MCS=15 时, data_length 低 M bit 指示需要传输的 CBG。

decide_tx(ack_received: bool, arq: nearlink_sdr.mac.qos.ArqState) → nearlink_sdr.mac.qos.TxDecision

综合 HARQ 反馈决定发送行为。

reset_cbg() → None

重置 CBG 状态 (新数据传输前)。

property all_cbg_acked: bool

class nearlink_sdr.mac.qos.LinkQualityTracker

链路质量跟踪与 AMC 建议。

跟踪最近 N 帧的 CRC 通过率, 计算瞬时 FER, 根据 FER 阈值建议 MCS 调整方向。

标准: 控制信息 LQI 字段 (前 4 bit 为 MCS 指示)。

window_size: int

32

fer_target_low: float

0.01

fer_target_high: float

0.1

property current_mcs: int

record(crc_ok: bool) → None

记录一帧接收结果。

property fer: float

当前窗口 FER。

property success_rate: float

当前窗口成功率。

suggest_mcs_adjustment() → int

建议 MCS 调整方向。

返回:

+1: 建议提升 MCS (链路质量好) -1: 建议降低 MCS (链路质量差) 0: 保持当前 MCS

apply_suggestion() → int

应用 MCS 调整建议并返回新 MCS。

encode_lqi() → int

编码 LQI 字段 (8 bit): 前 4 bit MCS, 后 4 bit 预留。

static decode_lqi(lqi: int) → int

解码 LQI 字段, 提取 MCS 指示。

class nearlink_sdr.mac.qos.LinkType

Bases: enum.IntEnum

数据链路类型。

Initialization

Initialize self. See help(type(self)) for accurate signature.

ASYNC

0

SYNC

1

class nearlink_sdr.mac.qos.Priority

Bases: enum.IntEnum

数据传输优先级 (数值越小优先级越高)。

Initialization

Initialize self. See help(type(self)) for accurate signature.

CONTROL

0

REALTIME

1

HIGH

2

NORMAL

3

LOW

4

class nearlink_sdr.mac.qos.QosManager

QoS 服务质量管理器。

集成 ARQ、HARQ、流控、链路质量跟踪和发送队列, 为 MAC-PHY 接口提供统一的数据传输质量管理。

arq: nearlink_sdr.mac.qos.ArqState

'field(...)'

harq: nearlink_sdr.mac.qos.HarqController

'field(...)'

flow: nearlink_sdr.mac.qos.FlowController

'field(...)'

quality: nearlink_sdr.mac.qos.LinkQualityTracker

'field(...)'

tx_queue: nearlink_sdr.mac.qos.TxQueue

'field(...)'

prepare_tx() → tuple[nearlink_sdr.mac.qos.TxDecision, nearlink_sdr.mac.qos.TxQueueItem | None]

准备下一帧发送。

返回:

(发送决策, 队列项或 None)

on_tx_feedback(crc_ok: bool) → nearlink_sdr.mac.qos.TxDecision

处理来自对端的 ACK/NACK 反馈。

submit_data(data: bytes, priority: nearlink_sdr.mac.qos.Priority = Priority.NORMAL) → bool

提交数据到发送队列。

get_ctrl_fields() → dict[str, int]

获取当前控制信息字段值。

class nearlink_sdr.mac.qos.TxDecision

Bases: enum.IntEnum

发送决策。

Initialization

Initialize self. See help(type(self)) for accurate signature.

NEW_DATA

'auto(...)'

RETRANSMIT

'auto(...)'

RETRANSMIT_CBG

'auto(...)'

EMPTY

'auto(...)'

class nearlink_sdr.mac.qos.TxQueue(max_size: int = 64)

优先级发送队列。

高优先级数据优先出队; 同优先级内按FIFO顺序; 重传数据优先于同优先级新数据。

Initialization

push(item: nearlink_sdr.mac.qos.TxQueueItem) → bool

入队, 队满时返回 False。

pop() → nearlink_sdr.mac.qos.TxQueueItem | None

出队最高优先级项。

peek() → nearlink_sdr.mac.qos.TxQueueItem | None

查看但不移除最高优先级项。

property size: int

property is_empty: bool

property is_full: bool

count_by_priority(priority: nearlink_sdr.mac.qos.Priority) → int

指定优先级的队列项数量。

clear() → None

清空所有队列。

class nearlink_sdr.mac.qos.TxQueueItem

发送队列项。

priority: nearlink_sdr.mac.qos.Priority

None

data: bytes

None

segment_type: int

0

retransmit: bool

False

attempt: int

0