diff options
Diffstat (limited to 'inc/chre')
| -rw-r--r-- | inc/chre/event.h | 273 | ||||
| -rw-r--r-- | inc/chre/nanoapp.h | 90 | ||||
| -rw-r--r-- | inc/chre/re.h | 329 | ||||
| -rw-r--r-- | inc/chre/sensor.h | 817 | ||||
| -rw-r--r-- | inc/chre/version.h | 129 |
5 files changed, 0 insertions, 1638 deletions
diff --git a/inc/chre/event.h b/inc/chre/event.h deleted file mode 100644 index 0f088bb8..00000000 --- a/inc/chre/event.h +++ /dev/null @@ -1,273 +0,0 @@ -/* - * 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_ */ - diff --git a/inc/chre/nanoapp.h b/inc/chre/nanoapp.h deleted file mode 100644 index 78a8accd..00000000 --- a/inc/chre/nanoapp.h +++ /dev/null @@ -1,90 +0,0 @@ -/* - * 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_ */ diff --git a/inc/chre/re.h b/inc/chre/re.h deleted file mode 100644 index 31b0ed7c..00000000 --- a/inc/chre/re.h +++ /dev/null @@ -1,329 +0,0 @@ -/* - * 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_ */ - diff --git a/inc/chre/sensor.h b/inc/chre/sensor.h deleted file mode 100644 index 9e743363..00000000 --- a/inc/chre/sensor.h +++ /dev/null @@ -1,817 +0,0 @@ -/* - * 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 on-change. 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 change the mode. - * - * @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_ */ - diff --git a/inc/chre/version.h b/inc/chre/version.h deleted file mode 100644 index ae6b14ca..00000000 --- a/inc/chre/version.h +++ /dev/null @@ -1,129 +0,0 @@ -/* - * 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_ */ - |