From fc5fc0e74df003b0ee454d3418b88cd722282c49 Mon Sep 17 00:00:00 2001 From: Gina Dimino Date: Mon, 12 Jul 2021 16:35:38 -0700 Subject: Remove obsolete sync directories for SAC Test: N/A Change-Id: I5245330990d722ad4d15a0600532943840f30830 --- .../architecture/configstore/add-class-item.html | 236 --------------------- en/devices/architecture/configstore/client.html | 166 --------------- en/devices/architecture/configstore/index.html | 108 ---------- en/devices/architecture/configstore/interface.html | 186 ---------------- en/devices/architecture/configstore/service.html | 128 ----------- 5 files changed, 824 deletions(-) delete mode 100644 en/devices/architecture/configstore/add-class-item.html delete mode 100644 en/devices/architecture/configstore/client.html delete mode 100644 en/devices/architecture/configstore/index.html delete mode 100644 en/devices/architecture/configstore/interface.html delete mode 100644 en/devices/architecture/configstore/service.html (limited to 'en/devices/architecture/configstore') diff --git a/en/devices/architecture/configstore/add-class-item.html b/en/devices/architecture/configstore/add-class-item.html deleted file mode 100644 index 319462b7..00000000 --- a/en/devices/architecture/configstore/add-class-item.html +++ /dev/null @@ -1,236 +0,0 @@ - - - Adding ConfigStore Classes & Items - - - - - - - -

You can add new ConfigStore items (i.e., interface methods) for an -existing interface class. If the interface class is not defined, you must add a -new class before you can add a ConfigStore item for that class. This section -uses the example of a disableInitBlank configuration item for -healthd being added to the IChargerConfigs interface -class.

- -

Note: Before continuing, ensure you are familiar -with general HIDL concepts, -HIDL C++ development -workflow, HIDL Code -Style, and -ConfigStore design.

- -

Adding interface classes

-

If no interface class is defined for the interface method you want to add, -you must first add the interface class before you can add the associated -ConfigStore items.

- -
    -
  1. Create a HAL interface file. The ConfigStore version is 1.0, so define -ConfigStore interfaces in hardware/interfaces/configstore/1.0. For -example, in -hardware/interfaces/configstore/1.0/IChargerConfigs.hal: - -
    -package android.hardware.configstore@1.0;
-
-interface IChargerConfigs {
-    // TO-BE-FILLED-BELOW
-};
-
    2. - -
  2. Update Android.bp and Android.mk for ConfigStore -shared library and header files to include the new interface HAL. For example: - -
    -hidl-gen -o hardware/interfaces/configstore/1.0/default -Lmakefile -randroid.hardware:hardware/interfaces -randroid.hidl:system/libhidl/transport android.hardware.configstore@1.0::IChargerConfigs
-hidl-gen -o hardware/interfaces/configstore/1.0/default -Landroidbp -randroid.hardware:hardware/interfaces -randroid.hidl:system/libhidl/transport android.hardware.configstore@1.0::IChargerConfigs
-
    -These commands update Android.bp and Android.mk in -hardware/interfaces/configstore/1.0.
    3. - -
  3. Generate the C++ stub for implementing the server code. For example: - -
    -hidl-gen -o hardware/interfaces/configstore/1.0/default -Lc++-impl -randroid.hardware:hardware/interfaces -randroid.hidl:system/libhidl/transport android.hardware.configstore@1.0::IChargerConfigs
-
    -This command creates two files, ChargerConfigs.h and -ChargerConfigs.cpp, in -hardware/interfaces/configstore/1.0/default.
    4. - -
  4. Open the .h and .cpp implementation files and remove code related to the -function HIDL_FETCH_name (e.g., -HIDL_FETCH_IChargerConfigs). This function is needed for HIDL -passthrough mode, which is unused by ConfigStore.
    5. - -
  5. Register the implementation to the ConfigStore service. For example, in -hardware/interfaces/configstore/1.0/default/service.cpp: - -
    -#include <android/hardware/configstore/1.0/IChargerConfigs.h>
