1 /****************************************************************************
2 **
3 ** This file is part of GAP, a system for computational discrete algebra.
4 **
5 ** Copyright of GAP belongs to its developers, whose names are too numerous
6 ** to list here. Please refer to the COPYRIGHT file for details.
7 **
8 ** SPDX-License-Identifier: GPL-2.0-or-later
9 **
10 ** This file declares APIs for GAP modules, including builtin modules,
11 ** or static and dynamic modules used by packages and end users to provide
12 ** kernel extensions.
13 */
14
15 #ifndef GAP_MODULES_H
16 #define GAP_MODULES_H
17
18 #include "system.h"
19
20 /****************************************************************************
21 **
22 *V GAP_KERNEL_API_VERSION
23 **
24 ** 'GAP_KERNEL_API_VERSION' gives the version of the GAP kernel. This value
25 ** is used to check if kernel modules were built with a compatible kernel.
26 ** This version is not the same as, and not connected to, the GAP version.
27 **
28 ** This is stored as
29 ** 'GAP_KERNEL_MAJOR_VERSION*1000 + GAP_KERNEL_MINOR_VERSION'.
30 **
31 ** The algorithm used is the following:
32 **
33 ** The kernel will not load a module compiled for a newer kernel.
34 **
35 ** The kernel will not load a module compiled for a different major version.
36 **
37 ** The minor version should be incremented when new backwards-compatible
38 ** functionality is added. The major version should be incremented when
39 ** a backwards-incompatible change is made.
40 **
41 ** The kernel version is a macro so it can be used by packages
42 ** to optionally compile support for new functionality.
43 **
44 */
45
46 // GAP_KERNEL_MAJOR_VERSION and GAP_KERNEL_MINOR_VERSION are defined in
47 // config.h
48
49 #define GAP_KERNEL_API_VERSION \
50 ((GAP_KERNEL_MAJOR_VERSION)*1000 + (GAP_KERNEL_MINOR_VERSION))
51
52 enum {
53 /** builtin module */
54 MODULE_BUILTIN = GAP_KERNEL_API_VERSION * 10,
55
56 /** statically loaded compiled module */
57 MODULE_STATIC = GAP_KERNEL_API_VERSION * 10 + 1,
58
59 /** dynamically loaded compiled module */
60 MODULE_DYNAMIC = GAP_KERNEL_API_VERSION * 10 + 2,
61 };
62
IS_MODULE_BUILTIN(UInt type)63 EXPORT_INLINE Int IS_MODULE_BUILTIN(UInt type)
64 {
65 return type % 10 == 0;
66 }
67
IS_MODULE_STATIC(UInt type)68 EXPORT_INLINE Int IS_MODULE_STATIC(UInt type)
69 {
70 return type % 10 == 1;
71 }
72
IS_MODULE_DYNAMIC(UInt type)73 EXPORT_INLINE Int IS_MODULE_DYNAMIC(UInt type)
74 {
75 return type % 10 == 2;
76 }
77
78
79 /****************************************************************************
80 **
81 *T StructInitInfo . . . . . . . . . . . . . . . . . module init information
82 */
83 struct init_info {
84
85 /* type of the module: MODULE_BUILTIN, MODULE_STATIC, MODULE_DYNAMIC */
86 UInt type;
87
88 /* name of the module: filename with ".c" or library filename */
89 const Char * name;
90
91 /* revision entry of c file for MODULE_BUILTIN */
92 const Char * revision_c;
93
94 /* revision entry of h file for MODULE_BUILTIN */
95 const Char * revision_h;
96
97 /* version number for MODULE_BUILTIN */
98 UInt version;
99
100 /* CRC value for MODULE_STATIC or MODULE_DYNAMIC */
101 Int crc;
102
103 /* initialise kernel data structures */
104 Int (*initKernel)(StructInitInfo *);
105
106 /* initialise library data structures */
107 Int (*initLibrary)(StructInitInfo *);
108
109 /* sanity check */
110 Int (*checkInit)(StructInitInfo *);
111
112 /* function to call before saving workspace */
113 Int (*preSave)(StructInitInfo *);
114
115 /* function to call after saving workspace */
116 Int (*postSave)(StructInitInfo *);
117
118 /* function to call after restoring workspace */
119 Int (*postRestore)(StructInitInfo *);
120
121 // number of bytes this module needs for its per-thread module state
122 UInt moduleStateSize;
123
124 // if this is not zero, then the module state offset is stored into
125 // the address this points at
126 Int * moduleStateOffsetPtr;
127
128 // initialize thread local module state
129 Int (*initModuleState)(void);
130
131 // destroy thread local module state
132 Int (*destroyModuleState)(void);
133
134 };
135
136
137 /****************************************************************************
138 **
139 *T StructBagNames . . . . . . . . . . . . . . . . . . . . . tnums and names
140 */
141 typedef struct {
142 Int tnum;
143 const Char * name;
144 } StructBagNames;
145
146
147 /****************************************************************************
148 **
149 *T StructGVarFilt . . . . . . . . . . . . . . . . . . . . . exported filter
150 */
151 typedef struct {
152 const Char * name;
153 const Char * argument;
154 Obj * filter;
155 Obj (*handler)(Obj, Obj);
156 const Char * cookie;
157 } StructGVarFilt;
158
159 // GVAR_FILT a helper macro for quickly creating table entries in
160 // StructGVarFilt arrays
161 #define GVAR_FILT(name, argument, filter) \
162 { \
163 #name, argument, filter, Filt##name, __FILE__ ":" #name \
164 }
165
166
167 /****************************************************************************
168 **
169 *T StructGVarAttr . . . . . . . . . . . . . . . . . . . exported attribute
170 */
171 typedef struct {
172 const Char * name;
173 const Char * argument;
174 Obj * attribute;
175 Obj (*handler)(Obj, Obj);
176 const Char * cookie;
177 } StructGVarAttr;
178
179 // GVAR_ATTR a helper macro for quickly creating table entries in
180 // StructGVarAttr arrays
181 #define GVAR_ATTR(name, argument, filter) \
182 { \
183 #name, argument, filter, Attr##name, __FILE__ ":" #name \
184 }
185
186
187 /****************************************************************************
188 **
189 *T StructGVarProp . . . . . . . . . . . . . . . . . . . . exported property
190 */
191 typedef struct {
192 const Char * name;
193 const Char * argument;
194 Obj * property;
195 Obj (*handler)(Obj, Obj);
196 const Char * cookie;
197 } StructGVarProp;
198
199 // GVAR_PROP a helper macro for quickly creating table entries in
200 // StructGVarProp arrays
201 #define GVAR_PROP(name, argument, filter) \
202 { \
203 #name, argument, filter, Prop##name, __FILE__ ":" #name \
204 }
205
206 /****************************************************************************
207 **
208 *T StructGVarOper . . . . . . . . . . . . . . . . . . . exported operation
209 */
210 typedef struct {
211 const Char * name;
212 Int nargs;
213 const Char * args;
214 Obj * operation;
215 ObjFunc handler;
216 const Char * cookie;
217 } StructGVarOper;
218
219 // GVAR_OPER is a helper macro for quickly creating table entries in
220 // StructGVarOper arrays
221 #define GVAR_OPER(name, nargs, args, operation) \
222 { \
223 #name, nargs, args, operation, Func##name, __FILE__ ":" #name \
224 }
225
226
227 /****************************************************************************
228 **
229 *T StructGVarFunc . . . . . . . . . . . . . . . . . . . . exported function
230 */
231 typedef struct {
232 const Char * name;
233 Int nargs;
234 const Char * args;
235 ObjFunc handler;
236 const Char * cookie;
237 } StructGVarFunc;
238
239 // GVAR_FUNC is a helper macro for quickly creating table entries in
240 // StructGVarFunc arrays
241 #define GVAR_FUNC(name, nargs, args) \
242 { \
243 #name, nargs, args, (ObjFunc)Func##name, __FILE__ ":" #name \
244 }
245
246
247 /****************************************************************************
248 **
249 *F InitBagNamesFromTable( <table> ) . . . . . . . . . initialise bag names
250 */
251 void InitBagNamesFromTable(const StructBagNames * tab);
252
253
254 /****************************************************************************
255 **
256 *F InitClearFiltsTNumsFromTable( <tab> ) . . . initialise clear filts tnums
257 */
258 void InitClearFiltsTNumsFromTable(const Int * tab);
259
260
261 /****************************************************************************
262 **
263 *F InitHasFiltListTNumsFromTable( <tab> ) . . initialise tester filts tnums
264 */
265 void InitHasFiltListTNumsFromTable(const Int * tab);
266
267
268 /****************************************************************************
269 **
270 *F InitSetFiltListTNumsFromTable( <tab> ) . . initialise setter filts tnums
271 */
272 void InitSetFiltListTNumsFromTable(const Int * tab);
273
274
275 /****************************************************************************
276 **
277 *F InitResetFiltListTNumsFromTable( <tab> ) initialise unsetter filts tnums
278 */
279 void InitResetFiltListTNumsFromTable(const Int * tab);
280
281
282 /****************************************************************************
283 **
284 *F InitGVarFiltsFromTable( <tab> ) . . . . . . . . . . . . . . . new filters
285 */
286 void InitGVarFiltsFromTable(const StructGVarFilt * tab);
287
288
289 /****************************************************************************
290 **
291 *F InitGVarAttrsFromTable( <tab> ) . . . . . . . . . . . . . new attributes
292 */
293 void InitGVarAttrsFromTable(const StructGVarAttr * tab);
294
295
296 /****************************************************************************
297 **
298 *F InitGVarPropsFromTable( <tab> ) . . . . . . . . . . . . . new properties
299 */
300 void InitGVarPropsFromTable(const StructGVarProp * tab);
301
302
303 /****************************************************************************
304 **
305 *F InitGVarOpersFromTable( <tab> ) . . . . . . . . . . . . . new operations
306 */
307 void InitGVarOpersFromTable(const StructGVarOper * tab);
308
309
310 /****************************************************************************
311 **
312 *F InitGVarFuncsFromTable( <tab> ) . . . . . . . . . . . . . . new function
313 */
314 void InitGVarFuncsFromTable(const StructGVarFunc * tab);
315
316
317 /****************************************************************************
318 **
319 *F InitHdlrFiltsFromTable( <tab> ) . . . . . . . . . . . . . . . new filters
320 */
321 void InitHdlrFiltsFromTable(const StructGVarFilt * tab);
322
323
324 /****************************************************************************
325 **
326 *F InitHdlrAttrsFromTable( <tab> ) . . . . . . . . . . . . . new attributes
327 */
328 void InitHdlrAttrsFromTable(const StructGVarAttr * tab);
329
330
331 /****************************************************************************
332 **
333 *F InitHdlrPropsFromTable( <tab> ) . . . . . . . . . . . . . new properties
334 */
335 void InitHdlrPropsFromTable(const StructGVarProp * tab);
336
337
338 /****************************************************************************
339 **
340 *F InitHdlrOpersFromTable( <tab> ) . . . . . . . . . . . . . new operations
341 */
342 void InitHdlrOpersFromTable(const StructGVarOper * tab);
343
344
345 /****************************************************************************
346 **
347 *F InitHdlrFuncsFromTable( <tab> ) . . . . . . . . . . . . . . new functions
348 */
349 void InitHdlrFuncsFromTable(const StructGVarFunc * tab);
350
351
352 /****************************************************************************
353 **
354 *F ImportGVarFromLibrary( <name>, <address> ) . . . import global variable
355 */
356 void ImportGVarFromLibrary(const Char * name, Obj * address);
357
358
359 /****************************************************************************
360 **
361 *F ImportFuncFromLibrary( <name>, <address> ) . . . import global function
362 */
363 void ImportFuncFromLibrary(const Char * name, Obj * address);
364
365
366 /****************************************************************************
367 **
368 *F ModulesSetup() . . . . . . . . . . . . . . . . . instantiate all modules
369 */
370 void ModulesSetup(void);
371
372 /****************************************************************************
373 **
374 *F ModulesInitKernel() . . . . . . . . . . call 'initKernel' for all modules
375 *F ModulesInitLibrary() . . . . . . . . . call 'initLibrary' for all modules
376 *F ModulesCheckInit() . . . . . . . . . . . call 'checkInit' for all modules
377 *F ModulesPreSave() . . . . . . . . . . . . . call 'preSave' for all modules
378 *F ModulesPostSave() . . . . . . . . . . . . call 'postSave' for all modules
379 *F ModulesPostRestore() . . . . . . . . . call 'postRestore' for all modules
380 */
381 void ModulesInitKernel(void);
382 void ModulesInitLibrary(void);
383 void ModulesCheckInit(void);
384 Int ModulesPreSave(void);
385 void ModulesPostSave(void);
386 void ModulesPostRestore(void);
387
388 void ModulesInitModuleState(void);
389 void ModulesDestroyModuleState(void);
390
391 void SaveModules(void);
392 void LoadModules(void);
393
394
395 /****************************************************************************
396 **
397 *F ActivateModule( <info> )
398 */
399 void ActivateModule(StructInitInfo * info);
400
401
402 /****************************************************************************
403 **
404 *F RecordLoadedModule( <module> ) . . . . . . . . store module in <Modules>
405 **
406 ** The filename argument is a C string. A copy of it is taken in some
407 ** private space and added to the module info.
408 **
409 ** This function triggers no garbage collection, so it OK to pass a pointer
410 ** to the content of a GAP string object as filename.
411 */
412 void RecordLoadedModule(StructInitInfo * module,
413 Int isGapRootRelative,
414 const Char * filename);
415
416
417 /****************************************************************************
418 **
419 *F * * * * * * * * * * * * * * initialize module * * * * * * * * * * * * * *
420 */
421
422 /****************************************************************************
423 **
424 *F InitInfoModules() . . . . . . . . . . . . . . . . table of init functions
425 */
426 StructInitInfo * InitInfoModules(void);
427
428
429 #endif // GAP_MODULES_H
430