diff options
| author | Gina Dimino <gdimino@google.com> | 2021-07-12 16:35:38 -0700 |
|---|---|---|
| committer | Gina Dimino <gdimino@google.com> | 2021-07-15 15:35:51 -0700 |
| commit | fc5fc0e74df003b0ee454d3418b88cd722282c49 (patch) | |
| tree | 7fa97b880b85be7de5b713d233cdc407c20b88cd /en/devices/architecture/configstore | |
| parent | e55b3193405187e091a4ac7730ef04360ec04504 (diff) | |
| download | source.android.com-fc5fc0e74df003b0ee454d3418b88cd722282c49.tar.gz | |
Remove obsolete sync directories for SAC
Test: N/A
Change-Id: I5245330990d722ad4d15a0600532943840f30830
Diffstat (limited to 'en/devices/architecture/configstore')
| -rw-r--r-- | en/devices/architecture/configstore/add-class-item.html | 236 | ||||
| -rw-r--r-- | en/devices/architecture/configstore/client.html | 166 | ||||
| -rw-r--r-- | en/devices/architecture/configstore/index.html | 108 | ||||
| -rw-r--r-- | en/devices/architecture/configstore/interface.html | 186 | ||||
| -rw-r--r-- | en/devices/architecture/configstore/service.html | 128 |
5 files changed, 0 insertions, 824 deletions
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 @@ -<html devsite> - <head> - <title>Adding ConfigStore Classes & Items</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> - - -<p>You can add new ConfigStore items</a> (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 <code>disableInitBlank</code> configuration item for -<code>healthd</code> being added to the <code>IChargerConfigs</code> interface -class.</p> - -<p class=note><strong>Note:</strong> Before continuing, ensure you are familiar -with <a href="/devices/architecture/hidl/index.html">general HIDL concepts</a>, -<a href="/devices/architecture/hidl-cpp/index.html">HIDL C++ development -workflow</a>, <a href="/devices/architecture/hidl/code-style.html">HIDL Code -Style</a>, and <a href="/devices/architecture/configstore/index.html"> -ConfigStore design</a>.</p> - -<h2 id=add-class>Adding interface classes</h2> -<p>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.</p> - -<ol> -<li>Create a HAL interface file. The ConfigStore version is 1.0, so define -ConfigStore interfaces in <code>hardware/interfaces/configstore/1.0</code>. For -example, in -<strong><code>hardware/interfaces/configstore/1.0/IChargerConfigs.hal</code></strong>: - -<pre class="devsite-click-to-copy"> -package android.hardware.configstore@1.0; - -interface IChargerConfigs { - // TO-BE-FILLED-BELOW -}; -</pre></li> - -<li>Update <code>Android.bp</code> and <code>Android.mk</code> for ConfigStore -shared library and header files to include the new interface HAL. For example: - -<pre class="devsite-click-to-copy"> -<code class=devsite-terminal>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</code> -<code class=devsite-terminal>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</code> -</pre> -These commands update <code>Android.bp</code> and <code>Android.mk</code> in -<code>hardware/interfaces/configstore/1.0</code>.</li> - -<li>Generate the C++ stub for implementing the server code. For example: - -<pre class="devsite-terminal devsite-click-to-copy"> -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 -</pre> -This command creates two files, <code>ChargerConfigs.h</code> and -<code>ChargerConfigs.cpp</code>, in -<code>hardware/interfaces/configstore/1.0/default</code>.</li> - -<li>Open the .h and .cpp implementation files and remove code related to the -function <code>HIDL_FETCH_<em>name</code></em> (e.g., -<code>HIDL_FETCH_IChargerConfigs</code>). This function is needed for HIDL -passthrough mode, which is unused by ConfigStore.</li> - -<li>Register the implementation to the ConfigStore service. For example, in -<strong><code>hardware/interfaces/configstore/1.0/default/service.cpp</code></strong>: - -<pre class="devsite-click-to-copy"> -#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 -} -</pre></li> - -<li>Modify <code>Android.mk</code> file to add implementation file -(<em>modulename</em>Configs.cpp) to LOCAL_SRC_FILES and to map build flags into -macro definitions. For example, in -<strong><code>hardware/interfaces/configstore/1.0/default/Android.mk</code></strong>: - -<pre class="devsite-click-to-copy"> -LOCAL_SRC_FILES += ChargerConfigs.cpp - -ifeq ($(strip $(BOARD_CHARGER_DISABLE_INIT_BLANK)),true) -LOCAL_CFLAGS += -DCHARGER_DISABLE_INIT_BLANK -endif -</pre></li> - -<li>(Optional) Add manifest entry. If it doesn't exist, default to the "default" -instance name of ConfigStore. For example, in -<strong><code>device/google/marlin/manifest.xml</code></strong>: - -<pre class="devsite-click-to-copy"> - <hal format="hidl"> - <name>android.hardware.configstore</name> - ... - <interface> - <name>IChargerConfigs</name> - <instance>default</instance> - </interface> - </hal> -</pre></li> - -<li>Add the sepolicy rule if needed (i.e., if the client does not have -permissions for making hwbinder calls to the <code>hal_configstore</code>). For -example, in <strong><code>system/sepolicy/private/healthd.te</code></strong>: - -<pre class="devsite-click-to-copy"> -... // other rules -binder_call(healthd, hal_configstore) -</pre></li> -</ol> - - -<h2 id=add-item>Adding new ConfigStore items</h2> -<p>To add a new ConfigStore item:</p> -<ol> -<li>Open the HAL file and add required interface method for the item. (The .hal -files for ConfigStore reside in -<code>hardware/interfaces/configstore/1.0</code>.) For example, in -<strong><code>hardware/interfaces/configstore/1.0/IChargerConfigs.hal</code></strong>: - -<pre class="devsite-click-to-copy"> -package android.hardware.configstore@1.0; - -interface IChargerConfigs { - ... // Other interfaces - disableInitBlank() generates(OptionalBool value); -}; -</pre></li> - -<li>Implement the method in the corresponding interface HAL implementation files -(.h and .cpp). Place default implementations in -<code>hardware/interfaces/configstore/1.0/default</code>. - -<p class=note><strong>Note:</strong> Running <code>hidl-gen</code> with -<code>-Lc++-impl</code> generates skeleton code for the newly added interface -method. However, as it also overwrites implementations for all existing -interface methods, use the <code>-o</code> option appropriately.</p> - -For example, in -<strong><code>hardware/interfaces/configstore/1.0/default/ChargerConfigs.h</code></strong>: - -<pre class="devsite-click-to-copy"> -struct ChargerConfigs : public IChargerConfigs { - ... // Other interfaces - Return<void> disableInitBlank(disableInitBlank_cb _hidl_cb) override; -}; -</pre> - -And in -<strong><code>hardware/interfaces/configstore/1.0/default/ChargerConfigs.cpp</code></strong>: - -<pre class="devsite-click-to-copy"> -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(); -} -</pre></li> -</ol> - -<h2 id=using>Using ConfigStore items</h2> -<p>To use a ConfigStore item:</p> - -<ol> -<li>Include required header files. For example, in -<strong><code>system/core/healthd/healthd.cpp</code></strong>: - -<pre class="devsite-click-to-copy"> -#include <android/hardware/configstore/1.0/IChargerConfigs.h> -#include <configstore/Utils.h> -</pre></li> - -<li>Access the ConfigStore item using the appropriate template function in -<code>android.hardware.configstore-utils</code>. For example, in -<strong><code>system/core/healthd/healthd.cpp</code></strong>: - -<pre class="devsite-click-to-copy"> -using namespace android::hardware::configstore; -using namespace android::hardware::configstore::V1_0; - -static int64_t disableInitBlank = getBool< - IChargerConfigs, - &IChargerConfigs::disableInitBlank>(false); -</pre> -In this example, the ConfigStore item <code>disableInitBlank</code> 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. -</li> - -<li>Add the dependency on ConfigStore and <code>configstore-utils</code> library -in <code>Android.mk</code> or <code>Android.bp</code>. For example, in -<strong><code>system/core/healthd/Android.mk</code></strong>: - -<pre class="devsite-click-to-copy"> -LOCAL_SHARED_LIBRARIES := \ - android.hardware.configstore@1.0 \ - android.hardware.configstore-utils \ - ... (other libraries) \ -</pre></li> -</ol> - - </body> -</html> 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 @@ -<html devsite> - <head> - <title>Client-Side Usage</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> - -<p>You can refactor conditionally-compiled code to read values dynamically from -the HAL interface. For example:</p> - -<pre class="devsite-click-to-copy"> -#ifdef TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS -//some code fragment -#endif -</pre> - -<p>Framework code can then call an appropriate utility function defined in -<code><configstore/Utils.h></code> depending on its type.</p> - -<h2 id=example>ConfigStore example</h2> -<p>This example shows reading -<code>TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS</code>, defined in ConfigStore HAL -as <code>forceHwcForVirtualDisplays()</code> with return type -<code>OptionalBool</code>:</p> - -<pre class="devsite-click-to-copy"> -#include <configstore/Utils.h> -using namespace android::hardware::configstore; -using namespace android::hardware::configstore::V1_0; - -static bool vsyncPhaseOffsetNs = getBool<ISurfaceFlingerConfigs, - ISurfaceFlingerConfigs::forceHwcForVirtualDisplays>(false); -</pre> - -<p>The utility function (<code>getBool</code> in the example above) contacts the -<code>configstore</code> service to get the handle for the proxy of the -interface function, then retrieves the value by invoking the handle via -HIDL/hwbinder.</p> - -<h2 id=utility-functions>Utility functions</h2> -<p><code><configstore/Utils.h></code> -(<code>configstore/1.0/include/configstore/Utils.h</code>) provides utility -functions for each primitive return type, including -<code>Optional[Bool|String|Int32|UInt32|Int64|UInt64]</code>, as listed -below:</p> - -<table> - -<tr> -<th>Type</th> -<th>Function <em>(template parameters omitted)</em></th> -</tr> - -<tr> -<td><code>OptionalBool</code></td> -<td><code>bool getBool(const bool defValue)</code></td> -</tr> - -<tr> -<td><code>OptionalInt32</code></td> -<td><code>int32_t getInt32(const int32_t defValue)</code></td> -</tr> - -<tr> -<td><code>OptionalUInt32</code></td> -<td><code>uint32_t getUInt32(const uint32_t defValue)</code></td> -</tr> - -<tr> -<td><code>OptionalInt64</code></td> -<td><code>int64_t getInt64(const int64_t defValue)</code></td> -</tr> - -<tr> -<td><code>OptionalUInt64</code></td> -<td><code>uint64_t getUInt64(const uint64_t defValue)</code></td> -</tr> - -<tr> -<td><code>OptionalString</code></td> -<td><code>std::string getString(const std::string &defValue)</code></td> -</tr> - -</table> - -<p><code>defValue</code> is a default value returned when the HAL implementation -does not specify a value for the configuration item. Each function takes two -template parameters:</p> -<ul> -<li><code><strong>I</code></strong>. Interface class name.</li> -<li><code><strong>Func</code></strong>. Member function pointer for getting the -configuration item.</li> -</ul> -<p>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.</p> - -<h2 id=utils>Using configstore-utils</h2> -<p>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 <code>/vendor</code> can still be used.</p> - -<p>For forward-compatibility, ensure your implementation adheres to the -following guidelines:</p> - -<ol> -<li>New items use the default value when <em>only</em> the old version service -is available. Example: - -<pre class="devsite-click-to-copy"> -service = V1_1::IConfig::getService(); // null if V1_0 is installed -value = DEFAULT_VALUE; - if(service) { - value = service->v1_1API(DEFAULT_VALUE); - } -</pre> - -</li> - -<li>Client uses the earliest interface in which the ConfigStore item was -introduced. Example: - -<pre class="devsite-click-to-copy"> -V1_1::IConfig::getService()->v1_0API(); // NOT ALLOWED - -V1_0::IConfig::getService()->v1_0API(); // OK -</pre> -</li> -<li>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(): - -<pre class="devsite-click-to-copy"> -V1_0::IConfig::getService()->v1_0API(); -</pre> - -<p class=note><strong>Note:</strong> The -<a href="https://android-review.googlesource.com/c/393736/">current AOSP -implementation</a> satisfies this requirement.</p> -</li> -</ol> - -<p>When the access functions in <code>configstore-utils</code> 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 <code>configstore-utils</code> wherever possible.</p> - - </body> -</html> 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 @@ -<html devsite> - <head> - <title>Configstore HAL</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> - - -<p>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).</p> - -<p>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 -<a href="/devices/architecture/configstore/interface.html">HAL interface</a>, -<a href="/devices/architecture/configstore/service.html">service -implementation</a>, and -<a href="/devices/architecture/configstore/client.html">client-side usage</a>, -all using <code>surfaceflinger</code> as an example. For help with ConfigStore -interface classes, see -<a href="/devices/architecture/configstore/add-class-item.html">Adding Interface -Classes & Items</a>.</p> - -<h2 id=system-properties>Why not use system properties?</h2> -<p>We considered using system properties but found several fundamental issues, -including: </p> -<ul> -<li><strong>Length limits on values</strong>. System properties have -tight limits on the length of their values (92 bytes). In addition, as these -limits have been directly exposed to Android apps as C macros, increasing the -length can cause backwards-compatibility issues.</li> -<li><strong>No type support</strong>. All values are essentially strings, and -APIs simply parse the string into an <code>int</code> or <code>bool</code>. -Other compound data types (array, struct, etc.) should be encoded/decoded by -the clients (e.g. "aaa,bbb,ccc" can be decoded as an array of three strings). -</li> -<li><strong>Overwrites</strong>. Because read-only system properties are -implemented as write-once properties, vendors/ODMs that want to override -AOSP-defined read-only values must import their own read-only values prior to -AOSP-defined read-only values, which in turn results in vendor-defined -re-writable values being overridden by AOSP-defined values.</li> -<li><strong>Address space requirements</strong>. System properties take a -relatively large amount of address space in each process. System properties are -grouped in <code>prop_area</code> units with a fixed size of 128KB, all of which -is allocated to a process address space even if only a single system property in -it is being accessed. This can cause problems on 32-bit devices where address -space is precious.</li> -</ul> -<p>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.</p> - -<h2>ConfigStore HAL design</h2> -<p>The basic design is simple:</p> -<p><img src="../images/treble_configstore_design.png"></p> -<p><strong>Figure 1.</strong> ConfigStore HAL design</p> - -<ul> -<li>Describe build flags (currently used for conditionally compiling the -framework) in HIDL.</li> -<li>Vendors and OEMs provide SoC and device-specific values for build flags by -implementing the HAL service.</li> -<li>Modify the framework to use the HAL service to find the value of a -configuration item at runtime.</li> -</ul> - -<p>Configuration items currently referenced by the framework are included in a -versioned HIDL package (<code>android.hardware.configstore@1.0</code>). 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.</p> - -<h2 id=security>Security considerations</h2> -<p>Build flags defined in the same interface are affected by same SELinux -policy. If one or more build flags should have different SELinux policies, -<strong>they must be separated to another interface</strong>. This can require -major uprev of <code>android.hardware.configstore package</code> as the -separated interfaces are no longer backwards-compatible.</p> - -<aside class="note"><strong>Note:</strong> For details on Android 8.0 SELinux, -see <a href="/security/selinux/images/SELinux_Treble.pdf">SELinux for Android -8.0</a>.</aside> - - </body> -</html> 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 @@ -<html devsite> - <head> - <title>Creating the HAL Interface</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> - -<p>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 <code>.hal</code> file. Using HIDL for specifying configuration items -includes the following benefits:</p> -<ul> -<li>Versioned (to add new config items, vendors/OEMs must explicitly extend the -HAL)</li> -<li>Well-documented</li> -<li>Access control using SELinux</li> -<li>Sanity check for configuration items via -<a href="/devices/tech/test_infra/tradefed/fundamentals/vts">Vendor Test -Suite</a> (range check, inter-dependency check among items, etc.)</li> -<li>Auto-generated APIs in both C++ and Java</li> -</ul> - -<h2 id=identify-flags>Identifying build flags used by the framework</h2> -<p>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 <code>surfaceflinger</code>: -</p> -<ul> -<li><code>TARGET_USES_HWC2</code> (will be obsoleted)</li> -<li><code>TARGET_BOARD_PLATFORM</code></li> -<li><code>TARGET_DISABLE_TRIPLE_BUFFERING</code></li> -<li><code>TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS</code></li> -<li><code>NUM_FRAMEBUFFER_SURFACE_BUFFERS</code></li> -<li><code>TARGET_RUNNING_WITHOUT_SYNC_FRAMEWORK</code></li> -<li><code>VSYNC_EVENT_PHASE_OFFSET_NS</code></li> -<li><code>SF_VSYNC_EVENT_PHASE_OFFSET_NS</code> (will be obsoleted)</li> -<li><code>PRESENT_TIME_OFFSET_FROM_VSYNC_NS</code></li> -<li><code>MAX_VIRTUAL_DISPLAY_DIMENSION</code></li> -</ul> - -<h2 id="create-interface">Creating a HAL interface</h2> -<p>Build configs for a subsystem are accessed via a HAL interface, while -interfaces for giving configuration values are grouped in the HAL package <code>android.hardware.configstore</code> (currently at version 1.0). For example, to -create a HAL interface file for <code>surfaceflinger</code>, in -<strong><code>hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal</code></strong>: -</p> - -<pre class="devsite-click-to-copy"> -package android.hardware.configstore@1.0; - -interface ISurfaceFlingerConfigs { - // TO-BE-FILLED-BELOW -}; -</pre> - -<p>After creating the <code>.hal</code> file, run -<code>hardware/interfaces/update-makefiles.sh</code> to add the new -<code>.hal</code> file to the <code>Android.bp</code> and -<code>Android.mk</code> files.</p> - -<h2 id="add-functions">Adding functions for build flags</h2> -<p>For each build flag, add a new function to the interface. For example, in -<strong><code>hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal</code></strong>: -</p> - -<pre class="devsite-click-to-copy"> -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); -}; -</pre> - -<p>When adding a function:</p> -<ul> -<li><strong>Be concise with names</strong>. Avoid converting makefile variable -names into function names and keep in mind that <code>TARGET_</code> and -<code>BOARD_</code> prefixes are no longer necessary.</li> -<li><strong>Add comments</strong>. Help developers understand the purpose of the -config item, how it changes framework behavior, valid values, etc.</li> -</ul> -<p>Function return types can be -<code>Optional[Bool|String|Int32|UInt32|Int64|UInt64]</code>. Types are defined -in <code>types.hal</code> 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.</p> - -<pre class="devsite-click-to-copy"> -struct OptionalString { - bool specified; - string value; -}; -</pre> - -<p>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 <code>NumBuffers</code> 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., -<code>USE_DEFAULT</code>) for denoting if the value is/is not specified by -HAL.</p> - -<p>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).</p> - -<p>For example, an option for aggregating two build flags into a single struct -in <strong><code>hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal</code></strong> -is:</p> - -<pre class="devsite-click-to-copy"> - interface ISurfaceFlingerConfigs { - // other functions here - struct SyncConfigs { - OptionalInt64 vsyncEventPhaseoffsetNs; - OptionalInt64 presentTimeoffsetFromSyncNs; - }; - getSyncConfigs() generates (SyncConfigs ret); - // other functions here -}; -</pre> - -<h2 id=alternatives>Alternatives to a single HAL function</h2> - -<p>As an alternative to using a single HAL function for all build flags, the HAL -interface also provides simple functions such as <code>getBoolean(string -key)</code> and <code>getInteger(string key)</code>. The actual -<code>key=value</code> pairs are stored in separate files and the HAL service -provides values by reading/parsing those files.</p> - -<p>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.</p> - -<p class=note><strong>Note:</strong> When using simple functions, access -control is almost impossible as HAL cannot identify clients by itself.</p> - -<h2 id=single-multiple>Single vs. multiple interfaces</h2> -<p>The design of the HAL interface for configuration items presents two -choices:</p> - -<ol> -<li>Single interface that covers all configuration items</li> -<li>Multiple interfaces, each of which covers a set of related configuration -items</li> -</ol> -<p>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.</p> - -<p>Because of these issues, Android uses multiple interfaces with a single HAL -interface for a group of related configuration items. For example, -<code>ISurfaceflingerConfigs</code> for <code>surfaceflinger</code>-related -configuration items, <code>IBluetoothConfigs</code> for Bluetooth-related -configuration items, etc.</p> - - </body> -</html> 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 @@ -<html devsite> - <head> - <title>Implementing the Service</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 The Android Open Source Project - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> - -<p>To prepare for the HAL implementation, you can generate basic configstore -interface code then modify it to meet your needs.</p> - -<h2 id=generate-boilerplate>Generating interface code</h2> -<p>To generate boilerplate code for the interface, run <code>hidl-gen</code>. -For example, to generate code for <code>surfaceflinger</code>:</p> - -<pre class="devsite-terminal devsite-click-to-copy"> -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 -</pre> - -<p class="note"><strong>Note:</strong> Don't run <code>hidl-gen</code> with -<code>-Landroidbp-impl</code> as this generates <code>Android.bp</code>. The -module must be built with <code>Android.mk</code> to access build flags.</p> - -<h2 id=modify-androidmk>Modifying Android.mk</h2> -<p>Next, modify <code>Android.mk</code> file to add implementation file -(<code><modulename>Configs.cpp</code>) to <code>LOCAL_SRC_FILES</code> and -to map build flags into macro definitions. For example, you can modify -<code>surfaceflinger</code> in -<strong><code>hardware/interface/configstore/1.0/default/Android.mk</code></strong>: -</p> - -<pre class="devsite-click-to-copy"> -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 -</pre> - -<p>If <code>Android.mk</code> includes several <code>ifeq-endif</code> blocks, -consider moving your code into a new file (i.e., <code>surfaceflinger.mk</code>) -then include that file from <code>Android.mk</code>.</p> - -<h2 id=implement-functions>Implementing functions</h2> -<p>To fill the functions to implement the HAL, call back the -<code>_hidl_cb</code> function with different values (conditioned on build -flags). For example, you can fill the functions for <code>surfaceflinger</code> -in <strong><code>hardware/interfaces/configstore/1.0/default/SurfaceFlingerConfigs.cpp</code></strong>:</p> - -<pre class="devsite-click-to-copy"> -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 -} -</pre> - -<p>Ensure the implementation does not contain a function named -<code>HIDL_FETCH_<interface name></code> (e.g., -<code>HIDL_FETCH_ISurfaceFlingerConfigs</code>). This function is needed for -HIDL passthrough mode, which is unused (and prohibited) by -<code>configstore</code>. ConfigStore must always run in binderized mode.</p> - -<h2 id=register-service>Registering as a service</h2> -<p>Finally, register all interface implementations to the -<code>configstore</code> service. For example, you can register -<code>surfaceflinger</code> implementations in -<strong><code>hardware/interfaces/configstore/1.0/default/service.cpp</code></strong>: -</p> - -<pre class="devsite-click-to-copy"> -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(); -</pre> - -<h2 id=bootstrapping>Ensuring early access</h2> -<p>To ensure a framework module can get early access the HAL service, the config -HAL service should start as early as possible, just after -<code>hwservicemanager</code> is ready. As the config HAL service does not read -external files, it is expected to be ready quickly after it is launched.</p> - - </body> -</html> |