-#include "ChargerConfigs.h"
-
-using android::hardware::configstore::V1_0::IChargerConfigs;
-using android::hardware::configstore::V1_0::implementation::ChargerConfigs;
-
-int main() {
-    ... // other code
-    sp<IChargerConfigs> chargerConfigs = new ChargerConfigs;
-    status = chargerConfigs->registerAsService();
-    LOG_ALWAYS_FATAL_IF(status != OK, "Could not register IChargerConfigs");
-    ... // other code
-}
-
    6. - -
  6. Modify Android.mk file to add implementation file -(modulenameConfigs.cpp) to LOCAL_SRC_FILES and to map build flags into -macro definitions. For example, in -hardware/interfaces/configstore/1.0/default/Android.mk: - -
    -LOCAL_SRC_FILES += ChargerConfigs.cpp
-
-ifeq ($(strip $(BOARD_CHARGER_DISABLE_INIT_BLANK)),true)
-LOCAL_CFLAGS += -DCHARGER_DISABLE_INIT_BLANK
-endif
-
    7. - -
  7. (Optional) Add manifest entry. If it doesn't exist, default to the "default" -instance name of ConfigStore. For example, in -device/google/marlin/manifest.xml: - -
    -    <hal format="hidl">
-        <name>android.hardware.configstore</name>
-        ...
-        <interface>
-            <name>IChargerConfigs</name>
-            <instance>default</instance>
-        </interface>
-    </hal>
-
    8. - -
  8. Add the sepolicy rule if needed (i.e., if the client does not have -permissions for making hwbinder calls to the hal_configstore). For -example, in system/sepolicy/private/healthd.te: - -
    -... // other rules
-binder_call(healthd, hal_configstore)
-
    9. -
- - -

Adding new ConfigStore items

-

To add a new ConfigStore item:

-
    -
  1. Open the HAL file and add required interface method for the item. (The .hal -files for ConfigStore reside in -hardware/interfaces/configstore/1.0.) For example, in -hardware/interfaces/configstore/1.0/IChargerConfigs.hal: - -
    -package android.hardware.configstore@1.0;
-
-interface IChargerConfigs {
-    ... // Other interfaces
-    disableInitBlank() generates(OptionalBool value);
-};
-
    2. - -
  2. Implement the method in the corresponding interface HAL implementation files -(.h and .cpp). Place default implementations in -hardware/interfaces/configstore/1.0/default. - -

    Note: Running hidl-gen with --Lc++-impl generates skeleton code for the newly added interface -method. However, as it also overwrites implementations for all existing -interface methods, use the -o option appropriately.

    - -For example, in -hardware/interfaces/configstore/1.0/default/ChargerConfigs.h: - -
    -struct ChargerConfigs : public IChargerConfigs {
-    ... // Other interfaces
-    Return<void> disableInitBlank(disableInitBlank_cb _hidl_cb) override;
-};
-
    - -And in -hardware/interfaces/configstore/1.0/default/ChargerConfigs.cpp: - -
    -Return<void> ChargerConfigs::disableInitBlank(disableInitBlank_cb _hidl_cb) {
-    bool value = false;
-#ifdef CHARGER_DISABLE_INIT_BLANK
-    value = true;
-#endif
-    _hidl_cb({true, value});
-    return Void();
-}
-
    3. -
- -

Using ConfigStore items

-

To use a ConfigStore item:

- -
    -
  1. Include required header files. For example, in -system/core/healthd/healthd.cpp: - -
    -#include <android/hardware/configstore/1.0/IChargerConfigs.h>
-#include <configstore/Utils.h>
-
    2. - -
  2. Access the ConfigStore item using the appropriate template function in -android.hardware.configstore-utils. For example, in -system/core/healthd/healthd.cpp: - -
    -using namespace android::hardware::configstore;
