Fix inconsistencies in VehicleArea HAL documentation
Remove references of area types and use more consistent language.
Use same documentation across AIDL and HIDL definitions.
Bug: 259987652
Test: presubmit
Change-Id: I4da6ff23fd221698c9fbe9c9f817f51959a49a79
diff --git a/automotive/vehicle/2.0/types.hal b/automotive/vehicle/2.0/types.hal
index d75b046..5b0a505 100644
--- a/automotive/vehicle/2.0/types.hal
+++ b/automotive/vehicle/2.0/types.hal
@@ -57,46 +57,25 @@
};
/**
- * Vehicle Areas
+ * List of different supported area types for vehicle properties.
* Used to construct property IDs in the VehicleProperty enum.
*
- * Some properties may be associated with particular vehicle areas. For
- * example, VehicleProperty:DOOR_LOCK property must be associated with
- * particular door, thus this property must be marked with
- * VehicleArea:DOOR flag.
+ * Some properties may be associated with particular areas in the vehicle. For example,
+ * VehicleProperty#DOOR_LOCK property must be associated with a particular door, thus this property
+ * must be of the VehicleArea#DOOR area type.
*
- * Other properties may not be associated with particular vehicle area.
- * These kinds of properties must have VehicleArea:GLOBAL flag.
+ * Other properties may not be associated with a particular area in the vehicle. These kinds of
+ * properties must be of the VehicleArea#GLOBAL area type.
*
- * [Definition] Area: An area represents a unique element of an AreaType.
- * For instance, if AreaType is WINDOW, then an area may be FRONT_WINDSHIELD.
- *
- * [Definition] AreaID: An AreaID is a combination of one or more areas,
- * and is represented using a bitmask of Area enums. Different AreaTypes may
- * not be mixed in a single AreaID. For instance, a window area cannot be
- * combined with a seat area in an AreaID.
- *
- * Rules for mapping a zoned property to AreaIDs:
- * - A property must be mapped to an array of AreaIDs that are impacted when
- * the property value changes.
- * - Each element in the array must represent an AreaID, in which the
- * property value can only be changed together in all the areas within
- * the AreaID and never independently. That is, when the property value
- * changes in one of the areas in an AreaID in the array, then it must
- * automatically change in all other areas in the AreaID.
- * - The property value must be independently controllable in any two
- * different AreaIDs in the array.
- * - An area must only appear once in the array of AreaIDs. That is, an
- * area must only be part of a single AreaID in the array.
- *
- * [Definition] Global Property: A property that applies to the entire car
- * and is not associated with a specific area. For example, FUEL_LEVEL,
- * HVAC_STEERING_WHEEL_HEAT.
- *
- * Rules for mapping a global property to AreaIDs:
- * - A global property must not be mapped to AreaIDs.
-*/
+ * Note: This is not the same as areaId used in VehicleAreaConfig. E.g. for a global property, the
+ * property ID is of the VehicleArea#GLOBAL area type, however, the area ID must be 0.
+ */
+// A better name would be VehicleAreaType
enum VehicleArea : int32_t {
+ /**
+ * A global property is a property that applies to the entire vehicle and is not associated with
+ * a specific area. For example, FUEL_LEVEL, HVAC_STEERING_WHEEL_HEAT are global properties.
+ */
GLOBAL = 0x01000000,
/** WINDOW maps to enum VehicleAreaWindow */
WINDOW = 0x03000000,
diff --git a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
index abd9540..20c046d 100644
--- a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
+++ b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
@@ -20,7 +20,7 @@
@JavaDerive(equals=true, toString=true)
parcelable VehicleAreaConfig {
/**
- * Area id is ignored for VehiclePropertyGroup:GLOBAL properties.
+ * Area id is always 0 for VehicleArea#GLOBAL properties.
*/
int areaId;
diff --git a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehiclePropConfig.aidl b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehiclePropConfig.aidl
index 1b48f0b..61b9369 100644
--- a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehiclePropConfig.aidl
+++ b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehiclePropConfig.aidl
@@ -37,7 +37,25 @@
VehiclePropertyChangeMode changeMode = VehiclePropertyChangeMode.STATIC;
/**
- * Contains per-area configuration.
+ * Contains per-areaId configuration.
+ *
+ * [Definition] area: An area represents a unique element of a VehicleArea. For instance, if the
+ * VehicleArea is WINDOW, then an example area is FRONT_WINDSHIELD.
+ *
+ * [Definition] area ID: An area ID is a combination of one or more areas, and is created by
+ * bitwise "OR"ing the areas together. Areas from different VehicleArea values may not be
+ * mixed in a single area ID. For example, a VehicleAreaWindow area cannot be combined with a
+ * VehicleAreaSeat area in an area ID.
+ *
+ * For VehicleArea#GLOBAL properties, they must map only to a single area ID of 0.
+ *
+ * Rules for mapping a non VehicleArea#GLOBAL property to area IDs:
+ * - A property must be mapped to a set of area IDs that are impacted when the property value
+ * changes.
+ * - An area cannot be part of multiple area IDs, it must only be part of a single area ID.
+ * - When the property value changes in one of the areas in an area ID, then it must
+ * automatically change in all other areas in the area ID.
+ * - The property value must be independently controllable in any two different area IDs.
*/
VehicleAreaConfig[] areaConfigs;
diff --git a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl
index dab0349..6f7f783 100644
--- a/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl
+++ b/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl
@@ -16,9 +16,28 @@
package android.hardware.automotive.vehicle;
+/**
+ * List of different supported area types for vehicle properties.
+ * Used to construct property IDs in the VehicleProperty enum.
+ *
+ * Some properties may be associated with particular areas in the vehicle. For example,
+ * VehicleProperty#DOOR_LOCK property must be associated with a particular door, thus this property
+ * must be of the VehicleArea#DOOR area type.
+ *
+ * Other properties may not be associated with a particular area in the vehicle. These kinds of
+ * properties must be of the VehicleArea#GLOBAL area type.
+ *
+ * Note: This is not the same as areaId used in VehicleAreaConfig. E.g. for a global property, the
+ * property ID is of the VehicleArea#GLOBAL area type, however, the area ID must be 0.
+ */
@VintfStability
@Backing(type="int")
+// A better name would be VehicleAreaType
enum VehicleArea {
+ /**
+ * A global property is a property that applies to the entire vehicle and is not associated with
+ * a specific area. For example, FUEL_LEVEL, HVAC_STEERING_WHEEL_HEAT are global properties.
+ */
GLOBAL = 0x01000000,
/** WINDOW maps to enum VehicleAreaWindow */
WINDOW = 0x03000000,
diff --git a/current.txt b/current.txt
index a6c4d80..754093f 100644
--- a/current.txt
+++ b/current.txt
@@ -937,5 +937,6 @@
889b59e3e7a59afa67bf19882a44f51a2f9e43b6556ec52baa9ec3efd1ef7fbe android.hardware.camera.device@3.2::types
db37a1c757e2e69b1ec9c75a981a6987bd87a131d92ab6acc00e04d19f374281 android.hardware.automotive.vehicle@2.0::types
997017f581406fca1675d2f612f7ccd73f0d04eadd54bf6212e6cf5971d0872d android.hardware.automotive.vehicle@2.0::types
+06983ffe6d75e90a22503a6d9fd14417f983a36bb060a80ad5915240d69b8a40 android.hardware.automotive.vehicle@2.0::types
# There will be no more HIDL HALs. Use AIDL instead.