Split the procedure for better readability

adglkh · Dec 3, 2024 · 4471d17 · 4471d17
1 parent f61f383
commit 4471d17
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 102 deletions.
diff --git a/explanation/aaos.md b/explanation/aaos.md
@@ -13,12 +13,7 @@ Until the 1.24.0 release, if you created your own VHAL implementation by followi
 
 However, if a third-party VHAL implementation is loaded during Android runtime, on the Anbox Cloud Dashboard, some vehicle property values may still not be accessible while others may not be editable on the Anbox Cloud dashboard, due to [permission controls](https://source.android.com/docs/automotive/vhal/previous/properties#vehicle-props) that categorise vehicle properties as read-only, write-only, or read-write.
 
-Anbox Cloud offers an [Anbox-specific VHAL HIDL interface](https://github.com/canonical/vendor_canonical_interfaces). By implementing this HIDL, the VHAL implementation allows the Anbox VHAL adapter to
-
-- modify non-writable vehicle property values.
-- access non-readable vehicle property values.
-
-without encountering permission issues.
+Anbox Cloud offers an [Anbox-specific VHAL HIDL interface](https://github.com/canonical/vendor_canonical_interfaces). By using this HIDL, the VHAL implementation allows the Anbox VHAL adapter to modify non-writable and access non-readable vehicle property values without encountering permission issues. See the {ref}`how-to guide <howto-integrate-hidl>` on instructions for setting this up with your VHAL implementation.
 
 ## Related topics
 

diff --git a/howto/android/custom-vhal.md b/howto/android/custom-vhal.md
@@ -1,5 +1,5 @@
 (howto-replace-anbox-vhal)=
-# Customise the Anbox VHAL
+# How to replace the Anbox VHAL with your custom implementation
 
 *since 1.22.0*
 
@@ -136,99 +136,7 @@ addons:
   - custom-vhal
 ```
 
-## Integrate Anbox VHAL interface
-
-To use and integrate the [Anbox VHAL interface](https://github.com/canonical/vendor_canonical_interfaces/tree/main/vehicle) into a VHAL implementation, the implementation must be built against Android 14. Before proceeding, ensure you have downloaded the Android 14 source. If you haven't done so yet, please follow the [official documentation](https://source.android.com/docs/setup/download) to set it up.
-
-1. Add a new remote definition named `github` to `.repo/manifests/manifest.xml` file.
-
-       <remote name="aosp"
-          fetch=".."
-          review="https://android-review.googlesource.com/" />
-
-       <remote name="github"
-          fetch="https://github.com/canonical/" />
-
-1. Add a new project named `vendor_canonical_interfaces` to the newly added remote and set it to use the `main` branch.
-
-       <project path="vendor/canonical/interfaces"
-                name="vendor_canonical_interfaces"
-                remote="github"
-                revision="main" />
-
-1. Sync the project with the remote.
-
-        repo sync vendor_canonical_interfaces
-
-1. In the VHAL implementation, create a VHAL manifest fragment named `[email protected]`.
-
-       <manifest version="1.0" type="device">
-           <hal format="hidl">
-               <name>vendor.canonical.interfaces.vehicle</name>
-               <transport>hwbinder</transport>
-               <fqname>@1.0::IVehicle/default</fqname>
-           </hal>
-       </manifest>
-
-   Place the VHAL manifest fragment file in the same folder as the `Android.bp` file that declares the VHAL service, and include the Anbox VHAL manifest fragment in the VHAL service declaration within the `Android.bp` file. Additionally, add the HIDL module as a shared library that the VHAL service links to in the `Android.bp` file.
-
-
-       cc_binary {
-           name: "vendor.<company>.vehicle@<version>-service",
-           vintf_fragments: [
-               ...
-               "[email protected]",
-           ],
-           shared_libs: [
-               ...
-               "[email protected]",
-           ],
-           ...
-       }
-
-1. Take the [example](https://github.com/canonical/vendor_canonical_interfaces/tree/main/vehicle/1.0/default) as a reference, which implements the `IVehicle` interface.
-
-        Return<void> VHalService::get(
-            const VehiclePropValue& requestedPropValue, IVehicle::get_cb _hidl_cb) {
-          uid_t uid = android::IPCThreadState::self()->getCallingUid();
-          if (uid != AID_VEHICLE_NETWORK) {
-            _hidl_cb(StatusCode::ACCESS_DENIED, kEmptyValue);
-            return Void();
-          }
-
-          // NOTE: a VHAL implementation must allow access to non-readable vehicle properties.
-          return Void();
-        }
-
-        Return<StatusCode> VHalService::set(const VehiclePropValue& value) {
-          uid_t uid = android::IPCThreadState::self()->getCallingUid();
-          if (uid != AID_VEHICLE_NETWORK)
-            return StatusCode::ACCESS_DENIED;
-
-          // NOTE: a VHAL implementation must allow modification of non-writable vehicle properties.
-          return StatusCode::NOT_AVAILABLE;
-        }
-
-   Please note that each function must implement a security mechanism to restrict access to vehicle properties to the authorised `AID_VEHICLE_NETWORK` process.
-
-1. Instantiate the VHAL service that implements the interface and register it as a binder service in the VHAL implementation.
-
-        #include <VHalService.h>
-
-        int main(int /* argc */, char* /* argv */[]) {
-            ...
-            ...
-            configureRpcThreadpool(4, true);
-            auto vendor_vhal_service = std::make_unique<VHalService>();
-            status_t status = vendor_vhal_service->registerAsService();
-            if (status != OK) {
-                return 1;
-            }
-            joinRpcThreadpool();
-            return 1;
-        }
-
-After implementing the Anbox HIDL interfaces and integrating them into your VHAL implementation, [build](https://source.android.com/docs/setup/build/building) the VHAL module. Then follow the instructions for [customising the Anbox VHAL](https://documentation.ubuntu.com/anbox-cloud/en/latest/howto/android/custom-vhal/) and load it as an addon during the Android runtime. Once registered, the service can be accessed by the Anbox VHAL adapter.
+If you would like to further your custom implementation and integrate the Anbox HIDL interface with your custom VHAL implementation, follow the instructions in {ref}`howto-integrate-hidl`.
 
 ## Related topics
 

diff --git a/howto/android/integrate-hidl.md b/howto/android/integrate-hidl.md
@@ -0,0 +1,110 @@
+(howto-integrate-hidl)=
+# How to integrate Anbox HIDL interface with a custom VHAL implementation
+
+The Anbox HIDL interface is used in the default Anbox VHAL implementation. This document guides you through the steps for setting up and integrating the Anbox HIDL interface with your custom VHAL implementation.
+
+Due to the technical requirements of this procedure, this document assumes familiarity with AOSP development on your part. If you are looking for a simpler solution to have a custom VHAL implementation, such as loading an existing VHAL implementation and making it work with Android runtime, see {ref}`replace the Anbox VHAL <howto-replace-anbox-vhal>`.
+
+## Prerequisites
+
+To use and integrate the [Anbox VHAL interface](https://github.com/canonical/vendor_canonical_interfaces/tree/main/vehicle) with a VHAL implementation, the VHAL implementation must be built against Android 14. Hence, you should have downloaded the Android 14 source to perform the following steps. If you don't have this ready, follow the instructions in the [official documentation](https://source.android.com/docs/setup/download).
+
+## Steps
+
+1. Add a new remote definition named `github` to `.repo/manifests/manifest.xml` file.
+
+    ```xml
+       <remote name="aosp"
+          fetch=".."
+          review="https://android-review.googlesource.com/" />
+
+       <remote name="github"
+          fetch="https://github.com/canonical/" />
+    ```
+
+1. Add a new project named `vendor_canonical_interfaces` to the newly added remote and set it to use the `main` branch.
+
+    ```xml
+       <project path="vendor/canonical/interfaces"
+                name="vendor_canonical_interfaces"
+                remote="github"
+                revision="main" />
+    ```
+
+1. Sync the project with the remote.
+
+        repo sync vendor_canonical_interfaces
+
+1. In the VHAL implementation, create a VHAL manifest fragment named `[email protected]`.
+
+    ```xml
+       <manifest version="1.0" type="device">
+           <hal format="hidl">
+               <name>vendor.canonical.interfaces.vehicle</name>
+               <transport>hwbinder</transport>
+               <fqname>@1.0::IVehicle/default</fqname>
+           </hal>
+       </manifest>
+    ```
+
+   Place the VHAL manifest fragment file in the same folder as the `Android.bp` file that declares the VHAL service, and include the Anbox VHAL manifest fragment in the VHAL service declaration within the `Android.bp` file. Additionally, add the HIDL module as a shared library that the VHAL service links to in the `Android.bp` file.
+
+
+       cc_binary {
+           name: "vendor.<company>.vehicle@<version>-service",
+           vintf_fragments: [
+               ...
+               "[email protected]",
+           ],
+           shared_libs: [
+               ...
+               "[email protected]",
+           ],
+           ...
+       }
+
+1. Let's consider an [example](https://github.com/canonical/vendor_canonical_interfaces/tree/main/vehicle/1.0/default) that implements the `IVehicle` interface.
+
+        Return<void> VHalService::get(
+            const VehiclePropValue& requestedPropValue, IVehicle::get_cb _hidl_cb) {
+          uid_t uid = android::IPCThreadState::self()->getCallingUid();
+          if (uid != AID_VEHICLE_NETWORK) {
+            _hidl_cb(StatusCode::ACCESS_DENIED, kEmptyValue);
+            return Void();
+          }
+
+          // NOTE: a VHAL implementation must allow access to non-readable vehicle properties.
+          return Void();
+        }
+
+        Return<StatusCode> VHalService::set(const VehiclePropValue& value) {
+          uid_t uid = android::IPCThreadState::self()->getCallingUid();
+          if (uid != AID_VEHICLE_NETWORK)
+            return StatusCode::ACCESS_DENIED;
+
+          // NOTE: a VHAL implementation must allow modification of non-writable vehicle properties.
+          return StatusCode::NOT_AVAILABLE;
+        }
+
+   Note that you must implement your own access control methods to vehicle properties to ensure secure access. When implementing, this translates to each function having a security mechanism that disallows access to vehicle properties for anything except the authorised `AID_VEHICLE_NETWORK` process.
+
+1. Instantiate the VHAL service that implements the interface and register it as a binder service in the VHAL implementation.
+
+        #include <VHalService.h>
+
+        int main(int /* argc */, char* /* argv */[]) {
+            ...
+            ...
+            configureRpcThreadpool(4, true);
+            auto vendor_vhal_service = std::make_unique<VHalService>();
+            status_t status = vendor_vhal_service->registerAsService();
+            if (status != OK) {
+                return 1;
+            }
+            joinRpcThreadpool();
+            return 1;
+        }
+
+Now, [build](https://source.android.com/docs/setup/build/building) the VHAL module.
+
+Follow the instructions in {ref}`replacing the Anbox VHAL <howto-replace-anbox-vhal>` and load it as an addon during the Android runtime. Once registered, the service can be accessed by the Anbox VHAL adapter.
diff --git a/howto/android/landing.md b/howto/android/landing.md
@@ -7,7 +7,8 @@ The following guides in this section describe how to work with Android in Anbox
 :titlesonly:
 
 Access Android instance <access-instance>
-Debug graphics with Renderdoc <debug-graphics-renderdoc>
 Create a virtual Android device <create-virtual-device>
-Customise the Anbox VHAL <custom-vhal>
+Debug graphics with Renderdoc <debug-graphics-renderdoc>
+Integrate Anbox HIDL interface <integrate-hidl>
+Replace the Anbox VHAL <custom-vhal>
 ```