feat: create documentation about the HAL example

.gitignore

@@ -0,0 +1,2 @@
+.idea
+.vscode

README.md

@@ -4,7 +4,7 @@ Whether you are an OEM company or a developer customizing the Android Open Sourc
 
 The Android Software Development Kit (SDK) is a collection of libraries and tools that enables and makes it easier to develop Android applications. SDK Add-ons allow third-party actors to extend the Android SDK to add interfaces to their features without changing the Android SDK. According to the Android Compatibility Definition Document (CDD), OEMs are not allowed to change the Android public APIs - namely those in the protected namespaces: `java.*`, `javax.*`, `sun.*`, `android.*`, `com.android.*`. Therefore, by using add-ons, OEMs can add libraries in their namespaces, providing functionalities that can be exported without infringing the CDD. Having to build only the add-on is also a great advantage that might save a lot of development time.
 
-In this post, we will build an SDK Add-on containing an example service - for which we will cover all the necessary config files. We will also learn how to connect an application to our example service using the add-on. Here, we are assuming you already have access to the Android source code and that you can build and deploy these changes. The code and configuration files were made with Android 10 (API level 30) in mind but they can be easily modifiable to work with other versions.
+In this project, we will build an SDK Add-on containing example services - for which we will cover all the necessary config files. We will also learn how to connect an application to our example services using the add-on. Here, we are assuming you already have access to the Android source code and that you can build and deploy these changes. The code and configuration files were made with Android 14 (API level 34) in mind but they can be easily modifiable to work with other versions.
 
 ## Setting up the AOSP source tree
 
@@ -34,7 +34,9 @@ We supply a shell script `add_to_aosp.sh` to automatically copy all code to the
 
 If you use VSCode, you can use [Run on Save](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) to automatically update the files with this script on save.
 
+#### Sample HAL implementation
 
+This repository also contains an example of how to develop a HAL and use it through the SDK-Addon. First, focus on how the **hello-world-service** works. Then, feel free to take a look at the [HAL Documentation](doc/HAL.md).
 
 ## Hello World System Service
 
@@ -264,10 +266,11 @@ The SDK Add-on is all set. Now we only have to build it. Notice, again, that I'm
 . build/envsetup.sh
 export TARGET=profusion_sdk_addon
 lunch sdk_car_x86_64-trunk_staging-eng
+m profusion.hardware.dummy_car_info_hal-update-api # to freeze AIDL interfaces from HAL
 make sdk_addon
 ```
 
-When the compilation succeeds, you will see two `.zip` files at `out/host/linux-x86/sdk_addon`. `profusion_sdk_addon-linux.zip` will contain the addon itself, which will be used to develop and compile our app. `profusion_sdk_addon-linux-img.zip` will contain a set of files to run the emulator outside the AOSP file tree.
+When the compilation succeeds, you will see two `.zip` files at `out/host/linux-x86/sdk_addon`. `profusion_sdk_addon-linux.zip` will contain the addon itself, which will be used to develop and compile our app. `profusion_sdk_addon-linux-img.zip` will supposedly contain the files to run an emulator. We will see how to use it later.
 
 ### Building Android
 
@@ -415,20 +418,23 @@ emulator
 
 ### Outside the AOSP tree
 
-If you use a remote server to build your addon (It could be a good idea. Building the AOSP right now could be a really really hard job for some hardware) you will probably want to extract the emulator to your local machine. Actually, that's very easy and you already have all you need.
+If you use a remote server to build your addon (It could be a good idea. Building the AOSP right now could be a really really hard job for some hardware) you will probably want to extract the emulator to your local machine. The `profusion_sdk_addon-linux-img.zip` generated by the build process should contain the emulator image, but I had trouble running it. So, we will use another make command to generate the image:
+
+```bash
+make emu_img_zip
+```
+
+This command will pack all the necessary files to create an emulator in a file called `sdk-repo-linux-system-images.zip` under the `out/target/product/emulator_car64_x86_64` folder. Copy this file to your local machine.
 
 Go to your Android Studio and create an emulator using the *Device Manager* tool. Since we builded to a Automotive TARGET, select an hardware under the _Automotive_ category as well. For the _system image_, select (or download first if you don't have it yet) the API 34 image.
 
-Before launching the emulator, extract the content of `profusion_sdk_addon-linux-img.zip` to the API 34 image folder:
+Before launching the emulator, extract the content of `sdk-repo-linux-system-images.zip` to the API 34 image folder:
 
 ```bash
-unzip out/host/linux-x86/sdk_addon/profusion_sdk_addon-linux-img.zip -d $ANDROID_SDK_ROOT/system-images/android-34-ext9/android-automotive
+unzip pathTo/sdk-repo-linux-system-images.zip -d $ANDROID_SDK_ROOT/system-images/android-34-ext9/android-automotive
 ```
 
----
-Note: If you choose to build a different TARGET like `aosp_x86_64` or another, you will need to extract the content to a different path and the `profusion_sdk_addon-linux-img.zip` could not work as expected. In that case, you could use `make emu_img_zip` to generate a similar `sdk-repo-linux-system-images.zip` under `$PRODUCT_OUT` folder.
-
----
+And that's it! You can now run the emulator and test the features.
 
 ### Build and install the App
 
@@ -458,10 +464,3 @@ adb shell
 ```
 
 ![Android emulator running the helloworld app and helloword service](assets/running_app.png "Helloworld App")
-
-
-### HAL
-To freeze the AIDL files:
-```bash
-m update-api
-```