README.md
1# Utils<a name="EN-US_TOPIC_0000001121139825"></a>
2
3- [Overview](#section62661387114)
4- [Directory Structure](#section1464106163817)
5- [Usage](#section25021123178)
6- [Repositories Involved](#section4571352889)
7
8## Overview<a name="section62661387114"></a>
9
10The Utils repository stores basic components of OpenHarmony. These basic components are used by OpenHarmony subsystems and upper-layer applications.
11
12The Utils library provides the following capabilities on different platforms:
13
14- LiteOS Cortex-M \(Hi3861 platform\): key value \(KV\) store, file operations, timer, and system attribute dumping
15- LiteOS Cortex-A \(Hi3516 or Hi3518 platform\): KV store, timer, JavaScript APIs for device query and data storage, and system attribute dumping
16
17**Table 1** Utils capabilities
18
19<a name="en-us_topic_0000001052623010_table206292206282"></a>
20<table><thead align="left"><tr id="en-us_topic_0000001052623010_row8629020112819"><th class="cellrowborder" valign="top" width="21.22%" id="mcps1.2.4.1.1"><p id="en-us_topic_0000001052623010_p66291220192816"><a name="en-us_topic_0000001052623010_p66291220192816"></a><a name="en-us_topic_0000001052623010_p66291220192816"></a>Module</p>
21</th>
22<th class="cellrowborder" valign="top" width="24.77%" id="mcps1.2.4.1.2"><p id="en-us_topic_0000001052623010_p3629122014289"><a name="en-us_topic_0000001052623010_p3629122014289"></a><a name="en-us_topic_0000001052623010_p3629122014289"></a>Platform</p>
23</th>
24<th class="cellrowborder" valign="top" width="54.010000000000005%" id="mcps1.2.4.1.3"><p id="en-us_topic_0000001052623010_p206298206288"><a name="en-us_topic_0000001052623010_p206298206288"></a><a name="en-us_topic_0000001052623010_p206298206288"></a>Description</p>
25</th>
26</tr>
27</thead>
28<tbody><tr id="en-us_topic_0000001052623010_row1162992082812"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="en-us_topic_0000001052623010_p136291920192814"><a name="en-us_topic_0000001052623010_p136291920192814"></a><a name="en-us_topic_0000001052623010_p136291920192814"></a>KV store</p>
29</td>
30<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="en-us_topic_0000001052623010_p5629112019284"><a name="en-us_topic_0000001052623010_p5629112019284"></a><a name="en-us_topic_0000001052623010_p5629112019284"></a>LiteOS Cortex-M and LiteOS Cortex-A</p>
31</td>
32<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="en-us_topic_0000001052623010_p3630112072811"><a name="en-us_topic_0000001052623010_p3630112072811"></a><a name="en-us_topic_0000001052623010_p3630112072811"></a>Provides KV storage for applications.</p>
33</td>
34</tr>
35<tr id="en-us_topic_0000001052623010_row116301920152816"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="en-us_topic_0000001052623010_p96300207286"><a name="en-us_topic_0000001052623010_p96300207286"></a><a name="en-us_topic_0000001052623010_p96300207286"></a>File operation</p>
36</td>
37<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="en-us_topic_0000001052623010_p1463032012281"><a name="en-us_topic_0000001052623010_p1463032012281"></a><a name="en-us_topic_0000001052623010_p1463032012281"></a>LiteOS Cortex-M</p>
38</td>
39<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="en-us_topic_0000001052623010_p163042052810"><a name="en-us_topic_0000001052623010_p163042052810"></a><a name="en-us_topic_0000001052623010_p163042052810"></a>Provides unified file operation interfaces that can be used on different underlying chip components.</p>
40</td>
41</tr>
42<tr id="en-us_topic_0000001052623010_row1163022022812"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="en-us_topic_0000001052623010_p66308202284"><a name="en-us_topic_0000001052623010_p66308202284"></a><a name="en-us_topic_0000001052623010_p66308202284"></a>Timer</p>
43</td>
44<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="en-us_topic_0000001052623010_p26301620192820"><a name="en-us_topic_0000001052623010_p26301620192820"></a><a name="en-us_topic_0000001052623010_p26301620192820"></a>LiteOS Cortex-M and LiteOS Cortex-A</p>
45</td>
46<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="en-us_topic_0000001052623010_p2630172062815"><a name="en-us_topic_0000001052623010_p2630172062815"></a><a name="en-us_topic_0000001052623010_p2630172062815"></a>Provides unified timer operation interfaces that can be used on different underlying chip components.</p>
47</td>
48</tr>
49<tr id="en-us_topic_0000001052623010_row363012202282"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="en-us_topic_0000001052623010_p4502105418285"><a name="en-us_topic_0000001052623010_p4502105418285"></a><a name="en-us_topic_0000001052623010_p4502105418285"></a>JavaScript API</p>
50</td>
51<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="en-us_topic_0000001052623010_p199870135293"><a name="en-us_topic_0000001052623010_p199870135293"></a><a name="en-us_topic_0000001052623010_p199870135293"></a>LiteOS Cortex-A</p>
52</td>
53<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="en-us_topic_0000001052623010_p1550005422814"><a name="en-us_topic_0000001052623010_p1550005422814"></a><a name="en-us_topic_0000001052623010_p1550005422814"></a>Provides JavaScript APIs for obtaining device information and storing data.</p>
54</td>
55</tr>
56<tr id="en-us_topic_0000001052623010_row5553145162815"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="en-us_topic_0000001052623010_p106300200288"><a name="en-us_topic_0000001052623010_p106300200288"></a><a name="en-us_topic_0000001052623010_p106300200288"></a>System attribute dumping</p>
57</td>
58<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="en-us_topic_0000001052623010_p16300204280"><a name="en-us_topic_0000001052623010_p16300204280"></a><a name="en-us_topic_0000001052623010_p16300204280"></a>LiteOS Cortex-M and LiteOS Cortex-A</p>
59</td>
60<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="en-us_topic_0000001052623010_p1563018208286"><a name="en-us_topic_0000001052623010_p1563018208286"></a><a name="en-us_topic_0000001052623010_p1563018208286"></a>Provides the command line tool for dumping system attributes.</p>
61</td>
62</tr>
63</tbody>
64</table>
65
66## Directory Structure<a name="section1464106163817"></a>
67
68```
69utils/native/lite/ # Root directory
70├── file # Implementation of the file system APIs
71├── hals # HAL directory
72│ └── file # Header files of the hardware abstraction layer for file operations
73├── include # Header files of external APIs
74├── js # JavaScript APIs
75│ └── builtin
76│ ├── common
77│ ├── deviceinfokit # Device information kit
78│ ├── filekit # File kit
79│ └── kvstorekit # KV store kit
80├── kal # KAL directory
81│ └── timer # KAL implementation of the timer
82├── kv_store # KV store implementation
83│ ├── innerkits # Internal KV store APIs
84│ └── src # KV store source file
85├── memory
86│ └── include # Memory pool management APIs
87├── os_dump # System attribute dumping
88└── timer_task # Timer implementation
89```
90
91## Usage<a name="section25021123178"></a>
92
93- **KV store**
94
95 ```
96 // Store or update the value of a key.
97 const char key1[] = "key_sample";
98 const char defValue[] = "test case of key value store.";
99 int ret = UtilsSetValue(key1, defValue);
100
101 // Obtain the value of the key.
102 char value1[32] = {0};
103 ret = UtilsGetValue(key1, value1, 32);
104
105 // Delete the value of the key.
106 UtilsDeleteValue(key1);
107 ```
108
109- **File operation**
110
111 ```
112 // Open or create a file.
113 const char fileName[] = "testfile";
114 int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0);
115
116 // Write a specified length of data into a file with the specified file descriptor.
117 const char defValue[] = "test case of file system.";
118 int ret = UtilsFileWrite(fd, defValue, strlen(defValue));
119
120 // Close a file with a specified file descriptor.
121 UtilsFileClose(fd);
122
123 // Obtain the file size.
124 int fileLen = 0;
125 ret = UtilsFileStat(fileName, &fileLen);
126 printf("file size = %d\n", fileLen);
127
128 // Adjust the read and write position offset in a file.
129 int fd1 = UtilsFileOpen(fileName, O_RDWR_FS, 0);
130 ret = UtilsFileSeek(fd1, 5, SEEK_SET_FS);
131
132 // Read a specified length of data from a file with the specified file descriptor and write the data into the buffer.
133 char buf[32] = {0};
134 int readLen = UtilsFileRead(fd1, buf, 32);
135 ret = UtilsFileClose(fd1);
136 printf("read len = %d : buf = %s\n", readLen, buf);
137
138 // Delete a specified file.
139 ret = UtilsFileDelete(fileName);
140 ```
141
142
143- **System attribute dumping**
144
145 LiteOS Cortex-M kernel: Run the following command over the serial port to dump the current system parameters:
146
147 ```
148 AT+SYSPARA
149 ```
150
151 LiteOS Cortex-A kernel: Run the **os\_dump** command in the **bin** directory to dump the current system parameters:
152
153 ```
154 ./bin/os_dump syspara
155 ```
156
157
158## Repositories Involved<a name="section4571352889"></a>
159
160[Utils](https://gitee.com/openharmony/docs/blob/master/en/readme/utils.md)
161
162utils\_native\_lite
163
164
README_zh.md
1# 项目介绍<a name="ZH-CN_TOPIC_0000001121139825"></a>
2
3- [简介](#section62661387114)
4- [目录](#section1464106163817)
5- [使用](#section25021123178)
6- [涉及仓](#section4571352889)
7
8## 简介<a name="section62661387114"></a>
9
10公共基础库存放OpenHarmony通用的基础组件。这些基础组件可被OpenHarmony各业务子系统及上层应用所使用。
11
12公共基础库在不同平台上提供的能力：
13
14- LiteOS-M内核\(Hi3861平台\)：KV\(key value\)存储、文件操作、定时器、Dump系统属性。
15- LiteOS-A内核\(Hi3516、Hi3518平台\)：KV\(key value\)存储、定时器、JS API\(设备查询，数据存储\)、Dump系统属性。
16
17**表 1** 公共基础库功能
18
19<a name="zh-cn_topic_0000001052623010_table206292206282"></a>
20<table><thead align="left"><tr id="zh-cn_topic_0000001052623010_row8629020112819"><th class="cellrowborder" valign="top" width="21.22%" id="mcps1.2.4.1.1"><p id="zh-cn_topic_0000001052623010_p66291220192816"><a name="zh-cn_topic_0000001052623010_p66291220192816"></a><a name="zh-cn_topic_0000001052623010_p66291220192816"></a>模块</p>
21</th>
22<th class="cellrowborder" valign="top" width="24.77%" id="mcps1.2.4.1.2"><p id="zh-cn_topic_0000001052623010_p3629122014289"><a name="zh-cn_topic_0000001052623010_p3629122014289"></a><a name="zh-cn_topic_0000001052623010_p3629122014289"></a>平台支持</p>
23</th>
24<th class="cellrowborder" valign="top" width="54.010000000000005%" id="mcps1.2.4.1.3"><p id="zh-cn_topic_0000001052623010_p206298206288"><a name="zh-cn_topic_0000001052623010_p206298206288"></a><a name="zh-cn_topic_0000001052623010_p206298206288"></a>说明</p>
25</th>
26</tr>
27</thead>
28<tbody><tr id="zh-cn_topic_0000001052623010_row1162992082812"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000001052623010_p136291920192814"><a name="zh-cn_topic_0000001052623010_p136291920192814"></a><a name="zh-cn_topic_0000001052623010_p136291920192814"></a>KV存储</p>
29</td>
30<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001052623010_p5629112019284"><a name="zh-cn_topic_0000001052623010_p5629112019284"></a><a name="zh-cn_topic_0000001052623010_p5629112019284"></a>LiteOS-M内核、LiteOS-A内核</p>
31</td>
32<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001052623010_p3630112072811"><a name="zh-cn_topic_0000001052623010_p3630112072811"></a><a name="zh-cn_topic_0000001052623010_p3630112072811"></a>为应用程序提供KV存储机制。</p>
33</td>
34</tr>
35<tr id="zh-cn_topic_0000001052623010_row116301920152816"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000001052623010_p96300207286"><a name="zh-cn_topic_0000001052623010_p96300207286"></a><a name="zh-cn_topic_0000001052623010_p96300207286"></a>文件操作</p>
36</td>
37<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001052623010_p1463032012281"><a name="zh-cn_topic_0000001052623010_p1463032012281"></a><a name="zh-cn_topic_0000001052623010_p1463032012281"></a>LiteOS-M内核</p>
38</td>
39<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001052623010_p163042052810"><a name="zh-cn_topic_0000001052623010_p163042052810"></a><a name="zh-cn_topic_0000001052623010_p163042052810"></a>提供统一的文件操作接口，屏蔽对底层不同芯片组件的差异。</p>
40</td>
41</tr>
42<tr id="zh-cn_topic_0000001052623010_row1163022022812"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000001052623010_p66308202284"><a name="zh-cn_topic_0000001052623010_p66308202284"></a><a name="zh-cn_topic_0000001052623010_p66308202284"></a>定时器</p>
43</td>
44<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001052623010_p26301620192820"><a name="zh-cn_topic_0000001052623010_p26301620192820"></a><a name="zh-cn_topic_0000001052623010_p26301620192820"></a>LiteOS-M内核、LiteOS-A内核</p>
45</td>
46<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001052623010_p2630172062815"><a name="zh-cn_topic_0000001052623010_p2630172062815"></a><a name="zh-cn_topic_0000001052623010_p2630172062815"></a>提供统一的定时器操作接口，屏蔽对底层不同芯片组件的差异。</p>
47</td>
48</tr>
49<tr id="zh-cn_topic_0000001052623010_row363012202282"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000001052623010_p4502105418285"><a name="zh-cn_topic_0000001052623010_p4502105418285"></a><a name="zh-cn_topic_0000001052623010_p4502105418285"></a>JS API</p>
50</td>
51<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001052623010_p199870135293"><a name="zh-cn_topic_0000001052623010_p199870135293"></a><a name="zh-cn_topic_0000001052623010_p199870135293"></a>LiteOS-A内核</p>
52</td>
53<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001052623010_p1550005422814"><a name="zh-cn_topic_0000001052623010_p1550005422814"></a><a name="zh-cn_topic_0000001052623010_p1550005422814"></a>提供获取设备信息，数据存储的JS API。</p>
54</td>
55</tr>
56<tr id="zh-cn_topic_0000001052623010_row5553145162815"><td class="cellrowborder" valign="top" width="21.22%" headers="mcps1.2.4.1.1 "><p id="zh-cn_topic_0000001052623010_p106300200288"><a name="zh-cn_topic_0000001052623010_p106300200288"></a><a name="zh-cn_topic_0000001052623010_p106300200288"></a>Dump系统属性</p>
57</td>
58<td class="cellrowborder" valign="top" width="24.77%" headers="mcps1.2.4.1.2 "><p id="zh-cn_topic_0000001052623010_p16300204280"><a name="zh-cn_topic_0000001052623010_p16300204280"></a><a name="zh-cn_topic_0000001052623010_p16300204280"></a>LiteOS-M内核、LiteOS-A内核</p>
59</td>
60<td class="cellrowborder" valign="top" width="54.010000000000005%" headers="mcps1.2.4.1.3 "><p id="zh-cn_topic_0000001052623010_p1563018208286"><a name="zh-cn_topic_0000001052623010_p1563018208286"></a><a name="zh-cn_topic_0000001052623010_p1563018208286"></a>提供dump系统属性的命令行工具。</p>
61</td>
62</tr>
63</tbody>
64</table>
65
66## 目录<a name="section1464106163817"></a>
67
68```
69utils/native/lite/ # 公共基础库根目录
70├── file # 文件接口实现
71├── hals # HAL目录
72│ └── file # 文件操作硬件抽象层头文件
73├── include # 公共基础库对外接口文件
74├── js # JS API目录
75│ └── builtin
76│ ├── common
77│ ├── deviceinfokit # 设备信息Kit
78│ ├── filekit # 文件Kit
79│ └── kvstorekit # KV存储Kit
80├── kal # KAL目录
81│ └── timer # Timer的KAL实现
82├── kv_store # KV存储实现
83│ ├── innerkits # KV存储内部接口
84│ └── src # KV存储源文件
85├── memory
86│ └── include # 内存池管理接口
87├── os_dump # Dump系统属性
88└── timer_task # Timer实现
89```
90
91## 使用<a name="section25021123178"></a>
92
93- **KV存储**
94
95 ```
96 // 存储/更新key对应数据项
97 const char key1[] = "key_sample";
98 const char defValue[] = "test case of key value store.";
99 int ret = UtilsSetValue(key1, defValue);
100
101 // 根据key获取对应数据项
102 char value1[32] = {0};
103 ret = UtilsGetValue(key1, value1, 32);
104
105 // 删除key对应数据项
106 UtilsDeleteValue(key1);
107 ```
108
109- **文件操作**
110
111 ```
112 // 打开或创建文件
113 const char fileName[] = "testfile";
114 int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0);
115
116 // 向文件写入特定大小的数据
117 const char defValue[] = "test case of file system.";
118 int ret = UtilsFileWrite(fd, defValue, strlen(defValue));
119
120 // 关闭文件
121 UtilsFileClose(fd);
122
123 // 获取文件大小
124 int fileLen = 0;
125 ret = UtilsFileStat(fileName, &fileLen);
126 printf("file size = %d\n", fileLen);
127
128 // 重新定位文件读/写偏移量
129 int fd1 = UtilsFileOpen(fileName, O_RDWR_FS, 0);
130 ret = UtilsFileSeek(fd1, 5, SEEK_SET_FS);
131
132 // 读取特定长度的文件数据
133 char buf[32] = {0};
134 int readLen = UtilsFileRead(fd1, buf, 32);
135 ret = UtilsFileClose(fd1);
136 printf("read len = %d : buf = %s\n", readLen, buf);
137
138 // 删除指定文件
139 ret = UtilsFileDelete(fileName);
140 ```
141
142
143- **dump系统属性**
144
145 LiteOS-M内核：在串口执行如下命令，即可打印当前系统参数
146
147 ```
148 AT+SYSPARA
149 ```
150
151 LiteOS-A内核：在bin路径下执行os\_dump，即可打印当前系统参数
152
153 ```
154 ./bin/os_dump syspara
155 ```
156
157
158## 涉及仓<a name="section4571352889"></a>
159
160[公共基础](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E5%85%AC%E5%85%B1%E5%9F%BA%E7%A1%80.md)
161
162utils\_native\_lite
163
164