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_PAL_WWAN_H_
18 #define CHRE_PAL_WWAN_H_
19
20 /**
21 * @file
22 * Defines the interface between the common CHRE core system and the
23 * platform-specific WWAN module.
24 */
25
26 #include <stdbool.h>
27 #include <stdint.h>
28
29 #include "chre/pal/system.h"
30 #include "chre/pal/version.h"
31 #include "chre_api/chre/wwan.h"
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 /**
38 * Initial version of the CHRE WWAN PAL, tied to CHRE API v1.1.
39 */
40 #define CHRE_PAL_WWAN_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0)
41
42 /**
43 * Introduced alongside CHRE API v1.4, adding support for NR5G Cell Info.
44 */
45 #define CHRE_PAL_WWAN_API_V1_4 CHRE_PAL_CREATE_API_VERSION(1, 4)
46
47 /**
48 * The version of the CHRE WWAN PAL defined in this header file.
49 */
50 #define CHRE_PAL_WWAN_API_CURRENT_VERSION CHRE_PAL_WWAN_API_V1_4
51
52 struct chrePalWwanCallbacks {
53 /**
54 * Callback invoked to provide the result of a prior request to
55 * requestCellInfo in struct chrePalWwanApi.
56 *
57 * This function call passes ownership of the result's memory to the core
58 * CHRE system, i.e. the PAL module must not modify or free the provided
59 * data until the associated API function is called to release the memory.
60 *
61 * @param result
62 *
63 * @see chrePalWwanApi.requestCellInfo
64 * @see chrePalWwanApi.releaseCellInfoResult
65 */
66 void (*cellInfoResultCallback)(struct chreWwanCellInfoResult *result);
67 };
68
69 struct chrePalWwanApi {
70 /**
71 * Version of the module providing this API. This value should be
72 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported
73 * API version constant (CHRE_PAL_WWAN_API_*) and the module-specific patch
74 * version.
75 */
76 uint32_t moduleVersion;
77
78 /**
79 * Initializes the WWAN module. Initialization must complete synchronously.
80 *
81 * @param systemApi Structure containing CHRE system function pointers which
82 * the PAL implementation should prefer to use over equivalent
83 * functionality exposed by the underlying platform. The module does
84 * not need to deep-copy this structure; its memory remains
85 * accessible at least until after close() is called.
86 * @param callbacks Structure containing entry points to the core CHRE
87 * system. The module does not need to deep-copy this structure; its
88 * memory remains accessible at least until after close() is called.
89 *
90 * @return true if initialization was successful, false otherwise
91 */
92 bool (*open)(const struct chrePalSystemApi *systemApi,
93 const struct chrePalWwanCallbacks *callbacks);
94
95 /**
96 * Performs clean shutdown of the WWAN module, usually done in preparation
97 * for stopping the CHRE. The WWAN module must ensure that it will not
98 * invoke any callbacks past this point, and complete any relevant teardown
99 * activities before returning from this function.
100 */
101 void (*close)(void);
102
103 /**
104 * Retrieves information about the features supported by this module. The
105 * value returned from this function must not change for the duration of
106 * execution.
107 *
108 * @return See chreWwanGetCapabilities()
109 *
110 * @see chreWwanGetCapabilities()
111 */
112 uint32_t (*getCapabilities)(void);
113
114 /**
115 * Initiates a request for information about the current serving cell and
116 * its neighbors.
117 *
118 * @return true if the request was accepted, in which case a subsequent call
119 * to cellInfoResultCallback will be used to communicate the result
120 *
121 * @see chreWwanGetCellInfoAsync()
122 * @see chrePalWwanCallbacks.cellInfoResultCallback
123 */
124 bool (*requestCellInfo)(void);
125
126 /**
127 * Invoked when the core CHRE system no longer needs a raw measurement event
128 * structure that was provided to it via measurementEventCallback(). The
129 * GNSS module may use this to free associated memory, etc.
130 *
131 * @param result Result data to release
132 */
133 void (*releaseCellInfoResult)(struct chreWwanCellInfoResult *result);
134 };
135
136 /**
137 * Retrieve a handle for the CHRE WWAN PAL.
138 *
139 * @param requestedApiVersion The implementation of this function must return a
140 * pointer to a structure with the same major version as requested.
141 *
142 * @return Pointer to API handle, or NULL if a compatible API version is not
143 * supported by the module, or the API as a whole is not implemented. If
144 * non-NULL, the returned API handle must be valid as long as this
145 * module is loaded.
146 */
147 const struct chrePalWwanApi *chrePalWwanGetApi(uint32_t requestedApiVersion);
148
149 /**
150 * Helper setter for nci in the chreWwanCellIdentityNr struct.
151 *
152 * @param nci INT64_MAX if invalid/unreported.
153 *
154 * @see chreWwanCellIdentityNr
155 *
156 * @since v1.4
157 */
chreWwanPackNrNci(int64_t nci,struct chreWwanCellIdentityNr * nrCellId)158 static inline void chreWwanPackNrNci(int64_t nci,
159 struct chreWwanCellIdentityNr *nrCellId) {
160 nrCellId->nci1 = (nci >> 32) & 0xffffffff;
161 nrCellId->nci0 = nci & 0xffffffff;
162 }
163
164 #ifdef __cplusplus
165 }
166 #endif
167
168 #endif // CHRE_PAL_WWAN_H_
169