From 49e36808da9d92c8104c37d25cad81c784beae6b Mon Sep 17 00:00:00 2001 From: Aaqib Ismail Date: Sat, 25 Mar 2023 21:31:47 +0000 Subject: [PATCH] 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 --- automotive/vehicle/2.0/types.hal | 49 ++++++------------- .../automotive/vehicle/VehicleAreaConfig.aidl | 2 +- .../automotive/vehicle/VehiclePropConfig.aidl | 20 +++++++- .../automotive/vehicle/VehicleArea.aidl | 19 +++++++ current.txt | 1 + 5 files changed, 54 insertions(+), 37 deletions(-) diff --git a/automotive/vehicle/2.0/types.hal b/automotive/vehicle/2.0/types.hal index d75b046774..5b0a5055c1 100644 --- a/automotive/vehicle/2.0/types.hal +++ b/automotive/vehicle/2.0/types.hal @@ -57,46 +57,25 @@ enum VehiclePropertyType : int32_t { }; /** - * 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 abd9540876..20c046d574 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 @@ package android.hardware.automotive.vehicle; @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 1b48f0b1b6..61b936932d 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 @@ parcelable VehiclePropConfig { 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 dab03496cb..6f7f78386a 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 a6c4d807cf..754093f2b1 100644 --- a/current.txt +++ b/current.txt @@ -937,5 +937,6 @@ a2fbd9747fbb9ceb8c1090b5a24138312246502d5af0654a8c2b603a9bf521fc android.hardwar 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.