# Parameter Management
## Overview
### Function

The 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.

### Basic Concepts

Figure 1 System parameter operation primitives

![System parameter operation primitives](figure/system-parameter-operation-primitives.png)

**Table 1** Description of system parameter operation primitives
| Operation Primitive| Description|
| -------- | -------- |
| get      | Obtains the value of a system parameter.       |
| set      | Sets the value of a system parameter.       |
| wait     | Waits for value change of a system parameter synchronously.|
| watch    | Observes value change of a system parameter asynchronously.|

#### System Parameter Definition

- Naming format

  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.

  **Table 2** System parameter names

  | Type| Example| Description|
  | -------- | -------- | -------- |
  | Parameter name | const.product.**name** | Complete system parameter name. It does not end with a period (.).          |
  | Parameter directory | const.product **.**     | Name of the directory storing system parameters with the same prefix. It ends with a period (.).|

- Type

  System parameters are categorized into three types.

  **Table 3** System parameter types

  | Type| Prefix| Description|
  | -------- | -------- | -------- |
  | 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).|
  | Writable| Others| Writable parameter, which will be lost after system restart. The value can contain a maximum of 96 bytes (including the terminator).|
  | 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).|

  The general naming format is as follows:
  ```
  [ const | persist ].$sub_system.$desc
  ```
  **$sub_system** is the name of the subsystem or module.

  **$desc** indicates the description of a system parameter. The description can contain multiple segments in dotted notation.

#### Definition Rules

Each subsystem defines the system parameters of its own modules, including the system parameter name, default value, and access permission information.

- System parameter value definition file

  - The system parameter value definition file ends with the **.para** extension. An example of the file format is as follows:

    ```shell
    # This is comment
    const.product.name=OHOS-PRODUCT
    const.os.version.api=26
    const.telephony.enable=false|true

    const.test.withblank=My Value
    const.test.withcomment=MyValue # This should be ommitted
    const.test.multiline="This is a multiline parameter.
    Line2 value.
    Last line."
    ```

  - You must use a complete system parameter command when assigning a value for a system parameter. The following table describes the value assignment modes.

    **Table 4** Value assignment modes

    | Type| Example| Description|
    | -------- | -------- | -------- |
    | String  | const.product.name=OHOS-PRODUCT | A multi-line string must be enclosed in double quotation marks ("").|
    | Number    | const.os.version.api=26         | Numbers do not need to be enclosed in quotation marks.|
    | Boolean    | const.telephony.enable=false    | A Boolean value can be **0**, **1**, **false**, or **true**.|

- DAC definition file

  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:

  ```java
  const.product.="root:root:660"
  ```

  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 information, which are separated using a semicolon (:).

  The following figure shows the structure of the UGO rule information.

  **Figure 2** UGO rule information

  ![UGO rule](figure/dac-definition.png)

