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