1# Updating the latest framework manifest
2
3## Adding new HALs / Major version update
4
5Add a new `<hal>` entry without a `max-level` attribute. The `<hal>` entry can
6be added to the main manifest under `manifest.xml`, or to the manifest
7fragment for the server module specified in `vintf_fragments`.
8
9Introducing new HALs are backwards compatible.
10
11## Minor version update
12
13When a framework HAL updates its minor version, simply update the `<version>` or
14`<fqname>` field to the latest version. This is the same as any other HALs.
15
16For example, when `IServiceManager` updates to 1.2, change its `<fqname>` field
17to `@1.2::IServiceManager/default`.
18
19Because minor version updates are backwards compatible, all devices that require
20a lower minor version of the HAL are still compatible.
21
22Leave `max-level` attribute empty.
23
24## Deprecating HAL
25
26When a framework HAL is deprecated, set `max-level` field of the HAL from empty
27to the last frozen version.
28For example, if IDisplayService is deprecated in Android S, set `max-level` to
29Android R (5):
30
31```xml
32<manifest version="3.0" type="framework">
33  <hal format="hidl" max-level="5"> <!-- Level::R -->
34    <name>android.frameworks.displayservice</name>
35    <transport>hwbinder</transport>
36    <fqname>@1.0::IDisplayService/default</fqname>
37  </hal>
38</manifest>
39```
40
41Note that the `max-level` of the HAL is set to Android R, meaning that the HAL
42is last available in Android R and disabled in Android S.
43
44Deprecating a HAL doesn’t mean dropping support of the HAL, so no devices will
45break.
46
47When setting `max-level` of a HAL:
48- If `optional="false"` in frozen DCMs, the build system checks that adding the
49  attribute does not break backwards compatibility; that is,
50  `max-level > last_frozen_level`.
51- If `optional="true"`, the check is disabled. Care must be taken to ensure
52  `max-level` is set appropriately.
53
54## Removing HAL
55
56When the framework drops support of a certain HAL, the corresponding HAL entry
57is removed from the framework manifest, and code that serves and registers the
58HAL must be removed simultaneously.
59
60Devices that are lower than the `max-level` attribute of the HAL may start to
61break if they require this HAL. Hence, this must only be done when there is
62enough evidence that the devices are not updateable to the latest Android
63release.
64
65# Freezing framework HAL manifest
66
67First, check `libvintf` or `hardware/interfaces/compatibility_matrices` to
68determine the current level.
69
70Execute the following, replacing the argument with the level to freeze:
71
72```shell script
73lunch cf_x86_phone-userdebug # or any generic target
74LEVEL=5
75./freeze.sh ${LEVEL}
76```
77
78A new file, `frozen/${LEVEL}.xml`, will be created after the command is
79executed. Frozen system manifests are stored in compatibility matrices. Then,
80manually inspect the frozen compatibility matrix. Modify the `optional`
81field for certain HALs. See comments in the compatibility matrix of the previous
82level for details.
83
84These compatibility matrices served as a reference for devices at that
85target FCM version. Devices at the given target FCM version should
86reference DCMs in the `frozen/` dir, with some of the HALs marked
87as `optional="true"` or even omitted if unused by device-specific code.
88
89At build time, compatibiltiy is checked between framework manifest and
90the respective frozen DCM. HALs in the framework manifest with `max-level`
91less than the specified level are omitted.
92