-using namespace android::hardware::configstore::V1_0;
-
-static int64_t disableInitBlank = getBool<
-        IChargerConfigs,
-        &IChargerConfigs::disableInitBlank>(false);
-
    -In this example, the ConfigStore item disableInitBlank is retrieved -and stored to a variable (useful when the variable needs to be accessed multiple -times). The value retrieved from the ConfigStore is cached inside the -instantiated template function so it can be retrieved quickly from the cached -value without contacting the ConfigStore service for later calls to the -instantiated template function. -
    3. - -
  3. Add the dependency on ConfigStore and configstore-utils library -in Android.mk or Android.bp. For example, in -system/core/healthd/Android.mk: - -
    -LOCAL_SHARED_LIBRARIES := \
-    android.hardware.configstore@1.0 \
-    android.hardware.configstore-utils \
-    ... (other libraries) \
-
    4. -
- - - diff --git a/en/devices/architecture/configstore/client.html b/en/devices/architecture/configstore/client.html deleted file mode 100644 index 7b691994..00000000 --- a/en/devices/architecture/configstore/client.html +++ /dev/null @@ -1,166 +0,0 @@ - - - Client-Side Usage - - - - - - -

You can refactor conditionally-compiled code to read values dynamically from -the HAL interface. For example:

- -
-#ifdef TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS
-//some code fragment
-#endif
-
- -

Framework code can then call an appropriate utility function defined in -<configstore/Utils.h> depending on its type.

- -

ConfigStore example

-

This example shows reading -TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS, defined in ConfigStore HAL -as forceHwcForVirtualDisplays() with return type -OptionalBool:

- -
-#include <configstore/Utils.h>
-using namespace android::hardware::configstore;
-using namespace android::hardware::configstore::V1_0;
-
-static bool vsyncPhaseOffsetNs = getBool<ISurfaceFlingerConfigs,
-        ISurfaceFlingerConfigs::forceHwcForVirtualDisplays>(false);
-
- -

The utility function (getBool in the example above) contacts the -configstore service to get the handle for the proxy of the -interface function, then retrieves the value by invoking the handle via -HIDL/hwbinder.

- -

Utility functions

-

<configstore/Utils.h> -(configstore/1.0/include/configstore/Utils.h) provides utility -functions for each primitive return type, including -Optional[Bool|String|Int32|UInt32|Int64|UInt64], as listed -below:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeFunction (template parameters omitted)
OptionalBoolbool getBool(const bool defValue)
OptionalInt32int32_t getInt32(const int32_t defValue)
OptionalUInt32uint32_t getUInt32(const uint32_t defValue)
OptionalInt64int64_t getInt64(const int64_t defValue)
OptionalUInt64uint64_t getUInt64(const uint64_t defValue)
OptionalStringstd::string getString(const std::string &defValue)
- -

defValue is a default value returned when the HAL implementation -does not specify a value for the configuration item. Each function takes two -template parameters:

- -

Because the configuration value is read-only and does not change, the utility -function internally caches the configuration value. Subsequent calls are -serviced more efficiently using the cached value in the same linking unit.

- -

Using configstore-utils

-

The ConfigStore HAL is designed to be forward-compatible for minor version -upgrades, meaning that when the HAL is up-revisioned and some framework code -uses the newly-introduced items, the ConfigStore service with older minor -version in /vendor can still be used.

- -

For forward-compatibility, ensure your implementation adheres to the -following guidelines:

- -
    -
  1. New items use the default value when only the old version service -is available. Example: - -
    -service = V1_1::IConfig::getService(); // null if V1_0 is installed
-value = DEFAULT_VALUE;
-  if(service) {
-    value = service->v1_1API(DEFAULT_VALUE);
-  }
-
    - -
    2. - -
  2. Client uses the earliest interface in which the ConfigStore item was -introduced. Example: - -
    -V1_1::IConfig::getService()->v1_0API(); // NOT ALLOWED
-
-V1_0::IConfig::getService()->v1_0API(); // OK
-
    -
    3. -
  3. New version service can be retrieved for old version interface. In the -following example, if the installed version is v1_1, the v1_1 service must be -returned for getService(): - -
    -V1_0::IConfig::getService()->v1_0API();
