fuquan/allwinner_a64
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

upload android base code part6

Browse source
This commit is contained in:
August 2018-08-08 17:48:24 +08:00
parent 421e214c7d
commit 4e516ec6ed
35396 changed files with 9188716 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
android/system/chre/chre_api/legacy/README.md Normal file
View file

@ -0,0 +1,2 @@
This folder contains prior versions of the CHRE API, intended for reference
purposes.

161
android/system/chre/chre_api/legacy/v1_0/chre.h Normal file
View file

@ -0,0 +1,161 @@
/*
* 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_
/**
* This header file includes all the headers which combine to fully defined
* the interface for the Context Hub Runtime Environment (CHRE). This is the
* environment in which a nanoapp runs.
*
* This interface is of interest to both implementors of CHREs and
* authors of nanoapps. The API documentation attempts to address concerns
* of both.
*
* See individual header files for API specific, and general comments below
* for overall platform information.
*/
#include <chre/event.h>
#include <chre/nanoapp.h>
#include <chre/re.h>
#include <chre/sensor.h>
#include <chre/version.h>
/**
* Entry points.
*
* The following entry points are required to be handled by the CHRE
* implementation, and the functions must all be implemented by nanoapps.
* o nanoappStart function (see chre_nanoapp.h)
* o nanoappHandleEvent function (see chre_nanoapp.h)
* o nanoappEnd function (see chre_nanoapp.h)
* o bss section zeroed out (prior to nanoappStart)
* o static variables initialized (prior to nanoappStart)
* o global C++ constructors called (prior to nanoappStart)
* o global C++ destructors called (after nanoappEnd)
*/
/**
* Threading model.
*
* A CHRE implementation is free to chose 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 [1].
*
* However, the Platform does require that all nanoapps are treated as
* non-reentrant. That is, any of the functions of the nanoapp, including
* the entry points defined above and the memory freeing callbacks defined
* below, cannot be invoked by the CHRE if a previous invocation
* hasn't completed. Note this means no nanoapp function can be invoked
* from an interrupt context.
*
* 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 implementors: 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.
*/
/**
* Notes on 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. For Android N, there is no firm
* definition of "quickly", but expect this term to gain definition in
* future releases as we get feedback from partners.
*
* In order to write a nanoapp that will be able to adopt to future
* stricter notions of "quickly", all nanoapp methods should be written so
* they execute in a small amount of time. Some nanoapps may have the need
* to occasionally perform a large block of calculations, which may seem
* to violate this. 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
* 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.
*/
/**
* 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.
*/
/**
* CHRE and Nanoapp compatibility.
*
* The Android N release introduces the first version of this API.
* It is anticipated that there will be a lot of feedback from
* Android partners on this initial API. To allow more flexibility
* in addressing that feedback, there is no plan to assure
* binary compatibility between the Android N and Android O CHRE
* implementations and nanoapps.
*
* That is, a nanoapp built with the Android O version of this
* API should not expect to run on a CHRE built with
* the Android N API. Similarly, a nanoapp build with the
* Android N API should not expect to run on a CHRE
* build with the Android O API. Such a nanoapp will need to
* recompiled with the appropriate API in order to work.
*/
#endif /* _CHRE_H_ */

273
android/system/chre/chre_api/legacy/v1_0/chre/event.h Normal file
View file

