health: convert README to markdown format.

Test: none
Change-Id: Ic9503d43a5e69cee0deb901193a99154d68f67b0
Fixes: 112277698

diff --git a/health/2.0/README b/health/2.0/README
deleted file mode 100644 (file)
index 44e2828f0ded7d720402a239e28923f435b8ca26..0000000000000000000000000000000000000000
--- a/health/2.0/README
+++ /dev/null
@@ -1,155 +0,0 @@
-Upgrading from health@1.0 HAL
-
-0. Remove android.hardware.health@1.0* from PRODUCT_PACKAGES
-   in device/<manufacturer>/<device>/device.mk
-
-1. If the device does not have a vendor-specific libhealthd AND does not
-   implement storage-related APIs, just do the following:
-
-    PRODUCT_PACKAGES += android.hardware.health@2.0-service
-
-   Otherwise, continue to Step 2.
-
-2. Create directory
-   device/<manufacturer>/<device>/health
-
-3. Create device/<manufacturer>/<device>/health/Android.bp
-   (or equivalent device/<manufacturer>/<device>/health/Android.mk)
-
-cc_binary {
-    name: "android.hardware.health@2.0-service.<device>",
-    init_rc: ["android.hardware.health@2.0-service.<device>.rc"],
-    proprietary: true,
-    relative_install_path: "hw",
-    srcs: [
-        "HealthService.cpp",
-    ],
-
-    cflags: [
-        "-Wall",
-        "-Werror",
-    ],
-
-    static_libs: [
-        "android.hardware.health@2.0-impl",
-        "android.hardware.health@1.0-convert",
-        "libhealthservice",
-        "libbatterymonitor",
-    ],
-
-    shared_libs: [
-        "libbase",
-        "libcutils",
-        "libhidlbase",
-        "libhidltransport",
-        "libutils",
-        "android.hardware.health@2.0",
-    ],
-
-    header_libs: ["libhealthd_headers"],
-
-    overrides: [
-        "healthd",
-    ],
-}
-
-    3.1 (recommended) To remove healthd from the build, keep "overrides" section.
-    3.2 To keep healthd in the build, remove "overrides" section.
-
-4. Create device/<manufacturer>/<device>/health/android.hardware.health@2.0-service.<device>.rc
-
-service vendor.health-hal-2-0 /vendor/bin/hw/android.hardware.health@2.0-service.<device>
-    class hal
-    user system
-    group system
-    file /dev/kmsg w
-
-5. Create device/<manufacturer>/<device>/health/HealthService.cpp:
-
-#include <health2/service.h>
-int main() { return health_service_main(); }
-
-6. libhealthd dependency:
-
-6.1 If the device has a vendor-specific libhealthd.<soc>, add it to static_libs.
-
-6.2 If the device does not have a vendor-specific libhealthd, add the following
-    lines to HealthService.cpp:
-
-#include <healthd/healthd.h>
-void healthd_board_init(struct healthd_config*) {}
-
-int healthd_board_battery_update(struct android::BatteryProperties*) {
-    // return 0 to log periodic polled battery status to kernel log
-    return 0;
-}
-
-7. Storage related APIs:
-
-7.1 If the device does not implement IHealth.getDiskStats and
-    IHealth.getStorageInfo, add libstoragehealthdefault to static_libs.
-
-7.2 If the device implements one of these two APIs, add and implement the
-    following functions in HealthService.cpp:
-
-void get_storage_info(std::vector<struct StorageInfo>& info) {
-    // ...
-}
-void get_disk_stats(std::vector<struct DiskStats>& stats) {
-    // ...
-}
-
-8. Update necessary SELinux permissions. For example,
-
-# device/<manufacturer>/<device>/sepolicy/vendor/file_contexts
-/vendor/bin/hw/android\.hardware\.health@2\.0-service.<device> u:object_r:hal_health_default_exec:s0
-
-# device/<manufacturer>/<device>/sepolicy/vendor/hal_health_default.te
-# Add device specific permissions to hal_health_default domain, especially
-# if Step 6.1 or Step 7.2 is done.
-
-9. Implementing health HAL in recovery. The health HAL is used for battery
-status checks during OTA for non-A/B devices. If the health HAL is not
-implemented in recovery, is_battery_ok() will always return true.
-
-9.1 If the device does not have a vendor-specific libhealthd, nothing needs to
-be done. A "backup" implementation is provided in
-android.hardware.health@2.0-impl-default, which is always installed to recovery
-image by default.
-
-9.2 If the device do have a vendor-specific libhealthd, implement the following
-module and include it in PRODUCT_PACKAGES (replace <device> with appropriate
-strings):
-
-// Android.bp
-cc_library_shared {
-    name: "android.hardware.health@2.0-impl-<device>",
-    recovery_available: true,
-    relative_install_path: "hw",
-    static_libs: [
-        "android.hardware.health@2.0-impl",
-        "libhealthd.<device>"
-        // Include the following if Step 7.1, otherwise do Step 7.2
-        "libhealthstoragedefault",
-    ],
-    srcs: [
-        "HealthImpl.cpp",
-    ],
-    overrides: [
-        "android.hardware.health@2.0-impl-default",
-    ],
-}
-
-// HealthImpl.cpp
-#include <health2/Health.h>
-#include <healthd/healthd.h>
-using android::hardware::health::V2_0::IHealth;
-using android::hardware::health::V2_0::implementation::Health;
-extern "C" IHealth* HIDL_FETCH_IHealth(const char* name) {
-    const static std::string providedInstance{"default"};
-    if (providedInstance != name) return nullptr;
-    return Health::initInstance(&gHealthdConfig).get();
-}
-
-# device.mk
-PRODUCT_PACKAGES += android.hardware.health@2.0-impl-<device>