-
    - -

    Note: The -current AOSP -implementation satisfies this requirement.

    -
    4. -
- -

When the access functions in configstore-utils library are used -for accessing the ConfigStore item, #1 is guaranteed by the implementation and -#2 is guaranteed by compiler errors. For these reasons we strongly recommend -using configstore-utils wherever possible.

- - - diff --git a/en/devices/architecture/configstore/index.html b/en/devices/architecture/configstore/index.html deleted file mode 100644 index 45dcb9e7..00000000 --- a/en/devices/architecture/configstore/index.html +++ /dev/null @@ -1,108 +0,0 @@ - - - Configstore HAL - - - - - - - -

Android O splits the monolithic Android OS into generic (system.img) -and hardware-specific (vendor.img and odm.img) partitions. As a result of this -change, conditional compilation must be removed from modules installed to the -system partition and such modules must now determine the configuration of the -system at runtime (and behave differently depending on that configuration).

- -

The ConfigStore HAL provides a set of APIs for accessing read-only -configuration items used to configure the Android framework. This page describes -the design of ConfigStore HAL (and why system properties were not used for this -purpose); other pages in this section detail the -HAL interface, -service -implementation, and -client-side usage, -all using surfaceflinger as an example. For help with ConfigStore -interface classes, see -Adding Interface -Classes & Items.

- -

Why not use system properties?

-

We considered using system properties but found several fundamental issues, -including:

- -

We attempted to overcome these limitations without sacrificing compatibility -but continued to be concerned that system properties were not designed to -support accessing read-only configuration items. Eventually we decided that -system properties are better suited for sharing a few dynamically-updated items -across all of Android in real time, and that a need existed for a new system -dedicated to accessing read-only configuration items.

- -

ConfigStore HAL design

-

The basic design is simple:

-

-

Figure 1. ConfigStore HAL design

- - - -

Configuration items currently referenced by the framework are included in a -versioned HIDL package (android.hardware.configstore@1.0). Vendors -and/or OEMs provide values to the configuration items by implementing interfaces -in this package, and the framework uses the interfaces when it needs to get a -value for a configuration item.

- -

Security considerations

-

Build flags defined in the same interface are affected by same SELinux -policy. If one or more build flags should have different SELinux policies, -they must be separated to another interface. This can require -major uprev of android.hardware.configstore package as the -separated interfaces are no longer backwards-compatible.

- - - - - diff --git a/en/devices/architecture/configstore/interface.html b/en/devices/architecture/configstore/interface.html deleted file mode 100644 index 6c735feb..00000000 --- a/en/devices/architecture/configstore/interface.html +++ /dev/null @@ -1,186 +0,0 @@ - - - Creating the HAL Interface - - - - - - -

You must use HIDL to describe all build flags used for conditionally -compiling the framework. Relevant build flags must be grouped and included in a -single .hal file. Using HIDL for specifying configuration items -includes the following benefits:

- - -

Identifying build flags used by the framework

-

Start by identifying the build configs used to conditionally compile the -framework, then abandon obsolete configs to make the set smaller. For example, -the following set of build flags are identified for surfaceflinger: -

- - -

Creating a HAL interface

-

Build configs for a subsystem are accessed via a HAL interface, while -interfaces for giving configuration values are grouped in the HAL package android.hardware.configstore (currently at version 1.0). For example, to -create a HAL interface file for surfaceflinger, in -hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal: -

- -
-package android.hardware.configstore@1.0;
-
-interface ISurfaceFlingerConfigs {
-    // TO-BE-FILLED-BELOW
-};
-
- -

After creating the .hal file, run -hardware/interfaces/update-makefiles.sh to add the new -.hal file to the Android.bp and -Android.mk files.

- -

Adding functions for build flags

-

For each build flag, add a new function to the interface. For example, in -hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal: -