@ -0,0 +1,273 @@
/*
* 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_EVENT_H_
#define _CHRE_EVENT_H_
/**
* Context Hub Runtime Environment API dealing with events and messages.
*/
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* The CHRE implementation is required to provide the following
* preprocessor defines via the build system.
*
* CHRE_MESSAGE_TO_HOST_MAX_SIZE: The maximum size, in bytes, allowed for
* a message sent to chreSendMessageToHost(). This must be at least
* CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE.
*/
#ifndef CHRE_MESSAGE_TO_HOST_MAX_SIZE
#error CHRE_MESSAGE_TO_HOST_MAX_SIZE must be defined by the Context Hub Runtime Environment implementation
#endif
/**
* The minimum size, in bytes, any CHRE implementation will
* use for CHRE_MESSAGE_TO_HOST_MAX_SIZE.
*/
#define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE 128
#if CHRE_MESSAGE_TO_HOST_MAX_SIZE < CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE
#error CHRE_MESSAGE_TO_HOST_MAX_SIZE is too small.
#endif
/**
* The lowest numerical value legal for a user-defined event.
*
* The system reserves all event values from 0 to 0x7FFF, inclusive.
* User events may use any value in the range 0x8000 to 0xFFFF, inclusive.
*
* Note that the same event values might be used by different nanoapps
* for different meanings. This is not a concern, as these values only
* have meaning when paired with the originating nanoapp.
*/
#define CHRE_EVENT_FIRST_USER_VALUE UINT16_C(0x8000)
/**
* nanoappHandleEvent argument: struct chreMessageFromHostData
*
* The format of the 'message' part of this structure is left undefined,
* and it's up to the nanoapp and host to have an established protocol
* beforehand.
*/
#define CHRE_EVENT_MESSAGE_FROM_HOST UINT16_C(0x0001)
/**
* nanoappHandleEvent argument: 'cookie' given to chreTimerSet() method.
*
* Indicates that a timer has elapsed, in accordance with how chreTimerSet() was
* invoked.
*/
#define CHRE_EVENT_TIMER UINT16_C(0x0002)
/**
* First possible value for CHRE_EVENT_SENSOR events.
*
* This allows us to separately define our CHRE_EVENT_SENSOR_* events in
* chre_sensor.h, without fear of collision with other event values.
*/
#define CHRE_EVENT_SENSOR_FIRST_EVENT UINT16_C(0x0100)
/**
* Last possible value for CHRE_EVENT_SENSOR events.
*
* This allows us to separately define our CHRE_EVENT_SENSOR_* events in
* chre_sensor.h, without fear of collision with other event values.
*/
#define CHRE_EVENT_SENSOR_LAST_EVENT UINT16_C(0x02FF)
/**
* First in a range of values dedicated for internal CHRE implementation usage.
*
* If a CHRE wishes to use events internally, any values within this range
* are assured not to be taken by future CHRE API additions.
*/
#define CHRE_EVENT_INTERNAL_FIRST_EVENT UINT16_C(0x7E00)
/**
* Last in a range of values dedicated for internal CHRE implementation usage.
*
* If a CHRE wishes to use events internally, any values within this range
* are assured not to be taken by future CHRE API additions.
*/
#define CHRE_EVENT_INTERNAL_LAST_EVENT UINT16_C(0x7FFF)
/**
* CHRE_EVENT_MESSAGE_FROM_HOST
*/
struct chreMessageFromHostData {
/**
* Message type (NOTE: not implemented correctly in the Android N release).
*
* In future releases, this will be a message type provided by the host.
*/
uint32_t reservedMessageType;
/**
* The size, in bytes of the following 'message'.
*
* This can be 0.
*/
uint32_t messageSize;
/**
* The message from the host.
*
* These contents are of a format that the host and nanoapp must have
* established beforehand.
*
* This data is 'messageSize' bytes in length. Note that if 'messageSize'
* is 0, this might be NULL.
*/
const void *message;
};
/**
* Callback which frees data associated with an event.
*
* This callback is (optionally) provided to the chreSendEvent() method as
* a means for freeing the event data and performing any other cleanup
* necessary when the event is completed. When this callback is invoked,
* 'eventData' is no longer needed and can be released.
*
* @param eventType The 'eventType' argument from chreSendEvent().
* @param eventData The 'eventData' argument from chreSendEvent().
*
* @see chreSendEvent
*/
typedef void (chreEventCompleteFunction)(uint16_t eventType, void *eventData);
/**
* Callback which frees a message.
*
* This callback is (optionally) provided to the chreSendMessageToHost() method
* as a means for freeing the message. When this callback is invoked,
* 'message' is no longer needed and can be released. Note that this in
* no way assures that said message did or did not make it to the host, simply
* that this memory is no longer needed.
*
* @param message The 'message' argument from chreSendMessageToHost().
* @param messageSize The 'messageSize' argument from chreSendMessageToHost().
*
* @see chreSendMessageToHost
*/
typedef void (chreMessageFreeFunction)(void *message, size_t messageSize);
/**
* Enqueue an event to be sent to another nanoapp.
*
* Note: This version of the API does not give an easy means to discover
* another nanoapp's instance ID. For now, events will need to be sent to/from
* the host to initially discover these IDs.
*
* @param eventType This is a user-defined event type, of at least the
* value CHRE_EVENT_FIRST_USER_VALUE. It is illegal to attempt to use any
* of the CHRE_EVENT_* values reserved for the CHRE.
* @param eventData A pointer value that will be understood by the receiving
* app. Note that NULL is perfectly acceptable. It also is not required
* that this be a valid pointer, although if this nanoapp is intended to
* work on arbitrary CHRE implementations, then the size of a
* pointer cannot be assumed to be a certain size. Note that the caller
* no longer owns this memory after the call.
* @param freeCallback A pointer to a callback function. After the lifetime
* of 'eventData' is over (either through successful delivery or the event
* being dropped), this callback will be invoked. This argument is allowed
* to be NULL, in which case no callback will be invoked.
* @param targetInstanceId The ID of the instance we're delivering this event
* to. Note that this is allowed to be our own instance.
* @returns true if the event was enqueued, false otherwise. Note that even
* if this method returns 'false', the 'freeCallback' will be invoked,
* if non-NULL. Note in the 'false' case, the 'freeCallback' may be
* invoked directly from within chreSendEvent(), so it's necessary
* for nanoapp authors to avoid possible recursion with this.
*
* @see chreEventDataFreeFunction
*/
bool chreSendEvent(uint16_t eventType, void *eventData,
chreEventCompleteFunction *freeCallback,
uint32_t targetInstanceId);
/**
* Send a message to the host.
*
* This message is by definition arbitrarily defined. Since we're not
* just a passing a pointer to memory around the system, but need to copy
* this into various buffers to send it to the host, the CHRE
* implementation cannot be asked to support an arbitrarily large message
* size. As a result, we have the CHRE implementation define
* CHRE_MESSAGE_TO_HOST_MAX_SIZE.
*
* CHRE_MESSAGE_TO_HOST_MAX_SIZE is not given a value by the Platform API. The
* Platform API does define CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, and requires
* that CHRE_MESSAGE_TO_HOST_MAX_SIZE is at least that value.
*
* As a result, if your message sizes are all less than
* CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, then you have no concerns on any
* CHRE implementation. If your message sizes are larger, you'll need to
* come up with a strategy for splitting your message across several calls
* to this method. As long as that strategy works for
* CHRE_MESSAGE_TO_HOST_MINIMUM_MAX_SIZE, it will work across all CHRE
* implementations (although on some implementations less calls to this
* method may be necessary).
*
* @param message Pointer to a block of memory to send to the host.
* NULL is acceptable only if messageSize is 0. If non-NULL, this
* must be a legitimate pointer (that is, unlike chreSendEvent(), a small
* integral value cannot be cast to a pointer for this). Note that the
* caller no longer owns this memory after the call.
* @param messageSize The size, in bytes, of the given message.
* This cannot exceed CHRE_MESSAGE_TO_HOST_MAX_SIZE.
* @param reservedMessageType Message type sent to the app on the host.
* NOTE: In the N release, there is a bug in some HAL implementations
* where this data does not make it to the app running on the host.
* Nanoapps cannot trust this across all platforms for N, but that
* will be fixed in O.
* @param freeCallback A pointer to a callback function. After the lifetime
* of 'message' is over (which does not assure that 'message' made it to
* the host, just that the transport layer no longer needs this memory),
* this callback will be invoked. This argument is allowed
* to be NULL, in which case no callback will be invoked.
* @returns true if the message was accepted for transmission, false otherwise.
* Note that even if this method returns 'false', the 'freeCallback' will
* be invoked, if non-NULL. In either case, the 'freeCallback' may be
* invoked directly from within chreSendMessageToHost(), so it's necessary
* for nanoapp authors to avoid possible recursion with this.
*
* @see chreMessageFreeFunction
*/
bool chreSendMessageToHost(void *message, uint32_t messageSize,
uint32_t reservedMessageType,
chreMessageFreeFunction *freeCallback);
#ifdef __cplusplus
}
#endif
#endif /* _CHRE_EVENT_H_ */

