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