-  Loading sequence

    The following table provides the sequence of loading system parameters.

    **Table 5** System parameter loading sequence
    | Type| Path| Description|
    | -------- | -------- | -------- |
    | 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.|
    | OS system parameters| /system/etc/param/ohos_const/*.para | Load the definition file containing OS constants preferentially.                              |
    | Vendor parameters| /vendor/etc/param/*.para | Load the system parameters defined by vendors with the secondary priority.                            |
    | System parameters| /system/etc/param/*.para | Load the parameters defined by each subsystem. If a system parameter already exists, ignore it.|
    | Persistent parameters| /data/parameters/ | If persistent parameters exist, load them at last. Persistent parameters will overwrite the default system parameters that have been loaded.|

### Constraints

The service management module is available only for the mini system and standard system.

## How to Develop

### Use Cases
You can set specific system parameters as needed to meet your service demand.

### Available APIs

  - Shell commands

    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.

    **Table 6** Description of shell commands

    | Command| Description|
    | -------- | -------- |
    | 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.|
    | param set **key value** | Sets the specified value for the specified key.|
    | 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 **val*** indicates matching of only the first three val characters.|
    | param watch | Observes value change of a system parameter asynchronously.|

  - syspara APIs

    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.

    **Table 7** Description of syspara APIs
    | API| Description|
    | -------- | -------- |
    | int GetParameter(const char\* key, const char\* def, char\* value, unsigned int len) | Obtains system parameters.|
    | int SetParameter(const char\* key, const char\* value) | Sets or updates system parameters.|
    | const char\* GetDeviceType(void) | Obtains the device type.|
    | const char\* GetManufacture(void) | Obtains the device manufacturer.|
    | const char\* GetBrand(void) | Obtains the device brand.|
    | const char\* GetMarketName(void) | Obtains the device marketing name.|
    | const char\* GetProductSeries(void) | Obtains the device series name.|
    | const char\* GetProductModel(void) | Obtains the device authentication model.|
    | const char\* GetSoftwareModel(void) | Obtains the device software model.|
    | const char\* GetHardwareModel(void) | Obtains the device hardware model.|
    | const char\* GetHardwareProfile(void) | Obtains the device hardware profile.|
    | const char\* GetSerial(void) | Obtains the device serial number (SN).|
    | const char\* GetOSFullName(void) | Obtains the operating system name.|
    | const char\* GetDisplayVersion(void) | Obtains the software version visible to users.|
    | const char\* GetBootloaderVersion(void) | Obtains the bootloader version of this device.|
    | const char\* GetSecurityPatchTag(void) | Obtains the security patch tag.|
    | const char\* GetAbiList(void) | Obtains the list of application binary interfaces (ABIs) supported on this device.|
    | int GetSdkApiVersion(void) | Obtains the SDK API level that matches the current system software.|
    | int GetFirstApiVersion(void) | Obtains the first SDK API level of the system software.|
    | const char\* GetIncrementalVersion(void) | Obtains the incremental version.|
    | const char\* GetVersionId(void) | Obtains the version ID.|
    | const char\* GetBuildType(void) | Obtains the build type.|
    | const char\* GetBuildUser(void) | Obtains the build account user name.|
    | const char\* GetBuildHost(void) | Obtains the build host name.|
    | const char\* GetBuildTime(void) | Obtains the build time.|
    | const char\* GetBuildRootHash(void) | Obtains the buildroot hash value of this version.|
    | const char\* GetOsReleaseType(void) | Obtains the system release type.|
    | int GetDevUdid(char \*udid, int size) | Obtains the device identifier (UDID).|
    | const char *AclGetSerial(void); | Obtains the device SN (with ACL check).|
    | int AclGetDevUdid(char *udid, int size); | Obtains the UDID (with ACL check).|

### How to Develop

1. System parameter definition

    You can define default system parameters and implement permission control on them by configuring the subsystem or product **.para** and **.para.dac** files. 

    ​    	On a standard system, use the **ohos_prebuilt_para** template to install the configuration file to the **/etc/param/** directory. The following is an example of the GN script:

    ```go
    import("//base/startup/init_lite/services/etc/param/param_fixer.gni")

    ohos_prebuilt_para("ohos.para") {
        source = "//base/startup/init_lite/services/etc/ohos.para"
        part_name = "init"
        module_install_dir = "etc/param"
    }

    ohos_prebuilt_para("ohos.para.dac") {
        source = "//base/startup/init_lite/services/etc/ohos.para.dac"
        part_name = "init"
        module_install_dir = "etc/param"
    }
    ```

    On a small system, run the **copy** command to copy the corresponding system parameter definition file to the **system/etc/param** directory.
    ```go
    copy("ohos.para") {
      sources = [ "//base/startup/init_lite/services/etc/param/ohos.para" ]
      outputs = [ "$root_out_dir/system/etc/param/ohos.para" ]
    }
    copy("ohos.para.dac") {
      sources = [ "//base/startup/init_lite/services/etc/param/ohos.para.dac" ]
      outputs = [ "$root_out_dir/system/etc/param/ohos.para.dac" ]
    }
    ```
    On a mini system, convert all defined default system parameters into header files through **action** and compile them into the system.
    ```go
    action("lite_const_param_to") {
      script = "//base/startup/init_lite/scripts/param_cfg_to_code.py"
      args = [
        "--source",
        rebase_path(
            "//base/startup/init_lite/services/etc_lite/param/ohos_const/ohospara"),
        "--dest_dir",
        rebase_path("$root_out_dir/gen/init_lite/"),
        "--priority",
        "0",
      ]
      outputs = [ "$target_gen_dir/${target_name}_param_cfg_to_code.log" ]
    }
    ```
2. Development example
    ```
    // set && get
    char key1[] = "rw.sys.version";
    char value1[] = "10.1.0";
    int ret = SetParameter(key1, value1);
    char valueGet1[128] = {0};
    ret = GetParameter(key1, "version=10.1.0", valueGet1, 128);

    // get sysparm
    char* value1 = GetDeviceType();
    printf("Product type =%s\n", value1);

    char* value2 = GetManufacture();
    printf("Manufacture =%s\n", value2);

    char* value3 = GetBrand();
    printf("GetBrand =%s\n", value3);

    char* value4 = GetMarketName();
    printf("MarketName =%s\n", value4);

    char* value5 = GetProductSeries();
    printf("ProductSeries =%s\n", value5);

    char* value6 = GetProductModel();
    printf("ProductModel =%s\n", value6);

    char* value7 = GetSoftwareModel();
    printf("SoftwareModel =%s\n", value7);

    char* value8 = GetHardwareModel();
    printf("HardwareModel =%s\n", value8);

    char* value9 = GetHardwareProfile();
    printf("Software profile =%s\n", value9);

    char* value10 = GetSerial();
    printf("Serial =%s\n", value10);

    char* value11 = GetOSFullName();
    printf("OS name =%s\n", value11);

    char* value12 = GetDisplayVersion();
    printf("Display version =%s\n", value12);

    char* value13 = GetBootloaderVersion();
    printf("bootloader version =%s\n", value13);

    char* value14 = GetSecurityPatchTag();
    printf("secure patch level =%s\n", value14);

    char* value15 = GetAbiList();
    printf("abi list =%s\n", value15);

    int value16 = GetFirstApiVersion();
    printf("first api level =%d\n", value16);

    char* value17 = GetIncrementalVersion();
    printf("Incremental version = %s\n", value17);

    char* value18 = GetVersionId();
    printf("formal id =%s\n", value18);

    char* value19 = GetBuildType();
    printf("build type =%s\n", value19);

    char* value20 = GetBuildUser();
    printf("build user =%s\n", value20);

    char* value21 = GetBuildHost();
    printf("Build host = %s\n", value21);

    char* value22 = GetBuildTime();
    printf("build time =%s\n", value22);

    char* value23 = GetBuildRootHash();
    printf("build root later..., %s\n", value23);

    char* value24 = GetOsReleaseType();
    printf("OS release type =%s\n", value24);

    char* value25 = GetOsReleaseType();
    printf("OS release type =%s\n", value25);

    char value26[65] = {0};
    GetDevUdid(value26, 65);
    printf("device udid =%s\n", value26);
    ```