## Introduction to EnterpriseAdminExtensionAbility
...
...
@@ -8,34 +8,35 @@ EnterpriseAdminExtensionAbility is a mandatory component for Mobile Device Manag
EnterpriseAdminExtensionAbility is applicable only to enterprise administrator applications.
## Observing Activation/Deactivation of a Device Administrator Application and Installation/Removal of an Application
## Observing Activation/Deactivation of a Device Administrator Application and Installation/Uninstallation of an Application
### Overview
**onAdminEnabled**: When an enterprise administrator or employee deploys an MDM application and activates the device administrator application, this callback is invoked to notify the MDM application that the DeviceAdmin permission is activated. The initialization policy of the MDM application can set in **onAdminEnabled**.
**onAdminEnabled**: called when an enterprise administrator or employee deploys an MDM application and enables the DeviceAdmin permission for the application. The MDM application can set the initialization policy in the **onAdminEnabled** callback.
**onAdminDisabled**: When the device administrator application is deactivated, the callback is invoked to notify the MDM application that the DeviceAdmin permission is deactivated.
**onAdminDisabled**: called when the system or employee disables the DeviceAdmin permission to notify the enterprise administrator that the device is no longer managed.
**onBundleAdded**: The enterprise administrator can subscribe to application installation and uninstallation events. When an application is installed on an enterprise device, the MDM application reports the event in this callback to notify the enterprise administrator.
**onBundleAdded**: The enterprise administrator can subscribe to application installation events. When an application is installed on an enterprise device, the MDM application reports the event in this callback to notify the enterprise administrator.
**onBundleRemoved**: When an application is removed from an enterprise device, the MDM application reports the event in this callback to notify the enterprise administrator.
**onBundleRemoved**: The enterprise administrator can subscribe to application uninstallation events. When an application is uninstalled on an enterprise device, the MDM application reports the event in this callback to notify the enterprise administrator.
| EnterpriseAdminExtensionAbility | onAdminEnabled(): void | Called when a device administrator application is activated. |
| EnterpriseAdminExtensionAbility | onAdminDisabled(): void | Called when a device administrator application is deactivated.|
| EnterpriseAdminExtensionAbility | onBundleAdded(bundleName: string): void | Called when an application is installed on a device. |
| EnterpriseAdminExtensionAbility | onBundleRemoved(bundleName: string): void | Called when an application is removed from a device. |
| EnterpriseAdminExtensionAbility | onAdminEnabled(): void | Called when the device administrator application is disabled. |
| EnterpriseAdminExtensionAbility | onAdminDisabled(): void | Called when the device administrator application is enabled.|
| EnterpriseAdminExtensionAbility | onBundleAdded(bundleName: string): void | Called when the MDM application is installed. |
| EnterpriseAdminExtensionAbility | onBundleRemoved(bundleName: string): void | Called when the MDM application is uninstalled. |
### How to Develop
To implement EnterpriseAdminExtensionAbility, you need to activate the device administrator application and create **ExtensionAbility** in the code directory of the device administrator application. The procedure is as follows:
1. In the **ets** directory of the target module, right-click and choose **New > Directory** to create a directory named **EnterpriseExtAbility**.
2. Right-click the **EnterpriseExtAbility** directory, and choose **New > TypeScript File** to create a file named **EnterpriseExtAbility.ts**.
3. Open the **EnterpriseExtAbility.ts** file and import the **EnterpriseAdminExtensionAbility** module. Inherit the **EnterpriseAdminExtensionAbility** module to the custom class and add application notification callbacks, such as **onAdminEnabled()** and **onAdminDisabled()**. When the device administrator application is activated or deactivated, the device administrator can receive notifications.
2. Right-click the **EnterpriseExtAbility** directory and choose **New > TypeScript File** to create a file named **EnterpriseExtAbility.ts**.
3. Open the **EnterpriseExtAbility.ts** file and import the **EnterpriseAdminExtensionAbility** module. Customize a class that inherits from **EnterpriseAdminExtensionAbility** and add the required callbacks, such as **onAdminEnabled()** and **onAdminDisabled()**, When the device administrator application is activated or deactivated, the device administrator can receive notifications.
The Hardware Driver Foundation (HDF) is designed based on a modular driver model to enable refined driver management and streamline driver development and deployment. The HDF allows the same type of device drivers to be placed in a host. The host manages the start and loading of a group of devices. You can deploy dependent drivers to the same host, and deploy independent drivers to different hosts.
The figure below shows the HDF driver model. A device refers to a physical device. A DeviceNode is a component of a device. A device has at least one DeviceNode. Each DeviceNode can publish a device service. Each DevicdNode has a unique driver to interact with the hardware.
**Figure 1** HDF driver model
## How to Develop
The HDF-based driver development involves driver implementation, write of the driver compilation script, and driver configuration. The procedure is as follows:
1. Implement a driver.
Write the driver code and register the driver entry with the HDF.
- Write the driver service code. <br>The following is an example:
```c
#include "hdf_device_desc.h" // Header file that defines the driver development APIs provided by the HDF.
#include "hdf_log.h" // Header file that defines the log APIs provided by the HDF.
#define HDF_LOG_TAG "sample_driver" // Tag contained in logs. If no tag is not specified, the default HDF_TAG is used.
// Bind the service APIs provided by the driver to the HDF.
// Define a driver entry object. It must be a global variable of the HdfDriverEntry type (defined in hdf_device_desc.h).
structHdfDriverEntryg_sampleDriverEntry={
.moduleVersion=1,
.moduleName="sample_driver",
.Bind=HdfSampleDriverBind,
.Init=HdfSampleDriverInit,
.Release=HdfSampleDriverRelease,
};
// Call HDF_INIT to register the driver entry with the HDF. When loading the driver, the HDF calls Bind() and then Init(). If Init() fails to be called, the HDF will call Release() to release driver resources and exit the driver model.
HDF_INIT(g_sampleDriverEntry);
```
2. Write the driver compilation script.
- LiteOS
Modify **makefile** and **BUILD.gn** files.
- **Makefile**:
Use the **makefile** template provided by the HDF to compile the driver code.
```c
include $(LITEOSTOPDIR)/../../drivers/hdf_core/adapter/khdf/liteos/lite.mk # (Mandatory) Import the HDF predefined content.
MODULE_NAME := # File to be generated.
LOCAL_INCLUDE: = # Directory of the driver header files.
LOCAL_SRCS : = # Source code files of the driver.
LOCAL_CFLAGS : = # Custom build options.
include $(HDF_DRIVER) # Import the makefile template to complete the build.
```
Add the path of the generated file to **hdf_lite.mk** in the **drivers/hdf_core/adapter/khdf/liteos** directory to link the file to the kernel image. <br>The following is an example:
```c
LITEOS_BASELIB += -lxxx # Static library generated by the link.
LIB_SUBDIRS += # Directory in which makefile is located.
```
- **BUILD.gn**:
Add **BUILD.gn**. The content of **BUILD.gn** is as follows:
public_configs = [ ":public" ] # Head file configuration of the dependencies.
}
config("public") { # Define the head file configuration of the dependencies.
include_dirs = [
"xxx/xxx/xxx", # Directory of dependency header files.
]
}
```
Add the **BUILD.gn** directory to **/drivers/hdf_core/adapter/khdf/liteos/BUILD.gn**.
```c
group("liteos") {
public_deps = [ ":$module_name" ]
deps = [
"xxx/xxx", # Directory where the BUILD.gn of the driver is located. It is a relative path to /drivers/hdf_core/adapter/khdf/liteos.
]
}
```
- Linux
To define the driver control macro, add the **Kconfig** file to the driver directory **xxx** and add the path of the **Kconfig** file to **drivers/hdf_core/adapter/khdf/linux/Kconfig**.
```c
source "drivers/hdf/khdf/xxx/Kconfig" # Kernel directory to which the HDF module is soft linked.
```
Add the driver directory to **drivers/hdf_core/adapter/khdf/linux/Makefile**.
```c
obj-$(CONFIG_DRIVERS_HDF) += xxx/
```
Add a **Makefile** to the driver directory **xxx** and add code compiling rules of the driver to the **Makefile** file.
```c
obj-y += xxx.o
```
3. Configure the driver.
The HDF Configuration Source (HCS) contains the source code of HDF configuration. For details about the HCS, see [Configuration Management](../driver/driver-hdf-manage.md).
The driver configuration consists of the driver device description defined by the HDF and the private driver configuration.
- (Mandatory) Set driver device information.
The HDF loads a driver based on the driver device description defined by the HDF. Therefore, the driver device description must be added to the **device_info.hcs** file defined by the HDF. <br>The following is an example:
```
root {
device_info {
match_attr = "hdf_manager";
template host { // Host template. If a node (for example, sample_host) uses the default values in this template, the node fields can be omitted.
hostName = "";
priority = 100;
uid = ""; // User ID (UID) of the user-mode process. It is left empty by default. If you do not set the value, this parameter will be set to the value of hostName, which indicates a common user.
gid = ""; // Group ID (GID) of the user-mode process. It is left empty by default. If you do not set the value, this parameter will be set to the value of hostName, which indicates a common user group.
caps = [""]]; // Linux capabilities of the user-mode process. It is left empty by default. Set this parameter based on service requirements.
template device {
template deviceNode {
policy = 0;
priority = 100;
preload = 0;
permission = 0664;
moduleName = "";
serviceName = "";
deviceMatchAttr = "";
}
}
}
sample_host :: host{
hostName = "host0"; // Host name. The host node is used as a container to hold a type of drivers.
priority = 100; // Host startup priority (0-200). A smaller value indicates a higher priority. The default value 100 is recommended. The hosts with the same priority start based on the time when the priority was configured. The host configured first starts first.
caps = ["DAC_OVERRIDE", "DAC_READ_SEARCH"]; // Linux capabilities of a user-mode process.
device_sample :: device { // Sample device node.
device0 :: deviceNode { // DeviceNode of the sample driver.
policy = 1; // Policy for publishing the driver service. For details, see Driver Service Management.
priority = 100; // Driver startup priority (0-200). A smaller value indicates a higher priority. The default value 100 is recommended. The drivers with the same priority start based on the time when the priority was configured. The driver configured first starts first.
preload = 0; // The value 0 means to load the driver by default during the startup of the system.
permission = 0664; // Permission for the DeviceNode created.
moduleName = "sample_driver"; // Driver name. The value must be the same as that of moduleName in the HdfDriverEntry structure.
serviceName = "sample_service"; // Name of the service published by the driver. The service name must be unique.
deviceMatchAttr = "sample_config"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver.
> - **uid**, **gid**, and **caps** are startup parameters for user-mode drivers only.
>
> - According to the principle of least privilege for processes, **uid** and **gid** do not need to be configured for service modules. In the preceding example, **uid** and **gid** are left empty (granted with the common user rights) for sample_host.
>
> - If you need to set **uid** and **gid** to **system** or **root** due to service requirements, contact security experts for review.
>
> - The process UIDs are configured in **base/startup/init/services/etc/passwd**, and the process GIDs are configured in **base/startup/init/services/etc/group**. For details, see [Adding a System Service User Group]( https://gitee.com/openharmony/startup_init_lite/wikis).
>
> - The **caps** value is in the caps = ["xxx"] format. To configure **CAP_DAC_OVERRIDE**, set this parameter to **caps = ["DAC_OVERRIDE"]**. Do not set it to **caps = ["CAP_DAC_OVERRIDE"]**.
>
> - **preload** specifies the driver loading policy. For details, see [Driver Loading](../driver/driver-hdf-load.md).
- (Optional) Set driver private information.
If the driver has private configuration, add a driver configuration file to set default driver configuration. When loading the driver, the HDF obtains and saves the driver private information in **property** of **HdfDeviceObject**, and passes the information to the driver using **Bind()** and **Init()** (see step 1). <br>The following is an example of the driver configuration:
```
root {
SampleDriverConfig {
sample_version = 1;
sample_bus = "I2C_0";
match_attr = "sample_config"; // The value must be the same as that of deviceMatchAttr in device_info.hcs.
}
}
```
Add the configuration file to the **hdf.hcs** file. <br>The following is an example:
The HDF loads the drivers that match the configured device list.
## Driver Loading Policies
The HDF supports on-demand loading and sequential loading of drivers. The **preload** field in the configuration file (see [Driver Development](../driver/driver-hdf-development.md)) specifies the loading policy of a driver. The values are as follows:
```c
typedefenum{
DEVICE_PRELOAD_ENABLE=0,
DEVICE_PRELOAD_ENABLE_STEP2=1,
DEVICE_PRELOAD_DISABLE=2,
DEVICE_PRELOAD_INVALID
}DevicePreload;
```
### On-Demand Loading
- The value **0** (**DEVICE_PRELOAD_ENABLE**) means to load the driver by default during the system boot process.
- The value **1** (**DEVICE_PRELOAD_ENABLE_STEP2**) means to load the driver after a quick start is complete. If the system does not support quick start, the value **1** has the same meaning as **DEVICE_PRELOAD_ENABLE**.
- The value **2** (**DEVICE_PRELOAD_DISABLE**) means to load the driver dynamically. When a user-mode process requests the driver service, the HDF attempts to dynamically load the driver if the driver service is not available. For more details, see [Driver Messaging Mechanism](../driver/driver-hdf-message-management.md).
### Sequential Loading (Default)
The **priority** field (ranging from 0 to 200) in the configuration file determines the loading sequence of a host and a driver. For the drivers in different hosts, the driver with a smaller priority value is loaded first. For the drivers in the same host, the driver with a smaller priority value is loaded first.
### Exception Recovery (User-Mode Driver)
The policies for restoring from a driver service exception are as follows:
- If **preload** is set to **0** (**DEVICE_PRELOAD_ENABLE**) or **1** (**DEVICE_PRELOAD_ENABLE_STEP2**) for the driver service, the startup module starts the host and reloads the service.
- If **preload** is set to **2** (**DEVICE_PRELOAD_DISABLE**), the service module needs to register an HDF service status listener. When receiving a notification on service exit, the service module calls **LoadDevice()** to reload the service.
The HDF messaging mechanism implements the interaction between the user-mode applications and kernel-mode drivers.
## Available APIs
The messaging mechanism allows:
1. A user-mode application to send a message to a driver.
2. A user-mode application to receive events reported by a driver.
**Table 1** APIs for the driver messaging mechanism
| API| Description|
| -------- | -------- |
| struct HdfIoService \*HdfIoServiceBind(const char \*serviceName); | Obtains a driver service. After obtaining the driver service, the user-mode application uses **Dispatch()** in the driver service obtained to send messages to the driver.|
| void HdfIoServiceRecycle(struct HdfIoService \*service); | Releases a driver service.|
| int HdfDeviceRegisterEventListener(struct HdfIoService \*target, struct HdfDevEventlistener \*listener); | Registers the method for receiving events reported by the driver.|
1. In the driver configuration file, set **policy** to **2**. For more details, see [Driver Service Management](../driver/driver-hdf-servicemanage.md).
```
device_sample :: Device {
policy = 2;
...
}
```
2. Set permissions for the device node of the driver. By default, the **permission** field is set to **0666**. You can set it based on service requirements.
3. Implement the **Dispatch()** method of **IDeviceIoService**.
```c
// Dispatch() is used to process messages sent from the user-mode application.
The Hardware Driver Foundation (HDF) provides driver framework capabilities, such as driver loading, driver service management, driver messaging mechanism, and configuration management, for driver developers. It strives to provide a more precise and efficient driver development environment, where you can perform one-time development for multi-device deployment.
## Driver Loading
The HDF supports the following loading modes:
- On-demand loading
The HDF allows drivers to be loaded by default during the operating system (OS) boot process or dynamically loaded after the OS is started.
- Sequential loading
The HDF allows drivers to be loaded based on their priorities during the OS boot process.
## Driver Service Management
The HDF supports centralized management of driver services. You can obtain a driver service by using the API provided by the HDF.
## Driver Messaging Mechanism
The HDF provides a unified driver messaging mechanism, which allows messages to be exchanged between user-mode applications and kernel-mode drivers.
## Configuration Management
HDF Configuration Source (HCS) provides the source code that describes the HDF configuration in key-value pairs. It decouples the configuration code from driver code, simplifying configuration management.
## Implementing Interaction Between the Application and the Driver
Write the code for interaction between the user-mode application and the driver. Place the code in the **drivers/hdf_core/adapter/uhdf** directory for compilation. For details about **BUILD.gn**, see **drivers/hdf_core/framework/sample/platform/uart/dev/BUILD.gn**.
> The user-mode application uses the message sending API of the HDF, and the compilation of the user-mode application depends on the dynamic libraries **hdf_core** and **osal** provided by the HDF. Therefore, you need to add the following dependencies to the .gn file:
Driver services are objects of capabilities provided by HDF driver devices to external systems and are managed by the HDF in a unified manner. Driver service management involves publishing and obtaining driver services.
The HDF uses the **policy** field in the configuration file to define policies for a driver to provide services externally. The values this field are as follows:
```c
typedefenum{
/* The driver does not provide services. */
SERVICE_POLICY_NONE=0,
/* The driver publishes services only for kernel-mode processes. */
SERVICE_POLICY_PUBLIC=1,
/* The driver publishes services for both kernel- and user-mode processes. */
SERVICE_POLICY_CAPACITY=2,
/** The driver services are not published externally but can be subscribed to. */
SERVICE_POLICY_FRIENDLY=3,
/* The driver private services cannot be published externally or subscribed to. */
SERVICE_POLICY_PRIVATE=4,
/** Invalid service policy. */
SERVICE_POLICY_INVALID
}ServicePolicy;
```
## When to Use
You can use the driver service management capability of the HDF when the driver needs to provide capabilities via APIs.
## Available APIs
The table below describes the APIs for driver service management.
**Table 1** APIs for driver service management
| API| Description|
| -------- | -------- |
| int32_t (\*Bind)(struct HdfDeviceObject \*deviceObject) | Binds a service API to the HDF. You need to implement the **Bind()** function.|
// deviceObject is a pointer to the device object created by the HDF for each driver. The device object holds private device data and service APIs.
if(deviceObject==NULL){
HDF_LOGE("Sample device object is null!");
returnHDF_FAILURE;
}
staticstructISampleDriverServicesampleDriverA={
.ServiceA=SampleDriverServiceA,
.ServiceB=SampleDriverServiceB,
};
deviceObject->service=&sampleDriverA.ioService;
returnHDF_SUCCESS;
}
```
3. Obtain the driver service.
The driver service can be obtained by using either of the following methods:
- Using the API provided by the HDF
If the service requester clearly knows the time when the driver is loaded, use the API provided by the HDF to obtain the driver service. The following is an example:
If the service requester is unaware of the time when the driver (in the same host) is loaded, use the subscription mechanism provided by the HDF to subscribe to the service. After the driver is loaded, the HDF publishes the driver service to the subscriber. The implementation is as follows:
```c
// Callback invoked to return the driver service after the subscribed driver is loaded.
// object is the pointer to the private data of the subscriber, and service is the pointer to the subscribed service object.
## cl.arkcompiler.1 New Alarms and Existing Alarm Enhancements for LLVM
**Change Impact**
By default, the **-Werror** option is disabled for the OpenHarmony NDK. If you have enabled the **-Werror** option, you are advised to correct the code based on the suggestions in the check result or mask the errors.
**Changes in Key Compilation Check Rules**
| New Check Item| Description| Suggestion|
| --- | --- | --- |
| Wunused-but-set-variable | An alarm is generated when the code contains unused variables (including the ++ operator).| Add the **maybe_unused** attribute when defining variables or use macros to distinguish variables.|
| Wdeprecated-non-prototype | An alarm is generated when a function without a prototype exists in the code.| Add a function prototype and specify the parameters.|
| Wunqualified-std-cast-call | An alarm is generated when **std::move** is incorrectly used in code.| Specify the use case of **std::move** and check the code.|
| Wdeprecated-builtins | An alarm is generated when a deprecated built-in function is used in the code.| Use the substitute function.|
| Warray-parameter | An alarm is generated when a function parameter contains an array that uses inconsistent forms.| Ensure the consistency of the function parameter.|
| Wbitwise-instead-of-logical | An alarm is generated when bitwise OR is used in Boolean operations.| Use logical OR in Boolean operations.|
| Wint-conversion | An alarm is generated when an int variable is converted to a pointer in the code.| Use a new implementation mode in the code.|
| Wdeprecated-declarations | An alarm is generated when a deprecated definition (including functions and variables) is used in code.| Use a new implementation mode in the code.|
| Wnull-pointer-subtraction | An alarm is generated when a null pointer is used in the subtraction operation.| Do not a null pointer in the subtraction operation.|
| Wunused-but-set-parameter | An alarm is generated when a function contains unused parameters.| Delete unused parameters.|
| Warray-bounds | An alarm is generated when out-of-bounds access to an array occurs in the code.| Modify the out-of-bounds access.|
| Wdeprecated-pragma | An alarm is generated when a deprecated macro is used in the code.| Delete the deprecated macro.|
| Wreserved-identifier | An alarm is generated when a variable starting with __ is used in the code.| Check the code to prevent variables starting with underscores (_) from being used externally.|
**Adaptation Guide**
1. For issues in the code that are not detected by LLVM 12, check and update the code.
2. Some old implementations are discarded during LLVM update. Adapt to the new rules and update the code.
3. If you believe a certain type of error can be masked, use the **-Wno-xxx** option to mask the error.
When your code depends on the **version-script** or **-gcc-toolchain** option, parsing may fail if you continue to use the original LLVM 12 configuration file or options.
**Changes in Key Compilation Rules**
1. The symbol representation is changed. In the new version, consecutive greater signs (>) are represented as ">>", which was represented as "> >" in the old version.
2. The -xx options are deprecated. For example, the **-gcc-toolchain** option is replaced by the **--gcc-toolchain** option. (This option has been marked as deprecated in versions later than Clang 3.4 and is officially deprecated in LLVM15.)
**Adaptation Guide**
If two consecutive greater signs (>) exist in the code (without considering the number of spaces in the middle), they will be parsed as "> >" in the older version and ">>" in the new version in version-script (due to mangling differences). In LLVM15, ">>" must be used.
If you use both LLVM 12 and LLVM 15 (this behavior is prohibited) for your code, the emu-tls symbol cannot be found in libc++.so.
**Key Library Dependency Changes**
In LLVM 15, the emu-tls symbol is extracted from the target binary file to libc++.so. That is, the __emutls_get_address attribute changes from an internal symbol to an externally visible symbol, which is included in libc++.so. As a result, the compiled dynamic library may depend on libc++.so.
**Adaptation Guide**
This symbol is also in libclang_rt.builtin.a. If you do not want the compiled dynamic library to depend on libc++.so, statically link the libclang_rt.builtin.a library.
## cl.arkcompiler.4 LLVM Official Release Notes
**Change Impact**
New features are added and internal interfaces are changed (such as IR in LLVM and compiler front-end modification). For details, see the official release notes.
