1# Parameter Management 2 3## Overview 4 5### Function 6 7The parameter management subsystem, namely, sysparam, provides easy-to-use key-value pair access interfaces for system services to customize functions based on their own system parameters. 8 9### Basic Concepts 10 11#### Operation Primitives 12 13Figure 1 shows the primitives used to operate system parameters. For details about how they work, see Table 1. 14 15Figure 1 Overview of system parameter operation primitives 16 17 18 19**Table 1** Description of system parameter operation primitives 20 21| Operation Primitive | Description | 22| -------- | -------- | 23| get | Obtains the value of a system parameter. | 24| set | Sets the value of a system parameter. | 25| wait | Waits for value change of a system parameter synchronously.| 26| watch | Watches for the value change of a system parameter asynchronously.| 27 28#### Parameter Definition 29 30- Naming format 31 32 A system parameter name consists of multiple segments in dotted notation. Each segment can be a string that consists of letters, digits, and underscores (_). The total length cannot exceed 96 bytes. 33 34 Two naming formats are supported for system parameters, as described in Table 2. 35 36 **Table 2** Description of system parameter naming formats 37 38 | Type | Example | Description | 39 | -------- | -------- | -------- | 40 | Parameter name | const.product.**name** | Complete system parameter name. It does not end with a period (.). | 41 | Parameter directory | const.product **.** | Name of the directory storing system parameters with the same prefix. It ends with a period (.).| 42 43- Type 44 45 System parameters are categorized into three types, as described in Table 3. 46 47 **Table 3** Description of system parameter types 48 49 | Type| Prefix| Description| 50 | -------- | -------- | -------- | 51 | Constant| const. | Constant parameter, which will not change once a value is assigned. The value can contain a maximum of 4,096 bytes (including the end-of-text character).| 52 | Writable| Others| Writable parameter, which will be discarded after a system restart. The value can contain a maximum of 96 bytes (including the end-of-text character).| 53 | Persistent| persist. | Writable and persistent parameter, which will not be discarded after a system restart. The value can contain a maximum of 96 bytes (including the end-of-text character).| 54 55 Given below is the general naming format for system parameters: 56 ``` 57 [ const | persist ].$sub_system.$desc 58 ``` 59 wherein, 60 61 - **$sub_system** is the subsystem or module name. 62 63 - **$desc** is the parameter description, which can contain multiple segments in dotted notation. 64 65#### Parameter Definition Rule 66 67System parameters are defined per module on each subsystem. The parameter definition includes the system parameter name, default value, and access permission information. 68 69- Value definition file 70 71 - A value definition file of system parameters ends with the **.para** extension. The following is an example format of file content: 72 73 ```shell 74 # This is comment 75 const.product.name=OHOS-PRODUCT 76 const.os.version.api=26 77 const.telephony.enable=false|true 78 79 const.test.withblank=My Value 80 const.test.withcomment=MyValue # This should be omitted 81 const.test.multiline="This is a multiline parameter. 82 Line2 value. 83 Last line." 84 ``` 85 86 - A complete system parameter command is required to assign a value for a system parameter. See Table 4 for the value assignment modes. 87 88 **Table 4** Description of value assignment modes 89 90 | Type| Example| Description| 91 | -------- | -------- | -------- | 92 | String | const.product.name=OHOS-PRODUCT | A string that spans multiple lines must be enclosed in double quotation marks ("").| 93 | Number | const.os.version.api=26 | A number that spans multiple lines does not need to be enclosed in double quotation marks ("").| 94 | Boolean | const.telephony.enable=false | A Boolean value can be **0**, **1**, **false**, or **true**.| 95 96- DAC definition file 97 98 Access permissions of system parameters are managed in discretionary access control (DAC) mode. A DAC definition file ends with the **.para.dac** extension. The following is an example format of DAC information: 99 100 ```java 101 const.product.="root:root:660" 102 ``` 103 104 As shown in this example, a **parameter directory** can be used to define the same access permission for system parameters with the same prefix. A piece of DAC information is divided into three segments, user, group, and Ugo rule, which are separated using a semicolon (:). 105 106 > **NOTE** 107 > 108 > Ugo is the abbreviation for user access, group access, ad other system user's access, respectively. These permissions are set to allow or deny access to members of their own group, or any other groups. 109 110 Figure 2 shows the Ugo rule structure. 111 112 **Figure 2** Overview of the Ugo rule structure 113 114  115 116- SELinux policy 117 118 An SELinux policy defines the access permissions for all users, programs, processes, and files. 119 120 - Adding an SELinux tag 121 122 To add an SELinux tag to system parameters, you first need to define the tag in the **/base/security/selinux/sepolicy/base/public/parameter.te** file. For example: 123 124 ```java 125 type servicectrl_param, parameter_attr 126 ``` 127 128 After the tag is defined, add the system parameter prefix associated with the tag to **/base/security/selinux/sepolicy/base/public/parameter_contexts**. The following uses the prefix **ohos.servicectrl** as an example: 129 130 ```java 131 ohos.servicectrl. u:object_r:servicectrl_param:s0 132 ``` 133 134 - Granting access permissions for a process 135 136 For example, to grant access permissions such as map for the init process, add the following code to the **/base/security/selinux/sepolicy/ohos_policy/startup/init/public/init.te** file: 137 138 ```java 139 allow servicectrl_param tmpfs:filesystem associate; 140 allow init servicectrl_param:file { map open read relabelto relabelfrom }; 141 ``` 142 143 - Granting the write permission 144 145 For example, to grant the write permission for services such as **init**, **samgr**, and **hdf_devmgr**, use the following code: 146 147 ```java 148 allow { init samgr hdf_devmgr } servicectrl_param:parameter_service { set }; 149 ``` 150 151 - Granting the read permission 152 153 If you want to grant the read permission only for certain services, replace **xxx** with these services in the following code: 154 155 ```java 156 allow { xxx } servicectrl_param:file { map open read }; 157 ``` 158 159 - Granting access permissions for all services 160 161 If you want to grant access permissions for all services, use the following code: 162 163 ```java 164 allow { domain -limit_domain } servicectrl_param:file { map open read }; 165 ``` 166 167- System parameter tag 168 169 You are advised to keep only two system parameter tags for each subsystem: 170 171 - A private tag to control system parameter settings. 172 173 - A public tag to grant access permissions from all services. 174 175- Loading sequence 176 177 System parameters are loaded by priority in the specified sequence, as described in Table 5. 178 179 **Table 5** Description of the system parameter loading sequence 180 181 | Type| Path| Description| 182 | -------- | -------- | -------- | 183 | Kernel parameters | /proc/cmdline | Convert some values of kernel parameters into system parameters. Specifically, convert all **ohospara.xxx=valXXX** parameters to **ohos.boot.xxx=valXXX** parameters.| 184 | OS system parameters| /system/etc/param/ohos_const/*.para | Load the definition file containing OS constants preferentially. | 185 | Vendor parameters| /vendor/etc/param/*.para | Load the system parameters defined by vendors with the secondary priority. | 186 | System parameters| /system/etc/param/*.para | Load the system parameters defined by each subsystem. A system parameter will be ignored if it already exists.| 187 | Persistent parameters| /data/parameters/ | Load persistent parameters, if any, at last. Persistent parameters will overwrite the default system parameters that have been loaded.| 188 189 190#### Tag File Size 191 192If one tag is associated with more than five system parameters, you need to set the size of the system parameter tag file in **/base/startup/init/services/etc/param/ohos.para.size**. The default value is **512**. 193 194The configuration rule is as follows: 195 196System parameter tag = Size 197 198For example: 199 200```java 201startup_init_param=40960 202``` 203 204 205### Constraints 206 207The parameter management subsystem is available only for the mini system and standard system. 208 209## How to Develop 210 211### Application Scenario 212 213You can set specific system parameters as needed to meet your service demand. 214 215### Implementation Method 216 217The parameter management subsystem allows you to manage system parameters by running shell commands or calling **syspara** APIs. 218 219 - Shell command mode 220 221 You can operate system parameters directly by running shell commands. This operation mode is available only for the standard system. Table 6 is a list of the shell commands. 222 223 **Table 6** Description of shell commands 224 225 | Command| Description| 226 | -------- | -------- | 227 | param get [**key**] | Obtains the system parameter value of the specified key. If no key name is specified, all system parameter values will be returned.| 228 | param set **key value** | Sets the specified value for the specified key.| 229 | param wait **key** **value** | Waits for the system parameter value of the specified key to match the specified value. Fuzzy match is supported. For example, * indicates any value, and <strong>val</strong>* indicates matching of only the first three val characters.| 230 | param watch | Watches for the value change of a system parameter asynchronously.| 231 232 - syspara API mode 233 234 Besides shell commands, you can use **syspara** APIs to manage system parameters. The return result is a constant string and the **free** operation is not supported. Table 7 is a list of the **syspara** APIs. 235 236 **Table 7** Description of syspara APIs 237 238 | API| Description| 239 | -------- | -------- | 240 | int GetParameter(const char\* key, const char\* def, char\* value, unsigned int len) | Obtains system parameters.| 241 | int SetParameter(const char\* key, const char\* value) | Sets or updates system parameters.| 242 | const char\* GetDeviceType(void) | Obtains the device type.| 243 | const char\* GetManufacture(void) | Obtains the device's manufacturer name.| 244 | const char\* GetBrand(void) | Obtains the device's brand name.| 245 | const char\* GetMarketName(void) | Obtains the device's marketing name.| 246 | const char\* GetProductSeries(void) | Obtains the device's product series name.| 247 | const char\* GetProductModel(void) | Obtains the device's product model.| 248 | const char\* GetSoftwareModel(void) | Obtains the device's software model.| 249 | const char\* GetHardwareModel(void) | Obtains the device's hardware model.| 250 | const char\* GetHardwareProfile(void) | Obtains the device's hardware profile.| 251 | const char\* GetSerial(void) | Obtains the device's serial number (SN).| 252 | const char\* GetOSFullName(void) | Obtains the device's OS name.| 253 | const char\* GetDisplayVersion(void) | Obtains the device's displayed software version.| 254 | const char\* GetBootloaderVersion(void) | Obtains the device's bootloader version.| 255 | const char\* GetSecurityPatchTag(void) | Obtains the device's security patch tag.| 256 | const char\* GetAbiList(void) | Obtains the list of supported application binary interfaces (ABIs).| 257 | int GetSdkApiVersion(void) | Obtains the SDK API version that matches the current system software.| 258 | int GetFirstApiVersion(void) | Obtains the first SDK API version of the system software.| 259 | const char\* GetIncrementalVersion(void) | Obtains the incremental version of the system software.| 260 | const char\* GetVersionId(void) | Obtains the version ID.| 261 | const char\* GetBuildType(void) | Obtains the build type.| 262 | const char\* GetBuildUser(void) | Obtains the build user.| 263 | const char\* GetBuildHost(void) | Obtains the build host.| 264 | const char\* GetBuildTime(void) | Obtains the build time.| 265 | const char\* GetBuildRootHash(void) | Obtains the buildroot hash value of the current version.| 266 | const char\* GetOsReleaseType(void) | Obtains the system release type.| 267 | int GetDevUdid(char \*udid, int size) | Obtains the device's unique device ID (UDID).| 268 | const char *AclGetSerial(void); | Obtains the device's SN with ACL check.| 269 | int AclGetDevUdid(char *udid, int size); | Obtains the device's UDID with ACL check.| 270 271### Development Procedure 272 273#### Parameter Definition 274 275You can define default system parameters and implement permission control on them by configuring the <strong>.para</strong> and <strong>.para.dac</strong> files of the respective subsystem or product. 276 277- On a standard system, use the <strong>ohos_prebuilt_para</strong> template to install the configuration file to the <strong>/etc/param/</strong> directory. The following is an example of the GN script: 278 279 ```go 280 import("//base/startup/init/services/etc/param/param_fixer.gni") 281 282 ohos_prebuilt_para("ohos.para") { 283 source = "//base/startup/init/services/etc/ohos.para" 284 part_name = "init" 285 module_install_dir = "etc/param" 286 } 287 288 ohos_prebuilt_para("ohos.para.dac") { 289 source = "//base/startup/init/services/etc/ohos.para.dac" 290 part_name = "init" 291 module_install_dir = "etc/param" 292 } 293 ``` 294 295- On a small system, run the <strong>copy</strong> command to copy the corresponding system parameter definition file to the <strong>system/etc/param</strong> directory. 296 ```go 297 copy("ohos.para") { 298 sources = [ "//base/startup/init/services/etc/param/ohos.para" ] 299 outputs = [ "$root_out_dir/system/etc/param/ohos.para" ] 300 } 301 copy("ohos.para.dac") { 302 sources = [ "//base/startup/init/services/etc/param/ohos.para.dac" ] 303 outputs = [ "$root_out_dir/system/etc/param/ohos.para.dac" ] 304 } 305 ``` 306- On a mini system, convert all defined default system parameters into header files through **action** and compile them into the system. 307 ```go 308 action("lite_const_param_to") { 309 script = "//base/startup/init/scripts/param_cfg_to_code.py" 310 args = [ 311 "--source", 312 rebase_path( 313 "//base/startup/init/services/etc_lite/param/ohos_const/ohospara"), 314 "--dest_dir", 315 rebase_path("$root_out_dir/gen/init/"), 316 "--priority", 317 "0", 318 ] 319 outputs = [ "$target_gen_dir/${target_name}_param_cfg_to_code.log" ] 320 } 321 ``` 322#### Development Example 323 ``` 324 // set && get 325 char key1[] = "rw.sys.version"; 326 char value1[] = "10.1.0"; 327 int ret = SetParameter(key1, value1); 328 char valueGet1[128] = {0}; 329 ret = GetParameter(key1, "version=10.1.0", valueGet1, 128); 330 331 // get sysparm 332 char* value1 = GetDeviceType(); 333 printf("Product type =%s\n", value1); 334 335 char* value2 = GetManufacture(); 336 printf("Manufacture =%s\n", value2); 337 338 char* value3 = GetBrand(); 339 printf("GetBrand =%s\n", value3); 340 341 char* value4 = GetMarketName(); 342 printf("MarketName =%s\n", value4); 343 344 char* value5 = GetProductSeries(); 345 printf("ProductSeries =%s\n", value5); 346 347 char* value6 = GetProductModel(); 348 printf("ProductModel =%s\n", value6); 349 350 char* value7 = GetSoftwareModel(); 351 printf("SoftwareModel =%s\n", value7); 352 353 char* value8 = GetHardwareModel(); 354 printf("HardwareModel =%s\n", value8); 355 356 char* value9 = GetHardwareProfile(); 357 printf("Software profile =%s\n", value9); 358 359 char* value10 = GetSerial(); 360 printf("Serial =%s\n", value10); 361 362 char* value11 = GetOSFullName(); 363 printf("OS name =%s\n", value11); 364 365 char* value12 = GetDisplayVersion(); 366 printf("Display version =%s\n", value12); 367 368 char* value13 = GetBootloaderVersion(); 369 printf("bootloader version =%s\n", value13); 370 371 char* value14 = GetSecurityPatchTag(); 372 printf("secure patch level =%s\n", value14); 373 374 char* value15 = GetAbiList(); 375 printf("abi list =%s\n", value15); 376 377 int value16 = GetFirstApiVersion(); 378 printf("first api level =%d\n", value16); 379 380 char* value17 = GetIncrementalVersion(); 381 printf("Incremental version = %s\n", value17); 382 383 char* value18 = GetVersionId(); 384 printf("formal id =%s\n", value18); 385 386 char* value19 = GetBuildType(); 387 printf("build type =%s\n", value19); 388 389 char* value20 = GetBuildUser(); 390 printf("build user =%s\n", value20); 391 392 char* value21 = GetBuildHost(); 393 printf("Build host = %s\n", value21); 394 395 char* value22 = GetBuildTime(); 396 printf("build time =%s\n", value22); 397 398 char* value23 = GetBuildRootHash(); 399 printf("build root later..., %s\n", value23); 400 401 char* value24 = GetOsReleaseType(); 402 printf("OS release type =%s\n", value24); 403 404 char* value25 = GetOsReleaseType(); 405 printf("OS release type =%s\n", value25); 406 407 char value26[65] = {0}; 408 GetDevUdid(value26, 65); 409 printf("device udid =%s\n", value26); 410 ``` 411
