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