- -
-interface ISurfaceFlingerConfigs {
-    disableTripleBuffering() generates(OptionalBool ret);
-    forceHwcForVirtualDisplays() generates(OptionalBool ret);
-    enum NumBuffers: uint8_t {
-        USE_DEFAULT = 0,
-        TWO = 2,
-        THREE = 3,
-    };
-    numFramebufferSurfaceBuffers() generates(NumBuffers ret);
-    runWithoutSyncFramework() generates(OptionalBool ret);
-    vsyncEventPhaseOffsetNs generates (OptionalUInt64 ret);
-    presentTimeOffsetFromSyncNs generates (OptionalUInt64 ret);
-    maxVirtualDisplayDimension() generates(OptionalInt32 ret);
-};
-
- -

When adding a function:

- -

Function return types can be -Optional[Bool|String|Int32|UInt32|Int64|UInt64]. Types are defined -in types.hal in the same directory and wrap primitive values with a -field that indicates if the value is specified by the HAL; if not, the default -value is used.

- -
-struct OptionalString {
-    bool specified;
-    string value;
-};
-
- -

When appropriate, define the enum that best represents the type of the -configuration item and use that enum as the return type. In the example above, -the NumBuffers enum is defined to limit the number of valid -values. When defining such custom data types, add a field or a enum value (e.g., -USE_DEFAULT) for denoting if the value is/is not specified by -HAL.

- -

It is not mandatory for a single build flag to become a single function in -HIDL. Module owners can alternatively aggregate closely-related build flags into -a struct and have a function that returns that struct (doing so can reduce -number of function calls).

- -

For example, an option for aggregating two build flags into a single struct -in hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal -is:

- -
- interface ISurfaceFlingerConfigs {
-    // other functions here
-    struct SyncConfigs {
-        OptionalInt64 vsyncEventPhaseoffsetNs;
-        OptionalInt64 presentTimeoffsetFromSyncNs;
-    };
-    getSyncConfigs() generates (SyncConfigs ret);
-    // other functions here
-};
-
- -

Alternatives to a single HAL function

- -

As an alternative to using a single HAL function for all build flags, the HAL -interface also provides simple functions such as getBoolean(string -key) and getInteger(string key). The actual -key=value pairs are stored in separate files and the HAL service -provides values by reading/parsing those files.

- -

While this approach is easy to define, it does not include the benefits -provided by HIDL (enforced versioning, ease of documentation, access control) -and is therefore not recommended.

- -

Note: When using simple functions, access -control is almost impossible as HAL cannot identify clients by itself.

- -

Single vs. multiple interfaces

-

The design of the HAL interface for configuration items presents two -choices:

- -
    -
  1. Single interface that covers all configuration items
    2. -
  2. Multiple interfaces, each of which covers a set of related configuration -items
    3. -
-

A single interface is easier but can become unmaintainable as more -configuration items are added to the single file. In addition, access control -is not fine-grained, so a process granted access to the interface can read all -configuration items (access to a partial set of configuration items cannot be -granted). Alternatively, if access is not granted, no configuration item can be -read.

- -

Because of these issues, Android uses multiple interfaces with a single HAL -interface for a group of related configuration items. For example, -ISurfaceflingerConfigs for surfaceflinger-related -configuration items, IBluetoothConfigs for Bluetooth-related -configuration items, etc.

- - - diff --git a/en/devices/architecture/configstore/service.html b/en/devices/architecture/configstore/service.html deleted file mode 100644 index 09874b4d..00000000 --- a/en/devices/architecture/configstore/service.html +++ /dev/null @@ -1,128 +0,0 @@ - - - Implementing the Service - - - - - - -

To prepare for the HAL implementation, you can generate basic configstore -interface code then modify it to meet your needs.

- -

Generating interface code

-

To generate boilerplate code for the interface, run hidl-gen. -For example, to generate code for surfaceflinger:

