1 /*
2 * Copyright (C) 2016 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 _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_
18 #define _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_
19
20 #include <cstddef>
21 #include <cstdint>
22
23 #include <shared/abort.h>
24
25 /**
26 * NOTE: The MessageType values are manually synced in the GTS Java's
27 * ContextHubTestConstants.java. If you make a change here, be sure
28 * to update ContextHubTestContants.java as well.
29 */
30
31 namespace nanoapp_testing {
32
33 /**
34 * Messages types which are sent between Nanoapps and the Java Host testing
35 * code.
36 */
37 enum class MessageType : uint32_t {
38 /**
39 * Value which should never be used.
40 *
41 * This value starts at CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE.
42 *
43 * This type should never be sent by Host or Nanoapp code.
44 */
45 kInvalidMessageType = 0x0400,
46
47 /**
48 * Test has completed in success.
49 *
50 * This type should only be sent by the Nanoapp code.
51 */
52 kSuccess = 0x0401,
53
54 /**
55 * Indicates a failure in the CHRE implementation.
56 *
57 * This should be followed by null-terminated string
58 * giving details of failure.
59 *
60 * This type should only be sent by the Nanoapp code.
61 */
62 kFailure = 0x0402,
63
64 /**
65 * Indicate a failure within the testing infrastructure.
66 *
67 * This should be followed by null-terminated string
68 * giving details of failure.
69 *
70 * This type should only be sent by the Nanoapp code.
71 */
72 kInternalFailure = 0x0403,
73
74 /**
75 * Indicate a test is being skipped.
76 *
77 * This should be followed by null-terminated string
78 * giving an explanation of why this test was skipped.
79 *
80 * This type should only be sent by the Nanoapp code.
81 */
82 kSkipped = 0x0404,
83
84 /**
85 * A generic message indicating that the test should continue.
86 *
87 * The meaning of this generic message depends on the specific test.
88 * In general, it means something along the lines of "The test is
89 * successful thus far, please proceed to the next stage."
90 *
91 * This type can be sent by the Host or Nanoapp code.
92 */
93 kContinue = 0x0405,
94
95 // Tests wanting to add custom message types for their protocols should
96 // add them below. Remember to update ContextHubTestConstants.java as
97 // well (see NOTE at the top of this header).
98 };
99
100 /**
101 * Sends a message to the host with the given data.
102 *
103 * This method will make a copy of 'data', so there's no need for the
104 * caller to keep that alive after this call.
105 *
106 * Note it may often be more convenient to use one the other methods
107 * when sending a text string.
108 *
109 * @param messageType The type of the message.
110 * @param data The data to send. This can be nullptr, but then 'dataSize'
111 * must be 0.
112 * @param dataSize The number of bytes of 'data' to send. If 'data' is
113 * not 'nullptr', then this must be non-zero.
114 */
115 void sendMessageToHost(MessageType messageType, const void *data = nullptr,
116 size_t dataSize = 0);
117
118 /**
119 * Sends a message to the host, optionally with the 'value' appended as in
120 * hex.
121 *
122 * This method will make a copy of 'message' and 'value', so there's no
123 * need for the caller to keep those alive after this call.
124 *
125 * Note it may often be more convenient to use one of the other methods
126 * below.
127 *
128 * @param messageType The type of the message.
129 * @param message The text of the message. This cannot be nullptr.
130 * @param value Optional, defaults to nullptr. If non-null, this value will
131 * be output as hexadecimal at the end of the message to the host.
132 */
133 void sendStringToHost(MessageType messageType, const char *message,
134 const uint32_t *value = nullptr);
135
136 /**
137 * Same as sendStringToHost(), but using MessageType::kFailure for the 'status'.
138 */
139 inline void sendFailureToHost(const char *message,
140 const uint32_t *value = nullptr) {
141 sendStringToHost(MessageType::kFailure, message, value);
142 }
143
144 /**
145 * Same as sendFailureToHost(), but aborts the test with the given 'reason',
146 * and never returns.
147 */
148 void sendFatalFailureToHost(const char *message,
149 const uint32_t *value = nullptr,
150 AbortBlame reason = AbortBlame::kChre);
151
152 /**
153 * Helper function to invoke sendFatalFailureToHost() with uint8_t type.
154 * It is needed since sendFatalFailureToHost() only accepts uint32_t type.
155 *
156 * TODO: Deprecate this function and redesign sendFatalFailureToHost()
157 * so that a generic string message is accepted.
158 *
159 * @param message a text message to be sent to host.
160 * @param value a value output into the message.
161 */
162 void sendFatalFailureToHostUint8(const char *message, const uint8_t value);
163
164 /**
165 * Same as sendStringToHost(), but uses MessageType::kInternalFailure for the
166 * 'status', and aborts the test with the given 'reason' and never returns.
167 */
168 void sendInternalFailureToHost(const char *message,
169 const uint32_t *value = nullptr,
170 AbortBlame reason = AbortBlame::kTestFramework);
171
172 /**
173 * Invoke sendMessageToHost with MessageType::kSuccess and no other information.
174 */
sendSuccessToHost()175 inline void sendSuccessToHost() {
176 sendMessageToHost(MessageType::kSuccess);
177 }
178
179 } // namespace nanoapp_testing
180
181 #endif // _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_
182
