diff options
author | Kiran Rachuri | 2018-05-15 14:39:11 -0500 |
---|---|---|
committer | android-build-merger | 2018-05-15 14:39:11 -0500 |
commit | cf4bd2c8d7e74744b77bc157791df0829f14930a (patch) | |
tree | 91d6a3b76a47a67e2df7a7a739676bf3e0f08fe1 /automotive | |
parent | f8b17e22fc2b5055c45d83f22282c4aec4a2aa3c (diff) | |
parent | e9a39e2714c7311fb88b38f509a96764671dae96 (diff) | |
download | platform-hardware-interfaces-cf4bd2c8d7e74744b77bc157791df0829f14930a.tar.gz platform-hardware-interfaces-cf4bd2c8d7e74744b77bc157791df0829f14930a.tar.xz platform-hardware-interfaces-cf4bd2c8d7e74744b77bc157791df0829f14930a.zip |
Update types.hal comments
am: e9a39e2714
Change-Id: I6f755b9067f937cfa01291842c06640fc2e6cb10
Diffstat (limited to 'automotive')
-rw-r--r-- | automotive/vehicle/2.0/types.hal | 167 |
1 files changed, 143 insertions, 24 deletions
diff --git a/automotive/vehicle/2.0/types.hal b/automotive/vehicle/2.0/types.hal index faa1adc7..23f9b779 100644 --- a/automotive/vehicle/2.0/types.hal +++ b/automotive/vehicle/2.0/types.hal | |||
@@ -42,6 +42,9 @@ enum VehiclePropertyType : int32_t { | |||
42 | }; | 42 | }; |
43 | 43 | ||
44 | /** | 44 | /** |
45 | * Vehicle Areas | ||
46 | * Used to construct property IDs in the VehicleProperty enum. | ||
47 | * | ||
45 | * Some properties may be associated with particular vehicle areas. For | 48 | * Some properties may be associated with particular vehicle areas. For |
46 | * example, VehicleProperty:DOOR_LOCK property must be associated with | 49 | * example, VehicleProperty:DOOR_LOCK property must be associated with |
47 | * particular door, thus this property must be marked with | 50 | * particular door, thus this property must be marked with |
@@ -50,8 +53,34 @@ enum VehiclePropertyType : int32_t { | |||
50 | * Other properties may not be associated with particular vehicle area, | 53 | * Other properties may not be associated with particular vehicle area, |
51 | * these kind of properties must have VehicleArea:GLOBAL flag. | 54 | * these kind of properties must have VehicleArea:GLOBAL flag. |
52 | * | 55 | * |
53 | * Used to create property ID in VehicleProperty enum. | 56 | * [Definition] Area: An area represents a unique element of an AreaType. |
54 | */ | 57 | * For instance, if AreaType is WINDOW, then an area may be FRONT_WINDSHIELD. |
58 | * | ||
59 | * [Definition] AreaID: An AreaID is a combination of one or more areas, | ||
60 | * and is represented using a bitmask of Area enums. Different AreaTypes may | ||
61 | * not be mixed in a single AreaID. For instance, a window area cannot be | ||
62 | * combined with a seat area in an AreaID. | ||
63 | * | ||
64 | * Rules for mapping a zoned property to AreaIDs: | ||
65 | * - A property must be mapped to an array of AreaIDs that are impacted when | ||
66 | * the property value changes. | ||
67 | * - Each element in the array must represent an AreaID, in which, the | ||
68 | * property value can only be changed together in all the areas within | ||
69 | * an AreaID and never independently. That is, when the property value | ||
70 | * changes in one of the areas in an AreaID in the array, then it must | ||
71 | * automatically change in all other areas in the AreaID. | ||
72 | * - The property value must be independently controllable in any two | ||
73 | * different AreaIDs in the array. | ||
74 | * - An area must only appear once in the array of AreaIDs. That is, an | ||
75 | * area must only be part of a single AreaID in the array. | ||
76 | * | ||
77 | * [Definition] Global Property: A property that applies to the entire car | ||
78 | * and is not associated with a specific area. For example, FUEL_LEVEL, | ||
79 | * HVAC_STEERING_WHEEL_HEAT. | ||
80 | * | ||
81 | * Rules for mapping a global property to AreaIDs: | ||
82 | * - A global property must not be mapped to AreaIDs. | ||
83 | */ | ||
55 | enum VehicleArea : int32_t { | 84 | enum VehicleArea : int32_t { |
56 | GLOBAL = 0x01000000, | 85 | GLOBAL = 0x01000000, |
57 | /** WINDOW maps to enum VehicleAreaWindow */ | 86 | /** WINDOW maps to enum VehicleAreaWindow */ |
@@ -331,16 +360,16 @@ enum VehicleProperty : int32_t { | |||
331 | /** | 360 | /** |
332 | * Reports wheel ticks | 361 | * Reports wheel ticks |
333 | * | 362 | * |
334 | * The first four elements represent ticks for individual wheels in the | 363 | * The first element in the vector is a reset count. A reset indicates |
364 | * previous tick counts are not comparable with this and future ones. Some | ||
365 | * sort of discontinuity in tick counting has occurred. | ||
366 | * | ||
367 | * The next four elements represent ticks for individual wheels in the | ||
335 | * following order: front left, front right, rear right, rear left. All | 368 | * following order: front left, front right, rear right, rear left. All |
336 | * tick counts are cumulative. Tick counts increment when the vehicle | 369 | * tick counts are cumulative. Tick counts increment when the vehicle |
337 | * moves forward, and decrement when vehicles moves in reverse. The ticks | 370 | * moves forward, and decrement when vehicles moves in reverse. The ticks |
338 | * should be reset to 0 when the vehicle is started by the user. | 371 | * should be reset to 0 when the vehicle is started by the user. |
339 | * | 372 | * |
340 | * The next element in the vector is a reset count. A reset indicates | ||
341 | * previous tick counts are not comparable with this and future ones. Some | ||
342 | * sort of discontinuity in tick counting has occurred. | ||
343 | * | ||
344 | * int64Values[0] = reset count | 373 | * int64Values[0] = reset count |
345 | * int64Values[1] = front left ticks | 374 | * int64Values[1] = front left ticks |
346 | * int64Values[2] = front right ticks | 375 | * int64Values[2] = front right ticks |
@@ -489,6 +518,12 @@ enum VehicleProperty : int32_t { | |||
489 | * | 518 | * |
490 | * This is the gear selected by the user. | 519 | * This is the gear selected by the user. |
491 | * | 520 | * |
521 | * Values in the config data must represent the list of supported gears | ||
522 | * for this vehicle. For example, config data for an automatic transmission | ||
523 | * must contain {GEAR_NEUTRAL, GEAR_REVERSE, GEAR_PARK, GEAR_DRIVE, | ||
524 | * GEAR_1, GEAR_2,...} and for manual transmission the list must be | ||
525 | * {GEAR_NEUTRAL, GEAR_REVERSE, GEAR_1, GEAR_2,...} | ||
526 | * | ||
492 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE | 527 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE |
493 | * @access VehiclePropertyAccess:READ | 528 | * @access VehiclePropertyAccess:READ |
494 | * @data_enum VehicleGear | 529 | * @data_enum VehicleGear |
@@ -500,8 +535,17 @@ enum VehicleProperty : int32_t { | |||
500 | | VehicleArea:GLOBAL), | 535 | | VehicleArea:GLOBAL), |
501 | 536 | ||
502 | /** | 537 | /** |
503 | * Current gear. In non-manual case, selected gear does not necessarily | 538 | * Current gear. In non-manual case, selected gear may not |
504 | * match the current gear. | 539 | * match the current gear. For example, if the selected gear is GEAR_DRIVE, |
540 | * the current gear will be one of GEAR_1, GEAR_2 etc, which reflects | ||
541 | * the actual gear the transmission is currently running in. | ||
542 | * | ||
543 | * Values in the config data must represent the list of supported gears | ||
544 | * for this vehicle. For example, config data for an automatic transmission | ||
545 | * must contain {GEAR_NEUTRAL, GEAR_REVERSE, GEAR_PARK, GEAR_1, GEAR_2,...} | ||
546 | * and for manual transmission the list must be | ||
547 | * {GEAR_NEUTRAL, GEAR_REVERSE, GEAR_1, GEAR_2,...}. This list need not be the | ||
548 | * same as that of the supported gears reported in GEAR_SELECTION. | ||
505 | * | 549 | * |
506 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE | 550 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE |
507 | * @access VehiclePropertyAccess:READ | 551 | * @access VehiclePropertyAccess:READ |
@@ -625,6 +669,41 @@ enum VehicleProperty : int32_t { | |||
625 | | VehiclePropertyType:BOOLEAN | 669 | | VehiclePropertyType:BOOLEAN |
626 | | VehicleArea:GLOBAL), | 670 | | VehicleArea:GLOBAL), |
627 | 671 | ||
672 | /* | ||
673 | * HVAC Properties | ||
674 | * | ||
675 | * Additional rules for mapping a zoned HVAC property to AreaIDs: | ||
676 | * - Every seat in VehicleAreaSeat that is available in the car, must be | ||
677 | * part of an AreaID in the AreaID array. | ||
678 | * | ||
679 | * Example 1: A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three | ||
680 | * back seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). There are two | ||
681 | * temperature control units -- driver side and passenger side. | ||
682 | * - A valid mapping set of AreaIDs for HVAC_TEMPERATURE_SET would be a | ||
683 | * two element array: | ||
684 | * - ROW_1_LEFT | ROW_2_LEFT | ||
685 | * - ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT | ||
686 | * - An alternative mapping for the same hardware configuration would be: | ||
687 | * - ROW_1_LEFT | ROW_2_CENTER | ROW_2_LEFT | ||
688 | * - ROW_1_RIGHT | ROW_2_RIGHT | ||
689 | * The temperature controllers are assigned to the seats which they | ||
690 | * "most influence", but every seat must be included exactly once. The | ||
691 | * assignment of the center rear seat to the left or right AreaID may seem | ||
692 | * arbitrary, but the inclusion of every seat in exactly one AreaID ensures | ||
693 | * that the seats in the car are all expressed and that a "reasonable" way | ||
694 | * to affect each seat is available. | ||
695 | * | ||
696 | * Example 2: A car has three seat rows with two seats in the front row (ROW_1_LEFT, | ||
697 | * ROW_1_RIGHT) and three seats in the second (ROW_2_LEFT, ROW_2_CENTER, | ||
698 | * ROW_2_RIGHT) and third rows (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). There | ||
699 | * are three temperature control units -- driver side, passenger side, and rear. | ||
700 | * - A reasonable way to map HVAC_TEMPERATURE_SET to AreaIDs is a three | ||
701 | * element array: | ||
702 | * - ROW_1_LEFT | ||
703 | * - ROW_1_RIGHT | ||
704 | * - ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT | ||
705 | */ | ||
706 | |||
628 | /** | 707 | /** |
629 | * Fan speed setting | 708 | * Fan speed setting |
630 | * | 709 | * |
@@ -754,22 +833,34 @@ enum VehicleProperty : int32_t { | |||
754 | | VehicleArea:SEAT), | 833 | | VehicleArea:SEAT), |
755 | 834 | ||
756 | /** | 835 | /** |
757 | * Enable temperature coupling between zones. | 836 | * Enable temperature coupling between areas. |
758 | * | 837 | * |
759 | * The areaId for this property must include the zones that are coupled | 838 | * The AreaIDs for HVAC_DUAL_ON property shall contain a combination of |
760 | * together. Typically, the front two zones (ROW_1_LEFT and ROW_1_RIGHT) | 839 | * HVAC_TEMPERATURE_SET AreaIDs that can be coupled together. If |
761 | * are coupled together when this property is enabled. Thus, the areaId | 840 | * HVAC_TEMPERATURE_SET is mapped to AreaIDs [a_1, a_2, ..., a_n], and if |
762 | * shall be (ROW_1_LEFT | ROW_1_RIGHT). When the property is enabled, the | 841 | * HVAC_DUAL_ON can be enabled to couple a_i and a_j, then HVAC_DUAL_ON |
763 | * ECU may synchronize the temperature for the affected zones. Any | 842 | * property must be mapped to [a_i | a_j]. Further, if a_k and a_l can also |
764 | * parameters modified as a side effect of turning on/off the DUAL_ON | 843 | * be coupled together separately then HVAC_DUAL_ON must be mapped to |
765 | * parameter shall generate onPropertyEvent() callbacks to the VHAL. In | 844 | * [a_i | a_j, a_k | a_l]. |
766 | * addition, if setting a temperature (i.e. driver's temp) changes another | 845 | * |
767 | * temperature (i.e. front passenger's temp), then the appropriate | 846 | * Example: A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three |
847 | * back seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). There are two | ||
848 | * temperature control units -- driver side and passenger side -- which can | ||
849 | * be optionally synchronized. This may be expressed in the AreaIDs this way: | ||
850 | * - HVAC_TEMPERATURE_SET->[ROW_1_LEFT | ROW_2_LEFT, ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT] | ||
851 | * - HVAC_DUAL_ON->[ROW_1_LEFT | ROW_2_LEFT | ROW_1_RIGHT | ROW_2_CENTER | ROW_2_RIGHT] | ||
852 | * | ||
853 | * When the property is enabled, the ECU must synchronize the temperature | ||
854 | * for the affected areas. Any parameters modified as a side effect | ||
855 | * of turning on/off the DUAL_ON parameter shall generate | ||
856 | * onPropertyEvent() callbacks to the VHAL. In addition, if setting | ||
857 | * a temperature (i.e. driver's temperature) changes another temperature | ||
858 | * (i.e. front passenger's temperature), then the appropriate | ||
768 | * onPropertyEvent() callbacks must be generated. If a user changes a | 859 | * onPropertyEvent() callbacks must be generated. If a user changes a |
769 | * temperature that breaks the coupling (e.g. setting the passenger | 860 | * temperature that breaks the coupling (e.g. setting the passenger |
770 | * temperature independently) then the VHAL must send the appropriate | 861 | * temperature independently) then the VHAL must send the appropriate |
771 | * onPropertyEvent() callbacks (i.e. HVAC_DUAL_ON = false, | 862 | * onPropertyEvent() callbacks (i.e. HVAC_DUAL_ON = false, |
772 | * HVAC_TEMPERATURE_SET[zone] = xxx, etc). | 863 | * HVAC_TEMPERATURE_SET[AreaID] = xxx, etc). |
773 | * | 864 | * |
774 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE | 865 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE |
775 | * @access VehiclePropertyAccess:READ_WRITE | 866 | * @access VehiclePropertyAccess:READ_WRITE |
@@ -877,13 +968,41 @@ enum VehicleProperty : int32_t { | |||
877 | | VehicleArea:SEAT), | 968 | | VehicleArea:SEAT), |
878 | 969 | ||
879 | /** | 970 | /** |
880 | * Represents global power state for HVAC. Setting this property to false | 971 | * Represents global power state for HVAC. Setting this property to false |
881 | * MAY mark some properties that control individual HVAC features/subsystems | 972 | * MAY mark some properties that control individual HVAC features/subsystems |
882 | * to UNAVAILABLE state. Setting this property to true MAY mark some | 973 | * to UNAVAILABLE state. Setting this property to true MAY mark some |
883 | * properties that control individual HVAC features/subsystems to AVAILABLE | 974 | * properties that control individual HVAC features/subsystems to AVAILABLE |
884 | * state (unless any/all of them are UNAVAILABLE on their own individual | 975 | * state (unless any/all of them are UNAVAILABLE on their own individual |
885 | * merits). The list of properties affected by HVAC_POWER_ON must be set | 976 | * merits). |
886 | * in the VehiclePropConfig.configArray. | 977 | * |
978 | * [Definition] HvacPower_DependentProperties: Properties that need HVAC to be | ||
979 | * powered on in order to enable their functionality. For example, in some cars, | ||
980 | * in order to turn on the AC, HVAC must be powered on first. | ||
981 | * | ||
982 | * HvacPower_DependentProperties list must be set in the | ||
983 | * VehiclePropConfig.configArray. HvacPower_DependentProperties must only contain | ||
984 | * properties that are associated with VehicleArea:SEAT. Properties that are not | ||
985 | * associated with VehicleArea:SEAT, for example, HVAC_DEFROSTER, must never | ||
986 | * depend on HVAC_POWER_ON property and must never be part of | ||
987 | * HvacPower_DependentProperties list. | ||
988 | * | ||
989 | * AreaID mapping for HVAC_POWER_ON property must contain all AreaIDs that | ||
990 | * HvacPower_DependentProperties are mapped to. | ||
991 | * | ||
992 | * Example 1: A car has two front seats (ROW_1_LEFT, ROW_1_RIGHT) and three back | ||
993 | * seats (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT). If the HVAC features (AC, | ||
994 | * Temperature etc.) throughout the car are dependent on a single HVAC power | ||
995 | * controller then HVAC_POWER_ON must be mapped to | ||
996 | * [ROW_1_LEFT | ROW_1_RIGHT | ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT]. | ||
997 | * | ||
998 | * Example 2: A car has two seats in the front row (ROW_1_LEFT, ROW_1_RIGHT) and | ||
999 | * three seats in the second (ROW_2_LEFT, ROW_2_CENTER, ROW_2_RIGHT) and third | ||
1000 | * rows (ROW_3_LEFT, ROW_3_CENTER, ROW_3_RIGHT). If the car has temperature | ||
1001 | * controllers in the front row which can operate entirely independently of | ||
1002 | * temperature controllers in the back of the vehicle, then HVAC_POWER_ON | ||
1003 | * must be mapped to a two element array: | ||
1004 | * - ROW_1_LEFT | ROW_1_RIGHT | ||
1005 | * - ROW_2_LEFT | ROW_2_CENTER | ROW_2_RIGHT | ROW_3_LEFT | ROW_3_CENTER | ROW_3_RIGHT | ||
887 | * | 1006 | * |
888 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE | 1007 | * @change_mode VehiclePropertyChangeMode:ON_CHANGE |
889 | * @access VehiclePropertyAccess:READ_WRITE | 1008 | * @access VehiclePropertyAccess:READ_WRITE |