From 4a5a6d613a08dc4633ba951f4309976f9e840242 Mon Sep 17 00:00:00 2001
From: wuying39 <wuying53@huawei.com>
Date: Tue, 18 Nov 2025 20:49:47 +0800
Subject: [PATCH] modify parameter validation of cache collect tool and README

---
 README.en.md                         |   4 +
 README.md                            |   3 +
 tools/cache_collect/README.en.md     | 145 +++++++++++++++++++++++++++
 tools/cache_collect/README.md        |  80 +++++++--------
 tools/cache_collect/collect.cpp      |   2 +-
 tools/cache_collect/collect_args.cpp |  94 +++++++++++------
 tools/cache_collect/collect_args.h   |  12 ++-
 7 files changed, 264 insertions(+), 76 deletions(-)
 create mode 100644 tools/cache_collect/README.en.md

diff --git a/README.en.md b/README.en.md
index ffc0d13..7d31cf7 100644
--- a/README.en.md
+++ b/README.en.md
@@ -55,6 +55,10 @@ Minimum required GCC version:
 
 - gcc-4.8.5 and glibc-2.17.
 
+Maximum supported GCC version:
+
+- gcc-12.2.0 and glibc-2.36.
+
 Minimum required Python version:
 
 - python-3.6.
diff --git a/README.md b/README.md
index c441df5..be4553c 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,9 @@ v1.0:
 最低依赖gcc版本：
 - gcc-4.8.5 和 glibc-2.17
 
+最高支持gcc版本：
+- gcc-12.2.0 和 glibc-2.36
+
 最低依赖python版本：
 - python-3.6
 