90
android/system/chre/chre_api/legacy/v1_0/chre/nanoapp.h Normal file
View file

@ -0,0 +1,90 @@
/*
* 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_NANOAPP_H_
#define _CHRE_NANOAPP_H_
/**
* Methods in the Context Hub Runtime Environment which must be implemented
* by the nanoapp.
*/
#include <stdbool.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Method invoked by the CHRE when loading the nanoapp.
*
* Every CHRE method is legal to call from this method.
*
* @returns 'true' if the nanoapp successfully started. 'false' if the nanoapp
* failed to properly initialize itself (for example, could not obtain
* sufficient memory from the heap). If this method returns 'false', the
* nanoapp will be unloaded by the CHRE (and nanoappEnd will
* _not_ be invoked in that case).
* @see nanoappEnd
*/
bool nanoappStart(void);
/**
* Method invoked by the CHRE when there is an event for this nanoapp.
*
* Every CHRE method is legal to call from this method.
*
* @param senderInstanceId The Instance ID for the source of this event.
* Note that this may be CHRE_INSTANCE_ID, indicating that the event
* was generated by the CHRE.
* @param eventType The event type. This might be one of the CHRE_EVENT_*
* types defined in this API. But it might also be a user-defined event.
* @param eventData The associated data, if any, for this specific type of
* event. From the nanoapp's perspective, this eventData's lifetime ends
* when this method returns, and thus any data the nanoapp wishes to
* retain must be copied. Note that interpretation of event data is
* given by the event type, and for some events may not be a valid
* pointer. See documentation of the specific CHRE_EVENT_* types for how to
* interpret this data for those. Note that for user events, you will
* need to establish what this data means.
*/
void nanoappHandleEvent(uint32_t senderInstanceId, uint16_t eventType,
const void* eventData);
/**
* Method invoked by the CHRE when unloading the nanoapp.
*
* It is not valid to attempt to send events or messages, or to invoke functions
* which will generate events to this app, within the nanoapp implementation of
* this function. That means it is illegal for the nanoapp invoke any of the
* following:
* - chreSendEvent()
* - chreSendMessageToHost()
* - chreSensorConfigure()
* - chreSensorConfigureModeOnly()
* - chreTimerSet()
*
* @see nanoappStart
*/
void nanoappEnd(void);
#ifdef __cplusplus
}
#endif
#endif /* _CHRE_NANOAPP_H_ */

329
android/system/chre/chre_api/legacy/v1_0/chre/re.h Normal file
View file

@ -0,0 +1,329 @@
/*
* 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_ */

817
android/system/chre/chre_api/legacy/v1_0/chre/sensor.h Normal file
View file

