Star79
22
代码
代码
Issues5
Pull Requests1
流水线
项目讨论
Wiki
分析
Star79
22
已合并
【doc】英文文档合入 #53
luyq11创建于 6月11日
【doc】英文文档合入 #53
已合并
luyq11创建于 6月11日
从luyq11/MindStudio-Tools-Extension-Library_kymaster合入到Ascend/mstxmaster
共 24 个文件变更+1223-0
AREADME_EN.md+66-0
@@ -0,0 +1,66 @@
1+<h1 align="center">MindStudio Tools Extension Library</h1>
2+ 
3+<div align="center">
4+<h2>Ascend AI Operator Tool Extension Interface Library</h2>
5+ 
6+ [![Ascend](https://img.shields.io/badge/Community-MindStudio-blue.svg)](https://www.hiascend.com/en/developer/software/mindstudio)
7+ [![License](https://badgen.net/badge/License/MulanPSL-2.0/blue)](./LICENSE)
8+ 
9+</div>
10+ 
11+## ✨ What's New
12+ 
13+<span style="font-size:14px;">
14+ 
15+🔹 **[2025.12.31]**: The MindStudio Tools Extension Library project is now fully open source.
16+ 
17+</span>
18+ 
19+## ️ ℹ️ Introduction
20+ 
21+MindStudio Tools Extension Library (msTX) introduces the msTX instrumentation API. It allows you to customize collection time ranges or the start and end time points of key functions, identify information such as key functions or iterations, and quickly scope performance and operator issues.
22+ 
23+## ⚙️ Features
24+ 
25+By default, the mstx API has no functionality. You need to call the mstx API in your user application and then enable the mstx instrumentation feature for different scenarios, such as configuring `--mstx=on` when profiling data with the msprof command line, configuring `ACL_PROF_MSPROFTX` when profiling data with the AscendCL API, and configuring `mstx=True` when profiling data with the Ascend PyTorch Profiler API.
26+ 
27+## 📦 Installation Guide
28+ 
29+For environment dependencies and installation methods, see the [msTX Installation Guide](docs/en/install_guide/mstx_install_guide.md).
30+ 
31+## 💡 Typical Use Cases
32+ 
33+For typical usage scenarios, refer to [msOpProf Extended Functions](https://gitcode.com/Ascend/msopprof/blob/master/docs/en/user_guide/extended_functions.md#mstx-extension) and [msSanitizer API Reference](https://gitcode.com/Ascend/mssanitizer/blob/master/docs/en/api_reference/mssanitizer_api_reference.md#mstx-extension).
34+ 
35+## 📚 API Reference
36+ 
37+For details on msTX APIs, refer to [msTX API Reference](docs/en/api_reference/README.md).
38+ 
39+## 🛠️ Contribution Guide
40+ 
41+Contributions are welcome. For details, see the [Contribution Guide](./docs/zh/contributing/contributing_guide.md).
42+ 
43+## ⚖️ Related Information
44+ 
45+🔹 [Release Notes](./docs/en/release_notes/release_notes.md)
46+🔹 [LICENSE Statement](./docs/en/legal/license_notice.md)
47+🔹 [Security Statement](./docs/en/legal/security_statement.md)
48+🔹 [Disclaimer](./docs/en/legal/disclaimer.md)
49+ 
50+## 🤝 Suggestions and Communication
51+ 
52+We welcome contributions to the community. If you have any questions or suggestions, please submit an [Issue](https://gitcode.com/Ascend/mstx/issues), and we will respond as soon as possible. Thank you for your support.
53+ 
54+| 📱 Follow the MindStudio Official Account | 💬 More Communication and Support |
55+|:-------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
56+| <img src="https://gitcode.com/Ascend/msot/blob/master/docs/zh/figures/readme/officialAccount.png" width="120"><br><sub>*Scan the QR code to get the latest updates*</sub> | 💡 **Join the WeChat Group**:<br>Follow the official account and reply "communication group" to get the group QR code.<br><br>🛠️ **Other Channels**:<br>👉 Ascend Assistant: [![WeChat](https://img.shields.io/badge/WeChat-07C160?style=flat-square&logo=wechat&logoColor=white)](https://gitcode.com/Ascend/msot/blob/master/docs/zh/figures/readme/xiaozhushou.png)<br>👉 Ascend Forum: [![Website](https://img.shields.io/badge/Website-%231e37ff?style=flat-square&logo=RSS&logoColor=white)](https://www.hiascend.com/forum/) |
57+ 
58+## 🙏 Acknowledgments
59+ 
60+This tool is jointly contributed by the following departments of Huawei:
61+🔹 Ascend Computing MindStudio Development Dept
62+🔹 Ascend Computing Ecosystem Enablement Dept
63+🔹 Ascend AI Cloud Service
64+🔹 2012 Compiler Lab
65+🔹 2012 Markov Lab
66+Thank you for every PR from the community. Contributions are welcome.
Adocs/en/api_reference/Common/mstxDomainCreateA.md+42-0
@@ -0,0 +1,42 @@
1+# mstxDomainCreateA<a id="mstxDomainCreateA"></a>
2+ 
3+**Product Support<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Creates a custom mstx domain.
17+ 
18+**Domain**: Used to partition trace data, allowing users to manage trace data in a customized manner. Trace data without a specified domain belongs to the default domain (domain name: default). By default, all trace data belongs to the default domain.
19+ 
20+**Prototype<a id="section1121883194711"></a>**
21+ 
22+```python
23+mstxDomainHandle_t mstxDomainCreateA(const char* id)
24+```
25+ 
26+**Parameter Description<a id="section11506138144714"></a>**
27+ 
28+**Table 1** Parameter description
29+ 
30+|Parameter|Input/Output|Description|
31+|--|--|--|
32+|id|Input|Name of the domain to be created.<br>Data Type: const char *.<br>The default domain name is globalDomain.<br>The maximum length is 1,023 bytes. Only digits, uppercase and lowercase letters, and underscores (_) are supported.<br>MSPTI scenario: cannot exceed 255 bytes.<br>Non-MSPTI scenarios (such as the msprof command line and Ascend PyTorch Profiler): cannot exceed 1,024 bytes.|
33+ 
34+**Returns<a id="section16621124213476"></a>**
35+ 
36+Returns a valid domain handle, indicating that the API is executed successfully; returns nullptr, indicating that the API execution fails.
37+ 
38+**Example<a id="zh-cn_topic_0000002180600114_section16621124213476"></a>**
39+ 
40+```python
41+mstxDomainHandle_t domain = mstxDomainCreateA("sample")
42+```
Adocs/en/api_reference/Common/mstxDomainDestroy.md+34-0
@@ -0,0 +1,34 @@
1+# mstxDomainDestroy<a id="mstxDomainDestroy"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Destroys the specified domain. The destroyed domain cannot be used again and must be recreated.
17+ 
18+**Prototype<a id="section1121883194711"></a>**
19+ 
20+```c
21+void mstxDomainDestroy (mstxDomainHandle_t domain)
22+```
23+ 
24+**Parameter Description<a id="section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+|Parameter|Input/Output|Description|
29+|--|--|--|
30+|domain|Input|Specifies the domain handle to destroy.|
31+ 
32+**Returns<a id="section16621124213476"></a>**
33+ 
34+None
Adocs/en/api_reference/Common/mstxDomainMarkA.md+38-0
@@ -0,0 +1,38 @@
1+# mstxDomainMarkA<a id="mstxDomainMarkA"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Marks an instantaneous event within the specified domain.
17+ 
18+If the passed domain has been destroyed, a warning is logged and the API no longer executes the instrumentation process.
19+ 
20+**Prototype<a id="section1121883194711"></a>**
21+ 
22+```c
23+void mstxDomainMarkA(mstxDomainHandle_t domain, const char *message, aclrtStream stream)
24+```
25+ 
26+**Parameter Description<a id="section11506138144714"></a>**
27+ 
28+**Table 1** Parameter description
29+ 
30+|Parameter|Input/Output|Description|
31+|--|--|--|
32+|domain|Input|Handle of the specified domain.|
33+|message|Input|Pointer to the message string carried by the instrumentation. Length requirements for the passed message string: MSPTI scenario: cannot exceed 255 bytes. Non-MSPTI scenarios (for example, msprof command line, Ascend PyTorch Profiler): cannot exceed 156 bytes.|
34+|stream|Input|Stream used to execute the instrumentation task. When set to nullptr, only the instantaneous event on the Host side is marked. When set to a valid stream, the instantaneous events on both the Host side and the corresponding Device side are marked.|
35+ 
36+**Returns<a id="section16621124213476"></a>**
37+ 
38+None
Adocs/en/api_reference/Common/mstxDomainRangeEnd.md+37-0
@@ -0,0 +1,37 @@
1+# mstxDomainRangeEnd<a id="mstxDomainRangeEnd"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Marks the end of a timestamp event within the specified domain.
17+ 
18+If the passed domain has been destroyed, a warning is printed in the log, and the API no longer executes the instrumentation process.
19+ 
20+**Prototype<a id="section1121883194711"></a>**
21+ 
22+```c
23+void mstxDomainRangeEnd(mstxDomainHandle_t domain, mstxRangeId id)
24+```
25+ 
26+**Parameter Description<a id="section11506138144714"></a>**
27+ 
28+**Table 1** Parameter description
29+ 
30+|Parameter|Input/Output|Description|
31+|--|--|--|
32+|domain|Input|Specified domain handle.|
33+|id|Input|ID returned by the mstxDomainRangeStartA API.|
34+ 
35+**Returns<a id="section16621124213476"></a>**
36+ 
37+None
Adocs/en/api_reference/Common/mstxDomainRangeStartA.md+38-0
@@ -0,0 +1,38 @@
1+# mstxDomainRangeStartA<a id="mstxDomainRangeStartA"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Marks the start of a timestamp event within the specified domain.
17+ 
18+If the passed domain has been destroyed, a warning is logged and the API no longer executes the instrumentation process.
19+ 
20+**Prototype<a id="section1121883194711"></a>**
21+ 
22+```python
23+mstxRangeId mstxDomainRangeStartA(mstxDomainHandle_t domain, const char *message, aclrtStream stream)
24+```
25+ 
26+**Parameter Description<a id="section11506138144714"></a>**
27+ 
28+**Table 1** Parameter description
29+ 
30+|Parameter|Input/Output|Description|
31+|--|--|--|
32+|domain|Input|Specified domain handle.|
33+|message|Input|Pointer to the message string carried by the instrumentation.<br>Length requirement for the incoming message string: MSPTI scenario: cannot exceed 255 bytes. Non-MSPTI scenarios (e.g., msprof command line, Ascend PyTorch Profiler): cannot exceed 156 bytes.|
34+|stream|Input|Stream used to execute the instrumentation task. When set to nullptr, only marks instantaneous events on the Host side. When set to a valid stream, marks instantaneous events on both the Host side and the corresponding Device side.|
35+ 
36+**Returns<a id="section16621124213476"></a>**
37+ 
38+range_id: Identifies the range. Returns 0 if instrumentation fails or the domain has been destroyed.
Adocs/en/api_reference/Common/mstxGetToolId.md+71-0
@@ -0,0 +1,71 @@
1+# mstxGetToolId<a id="mstxGetToolId"></a>
2+ 
3+**Product Support<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002446914857_section20806203412478"></a>**
15+ 
16+Obtains the tool ID that currently intercepts the mstx APIs. The tool ID macro is defined as follows:
17+ 
18+Invalid value 0, indicating that no tool has launched the program.
19+ 
20+```c
21+#define MSTX_TOOL_INVALID_ID 0x0
22+```
23+ 
24+0x1000, indicating that the program is launched by [msProf](https://www.hiascend.com/document/detail/en/canncommercial/83RC1/devaids/Profiling/atlasprofiling_16_0010.html) or [MSPTI](https://www.hiascend.com/document/detail/en/canncommercial/83RC1/devaids/Profiling/atlasprofiling_16_1153.html)
25+ 
26+```c
27+#define MSTX_TOOL_MSPROF_ID 0x1000
28+```
29+ 
30+0x1001, indicating that the program is launched by the [msProf](https://www.hiascend.com/document/detail/en/canncommercial/83RC1/devaids/optool/atlasopdev_16_0082.html) tool
31+ 
32+```c
33+#define MSTX_TOOL_MSOPPROF_ID 0x1001
34+```
35+ 
36+0x1002, indicating that the program is launched by the [msSanitizer](https://www.hiascend.com/document/detail/en/canncommercial/83RC1/devaids/optool/atlasopdev_16_0039.html) tool
37+ 
38+```c
39+#define MSTX_TOOL_MSSANITIZER_ID 0x1002
40+```
41+ 
42+0x1003, indicating that the program is launched by the [msLeaks Memory Leak Detection Tool](https://www.hiascend.com/document/detail/en/canncommercial/83RC1/devaids/msleaks/atlas_msleaks_0001.html)
43+ 
44+```c
45+#define MSTX_TOOL_MSLEAKS_ID 0x1003
46+```
47+ 
48+**Prototype<a id="zh-cn_topic_0000002446914857_section1121883194711"></a>**
49+ 
50+```c
51+void mstxGetToolId(uint64 *id)
52+```
53+ 
54+**Parameter Description<a id="zh-cn_topic_0000002446914857_section11506138144714"></a>**
55+ 
56+**Table 1** Parameter description
57+ 
58+|Parameter|Input/Output|Description|
59+|--|--|--|
60+|id|Output|As an output parameter, returns the tool ID that currently intercepts the mstx API.<br>Data Type: uint64 *.|
61+ 
62+**Returns<a id="zh-cn_topic_0000002446914857_section446682320445"></a>**
63+ 
64+None
65+ 
66+**Example<a id="zh-cn_topic_0000002446914857_section16621124213476"></a>**
67+ 
68+```py
69+uint64 id;
70+mstxGetToolId(&id);
71+```
Adocs/en/api_reference/Common/mstxMarkA.md+35-0
@@ -0,0 +1,35 @@
1+# mstxMarkA<a id="mstxMarkA"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="section20806203412478"></a>**
15+ 
16+Marks an instantaneous event.
17+ 
18+**Prototype<a id="section1121883194711"></a>**
19+ 
20+```c
21+void mstxMarkA(const char *message, aclrtStream stream)
22+```
23+ 
24+**Parameter Description<a id="section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+|Parameter|Input/Output|Description|
29+|--|--|--|
30+|message|Input|Pointer to the string carrying information for the trace event.<br>Length requirement for the input message string: MSPTI scenario: cannot exceed 255 bytes.<br>Non-MSPTI scenario (for example, msprof command line, Ascend PyTorch Profiler): cannot exceed 156 bytes.<br>message cannot be a null pointer.|
31+|stream|Input|Stream used to execute the trace task.<br>When set to nullptr, only marks the instantaneous event on the Host side.<br>When set to a valid stream, marks the instantaneous event on both the Host side and the corresponding Device side.|
32+ 
33+**Returns<a id="section16621124213476"></a>**
34+ 
35+None
Adocs/en/api_reference/Common/mstxRangeEnd.md+49-0
@@ -0,0 +1,49 @@
1+# mstxRangeEnd<a id="mstxRangeEnd"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000001979850148_section20806203412478"></a>**
15+ 
16+Marks the end position of the mstx range capability.
17+ 
18+**Prototype<a id="zh-cn_topic_0000001979850148_section1121883194711"></a>**
19+ 
20+C/C++ function prototype:
21+ 
22+```c
23+void mstxRangeEnd(mstxRangeId id)
24+```
25+ 
26+Python function:
27+ 
28+```py
29+mstx.range_end(range_id)
30+```
31+ 
32+**Parameter Description<a id="zh-cn_topic_0000001979850148_section11506138144714"></a>**
33+ 
34+**Table 1** Parameter description
35+ 
36+| Parameter | Input/Output | Description |
37+|--|--|--|
38+| id (C/C++) | Input | ID returned by mstxRangeStartA (C/C++). |
39+| range_id (Python) | Input | range_id returned by mstx.range_start (Python). |
40+ 
41+**Returns<a id="zh-cn_topic_0000001979850148_section16621124213476"></a>**
42+ 
43+If 0 is returned, it indicates failure.
44+ 
45+**Example<a id="zh-cn_topic_0000001979850148_section377820328555"></a>**
46+ 
47+C/C++ call: The mstxRangeEnd API must be used together with mstxRangeStartA. For details, see [C/C++ Calling Method](mstxRangeStartA.md#c-calling-method).
48+ 
49+Python call: The mstx.range_end API must be used together with mstx.range_start. For a specific example, see [Python Calling Method](mstxRangeStartA.md#python-calling-method).
Adocs/en/api_reference/Common/mstxRangeStartA.md+129-0
@@ -0,0 +1,129 @@
1+# mstxRangeStartA<a id="mstxRangeStartA"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002016210401_section20806203412478"></a>**
15+ 
16+Marks the start position of the mstx range capability.
17+ 
18+**Prototype<a id="section1121883194711"></a>**
19+ 
20+C/C++:
21+ 
22+```c
23+mstxRangeId mstxRangeStartA(const char *message, aclrtStream stream)
24+```
25+ 
26+Python:
27+ 
28+```py
29+mstx.range_start(message, stream)
30+```
31+ 
32+**Parameter Description<a id="zh-cn_topic_0000002016210401_section11506138144714"></a>**
33+ 
34+**Table 1** Parameter description
35+ 
36+|Parameter|Input/Output|Description|
37+|--|--|--|
38+|message|Input|message is a text marker that carries trace information.<br>Data type in C/C++: const char *.<br>In Python, message is a string. Defaults to None.<br>Length requirement for the input message string: MSPTI scenario: cannot exceed 255 bytes.<br>Non-MSPTI scenario (for example, msprof command line, Ascend PyTorch Profiler): cannot exceed 156 bytes.<br>message cannot be a null pointer.|
39+|stream|Input|stream indicates the thread that uses the mark.<br>Data type in C/C++: aclrtStream.<br>In Python, stream is an aclrtStream object. Defaults to None.<br>When set to nullptr, only the instantaneous event on the Host side is marked.<br>When set to a valid stream, the instantaneous events on the Host side and the corresponding Device side are marked.|
40+ 
41+**Returns<a id="zh-cn_topic_0000002016210401_section16621124213476"></a>**
42+ 
43+If 0 is returned, it indicates failure.
44+ 
45+**Example<a id="zh-cn_topic_0000002016210401_section377820328555"></a>**
46+ 
47+- C/C++ Calling Method:<a id="c-calling-method"></a>
48+ 
49+ ```c
50+ ...
51+ bool RunOp()
52+ {
53+ // create op desc
54+ ...
55+ const char *message = "h1";
56+ mstxRangeId id = mstxRangeStartA(message, NULL);
57+ ...
58+ // Run op
59+ if
60+ (!opRunner.RunOp()) {
61+ ERROR_LOG("Run
62+ op failed");
63+ return false;
64+ }
65+ mstxRangeEnd(id);
66+ ...
67+ }
68+ ```
69+ 
70+- **Python** Calling Method 1:<a id="python-calling-method"></a>
71+ 
72+ Through the Python API interface, implement the relevant interface content in C/C++ language and compile it to generate an so file. The relevant so file can be directly referenced by Python in PYTHONPATH.
73+ 
74+ ```py
75+ import mstx
76+ mstx.range_start("aaa")
77+ print(1)
78+ mstx.range_end(1)
79+ import torch
80+ import torch_npu
81+ a = torch.Tensor([1,2,3,4]).npu()
82+ b = torch.Tensor([1,2,3,4]).npu()
83+ hi_str = "hi"
84+ hello_str = "hello"
85+ hi_id = mstx.range_start(hi_str, None)
86+ c = a + b
87+ hello_id = mstx.range_start(hello_str, stream=None)
88+ d = a - b
89+ mstx.range_end(hi_id)
90+ e = a * b
91+ mstx.range_end(hello_id)
92+ ```
93+ 
94+- **Python** Calling Method 2:
95+ 
96+ Directly use Python for development, reference the original mstx .so file via ctypes.CDLL("libms_tools_ext.so"), and use the APIs provided within it.
97+ 
98+ ```py
99+ import mstx
100+ import torch
101+ import torch_npu
102+ import acl
103+ import sys
104+ import ctypes
105+ lib = ctypes.CDLL("libms_tools_ext.so")
106+ # Define the parameter types and return type of the function
107+ lib.mstxRangeStartA.argtypes = [ctypes.c_char_p, ctypes.c_void_p]
108+ lib.mstxRangeStartA.restype = ctypes.c_uint64
109+ lib.mstxRangeEnd.argtypes = [ctypes.c_uint64]
110+ lib.mstxRangeEnd.restype = None
111+ a = torch.Tensor([1,2,3,4]).npu()
112+ b = torch.Tensor([1,2,3,4]).npu()
113+ # Create a ctypes.c_char_p pointer
114+ hi_str = b"hi"
115+ hi_ptr = ctypes.c_char_p(hi_str)
116+ hi_id = ctypes.c_uint64()
117+ # Create a ctypes.c_char_p pointer
118+ hello_str = b"hello"
119+ hello_ptr = ctypes.c_char_p(hello_str)
120+ hello_id = ctypes.c_uint64()
121+ # Call the function
122+ hi_id.value = lib.mstxRangeStartA(hi_ptr, None)
123+ c = a + b
124+ hello_id.value = lib.mstxRangeStartA(hello_ptr, None)
125+ d = a - b
126+ lib.mstxRangeEnd(hi_id)
127+ e = a * b
128+ lib.mstxRangeEnd(hello_id)
129+ ```
Adocs/en/api_reference/Mem/mstxMemHeapRegister.md+102-0
@@ -0,0 +1,102 @@
1+# mstxMemHeapRegister<a id="mstxMemHeapRegister"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002216005989_section20806203412478"></a>**
15+ 
16+Registers a memory pool. When calling this API to register a memory pool, the user must ensure that the memory has been allocated in advance.
17+ 
18+**Prototype<a id="zh-cn_topic_0000002216005989_section1121883194711"></a>**
19+ 
20+```python
21+mstxMemHeapHandle_t mstxMemHeapRegister(mstxDomainHandle_t domain, mstxMemHeapDesc_t const *desc)
22+```
23+ 
24+**Parameter Description<a id="zh-cn_topic_0000002216005989_section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+<a name="zh-cn_topic_0000002216005989_table827101275518"></a>
29+<table><thead align="left"><tr id="zh-cn_topic_0000002216005989_row429121265517"><th class="cellrowborder" valign="top" width="16.881688168816883%" id="mcps1.2.4.1.1"><p id="zh-cn_topic_0000002216005989_p1329121214558"><a name="zh-cn_topic_0000002216005989_p1329121214558"></a><a name="zh-cn_topic_0000002216005989_p1329121214558"></a>Parameter</p>
30+</th>
31+<th class="cellrowborder" valign="top" width="11.401140114011401%" id="mcps1.2.4.1.2"><p id="zh-cn_topic_0000002216005989_p10230141454318"><a name="zh-cn_topic_0000002216005989_p10230141454318"></a><a name="zh-cn_topic_0000002216005989_p10230141454318"></a>Input/Output</p>
32+</th>
33+<th class="cellrowborder" valign="top" width="71.71717171717171%" id="mcps1.2.4.1.3"><p id="zh-cn_topic_0000002216005989_p83121275519"><a name="zh-cn_topic_0000002216005989_p83121275519"></a><a name="zh-cn_topic_0000002216005989_p83121275519"></a>Description</p>
34+</th>
35+</tr>
36+</thead>
37+<tbody><tr id="zh-cn_topic_0000002216005989_row1131131265511"><td class="cellrowborder" valign="top" width="16.881688168816883%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002216005989_p7669321185110"><a name="zh-cn_topic_0000002216005989_p7669321185110"></a><a name="zh-cn_topic_0000002216005989_p7669321185110"></a>domain</p>
38+</td>
39+<td class="cellrowborder" valign="top" width="11.401140114011401%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002216005989_p723015144436"><a name="zh-cn_topic_0000002216005989_p723015144436"></a><a name="zh-cn_topic_0000002216005989_p723015144436"></a>Input</p>
40+</td>
41+<td class="cellrowborder" valign="top" width="71.71717171717171%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002216005989_p3243153110413"><a name="zh-cn_topic_0000002216005989_p3243153110413"></a><a name="zh-cn_topic_0000002216005989_p3243153110413"></a>Either globalDomain or the handle returned by <a href="../Common/mstxDomainCreateA.md">mstxDomainCreateA</a>.</p>
42+<p id="zh-cn_topic_0000002216005989_p17135131418533"><a name="zh-cn_topic_0000002216005989_p17135131418533"></a><a name="zh-cn_topic_0000002216005989_p17135131418533"></a>Data type: const char *.</p>
43+</td>
44+</tr>
45+<tr id="zh-cn_topic_0000002216005989_row18118485118"><td class="cellrowborder" valign="top" width="16.881688168816883%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002216005989_p211549516"><a name="zh-cn_topic_0000002216005989_p211549516"></a><a name="zh-cn_topic_0000002216005989_p211549516"></a>desc</p>
46+</td>
47+<td class="cellrowborder" valign="top" width="11.401140114011401%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002216005989_p1920117129516"><a name="zh-cn_topic_0000002216005989_p1920117129516"></a><a name="zh-cn_topic_0000002216005989_p1920117129516"></a>Input</p>
48+</td>
49+<td class="cellrowborder" valign="top" width="71.71717171717171%" headers="mcps1.2.4.1.3 ">
50+ 
51+<pre class="screen" id="zh-cn_topic_0000002216005989_screen47021458121411"><a name="zh-cn_topic_0000002216005989_screen47021458121411"></a><a name="zh-cn_topic_0000002216005989_screen47021458121411"></a>typedef enum mstxMemHeapUsageType {
52+ /* @brief This heap memory is used as a memory pool
53+ * Heap memory registered using this usage type must be accessed after secondary allocation registration
54+ */
55+ MSTX_MEM_HEAP_USAGE_TYPE_SUB_ALLOCATOR = 0,
56+} mstxMemHeapUsageType;
57+ 
58+/** @brief Heap memory type
59+ 
60+ * The "type" here refers to the method used to describe the heap memory pointer. Currently, only linearly arranged memory is supported.
61+ * memory, but the capability to support more memory types in the future is reserved here. For example, some APIs return
62+ * multiple handles to describe a memory range, or some high-dimensional memory requires stride, tiling, or
63+ * interlace for description.
64+ */
65+typedef enum mstxMemType {
66+ /** @brief Standard linearly laid out virtual memory
67+ * In this case, mstxMemHeapRegister receives a description of the mstxMemVirtualRangeDesc_t type.
68+ */
69+ MSTX_MEM_TYPE_VIRTUAL_ADDRESS = 0,
70+} mstxMemType;
71+ 
72+typedef struct mstxMemVirtualRangeDesc_t {
73+ uint32_t deviceId; // Device ID corresponding to the memory region
74+ void const *ptr; // Start address of the memory region
75+ uint64_t size; // Length of the memory region
76+} mstxMemVirtualRangeDesc_t;
77+ 
78+typedef struct mstxMemHeapDesc_t {
79+ mstxMemHeapUsageType usage; // Usage mode of the heap memory
80+ mstxMemType type; // Type of the heap memory
81+ void const *typeSpecificDesc; // Description information of the heap memory under the specified memory type
82+} mstxMemHeapDesc_t;</pre>
83+</td>
84+</tr>
85+</tbody>
86+</table>
87+ 
88+**Returns<a id="zh-cn_topic_0000002216005989_section16621124213476"></a>**
89+ 
90+Handle corresponding to the memory pool.
91+ 
92+**Example<a id="zh-cn_topic_0000002216005989_section377820328555"></a>**
93+ 
94+```c
95+mstxMemVirtualRangeDesc_t rangeDesc = {};
96+ rangeDesc.deviceId = deviceId; // Device ID
97+ rangeDesc.ptr = gm; // Start address of the registered memory pool gm
98+ rangeDesc.size = 1024; // Memory pool size
99+ heapDesc.typeSpecificDesc = &rangeDesc;
100+ mstxMemHeapDesc_t heapDesc{};
101+ mstxMemHeapHandle_t memPool = mstxMemHeapRegister(globalDomain, &heapDesc); // Register memory pool
102+```
Adocs/en/api_reference/Mem/mstxMemHeapUnregister.md+69-0
@@ -0,0 +1,69 @@
1+# mstxMemHeapUnregister<a id="mstxMemHeapUnregister"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002215920417_section20806203412478"></a>**
15+ 
16+When a memory pool is unregistered, the regions associated with it are also unregistered.
17+ 
18+**Prototype<a id="zh-cn_topic_0000002215920417_section1121883194711"></a>**
19+ 
20+```python
21+void mstxMemHeapUnregister(mstxDomainHandle_t domain, mstxMemHeapHandle_t heap)
22+```
23+ 
24+**Parameter Description<a id="zh-cn_topic_0000002215920417_section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+<a name="zh-cn_topic_0000002215920417_table827101275518"></a>
29+<table><thead align="left"><tr id="zh-cn_topic_0000002215920417_row429121265517"><th class="cellrowborder" valign="top" width="28.65286528652865%" id="mcps1.2.4.1.1"><p id="zh-cn_topic_0000002215920417_p1329121214558"><a name="zh-cn_topic_0000002215920417_p1329121214558"></a><a name="zh-cn_topic_0000002215920417_p1329121214558"></a>Parameter</p>
30+</th>
31+<th class="cellrowborder" valign="top" width="26.72267226722672%" id="mcps1.2.4.1.2"><p id="zh-cn_topic_0000002215920417_p10230141454318"><a name="zh-cn_topic_0000002215920417_p10230141454318"></a><a name="zh-cn_topic_0000002215920417_p10230141454318"></a>Input/Output</p>
32+</th>
33+<th class="cellrowborder" valign="top" width="44.62446244624462%" id="mcps1.2.4.1.3"><p id="zh-cn_topic_0000002215920417_p83121275519"><a name="zh-cn_topic_0000002215920417_p83121275519"></a><a name="zh-cn_topic_0000002215920417_p83121275519"></a>Description</p>
34+</th>
35+</tr>
36+</thead>
37+<tbody><tr id="zh-cn_topic_0000002215920417_row1131131265511"><td class="cellrowborder" valign="top" width="28.65286528652865%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002215920417_p7669321185110"><a name="zh-cn_topic_0000002215920417_p7669321185110"></a><a name="zh-cn_topic_0000002215920417_p7669321185110"></a>domain</p>
38+</td>
39+<td class="cellrowborder" valign="top" width="26.72267226722672%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002215920417_p723015144436"><a name="zh-cn_topic_0000002215920417_p723015144436"></a><a name="zh-cn_topic_0000002215920417_p723015144436"></a>Input</p>
40+</td>
41+<td class="cellrowborder" valign="top" width="44.62446244624462%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002215920417_p3243153110413"><a name="zh-cn_topic_0000002215920417_p3243153110413"></a><a name="zh-cn_topic_0000002215920417_p3243153110413"></a>domain is the domain to which the memory pool belongs. It can be globalDomain or the handle returned by <a href="../Common/mstxDomainCreateA.md">mstxDomainCreateA</a>.</p>
42+<p id="zh-cn_topic_0000002215920417_p17135131418533"><a name="zh-cn_topic_0000002215920417_p17135131418533"></a><a name="zh-cn_topic_0000002215920417_p17135131418533"></a>Data Type: const char *.</p>
43+</td>
44+</tr>
45+<tr id="zh-cn_topic_0000002215920417_row18118485118"><td class="cellrowborder" valign="top" width="28.65286528652865%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002215920417_p17725843815"><a name="zh-cn_topic_0000002215920417_p17725843815"></a><a name="zh-cn_topic_0000002215920417_p17725843815"></a>heap</p>
46+</td>
47+<td class="cellrowborder" valign="top" width="26.72267226722672%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002215920417_p1920117129516"><a name="zh-cn_topic_0000002215920417_p1920117129516"></a><a name="zh-cn_topic_0000002215920417_p1920117129516"></a>Input</p>
48+</td>
49+<td class="cellrowborder" valign="top" width="44.62446244624462%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002215920417_p15419387397"><a name="zh-cn_topic_0000002215920417_p15419387397"></a><a name="zh-cn_topic_0000002215920417_p15419387397"></a>heap is the handle of the memory pool to be unregistered. It is the return value of <a href="mstxMemHeapRegister.md">mstxMemHeapRegister</a>.</p>
50+<pre class="screen" id="zh-cn_topic_0000002215920417_screen977616221627"><a name="zh-cn_topic_0000002215920417_screen977616221627"></a><a name="zh-cn_topic_0000002215920417_screen977616221627"></a>struct mstxMemHeap_st;
51+typedef struct mstxMemHeap_st mstxMemHeap_t;
52+typedef mstxMemHeap_t* mstxMemHeapHandle_t;</pre>
53+</td>
54+</tr>
55+</tbody>
56+</table>
57+ 
58+**Returns<a id="zh-cn_topic_0000002215920417_section16621124213476"></a>**
59+ 
60+None
61+ 
62+**Example<a id="zh-cn_topic_0000002215920417_section7800053122316"></a>**
63+ 
64+```py
65+mstxMemHeapDesc_t heapDesc{};
66+mstxMemHeapHandle_t memPool = mstxMemHeapRegister(globalDomain, &heapDesc); // Register Memory Poolter Memory Pool
67+...
68+mstxMemHeapUnregister(globalDomain, memPool); // Unregister Memory Poolister Memory Pool
69+```
Adocs/en/api_reference/Mem/mstxMemRegionsRegister.md+81-0
@@ -0,0 +1,81 @@
1+# mstxMemRegionsRegister<a id="mstxMemRegionsRegister"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002180759810_section20806203412478"></a>**
15+ 
16+Registers memory pool secondary allocation. The user must ensure that the memory registered by RegionsRegister is within the range registered by [mstxMemHeapRegister](mstxMemHeapRegister.md); otherwise, the tool will report an out-of-bounds read/write.
17+ 
18+**Prototype<a id="zh-cn_topic_0000002180759810_section1121883194711"></a>**
19+ 
20+```c
21+void mstxMemRegionsRegister(mstxDomainHandle_t domain, mstxMemRegionsRegisterBatch_t const *desc)
22+```
23+ 
24+**Parameter Description<a id="zh-cn_topic_0000002180759810_section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+<a name="zh-cn_topic_0000002180759810_table827101275518"></a>
29+<table><thead align="left"><tr id="zh-cn_topic_0000002180759810_row429121265517"><th class="cellrowborder" valign="top" width="28.65286528652865%" id="mcps1.2.4.1.1"><p id="zh-cn_topic_0000002180759810_p1329121214558"><a name="zh-cn_topic_0000002180759810_p1329121214558"></a><a name="zh-cn_topic_0000002180759810_p1329121214558"></a>Parameter</p>
30+</th>
31+<th class="cellrowborder" valign="top" width="26.7026702670267%" id="mcps1.2.4.1.2"><p id="zh-cn_topic_0000002180759810_p10230141454318"><a name="zh-cn_topic_0000002180759810_p10230141454318"></a><a name="zh-cn_topic_0000002180759810_p10230141454318"></a>Input/Output</p>
32+</th>
33+<th class="cellrowborder" valign="top" width="44.64446444644465%" id="mcps1.2.4.1.3"><p id="zh-cn_topic_0000002180759810_p83121275519"><a name="zh-cn_topic_0000002180759810_p83121275519"></a><a name="zh-cn_topic_0000002180759810_p83121275519"></a>Description</p>
34+</th>
35+</tr>
36+</thead>
37+<tbody><tr id="zh-cn_topic_0000002180759810_row1131131265511"><td class="cellrowborder" valign="top" width="28.65286528652865%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002180759810_p7669321185110"><a name="zh-cn_topic_0000002180759810_p7669321185110"></a><a name="zh-cn_topic_0000002180759810_p7669321185110"></a>domain</p>
38+</td>
39+<td class="cellrowborder" valign="top" width="26.7026702670267%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002180759810_p723015144436"><a name="zh-cn_topic_0000002180759810_p723015144436"></a><a name="zh-cn_topic_0000002180759810_p723015144436"></a>Input</p>
40+</td>
41+<td class="cellrowborder" valign="top" width="44.64446444644465%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002180759810_p3243153110413"><a name="zh-cn_topic_0000002180759810_p3243153110413"></a><a name="zh-cn_topic_0000002180759810_p3243153110413"></a>Either globalDomain or the handle returned by <a href="../Common/mstxDomainCreateA.md">mstxDomainCreateA</a>.</p>
42+<p id="zh-cn_topic_0000002180759810_p17135131418533"><a name="zh-cn_topic_0000002180759810_p17135131418533"></a><a name="zh-cn_topic_0000002180759810_p17135131418533"></a>Data type: const char *.</p>
43+</td>
44+</tr>
45+<tr id="zh-cn_topic_0000002180759810_row18118485118"><td class="cellrowborder" valign="top" width="28.65286528652865%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002180759810_p211549516"><a name="zh-cn_topic_0000002180759810_p211549516"></a><a name="zh-cn_topic_0000002180759810_p211549516"></a>desc</p>
46+</td>
47+<td class="cellrowborder" valign="top" width="26.7026702670267%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002180759810_p1920117129516"><a name="zh-cn_topic_0000002180759810_p1920117129516"></a><a name="zh-cn_topic_0000002180759810_p1920117129516"></a>Input</p>
48+</td>
49+<td class="cellrowborder" valign="top" width="44.64446444644465%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002180759810_p14824161520710"><a name="zh-cn_topic_0000002180759810_p14824161520710"></a><a name="zh-cn_topic_0000002180759810_p14824161520710"></a>Description information of the memory region to be sub-allocated from the memory pool. Cannot be null.</p>
50+ 
51+<pre class="screen" id="zh-cn_topic_0000002180759810_screen19859174319117"><a name="zh-cn_topic_0000002180759810_screen19859174319117"></a><a name="zh-cn_topic_0000002180759810_screen19859174319117"></a>struct mstxMemRegion_st;
52+typedef struct mstxMemRegion_st mstxMemRegion_t;
53+typedef mstxMemRegion_t* mstxMemRegionHandle_t;
54+ 
55+typedef struct mstxMemRegionsRegisterBatch_t {
56+ mstxMemHeapHandle_t heap; // Handle of the memory pool for sub-allocation
57+ mstxMemType regionType; // Memory type of the memory region
58+ size_t regionCount; // Number of memory regions
59+ void const *regionDescArray; // Memory region description data
60+ mstxMemRegionHandle_t* regionHandleArrayOut; // Returned handle array obtained from registering sub-allocation
61+} mstxMemRegionsRegisterBatch_t;</pre>
62+</td>
63+</tr>
64+</tbody>
65+</table>
66+ 
67+**Return Value Description<a id="zh-cn_topic_0000002180759810_section16621124213476"></a>**
68+ 
69+None
70+ 
71+**Example<a id="zh-cn_topic_0000002180759810_section377820328555"></a>**
72+ 
73+```shell
74+mstxMemRegionsRegisterBatch_t regionsDesc{};
75+regionsDesc.heap = memPool;
76+regionsDesc.regionType = MSTX_MEM_TYPE_VIRTUAL_ADDRESS;
77+regionsDesc.regionCount = 1;
78+regionsDesc.regionDescArray = rangesDesc;
79+regionsDesc.regionHandleArrayOut = regionHandles;
80+mstxMemRegionsRegister(globalDomain, regionsDesc); // Secondary allocation registrationry Allocation Registration
81+```
Adocs/en/api_reference/Mem/mstxMemRegionsUnregister.md+86-0
@@ -0,0 +1,86 @@
1+# mstxMemRegionsUnregister<a id="mstxMemRegionsUnregister"></a>
2+ 
3+**Supported Products<a id="section8178181118225"></a>**
4+ 
5+|Product|Supported|
6+|--|:-:|
7+|Ascend 910_95 AI Processors|√|
8+|Atlas A3 training products/Atlas A3 inference products|√|
9+|Atlas A2 training products/Atlas A2 inference products|√|
10+|Atlas 200I/500 A2 inference products|√|
11+|Atlas inference products|√|
12+|Atlas training products|√|
13+ 
14+**Function<a id="zh-cn_topic_0000002180600118_section20806203412478"></a>**
15+ 
16+Unregisters secondary allocation of a memory pool.
17+ 
18+**Prototype<a id="zh-cn_topic_0000002180600118_section1121883194711"></a>**
19+ 
20+```c
21+void mstxMemRegionsUnregister(mstxDomainHandle_t domain, mstxMemRegionsUnregisterBatch_t const *desc)
22+```
23+ 
24+**Parameter Description<a id="zh-cn_topic_0000002180600118_section11506138144714"></a>**
25+ 
26+**Table 1** Parameter description
27+ 
28+<a name="zh-cn_topic_0000002180600118_table827101275518"></a>
29+<table><thead align="left"><tr id="zh-cn_topic_0000002180600118_row429121265517"><th class="cellrowborder" valign="top" width="28.652865286528655%" id="mcps1.2.4.1.1"><p id="zh-cn_topic_0000002180600118_p1329121214558"><a name="zh-cn_topic_0000002180600118_p1329121214558"></a><a name="zh-cn_topic_0000002180600118_p1329121214558"></a>Parameter</p>
30+</th>
31+<th class="cellrowborder" valign="top" width="21.002100210021005%" id="mcps1.2.4.1.2"><p id="zh-cn_topic_0000002180600118_p10230141454318"><a name="zh-cn_topic_0000002180600118_p10230141454318"></a><a name="zh-cn_topic_0000002180600118_p10230141454318"></a>Input/Output</p>
32+</th>
33+<th class="cellrowborder" valign="top" width="50.34503450345035%" id="mcps1.2.4.1.3"><p id="zh-cn_topic_0000002180600118_p83121275519"><a name="zh-cn_topic_0000002180600118_p83121275519"></a><a name="zh-cn_topic_0000002180600118_p83121275519"></a>Description</p>
34+</th>
35+</tr>
36+</thead>
37+<tbody><tr id="zh-cn_topic_0000002180600118_row1131131265511"><td class="cellrowborder" valign="top" width="28.652865286528655%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002180600118_p7669321185110"><a name="zh-cn_topic_0000002180600118_p7669321185110"></a><a name="zh-cn_topic_0000002180600118_p7669321185110"></a>domain</p>
38+</td>
39+<td class="cellrowborder" valign="top" width="21.002100210021005%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002180600118_p723015144436"><a name="zh-cn_topic_0000002180600118_p723015144436"></a><a name="zh-cn_topic_0000002180600118_p723015144436"></a>Input</p>
40+</td>
41+<td class="cellrowborder" valign="top" width="50.34503450345035%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002180600118_p3243153110413"><a name="zh-cn_topic_0000002180600118_p3243153110413"></a><a name="zh-cn_topic_0000002180600118_p3243153110413"></a>Either globalDomain or the handle returned by <a href="../Common/mstxDomainCreateA.md">mstxDomainCreateA</a>.</p>
42+<p id="zh-cn_topic_0000002180600118_p17135131418533"><a name="zh-cn_topic_0000002180600118_p17135131418533"></a><a name="zh-cn_topic_0000002180600118_p17135131418533"></a>Data Type: const char *.</p>
43+</td>
44+</tr>
45+<tr id="zh-cn_topic_0000002180600118_row18118485118"><td class="cellrowborder" valign="top" width="28.652865286528655%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000002180600118_p211549516"><a name="zh-cn_topic_0000002180600118_p211549516"></a><a name="zh-cn_topic_0000002180600118_p211549516"></a>desc</p>
46+</td>
47+<td class="cellrowborder" valign="top" width="21.002100210021005%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000002180600118_p1920117129516"><a name="zh-cn_topic_0000002180600118_p1920117129516"></a><a name="zh-cn_topic_0000002180600118_p1920117129516"></a>Input</p>
48+</td>
49+<td class="cellrowborder" valign="top" width="50.34503450345035%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000002180600118_p14824161520710"><a name="zh-cn_topic_0000002180600118_p14824161520710"></a><a name="zh-cn_topic_0000002180600118_p14824161520710"></a>The input description information must be the input description information from a previous <a href="mstxMemHeapRegister.md">mstxMemHeapRegister</a> call; otherwise, the tool will print an error message.</p>
50+ 
51+<pre class="screen" id="zh-cn_topic_0000002180600118_screen1854493213265"><a name="zh-cn_topic_0000002180600118_screen1854493213265"></a><a name="zh-cn_topic_0000002180600118_screen1854493213265"></a>typedef enum mstxMemRegionRefType {
52+ // Describes a memory reference via a pointer
53+ MSTX_MEM_REGION_REF_TYPE_POINTER = 0,
54+ // Describes a memory reference via a handle
55+ MSTX_MEM_REGION_REF_TYPE_HANDLE
56+} mstxMemRegionRefType;
57+ 
58+typedef struct mstxMemRegionRef_t {
59+ mstxMemRegionRefType refType; // Describes how the memory is referenced
60+ union {
61+ void const* pointer; // When the current memory reference is described by a pointer, this stores the memory region pointer
62+ mstxMemRegionHandle_t handle; // When the memory reference is described by a handle, this stores the handle of the memory region
63+ };
64+} mstxMemRegionRef_t;
65+ 
66+typedef struct mstxMemRegionsUnregisterBatch_t {
67+ size_t refCount; // Number of memory references
68+ mstxMemRegionRef_t const *refArray; // Array of memory region references to unregister
69+} mstxMemRegionsUnregisterBatch_t;</pre>
70+</td>
71+</tr>
72+</tbody>
73+</table>
74+ 
75+**Returns<a id="zh-cn_topic_0000002180600118_section16621124213476"></a>**
76+ 
77+None
78+ 
79+**Example<a id="zh-cn_topic_0000002180600118_section377820328555"></a>**
80+ 
81+```python
82+mstxMemRegionsUnregisterBatch_t refsDesc = {}
83+refsDesc.refCount = 1;
84+refsDesc.refArray = regionRef;
85+mstxMemRegionsUnregister(globalDomain, &refsDesc); // Unregister secondary allocationster Secondary Allocation
86+```
Adocs/en/api_reference/README.md+30-0
@@ -0,0 +1,30 @@
1+# **MindStudio Tools Extension Library API Reference**
2+ 
3+This section describes the instrumentation APIs of the MindStudio Tools Extension Library (msTX). You can customize the collection period or the start and end timestamps of key functions to identify information such as key functions or iterations, enabling quick delimitation of performance and operator issues.
4+ 
5+By default, the msTX APIs have no functionality. After calling the msTX APIs in your user application, you need to enable the msTX instrumentation feature according to different scenarios, for example, configuring `--mstx=on` when collecting data using the msprof command line, configuring `ACL_PROF_MSPROFTX` when collecting data using the AscendCL API, and configuring `mstx=True` when collecting data using the Ascend PyTorch Profiler interface.
6+ 
7+- Library file `libms_tools_ext.so` path: `${INSTALL_DIR}/lib64/`.
8+- When compiling with the header file, the user program needs to link the dl library during compilation. Header file `ms_tools_ext.h` path: `${INSTALL_DIR}/include/mstx`.
9+ 
10+Replace `${INSTALL_DIR}` with the file storage path after CANN software installation. For example, if you install CANN as the root user, the default file storage path is: `/usr/local/Ascend/cann`.
11+ 
12+**API List<a id="section6371427124715"></a>**
13+ 
14+**Table 1** MindStudio mstx API list
15+ 
16+|API|Description|
17+|--|--|
18+|[mstxGetToolId](./Common/mstxGetToolId.md)|Obtains the ID of the tool currently intercepting mstx APIs.|
19+|[mstxMarkA](./Common/mstxMarkA.md)|Marks an instantaneous event.|
20+|[mstxRangeStartA](./Common/mstxRangeStartA.md)|Marks the start of a range event.|
21+|[mstxRangeEnd](./Common/mstxRangeEnd.md)|Marks the end of a range event.|
22+|[mstxDomainCreateA](./Common/mstxDomainCreateA.md)|Creates a custom domain.|
23+|[mstxDomainDestroy](./Common/mstxDomainDestroy.md)|Destroys a specified domain. A destroyed domain cannot be used again and must be re-created.|
24+|[mstxDomainMarkA](./Common/mstxDomainMarkA.md)|Marks an instantaneous event within a specified domain.|
25+|[mstxDomainRangeStartA](./Common/mstxDomainRangeStartA.md)|Marks the start of a range event within a specified domain.|
26+|[mstxDomainRangeEnd](./Common/mstxDomainRangeEnd.md)|Marks the end of a range event within a specified domain.|
27+|[mstxMemHeapRegister](./Mem/mstxMemHeapRegister.md)|Registers a memory pool.|
28+|[mstxMemRegionsRegister](./Mem/mstxMemRegionsRegister.md)|Registers secondary allocation of a memory pool.|
29+|[mstxMemRegionsUnregister](./Mem/mstxMemRegionsUnregister.md)|Unregisters secondary allocation of a memory pool.|
30+|[mstxMemHeapUnregister](./Mem/mstxMemHeapUnregister.md)|When a memory pool is unregistered, the associated regions are also unregistered.|
Adocs/en/contributing/contributing_guide.md+11-0
@@ -0,0 +1,11 @@
1+# Contribution Guide
2+ 
3+<br>
4+ 
5+## 1. Contribution Workflow and Specifications
6+ 
7+Before participating in development, familiarize yourself with the contribution workflow and guidelines. For details, see [Contribution Workflow and Guidelines](https://gitcode.com/Ascend/msot/blob/master/docs/en/common/contribute_workflow.md).
8+ 
9+## 2. Development Guide
10+ 
11+Introduces development environment setup, code compilation, testing methods, and more. For details, see [msTX Development Guide](../development_guide/develop_guide.md).
Adocs/en/development_guide/develop_guide.md+33-0
@@ -0,0 +1,33 @@
1+# MindStudio Tools Extension Library Development Guide
2+ 
3+<br>
4+ 
5+## 1. Development Environment Preparation
6+ 
7+For details, see [Operator Tool Development Environment Setup Guide](https://gitcode.com/Ascend/msot/blob/master/docs/en/common/dev_env_setup.md).
8+ 
9+## 2. Compilation and Packaging
10+ 
11+```shell
12+python build.py
13+```
14+ 
15+## 3. Unit Testing
16+ 
17+You can run UT tests for C/CPP/PYTHON code using a one-click script:
18+ 
19+```sh
20+python build.py test
21+```
22+ 
23+If the output is similar to the following, and the number of run test cases equals the number of passed test cases, it indicates success:
24+ 
25+```text
26+[----------] 4 tests from CoreApi (8ms total)
27+```
28+ 
29+```text
30+============= 4 passed in 0.03s =============
31+```
32+ 
33+NOTE: You need to install pytest in the environment beforehand to run Python tests. There are multiple independent test suites. If the output results are similar to the example, it indicates successful execution.
Adocs/en/install_guide/mstx_install_guide.md+41-0
@@ -0,0 +1,41 @@
1+# MindStudio Tools Extension Library Installation Guide
2+ 
3+## 1. Dependencies
4+ 
5+Since the code in this project depends on Python 3 header files, the `python3-dev` package must be installed in the build environment. You can install it by running the following command:
6+ 
7+```sh
8+apt-get install python3-dev
9+```
10+ 
11+## 2. Building and Packaging
12+ 
13+```sh
14+python build.py
15+```
16+ 
17+## 3. Installing the whl Package
18+ 
19+```sh
20+cd output
21+pip3 install mstx-xxxxx.whl
22+```
23+ 
24+## 4. Upgrade
25+ 
26+To replace an existing installed whl package in the runtime environment with a new whl package, perform the following installation operation:
27+ 
28+```sh
29+pip3 install mstx-xxxxx.whl --force-reinstall
30+```
31+ 
32+During installation, if prompted whether to replace the existing package:
33+Enter "y", and the package will automatically complete the upgrade operation.
34+ 
35+## 5. Uninstallation
36+ 
37+To uninstall, use the following command:
38+ 
39+```sh
40+pip3 uninstall mstx-xxxxx.whl
41+```
Adocs/en/legal/disclaimer.md+14-0
@@ -0,0 +1,14 @@
1+# Disclaimer
2+ 
3+## To Users
4+ 
5+- This tool is intended solely for debugging and development. Users are responsible for any risks and should carefully review the following information:
6+ - Data processing and deletion: Users are responsible for managing and deleting any data generated while using this tool. Users are advised to delete such data promptly after use to prevent information leakage.
7+ - Data confidentiality and transmission: Users understand and agree not to share or transmit any data generated by this tool. Neither the tool nor its developers are responsible for any information leaks, data breaches, or other negative consequences.
8+ - User input security: Users are responsible for the security of any commands they enter and for any risks or losses resulting from improper input. The tool and its developers are not liable for issues caused by incorrect command usage.
9+- Disclaimer scope: This disclaimer applies to all individuals and entities using this tool. By using the tool, you acknowledge and accept this statement and assume all risks and responsibilities arising from its use. If you do not agree, please stop using the tool immediately.
10+- Before using this tool, **please read and understand the preceding disclaimer**. If you have any questions, contact the developer.
11+ 
12+## To Data Owners
13+ 
14+If you do not want your model or dataset to be mentioned in this tool, or if you wish to update its description, please submit an issue on GitCode. We will delete or update your description according to your request. Thank you for your understanding and contribution to this tool.
Adocs/en/legal/license_notice.md+9-0
@@ -0,0 +1,9 @@
1+# LICENSE Statement
2+ 
3+## Product Code License
4+ 
5+The product code is licensed under the Mulan Permissive Software License, Version 2 (Mulan PSL v2). For details, see the [LICENSE file](../../../LICENSE).
6+ 
7+## Document License in the `docs` Directory
8+ 
9+Documents in the `docs` directory are licensed under the CC BY 4.0 License. For details, see the [LICENSE file](../../LICENSE).
Adocs/en/legal/security_statement.md+83-0
@@ -0,0 +1,83 @@
1+# Security Statement
2+ 
3+## System Security Hardening
4+ 
5+You are advised to enable **address space layout randomization** (ASLR) level 2 in the system. Run the following command to enable it:
6+ 
7+```sh
8+echo 2 > /proc/sys/kernel/randomize_va_space
9+```
10+ 
11+## Running User Recommendations
12+ 
13+1. All tools in this repository are designed to be installed and used with minimal permissions. For security reasons and to follow the principle of least privilege, do not use `root` or other privileged accounts to run any of the tools. You are advised to install and execute them as a regular user.
14+ 
15+2. If a tool depends on CANN, use the CANN package installed by the same non-privileged user. After running the `source` command, do not modify environment variables in `set_env.sh`.
16+ 
17+3. Before using any tool in this repository, you are advised to set `umask` to `0027` or a more restrictive value to ensure that generated files meet the minimum permission security requirements.
18+ 
19+## File Permission Control
20+ 
21+1. When providing input files to the tool as command inputs, it is recommended that the file owner match the process owner of the tool and that file permissions restrict write access for `group` and `others`. By default, tool files written to the drive are not writable by others. You can manually control the permissions for the generated files as needed.
22+ 
23+2. Proper permission control is essential during installation and use. For details, see the following table.
24+ 
25+## File Permission Reference
26+ 
27+| Type | Maximum Linux Permission|
28+| ---------------------------------- | ------------------- |
29+| Home directory | 750 (rwxr-x---) |
30+| Program files (including scripts and libraries) | 550 (r-xr-x---) |
31+| Program file directory | 550 (r-xr-x---) |
32+| Configuration files | 640 (rw-r-----) |
33+| Configuration file directory | 750 (rwxr-x---) |
34+| Log files (recorded or archived) | 440 (r--r-----) |
35+| Log files (being recorded) | 640 (rw-r-----) |
36+| Log file directory | 750 (rwxr-x---) |
37+| Debug files | 640 (rw-r-----) |
38+| Debug file directory | 750 (rwxr-x---) |
39+| Temporary file directory | 750 (rwxr-x---) |
40+| Maintenance and upgrade file directory | 770 (rwxrwx---) |
41+| Service data files | 640 (rw-r-----) |
42+| Service data file directory | 750 (rwxr-x---) |
43+| Key components, private keys, certificates, and ciphertext file directory| 700 (rwx------) |
44+| Key components, private keys, certificates, and ciphertext files | 600 (rw-------) |
45+| APIs and scripts for encryption and decryption | 500 (r-x------) |
46+ 
47+## Vulnerability Security Statement
48+ 
49+For details, see [MindStudio Vulnerability Handling Procedure](./vulnerability_handling_procedure.md).
50+ 
51+## Data Security
52+ 
53+During the use of this tool, certain code-line-related features may access the user's operator code. If the operator code is confidential and must not be leaked, you should delete the corresponding deliverables promptly after use to prevent unnecessary information disclosure.
54+ 
55+## Build Security
56+ 
57+This tool supports source code compilation and installation. During compilation, third-party dependencies may be downloaded and build shell scripts executed, resulting in temporary program files and build directories. You may control permissions on files within the source code directory as needed to mitigate security risks. During the build process, you may also modify build scripts as necessary to avoid related security risks and ensure the security of build artifacts.
58+ 
59+## Runtime Security
60+ 
61+1. If an exception occurs during operation, the tool will exit the process and print error messages. This is expected behavior. You are advised to locate the specific cause of the error based on the error prompts, such as by viewing log files or result files generated during the collection and parsing process.
62+ 
63+2. During tool usage, no security validation is performed on user input programs. You need to ensure the security of the programs yourself.
64+ 
65+## Public Network Address Statement
66+ 
67+The tool does not involve the use of public IP addresses.
68+ 
69+## Public API Statement
70+ 
71+This project is developed in Python with source code released. It is recommended to use the public APIs specified in the documentation. Directly calling source code APIs that are not explicitly disclosed is not recommended.
72+ 
73+## Usage of Secure Functions
74+ 
75+While unsecure functions are not forcibly disabled, you are advised to use their secure variants that explicitly take a buffer length parameter, for example, `memset_s` and `memcpy_s`.
76+ 
77+## Communication Security Hardening
78+ 
79+Remote communication is not involved. You are advised to use the tool in a secure network environment with a firewall or LAN, and pay attention to the communication security of other third-party software.
80+ 
81+## Communication Matrix
82+ 
83+External port communication is not involved.
Adocs/en/legal/vulnerability_handling_procedure.md+88-0
@@ -0,0 +1,88 @@
1+# MindStudio Vulnerability Mechanism
2+ 
3+The MindStudio community highly values the security of community versions. Vulnerability management specialists are specifically designated to handle vulnerability-related matters. To build a more secure AI full-process toolchain, we look forward to your participation.
4+ 
5+## Vulnerability Handling Process
6+ 
7+For each security vulnerability, the MindStudio community assigns personnel to follow up and handle it. The end-to-end vulnerability handling process is shown in the following figure.
8+ 
9+![Vulnerability Handling Procedure](../figures/vulnerability_handling_procedure.png)
10+ 
11+The following sections explain the vulnerability reporting, assessment, and disclosure processes.
12+ 
13+## Vulnerability Reporting
14+ 
15+You can contact the MindStudio community team by submitting an issue. We will arrange for a security vulnerability specialist to contact you promptly.
16+To ensure security, do not describe specific information related to security and privacy in the issue.
17+ 
18+### Response to Reports
19+ 
20+1. The MindStudio community will confirm, analyze, and report security vulnerability issues within three working days, while initiating the security handling process.
21+2. The MindStudio security team will assign confirmed security vulnerability issues to dedicated personnel and follow up on them.
22+3. During the process of classifying, confirming, and fixing security vulnerabilities, as well as releasing patches, we will provide timely updates on the report.
23+ 
24+## Vulnerability Assessment
25+ 
26+The industry widely uses the CVSS standard to assess vulnerability severity. When using CVSS v3.1 for vulnerability assessment, MindStudio sets specific attack scenarios and performs assessments based on the actual impact within those scenarios. Vulnerability severity assessment involves assessing the difficulty of exploitation as well as the impact on confidentiality, integrity, and availability after exploitation, resulting in a numerical score.
27+ 
28+### Vulnerability Assessment Metrics
29+ 
30+MindStudio assesses the severity level of a vulnerability using the following vectors:
31+ 
32+- Attack vector (AV): indicates the "remoteness" of an attack and how a vulnerability can be exploited.
33+- Attack complexity (AC): describes the difficulty of executing an attack and the factors required for a successful attack.
34+- User interaction (UI): determines whether the attack requires user participation.
35+- Privileges required (PR): records the level of user authentication required for a successful attack.
36+- Scope (S): determines whether an attack can affect components with different permission levels.
37+- Confidentiality (C): measures the impact resulting from information disclosure to unauthorized parties.
38+- Integrity (I): measures the impact resulting from information tampering.
39+- Availability (A): measures the impact on users' access to data or services when needed.
40+ 
41+### Assessment Principles
42+ 
43+- Assess the severity level of a vulnerability, not the risk.
44+- The assessment must be based on an attack scenario where a successful attack can compromise the confidentiality, integrity, and availability of the system.
45+- When a security vulnerability has multiple attack scenarios, use the scenario with the greatest impact (the highest CVSS score) as the basis.
46+- If a vulnerability exists in an embedded or invoked library, perform the assessment after determining the attack scenario based on how the library is used in the product.
47+- If a security defect cannot be triggered or does not affect confidentiality, integrity, or availability (CIA), the CVSS score is 0.
48+ 
49+### Assessment Procedure
50+ 
51+To assess the severity level of a vulnerability, perform the following steps:
52+ 
53+1. Set a possible attack scenario and score based on this attack scenario.
54+2. Identify the vulnerable component and affected components.
55+ 
56+3. Select values for base metrics.
57+ 
58+ - Select values for the exploitability metrics (attack vector, attack complexity, privileges required, user interaction, and scope) based on the vulnerable component.
59+ 
60+ - Ensure impact metrics (confidentiality, integrity, and availability) reflect the impact on either the vulnerable component or the affected components, whichever is more severe.
61+ 
62+### Severity Rating
63+ 
64+| **Severity Rating** | **CVSS Score** | **Vulnerability Fix Time** |
65+| ------------------------------- | --------------------- | ---------------- |
66+| Critical | 9.0~10.0 | 7 days |
67+| High | 7.0~8.9 | 14 days |
68+| Medium | 4.0~6.9 | 30 days |
69+| Low | 0.1~3.9 | 30 days |
70+ 
71+## Vulnerability Disclosure
72+ 
73+After a security vulnerability is fixed, the MindStudio community will release a security advisory (SA) and security notice (SN). The security advisory contains the technical details, type, reporter, CVE ID, affected versions, and fixed versions of the vulnerability.
74+To ensure security for MindStudio users, the MindStudio community will not publicly disclose, discuss, or confirm security issues until after investigation and fixing are complete and an SA has been released.
75+ 
76+## Appendixes
77+ 
78+### MindStudio SA
79+ 
80+Currently maintained versions have no security vulnerabilities.
81+ 
82+### MindStudio SN
83+ 
84+Vulnerability descriptions for third-party open-source components:
85+ 
86+| CVE ID | Third-Party Component Name | Affected MindStudio Tool/Plugin| Status | Description |
87+| ------- | ------------ | --------------------------- | ---- | ---- |
88+| - | - | - | - | - |
Adocs/en/release_notes/release_notes.md+37-0
@@ -0,0 +1,37 @@
1+# MindStudio Tools Extension Library Release Notes
2+ 
3+## Version Compatibility
4+ 
5+### Product Version Information
6+ 
7+| Product | Version | Version Type |
8+|------|-------|------|
9+| msTX | 26.0.0 | Internal release |
10+| msTX | 8.3.0 | Official release |
11+ 
12+### Related Product Version Mapping
13+ 
14+| msTX | CANN Version | Python Version |
15+|----------|-----------------|----------|
16+| 26.0.0 | 9.0.0 or later | Python 3.11 or later |
17+| 8.3.0 | 8.2.RC1 or later | Python 3.11 or later |
18+ 
19+## Version Compatibility
20+ 
21+No compatibility changes.
22+ 
23+## Feature Changes
24+ 
25+### 26.0.0
26+ 
27+No new features.
28+ 
29+### 8.3.0
30+ 
31+Initial release with the following features:
32+ 
33+1. Provides core tracing APIs, supporting code execution point marking and scope measurement.
34+ 
35+2. Provides domain management APIs for categorizing marks and scopes, enabling data type isolation in multi-tool scenarios.
36+ 
37+3. Provides memory tracing APIs, supporting registration and deregistration of memory regions for memory debugging tools.