1
2/*
3 * Copyright (C) 2017 The Android Open Source Project
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef CHRE_HOST_HOST_PROTOCOL_HOST_H_
19#define CHRE_HOST_HOST_PROTOCOL_HOST_H_
20
21#include <stdint.h>
22
23#include "chre/platform/shared/host_protocol_common.h"
24#include "chre_host/fragmented_load_transaction.h"
25#include "chre_host/host_messages_generated.h"
26#include "flatbuffers/flatbuffers.h"
27
28#include <vector>
29
30namespace android {
31namespace chre {
32
33/**
34 * Checks that a string encapsulated as a byte vector is null-terminated, and
35 * if it is, returns a pointer to the vector's data. Otherwise returns null.
36 *
37 * @param vec Target vector, can be null
38 *
39 * @return Pointer to the vector's data, or null
40 */
41const char *getStringFromByteVector(const std::vector<int8_t>& vec);
42
43/**
44 * Calling code should provide an implementation of this interface to handle
45 * parsed results from decodeMessageFromChre().
46 */
47class IChreMessageHandlers {
48 public:
49  virtual ~IChreMessageHandlers() = default;
50
51  virtual void handleNanoappMessage(
52      const ::chre::fbs::NanoappMessageT& /*message*/) {};
53
54  virtual void handleHubInfoResponse(
55      const ::chre::fbs::HubInfoResponseT& /*response*/) {};
56
57  virtual void handleNanoappListResponse(
58      const ::chre::fbs::NanoappListResponseT& /*response*/) {};
59
60  virtual void handleLoadNanoappResponse(
61      const ::chre::fbs::LoadNanoappResponseT& /*response*/) {};
62
63  virtual void handleUnloadNanoappResponse(
64      const ::chre::fbs::UnloadNanoappResponseT& /*response*/) {};
65
66  virtual void handleDebugDumpData(
67      const ::chre::fbs::DebugDumpDataT& /*data*/) {};
68
69  virtual void handleDebugDumpResponse(
70      const ::chre::fbs::DebugDumpResponseT& /*response*/) {};
71};
72
73/**
74 * A set of helper methods that simplify the encode/decode of FlatBuffers
75 * messages used in communication with CHRE from the host.
76 */
77class HostProtocolHost : public ::chre::HostProtocolCommon {
78 public:
79  /**
80   * Decodes a message sent from CHRE and invokes the appropriate handler
81   * function in the provided interface implementation to handle the parsed
82   * result.
83   *
84   * @param message Buffer containing a complete FlatBuffers CHRE message
85   * @param messageLen Size of the message, in bytes
86   * @param handlers Set of callbacks to handle the parsed message. If this
87   *        function returns success, then exactly one of these functions was
88   *        called.
89   *
90   * @return true if the message was parsed successfully and passed to a handler
91   */
92  static bool decodeMessageFromChre(const void *message, size_t messageLen,
93                                    IChreMessageHandlers& handlers);
94
95  /**
96   * Encodes a message requesting hub information from CHRE
97   *
98   * @param builder A newly constructed FlatBufferBuilder that will be used to
99   *        construct the message
100   */
101  static void encodeHubInfoRequest(flatbuffers::FlatBufferBuilder& builder);
102
103  /**
104   * Encodes a message requesting to load a nanoapp specified by the included
105   * (possibly fragmented) binary payload and metadata.
106   *
107   * @param builder A newly constructed FlatBufferBuilder that will be used to
108   *        construct the message
109   * @param request The FragmentedLoadRequest object with the binary and the
110   *        metadata
111   */
112  static void encodeFragmentedLoadNanoappRequest(
113      flatbuffers::FlatBufferBuilder& builder,
114      const FragmentedLoadRequest& request);
115
116  /**
117   * Encodes a message requesting the list of loaded nanoapps from CHRE
118   *
119   * @param builder A newly constructed FlatBufferBuilder that will be used to
120   *        construct the message
121   */
122  static void encodeNanoappListRequest(flatbuffers::FlatBufferBuilder& builder);
123
124  /**
125   * Encodes a message requesting to unload a nanoapp specified by app ID.
126   *
127   * @param builder A newly constructed FlatBufferBuilder that will be used to
128   *        construct the message
129   * @param transactionId A transaction identifier to tie the subsequent
130   *        response to this request
131   * @param appId Identifier for the app to unload
132   * @param allowSystemNanoappUnload Whether this request should be allowed to
133   *        result in unloading a system nanoapp (e.g. requests from the context
134   *        hub HAL should have set this to false, as system nanoapps are not
135   *        expected to be managed through that HAL)
136   */
137  static void encodeUnloadNanoappRequest(
138      flatbuffers::FlatBufferBuilder& builder, uint32_t transactionId,
139      uint64_t appId, bool allowSystemNanoappUnload);
140
141  /**
142   * Encodes a message to send the AP timestamp to CHRE
143   *
144   * @param builder A newly constructed FlatBufferBuilder that will be used to
145   *        construct the message
146   * @param offset The AP to SLPI offset in nanoseconds
147   */
148  static void encodeTimeSyncMessage(flatbuffers::FlatBufferBuilder& builder,
149                                    int64_t offset);
150
151  /**
152   * Encodes a message requesting debugging information from CHRE
153   *
154   * @param builder A newly constructed FlatBufferBuilder that will be used to
155   *        construct the message
156   */
157  static void encodeDebugDumpRequest(flatbuffers::FlatBufferBuilder& builder);
158
159  /**
160   * Decodes the host client ID included in the message container
161   *
162   * @param message Buffer containing a complete FlatBuffers CHRE message
163   * @param messageLen Size of the message, in bytes
164   * @param hostClientId Output parameter that will be populated with the client
165   *        ID included in the message on success
166   *
167   * @return true if the host client ID was successfully decoded from the
168   *         message
169   */
170  static bool extractHostClientIdAndType(
171      const void *message, size_t messageLen, uint16_t *hostClientId,
172      ::chre::fbs::ChreMessage *messageType);
173
174  /**
175   * Update the host client ID field in the MessageContainer.
176   *
177   * @param message Buffer containing a complete FlatBuffers CHRE message
178   * @param messageLen Size of the message, in bytes
179   * @param hostClientId The value to set the host client ID to
180   *
181   * @return true if the message was verified successfully, and we were able to
182   *         modify the host client ID field
183   */
184  static bool mutateHostClientId(void *message, size_t messageLen,
185                                 uint16_t hostClientId);
186
187 private:
188  /**
189   * Encodes a message requesting to load a nanoapp specified by the included
190   * binary payload and metadata.
191   *
192   * @param builder A newly constructed FlatBufferBuilder that will be used to
193   *        construct the message
194   */
195  static void encodeLoadNanoappRequest(
196      flatbuffers::FlatBufferBuilder& builder, uint32_t transactionId,
197      uint64_t appId, uint32_t appVersion, uint32_t targetApiVersion,
198      const std::vector<uint8_t>& nanoappBinary, uint32_t fragmentId,
199      size_t appTotalSizeBytes);
200};
201
202}  // namespace chre
203}  // namespace android
204
205#endif  // CHRE_HOST_HOST_PROTOCOL_HOST_H_
206