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 "chre/util/entry_points.h"
32 
33 #include <stdint.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 helps identify whether
43 #define CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION  UINT8_C(0)
44 
45 //! The symbol name expected from the nanoapp's definition of its info struct
46 #define CHRE_NSL_DSO_NANOAPP_INFO_SYMBOL_NAME  "_chreNslDsoNanoappInfo"
47 
48 //! Maximum length of vendor and name strings
49 #define CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN  (32)
50 
51 /**
52  * DSO-based nanoapps must expose this struct under a symbol whose name is given
53  * by CHRE_NSL_DSO_NANOAPP_INFO_SYMBOL_NAME. When the nanoapp is loaded, dlsym()
54  * will be used to locate this symbol to register the nanoapp with the system.
55  */
56 struct chreNslNanoappInfo {
57   //! @see CHRE_NSL_NANOAPP_INFO_MAGIC
58   uint32_t magic;
59 
60   //! @see CHRE_NSL_NANOAPP_INFO_STRUCT_MINOR_VERSION
61   uint8_t structMinorVersion;
62 
63   //! Set to 1 if this nanoapp is a "system nanoapp" that should not show up in
64   //! the context hub HAL, likely because it implements some device
65   //! functionality beneath the HAL.
66   uint8_t isSystemNanoapp:1;
67 
68   //! Reserved for future use, set to 0. Assignment of this field to some use
69   //! must be accompanied by an increase of the struct minor version.
70   uint8_t reservedFlags:7;
71   uint8_t reserved;
72 
73   //! The CHRE API version that the nanoapp was compiled against
74   uint32_t targetApiVersion;
75 
76   //! A human-friendly name of the nanoapp vendor (null-terminated string,
77   //! maximum length CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN)
78   const char *vendor;
79 
80   //! A human-friendly name for the nanoapp (null-terminated string, maximum
81   //! length CHRE_NSL_DSO_NANOAPP_STRING_MAX_LEN)
82   const char *name;
83 
84   //! Identifies the vendor (most significant 5 bytes) and application
85   uint64_t appId;
86 
87   //! Application-specific version number
88   uint32_t appVersion;
89 
90   struct {
91     chreNanoappStartFunction *start;
92     chreNanoappHandleEventFunction *handleEvent;
93     chreNanoappEndFunction *end;
94   } entryPoints;
95 };
96 
97 /**
98  * Defined as a placeholder to enable future functionality extension.
99  *
100  * @param apiId
101  * @param apiHandle If this function returns true, this will be set to a pointer
102  *        to the associated structure containing the API
103  *
104  * @return true if the requested API is supported, false otherwise
105  */
106 bool chreNslDsoGetApi(uint32_t apiId, void **apiHandle);
107 
108 #ifdef __cplusplus
109 }
110 #endif
111 
112 #endif  // CHRE_PLATFORM_SHARED_NANOAPP_SUPPORT_LIB_DSO_H_
113