@ -0,0 +1,817 @@
/*
* 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_SENSOR_H_
#define _CHRE_SENSOR_H_
/**
* API dealing with sensor interaction in the Context Hub Runtime
* Environment.
*
* This includes the definition of our sensor types and the ability to
* configure them for receiving events.
*/
#include <stdbool.h>
#include <stdint.h>
// For CHRE_EVENT_SENSOR_FIRST_EVENT and CHRE_EVENT_SENSOR_LAST_EVENT
#include <chre/event.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* The CHRE_SENSOR_TYPE_* defines are the sensor types supported.
*
* Unless otherwise noted, each of these sensor types is based off of a
* corresponding sensor type in the Android API's sensors.h interface.
* For a given CHRE_SENSOR_TYPE_FOO, it corresponds to the SENSOR_TYPE_FOO in
* hardware/libhardware/include/hardware/sensors.h of the Android code base.
*
* Unless otherwise noted below, a CHRE_SENSOR_TYPE_FOO should be assumed
* to work the same as the Android SENSOR_TYPE_FOO, as documented in the
* sensors.h documentation and as detailed within the Android Compatibility
* Definition Document.
*
* Note that every sensor will generate CHRE_EVENT_SENSOR_SAMPLING_CHANGE
* events, so it is not listed with each individual sensor.
*/
/**
* Accelerometer.
*
* Generates: CHRE_EVENT_SENSOR_ACCELEROMETER_DATA
*
* @see CHRE_EVENT_SENSOR_ACCELEROMETER_DATA
*/
#define CHRE_SENSOR_TYPE_ACCELEROMETER UINT8_C(1)
/**
* Instantaneous motion detection.
*
* Generates: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA
*
* This is a one-shot sensor.
*
* This does not have a direct analogy within sensors.h. This is similar
* to SENSOR_TYPE_MOTION_DETECT, but this triggers instantly upon any
* motion, instead of waiting for a period of continuous motion.
*/
#define CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT UINT8_C(2)
/**
* Stationary detection.
*
* Generates: CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA
*
* This is a one-shot sensor.
*/
#define CHRE_SENSOR_TYPE_STATIONARY_DETECT UINT8_C(3)
/**
* Gyroscope.
*
* Generates: CHRE_EVENT_SENSOR_GYROSCOPE_DATA and
* CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO
*
* Note that the GYROSCOPE_DATA is always the calibrated data, and not
* raw data.
*/
#define CHRE_SENSOR_TYPE_GYROSCOPE UINT8_C(6)
/**
* Magnetometer.
*
* Generates: CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA and
* CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO
*
* Note that the GEOMAGNETIC_FIELD_DATA is always the calibrated data, and not
* raw data.
*/
#define CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD UINT8_C(8)
/**
* Barometric pressure sensor.
*
* Generates: CHRE_EVENT_SENSOR_PRESSURE_DATA
*/
#define CHRE_SENSOR_TYPE_PRESSURE UINT8_C(10)
/**
* Ambient light sensor.
*
* Generates: CHRE_EVENT_SENSOR_LIGHT_DATA
*/
#define CHRE_SENSOR_TYPE_LIGHT UINT8_C(12)
/**
* Proximity detection.
*
* Generates: CHRE_EVENT_SENSOR_PROXIMITY_DATA
*
* This is an on-change sensor.
*/
#define CHRE_SENSOR_TYPE_PROXIMITY UINT8_C(13)
/**
* Base value for all of the data events for sensors.
*
* The value for a data event FOO is
* CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_FOO
*
* This allows for easy mapping, and also explains why there are gaps
* in our values since we don't have all possible sensor types assigned.
*/
#define CHRE_EVENT_SENSOR_DATA_EVENT_BASE CHRE_EVENT_SENSOR_FIRST_EVENT
/**
* nanoappHandleEvent argument: struct chreSensorThreeAxisData
*
* The data can be interpreted using the 'x', 'y', and 'z' fields within
* 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z).
*
* All values are in SI units (m/s^2) and measure the acceleration of the
* device minus the force of gravity.
*/
#define CHRE_EVENT_SENSOR_ACCELEROMETER_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_ACCELEROMETER)
/**
* nanoappHandleEvent argument: struct chreSensorOccurrenceData
*
* Since this is a one-shot sensor, after this event is delivered to the
* nanoapp, the sensor automatically goes into DONE mode. Sensors of this
* type must be configured with a ONE_SHOT mode.
*/
#define CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT)
/**
* nanoappHandleEvent argument: struct chreSensorOccurrenceData
*
* Since this is a one-shot sensor, after this event is delivered to the
* nanoapp, the sensor automatically goes into DONE mode. Sensors of this
* type must be configured with a ONE_SHOT mode.
*/
#define CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_STATIONARY_DETECT)
/**
* nanoappHandleEvent argument: struct chreSensorThreeAxisData
*
* The data can be interpreted using the 'x', 'y', and 'z' fields within
* 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z).
*
* All values are in radians/second and measure the rate of rotation
* around the X, Y and Z axis.
*/
#define CHRE_EVENT_SENSOR_GYROSCOPE_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GYROSCOPE)
/**
* nanoappHandleEvent argument: struct chreSensorThreeAxisData
*
* The data can be interpreted using the 'x', 'y', and 'z' fields within
* 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z).
*
* All values are in micro-Tesla (uT) and measure the geomagnetic
* field in the X, Y and Z axis.
*/
#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD)
/**
* nanoappHandleEvent argument: struct chreSensorFloatData
*
* The data can be interpreted using the 'pressure' field within 'readings'.
* This value is in hectopascals (hPa).
*/
#define CHRE_EVENT_SENSOR_PRESSURE_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PRESSURE)
/**
* nanoappHandleEvent argument: struct chreSensorFloatData
*
* The data can be interpreted using the 'light' field within 'readings'.
* This value is in SI lux units.
*/
#define CHRE_EVENT_SENSOR_LIGHT_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_LIGHT)
/**
* nanoappHandleEvent argument: struct chreSensorByteData
*
* The data is interpreted from the following fields in 'readings':
* o 'isNear': If set to 1, we are nearby (on the order of centimeters);
* if set to 0, we are far.
* o 'invalid': If set to 1, this is not a valid reading of this data.
*
* As an on-change sensor, there is an event generated upon configuring
* this sensor. This is when we might get an 'invalid' reading. Thus,
* this field must be checked on the first event before interpreting 'isNear'.
*/
#define CHRE_EVENT_SENSOR_PROXIMITY_DATA \
(CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PROXIMITY)
/**
* First value for sensor events which are not data from the sensor.
*
* Unlike the data event values, these other event values don't have any
* mapping to sensor types.
*/
#define CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE \
(CHRE_EVENT_SENSOR_FIRST_EVENT + 0x0100)
/**
* nanoappHandleEvent argument: struct chreSensorSamplingStatusEvent
*
* Indicates that the interval and/or the latency which this sensor is
* sampling at has changed.
*/
#define CHRE_EVENT_SENSOR_SAMPLING_CHANGE \
(CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 0)
/**
* nanoappHandleEvent argument: struct chreSensorThreeAxisData
*
* The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias'
* field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias;
* bias[1] == y_bias; bias[2] == z_bias).
*
* All values are in radians/second and measure the rate of rotation
* around the X, Y and Z axis.
*/
#define CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO \
(CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 1)
/**
* nanoappHandleEvent argument: struct chreSensorThreeAxisData
*
* The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias'
* field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias;
* bias[1] == y_bias; bias[2] == z_bias).
*
* All values are in micro-Tesla (uT) and measure the geomagnetic
* field in the X, Y and Z axis.
*/
#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO \
(CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 2)
#if CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO > CHRE_EVENT_SENSOR_LAST_EVENT
#error Too many sensor events.
#endif
/**
* Value indicating we want the smallest possible latency for a sensor.
*
* This literally translates to 0 nanoseconds for the chreSensorConfigure()
* argument. While we won't get exactly 0 nanoseconds, the CHRE will
* queue up this event As Soon As Possible.
*/
#define CHRE_SENSOR_LATENCY_ASAP UINT64_C(0)
/**
* Special value indicating non-importance of the interval.
*
* @see chreSensorConfigure
* @see chreSensorSamplingStatus
*/
#define CHRE_SENSOR_INTERVAL_DEFAULT UINT64_C(-1)
/**
* Special value indicating non-importance of the latency.
*
* @see chreSensorConfigure
* @see chreSensorSamplingStatus
*/
#define CHRE_SENSOR_LATENCY_DEFAULT UINT64_C(-1)
// This is used to define elements of enum chreSensorConfigureMode.
#define CHRE_SENSOR_CONFIGURE_RAW_POWER_ON (1 << 0)
// This is used to define elements of enum chreSensorConfigureMode.
#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS (1 << 1)
// This is used to define elements of enum chreSensorConfigureMode.
#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT (2 << 1)
/**
* Modes we can configure a sensor to use.
*
* Our mode will affect not only how/if we receive events, but
* also whether or not the sensor will be powered on our behalf.
*
* @see chreSensorConfigure
*/
enum chreSensorConfigureMode {
/**
* Get events from the sensor.
*
* Power: Turn on if not already on.
* Reporting: Continuous. Send each new event as it comes (subject to
* batching and latency).
*/
CHRE_SENSOR_CONFIGURE_MODE_CONTINUOUS =
(CHRE_SENSOR_CONFIGURE_RAW_POWER_ON |
CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS),
/**
* Get a single event from the sensor and then become DONE.
*
* Once the event is sent, the sensor automatically
* changes to CHRE_SENSOR_CONFIGURE_MODE_DONE mode.
*
* Power: Turn on if not already on.
* Reporting: One shot. Send the next event and then be DONE.
*/
CHRE_SENSOR_CONFIGURE_MODE_ONE_SHOT =
(CHRE_SENSOR_CONFIGURE_RAW_POWER_ON |
CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT),
/**
* Get events from a sensor that are generated for other apps.
*
* This is considered passive because the sensor will not be powered
* on for the sake of our nanoapp. If and only if another app in
* the system has requested this sensor power on will we get events.
*
* This can be useful for something which is interested in seeing data,
* but not interested enough to be responsible for powering on the sensor.
*
* Power: Do not power the sensor on our behalf.
* Reporting: Continuous. Send each event as it comes.
*/
CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS =
CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS,
/**
* Get a single event from a sensor that is generated for other apps.
*
* See CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS for more details
* on what be "passive" means.
*
* Power: Do not power the sensor on our behalf.
* Reporting: One shot. Send only the next event and then be DONE.
*/
CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_ONE_SHOT =
CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT,
/**
* Indicate we are done using this sensor and no longer interested in it.
*
* See chreSensorConfigure for more details on expressing interest or
* lack of interest in a sensor.
*
* Power: Do not power the sensor on our behalf.
* Reporting: None.
*/
CHRE_SENSOR_CONFIGURE_MODE_DONE = 0,
};
/**
* A structure containing information about a Sensor.
*
* See documentation of individual fields below.
*/
struct chreSensorInfo {
/**
* The name of the sensor.
*
* A text name, useful for logging/debugging, describing the Sensor. This
* is not assured to be unique (i.e. there could be multiple sensors with
* the name "Temperature").
*
* CHRE implementations may not set this as NULL. An empty
* string, while discouraged, is legal.
*/
const char *sensorName;
/**
* One of the CHRE_SENSOR_TYPE_* defines above.
*/
uint8_t sensorType;
/**
* Flag indicating if this sensor is on-change.
*
* An on-change sensor only generates events when underlying state
* changes. This has the same meaning as on-change does in the Android
* Sensors HAL. See sensors.h for much more details.
*
* A value of 1 indicates this is on-change. 0 indicates this is not
* on-change.
*/
uint8_t isOnChange : 1;
/**
* Flag indicating if this sensor is one-shot.
*
* A one-shot sensor only triggers a single event, and then automatically
* disables itself.
*
* A value of 1 indicates this is one-shot. 0 indicates this is not
* on-change.
*/
uint8_t isOneShot : 1;
uint8_t unusedFlags : 6;
};
/**
* Header used in every structure containing batchable data from a sensor.
*
* The typical structure for sensor data looks like:
*
* struct chreSensorTypeData {
* struct chreSensorDataHeader header;
* struct chreSensorTypeSampleData {
* uint32_t timestampDelta;
* union {
* <type> value;
* <type> interpretation0;
* <type> interpretation1;
* };
* } readings[1];
* };
*
* Despite 'readings' being declared as an array of 1 element,
* an instance of the struct will actually have 'readings' as
* an array of header.readingCount elements (which may be 1).
* The 'timestampDelta' is in relation to the previous 'readings' (or
* the baseTimestamp for readings[0]. So,
* Timestamp for readings[0] == header.baseTimestamp +
* readings[0].timestampDelta.
* Timestamp for readings[1] == timestamp for readings[0] +
* readings[1].timestampDelta.
* And thus, in order to determine the timestamp for readings[N], it's
* necessary to process through all of the N-1 readings. The advantage,
* though, is that our entire readings can span an arbitrary length of time,
* just as long as any two consecutive readings differ by no more than
* 4.295 seconds (timestampDelta, like all time in the CHRE, is in
* nanoseconds).
*
* If a sensor has batched readings where two consecutive readings differ by
* more than 4.295 seconds, the CHRE will split them across multiple
* instances of the struct, and send multiple events.
*
* The value from the sensor is typically expressed in a union,
* allowing a generic access to the data ('value'), along with
* differently named access giving a more natural interpretation
* of the data for the specific sensor types which use this
* structure. This allows, for example, barometer code to
* reference readings[N].pressure, and an ambient light sensor
* to reference readings[N].light, while both use the same
* structure.
*/
struct chreSensorDataHeader {
/**
* The base timestamp, in nanoseconds.
*/
uint64_t baseTimestamp;
/**
* The handle of the sensor producing this event.
*/
uint32_t sensorHandle;
/**
* The number elements in the 'readings' array.
*
* This must be at least 1.
*/
uint16_t readingCount;
/**
* Reserved bytes.
*
* These must be 0.
*/
uint8_t reserved[2];
};
/**
* Data for a sensor which reports on three axes.
*
* This is used by CHRE_EVENT_SENSOR_ACCELEROMETER_DATA,
* CHRE_EVENT_SENSOR_GYROSCOPE_DATA,
* CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO,
* CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA, and
* CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO.
*/
struct chreSensorThreeAxisData {
/**
* @see chreSensorDataHeader
*/
struct chreSensorDataHeader header;
struct chreSensorThreeAxisSampleData {
/**
* @see chreSensorDataHeader
*/
uint32_t timestampDelta;
union {
float values[3];
float v[3];
struct {
float x;
float y;
float z;
};
float bias[3];
struct {
float x_bias;
float y_bias;
float z_bias;
};
};
} readings[1];
};
/**
* Data from a sensor where we only care about a event occurring.
*
* This is a bit unusual in that our readings have no data in addition
* to the timestamp. But since we only care about the occurrence, we
* don't need to know anything else.
*
* Used by: CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA and
* CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA.
*/
struct chreSensorOccurrenceData {
struct chreSensorDataHeader header;
struct chreSensorOccurenceSampleData {
uint32_t timestampDelta;
// This space intentionally left blank.
// Only the timestamp is meaningful here, there
// is no additional data.
} readings[1];
};
/**
* CHRE_EVENT_SENSOR_LIGHT_DATA and CHRE_EVENT_SENSOR_PRESSURE_DATA.
*/
struct chreSensorFloatData {
struct chreSensorDataHeader header;
struct chreSensorFloatSampleData {
uint32_t timestampDelta;
union {
float value;
float light; // lux
float pressure; // hectopascals (hPa)
};
} readings[1];
};
/**
* CHRE_EVENT_SENSOR_PROXIMITY_DATA.
*/
struct chreSensorByteData {
struct chreSensorDataHeader header;
struct chreSensorByteSampleData {
uint32_t timestampDelta;
union {
uint8_t value;
struct {
uint8_t isNear : 1;
uint8_t invalid : 1;
uint8_t padding0 : 6;
};
};
} readings[1];
};
/**
* The status of a sensor's sampling configuration.
*/
struct chreSensorSamplingStatus {
/**
* The interval, in nanoseconds, at which the sensor is now sampling.
*
* If this is CHRE_SENSOR_INTERVAL_DEFAULT, then a sampling interval
* isn't meaningful for this sensor.
*
* Note that if 'enabled' is false, this value is not meaningful.
*/
uint64_t interval;
/**
* The latency, in nanoseconds, at which the senor is now reporting.
*
* If this is CHRE_SENSOR_LATENCY_DEFAULT, then a latency
* isn't meaningful for this sensor.
*
* Note that if 'enabled' is false, this value is not meaningful.
*/
uint64_t latency;
/**
* True if the sensor is actively powered and sampling; false otherwise.
*/
bool enabled;
};
/**
* The nanoappHandleEvent argument for CHRE_EVENT_SENSOR_SAMPLING_CHANGE.
*
* Note that only at least one of 'interval' or 'latency' must be
* different than it was prior to this event. Thus, one of these
* fields may be (but doesn't need to be) the same as before.
*/
struct chreSensorSamplingStatusEvent {
/**
* The handle of the sensor which has experienced a change in sampling.
*/
uint32_t sensorHandle;
/**
* The new sampling status.
*
* At least one of the field in this struct will be different from
* the previous sampling status event.
*/
struct chreSensorSamplingStatus status;
};
/**
* Find the default sensor for a given sensor type.
*
* @param sensorType One of the CHRE_SENSOR_TYPE_* constants.
* @param handle If a sensor is found, then the memory will be filled with
* the value for the sensor's handle. This argument must be non-NULL.
* @returns true if a sensor was found, false otherwise.
*/
bool chreSensorFindDefault(uint8_t sensorType, uint32_t *handle);
/**
* Get the chreSensorInfo struct for a given sensor.
*
* @param sensorHandle The sensor handle, as obtained from
* chreSensorFindDefault() or passed to nanoappHandleEvent().
* @param info If the sensor is valid, then this memory will be filled with
* the SensorInfo contents for this sensor. This argument must be
* non-NULL.
* @returns true if the senor handle is valid and 'info' was filled in;
* false otherwise.
*/
bool chreGetSensorInfo(uint32_t sensorHandle, struct chreSensorInfo *info);
/**
* Get the chreSensorSamplingStatus struct for a given sensor.
*
* Note that this may be different from what was requested in
* chreSensorConfigure(), for multiple reasons. It's possible that the sensor
* does not exactly support the interval requested in chreSensorConfigure(), so
* a faster one was chosen.
*
* It's also possible that there is another user of this sensor who has
* requested a faster interval and/or lower latency. This latter scenario
* should be noted, because it means the sensor rate can change due to no
* interaction from this nanoapp. Note that the
* CHRE_EVENT_SENSOR_SAMPLING_CHANGE event will trigger in this case, so it's
* not necessary to poll for such a change.
*
* @param sensorHandle The sensor handle, as obtained from
* chreSensorFindDefault() or passed to nanoappHandleEvent().
* @param status If the sensor is valid, then this memory will be filled with
* the sampling status contents for this sensor. This argument must be
* non-NULL.
* @returns true if the senor handle is valid and 'status' was filled in;
* false otherwise.
*/
bool chreGetSensorSamplingStatus(uint32_t sensorHandle,
struct chreSensorSamplingStatus *status);
/**
* Configures a given sensor at a specific interval and latency and mode.
*
* If this sensor's chreSensorInfo has isOneShot set to 1,
* then the mode must be one of the ONE_SHOT modes, or this method will fail.
*
* The CHRE wants to power as few sensors as possible, in keeping with its
* low power design. As such, it only turns on sensors when there are clients
* actively interested in that sensor data, and turns off sensors as soon as
* there are no clients interested in them. Calling this method generally
* indicates an interest, and using CHRE_SENSOR_CONFIGURE_MODE_DONE shows
* when we are no longer interested.
*
* Thus, each initial Configure of a sensor (per nanoapp) needs to eventually
* have a DONE call made, either directly or on its behalf. Subsequent calls
* to a Configure method within the same nanoapp, when there has been no DONE
* in between, still only require a single DONE call.
*
* For example, the following is valid usage:
* <code>
* chreSensorConfigure(myHandle, mode, interval0, latency0);
* [...]
* chreSensorConfigure(myHandle, mode, interval1, latency0);
* [...]
* chreSensorConfigure(myHandle, mode, interval1, latency1);
* [...]
* chreSensorConfigureModeOnly(myHandle, CHRE_SENSOR_CONFIGURE_MODE_DONE);
* </code>
*
* The first call to Configure is the one which creates the requirement
* to eventually call with DONE. The subsequent calls are just changing the
* interval/latency. They have not changed the fact that this nanoapp is
* still interested in output from the sensor 'myHandle'. Thus, only one
* single call for DONE is needed.
*
* There is a special case. One-shot sensors, sensors which
* just trigger a single event and never trigger again, implicitly go into
* DONE mode after that single event triggers. Thus, the
* following are legitimate usages:
* <code>
* chreSensorConfigure(myHandle, MODE_ONE_SHOT, rate, latency);
* [...]
* [myHandle triggers an event]
* [no need to configure to DONE].
* </code>
*
* And:
* <code>
* chreSensorConfigure(myHandle, MODE_ONE_SHOT, rate, latency);
* [...]
* chreSensorConfigureModeOnly(myHandle, MODE_DONE);
* [we cancelled myHandle before it ever triggered an event]
* </code>
*
* Note that while PASSIVE modes, by definition, don't express
* an interest in powering the sensor, DONE is still necessary
* to silence the event reporting.
*
* @param sensorHandle The handle to the sensor, as obtained from
* chreSensorFindDefault().
* @param mode The mode to use. See descriptions within the
* chreSensorConfigureMode enum.
* @param interval The interval, in nanoseconds, at which we want events from
* the sensor. On success, the sensor will be set to 'interval', or a value
* less than 'interval'. There is a special value
* CHRE_SENSOR_INTERVAL_DEFAULT, in which we don't express a preference for
* the interval, and allow the sensor to chose what it wants. Note that
* due to batching, we may receive events less frequently than
* 'interval'.
* @param latency The maximum latency, in nanoseconds, allowed before the
* CHRE begins delivery of an event. This will control how many events
* can be queued by the sensor before requiring a delivery event.
* Latency is defined as the "timestamp when event is queued by the CHRE"
* minus "timestamp of oldest unsent data reading".
* There is a special value CHRE_SENSOR_LATENCY_DEFAULT, in which we don't
* express a preference for the latency, and allow the sensor to chose what
* it wants.
* Note that there is no assurance of how long it will take an event to
* get through a CHRE's queueing system, and thus there is no ability to
* request a minimum time from the occurrence of a phenomenon to when the
* nanoapp receives the information. The current CHRE API has no
* real-time elements, although future versions may introduce some to
* help with this issue.
* @returns true if the configuration succeeded, false otherwise.
*
* @see chreSensorConfigureMode
* @see chreSensorFindDefault
* @see chreSensorInfo
*/
bool chreSensorConfigure(uint32_t sensorHandle,
enum chreSensorConfigureMode mode,
uint64_t interval, uint64_t latency);
/**
* Short cut for chreSensorConfigure where we only want to configure the mode
* and do not care about interval/latency.
*
* @see chreSensorConfigure
*/
static inline bool chreSensorConfigureModeOnly(
uint32_t sensorHandle, enum chreSensorConfigureMode mode) {
return chreSensorConfigure(sensorHandle,
mode,
CHRE_SENSOR_INTERVAL_DEFAULT,
CHRE_SENSOR_LATENCY_DEFAULT);
}
#ifdef __cplusplus
}
#endif
#endif /* _CHRE_SENSOR_H_ */

