diff options
author | Yifan Hong <elsk@google.com> | 2020-10-20 17:06:59 +0000 |
---|---|---|
committer | Gerrit Code Review <noreply-gerritcodereview@google.com> | 2020-10-20 17:06:59 +0000 |
commit | d6e79a433b651cff12c850e86875ddf242c6564e (patch) | |
tree | a42e3d5d6c44504371f073ba551ebf9d3eb7de4c /vintfdata | |
parent | c89aabe52def7bc9861d662bd04c7f21d53699f7 (diff) | |
parent | 344245360fb5606f80b90249991935df2582bc44 (diff) | |
download | libhidl-d6e79a433b651cff12c850e86875ddf242c6564e.tar.gz |
Merge "Add freeze manifest readme."
Diffstat (limited to 'vintfdata')
-rw-r--r-- | vintfdata/README.md | 79 |
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. |