health: convert README to markdown format.

Test: none
Change-Id: Ic9503d43a5e69cee0deb901193a99154d68f67b0
Fixes: 112277698

3 files changed, 186 insertions, 162 deletions

diff --git a/health/2.0/README b/health/2.0/README
index 44e2828f0..42061c01a 100644..120000
--- a/health/2.0/README
+++ b/health/2.0/README
@@ -1,155 +1 @@
-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>
+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
index 000000000..5efc51a13
--- /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
index 1d5c27f35..c59b3f34d 100644
--- 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) {
     // ...
 }
+```