Add freeze manifest readme.

Test: none
Bug: 37226359
Change-Id: If1cd39be4d2b5d70de43f16108dbbfa6d05bdb4d

1 files changed, 79 insertions, 0 deletions

diff --git a/vintfdata/README.md b/vintfdata/README.md
new file mode 100644
index 0000000..0d17b66
--- /dev/null
+++ b/vintfdata/README.md
@@ -0,0 +1,79 @@
+# Updating the latest framework manifest
+
+## Adding new HALs / Major version update
+
+Add a new `<hal>` entry without a `max-level` attribute. The `<hal>` entry can
+be added to the main manifest under `manifest.xml`, or to the manifest
+fragment for the server module specified in `vintf_fragments`.
+
+Introducing new HALs are backwards compatible.
+
+## Minor version update
+
+When a framework HAL updates its minor version, simply update the `<version>` or
+`<fqname>` field to the latest version. This is the same as any other HALs.
+
+For example, when `IServiceManager` updates to 1.2, change its `<fqname>` field
+to `@1.2::IServiceManager/default`.
+
+Because minor version updates are backwards compatible, all devices that require
+a lower minor version of the HAL are still compatible.
+
+Leave `max-level` attribute empty.
+
+## Deprecating HAL
+
+When a framework HAL is deprecated, set `max-level` field of the HAL from empty
+to the last frozen version.
+For example, if IDisplayService is deprecated in Android S, set `max-level` to
+Android R (5):
+
+```xml
+<manifest version="3.0" type="framework">
+  <hal format="hidl" max-level="5"> <!-- Level::R -->
+    <name>android.frameworks.displayservice</name>
+    <transport>hwbinder</transport>
+    <fqname>@1.0::IDisplayService/default</fqname>
+  </hal>
+</manifest>
+```
+
+Note that the `max-level` of the HAL is set to Android R, meaning that the HAL
+is last available in Android R and disabled in Android S.
+
+Deprecating a HAL doesn’t mean dropping support of the HAL, so no devices will
+break.
+
+## Removing HAL
+
+When the framework drops support of a certain HAL, the corresponding HAL entry
+is removed from the framework manifest, and code that serves and registers the
+HAL must be removed simultaneously.
+
+Devices that are lower than the `max-level` attribute of the HAL may start to
+break if they require this HAL. Hence, this must only be done when there is
+enough evidence that the devices are not updateable to the latest Android
+release.
+
+# Freezing framework HAL manifest
+
+First, check `libvintf` or `hardware/interfaces/compatibility_matrices` to
+determine the current level.
+
+Execute the following, replacing the argument with the level to freeze:
+
+```shell script
+LEVEL=5
+./freeze.sh ${LEVEL}
+```
+
+A new file, `frozen/${LEVEL}.xml`, will be created after the command is
+executed. Frozen system manifests are stored in compatibility matrices. These
+compatibility matrices served as a reference for devices at that
+target FCM version. Devices at the given target FCM version should
+use DCMs in the `frozen/` dir, although some of the HALs may be marked
+as `optional="true"` or even omitted if unused by device-specific code.
+
+At build time, compatibiltiy is checked between framework manifest and
+the respective frozen DCM. HALs in the framework manifest with `max-level`
+less than the specified level are omitted.