chre_api/chre/re.h

/*
 * 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_

/**
 * @file
 * 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);

/**
 * Retrieve CHRE's estimate of the time on the host, corresponding to the
 * Android API SystemClock.elapsedRealtimeNanos().
 *
 * A call to this function must not require waking up the host and should return
 * quickly.  The CHRE platform is expected to maintain the ability to estimate
 * the host's clock using its own clock source, for example by applying an
 * offset to the value it would return in chreGetTime().
 *
 * @return An estimate of the current time on the host, accurate to within
 *     +/- 1.5 milliseconds.  This estimate is not guaranteed to be
 *     monotonically increasing, and may move backwards as a result of receiving
 *     new information from the host.
 *
 * @since v1.1
 */
uint64_t chreGetEstimatedHostTime(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_ */