diff --git a/tools/cache_collect/README.en.md b/tools/cache_collect/README.en.md
new file mode 100644
index 0000000..b5fbdaa
--- /dev/null
+++ b/tools/cache_collect/README.en.md
@@ -0,0 +1,145 @@
+# Cache Collect Tool
+### Description
+This tool is designed to collect L2I cache, l2D cache information of go program.
+
+1. It generates statistics of hotspots from the function and instruction perspectives. 
+
+2. It reports the L2I cache miss ratio, L2D cache miss ratio, and IPC (Instructions Per Cycle) for each process.
+
+In L2I cache collect mode, the corresponding data can be output as a txt file for BOLT in the work directory.
+```
+Format: 1 [funcName] [offset] [number]
+```
+[number] is the sample count for [funcName] at [offset]
+
+### Build
+Build the libkperf tool first:
+```
+bash build.sh
+```
+
+then:
+```
+cd tools/cache_collect
+mkdir build && cd build
+cmake ..
+make
+```
+
+### Run
+Use './cache_collect --help/-h' to view the help information.
+
+```
+  Usage: ./cache_collect --pid/-p <pid> [options]
+
+  Required:
+    --pid/-p <pid>           : Target process ID(s). Multiple IDs can be separated by ','
+  Optional:
+    --duration/-d <seconds>  : Set collection time of hotspots. Unit: s, default: 10
+    --level/-l <level>       : Set to 'inst' for instruction-level summary. Default: function-level summary
+    --mode/-m <mode>         : Set to 'dcache' to collect L2D cache data. Default: L2I cache data
+    --interval/-i <ms>       : Interval for reading the ring buffer. Unit: ms, default: 1000
+    --frequency/-f <freq>    : Sampling frequency, default: 1000
+    --bolt/-b <option>       : Generate BOLT format output file. Options: 'cycles', 'l2i_cache', 'l2i_cache_refill', or 'all'. Only for default mode.
+    --summary/-s <seconds>   : Set collection time of summary ratio and IPC collection. Unit: s, default: 5
+  Examples:
+    ./cache_collect -p 125785 -d 10 -l inst -m dcache -i 2000
+    ./cache_collect -p 125785,143789 -m dcache -f 4000 -b cycles
+```
+
+### Example
+pwd: /home/test/libkperf/tools/cache_collect/build
+#### The function level:
+command:
+```
+./cache_collect -p 1630278 -b all
+```
+
+The output results is:
+```
+====================================================================================================================================================================================
+                                                                    HOTSPOT FUNC
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Function                                          Pid         Start Addr        End Addr          Length            l2 icache refill    l2 icache      Cycles         Ratio(%)
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+main.addSub                                       1630278     244e20            244f30            110               76                  144            13820058736    52.65
+main.addSubFuse                                   1630278     244f30            245030            100               7921                2586           12423196469    47.33
+gogo                                              1630278     7b0e0             7b120             40                1428                1017           2575901        0.01
+runtime.sighandler                                1630278     5fa80             60070             5f0               56                  1741           2568366        0.01
+runtime.retake                                    1630278     572e0             575b0             2d0               0                   0              433392         0.00
+runtime.unlock2                                   1630278     1c580             1c650             d0                780                 5707           296167         0.00
+runtime.nanotime1.abi0                            1630278     7f3c0             7f4a0             e0                306                 4522           3155           0.00
+runtime.usleep.abi0                               1630278     7f150             7f1b0             60                0                   31             34             0.00
+runtime.sysmon                                    1630278     56e30             572e0             4b0               33                  1              30             0.00
+....
+____________________________________________________________________________________________________________________________________________________________________________________
+Bolt file: /home/test/libkperf/tools/cache_collect/build/1630278_20251106_160118_cycles.txt
+Bolt file: /home/test/libkperf/tools/cache_collect/build/1630278_20251106_160118_l2i_cache_refill.txt
+Bolt file: /home/test/libkperf/tools/cache_collect/build/1630278_20251106_160118_l2i_cache.txt
+======================================================================
+SUMMARY
+----------------------------------------------------------------------
+Pid             l2 icache Miss Rate      l2 dcache Miss Rate       IPC
+----------------------------------------------------------------------
+1630278                      59.60%                   49.89%      2.71
+----------------------------------------------------------------------
+```
+
+The content of '1630278_20251106_160118_cycles.txt' is:
+```
+no_lbr cycles:
+1 main.addSub/1 20 5352
+1 main.addSubFuse/1 20 4813
+1 gogo/1 20 1 1 runtime.sighandler/1 30 1
+1 runtime.retake/1 7c 2
+1 runtime.unlock2/1 30 1
+1 runtime.nanotime1.abi0/1 98 3
+1 runtime.usleep.abi0/1 48 4
+1 runtime.sysmon/1 e4 2
+```
+
+#### The instruction level:
+command:
+```
+./cache_collect -p 1630278 -l inst -b cycles
+```
+
+The output results is:
+```
+=================================================================================================================================================
+                                                                    HOTSPOT INST
+-------------------------------------------------------------------------------------------------------------------------------------------------
+Addr                FuncName                                          Pid            l2 icache refill    l2 icache      Cycles         Ratio(%)
+-------------------------------------------------------------------------------------------------------------------------------------------------
+244f50              main.addSubFuse                                   1630278        1004                1699           4574485132     17.49
+244e98              main.addSub                                       1630278        50                  0              2237117248     8.55
+244e50              main.addSub                                       1630278        0                   90             2157851199     8.25
+244e40              main.addSub                                       1630278        0                   0              1647745701     6.30
+244edc              main.addSub                                       1630278        0                   132            1616315405     6.18
+244eb0              main.addSub                                       1630278        37                  0              1483391344     5.67
+244fa4              main.addSubFuse                                   1630278        0                   64             1343424392     5.14
+244fe8              main.addSubFuse                                   1630278        0                   0              1115313116     4.26
+244fac              main.addSubFuse                                   1630278        1                   0              900182732      3.44
+244fc4              main.addSubFuse                                   1630278        42                  553            755279597      2.89
+244f88              main.addSubFuse                                   1630278        60                  1357           714211321      2.73
+244f6c              main.addSubFuse                                   1630278        93                  131            639790055      2.45
+244e74              main.addSub                                       1630278        0                   0              565132676      2.16
+...
+__________________________________________________________________________________________________________________________________________________
+Bolt file: /home/test/libkperf/tools/cache_collect/build/1630278_20251106_161435_cycles.txt
+...
+```
+
+The content of bolt file is :
+```
+no_lbr cycles:
+1 main.addSubFuse/1 20 1768
+1 main.addSub/1 78 869
+1 main.addSub/1 30 838
+1 main.addSub/1 20 641
+1 main.addSub/1 bc 629
+1 main.addSub/1 90 576
+1 main.addSubFuse/1 74 500 
+1 main.addSubFuse/1 b8 433
+...
+```
\ No newline at end of file
diff --git a/tools/cache_collect/README.md b/tools/cache_collect/README.md
index 7df18e8..45e3028 100644
--- a/tools/cache_collect/README.md
+++ b/tools/cache_collect/README.md
@@ -1,23 +1,21 @@
 # Cache Collect Tool
-### Description
-This tool is designed to collect L2I cache, l2D cache infomation of go program.
+### 描述
+该工具用于收集 Go 程序的 L2I Cache 和 L2D Cache 信息。
+1. 从函数和指令两个角度生成热点统计数据。
+2. 报告每个进程的 L2I Cache 未命中率、L2D Cache 未命中率以及 IPC（每周期指令数）。
 
