docs(algo): 补 sample_ring_window 注释,详解窗首下标推导

- 补环内布局示意与 s_head 语义(下一待写位置,非最后写入位置),
  据此推出窗首 = s_head - n、窗尾 = s_head - 1。
- 重点解释 start 为何写成 (s_head + DEPTH - n) % DEPTH:
  加 DEPTH 不改变同余类;规避 16 位下溢后再取模不等价(65536 不是
  40 的倍数);规避有符号负取模(-17 % 40 == -17)。
- 补限定条件:仅 adcTask 上下文,写者与读者同任务串行,故不加锁。
- .h 只加一行指针指向 .c 的推导,避免同一事实两处详述。
- 纯注释改动:去注释后代码 token 与 HEAD 完全一致;@build 0 错 0 警。
This commit is contained in:
2026-10-29 17:06:28 +08:00
parent cdf88a7121
commit de512a0db8
2 changed files with 86 additions and 5 deletions
+3
View File
@@ -59,6 +59,9 @@ int sample_ring_push_frame(const float *values, uint8_t n);
* 返 回 值:0 - 成功;-1 - 参数错;-2 - 已累积点数不足 n
* 限定条件:无
* 函数说明:out[n-1] 为最新一点。相量层以本函数取"以当前时刻为终止的一周波"。
* ⚠ 仅 adcTask 上下文调用(写者与读者同任务串行,本层不加锁);
* 环内布局、窗首下标推导与"先加 DEPTH 再减 n"的理由见
* `App/algo/sample_ring.c` 同名函数的注释。
*/
int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out);