129
android/system/chre/chre_api/legacy/v1_0/chre/version.h Normal file
View file

@ -0,0 +1,129 @@
/*
* 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_VERSION_H_
#define _CHRE_VERSION_H_
/**
* Definitions and methods for the versioning of the Context Hub Runtime
* Environment.
*
* The CHRE API versioning pertains to all the chre_*.h files and chre.h.
*/
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Value for version 0.1 of the Context Hub Runtime Environment API interface.
*
* This is a legacy version. Version 1.0 is considered the first official
* version of the API.
*
* @see CHRE_API_VERSION
*/
#define CHRE_API_VERSION_0_1 UINT32_C(0x00010000)
/**
* Value for version 1.0 of the Context Hub Runtime Environment API interface.
*
* The version of the CHRE API which shipped with the Android Nougat release.
*
* @see CHRE_API_VERSION
*/
#define CHRE_API_VERSION_1_0 UINT32_C(0x01000000)
/**
* Major and Minor Version of this Context Hub Runtime Environment API.
*
* The major version changes when there is an incompatible API change.
*
* The minor version changes when there is an addition in functionality
* in a backwards-compatible manner.
*
* We define the version number as an unsigned 32-bit value. The most
* significant byte is the Major Version. The second-most significant byte
* is the Minor Version. The two least significant bytes are the Patch
* Version. The Patch Version is not defined by this header API, but
* is provided by a specific CHRE implementation (see chreGetVersion()).
*
* Note that version numbers can always be numerically compared with
* expected results, so 1.0.0 < 1.0.4 < 1.1.0 < 2.0.300 < 3.5.0.
*/
#define CHRE_API_VERSION CHRE_API_VERSION_1_0
/**
* Get the API version the CHRE implementation was compiled against.
*
* This is not necessarily the CHRE_API_VERSION in the header the nanoapp was
* built against, and indeed may not have even appeared in the context_hub_os.h
* header which this nanoapp was built against.
*
* By definition, this will have the two least significant bytes set to 0,
* and only contain the major and minor version number.
*
* @returns The API version.
*/
uint32_t chreGetApiVersion(void);
/**
* Get the version of this CHRE implementation.
*
* By definition, ((chreGetApiVersion() & UINT32_C(0xFFFF0000)) ==
* (chreGetVersion() & UINT32_C(0xFFFF0000))).
*
* The Patch Version, in the lower two bytes, only have meaning in context
* of this specific platform ID. It is increased by the platform every time
* a backwards-compatible bug fix is released.
*
* @returns The version.
*
* @see chreGetPlatformId()
*/
uint32_t chreGetVersion(void);
/**
* Get the Platform ID of this CHRE.
*
* The most significant five bytes are the vendor ID as set out by the
* NANOAPP_VENDOR convention in context_hub.h, as used by nanoapp IDs.
*
* The least significant three bytes are set by the vendor, but must be
* unique for each different CHRE implementation/hardware that the vendor
* supplies.
*
* The idea is that in the case of known bugs in the field, a new nanoapp could
* be shipped with a workaround that would use this value, and chreGetVersion(),
* to have code that can conditionally work around the bug on a buggy version.
* Thus, we require this uniqueness to allow such a setup to work.
*
* @returns The platform ID.
*/
uint64_t chreGetPlatformId(void);
#ifdef __cplusplus
}
#endif
#endif /* _CHRE_VERSION_H_ */