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 enum chreError { 80 //! No error occurred 81 CHRE_ERROR_NONE = 0, 82 83 //! An unspecified failure occurred 84 CHRE_ERROR = 1, 85 86 //! One or more supplied arguments are invalid 87 CHRE_ERROR_INVALID_ARGUMENT = 2, 88 89 //! Unable to satisfy request because the system is busy 90 CHRE_ERROR_BUSY = 3, 91 92 //! Unable to allocate memory 93 CHRE_ERROR_NO_MEMORY = 4, 94 95 //! The requested feature is not supported 96 CHRE_ERROR_NOT_SUPPORTED = 5, 97 98 //! A timeout occurred while processing the request 99 CHRE_ERROR_TIMEOUT = 6, 100 101 //! The relevant capability is disabled, for example due to a user 102 //! configuration that takes precedence over this request 103 CHRE_ERROR_FUNCTION_DISABLED = 7, 104 105 //! The request was rejected due to internal rate limiting of the requested 106 //! functionality - the client may try its request again after waiting an 107 //! unspecified amount of time 108 CHRE_ERROR_REJECTED_RATE_LIMIT = 8, 109 110 //! The requested functionality is not currently accessible from the CHRE, 111 //! because another master, such as the main applications processor, is 112 //! currently controlling it. 113 CHRE_ERROR_FUNCTION_RESTRICTED_TO_OTHER_MASTER = 9, 114 115 //!< Do not exceed this value when adding new error codes 116 CHRE_ERROR_LAST = UINT8_MAX, 117 }; 118 119 /** 120 * Generic data structure to indicate the result of an asynchronous operation. 121 * 122 * @note 123 * The general model followed by CHRE for asynchronous operations is that a 124 * request function returns a boolean value that indicates whether the request 125 * was accepted for further processing. The actual result of the operation is 126 * provided in a subsequent event sent with an event type that is defined in the 127 * specific API. Typically, a "cookie" parameter is supplied to allow the client 128 * to tie the response to a specific request, or pass data through, etc. The 129 * response is expected to be delivered within CHRE_ASYNC_RESULT_TIMEOUT_NS if 130 * not specified otherwise. 131 * 132 * The CHRE implementation must allow for multiple asynchronous requests to be 133 * outstanding at a given time, under reasonable resource constraints. Further, 134 * requests must be processed in the same order as supplied by the client of the 135 * API in order to maintain causality. Using GNSS as an example, if a client 136 * calls chreGnssLocationSessionStartAsync() and then immediately calls 137 * chreGnssLocationSessionStopAsync(), the final result must be that the 138 * location session is stopped. Whether requests always complete in the 139 * order that they are given is implementation-defined. For example, if a client 140 * calls chreGnssLocationSessionStart() and then immediately calls 141 * chreGnssMeasurementSessionStart(), it is possible for the 142 * CHRE_EVENT_GNSS_RESULT associated with the measurement session to be 143 * delivered before the one for the location session. 144 */ 145 struct chreAsyncResult { 146 //! Indicates the request associated with this result. The interpretation of 147 //! values in this field is dependent upon the event type provided when this 148 //! result was delivered. 149 uint8_t requestType; 150 151 //! Set to true if the request was successfully processed 152 bool success; 153 154 //! If the request failed (success is false), this is set to a value from 155 //! enum chreError (other than CHRE_ERROR_NONE), which may provide 156 //! additional information about the nature of the failure. 157 //! @see #chreError 158 uint8_t errorCode; 159 160 //! Reserved for future use, set to 0 161 uint8_t reserved; 162 163 //! Set to the cookie parameter given to the request function tied to this 164 //! result 165 const void *cookie; 166 }; 167 168 169 #ifdef __cplusplus 170 } 171 #endif 172 173 #endif /* _CHRE_COMMON_H_ */ 174
