1e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/* 2e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Copyright (C) 2016 The Android Open Source Project 3e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 4e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Licensed under the Apache License, Version 2.0 (the "License"); 5e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * you may not use this file except in compliance with the License. 6e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * You may obtain a copy of the License at 7e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 8e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * http://www.apache.org/licenses/LICENSE-2.0 9e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 10e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Unless required by applicable law or agreed to in writing, software 11e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * distributed under the License is distributed on an "AS IS" BASIS, 12e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * See the License for the specific language governing permissions and 14e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * limitations under the License. 15e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 16e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 17e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#ifndef _CHRE_RE_H_ 18e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#define _CHRE_RE_H_ 19e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 20e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 216bb73b09cc327ecbfede8cb7657d93cecb57e159Brian Duddie * @file 22e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Some of the core Runtime Environment utilities of the Context Hub 23e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Runtime Environment. 24e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 25e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This includes functions for memory allocation, logging, and timers. 26e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 27e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 28e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include <stdarg.h> 29e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include <stdbool.h> 30e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include <stdint.h> 31e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include <stdlib.h> 32e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 33e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#ifdef __cplusplus 34e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieextern "C" { 35e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#endif 36e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 37e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 38e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The instance ID for the CHRE. 39e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 40e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This ID is used to identify events generated by the CHRE (as 41e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * opposed to events generated by another nanoapp). 42e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 43e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#define CHRE_INSTANCE_ID UINT32_C(0) 44e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 45e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 46e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * A timer ID representing an invalid timer. 47e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 48e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This valid is returned by chreTimerSet() if a timer cannot be 49e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * started. 50e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 51e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#define CHRE_TIMER_INVALID UINT32_C(-1) 52e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 53e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 54e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 55e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Logging levels used to indicate severity level of logging messages. 56e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 57e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE_LOG_ERROR: Something fatal has happened, i.e. something that will have 58e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * user-visible consequences and won't be recoverable without explicitly 59e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * deleting some data, uninstalling applications, wiping the data 60e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * partitions or reflashing the entire phone (or worse). 61e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE_LOG_WARN: Something that will have user-visible consequences but is 62e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * likely to be recoverable without data loss by performing some explicit 63e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * action, ranging from waiting or restarting an app all the way to 64e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * re-downloading a new version of an application or rebooting the device. 65e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE_LOG_INFO: Something interesting to most people happened, i.e. when a 66e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * situation is detected that is likely to have widespread impact, though 67e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * isn't necessarily an error. 68e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE_LOG_DEBUG: Used to further note what is happening on the device that 69e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * could be relevant to investigate and debug unexpected behaviors. You 70e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * should log only what is needed to gather enough information about what 71e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * is going on about your component. 72e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 73e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * There is currently no API to turn on/off logging by level, but we anticipate 74e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * adding such in future releases. 75e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 76e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see chreLog 77e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 78e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieenum chreLogLevel { 79e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie CHRE_LOG_ERROR, 80e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie CHRE_LOG_WARN, 81e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie CHRE_LOG_INFO, 82e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie CHRE_LOG_DEBUG 83e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie}; 84e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 85e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 86e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 87e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Get the application ID. 88e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 89e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The application ID is set by the loader of the nanoapp. This is not 90e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * assured to be unique among all nanoapps running in the system. 91e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 92e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns The application ID. 93e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 94e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieuint64_t chreGetAppId(void); 95e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 96e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 97e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Get the instance ID. 98e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 99e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The instance ID is the CHRE handle to this nanoapp. This is assured 100e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * to be unique among all nanoapps running in the system, and to be 101e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * different from the CHRE_INSTANCE_ID. This is the ID used to communicate 102e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * between nanoapps. 103e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 104e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns The instance ID 105e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 106e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieuint32_t chreGetInstanceId(void); 107e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 108e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 109e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * A method for logging information about the system. 110e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 111e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * A log entry can have a variety of levels (@see LogLevel). This function 112e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * allows a variable number of arguments, in a printf-style format. 113e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 114e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * A nanoapp needs to be able to rely upon consistent printf format 115e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * recognition across any platform, and thus we establish formats which 116e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * are required to be handled by every CHRE implementation. Some of the 117e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * integral formats may seem obscure, but this API heavily uses types like 118e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * uint32_t and uint16_t. The platform independent macros for those printf 119e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * formats, like PRId32 or PRIx16, end up using some of these "obscure" 120e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * formats on some platforms, and thus are required. 121e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 122e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * For the initial N release, our emphasis is on correctly getting information 123e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * into the log, and minimizing the requirements for CHRE implementations 124e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * beyond that. We're not as concerned about how the information is visually 125e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * displayed. As a result, there are a number of format sub-specifiers which 126e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * are "OPTIONAL" for the N implementation. "OPTIONAL" in this context means 127e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * that a CHRE implementation is allowed to essentially ignore the specifier, 128e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * but it must understand the specifier enough in order to properly skip it. 129e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 130e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * For a nanoapp author, an OPTIONAL format means you might not get exactly 131e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * what you want on every CHRE implementation, but you will always get 132e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * something sane. 133e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 134e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * To be clearer, here's an example with the OPTIONAL 0-padding for integers 135e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * for different hypothetical CHRE implementations. 136e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Compliant, chose to implement OPTIONAL format: 137e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * chreLog(level, "%04x", 20) ==> "0014" 138e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Compliant, chose not to implement OPTIONAL format: 139e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * chreLog(level, "%04x", 20) ==> "14" 140e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Non-compliant, discarded format because the '0' was assumed to be incorrect: 141e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * chreLog(level, "%04x", 20) ==> "" 142e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 143e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Note that some of the OPTIONAL specifiers will probably become 144e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * required in future APIs. 145e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 146e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * We also have NOT_SUPPORTED specifiers. Nanoapp authors should not use any 147e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * NOT_SUPPORTED specifiers, as unexpected things could happen on any given 148e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE implementation. A CHRE implementation is allowed to support this 149e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * (for example, when using shared code which already supports this), but 150e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * nanoapp authors need to avoid these. 151e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 152e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 153e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Unless specifically noted as OPTIONAL or NOT_SUPPORTED, format 154e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * (sub-)specifiers listed below are required. 155e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 156e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * OPTIONAL format sub-specifiers: 157e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '-' (left-justify within the given field width) 158e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '+' (preceed the result with a '+' sign if it is positive) 159e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - ' ' (preceed the result with a blank space if no sign is going to be 160e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * output) 161e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '#' (For 'o', 'x' or 'X', preceed output with "0", "0x" or "0X", 162e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * respectively. For floating point, unconditionally output a decimal 163e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * point.) 164e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '0' (left pad the number with zeroes instead of spaces when <width> 165e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * needs padding) 166e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - <width> (A number representing the minimum number of characters to be 167e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * output, left-padding with blank spaces if needed to meet the 168e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * minimum) 169e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '.'<precision> (A number which has different meaning depending on context.) 170e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - Integer context: Minimum number of digits to output, padding with 171e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * leading zeros if needed to meet the minimum. 172e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'f' context: Number of digits to output after the decimal 173e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * point (to the right of it). 174e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 's' context: Maximum number of characters to output. 175e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 176e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Integral format specifiers: 177e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'd' (signed) 178e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'u' (unsigned) 179e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'o' (octal) 180e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'x' (hexadecimal, lower case) 181e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'X' (hexadecimal, upper case) 182e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 183e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Integral format sub-specifiers (as prefixes to an above integral format): 184e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'hh' (char) 185e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'h' (short) 186e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'l' (long) 187e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'll' (long long) 188e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'z' (size_t) 189e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 't' (ptrdiff_t) 190e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 191e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Other format specifiers: 192e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'f' (floating point) 193e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'c' (character) 194e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 's' (character string, terminated by '\0') 195e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'p' (pointer) 196e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '%' (escaping the percent sign (i.e. "%%" becomes "%")) 197e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 198e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * NOT_SUPPORTED specifiers: 199e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'n' (output nothing, but fill in a given pointer with the number 200e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * of characters written so far) 201e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - '*' (indicates that the width/precision value comes from one of the 202e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * arguments to the function) 203e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'e', 'E' (scientific notation output) 204e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * - 'g', 'G' (Shortest floating point representation) 205e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 206e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param level The severity level for this message. 207e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param formatStr Either the entirety of the message, or a printf-style 208e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * format string of the format documented above. 209e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param ... A variable number of arguments necessary for the given 210e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 'formatStr' (there may be no additional arguments for some 'formatStr's). 211e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 212e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddievoid chreLog(enum chreLogLevel level, const char *formatStr, ...); 213e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 214e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 215e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Get the system time. 216e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 217e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This returns a time in nanoseconds in reference to some arbitrary 218e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * time in the past. This method is only useful for determining timing 219e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * between events on the system, and is not useful for determining 220e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * any sort of absolute time. 221e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 222e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This value must always increase (and must never roll over). This 223e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * value has no meaning across CHRE reboots. 224e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 225e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns The system time, in nanoseconds. 226e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 227e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieuint64_t chreGetTime(void); 228e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 229e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 230e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Set a timer. 231e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 232e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * When the timer fires, nanoappHandleEvent will be invoked with 233e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * CHRE_EVENT_TIMER and with the given 'cookie'. 234e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 235e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * A CHRE implementation is required to provide at least 32 236e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * timers. However, there's no assurance there will be any available 237e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * for any given nanoapp (if it's loaded late, etc). 238e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 239e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param duration Time, in nanoseconds, before the timer fires. 240e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param cookie Argument that will be sent to nanoappHandleEvent upon the 241e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * timer firing. This is allowed to be NULL and does not need to be 242e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * a valid pointer (assuming the nanoappHandleEvent code is expecting such). 243e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param oneShot If true, the timer will just fire once. If false, the 244e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * timer will continue to refire every 'duration', until this timer is 245e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * canceled (@see chreTimerCancel). 246e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 247e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns The timer ID. If the system is unable to set a timer 248e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * (no more available timers, etc.) then CHRE_TIMER_INVALID will 249e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * be returned. 250e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 251e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see nanoappHandleEvent 252e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 2536bb73b09cc327ecbfede8cb7657d93cecb57e159Brian Duddieuint32_t chreTimerSet(uint64_t duration, const void *cookie, bool oneShot); 254e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 255e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 256e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Cancel a timer. 257e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 258e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * After this method returns, the CHRE assures there will be no more 259e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * events sent from this timer, and any enqueued events from this timer 260e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * will need to be evicted from the queue by the CHRE. 261e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 262e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param timerId A timer ID obtained by this nanoapp via chreTimerSet(). 263e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns true if the timer was cancelled, false otherwise. We may 264e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * fail to cancel the timer if it's a one shot which (just) fired, 265e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * or if the given timer ID is not owned by the calling app. 266e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 267e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddiebool chreTimerCancel(uint32_t timerId); 268e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 269e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 270e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Terminate this nanoapp. 271e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 272e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This takes effect immediately. 273e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 274e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The CHRE will no longer execute this nanoapp. The CHRE will not invoke 275e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * nanoappEnd(), nor will it call any memory free callbacks in the nanoapp. 276e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 277e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The CHRE will unload/evict this nanoapp's code. 278e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 279e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param abortCode A value indicating the reason for aborting. (Note that 280e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * in this version of the API, there is no way for anyone to access this 281e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * code, but future APIs may expose it.) 282e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns Never. This method does not return, as the CHRE stops nanoapp 283e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * execution immediately. 284e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 285e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddievoid chreAbort(uint32_t abortCode); 286e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 287e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 288e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Allocate a given number of bytes from the system heap. 289e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 290e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The nanoapp is required to free this memory via chreHeapFree() prior to 291e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * the nanoapp ending. 292e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 293e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * While the CHRE implementation is required to free up heap resources of 294e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * a nanoapp when unloading it, future requirements and tests focused on 295e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * nanoapps themselves may check for memory leaks, and will require nanoapps 296e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * to properly manage their heap resources. 297e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 298e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param bytes The number of bytes requested. 299e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @returns A pointer to 'bytes' contiguous bytes of heap memory, or NULL 300e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * if the allocation could not be performed. This pointer must be suitably 301e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * aligned for any kind of variable. 302e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 303e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see chreHeapFree. 304e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 3056bb73b09cc327ecbfede8cb7657d93cecb57e159Brian Duddievoid *chreHeapAlloc(uint32_t bytes); 306e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 307e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 308e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Free a heap allocation. 309e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 310e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This allocation must be from a value returned from a chreHeapAlloc() call 311e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * made by this nanoapp. In other words, it is illegal to free memory 312e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * allocated by another nanoapp (or the CHRE). 313e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 314e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param ptr 'ptr' is required to be a value returned from chreHeapAlloc(). 315e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Note that since chreHeapAlloc can return NULL, CHRE 316e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * implementations must safely handle 'ptr' being NULL. 317e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 318e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see chreHeapAlloc. 319e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 3206bb73b09cc327ecbfede8cb7657d93cecb57e159Brian Duddievoid chreHeapFree(void *ptr); 321e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 322e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 323e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#ifdef __cplusplus 324e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie} 325e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#endif 326e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 327e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#endif /* _CHRE_RE_H_ */ 328e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 329