-1. It generates statistics of hotspots from the function and instruction perspectives. 
-
-2. It reports the L2I cache miss ratio, L2D cache miss ratio, and IPC (Instructions Per Cycle) for each process.
-
-In L2I cache collect mode, the corresponding data can be output as a txt file for BOLT in the work directory.
-Format: 1 [funcName] [offset] [number]
-
-[number] is the sample count for [funcName] at [offset]
+在 L2I Cache 收集模式下，可以将对应数据输出为 BOLT 格式的 txt 文件到工作目录。 格式如下：
+```
+1 [funcName] [offset] [number]
+```
+其中：funcName为函数名，offset为指令地址偏移量，number为采样到的次数
 
-### Build
-Build the libkperf tool first:
+### 构建
+1. 构建 libkperf 工具：
 ```
 bash build.sh
 ```
-
-then:
+2. 构建cache collect工具：
 ```
 cd tools/cache_collect
 mkdir build && cd build
@@ -25,36 +23,38 @@ cmake ..
 make
 ```
 
-### Run
-Use 'cache_collect --help/-h' to view the help information.
+### 运行
+使用 ./cache_collect --help/-h 查看帮助信息。
 
 ```
-  Usage: cache_collect --pid/-p <pid> [options]
+  用法: ./cache_collect --pid/-p <pid> [选项]
+
+  必选参数:
+    --pid/-p <pid>           : 目标进程 ID，可用 ',' 分隔多个 ID
+
+  可选参数:
+    --duration/-d <秒>       : 设置热点收集时间，单位：秒，默认：10
+    --level/-l <级别>        : 设置为 'inst' 时输出指令级汇总，默认：以函数级别汇总
+    --mode/-m <模式>         : 设置为 'dcache' 采集L2D Cache数据，默认：采集L2I Cache数据
+    --interval/-i <毫秒>     : 读取环形缓冲区的间隔，单位：毫秒，默认：1000
+    --frequency/-f <频率>    : 采样频率，默认：1000
+    --bolt/-b <选项>         : 生成 BOLT 格式输出文件，仅在默认模式下使用。选项包括：'cycles'、'l2i_cache'、'l2i_cache_refill' 或 'all'。
+    --summary/-s <秒>        : 设置汇总比例和 IPC 收集的时间，单位：秒，默认：5
 
-  Required:
-    --pid/-p <pid>           : Target process ID(s). Multiple IDs can be separated by ','
-  Optional:
-    --duration/-d <seconds>  : Set collection time of hotspots. Unit: s, default: 10
-    --level/-l <level>       : Set to 'inst' for instruction-level summary. Default: function-level summary
-    --mode/-m <mode>         : Set to 'dcache' to collect L2D cache data. Default: L2I cache data
-    --interval/-i <ms>       : Interval for reading the ring buffer. Unit: ms, default: 1000
-    --frequency/-f <freq>    : Sampling frequency, default: 1000
-    --bolt/-b <option>       : Generate BOLT format output file. Options: 'cycles', 'l2i_cache', 'l2i_cache_refill', or 'all'. Only for default mode.
-    --summary/-s <seconds>   : Set collection time of summary ratio and IPC collection. Unit: s, default: 5
-  Examples:
-    cache_collect -p 125785 -d 10 -l inst -m dcache -i 2000
-    cache_collect -p 125785,143789 -m dcache -f 4000 -b cycles
+  命令示例:
+    ./cache_collect -p 125785 -d 10 -l inst -m dcache -i 2000
+    ./cache_collect -p 125785,143789 -m dcache -f 4000 -b cycles
 ```
 
-### Example
-pwd: /home/test/libkperf/tools/cache_collect/build
-#### The function level:
-command:
+### 示例
+当前目录: /home/test/libkperf/tools/cache_collect/build
+#### 函数级别统计:
+命令:
 ```
 ./cache_collect -p 1630278 -b all
 ```
 
-The output results is:
+输出结果:
 ```
 ====================================================================================================================================================================================
                                                                     HOTSPOT FUNC
@@ -84,7 +84,7 @@ Pid             l2 icache Miss Rate      l2 dcache Miss Rate       IPC
 ----------------------------------------------------------------------
 ```
 
-The content of '1630278_20251106_160118_cycles.txt' is:
+Bolt文件'1630278_20251106_160118_cycles.txt'的内容:
 ```
 no_lbr cycles:
 1 main.addSub/1 20 5352
@@ -97,13 +97,13 @@ no_lbr cycles:
 1 runtime.sysmon/1 e4 2
 ```
 