- -
-hidl-gen -o hardware/interfaces/configstore/1.0/default \
-    -Lc++-impl \
-    -randroid.hardware:hardware/interfaces \
-    -randroid.hidl:system/libhidl/transport \
-    android.hardware.config@1.0::ISurfaceFlingerConfigs
-
- -

Note: Don't run hidl-gen with --Landroidbp-impl as this generates Android.bp. The -module must be built with Android.mk to access build flags.

- -

Modifying Android.mk

-

Next, modify Android.mk file to add implementation file -(<modulename>Configs.cpp) to LOCAL_SRC_FILES and -to map build flags into macro definitions. For example, you can modify -surfaceflinger in -hardware/interface/configstore/1.0/default/Android.mk: -

- -
-LOCAL_SRC_FILES += SurfaceFlingerConfigs.cpp
-ifneq ($(NUM_FRAMEBUFFER_SURFACE_BUFFERS),)
-    LOCAL_CFLAGS += -DNUM_FRAMEBUFFER_SURFACE_BUFFERS=$(NUM_FRAMEBUFFER_SURFACE_BUFFERS)
-endif
-
-ifeq ($(TARGET_RUNNING_WITHOUT_SYNC_FRAMEWORK),true)
-    LOCAL_CFLAGS += -DRUNNING_WITHOUT_SYNC_FRAMEWORK
-endif
-
- -

If Android.mk includes several ifeq-endif blocks, -consider moving your code into a new file (i.e., surfaceflinger.mk) -then include that file from Android.mk.

- -

Implementing functions

-

To fill the functions to implement the HAL, call back the -_hidl_cb function with different values (conditioned on build -flags). For example, you can fill the functions for surfaceflinger -in hardware/interfaces/configstore/1.0/default/SurfaceFlingerConfigs.cpp:

- -
-Return<void> SurfaceFlingerConfigs::numFramebufferSurfaceBuffers(
-        numFramebufferSurfaceBuffers_cb _hidl_cb) {
-    #if NUM_FRAMEBUFFER_SURFACE_BUFFERS 2
-    _hidl_cb(NumBuffers.TWO);
-    #else if NUM_FRAMEBUFFER_SURFACE_BUFFERS 3
-    _hidl_cb(NumBuffers.THREE);
-    #else
-    _hidl_cb(NumBuffers.USE_DEFAULT);
-    #endif
-}
-
-Return<void> SurfaceFlingerConfigs::runWithoutSyncFramework(
-        runWithoutSyncFramework_cb _hidl_cb) {
-    #ifdef RUNNING_WITHOUT_SYNC_FRAMEWORK
-    _hidl_cb({true /* specified */, true /* value */});
-    #else
-    // when macro not defined, we can give any value to the second argument.
-    // It will simply be ignored in the framework side.
-    _hidl_cb({false /* specified */, false /* value */});
-    #endif
-}
-
- -

Ensure the implementation does not contain a function named -HIDL_FETCH_<interface name> (e.g., -HIDL_FETCH_ISurfaceFlingerConfigs). This function is needed for -HIDL passthrough mode, which is unused (and prohibited) by -configstore. ConfigStore must always run in binderized mode.

- -

Registering as a service

-

Finally, register all interface implementations to the -configstore service. For example, you can register -surfaceflinger implementations in -hardware/interfaces/configstore/1.0/default/service.cpp: -

- -
-configureRpcThreadpool(maxThreads, true);
-sp<ISurfaceFlingerConfigs> surfaceFlingerConfigs = new SurfaceFlingerConfigs;
-status_t status = surfaceFlingerConfigs->registerAsService();
-
-sp<IBluetoothConfigs> bluetoothConfigs = new BluetoothConfigs;
-status = bluetoothConfigs->registerAsService();
-
-// register more interfaces here
-joinRpcThreadpool();
-
- -

Ensuring early access

-

To ensure a framework module can get early access the HAL service, the config -HAL service should start as early as possible, just after -hwservicemanager is ready. As the config HAL service does not read -external files, it is expected to be ready quickly after it is launched.

- - - -- cgit v1.2.3