/*
* Copyright (C) 2016 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _CHRE_RE_H_
#define _CHRE_RE_H_
/**
* Some of the core Runtime Environment utilities of the Context Hub
* Runtime Environment.
*
* This includes functions for memory allocation, logging, and timers.
*/
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* The instance ID for the CHRE.
*
* This ID is used to identify events generated by the CHRE (as
* opposed to events generated by another nanoapp).
*/
#define CHRE_INSTANCE_ID UINT32_C(0)
/**
* A timer ID representing an invalid timer.
*
* This valid is returned by chreTimerSet() if a timer cannot be
* started.
*/
#define CHRE_TIMER_INVALID UINT32_C(-1)
/**
* Logging levels used to indicate severity level of logging messages.
*
* CHRE_LOG_ERROR: Something fatal has happened, i.e. something that will have
* user-visible consequences and won't be recoverable without explicitly
* deleting some data, uninstalling applications, wiping the data
* partitions or reflashing the entire phone (or worse).
* CHRE_LOG_WARN: Something that will have user-visible consequences but is
* likely to be recoverable without data loss by performing some explicit
* action, ranging from waiting or restarting an app all the way to
* re-downloading a new version of an application or rebooting the device.
* CHRE_LOG_INFO: Something interesting to most people happened, i.e. when a
* situation is detected that is likely to have widespread impact, though
* isn't necessarily an error.
* CHRE_LOG_DEBUG: Used to further note what is happening on the device that
* could be relevant to investigate and debug unexpected behaviors. You
* should log only what is needed to gather enough information about what
* is going on about your component.
*
* There is currently no API to turn on/off logging by level, but we anticipate
* adding such in future releases.
*
* @see chreLog
*/
enum chreLogLevel {
CHRE_LOG_ERROR,
CHRE_LOG_WARN,
CHRE_LOG_INFO,
CHRE_LOG_DEBUG
};
/**
* Get the application ID.
*
* The application ID is set by the loader of the nanoapp. This is not
* assured to be unique among all nanoapps running in the system.
*
* @returns The application ID.
*/
uint64_t chreGetAppId(void);
/**
* Get the instance ID.
*
* The instance ID is the CHRE handle to this nanoapp. This is assured
* to be unique among all nanoapps running in the system, and to be
* different from the CHRE_INSTANCE_ID. This is the ID used to communicate
* between nanoapps.
*
* @returns The instance ID
*/
uint32_t chreGetInstanceId(void);
/**
* A method for logging information about the system.
*
* A log entry can have a variety of levels (@see LogLevel). This function
* allows a variable number of arguments, in a printf-style format.
*
* A nanoapp needs to be able to rely upon consistent printf format
* recognition across any platform, and thus we establish formats which
* are required to be handled by every CHRE implementation. Some of the
* integral formats may seem obscure, but this API heavily uses types like
* uint32_t and uint16_t. The platform independent macros for those printf
* formats, like PRId32 or PRIx16, end up using some of these "obscure"
* formats on some platforms, and thus are required.
*
* For the initial N release, our emphasis is on correctly getting information
* into the log, and minimizing the requirements for CHRE implementations
* beyond that. We're not as concerned about how the information is visually
* displayed. As a result, there are a number of format sub-specifiers which
* are "OPTIONAL" for the N implementation. "OPTIONAL" in this context means
* that a CHRE implementation is allowed to essentially ignore the specifier,
* but it must understand the specifier enough in order to properly skip it.
*
* For a nanoapp author, an OPTIONAL format means you might not get exactly
* what you want on every CHRE implementation, but you will always get
* something sane.
*
* To be clearer, here's an example with the OPTIONAL 0-padding for integers
* for different hypothetical CHRE implementations.
* Compliant, chose to implement OPTIONAL format:
* chreLog(level, "%04x", 20) ==> "0014"
* Compliant, chose not to implement OPTIONAL format:
* chreLog(level, "%04x", 20) ==> "14"
* Non-compliant, discarded format because the '0' was assumed to be incorrect:
* chreLog(level, "%04x", 20) ==> ""
*
* Note that some of the OPTIONAL specifiers will probably become
* required in future APIs.
*
* We also have NOT_SUPPORTED specifiers. Nanoapp authors should not use any
* NOT_SUPPORTED specifiers, as unexpected things could happen on any given
* CHRE implementation. A CHRE implementation is allowed to support this
* (for example, when using shared code which already supports this), but
* nanoapp authors need to avoid these.
*
*
* Unless specifically noted as OPTIONAL or NOT_SUPPORTED, format
* (sub-)specifiers listed below are required.
*
* OPTIONAL format sub-specifiers:
* - '-' (left-justify within the given field width)
* - '+' (preceed the result with a '+' sign if it is positive)
* - ' ' (preceed the result with a blank space if no sign is going to be
* output)
* - '#' (For 'o', 'x' or 'X', preceed output with "0", "0x" or "0X",
* respectively. For floating point, unconditionally output a decimal
* point.)
* - '0' (left pad the number with zeroes instead of spaces when <width>
* needs padding)
* - <width> (A number representing the minimum number of characters to be
* output, left-padding with blank spaces if needed to meet the
* minimum)
* - '.'<precision> (A number which has different meaning depending on context.)
* - Integer context: Minimum number of digits to output, padding with
* leading zeros if needed to meet the minimum.
* - 'f' context: Number of digits to output after the decimal
* point (to the right of it).
* - 's' context: Maximum number of characters to output.
*
* Integral format specifiers:
* - 'd' (signed)
* - 'u' (unsigned)
* - 'o' (octal)
* - 'x' (hexadecimal, lower case)
* - 'X' (hexadecimal, upper case)
*
* Integral format sub-specifiers (as prefixes to an above integral format):
* - 'hh' (char)
* - 'h' (short)
* - 'l' (long)
* - 'll' (long long)
* - 'z' (size_t)
* - 't' (ptrdiff_t)
*
* Other format specifiers:
* - 'f' (floating point)
* - 'c' (character)
* - 's' (character string, terminated by '\0')
* - 'p' (pointer)
* - '%' (escaping the percent sign (i.e. "%%" becomes "%"))
*
* NOT_SUPPORTED specifiers:
* - 'n' (output nothing, but fill in a given pointer with the number
* of characters written so far)
* - '*' (indicates that the width/precision value comes from one of the
* arguments to the function)
* - 'e', 'E' (scientific notation output)
* - 'g', 'G' (Shortest floating point representation)
*
* @param level The severity level for this message.
* @param formatStr Either the entirety of the message, or a printf-style
* format string of the format documented above.
* @param ... A variable number of arguments necessary for the given
* 'formatStr' (there may be no additional arguments for some 'formatStr's).
*/
void chreLog(enum chreLogLevel level, const char *formatStr, ...);
/**
* Get the system time.
*
* This returns a time in nanoseconds in reference to some arbitrary
* time in the past. This method is only useful for determining timing
* between events on the system, and is not useful for determining
* any sort of absolute time.
*
* This value must always increase (and must never roll over). This
* value has no meaning across CHRE reboots.
*
* @returns The system time, in nanoseconds.
*/
uint64_t chreGetTime(void);
/**
* Set a timer.
*
* When the timer fires, nanoappHandleEvent will be invoked with
* CHRE_EVENT_TIMER and with the given 'cookie'.
*
* A CHRE implementation is required to provide at least 32
* timers. However, there's no assurance there will be any available
* for any given nanoapp (if it's loaded late, etc).
*
* @param duration Time, in nanoseconds, before the timer fires.
* @param cookie Argument that will be sent to nanoappHandleEvent upon the
* timer firing. This is allowed to be NULL and does not need to be
* a valid pointer (assuming the nanoappHandleEvent code is expecting such).
* @param oneShot If true, the timer will just fire once. If false, the
* timer will continue to refire every 'duration', until this timer is
* canceled (@see chreTimerCancel).
*
* @returns The timer ID. If the system is unable to set a timer
* (no more available timers, etc.) then CHRE_TIMER_INVALID will
* be returned.
*
* @see nanoappHandleEvent
*/
uint32_t chreTimerSet(uint64_t duration, const void* cookie, bool oneShot);
/**
* Cancel a timer.
*
* After this method returns, the CHRE assures there will be no more
* events sent from this timer, and any enqueued events from this timer
* will need to be evicted from the queue by the CHRE.
*
* @param timerId A timer ID obtained by this nanoapp via chreTimerSet().
* @returns true if the timer was cancelled, false otherwise. We may
* fail to cancel the timer if it's a one shot which (just) fired,
* or if the given timer ID is not owned by the calling app.
*/
bool chreTimerCancel(uint32_t timerId);
/**
* Terminate this nanoapp.
*
* This takes effect immediately.
*
* The CHRE will no longer execute this nanoapp. The CHRE will not invoke
* nanoappEnd(), nor will it call any memory free callbacks in the nanoapp.
*
* The CHRE will unload/evict this nanoapp's code.
*
* @param abortCode A value indicating the reason for aborting. (Note that
* in this version of the API, there is no way for anyone to access this
* code, but future APIs may expose it.)
* @returns Never. This method does not return, as the CHRE stops nanoapp
* execution immediately.
*/
void chreAbort(uint32_t abortCode);
/**
* Allocate a given number of bytes from the system heap.
*
* The nanoapp is required to free this memory via chreHeapFree() prior to
* the nanoapp ending.
*
* While the CHRE implementation is required to free up heap resources of
* a nanoapp when unloading it, future requirements and tests focused on
* nanoapps themselves may check for memory leaks, and will require nanoapps
* to properly manage their heap resources.
*
* @param bytes The number of bytes requested.
* @returns A pointer to 'bytes' contiguous bytes of heap memory, or NULL
* if the allocation could not be performed. This pointer must be suitably
* aligned for any kind of variable.
*
* @see chreHeapFree.
*/
void* chreHeapAlloc(uint32_t bytes);
/**
* Free a heap allocation.
*
* This allocation must be from a value returned from a chreHeapAlloc() call
* made by this nanoapp. In other words, it is illegal to free memory
* allocated by another nanoapp (or the CHRE).
*
* @param ptr 'ptr' is required to be a value returned from chreHeapAlloc().
* Note that since chreHeapAlloc can return NULL, CHRE
* implementations must safely handle 'ptr' being NULL.
*
* @see chreHeapAlloc.
*/
void chreHeapFree(void* ptr);
#ifdef __cplusplus
}
#endif
#endif /* _CHRE_RE_H_ */