1 #ifndef _G_PREREQ_TRACKER_NVOC_H_
2 #define _G_PREREQ_TRACKER_NVOC_H_
3 #include "nvoc/runtime.h"
4
5 #ifdef __cplusplus
6 extern "C" {
7 #endif
8
9 /*
10 * SPDX-FileCopyrightText: Copyright (c) 2015-2021 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
11 * SPDX-License-Identifier: MIT
12 *
13 * Permission is hereby granted, free of charge, to any person obtaining a
14 * copy of this software and associated documentation files (the "Software"),
15 * to deal in the Software without restriction, including without limitation
16 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
17 * and/or sell copies of the Software, and to permit persons to whom the
18 * Software is furnished to do so, subject to the following conditions:
19 *
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 * DEALINGS IN THE SOFTWARE.
30 */
31
32 /*!
33 * @file prereq_tracker.h
34 * @brief Holds interfaces and data structures required by the prerequisite
35 * tracking feature/code.
36 *
37 * Code depending on multiple other features should use prereqComposeEntry() to create
38 * a prerequisite tracking structure with a provided bitVector of all necessary
39 * dependencies, which will arm the prereq to start watching those dependencies.
40 * Once those dependencies are fulfilled they should issue prereqSatisfy() (one-by-one)
41 * This common code should broadcast those to all prerequisite tracking structures
42 * and once all respective dependencies are satisfied, will issue the
43 * registered callback.
44 * Similarly, dependencies should issue prereqRetract() before they change
45 * their state and common code will broadcast that to all tracking structures
46 * and issue callbacks again with bSatisfied=false, if all dependencies
47 * for that prereq were previously satisfied.
48 *
49 * @note Feature is designed to prevent creating new prerequisites once
50 * dependencies start issuing Satisfy()/Retract() notifications.
51 * Therefore, ComposeEntry all prerequisites during
52 * stateInit() and allow code to issue Satisfy()/Retract() only in
53 * stateLoad() or later.
54 */
55
56 #include "g_prereq_tracker_nvoc.h"
57
58 #ifndef __PREREQUISITE_TRACKER_H__
59 #define __PREREQUISITE_TRACKER_H__
60
61 /* ------------------------ Includes ---------------------------------------- */
62 #include "containers/list.h"
63 #include "utils/nvbitvector.h"
64
65 #include "nvoc/object.h"
66
67 /* ------------------------ Macros ------------------------------------------ */
68
69 #define PREREQ_ID_VECTOR_SIZE 64
70
71 /*!
72 * Performs check if all dependencies of the given prerequisite tracking
73 * structure has been satisfied.
74 *
75 * @param[in] _pPrereq PREREQ_ENTRY pointer
76 *
77 * @return boolean if prerequisite has been satisfied.
78 */
79 #define PREREQ_IS_SATISFIED(_pPrereq) \
80 ((_pPrereq)->countRequested == (_pPrereq)->countSatisfied)
81
82 /* ------------------------ Datatypes --------------------------------------- */
83
84 struct OBJGPU;
85
86 #ifndef __NVOC_CLASS_OBJGPU_TYPEDEF__
87 #define __NVOC_CLASS_OBJGPU_TYPEDEF__
88 typedef struct OBJGPU OBJGPU;
89 #endif /* __NVOC_CLASS_OBJGPU_TYPEDEF__ */
90
91 #ifndef __nvoc_class_id_OBJGPU
92 #define __nvoc_class_id_OBJGPU 0x7ef3cb
93 #endif /* __nvoc_class_id_OBJGPU */
94
95
96
97 /*!
98 * @brief Callback prototype.
99 *
100 * @param[in] pGpu OBJGPU pointer
101 * @param[in] bSatisfied
102 * Indicates if dependencies were just satisfied or about to be retracted.
103 *
104 * @return NV_OK if callback successfully executed
105 * @return status failure specific error code
106 */
107 typedef NV_STATUS GpuPrereqCallback(struct OBJGPU *pGpu, NvBool bSatisfied);
108
109 typedef NvU16 PREREQ_ID;
110
111 /*!
112 * Bitvector for storing prereq IDs required for another prereq struct
113 * Limited to size defined above, set to largest required by users
114 */
115 MAKE_BITVECTOR(PREREQ_ID_BIT_VECTOR, PREREQ_ID_VECTOR_SIZE);
116
117 /*!
118 * An individual prerequisite tracking entry structure.
119 */
120 typedef struct
121 {
122 /*!
123 * Mask of the dependencies (prerequisites that have to be satisfied before
124 * callback can be issues).
125 */
126 PREREQ_ID_BIT_VECTOR requested;
127
128 /*!
129 * Counter of all dependencies (prerequisites) tracked by this structure.
130 */
131 NvS32 countRequested;
132 /*!
133 * Counter of currently satisfied dependencies (prerequisites) tracked by
134 * this structure. Once equal to @ref countRequested, callback can be issued.
135 */
136 NvS32 countSatisfied;
137
138 /*!
139 * Boolean indicating that the given PREREQ_ENTRY is armed and ready to fire @ref
140 * callback whenever all PREREQ_IDs specified in @ref requested are satisfied.
141 *
142 * This bit is set during @ref prereqComposeEntry_IMPL(), which will also do an
143 * initial satisfaction check of all @ref requested PREREQ_IDs
144 * and fire the @ref callback if necessary.
145 */
146 NvBool bArmed;
147
148 /*!
149 * @copydoc GpuPrereqCallback
150 */
151 GpuPrereqCallback *callback;
152 } PREREQ_ENTRY;
153 MAKE_LIST(PrereqList, PREREQ_ENTRY);
154
155 /*!
156 * Holds common prerequisite tracking information.
157 */
158
159 // Private field names are wrapped in PRIVATE_FIELD, which does nothing for
160 // the matching C source file, but causes diagnostics to be issued if another
161 // source file references the field.
162 #ifdef NVOC_PREREQ_TRACKER_H_PRIVATE_ACCESS_ALLOWED
163 #define PRIVATE_FIELD(x) x
164 #else
165 #define PRIVATE_FIELD(x) NVOC_PRIVATE_FIELD(x)
166 #endif
167
168 struct PrereqTracker {
169 const struct NVOC_RTTI *__nvoc_rtti;
170 struct Object __nvoc_base_Object;
171 struct Object *__nvoc_pbase_Object;
172 struct PrereqTracker *__nvoc_pbase_PrereqTracker;
173 union PREREQ_ID_BIT_VECTOR satisfied;
174 NvBool bInitialized;
175 PrereqList prereqList;
176 struct OBJGPU *pParent;
177 };
178
179 #ifndef __NVOC_CLASS_PrereqTracker_TYPEDEF__
180 #define __NVOC_CLASS_PrereqTracker_TYPEDEF__
181 typedef struct PrereqTracker PrereqTracker;
182 #endif /* __NVOC_CLASS_PrereqTracker_TYPEDEF__ */
183
184 #ifndef __nvoc_class_id_PrereqTracker
185 #define __nvoc_class_id_PrereqTracker 0x0e171b
186 #endif /* __nvoc_class_id_PrereqTracker */
187
188 extern const struct NVOC_CLASS_DEF __nvoc_class_def_PrereqTracker;
189
190 #define __staticCast_PrereqTracker(pThis) \
191 ((pThis)->__nvoc_pbase_PrereqTracker)
192
193 #ifdef __nvoc_prereq_tracker_h_disabled
194 #define __dynamicCast_PrereqTracker(pThis) ((PrereqTracker*)NULL)
195 #else //__nvoc_prereq_tracker_h_disabled
196 #define __dynamicCast_PrereqTracker(pThis) \
197 ((PrereqTracker*)__nvoc_dynamicCast(staticCast((pThis), Dynamic), classInfo(PrereqTracker)))
198 #endif //__nvoc_prereq_tracker_h_disabled
199
200
201 NV_STATUS __nvoc_objCreateDynamic_PrereqTracker(PrereqTracker**, Dynamic*, NvU32, va_list);
202
203 NV_STATUS __nvoc_objCreate_PrereqTracker(PrereqTracker**, Dynamic*, NvU32, struct OBJGPU * arg_pParent);
204 #define __objCreate_PrereqTracker(ppNewObj, pParent, createFlags, arg_pParent) \
205 __nvoc_objCreate_PrereqTracker((ppNewObj), staticCast((pParent), Dynamic), (createFlags), arg_pParent)
206
207 NV_STATUS prereqConstruct_IMPL(struct PrereqTracker *arg_pTracker, struct OBJGPU *arg_pParent);
208
209 #define __nvoc_prereqConstruct(arg_pTracker, arg_pParent) prereqConstruct_IMPL(arg_pTracker, arg_pParent)
210 void prereqDestruct_IMPL(struct PrereqTracker *pTracker);
211
212 #define __nvoc_prereqDestruct(pTracker) prereqDestruct_IMPL(pTracker)
213 NV_STATUS prereqSatisfy_IMPL(struct PrereqTracker *pTracker, PREREQ_ID prereqId);
214
215 #ifdef __nvoc_prereq_tracker_h_disabled
prereqSatisfy(struct PrereqTracker * pTracker,PREREQ_ID prereqId)216 static inline NV_STATUS prereqSatisfy(struct PrereqTracker *pTracker, PREREQ_ID prereqId) {
217 NV_ASSERT_FAILED_PRECOMP("PrereqTracker was disabled!");
218 return NV_ERR_NOT_SUPPORTED;
219 }
220 #else //__nvoc_prereq_tracker_h_disabled
221 #define prereqSatisfy(pTracker, prereqId) prereqSatisfy_IMPL(pTracker, prereqId)
222 #endif //__nvoc_prereq_tracker_h_disabled
223
224 NV_STATUS prereqRetract_IMPL(struct PrereqTracker *pTracker, PREREQ_ID prereqId);
225
226 #ifdef __nvoc_prereq_tracker_h_disabled
prereqRetract(struct PrereqTracker * pTracker,PREREQ_ID prereqId)227 static inline NV_STATUS prereqRetract(struct PrereqTracker *pTracker, PREREQ_ID prereqId) {
228 NV_ASSERT_FAILED_PRECOMP("PrereqTracker was disabled!");
229 return NV_ERR_NOT_SUPPORTED;
230 }
231 #else //__nvoc_prereq_tracker_h_disabled
232 #define prereqRetract(pTracker, prereqId) prereqRetract_IMPL(pTracker, prereqId)
233 #endif //__nvoc_prereq_tracker_h_disabled
234
235 NvBool prereqIdIsSatisfied_IMPL(struct PrereqTracker *pTracker, PREREQ_ID prereqId);
236
237 #ifdef __nvoc_prereq_tracker_h_disabled
prereqIdIsSatisfied(struct PrereqTracker * pTracker,PREREQ_ID prereqId)238 static inline NvBool prereqIdIsSatisfied(struct PrereqTracker *pTracker, PREREQ_ID prereqId) {
239 NV_ASSERT_FAILED_PRECOMP("PrereqTracker was disabled!");
240 return NV_FALSE;
241 }
242 #else //__nvoc_prereq_tracker_h_disabled
243 #define prereqIdIsSatisfied(pTracker, prereqId) prereqIdIsSatisfied_IMPL(pTracker, prereqId)
244 #endif //__nvoc_prereq_tracker_h_disabled
245
246 NV_STATUS prereqComposeEntry_IMPL(struct PrereqTracker *pTracker, GpuPrereqCallback *callback, union PREREQ_ID_BIT_VECTOR *pDepends, PREREQ_ENTRY **ppPrereq);
247
248 #ifdef __nvoc_prereq_tracker_h_disabled
prereqComposeEntry(struct PrereqTracker * pTracker,GpuPrereqCallback * callback,union PREREQ_ID_BIT_VECTOR * pDepends,PREREQ_ENTRY ** ppPrereq)249 static inline NV_STATUS prereqComposeEntry(struct PrereqTracker *pTracker, GpuPrereqCallback *callback, union PREREQ_ID_BIT_VECTOR *pDepends, PREREQ_ENTRY **ppPrereq) {
250 NV_ASSERT_FAILED_PRECOMP("PrereqTracker was disabled!");
251 return NV_ERR_NOT_SUPPORTED;
252 }
253 #else //__nvoc_prereq_tracker_h_disabled
254 #define prereqComposeEntry(pTracker, callback, pDepends, ppPrereq) prereqComposeEntry_IMPL(pTracker, callback, pDepends, ppPrereq)
255 #endif //__nvoc_prereq_tracker_h_disabled
256
257 #undef PRIVATE_FIELD
258
259
260 #endif // __PREREQUISITE_TRACKER_H__
261
262 #ifdef __cplusplus
263 } // extern "C"
264 #endif
265
266 #endif // _G_PREREQ_TRACKER_NVOC_H_
267