1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef CHRE_PLATFORM_SHARED_NANOAPP_SUPPORT_LIB_DSO_H_ 18 #define CHRE_PLATFORM_SHARED_NANOAPP_SUPPORT_LIB_DSO_H_ 19 20 /** 21 * @file 22 * This provides the interface that the dynamic shared object (DSO) nanoapp 23 * nanoapp support library (NSL) uses to interface with the underlying CHRE 24 * implementation in a compatible manner. 25 * 26 * This header file must retain compatibility with C, and have minimal or no 27 * dependencies on other CHRE system header files, as it will be used when 28 * compiling external/dynamic nanoapps. 29 */ 30 31 #include <stdint.h> 32 33 #include "chre_api/chre.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 //! Special magic value to uniquely identify the nanoapp info structure 40 #define CHRE_NSL_NANOAPP_INFO_MAGIC UINT32_C(0x50e69977) 41 42 //! The minor version in the nanoapp info structure to determine which fields 43 //! are available to support backwards compatibility. 44 #define CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION UINT8_C(3) 45 46 //! Explicit definition of nanoapp info structure minor version three (3), 47 //! can be used to determine if a nanoapp supports app permissions declaration 48 #define CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION_3 UINT8_C(3) 49 50 //! The symbol name expected from the nanoapp's definition of its info struct 51 #define CHRE_NSL_DSO_NANOAPP_INFO_SYMBOL_NAME "_chreNslDsoNanoappInfo" 52 53 //! The symbol name expected from the nanoapp's definition of its unstable ID 54 //! char array 55 #define CHRE_NSL_DSO_NANOAPP_UNSTABLE_ID_SYMBOL_NAME "_chreNanoappUnstableId" 56 57 //! Maximum length of vendor and name strings 58 #define CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN (32) 59 60 //! @see nanoappStart() 61 typedef bool(chreNanoappStartFunction)(void); 62 63 //! @see nanoappHandleEvent() 64 typedef void(chreNanoappHandleEventFunction)(uint32_t senderInstanceId, 65 uint16_t eventType, 66 const void *eventData); 67 68 //! @see nanoappEnd() 69 typedef void(chreNanoappEndFunction)(void); 70 71 /** 72 * DSO-based nanoapps must expose this struct under a symbol whose name is given 73 * by CHRE_NSL_DSO_NANOAPP_INFO_SYMBOL_NAME. When the nanoapp is loaded, dlsym() 74 * will be used to locate this symbol to register the nanoapp with the system. 75 */ 76 struct chreNslNanoappInfo { 77 //! @see CHRE_NSL_NANOAPP_INFO_MAGIC 78 uint32_t magic; 79 80 //! @see CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION 81 uint8_t structMinorVersion; 82 83 //! Set to 1 if this nanoapp is a "system nanoapp" that should not show up in 84 //! the context hub HAL, likely because it implements some device 85 //! functionality beneath the HAL. 86 uint8_t isSystemNanoapp : 1; 87 88 //! Set to 1 if this nanoapp runs in tightly coupled memory. This flag is only 89 //! relevant to platforms that have the ability to run nanoapps within tightly 90 //! coupled memory. 91 //! 92 //! @since minor version 1 93 uint8_t isTcmNanoapp : 1; 94 95 //! Reserved for future use, set to 0. Assignment of this field to some use 96 //! must be accompanied by an increase of the struct minor version. 97 uint8_t reservedFlags : 6; 98 uint8_t reserved; 99 100 //! The CHRE API version that the nanoapp was compiled against 101 uint32_t targetApiVersion; 102 103 //! A human-friendly name of the nanoapp vendor (null-terminated string, 104 //! maximum length CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN) 105 const char *vendor; 106 107 //! A human-friendly name for the nanoapp (null-terminated string, maximum 108 //! length CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN) 109 const char *name; 110 111 //! Identifies the vendor (most significant 5 bytes) and application 112 uint64_t appId; 113 114 //! Application-specific version number 115 uint32_t appVersion; 116 117 struct { 118 chreNanoappStartFunction *start; 119 chreNanoappHandleEventFunction *handleEvent; 120 chreNanoappEndFunction *end; 121 } entryPoints; 122 123 //! Application-specific verison string. This might contain a commit hash at 124 //! which the app was built, but is up to the app itself. 125 //! 126 //! @since minor version 2 127 const char *appVersionString; 128 129 //! Set of permissions that determines what APIs the application is allowed to 130 //! use. See chre/util/system/napp_permissions.h for more details on what 131 //! permissions can be declared here and what their values are. 132 //! 133 //! @since minor version 3 134 uint32_t appPermissions; 135 }; 136 137 /** 138 * Get the Chre Nsl Nanoapp Info object 139 * 140 * @return struct chreNslNanoappInfo 141 */ 142 const struct chreNslNanoappInfo *getChreNslDsoNanoappInfo(); 143 144 /** 145 * Defined as a placeholder to enable future functionality extension. 146 * 147 * @param apiId 148 * @param apiHandle If this function returns true, this will be set to a pointer 149 * to the associated structure containing the API 150 * 151 * @return true if the requested API is supported, false otherwise 152 */ 153 bool chreNslDsoGetApi(uint32_t apiId, void **apiHandle); 154 155 #ifdef __cplusplus 156 } 157 #endif 158 159 #endif // CHRE_PLATFORM_SHARED_NANOAPP_SUPPORT_LIB_DSO_H_ 160