-#### The instruction level:
-command:
+#### 指令级别统计:
+命令:
 ```
 ./cache_collect -p 1630278 -l inst -b cycles
 ```
 
-The output results is:
+输出结果:
 ```
 =================================================================================================================================================
                                                                     HOTSPOT INST
@@ -129,7 +129,7 @@ Bolt file: /home/test/libkperf/tools/cache_collect/build/1630278_20251106_161435
 ...
 ```
 
-The content of bolt file is :
+Bolt文件的内容:
 ```
 no_lbr cycles:
 1 main.addSubFuse/1 20 1768
diff --git a/tools/cache_collect/collect.cpp b/tools/cache_collect/collect.cpp
index b7ffc89..369594c 100644
--- a/tools/cache_collect/collect.cpp
+++ b/tools/cache_collect/collect.cpp
@@ -172,7 +172,7 @@ static void PrintHotSpotTitle(int length) {
               << std::setw(18) << "Length";
     }
 
-    std::string refill = dataCollect ? "l2dcache refill" : "l2 icache refill";
+    std::string refill = dataCollect ? "l2 dcache refill" : "l2 icache refill";
     std::string cache  = dataCollect ? "l2 dcache"       : "l2 icache";
     std::cout << std::setw(20) << refill
           << std::setw(15) << cache
diff --git a/tools/cache_collect/collect_args.cpp b/tools/cache_collect/collect_args.cpp
index cd08616..37ac8d1 100644
--- a/tools/cache_collect/collect_args.cpp
+++ b/tools/cache_collect/collect_args.cpp
@@ -15,6 +15,9 @@
 #include <iostream>
 #include <getopt.h>
 #include <sstream>
+#include <stdexcept>
+#include <vector>
+#include <cstdlib>
 #include <unordered_map>
 #include "collect_args.h"
 
@@ -34,6 +37,28 @@ BoltOption CollectArgs::ParseBoltOption(const std::string& value) {
     return BoltOption::NONE;
 }
 
+
+bool CollectArgs::ParsePositiveIntArg(const char* arg, const std::string& paramName, int& outValue, int minValue)
+{
+    try {
+        int value = std::stoul(arg);
+        if (value < minValue) {
+            std::cerr << "Error: parameter '" << paramName << "' must bigger than 0, but got " << value << ".\n";
+            return false;
+        }
+        outValue = static_cast<unsigned>(value);
+        return true;
+    } catch (const std::invalid_argument& e) {
+        std::cerr << "Error: failed to parse parameter '" << paramName << "' from argument '" << arg
+                  << "'. Reason: " << e.what() << ". Expected an integer.\n";
+        return false;
+    } catch (const std::out_of_range& e) {
+        std::cerr << "Error: parameter '" << paramName << "' value '" << arg
+                  << "' is out of valid range. Reason: " << e.what() << "\n";
+        return false;
+    }
+}
+
 bool CollectArgs::ParseOption(int argc, char* argv[])
 {
     int opt;
@@ -42,15 +67,15 @@ bool CollectArgs::ParseOption(int argc, char* argv[])
     std::string mode;
     std::string bolt;
     struct option long_options[] = {
-        {"help",      no_argument, 0, 'h'},
-        {"pid",      required_argument, 0, 'p'},
-        {"duration", required_argument, 0, 'd'},
-        {"level",    required_argument, 0, 'l'},
-        {"mode",     required_argument, 0, 'm'},
-        {"interval", required_argument, 0, 'i'},
+        {"help",      no_argument,       0, 'h'},
+        {"pid",       required_argument, 0, 'p'},
+        {"duration",  required_argument, 0, 'd'},
+        {"level",     required_argument, 0, 'l'},
+        {"mode",      required_argument, 0, 'm'},
+        {"interval",  required_argument, 0, 'i'},
         {"frequency", required_argument, 0, 'f'},
-        {"bolt", required_argument, 0, 'b'},
-        {"summary", required_argument, 0, 's'},
+        {"bolt",      required_argument, 0, 'b'},
+        {"summary",   required_argument, 0, 's'},
         {0, 0, 0, 0}
     };
 
@@ -60,10 +85,7 @@ bool CollectArgs::ParseOption(int argc, char* argv[])
                 printUsage();
                 exit(0);
             case 'd':
-                try {
-                    duration = std::stoi(optarg);
-                } catch (const std::invalid_argument& e) {
-                    std::cerr << "Not valid collecting duration: " << e.what() << "\n";
+                if (!ParsePositiveIntArg(optarg, "hotspot duration", duration)) {
                     return false;
                 }
                 break;
@@ -74,39 +96,40 @@ bool CollectArgs::ParseOption(int argc, char* argv[])
                 level = optarg;
                 if (level == "inst") {
                     enableInst = true;
+                } else {
+                    std::cerr << "Error: invalid input for --level/-l, only support 'inst'" << "\n";
+                    return false;
                 }
                 break;
             case 'm':
                 mode = optarg;
                 if (mode == "dcache") {
                     enableData = true;
+                } else {
+                    std::cerr << "Error: invalid input for --mode/-m, only support 'dcache'" << "\n";
+                    return false;
                 }
                 break;
             case 'i':
-                try {
-                    interval = std::stoi(optarg);
-                } catch (const std::invalid_argument& e) {
-                    std::cerr << "Not valid interval: " << e.what() << "\n";
+                if (!ParsePositiveIntArg(optarg, "interval", interval)) {
                     return false;
                 }
                 break;
             case 'f':
-                try {
-                    frequency = std::stoi(optarg);
-                } catch (const std::invalid_argument& e) {
-                    std::cerr << "Not valid frequency: " << e.what() << "\n";
+                if (!ParsePositiveIntArg(optarg, "frequency", frequency)) {
                     return false;
                 }
                 break;
             case 'b':
                 bolt = optarg;
                 boltOption = ParseBoltOption(bolt);
+                if (boltOption == BoltOption::NONE) {
+                    std::cerr << "Error: invalid input for --bolt/-b, only support 'cycles', 'l2i_cache', 'l2i_cache_refill', and 'all'" << "\n";
+                    return false;
+                }
                 break;
             case 's':
-                try {
-                    summaryTime = std::stoi(optarg);
-                } catch (const std::invalid_argument& e) {
-                    std::cerr << "Not valid duration for summary collecting: " << e.what() << "\n";
+                if (!ParsePositiveIntArg(optarg, "summary duration", summaryTime)) {
                     return false;
                 }
                 break;
@@ -115,22 +138,33 @@ bool CollectArgs::ParseOption(int argc, char* argv[])
                 return false;
         }
     }
-
+    if (boltOption != BoltOption::NONE && enableData == true) {
+        std::cerr << "Error: bolt file can only be set in default collection mode\n";
+        return false;
+    }
     if (pidList.empty()) {
-        std::cerr << "Please input --pid/-p\n";
+        std::cerr << "Error: missing required parameter --pid/-p\n";
         return false;
     }
-    ParsePidList();
-    return true;
+    return ParsePidList();
 }
 
-void CollectArgs::ParsePidList()
+bool CollectArgs::ParsePidList()
 {
     std::stringstream ss(pidList);
     std::string pidStr;
     while (std::getline(ss, pidStr, ',')) {
-        pids.push_back(std::stoi(pidStr));
+        pid_t pid;
+        try {
+            pid = std::stoi(pidStr);
+        } catch (const std::invalid_argument& e) {
+            std::cerr << "Error: failed to parse pid from input parameter: '" << pidStr
+                    << "' .Reason: " << e.what() << ". Expected an integer.\n";
+            return false;
+        }
+        pids.push_back(pid);
     }
+    return true;
 }
 
 void CollectArgs::printUsage()
diff --git a/tools/cache_collect/collect_args.h b/tools/cache_collect/collect_args.h
index 8c57f4b..cfb7cd9 100644
--- a/tools/cache_collect/collect_args.h
+++ b/tools/cache_collect/collect_args.h
@@ -17,6 +17,7 @@
 
 #include <string>
 #include <vector>
+#include <climits>
 #include <unistd.h>
 
 enum class BoltOption {
@@ -29,10 +30,10 @@ enum class BoltOption {
 
 class CollectArgs {
 public:
-    unsigned long duration = 10;
-    unsigned long summaryTime = 5;
-    unsigned frequency = 1000;
-    unsigned interval = 1000;
+    int duration = 10;
+    int summaryTime = 5;
+    int frequency = 1000;
+    int interval = 1000;
     bool enableData = false;
     bool enableInst = false;
     BoltOption boltOption = BoltOption::NONE;
@@ -43,7 +44,8 @@ public:
 
 private:
     std::string pidList;
-    void ParsePidList();
+    bool ParsePidList();
+    bool ParsePositiveIntArg(const char* arg, const std::string& paramName, int& outValue, int minValue = 1);
     BoltOption ParseBoltOption(const std::string& value);
 };
 #endif
\ No newline at end of file
-- 
Gitee