1 /*
2  * Copyright (C) 2022 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 #include <stdint.h>
23 
24 #ifndef __packed
25 #define __packed __attribute__((packed))
26 #endif
27 
28 /****************************************************************************/
29 /**
30  * This should be the start of EVERY request and response struct.
31  *
32  * We don't really need a struct just to hold one integer, but if we need to add
33  * to it later, we'll be glad we did.
34  */
35 struct nos2_cmd_hal {
36   uint32_t version;
37 } __packed;
38 /**
39  * IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
40  *
41  *   Do *NOT* increment the version number with each new dessert release!
42  *
43  *   We'll use a (major << 16) | (minor) value for the version. The major
44  *   versionn indicates when the command was first supported, and the minor
45  *   indicates variations to it since then.
46  *
47  *   We're currently working on Android 14 (UDC), so start with that. Bump minor
48  *   values ONLY if the behavior changes.
49  *
50  *   By including the version struct in every request and response, we can
51  *   support multiple minor HAL changes independently. Add a new version
52  *   constant below IF AND ONLY IF a command's struct changes or its behavior is
53  *   different. THEN use that version internally to
54  *
55  *   1. Reject the command if the version is one you don't know about, AND
56  *
57  *   2. Verify that the incoming struct matches expectations for the versions
58  *      you do know about, AND
59  *
60  *   3. Support as many versions as possible, in case Android is downgraded and
61  *      Nugget OS is not (or vice-versa), SO
62  *
63  *   4) Make sure to indicate the version in the output structs too, in case the
64  *      command has no input args but the output later changes.
65  *
66  * IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
67  */
68 #define NOS2_HAL_VERSION_UDC (14U << 16)
69 /* STOP! Don't just randomly add new values here! Read the comment above! */
70 
71 /****************************************************************************/
72 /* Common types */
73 
74 /* TODO(b/257251378): We'll need some <tag,len,bytes[]> stuff here. */
75 
76 /****************************************************************************/
77 #ifdef __cplusplus
78 }
79 #endif
80