1 /*
2  * Copyright (C) 2020 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 /*
18  * Implementation Notes
19  * Each platform must supply a platform-specific platform_notifier.h to provide
20  * definitions and a platform-specific notifier.c to provide the implementation
21  * for the definitions in this file.
22  */
23 
24 #ifndef CHPP_SYNC_H_
25 #define CHPP_SYNC_H_
26 
27 #include <stdint.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /*
34  * Platform-specific condition variable struct defined in the platform's
35  * platform_notifier.h that enables the funcions defined here.
36  */
37 struct ChppNotifier;
38 
39 /**
40  * Initializes the platform-specific ChppNotifier.
41  * Will be called before notifier is used anywhere else.
42  *
43  * @param notifier Points to the ChppNotifier being initialized.
44  */
45 static void chppNotifierInit(struct ChppNotifier *notifier);
46 
47 /**
48  * Deinitializes the platform-specific ChppNotifier.
49  *
50  * @param notifier Points to the ChppNotifier being deinitialized.
51  */
52 static void chppNotifierDeinit(struct ChppNotifier *notifier);
53 
54 /**
55  * Returns the signal value in chppNotifierSignal(), if any. Resets the signal
56  * value afterwards.
57  *
58  * @param notifier Points to the ChppNotifier being used.
59  *
60  * @return The signal value indicated in chppNotifierSignal().
61  */
62 static uint32_t chppNotifierGetSignal(struct ChppNotifier *notifier);
63 
64 /**
65  * Waits on a platform-specific notifier until it is signaled through
66  * chppNotifierSignal(). Similar to chppNotifierTimedWait(), but without the
67  * timeout.
68  *
69  * @param notifier Points to the ChppNotifier being used.
70  *
71  * @return The signal value indicated in chppNotifierSignal().
72  */
73 static uint32_t chppNotifierWait(struct ChppNotifier *notifier);
74 
75 /**
76  * Waits on a platform-specific notifier until it is signaled through
77  * chppNotifierSignal() or until the specified timeout.
78  *
79  * Note that while the timeout is specified as a uint64_t, in practice, CHPP
80  * would only use values up to CHPP_TRANSPORT_TX_TIMEOUT_NS.
81  *
82  * @param notifier Points to the ChppNotifier being used.
83  * @param timeoutNs Timeout in nanoseconds.
84  *
85  * @return The signal value indicated in chppNotifierSignal().
86  */
87 static uint32_t chppNotifierTimedWait(struct ChppNotifier *notifier,
88                                       uint64_t timeoutNs);
89 
90 /**
91  * Signals chppNotifierTimedWait() with the specified signal value.
92  *
93  * The signal values can be defined by the user of this class. Note that it is
94  * expected for different signals to be bitwise exclusive, i.e. each bit in the
95  * uint32_t should indicate a specific type of signal event. This allows for
96  * multiple events to be handled simultaneously in chppNotifierTimedWait().
97  *
98  * @param notifier Points to the ChppNotifier being used.
99  * @param signal The value where each bit represents a different event.
100  *               As such the value 0 will not notify any event.
101  */
102 static void chppNotifierSignal(struct ChppNotifier *notifier, uint32_t signal);
103 
104 #ifdef __cplusplus
105 }
106 #endif
107 
108 #include "chpp/platform/platform_notifier.h"
109 
110 #endif  // CHPP_SYNC_H_
111