readme update

README.md

@@ -9,16 +9,19 @@ changelog
 11.28 完全重构,更新文档.
 12.1  一个编译问题,添加说明.
 12.5  编译问题补充
+12.21 跟进更新,重新部分内容
 ```
 
 ## 说明
 
-监控 数值变量(给定 地址,长度), 达到设定条件打印系统内 Task 信息(用户态堆栈/内核态堆栈/调用链信息).
-- 支持多进程, 单个进程退出时,取消该进程的所有监控.
-- 相同定时间隔会分配到同一个定时器,一个定时器最多监控 32 个变量,全局最多 128 个定时器.
-    - 以上数量限制定义在 `source/module/monitor_timer.h`.
-    - `testcase/helloworld.c` 有测试到单进程 2049 个变量;
-- 获取用户态堆栈,要求目标程序编译时开启 `-g` 选项
+监控 数值变量(给定 地址,长度), 达到设定条件打印 Task 信息(用户态堆栈/内核态堆栈/调用链信息).
+- 支持多进程/线程, 单个进程/线程 退出时,取消其注册的所有监控.
+- 同一个 Task(线程) 注册的所有监控中, 相同的定时间隔监控会分配到同一个定时器.
+- 一个定时器最多监控 32 个变量,全局最多 128 个定时器.
+  - 以上数量限制定义在 `source/module/monitor_timer.h`.
+  - `testcase/helloworld.c` 有测试到单进程 2049 个变量;
+- 用户态堆栈符号信息还原的准确度 取决于目标程序编译方式.
+  - gcc 下 `-s` 会抹除符号信息,有可能导致无法将地址还原为正确符号信息.
 
 文件结构
 
@@ -40,12 +43,20 @@ changelog
 设定对变量监控有两种函数: 宏定义 或 定义 watch_arg 结构体
 - 都需要添加 `source/uapi` 下的头文件 `#include "monitor_user.h"`
 
-需要取消监控时调用 `cancel_watch();` variant_monitor 会取消该进程所有监控.
-- 当进程退出后,也会执行相同的操作,取消该进程所有监控.
+需要取消监控时调用 `cancel_watch();` variant_monitor 会取消该进程/线程 的所有监控.
+- 当进程/线程退出后,也会执行相同的操作,取消该进程/线程的 所有监控.
 - 因此调用 `cancel_watch();` 是个可选项,但依然建议调用以避免可能的内存泄漏.
 
-获取 Task 信息是一项耗时操作,这里使用了 workqueue 处理,且一次处理后该定时器重启间隔默认为 5s.
-- 此值可以在 `/proc/variable_monitor/dump_reset_sec` 查看和修改.
+对变量监控采取轮询方式, 变量超出阈值到抓取到 Task 信息,会有一定的时间间隔. 针对时效性, 模块提供了 2 种捕获模式
+- `CAPTURE_IMMEDIATE`(1): 当检测到有变量超出阈值时,立刻抓取 Task 信息,不再等待同一个定时器的其他监控.若 Task 正在前台,则发送 ipi 中断在其上下文立刻获取 Task 信息.
+  - 延迟低,约为 10us, 但只能抓取一个 struct_task 信息(线程 or 进程).
+- `CAPTURE_AGGREGATE`(0, 默认): 一次检测完定时器内全部变量,之后使用 workqueue 抓取 Task 信息.
+  - 延迟高,约为 200us, 但可以抓取更多的 struct_task 信息.
+- 此值可以在 `/proc/variable_monitor/stack_capture_mode` 查看和修改.
+
+获取 Task 信息是一项耗时操作,因此对 `CAPTURE_AGGREGATE`模式下 抓取范围 和 定时器重启间隔做了限制.
+- 定时器重启间隔默认 5s.此值可以在 `/proc/variable_monitor/dump_reset_sec` 查看和修改,修改后即刻生效.
+- `CAPTURE_AGGREGATE` 模式下默认抓取变量所在 **进程** (包括所有线程) 信息. 如果需要抓取系统全部堆栈信息可以修改 可以`echo 1 > /proc/variable_monitor/sample_all`.
 
 ### 挂载驱动
 
@@ -85,12 +96,16 @@ START_WATCH_INT("temp", &temp, 150);
 START_WATCH_INT_LESS("temp", &temp, 150);
 ```
 
+使用宏定义,会将 此监控绑定到申请监控的线程上,当 线程退出时,会自动取消此线程的所有监控.
+- 注意不是进程.
+
 默认情况下,使用宏定义 定时器的时间间隔为 10us; 此值可以在 `/proc/variable_monitor/def_interval_ns` 查看和修改.
 
 ### watch_arg 结构体
 
 如果需要对定时间隔等有更多控制,请定义 watch_arg 结构体,start_watch 启动监控:
 - 对每个需要监控的变量 设置: 名称 && 地址 && 长度, 设置阈值, 比较方式, 定时器间隔(ns) 等.
+- 需要监控生命周期与进程相同传入的 task_id 要与进程的 tgid 相同.
 - `start_watch(watch_arg);` 启动监控
 - 需要取消监控时调用 `cancel_watch();`