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 // IWYU pragma: private, include "chre_api/chre.h" 18 // IWYU pragma: friend chre/.*\.h 19 20 #ifndef _CHRE_COMMON_H_ 21 #define _CHRE_COMMON_H_ 22 23 /** 24 * @file 25 * Definitions shared across multiple CHRE header files 26 */ 27 28 #include <stdbool.h> 29 #include <stdint.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * Mask of the 5 most significant bytes in a 64-bit nanoapp or CHRE platform 37 * identifier, which represents the vendor ID portion of the ID. 38 */ 39 #define CHRE_VENDOR_ID_MASK UINT64_C(0xFFFFFFFFFF000000) 40 41 /** 42 * Vendor ID "Googl". Used in nanoapp IDs and CHRE platform IDs developed and 43 * released by Google. 44 */ 45 #define CHRE_VENDOR_ID_GOOGLE UINT64_C(0x476F6F676C000000) 46 47 /** 48 * Vendor ID "GoogT". Used for nanoapp IDs associated with testing done by 49 * Google. 50 */ 51 #define CHRE_VENDOR_ID_GOOGLE_TEST UINT64_C(0x476F6F6754000000) 52 53 /** 54 * Helper macro to mask off all bytes other than the vendor ID (most significant 55 * 5 bytes) in 64-bit nanoapp and CHRE platform identifiers. 56 * 57 * @see chreGetNanoappInfo() 58 * @see chreGetPlatformId() 59 */ 60 #define CHRE_EXTRACT_VENDOR_ID(id) ((id) & CHRE_VENDOR_ID_MASK) 61 62 /** 63 * Number of nanoseconds in one second, represented as an unsigned 64-bit 64 * integer 65 */ 66 #define CHRE_NSEC_PER_SEC UINT64_C(1000000000) 67 68 /** 69 * General timeout for asynchronous API requests. Unless specified otherwise, a 70 * function call that returns data asynchronously via an event, such as 71 * CHRE_EVENT_ASYNC_GNSS_RESULT, must do so within this amount of time. 72 */ 73 #define CHRE_ASYNC_RESULT_TIMEOUT_NS (5 * CHRE_NSEC_PER_SEC) 74 75 /** 76 * A generic listing of error codes for use in {@link #chreAsyncResult} and 77 * elsewhere. In general, module-specific error codes may be added to this enum, 78 * but effort should be made to come up with a generic name that still captures 79 * the meaning of the error. 80 */ 81 // LINT.IfChange 82 enum chreError { 83 //! No error occurred 84 CHRE_ERROR_NONE = 0, 85 86 //! An unspecified failure occurred 87 CHRE_ERROR = 1, 88 89 //! One or more supplied arguments are invalid 90 CHRE_ERROR_INVALID_ARGUMENT = 2, 91 92 //! Unable to satisfy request because the system is busy 93 CHRE_ERROR_BUSY = 3, 94 95 //! Unable to allocate memory 96 CHRE_ERROR_NO_MEMORY = 4, 97 98 //! The requested feature is not supported 99 CHRE_ERROR_NOT_SUPPORTED = 5, 100 101 //! A timeout occurred while processing the request 102 CHRE_ERROR_TIMEOUT = 6, 103 104 //! The relevant capability is disabled, for example due to a user 105 //! configuration that takes precedence over this request 106 CHRE_ERROR_FUNCTION_DISABLED = 7, 107 108 //! The request was rejected due to internal rate limiting of the requested 109 //! functionality - the client may try its request again after waiting an 110 //! unspecified amount of time 111 CHRE_ERROR_REJECTED_RATE_LIMIT = 8, 112 113 //! The requested functionality is not currently accessible from the CHRE, 114 //! because another client, such as the main applications processor, is 115 //! currently controlling it. 116 CHRE_ERROR_FUNCTION_RESTRICTED_TO_OTHER_MASTER = 9, 117 CHRE_ERROR_FUNCTION_RESTRICTED_TO_OTHER_CLIENT = 9, 118 119 //! This request is no longer valid. It may have been replaced by a newer 120 //! request before taking effect. 121 //! @since v1.6 122 CHRE_ERROR_OBSOLETE_REQUEST = 10, 123 124 //! A transient error occurred. The request can be retried. 125 //! @since v1.10 126 CHRE_ERROR_TRANSIENT = 11, 127 128 //! Unable to satisfy request because of missing permissions. 129 //! @since v1.10 130 CHRE_ERROR_PERMISSION_DENIED = 12, 131 132 //! Unable to satisfy request because the destination is not found. 133 //! @since v1.10 134 CHRE_ERROR_DESTINATION_NOT_FOUND = 13, 135 136 //!< Do not exceed this value when adding new error codes 137 CHRE_ERROR_LAST = UINT8_MAX, 138 }; 139 // LINT.ThenChange(../../../../core/include/chre/core/api_manager_common.h) 140 141 /** 142 * Generic data structure to indicate the result of an asynchronous operation. 143 * 144 * @note 145 * The general model followed by CHRE for asynchronous operations is that a 146 * request function returns a boolean value that indicates whether the request 147 * was accepted for further processing. The actual result of the operation is 148 * provided in a subsequent event sent with an event type that is defined in the 149 * specific API. Typically, a "cookie" parameter is supplied to allow the client 150 * to tie the response to a specific request, or pass data through, etc. The 151 * response is expected to be delivered within CHRE_ASYNC_RESULT_TIMEOUT_NS if 152 * not specified otherwise. 153 * 154 * The CHRE implementation must allow for multiple asynchronous requests to be 155 * outstanding at a given time, under reasonable resource constraints. Further, 156 * requests must be processed in the same order as supplied by the client of the 157 * API in order to maintain causality. Using GNSS as an example, if a client 158 * calls chreGnssLocationSessionStartAsync() and then immediately calls 159 * chreGnssLocationSessionStopAsync(), the final result must be that the 160 * location session is stopped. Whether requests always complete in the 161 * order that they are given is implementation-defined. For example, if a client 162 * calls chreGnssLocationSessionStart() and then immediately calls 163 * chreGnssMeasurementSessionStart(), it is possible for the 164 * CHRE_EVENT_GNSS_RESULT associated with the measurement session to be 165 * delivered before the one for the location session. 166 */ 167 struct chreAsyncResult { 168 //! Indicates the request associated with this result. The interpretation of 169 //! values in this field is dependent upon the event type provided when this 170 //! result was delivered. 171 uint8_t requestType; 172 173 //! Set to true if the request was successfully processed 174 bool success; 175 176 //! If the request failed (success is false), this is set to a value from 177 //! enum chreError (other than CHRE_ERROR_NONE), which may provide 178 //! additional information about the nature of the failure. 179 //! @see #chreError 180 uint8_t errorCode; 181 182 //! Reserved for future use, set to 0 183 uint8_t reserved; 184 185 //! Set to the cookie parameter given to the request function tied to this 186 //! result 187 const void *cookie; 188 }; 189 190 /** 191 * A structure to store an event describing the end of batched events. 192 * 193 * @since v1.8 194 */ 195 struct chreBatchCompleteEvent { 196 //! Indicates the type of event (of type CHRE_EVENT_TYPE_*) that was 197 //! batched. 198 uint16_t eventType; 199 200 //! Reserved for future use, set to 0 201 uint8_t reserved[2]; 202 }; 203 204 #ifdef __cplusplus 205 } 206 #endif 207 208 #endif /* _CHRE_COMMON_H_ */ 209