You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
199 lines
10 KiB
199 lines
10 KiB
/*
|
|
* 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_H_
|
|
#define _CHRE_H_
|
|
|
|
/**
|
|
* @file
|
|
* This header file includes all the headers which combine to fully define the
|
|
* interface for the Context Hub Runtime Environment (CHRE). This interface is
|
|
* of interest to both implementers of CHREs and authors of nanoapps. The API
|
|
* documentation attempts to address concerns of both.
|
|
*
|
|
* See individual header files for API details, and general comments below
|
|
* for overall platform information.
|
|
*/
|
|
|
|
#include <chre/audio.h>
|
|
#include <chre/common.h>
|
|
#include <chre/event.h>
|
|
#include <chre/gnss.h>
|
|
#include <chre/nanoapp.h>
|
|
#include <chre/re.h>
|
|
#include <chre/sensor.h>
|
|
#include <chre/version.h>
|
|
#include <chre/wifi.h>
|
|
#include <chre/wwan.h>
|
|
|
|
/**
|
|
* @mainpage
|
|
* CHRE is the Context Hub Runtime Environment. CHRE is used in Android to run
|
|
* contextual applications, called nanoapps, in a low-power processing domain
|
|
* other than the applications processor that runs Android itself. The CHRE
|
|
* API, documented herein, is the common interface exposed to nanoapps for any
|
|
* compatible CHRE implementation. The CHRE API provides the ability for
|
|
* creating nanoapps that are code-compatible across different CHRE
|
|
* implementations and underlying platforms. Refer to the following sections for
|
|
* a discussion on some important details of CHRE that aren't explicitly exposed
|
|
* in the API itself.
|
|
*
|
|
* @section entry_points Entry points
|
|
*
|
|
* The following entry points are used to bind a nanoapp to the CHRE system, and
|
|
* all three must be implemented by any nanoapp (see chre/nanoapp.h):
|
|
* - nanoappStart: initialization
|
|
* - nanoappHandleEvent: hook for event-driven processing
|
|
* - nanoappEnd: graceful teardown
|
|
*
|
|
* The CHRE implementation must also ensure that it performs these functions
|
|
* prior to invoking nanoappStart, or after nanoappEnd returns:
|
|
* - bss section zeroed out (prior to nanoappStart)
|
|
* - static variables initialized (prior to nanoappStart)
|
|
* - global C++ constructors called (prior to nanoappStart)
|
|
* - global C++ destructors called (after nanoappEnd)
|
|
*
|
|
* @section threading Threading model
|
|
*
|
|
* A CHRE implementation is free to choose among many different
|
|
* threading models, including a single-threaded system or a multi-threaded
|
|
* system with preemption. The current platform definition is agnostic to this
|
|
* underlying choice. However, the CHRE implementation must ensure that time
|
|
* spent executing within a nanoapp does not significantly degrade or otherwise
|
|
* interfere with other functions of the system in which CHRE is implemented,
|
|
* especially latency-sensitive tasks such as sensor event delivery to the AP.
|
|
* In other words, it must ensure that these functions can either occur in
|
|
* parallel or preempt a nanoapp's execution. The current version of the API
|
|
* does not specify whether the implementation allows for CPU sharing between
|
|
* nanoapps on a more granular level than the handling of individual events [1].
|
|
* In any case, event ordering from the perspective of an individual nanoapp
|
|
* must be FIFO, but the CHRE implementation may choose to violate total
|
|
* ordering of events across all nanoapps to achieve more fair resource sharing,
|
|
* but this is not required.
|
|
*
|
|
* This version of the CHRE API does require that all nanoapps are treated as
|
|
* non-reentrant, meaning that only one instance of program flow can be inside
|
|
* an individual nanoapp at any given time. That is, any of the functions of
|
|
* the nanoapp, including the entry points and all other callbacks, cannot be
|
|
* invoked if a previous invocation to the same or any other function in the
|
|
* nanoapp has not completed yet.
|
|
*
|
|
* For example, if a nanoapp is currently in nanoappHandleEvent(), the CHRE is
|
|
* not allowed to call nanoappHandleEvent() again, or to call a memory freeing
|
|
* callback. Similarly, if a nanoapp is currently in a memory freeing
|
|
* callback, the CHRE is not allowed to call nanoappHandleEvent(), or invoke
|
|
* another memory freeing callback.
|
|
*
|
|
* There are two exceptions to this rule: If an invocation of chreSendEvent()
|
|
* fails (returns 'false'), it is allowed to immediately invoke the memory
|
|
* freeing callback passed into that function. This is a rare case, and one
|
|
* where otherwise a CHRE implementation is likely to leak memory. Similarly,
|
|
* chreSendMessageToHost() is allowed to invoke the memory freeing callback
|
|
* directly, whether it returns 'true' or 'false'. This is because the CHRE
|
|
* implementation may copy the message data to its own buffer, and therefore
|
|
* wouldn't need the nanoapp-supplied buffer after chreSendMessageToHost()
|
|
* returns.
|
|
*
|
|
* For a nanoapp author, this means no thought needs to be given to
|
|
* synchronization issues with global objects, as they will, by definition,
|
|
* only be accessed by a single thread at once.
|
|
*
|
|
* [1]: Note to CHRE implementers: A future version of the CHRE platform may
|
|
* require multi-threading with preemption. This is mentioned as a heads up,
|
|
* and to allow implementors deciding between implementation approaches to
|
|
* make the most informed choice.
|
|
*
|
|
* @section timing Timing
|
|
*
|
|
* Nanoapps should expect to be running on a highly constrained system, with
|
|
* little memory and little CPU. Any single nanoapp should expect to
|
|
* be one of several nanoapps on the system, which also share the CPU with the
|
|
* CHRE and possibly other services as well.
|
|
*
|
|
* Thus, a nanoapp needs to be efficient in its memory and CPU usage.
|
|
* Also, as noted in the Threading Model section, a CHRE implementation may
|
|
* be single threaded. As a result, all methods invoked in a nanoapp
|
|
* (like nanoappStart, nanoappHandleEvent, memory free callbacks, etc.)
|
|
* must run "quickly". "Quickly" is difficult to define, as there is a
|
|
* diversity of Context Hub hardware. Nanoapp authors are strongly recommended
|
|
* to limit their application to consuming no more than 1 second of CPU time
|
|
* prior to returning control to the CHRE implementation. A CHRE implementation
|
|
* may consider a nanoapp as unresponsive if it spends more time than this to
|
|
* process a single event, and take corrective action.
|
|
*
|
|
* A nanoapp may have the need to occasionally perform a large block of
|
|
* calculations that exceeds the 1 second guidance. The recommended approach in
|
|
* this case is to split up the large block of calculations into smaller
|
|
* batches. In one call into the nanoapp, the nanoapp can perform the first
|
|
* batch, and then set a timer or send an event (chreSendEvent()) to itself
|
|
* indicating which batch should be done next. This will allow the nanoapp to
|
|
* perform the entire calculation over time, without monopolizing system
|
|
* resources.
|
|
*
|
|
* @section floats Floating point support
|
|
*
|
|
* The C type 'float' is used in this API, and thus a CHRE implementation
|
|
* is required to support 'float's.
|
|
*
|
|
* Support of the C types 'double' and 'long double' is optional for a
|
|
* CHRE implementation. Note that if a CHRE decides to support them, unlike
|
|
* 'float' support, there is no requirement that this support is particularly
|
|
* efficient. So nanoapp authors should be aware this may be inefficient.
|
|
*
|
|
* If a CHRE implementation choses not to support 'double' or
|
|
* 'long double', then the build toolchain setup provided needs to set
|
|
* the preprocessor define CHRE_NO_DOUBLE_SUPPORT.
|
|
*
|
|
* @section compat CHRE and Nanoapp compatibility
|
|
*
|
|
* CHRE implementations must make affordances to maintain binary compatibility
|
|
* across minor revisions of the API version (e.g. v1.1 to v1.2). This applies
|
|
* to both running a nanoapp compiled for a newer version of the API on a CHRE
|
|
* implementation built against an older version (backwards compatibility), and
|
|
* vice versa (forwards compatibility). API changes that are acceptable in
|
|
* minor version changes that may require special measures to ensure binary
|
|
* compatibility include: addition of new functions; addition of arguments to
|
|
* existing functions when the default value used for nanoapps compiled against
|
|
* the old version is well-defined and does not affect existing functionality;
|
|
* and addition of fields to existing structures, even when this induces a
|
|
* binary layout change (this should be made rare via judicious use of reserved
|
|
* fields). API changes that must only occur alongside a major version change
|
|
* and are therefore not compatible include: removal of any function, argument,
|
|
* field in a data structure, or mandatory functional behavior that a nanoapp
|
|
* may depend on; any change in the interpretation of an existing data structure
|
|
* field that alters the way it was defined previously (changing the units of a
|
|
* field would fall under this, but appropriating a previously reserved field
|
|
* for some new functionality would not); and any change in functionality or
|
|
* expected behavior that conflicts with the previous definition.
|
|
*
|
|
* Note that the CHRE API only specifies the software interface between a
|
|
* nanoapp and the CHRE system - the binary interface (ABI) between nanoapp and
|
|
* CHRE is necessarily implementation-dependent. Therefore, the recommended
|
|
* approach to accomplish binary compatibility is to build a Nanoapp Support
|
|
* Library (NSL) that is specific to the CHRE implementation into the nanoapp
|
|
* binary, and use it to handle ABI details in a way that ensures compatibility.
|
|
* In addition, to accomplish forwards compatibility, the CHRE implementation is
|
|
* expected to recognize the CHRE API version that a nanoapp is targeting and
|
|
* engage compatibility behaviors where necessary.
|
|
*
|
|
* By definition, major API version changes (e.g. v1.1 to v2.0) break
|
|
* compatibility. Therefore, a CHRE implementation must not attempt to load a
|
|
* nanoapp that is targeting a newer major API version.
|
|
*/
|
|
|
|
#endif /* _CHRE_H_ */
|
|
|