Update VehicleAreaConfig documentation.
Flag: EXEMPT HAL
Test: Presubmit
Bug: 382563296
Change-Id: I47df27fca04a42673b27d1f2d58209449837395e
diff --git a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
index 1720628..9ca4366 100644
--- a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
+++ b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/VehicleAreaConfig.aidl
@@ -29,142 +29,156 @@
int areaId;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional minimum int32 value at boot time.
+ *
+ * Assume unspecified if both {@code minInt32Value} and
+ * {@code maxInt32Value} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minInt32Value} and {@code maxInt32Value} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code INT32} type property. Ignored for other types.
*
- * The optional minimum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the min supported value
- * ({@code MinMaxSupportedValueResult.minSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minInt32Value} and {@code maxInt32Value} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMinSupportedValue} must be
+ * {@code true}.
*/
int minInt32Value;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional maximum int32 value at boot time.
+ *
+ * Assume unspecified if both {@code minInt32Value} and
+ * {@code maxInt32Value} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minInt32Value} and {@code maxInt32Value} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code INT32} type property. Ignored for other types.
*
- * The optional maximum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the max supported value
- * ({@code MinMaxSupportedValueResult.maxSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minInt32Value} and {@code maxInt32Value} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMaxSupportedValue} must be
+ * {@code true}.
*/
int maxInt32Value;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional minimum int64 value at boot time.
+ *
+ * Assume unspecified if both {@code minInt64Value} and
+ * {@code maxInt64Value} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minInt64Value} and {@code maxInt64Value} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code INT64} type property. Ignored for other types.
*
- * The optional minimum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the min supported value
- * ({@code MinMaxSupportedValueResult.minSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minInt64Value} and {@code maxInt64Value} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMinSupportedValue} must be
+ * {@code true}.
*/
long minInt64Value;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional maximum int64 value at boot time.
+ *
+ * Assume unspecified if both {@code minInt64Value} and
+ * {@code maxInt64Value} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minInt64Value} and {@code maxInt64Value} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code INT64} type property. Ignored for other types.
*
- * The optional maximum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the max supported value
- * ({@code MinMaxSupportedValueResult.maxSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minInt64Value} and {@code maxInt64Value} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMaxSupportedValue} must be
+ * {@code true}.
*/
long maxInt64Value;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional minimum float value at boot time.
+ *
+ * Assume unspecified if both {@code minFloatValue} and
+ * {@code maxFloatValue} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minFloatValue} and {@code maxFloatValue} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code FLOAT} type property. Ignored for other types.
*
- * The optional minimum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the min supported value
- * ({@code MinMaxSupportedValueResult.minSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minFloatValue} and {@code maxFloatValue} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMinSupportedValue} must be
+ * {@code true}.
*/
float minFloatValue;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * The optional maximum float value at boot time.
+ *
+ * Assume unspecified if both {@code minFloatValue} and
+ * {@code maxFloatValue} is 0. If either one is not 0, then we assume min
+ * and max both take effect. If no minimum or maximum value is available at
+ * boot time, both {@code minFloatValue} and {@code maxFloatValue} must be
+ * set to 0.
+ *
+ * Note that this property only represents the minimum value at boot time
+ * and may not represent the current actual minimum value.
*
* Only applicable for {@code FLOAT} type property. Ignored for other types.
*
- * The optional maximum value at boot time.
+ * For certain properties, this field must be specified, see
+ * {@code VehicleProperty} documentation.
*
- * For backward compatibility,
- * if {@code HasSupportedValueInfo.hasMinSupportedValue} is {@code true},
- * and {@code HasSupportedValueInfo.hasMaxSupportedValue} is {@code true},
- * this must be equal to the max supported value
- * ({@code MinMaxSupportedValueResult.maxSupportedValue}) at boot time.
- *
- * If no minimum or maximum value is available at boot time, both
- * {@code minFloatValue} and {@code maxFloatValue} must be set to 0.
- *
- * If either one is not 0, then we assume min and max both take effect.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * specified, {@code HasSupportedValueInfo.hasMinSupportedValue} must be
+ * {@code true}.
*/
float maxFloatValue;
/**
- * client should use {@code getMinMaxSupportedValue} instead.
+ * Optional supported subset of supported enum values at boot time.
*
* Only applicable for property with {@code @data_enum} annotation. Ignored
* for other properties.
*
- * Optional supported subset of supported values at boot time.
- *
* If the property has a @data_enum and supportedEnumValues is {@code null},
* then it is assumed all @data_enum values are supported unless specified
* through another mechanism.
*
- * For backward compatibility, if
- * {@code HasSupportedValueInfo.hasSupportedValuesList} is {@code true}
- * and this property has {@code data_enum} annotation,
- * this must be set to the same as
- * {@code SupportedValuesListResult.supportedValuesList} at boot time.
+ * If {@code HasSupportedValueInfo} is not {@code null} and this field is
+ * not {@code null}, {@code HasSupportedValueInfo.hasSupportedValuesList}
+ * must be {@code true}.
*/
@nullable long[] supportedEnumValues;
@@ -237,7 +251,19 @@
* {@code getSupportedValuesLists}, {@code subscribeSupportedValueChange},
* {@code unsubscribeSupportedValueChange}.
*
- * If this is {@code null} for legacy properties, the APIs mentioned before are not supported.
+ * If this is not {@code null}. The VHAL implementation must implement
+ * {@code getMinMaxSupportedValue}, {@code getSupportedValuesLists},
+ * {@code subscribeSupportedValueChange} for the [propId, areaId].
+ *
+ * This should be non-null if the VHAL implementation wants to expose
+ * min/max supported value or supported values list that may change dynamically. For example,
+ * if the max HVAC fan speed may change due to HVAC power settings.
+ *
+ * This should not be non-null if the VHAL implementation wants to expose supported
+ * values list for property ID that is not an enum type (hence do not support
+ * {@code VehicleAreaConfig#supportedEnumValues}).
+ *
+ * If this is {@code null}, the APIs mentioned before are not supported.
* Client must fallback to use static supported value information in {@code VehicleAreaConfig}.
*
* For VHAL implementation < V4, this is always {@code null}.