diff --git a/health/2.0/README b/health/2.0/README
new file mode 120000 (symlink)
index 0000000000000000000000000000000000000000..42061c01a1c70097d1e4579f29a5adf40abdec95
--- /dev/null
+++ b/health/2.0/README
@@ -0,0 +1 @@
+README.md
\ No newline at end of file

diff --git a/health/2.0/README.md b/health/2.0/README.md
new file mode 100644 (file)
index 0000000..5efc51a
--- /dev/null
+++ b/health/2.0/README.md
@@ -0,0 +1,176 @@
+# Upgrading from Health 1.0 HAL
+
+1. Remove `android.hardware.health@1.0*` from `PRODUCT_PACKAGES`
+   in `device/<manufacturer>/<device>/device.mk`
+
+1. If the device does not have a vendor-specific `libhealthd` AND does not
+   implement storage-related APIs, just do the following:
+
+   ```mk
+   PRODUCT_PACKAGES += android.hardware.health@2.0-service
+   ```
+
+   Otherwise, continue to the next step.
+
+1. Create directory
+   `device/<manufacturer>/<device>/health`
+
+1. Create `device/<manufacturer>/<device>/health/Android.bp`
+   (or equivalent `device/<manufacturer>/<device>/health/Android.mk`)
+
+    ```bp
+    cc_binary {
+        name: "android.hardware.health@2.0-service.<device>",
+        init_rc: ["android.hardware.health@2.0-service.<device>.rc"],
+        proprietary: true,
+        relative_install_path: "hw",
+        srcs: [
+            "HealthService.cpp",
+        ],
+
+        cflags: [
+            "-Wall",
+            "-Werror",
+        ],
+
+        static_libs: [
+            "android.hardware.health@2.0-impl",
+            "android.hardware.health@1.0-convert",
+            "libhealthservice",
+            "libbatterymonitor",
+        ],
+
+        shared_libs: [
+            "libbase",
+            "libcutils",
+            "libhidlbase",
+            "libhidltransport",
+            "libutils",
+            "android.hardware.health@2.0",
+        ],
+
+        header_libs: ["libhealthd_headers"],
+
+        overrides: [
+            "healthd",
+        ],
+    }
+    ```
+
+    1. (recommended) To remove `healthd` from the build, keep "overrides" section.
+    1. To keep `healthd` in the build, remove "overrides" section.
+
+1. Create `device/<manufacturer>/<device>/health/android.hardware.health@2.0-service.<device>.rc`
+
+    ```rc
+    service vendor.health-hal-2-0 /vendor/bin/hw/android.hardware.health@2.0-service.<device>
+        class hal
+        user system
+        group system
+        file /dev/kmsg w
+    ```
+
+1. Create `device/<manufacturer>/<device>/health/HealthService.cpp`:
+
+    ```c++
+    #include <health2/service.h>
+    int main() { return health_service_main(); }
+    ```
+
+1. `libhealthd` dependency:
+
+    1. If the device has a vendor-specific `libhealthd.<soc>`, add it to static_libs.
+
+    1. If the device does not have a vendor-specific `libhealthd`, add the following
+        lines to `HealthService.cpp`:
+
+        ```c++
+        #include <healthd/healthd.h>
+        void healthd_board_init(struct healthd_config*) {}
+
+        int healthd_board_battery_update(struct android::BatteryProperties*) {
+            // return 0 to log periodic polled battery status to kernel log
+            return 0;
+        }
+        ```
+
+1. Storage related APIs:
+
+    1. If the device does not implement `IHealth.getDiskStats` and
+        `IHealth.getStorageInfo`, add `libstoragehealthdefault` to `static_libs`.
+
+    1. If the device implements one of these two APIs, add and implement the
+        following functions in `HealthService.cpp`:
+
+        ```c++
+        void get_storage_info(std::vector<struct StorageInfo>& info) {
+            // ...
+        }
+        void get_disk_stats(std::vector<struct DiskStats>& stats) {
+            // ...
+        }
+        ```
+
+1. Update necessary SELinux permissions. For example,
+
+    ```
+    # device/<manufacturer>/<device>/sepolicy/vendor/file_contexts
+    /vendor/bin/hw/android\.hardware\.health@2\.0-service.<device> u:object_r:hal_health_default_exec:s0
+
+    # device/<manufacturer>/<device>/sepolicy/vendor/hal_health_default.te
+    # Add device specific permissions to hal_health_default domain, especially
+    # if a device-specific libhealthd is used and/or device-specific storage related
+    # APIs are implemented.
+    ```
+
+1. Implementing health HAL in recovery. The health HAL is used for battery
+status checks during OTA for non-A/B devices. If the health HAL is not
+implemented in recovery, `is_battery_ok()` will always return `true`.
+
+    1. If the device does not have a vendor-specific `libhealthd`, nothing needs to
+    be done. A "backup" implementation is provided in
+    `android.hardware.health@2.0-impl-default`, which is always installed to recovery
+    image by default.
+
+    1. If the device does have a vendor-specific `libhealthd`, implement the following
+    module and include it in `PRODUCT_PACKAGES` (replace `<device>` with appropriate
+    strings):
+
+    ```bp
+    // Android.bp
+    cc_library_shared {
+        name: "android.hardware.health@2.0-impl-<device>",
+        recovery_available: true,
+        relative_install_path: "hw",
+        static_libs: [
+            "android.hardware.health@2.0-impl",
+            "libhealthd.<device>"
+            // Include the following or implement device-specific storage APIs
+            "libhealthstoragedefault",
+        ],
+        srcs: [
+            "HealthImpl.cpp",
+        ],
+        overrides: [
+            "android.hardware.health@2.0-impl-default",
+        ],
+    }
+    ```
+
+    ```c++
+    // HealthImpl.cpp
+    #include <health2/Health.h>
+    #include <healthd/healthd.h>
+    using android::hardware::health::V2_0::IHealth;
+    using android::hardware::health::V2_0::implementation::Health;
+    extern "C" IHealth* HIDL_FETCH_IHealth(const char* name) {
+        const static std::string providedInstance{"default"};
+        if (providedInstance != name) return nullptr;
+        return Health::initInstance(&gHealthdConfig).get();
+    }
+    ```
+
+    ```mk
+    # device.mk
+    PRODUCT_PACKAGES += android.hardware.health@2.0-impl-<device>
+    ```

