Docs: Changes to source.android.com

  - 207940242 One more fix: add header for Television Requirements. by Gina Dimino <gdimino@google.com>
  - 207936055 Update health README link. by Android Partner Docs <noreply@android.com>
  - 207929938 Errata run for Android 9 CDD. by Gina Dimino <gdimino@google.com>
  - 207897850 Fix typos in Develop and Configure index pages by Kenneth Lau <kennethlau@google.com>
  - 207813977 Devsite localized content from translation request 958913. by Android Partner Docs <noreply@android.com>
  - 207813949 Devsite localized content from translation request 953118. by Android Partner Docs <noreply@android.com>
  - 207813941 Devsite localized content from translation request 961934. by Android Partner Docs <noreply@android.com>
  - 207813934 Devsite localized content from translation request 552632. by Android Partner Docs <noreply@android.com>
  - 207813463 Update line numbers in links by Kenneth Lau <kennethlau@google.com>
  - 207796341 Fixing the URL for the CDD link in versions file. by Gina Dimino <gdimino@google.com>
  - 207779392 Fix incorrect link by Kenneth Lau <kennethlau@google.com>
  - 207777680 Update build numbers for 2018/08 releases by Android Partner Docs <noreply@android.com>
  - 207775888 Update links to AOSP by Kenneth Lau <kennethlau@google.com>
  - 207769948 Update links to AOSP by Kenneth Lau <kennethlau@google.com>
  - 207763826 Clarify system for HIDL passthrough loading. by Android Partner Docs <noreply@android.com>
  - 207733156 Fixing malformed links in html for kernel patches, adding... by Heidi von Markham <hvm@google.com>
  - 207650104 Remove link by Heidi von Markham <hvm@google.com>
  - 207640627 Tags for Android P. by Android Partner Docs <noreply@android.com>
  - 207626815 Making link absolute by Clay Murphy <claym@google.com>
  - 207611166 Add Background Restrictions into Release Notes. by Christina Nguyen <cqn@google.com>
  - 207606267 Fixing unclosed tag, reformatting for clarity by Heidi von Markham <hvm@google.com>
  - 207604244 Fix malformed link by Clay Murphy <claym@google.com>
  - 207598416 adding subscript by Heidi von Markham <hvm@google.com>
  - 207595049 Fix link in section 3.5.1. by Gina Dimino <gdimino@google.com>
  - 207590813 Fix broken link due to file path change by Christina Nguyen <cqn@google.com>
  - 207588930 Update Power nav to include changes to mgmt page (broken ... by Christina Nguyen <cqn@google.com>
  - 207588102 Separate out the Power Management article into "Applicati... by Christina Nguyen <cqn@google.com>
  - 207583000 Fix broken links in HAL interface section by Kenneth Lau <kennethlau@google.com>
  - 207582699 Put index files in place as redirects are not taking hold by Clay Murphy <claym@google.com>
  - 207575443 P release notes: fix bad links, remove "P release" by Mark Hecomovich <mheco@google.com>
  - 207574657 Fix link typo from release notes to Carrier ID page by Christina Nguyen <cqn@google.com>
  - 207559561 Integrate SAC next branch into mainline for Android P/9 p... by Mark Hecomovich <mheco@google.com>
  - 207559252 Publish links to July localized versions within Japanese ... by Clay Murphy <claym@google.com>
  - 207122872 Devsite localized content from translation request 958912. by Android Partner Docs <noreply@android.com>
  - 207122854 Devsite localized content from translation request 961384. by Android Partner Docs <noreply@android.com>
  - 207007888 Add blurb about the SystemUpdateSampler app on SAC so use... by Christina Nguyen <cqn@google.com>
  - 206862073 Update Camera HAL testing page by Kenneth Lau <kennethlau@google.com>
  - 206805870 Devsite localized content from translation request 960240. by Android Partner Docs <noreply@android.com>
  - 206805861 Devsite localized content from translation request 954945. by Android Partner Docs <noreply@android.com>

PiperOrigin-RevId: 207940242
Change-Id: I3dee204c744e2e6062ac56810b88aefabf84636a

1 files changed, 302 insertions, 0 deletions

diff --git a/en/devices/architecture/hidl/memoryblock.md b/en/devices/architecture/hidl/memoryblock.md
new file mode 100644
index 00000000..de2b3493
--- /dev/null
+++ b/en/devices/architecture/hidl/memoryblock.md
@@ -0,0 +1,302 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+{% include "_versions.html" %}
+
+<!--
+  Copyright 2018 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.
+-->
+
+# HIDL Memory Block
+
+The HIDL MemoryBlock is an abstract layer built on `hidl_memory`, `HIDL
+@1.0::IAllocator`, and `HIDL @1.0::IMapper`. It is designed for HIDL services
+that have multiple memory blocks to share a single memory heap.
+
+
+## Performance improvements
+
+Using MemoryBlock in applications can significantly reduce the number of
+`mmap`/`munmap` and user space segmentation faults, thus improving performance.
+For example:
+
+*   Using per `hidl_memory` for each buffer allocation averages 238 us/1 allocation.
+*   Using `MemoryBlock` and sharing a single `hidl_memory` averages 2.82 us/1 allocation.
+
+
+## Architecture
+
+The HIDL MemoryBlock architecture includes HIDL services with multiple memory
+blocks sharing a single memory heap:
+
+![HIDL MemoryBlock](/devices/architecture/images/hidl_memoryblock_arch.png)
+
+**Figure 1.** HIDL MemoryBlock architecture
+
+
+## Normal usage
+
+This section provides an example of using MemoryBlock by first declaring the HAL
+then implementing the HAL.
+
+
+### Declaring the HAL
+
+For the following example IFoo HAL:
+
+```
+import android.hidl.memory.block@1.0::MemoryBlock;
+
+interface IFoo {
+    getSome() generates(MemoryBlock block);
+    giveBack(MemoryBlock block);
+};
+```
+
+The `Android.bp` is as follows:
+
+```
+hidl_interface {
+    ...
+    srcs: [
+        "IFoo.hal",
+    ],
+    interfaces: [
+        "android.hidl.memory.block@1.0",
+        ...
+};
+```
+
+### Implementing the HAL
+
+To implement the example HAL:
+
+1.  Get the `hidl_memory` (for details, refer to [HIDL C++](/devices/architecture/hidl-cpp/)).
+
+
+    ```
+    #include <android/hidl/allocator/1.0/IAllocator.h>
+
+    using ::android::hidl::allocator::V1_0::IAllocator;
+    using ::android::hardware::hidl_memory;
+    ...
+      sp<IAllocator> allocator = IAllocator::getService("ashmem");
+      allocator->allocate(2048, [&](bool success, const hidl_memory& mem)
+      {
+            if (!success) { /* error */ }
+            // you can now use the hidl_memory object 'mem' or pass it
+      }));
+    ```
+
+1.  Make a `HidlMemoryDealer` with the acquired `hidl_memory`:
+
+    ```
+    #include <hidlmemory/HidlMemoryDealer.h>
+
+    using ::android::hardware::HidlMemoryDealer
+    /* The mem argument is acquired in the Step1, returned by the ashmemAllocator->allocate */
+    sp<HidlMemoryDealer> memory_dealer = HidlMemoryDealer::getInstance(mem);
+    ```
+
+1.  Allocate `MemoryBlock`, which is a struct defined with HIDL.
+
+    Example `MemoryBlock`:
+
+    ```
+    struct MemoryBlock {
+    IMemoryToken token;
+    uint64_t size;
+    uint64_t offset;
+    };
+    ```
+
+    Example using the `MemoryDealer` to allocate a `MemoryBlock`:
+
+
+    ```
+    #include <android/hidl/memory/block/1.0/types.h>
+
+    using ::android::hidl::memory::block::V1_0::MemoryBlock;
+
+    Return<void> Foo::getSome(getSome_cb _hidl_cb) {
+        MemoryBlock block = memory_dealer->allocate(1024);
+        if(HidlMemoryDealer::isOk(block)){
+            _hidl_cb(block);
+        ...
+    ```
+
+1.  Deallocate `MemoryBlock`:
+
+    ```
+    Return<void> Foo::giveBack(const MemoryBlock& block) {
+        memory_dealer->deallocate(block.offset);
+    ...
+    ```
+
+1.  Manipulate the data:
+
+    ```
+    #include <hidlmemory/mapping.h>
+    #include <android/hidl/memory/1.0/IMemory.h>
+
+    using ::android::hidl::memory::V1_0::IMemory;
+
+    sp<IMemory> memory = mapMemory(block);
+    uint8_t* data =
+
+    static_cast<uint8_t*>(static_cast<void*>(memory->getPointer()));
+    ```
+
+1.  Config `Android.bp`:
+
+    ```
+    shared_libs: [
+            "android.hidl.memory@1.0",
+
+            "android.hidl.memory.block@1.0"
+
+            "android.hidl.memory.token@1.0",
+            "libhidlbase",
+            "libhidlmemory",
+    ```
+
+1.  Review the flow to determine if you need to `lockMemory`. 
+
+    Normally, the MemoryBlock uses reference count to maintain the shared
+    `hidl_memory` which is `mmap()`-ed the first time one of its `MemoryBlock`s gets
+    mapped and is `munmap()`-ed when nothing refers to it. To keep the `hidl_memory`
+    always mapped, you can use `lockMemory`, a RAII style object that keeps the
+    corresponding `hidl_memory` mapped throughout the lock life cycle. Example:
+
+    ```
+    #include <hidlmemory/mapping.h>
+
+    sp<RefBase> lockMemory(const sp<IMemoryToken> key);
+    ```
+
+## Extended usage
+
+This section provides details about the extended usage of `MemoryBlock`.
+
+
+### Using reference count to manage Memoryblock
+
+In most situations, the most efficient way to use MemoryBlock is to explicitly
+allocate/deallocate. However, in complicated applications using reference count
+for garbage collection might be a better idea. To have reference count on
+MemoryBlock, you can bind MemoryBlock with a binder object, which helps to count
+the references and deallocate the MemoryBlock when the count decreases to zero.
+
+
+### Declaring the HAL
+
+When declaring the HAL, describe a HIDL struct that contains a MemoryBlock and a
+IBase:
+
+
+```
+import android.hidl.memory.block@1.0::MemoryBlock;
+
+struct MemoryBlockAllocation {
+    MemoryBlock block;
+    IBase refcnt;
+};
+```
+
+Use the `MemoryBlockAllocation` to replace `MemoryBlock` and remove the method
+to give back the `MemoryBlock`. It will be deallocated by reference counting
+with the `MemoryBlockAllocation`. Example:
+
+
+```
+interface IFoo {
+    allocateSome() generates(MemoryBlockAllocation allocation);
+};
+```
+
+### Implementing the HAL
+
+Example of the service side implementation of the HAL:
+
+
+```
+class MemoryBlockRefCnt: public virtual IBase {
+   MemoryBlockRefCnt(uint64_t offset, sp<MemoryDealer> dealer)
+     : mOffset(offset), mDealer(dealer) {}
+   ~MemoryBlockRefCnt() {
+       mDealer->deallocate(mOffset);
+   }
+ private:
+   uint64_t mOffset;
+   sp<MemoryDealer> mDealer;
+};
+
+Return<void> Foo::allocateSome(allocateSome_cb _hidl_cb) {
+    MemoryBlockAllocation allocation;
+    allocation.block = memory_dealer->allocate(1024);
+    if(HidlMemoryDealer::isOk(block)){
+        allocation.refcnt= new MemoryBlockRefCnt(...);
+        _hidl_cb(allocation);
+```
+
+
+Example of the client side implementation of the HAL:
+
+
+```
+ifoo->allocateSome([&](const MemoryBlockAllocation& allocation){
+    ...
+);
+```
+
+### Attaching/retrieving metadata
+
+Some applications need additional data to bind with the allocated `MemoryBlock`.
+You can append/retrieve metadata using two methods:
+
+
+*   If the application accesses the metadata as often as the block itself,
+    append the metadata and pass them all in a struct. Example:
+
+    ```
+    import android.hidl.memory.block@1.0::MemoryBlock;
+
+    struct MemoryBlockWithMetaData{
+        MemoryBlock block;
+        MetaDataStruct metaData;
+    };
+    ```
+
+*   If the application accesses the metadata much less frequently than the
+    block, it is more efficient to pass the metadata passively with an
+    interface. Example:
+
+    ```
+    import android.hidl.memory.block@1.0::MemoryBlock;
+
+    struct MemoryBlockWithMetaData{
+        MemoryBlock block;
+        IMetaData metaData;
+    };
+    ```
+
+    Next, bind the metadata with the MemoryBlock using the Memory Dealer. Example:
+
+    ```
+    MemoryBlockWithMetaData memory_block;
+    memory_block.block = dealer->allocate(size);
+    if(HidlMemoryDealer::isOk(block)){
+        memory_block.metaData = new MetaData(...);
+    ```