1 /*
2  * Copyright (C) 2017 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 
17 #ifndef CHRE_PLATFORM_SHARED_HOST_PROTOCOL_CHRE_H_
18 #define CHRE_PLATFORM_SHARED_HOST_PROTOCOL_CHRE_H_
19 
20 #include <stdint.h>
21 
22 #include "chre/platform/shared/host_messages_generated.h"
23 #include "chre/platform/shared/host_protocol_common.h"
24 #include "flatbuffers/flatbuffers.h"
25 
26 namespace chre {
27 
28 typedef flatbuffers::Offset<fbs::NanoappListEntry> NanoappListEntryOffset;
29 
30 /**
31  * Checks that a string encapsulated as a byte vector is null-terminated, and
32  * if it is, returns a pointer to the vector's data. Otherwise returns null.
33  *
34  * This is similar to getStringFromByteVector in host_protocol_host.h. Ensure
35  * that method's implementation is kept in sync with this.
36  *
37  * @param vec Target vector, can be null
38  *
39  * @return Pointer to the vector's data, or null
40  */
41 const char *getStringFromByteVector(const flatbuffers::Vector<int8_t> *vec);
42 
43 /**
44  * These methods are called from decodeMessageFromHost() and must be implemented
45  * by the code that calls it to handle parsed messages.
46  */
47 class HostMessageHandlers {
48  public:
49   static void handleNanoappMessage(
50     uint64_t appId, uint32_t messageType, uint16_t hostEndpoint,
51     const void *messageData, size_t messageDataLen);
52 
53   static void handleHubInfoRequest(uint16_t hostClientId);
54 
55   static void handleNanoappListRequest(uint16_t hostClientId);
56 
57   static void handleLoadNanoappRequest(
58       uint16_t hostClientId, uint32_t transactionId, uint64_t appId,
59       uint32_t appVersion, uint32_t targetApiVersion, const void *buffer,
60       size_t bufferLen, const char *appFileName, uint32_t fragmentId,
61       size_t appBinaryLen);
62 
63   static void handleUnloadNanoappRequest(
64       uint16_t hostClientId, uint32_t transactionId, uint64_t appId,
65       bool allowSystemNanoappUnload);
66 
67   static void handleTimeSyncMessage(int64_t offset);
68 
69   static void handleDebugDumpRequest(uint16_t hostClientId);
70 };
71 
72 /**
73  * A set of helper methods that simplify the encode/decode of FlatBuffers
74  * messages used in communications with the host from CHRE.
75  */
76 class HostProtocolChre : public HostProtocolCommon {
77  public:
78   /**
79    * Verifies and decodes a FlatBuffers-encoded CHRE message.
80    *
81    * @param message Buffer containing message
82    * @param messageLen Size of the message, in bytes
83    * @param handlers Contains callbacks to process a decoded message
84    *
85    * @return bool true if the message was successfully decoded, false if it was
86    *         corrupted/invalid/unrecognized
87    */
88   static bool decodeMessageFromHost(const void *message, size_t messageLen);
89 
90   /**
91    * Refer to the context hub HAL definition for a details of these parameters.
92    *
93    * @param builder A newly constructed FlatBufferBuilder that will be used to
94    *        encode the message
95    */
96   static void encodeHubInfoResponse(
97       flatbuffers::FlatBufferBuilder& builder, const char *name,
98       const char *vendor, const char *toolchain, uint32_t legacyPlatformVersion,
99       uint32_t legacyToolchainVersion, float peakMips, float stoppedPower,
100       float sleepPower, float peakPower, uint32_t maxMessageLen,
101       uint64_t platformId, uint32_t version, uint16_t hostClientId);
102 
103   /**
104    * Supports construction of a NanoappListResponse by adding a single
105    * NanoappListEntry to the response. The offset for the newly added entry is
106    * maintained in the given vector until finishNanoappListResponse() is called.
107    * Example usage:
108    *
109    *   FlatBufferBuilder builder;
110    *   DynamicVector<NanoappListEntryOffset> vector;
111    *   for (auto app : appList) {
112    *     HostProtocolChre::addNanoppListEntry(builder, vector, ...);
113    *   }
114    *   HostProtocolChre::finishNanoappListResponse(builder, vector);
115    *
116    * @param builder A FlatBufferBuilder to use for encoding the message
117    * @param offsetVector A vector to track the offset to the newly added
118    *        NanoappListEntry, which be passed to finishNanoappListResponse()
119    *        once all entries are added
120    */
121   static void addNanoappListEntry(
122       flatbuffers::FlatBufferBuilder& builder,
123       DynamicVector<NanoappListEntryOffset>& offsetVector,
124       uint64_t appId, uint32_t appVersion, bool enabled, bool isSystemNanoapp);
125 
126   /**
127    * Finishes encoding a NanoappListResponse message after all NanoappListEntry
128    * elements have already been added to the builder.
129    *
130    * @param builder The FlatBufferBuilder used with addNanoappListEntry()
131    * @param offsetVector The vector used with addNanoappListEntry()
132    * @param hostClientId
133    *
134    * @see addNanoappListEntry()
135    */
136   static void finishNanoappListResponse(
137       flatbuffers::FlatBufferBuilder& builder,
138       DynamicVector<NanoappListEntryOffset>& offsetVector,
139       uint16_t hostClientId);
140 
141   /**
142    * Encodes a response to the host communicating the result of dynamically
143    * loading a nanoapp.
144    */
145   static void encodeLoadNanoappResponse(
146       flatbuffers::FlatBufferBuilder& builder, uint16_t hostClientId,
147       uint32_t transactionId, bool success, uint32_t fragmentId);
148 
149   /**
150    * Encodes a response to the host communicating the result of dynamically
151    * unloading a nanoapp.
152    */
153   static void encodeUnloadNanoappResponse(
154       flatbuffers::FlatBufferBuilder& builder, uint16_t hostClientId,
155       uint32_t transactionId, bool success);
156 
157   /**
158    * Encodes a buffer of log messages to the host.
159    */
160   static void encodeLogMessages(
161       flatbuffers::FlatBufferBuilder& builder, const char *logBuffer,
162       size_t bufferSize);
163 
164   /**
165    * Encodes a string into a DebugDumpData message.
166    *
167    * @param debugStr Null-terminated ASCII string containing debug information
168    * @param debugStrSize Size of the debugStr buffer, including null termination
169    */
170   static void encodeDebugDumpData(
171       flatbuffers::FlatBufferBuilder& builder, uint16_t hostClientId,
172       const char *debugStr, size_t debugStrSize);
173 
174   /**
175    * Encodes the final response to a debug dump request.
176    */
177   static void encodeDebugDumpResponse(
178       flatbuffers::FlatBufferBuilder& builder, uint16_t hostClientId,
179       bool success, uint32_t dataCount);
180 
181   /**
182    * Encodes a message requesting time sync from host.
183    */
184   static void encodeTimeSyncRequest(flatbuffers::FlatBufferBuilder& builder);
185 
186   /**
187    * Encodes a message notifying the host that audio has been requested by a
188    * nanoapp, so the low-power microphone needs to be powered on.
189    */
190   static void encodeLowPowerMicAccessRequest(
191       flatbuffers::FlatBufferBuilder& builder);
192 
193   /**
194    * Encodes a message notifying the host that no nanoapps are requesting audio
195    * anymore, so the low-power microphone may be powered off.
196    */
197   static void encodeLowPowerMicAccessRelease(
198       flatbuffers::FlatBufferBuilder& builder);
199 };
200 
201 }  // namespace chre
202 
203 #endif  // CHRE_PLATFORM_SHARED_HOST_PROTOCOL_CHRE_H_
204