diff --git a/health/2.0/utils/README b/health/2.0/utils/README.md
similarity index 68%
rename from health/2.0/utils/README
rename to health/2.0/utils/README.md
index 1d5c27f35fa8fa0804e8ee981d95f0e6975004a6..c59b3f34df2b4465450e7292ce1f5eaefa4e9dfb 100644 (file)
--- a/health/2.0/utils/README
+++ b/health/2.0/utils/README.md
@@ -1,28 +1,30 @@
-* libhealthhalutils
+# libhealthhalutils
 
 A convenience library for (hwbinder) clients of health HAL to choose between
 the "default" instance (served by vendor service) or "backup" instance (served
 by healthd). C++ clients of health HAL should use this library instead of
-calling IHealth::getService() directly.
+calling `IHealth::getService()` directly.
 
-Its Java equivalent can be found in BatteryService.HealthServiceWrapper.
+Its Java equivalent can be found in `BatteryService.HealthServiceWrapper`.
 
-* libhealthservice
+# libhealthservice
 
 Common code for all (hwbinder) services of the health HAL, including healthd and
-vendor health service android.hardware.health@2.0-service(.<vendor>). main() in
-those binaries calls health_service_main() directly.
+vendor health service `android.hardware.health@2.0-service(.<vendor>)`. `main()` in
+those binaries calls `health_service_main()` directly.
 
-* libhealthstoragedefault
+# libhealthstoragedefault
 
 Default implementation for storage related APIs for (hwbinder) services of the
 health HAL. If an implementation of the health HAL do not wish to provide any
 storage info, include this library. Otherwise, it should implement the following
 two functions:
 
+```c++
 void get_storage_info(std::vector<struct StorageInfo>& info) {
     // ...
 }
 void get_disk_stats(std::vector<struct DiskStats>& stats) {
     // ...
 }
+```