1 /*
2 progs.h
3
4 Progs VM Engine interface.
5
6 Copyright (C) 1996-1997 Id Software, Inc.
7
8 This program is free software; you can redistribute it and/or
9 modify it under the terms of the GNU General Public License
10 as published by the Free Software Foundation; either version 2
11 of the License, or (at your option) any later version.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16
17 See the GNU General Public License for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to:
21
22 Free Software Foundation, Inc.
23 59 Temple Place - Suite 330
24 Boston, MA 02111-1307, USA
25
26 */
27
28 #ifndef __QF_progs_h
29 #define __QF_progs_h
30
31 /** \defgroup progs QuakeC Virtual Machine (VM)
32 \image html vm-mem.svg
33 \image latex vm-mem.eps "VM memory map"
34 */
35
36 #include "QF/pr_comp.h"
37 #include "QF/pr_debug.h"
38
39 struct QFile_s;
40
41 /** \ingroup progs */
42 //@{
43 typedef struct progs_s progs_t;
44 typedef struct pr_resource_s pr_resource_t;
45 typedef struct edict_s edict_t;
46 //@}
47
48 //============================================================================
49
50 /** \defgroup progs_misc Miscelaneous functions
51 \ingroup progs
52 */
53 //@{
54
55 /** Initialize the progs engine.
56 */
57 void PR_Init (void);
58
59 /** Initialize the Cvars for the progs engine. Call before calling PR_Init().
60 */
61 void PR_Init_Cvars (void);
62
63 void PR_Error (progs_t *pr, const char *error, ...) __attribute__((format(printf,2,3), noreturn));
64 void PR_RunError (progs_t *pr, const char *error, ...) __attribute__((format(printf,2,3), noreturn));
65
66 //@}
67
68 /** \defgroup progs_execution Execution
69 \ingroup progs
70 */
71 //@{
72
73 /** Ensure P_* macros point to the right place for passing parameters to progs
74 functions.
75 \param pr pointer to ::progs_t VM struct
76
77 \warning Failure to use this macro before assigning to the P_* macros can
78 cause corruption of the VM data due to "register" based calling. Can be
79 safely ignored for parameterless functions, or forwarding parameters
80 though a builtin.
81
82 \hideinitializer
83 */
84 #define PR_RESET_PARAMS(pr) \
85 do { \
86 (pr)->pr_params[0] = (pr)->pr_real_params[0]; \
87 (pr)->pr_params[1] = (pr)->pr_real_params[1]; \
88 } while (0)
89
90 /** Save the current parameters.
91 \param pr pointer to ::progs_t VM struct
92 */
93 void PR_SaveParams (progs_t *pr);
94
95 /** Restore the parameters saved by PR_SaveParams().
96 \param pr pointer to ::progs_t VM struct
97 */
98 void PR_RestoreParams (progs_t *pr);
99
100 /** Push an execution frame onto the VM stack. Saves current execution state.
101 \param pr pointer to ::progs_t VM struct
102 */
103 void PR_PushFrame (progs_t *pr);
104
105 /** Pop an execution frame from the VM stack. Restores execution state. Also
106 frees any temporary strings allocated in this frame (via
107 PR_FreeTempStrings()).
108 \param pr pointer to ::progs_t VM struct
109 */
110 void PR_PopFrame (progs_t *pr);
111
112 /** Run a progs function. If \p fnum is a builtin rather than a progs
113 function, PR_ExecuteProgram() will call the function and then immediately
114 return to the caller. Nested calls are fully supported.
115 \param pr pointer to ::progs_t VM struct
116 \param fnum number of the function to call
117 */
118 void PR_ExecuteProgram (progs_t *pr, func_t fnum);
119
120 /** Setup to call a function. If \p fnum is a builtin rather than a progs
121 function, then the function is called immediately. When called from a
122 builtin function, and \p fnum is not a builtin, the progs function will
123 execute upon return of control to PR_ExecuteProgram().
124 \param pr pointer to ::progs_t VM struct
125 \param fnum number of the function to call
126 \return true if \p fnum was a progs function, false if \p fnum was
127 a builtin
128 */
129 int PR_CallFunction (progs_t *pr, func_t fnum);
130
131 //@}
132
133 /** \defgroup progs_load Loading
134 \ingroup progs
135 */
136 //@{
137
138 /** Type of functions that are called at progs load.
139 \param pr pointer to ::progs_t VM struct
140 \return true for success, false for failure
141 */
142 typedef int pr_load_func_t (progs_t *pr);
143
144 /** Initialize a ::progs_t VM struct from an already open file.
145 \param pr pointer to ::progs_t VM struct
146 \param file handle of file to read progs data from
147 \param size bytes of \p file to read
148 \param max_edicts \e number of entities to allocate space for
149 \param zone minimum size of dynamic memory to allocate space for
150 dynamic memory (bytes).
151
152 \note \e All runtime strings (permanent or temporary) are allocated from
153 the VM's dynamic memory space, so be sure \p zone is of sufficient size.
154 So far, 1MB has proven more than sufficient for Quakeword, even when using
155 Ruamoko objects.
156 */
157 void PR_LoadProgsFile (progs_t *pr, struct QFile_s *file, int size,
158 int max_edicts, int zone);
159
160 /** Convenience wrapper for PR_LoadProgsFile() and PR_RunLoadFuncs().
161 Searches for the specified file in the Quake filesystem.
162 \param pr pointer to ::progs_t VM struct
163 \param progsname name of the file to load as progs data
164 \param max_edicts \e number of entities to allocate space for
165 \param zone minimum size of dynamic memory to allocate space for
166 */
167 void PR_LoadProgs (progs_t *pr, const char *progsname, int max_edicts,
168 int zone);
169
170 /** Register a primary function to be called after the progs code has been
171 loaded. These functions are remembered across progs loads. They will be
172 called in order of registration.
173 \param pr pointer to ::progs_t VM struct
174 \param func function to call
175 */
176 void PR_AddLoadFunc (progs_t *pr, pr_load_func_t *func);
177
178 /** Register a secondary function to be called after the progs code has been
179 loaded. These functions will be forgotten after each load. They will be
180 called in \e reverse order of being registered.
181 \param pr pointer to ::progs_t VM struct
182 \param func function to call
183 */
184 void PR_AddLoadFinishFunc (progs_t *pr, pr_load_func_t *func);
185
186 /** Run all load functions. Any load function returning false will abort the
187 load operation.
188 \param pr pointer to ::progs_t VM struct
189 \return true for success, false for failure
190
191 Calls the first set of internal load functions followed by the supplied
192 symbol resolution function, if any (progs_t::resolve), the second set of
193 internal load functions. After that, any primary load functions are called
194 in order of registration followed by any \c .ctor functions in the progs,
195 then any secondary load functions the primary load functions registered
196 in \e reverse order of registration.
197 */
198 int PR_RunLoadFuncs (progs_t *pr);
199
200 /** Validate the opcodes and statement addresses in the progs. This is an
201 internal load function.
202 \param pr pointer to ::progs_t VM struct
203 \return true for success, false for failure
204
205 \todo should this be elsewhere?
206 */
207 int PR_Check_Opcodes (progs_t *pr);
208
209 void PR_BoundsCheckSize (progs_t *pr, pointer_t addr, unsigned size);
210 void PR_BoundsCheck (progs_t *pr, int addr, etype_t type);
211
212 //@}
213
214 /** \defgroup progs_edict Edict management
215 \ingroup progs
216 */
217 //@{
218
219 struct edict_s {
220 qboolean free;
221 int entnum; ///< number of this entity
222 float freetime; ///< sv.time when the object was freed
223 void *edata; ///< external per-edict data
224 pr_type_t v[1]; ///< fields from progs
225 };
226
227 // pr_edict.c
228 void ED_ClearEdict (progs_t *pr, edict_t *e, int val);
229 edict_t *ED_Alloc (progs_t *pr);
230 void ED_Free (progs_t *pr, edict_t *ed);
231 edict_t *ED_EdictNum(progs_t *pr, pr_int_t n);
232 pr_int_t ED_NumForEdict(progs_t *pr, edict_t *e);
233 void ED_Count (progs_t *pr);
234 qboolean PR_EdictValid (progs_t *pr, pr_int_t e);
235
236 // pr_debug.c
237 void ED_Print (progs_t *pr, edict_t *ed);
238 void ED_PrintEdicts (progs_t *pr, const char *fieldval);
239 void ED_PrintNum (progs_t *pr, pr_int_t ent);
240
241 // pr_parse.c
242 struct script_s;
243 struct plitem_s;
244 qboolean ED_ParseEpair (progs_t *pr, pr_type_t *base, ddef_t *key,
245 const char *s);
246 struct plitem_s *ED_EntityDict (progs_t *pr, edict_t *ed);
247 struct plitem_s *ED_GlobalsDict (progs_t *pr);
248 void ED_InitGlobals (progs_t *pr, struct plitem_s *globals);
249 void ED_InitEntity (progs_t *pr, struct plitem_s *entity, edict_t *ent);
250 struct plitem_s *ED_ConvertToPlist (progs_t *pr, struct script_s *script);
251 struct plitem_s *ED_Parse (progs_t *pr, const char *data);
252 void ED_LoadFromFile (progs_t *pr, const char *data);
253 void ED_EntityParseFunction (progs_t *pr);
254
255 #define PR_edicts(p) ((byte *) *(p)->edicts)
256
257 #define NEXT_EDICT(p,e) ((edict_t *) ((byte *) e + (p)->pr_edict_size))
258 #define EDICT_TO_PROG(p,e) ((pr_int_t)(intptr_t)((byte *)(e) - PR_edicts (p)))
259 #define PROG_TO_EDICT(p,e) ((edict_t *) (PR_edicts (p) + (e)))
260 #define NUM_FOR_BAD_EDICT(p,e) ((e)->entnum)
261 #ifndef PR_PARANOID_PROGS
262 # define EDICT_NUM(p,n) (PROG_TO_EDICT (p, (n) * (p)->pr_edict_size))
263 # define NUM_FOR_EDICT(p,e) NUM_FOR_BAD_EDICT (p, e)
264 #else
265 # define EDICT_NUM(p,n) ED_EdictNum (p, n)
266 # define NUM_FOR_EDICT(p,e) ED_NumForEdict (p, e)
267 #endif
268
269 //@}
270
271 /** \defgroup pr_symbols Symbol Management
272 \ingroup progs
273 Lookup functions for symbol name resolution.
274 */
275 //@{
276
277 ddef_t *PR_FieldAtOfs (progs_t *pr, pr_int_t ofs);
278 ddef_t *PR_GlobalAtOfs (progs_t *pr, pr_int_t ofs);
279
280 ddef_t *PR_FindField (progs_t *pr, const char *name);
281 ddef_t *PR_FindGlobal (progs_t *pr, const char *name);
282 dfunction_t *PR_FindFunction (progs_t *pr, const char *name);
283
284 int PR_ResolveGlobals (progs_t *pr);
285
286 int PR_AccessField (progs_t *pr, const char *name, etype_t type,
287 const char *file, int line);
288
289 void PR_Undefined (progs_t *pr, const char *type, const char *name) __attribute__((noreturn));
290 //@}
291
292 //============================================================================
293
294 /** \defgroup progs_data_access Data Access
295 \ingroup progs
296 Macros for accessing data in the VM address space
297 */
298
299 /** \defgroup prda_globals Globals
300 \ingroup progs_data_access
301 Typed global access macros. No checking is done against the QC type, but
302 the appropriate C type will be used.
303 */
304 //@{
305
306 /** \internal
307 \param p pointer to ::progs_t VM struct
308 \param o offset into global data space
309 \param t typename prefix (see pr_type_u)
310 \return lvalue of the appropriate type
311
312 \hideinitializer
313 */
314 #define G_var(p,o,t) ((p)->pr_globals[o].t##_var)
315
316 /** Access a float global. Can be assigned to.
317
318 \par QC type:
319 \c float
320 \param p pointer to ::progs_t VM struct
321 \param o offset into global data space
322 \return float lvalue
323
324 \hideinitializer
325 */
326 #define G_FLOAT(p,o) G_var (p, o, float)
327
328 /** Access an integer global. Can be assigned to.
329
330 \par QC type:
331 \c integer
332 \param p pointer to ::progs_t VM struct
333 \param o offset into global data space
334 \return int lvalue
335
336 \hideinitializer
337 */
338 #define G_INT(p,o) G_var (p, o, integer)
339
340 /** Access an unsigned integer global. Can be assigned to.
341
342 \par QC type:
343 \c uinteger
344 \param p pointer to ::progs_t VM struct
345 \param o offset into global data space
346 \return unsigned int lvalue
347
348 \hideinitializer
349 */
350 #define G_UINT(p,o) G_var (p, o, uinteger)
351
352 /** Access a vector global. Can be assigned to.
353
354 \par QC type:
355 \c vector
356 \param p pointer to ::progs_t VM struct
357 \param o offset into global data space
358 \return vec3_t lvalue
359
360 \hideinitializer
361 */
362 #define G_VECTOR(p,o) G_var (p, o, vector)
363
364 /** Access a quaternion global. Can be assigned to.
365
366 \par QC type:
367 \c quaternion
368 \param p pointer to ::progs_t VM struct
369 \param o offset into global data space
370 \return quat_t lvalue
371
372 \hideinitializer
373 */
374 #define G_QUAT(p,o) G_var (p, o, quat)
375
376 /** Access a string index global. Can be assigned to.
377
378 \par QC type:
379 \c string
380 \param p pointer to ::progs_t VM struct
381 \param o offset into global data space
382 \return string_t lvalue
383
384 \hideinitializer
385 */
386 #define G_STRING(p,o) G_var (p, o, string)
387
388 /** Access a function global. Can be assigned to.
389
390 \par QC type:
391 \c void()
392 \param p pointer to ::progs_t VM struct
393 \param o offset into global data space
394 \return func_t lvalue
395
396 \hideinitializer
397 */
398 #define G_FUNCTION(p,o) G_var (p, o, func)
399
400 /** Access a pointer global. Can be assigned to.
401
402 \par QC type:
403 \c void *
404 \param p pointer to ::progs_t VM struct
405 \param o offset into global data space
406 \return pointer_t lvalue
407
408 \hideinitializer
409 */
410 #define G_POINTER(p,o) G_var (p, o, pointer)
411
412
413 /** Access an entity global.
414
415 \par QC type:
416 \c entity
417 \param p pointer to ::progs_t VM struct
418 \param o offset into global data space
419 \return C pointer to the entity
420
421 \hideinitializer
422 */
423 #define G_EDICT(p,o) ((edict_t *)(PR_edicts (p) + G_INT (p, o)))
424
425 /** Access an entity global.
426
427 \par QC type:
428 \c entity
429 \param p pointer to ::progs_t VM struct
430 \param o offset into global data space
431 \return the entity number
432
433 \hideinitializer
434 */
435 #define G_EDICTNUM(p,o) NUM_FOR_EDICT(p, G_EDICT (p, o))
436
437 /** Access a string global, converting it to a C string. Kills the program
438 if the string is invalid.
439
440 \par QC type:
441 \c string
442 \param p pointer to ::progs_t VM struct
443 \param o offset into global data space
444 \return const char * to the string
445
446 \hideinitializer
447 */
448 #define G_GSTRING(p,o) PR_GetString (p, G_STRING (p, o))
449
450 /** Access a dstring global. Kills the program if the dstring is invalid.
451
452 \par QC type:
453 \c string
454 \param p pointer to ::progs_t VM struct
455 \param o offset into global data space
456 \return dstring_t * to the dstring
457
458 \hideinitializer
459 */
460 #define G_DSTRING(p,o) PR_GetMutableString (p, G_STRING (p, o))
461
462 /** Access a pointer parameter.
463
464 \par QC type:
465 \c void *
466 \param p pointer to ::progs_t VM struct
467 \param o offset into global data space
468 \return C pointer represented by the parameter. 0 offset -> NULL
469
470 \hideinitializer
471 */
472 #define G_GPOINTER(p,o) PR_GetPointer (p, o)
473
474 /** Access a structure global. Can be assigned to.
475
476 \par QC type:
477 \c void *
478 \param p pointer to ::progs_t VM struct
479 \param t C type of the structure
480 \param o offset into global data space
481 \return structure lvalue. use & to make a pointer of the
482 appropriate type.
483
484 \hideinitializer
485 */
486 #define G_STRUCT(p,t,o) (*(t *)G_GPOINTER (p, o))
487 //@}
488
489 /** \defgroup prda_parameters Parameters
490 \ingroup progs_data_access
491 Typed parameter access macros. No checking is done against the QC type, but
492 the appropriate C type will be used.
493 */
494 //@{
495
496 /** \internal
497 \param p pointer to ::progs_t VM struct
498 \param n parameter number (0-7)
499 \param t typename prefix (see pr_type_u)
500 \return lvalue of the appropriate type
501
502 \hideinitializer
503 */
504 #define P_var(p,n,t) ((p)->pr_params[n]->t##_var)
505
506 /** Access a float parameter. Can be assigned to.
507
508 \par QC type:
509 \c float
510 \param p pointer to ::progs_t VM struct
511 \param n parameter number (0-7)
512 \return float lvalue
513
514 \hideinitializer
515 */
516 #define P_FLOAT(p,n) P_var (p, n, float)
517
518 /** Access an integer parameter. Can be assigned to.
519
520 \par QC type:
521 \c integer
522 \param p pointer to ::progs_t VM struct
523 \param n parameter number (0-7)
524 \return int lvalue
525
526 \hideinitializer
527 */
528 #define P_INT(p,n) P_var (p, n, integer)
529
530 /** Access an unsigned integer parameter. Can be assigned to.
531
532 \par QC type:
533 \c uinteger
534 \param p pointer to ::progs_t VM struct
535 \param n parameter number (0-7)
536 \return unsigned int lvalue
537
538 \hideinitializer
539 */
540 #define P_UINT(p,n) P_var (p, n, uinteger)
541
542 /** Access a vector parameter. Can be used any way a vec3_t variable can.
543
544 \par QC type:
545 \c vector
546 \param p pointer to ::progs_t VM struct
547 \param n parameter number (0-7)
548 \return vec3_t lvalue
549
550 \hideinitializer
551 */
552 #define P_VECTOR(p,n) P_var (p, n, vector)
553
554 /** Access a quaterion parameter. Can be used any way a quat_t variable can.
555
556 \par QC type:
557 \c quaterion
558 \param p pointer to ::progs_t VM struct
559 \param n parameter number (0-7)
560 \return quat_t lvalue
561
562 \hideinitializer
563 */
564 #define P_QUAT(p,n) P_var (p, n, quat)
565
566 /** Access a string index parameter. Can be assigned to.
567
568 \par QC type:
569 \c string
570 \param p pointer to ::progs_t VM struct
571 \param n parameter number (0-7)
572 \return string_t lvalue
573
574 \hideinitializer
575 */
576 #define P_STRING(p,n) P_var (p, n, string)
577
578 /** Access a function parameter. Can be assigned to.
579
580 \par QC type:
581 \c void()
582 \param p pointer to ::progs_t VM struct
583 \param n parameter number (0-7)
584 \return func_t lvalue
585
586 \hideinitializer
587 */
588 #define P_FUNCTION(p,n) P_var (p, n, func)
589
590 /** Access a pointer parameter. Can be assigned to.
591
592 \par QC type:
593 \c void *
594 \param p pointer to ::progs_t VM struct
595 \param n parameter number (0-7)
596 \return pointer_t lvalue
597
598 \hideinitializer
599 */
600 #define P_POINTER(p,n) P_var (p, n, pointer)
601
602
603 /** Access an entity parameter.
604
605 \par QC type:
606 \c entity
607 \param p pointer to ::progs_t VM struct
608 \param n parameter number (0-7)
609 \return C pointer to the entity
610
611 \hideinitializer
612 */
613 #define P_EDICT(p,n) ((edict_t *)(PR_edicts (p) + P_INT (p, n)))
614
615 /** Access an entity parameter.
616
617 \par QC type:
618 \c entity
619 \param p pointer to ::progs_t VM struct
620 \param n parameter number (0-7)
621 \return the entity number
622
623 \hideinitializer
624 */
625 #define P_EDICTNUM(p,n) NUM_FOR_EDICT (p, P_EDICT (p, n))
626
627 /** Access a string parameter, converting it to a C string. Kills the program
628 if the string is invalid.
629
630 \par QC type:
631 \c string
632 \param p pointer to ::progs_t VM struct
633 \param n parameter number (0-7)
634 \return const char * to the string
635
636 \hideinitializer
637 */
638 #define P_GSTRING(p,n) PR_GetString (p, P_STRING (p, n))
639
640 /** Access a dstring parameter. Kills the program if the dstring is invalid.
641
642 \par QC type:
643 \c string
644 \param p pointer to ::progs_t VM struct
645 \param n parameter number (0-7)
646 \return dstring_t * to the dstring
647
648 \hideinitializer
649 */
650 #define P_DSTRING(p,n) PR_GetMutableString (p, P_STRING (p, n))
651
652 /** Access a pointer parameter.
653
654 \par QC type:
655 \c void *
656 \param p pointer to ::progs_t VM struct
657 \param n parameter number (0-7)
658 \return C pointer represented by the parameter. 0 offset -> NULL
659
660 \hideinitializer
661 */
662 #define P_GPOINTER(p,n) PR_GetPointer (p, P_POINTER (p, n))
663
664 /** Access a structure pointer parameter.
665
666 \par QC type:
667 \c void *
668 \param p pointer to ::progs_t VM struct
669 \param t C type of the structure
670 \param n parameter number (0-7)
671 \return structure lvalue. use & to make a pointer of the
672 appropriate type.
673
674 \hideinitializer
675 */
676 #define P_STRUCT(p,t,n) (*(t *)P_GPOINTER (p, n))
677 //@}
678
679 /** \defgroup prda_return Return Values
680 \ingroup progs_data_access
681 These macros are used to access the value returned by an interpreted VM
682 function, and to return values from engine functions into progs space
683 (that is, builtins).
684 \warning No checking is performed against progs types; for example, if you
685 ask for an \c int from a function that returned a \c float, you're asking
686 for trouble.
687 */
688 //@{
689
690 /** \internal
691 \param p pointer to ::progs_t VM struct
692 \param t typename prefix (see pr_type_u)
693 \return lvalue of the appropriate type
694
695 \hideinitializer
696 */
697 #define R_var(p,t) ((p)->pr_return->t##_var)
698
699 /** Access the VM function return value as a \c float
700
701 \par QC type:
702 \c float
703 \param p pointer to ::progs_t VM struct
704 \return float lvalue
705
706 \hideinitializer
707 */
708 #define R_FLOAT(p) R_var (p, float)
709
710 /** Access the VM function return value as a \c ::pr_int_t (AKA int32_t)
711
712 \par QC type:
713 \c integer
714 \param p pointer to ::progs_t VM struct
715 \return ::pr_int_t lvalue
716
717 \hideinitializer
718 */
719 #define R_INT(p) R_var (p, integer)
720
721 /** Access the VM function return value as a \c ::pr_uint_t (AKA uint32_t)
722
723 \par QC type:
724 \c uinteger
725 \param p pointer to ::progs_t VM struct
726 \return ::pr_int_t lvalue
727
728 \hideinitializer
729 */
730 #define R_UINT(p) R_var (p, uinteger)
731
732 /** Access the VM function return value as a \c ::vec3_t vector.
733
734 \par QC type:
735 \c vector
736 \param p pointer to ::progs_t VM struct
737 \return ::vec3_t lvalue
738
739 \hideinitializer
740 */
741 #define R_VECTOR(p) R_var (p, vector)
742
743 /** Access the VM function return value as a \c ::quat_t quaternion.
744
745 \par QC type:
746 \c quaternion
747 \param p pointer to ::progs_t VM struct
748 \return ::quat_t lvalue
749
750 \hideinitializer
751 */
752 #define R_QUAT(p) R_var (p, quat)
753
754 /** Access the VM function return value as a ::string_t (a VM string reference).
755
756 \par QC type:
757 \c string
758 \param p pointer to ::progs_t VM struct
759 \return ::string_t lvalue
760
761 \hideinitializer
762 */
763 #define R_STRING(p) R_var (p, string)
764
765 /** Access the VM function return value as a ::func_t (a VM function reference)
766
767 \par QC type:
768 \c void()
769 \param p pointer to ::progs_t VM struct
770 \return ::func_t lvalue
771
772 \hideinitializer
773 */
774 #define R_FUNCTION(p) R_var (p, func)
775
776 /** Access the VM function return value as a ::pointer_t (a VM "pointer")
777
778 \par QC type:
779 \c void *
780 \param p pointer to ::progs_t VM struct
781 \return ::pointer_t lvalue
782
783 \hideinitializer
784 */
785 #define R_POINTER(p) R_var (p, pointer)
786
787
788 /** Set the return value to the given C string. The returned string will
789 eventually be garbage collected (see PR_SetReturnString()).
790
791 \par QC type:
792 \c string
793 \param p pointer to ::progs_t VM struct
794 \param s C string to be returned
795
796 \hideinitializer
797 */
798 #define RETURN_STRING(p,s) (R_STRING (p) = PR_SetReturnString((p), s))
799
800 /** Set the return value to the given C entity pointer. The pointer is
801 converted into a progs entity address.
802
803 \par QC type:
804 \c entity
805 \param p pointer to ::progs_t VM struct
806 \param e C entity pointer to be returned
807
808 \hideinitializer
809 */
810 #define RETURN_EDICT(p,e) (R_STRING (p) = EDICT_TO_PROG(p, e))
811
812 /** Set the return value to the given C pointer. NULL is converted to 0.
813
814 \par QC type:
815 \c void *
816 \param p pointer to ::progs_t VM struct
817 \param ptr C entity pointer to be returned
818
819 \hideinitializer
820 */
821 #define RETURN_POINTER(p,ptr) (R_POINTER (p) = PR_SetPointer (p, ptr))
822
823 /** Set the return value to the given vector.
824
825 \par QC type:
826 \c vector
827 \param p pointer to ::progs_t VM struct
828 \param v vector to be returned
829
830 \hideinitializer
831 */
832 #define RETURN_VECTOR(p,v) VectorCopy (v, R_VECTOR (p))
833
834 /** Set the return value to the given quaterion.
835
836 \par QC type:
837 \c vector
838 \param p pointer to ::progs_t VM struct
839 \param q quaternion to be returned
840
841 \hideinitializer
842 */
843 #define RETURN_QUAT(p,q) VectorCopy (q, R_QUAT (p))
844 //@}
845
846 /** \defgroup prda_entity_fields Entity Fields
847 \ingroup progs_data_access
848 Typed entity field access macros. No checking is done against the QC type,
849 but the appropriate C type will be used.
850 */
851 //@{
852
853 /** \internal
854 \param e pointer to the entity
855 \param o field offset into entity data space
856 \param t typename prefix (see pr_type_u)
857 \return lvalue of the appropriate type
858
859 \hideinitializer
860 */
861 #define E_var(e,o,t) ((e)->v[o].t##_var)
862
863
864 /** Access a float entity field. Can be assigned to.
865
866 \par QC type:
867 \c float
868 \param e pointer to the entity
869 \param o field offset into entity data space
870 \return float lvalue
871
872 \hideinitializer
873 */
874 #define E_FLOAT(e,o) E_var (e, o, float)
875
876 /** Access an integer entity field. Can be assigned to.
877
878 \par QC type:
879 \c integer
880 \param e pointer to the entity
881 \param o field offset into entity data space
882 \return int lvalue
883
884 \hideinitializer
885 */
886 #define E_INT(e,o) E_var (e, o, integer)
887
888 /** Access an unsigned integer entity field. Can be assigned to.
889
890 \par QC type:
891 \c uinteger
892 \param e pointer to the entity
893 \param o field offset into entity data space
894 \return unsigned int lvalue
895
896 \hideinitializer
897 */
898 #define E_UINT(e,o) E_var (e, o, uinteger)
899
900 /** Access a vector entity field. Can be used any way a vec3_t variable can.
901
902 \par QC type:
903 \c vector
904 \param e pointer to the entity
905 \param o field offset into entity data space
906 \return vec3_t lvalue
907
908 \hideinitializer
909 */
910 #define E_VECTOR(e,o) E_var (e, o, vector)
911
912 /** Access a quaternion entity field. Can be used any way a quat_t variable
913 can.
914
915 \par QC type:
916 \c quaterion
917 \param e pointer to the entity
918 \param o field offset into entity data space
919 \return quat_t lvalue
920
921 \hideinitializer
922 */
923 #define E_QUAT(e,o) E_var (e, o, quat)
924
925 /** Access a string index entity field. Can be assigned to.
926
927 \par QC type:
928 \c string
929 \param e pointer to the entity
930 \param o field offset into entity data space
931 \return string_t lvalue
932
933 \hideinitializer
934 */
935 #define E_STRING(e,o) E_var (e, o, string)
936
937 /** Access a function entity field. Can be assigned to.
938
939 \par QC type:
940 \c void()
941 \param e pointer to the entity
942 \param o field offset into entity data space
943 \return func_t lvalue
944
945 \hideinitializer
946 */
947 #define E_FUNCTION(e,o) E_var (e, o, func)
948
949 /** Access a pointer entity field. Can be assigned to.
950
951 \par QC type:
952 \c void *
953 \param e pointer to the entity
954 \param o field offset into entity data space
955 \return pointer_t lvalue
956
957 \hideinitializer
958 */
959 #define E_POINTER(e,o) E_var (e, o, pointer)
960
961
962 /** Access a string entity field, converting it to a C string. Kills the
963 program if the string is invalid.
964
965 \par QC type:
966 \c string
967 \param p pointer to ::progs_t VM struct
968 \param e pointer to the entity
969 \param o field offset into entity data space
970 \return const char * to the string
971
972 \hideinitializer
973 */
974 #define E_GSTRING(p,e,o) (PR_GetString (p, E_STRING (e, o)))
975
976 /** Access a dstring entity field. Kills the program if the dstring is invalid.
977
978 \par QC type:
979 \c string
980 \param p pointer to ::progs_t VM struct
981 \param e pointer to the entity
982 \param o field offset into entity data space
983 \return dstring_t * to the dstring
984
985 \hideinitializer
986 */
987 #define E_DSTRING(p,e,o) (PR_GetMutableString (p, E_STRING (e, o)))
988 //@}
989
990 /** \defgroup pr_builtins VM Builtin functions
991 \ingroup progs
992 Builtin management functions.
993
994 Builtins are arranged into groups of 65536 to allow for diffent expantion
995 sets. eg, stock id is 0x0000xxxx, quakeforge is 0x000fxxxx. predefined
996 groups go up to 0x0fffxxxx allowing 4096 different groups. Builtins
997 0x10000000 to 0x7fffffff are reserved for auto-allocation. The range
998 0x8000000 to 0xffffffff is unavailable due to the builtin number being
999 a negative statement address.
1000 */
1001 //@{
1002
1003 #define PR_RANGE_SHIFT 16
1004 #define PR_RANGE_MASK 0xffff0000
1005
1006 #define PR_RANGE_QF 0x000f
1007
1008 #define PR_RANGE_AUTO 0x1000
1009 #define PR_RANGE_MAX 0x7fff
1010 #define PR_RANGE_NONE 0xffff
1011 #define PR_AUTOBUILTIN (PR_RANGE_AUTO << PR_RANGE_SHIFT)
1012
1013 typedef void (*builtin_proc) (progs_t *pr);
1014
1015 /** Create a static array of these and pass the array to PR_RegisterBuiltins()
1016 to register the module's QC builtin functions.
1017 */
1018 typedef struct {
1019 /// QC name of the builtin. Must be an exact match for automatically
1020 /// resolved builtins (func = \#0 in QC). NULL indicates end of array for
1021 /// PR_RegisterBuiltins()
1022 const char *name;
1023 /// Pointer to the C implementation of the builtin function.
1024 builtin_proc proc;
1025 /// The number of the builtin for \#N in QC. -1 for automatic allocation.
1026 /// 0 or >= ::PR_AUTOBUILTIN is invalid.
1027 pr_int_t binum;
1028 } builtin_t;
1029
1030 /** Duplicate the dfunction_t descriptor with the addition of a pointer to the
1031 builtin function. Avoids a level of indirection when calling a builtin
1032 function.
1033 */
1034 typedef struct {
1035 pr_int_t first_statement;
1036 pr_int_t parm_start;
1037 pr_int_t locals;
1038 pr_int_t profile;
1039 pr_int_t numparms;
1040 uint8_t parm_size[MAX_PARMS];
1041 dfunction_t *descriptor;
1042 builtin_proc func;
1043 } bfunction_t;
1044
1045 /** Register a set of builtin functions with the VM. Different VMs within the
1046 same program can have different builtin sets. May be called multiple times
1047 for the same VM, but redefining a builtin is an error.
1048 \param pr pointer to ::progs_t VM struct
1049 \param builtins array of builtin_t builtins
1050 */
1051 void PR_RegisterBuiltins (progs_t *pr, builtin_t *builtins);
1052
1053 /** Lookup a builtin function referred by name.
1054 \param pr pointer to ::progs_t VM struct
1055 \param name name of the builtin function to lookup
1056 \return pointer to the builtin function entry, or NULL if not found
1057 */
1058 builtin_t *PR_FindBuiltin (progs_t *pr, const char *name);
1059
1060 /** Lookup a builtin function by builtin number.
1061 \param pr pointer to ::progs_t VM struct
1062 \param num number of the builtin function to lookup
1063 \return pointer to the builtin function entry, or NULL if not found
1064 */
1065 builtin_t *PR_FindBuiltinNum (progs_t *pr, pr_int_t num);
1066
1067 /** Fixup all automatically resolved builtin functions (func = #0 in QC).
1068 Performs any necessary builtin function number mapping. Also builds the
1069 bfunction_t table. Called automatically during progs load.
1070 \param pr pointer to ::progs_t VM struct
1071 \return true for success, false for failure
1072 */
1073 int PR_RelocateBuiltins (progs_t *pr);
1074
1075 //@}
1076
1077 /** \defgroup pr_strings String Management
1078 \ingroup progs
1079 Strings management functions.
1080
1081 All strings accessable by the VM are stored within the VM address space.
1082 These functions provide facilities to set permanent, dynamic and
1083 temporary strings, as well as mutable strings using dstrings.
1084
1085 Permanent strings are either supplied by the progs (+ve string index) or
1086 set by the main program using PR_SetString(). Permanent strings can never
1087 be altered and will exist until the next progs load.
1088
1089 Dynamic strings can be freed at any time, but not altered.
1090
1091 Temporary strings are always set by the main program using
1092 PR_SetTempString() or PR_CatStrings(). They will be freed when the
1093 current progs stack frame is cleared. Use PR_PushFrame() and PR_PopFrame()
1094 around the calls to PR_SetTempString() and PR_ExecuteProgram() when using
1095 strings as parameters to a progs function.
1096
1097 Mutable strings are dstrings (dstring_t) mapped into the VM address space.
1098 They can be created, altered, and destroyed at any time by the main
1099 program (or the progs code via an appropriate builtin function).
1100 */
1101 //@{
1102
1103 /** Initialize the string tables using the strings supplied by the progs.
1104 Called automatically during progs load.
1105 \param pr pointer to ::progs_t VM struct
1106 \return true for success, false for failure
1107 */
1108 int PR_LoadStrings (progs_t *pr);
1109
1110 /** Check the validity of a string index.
1111 \param pr pointer to ::progs_t VM struct
1112 \param num string index to be validated
1113 \return true if the index is valid, false otherwise
1114 */
1115 qboolean PR_StringValid (progs_t *pr, string_t num);
1116
1117 /** Convert a string index to a C string.
1118 \param pr pointer to ::progs_t VM struct
1119 \param num string index to be converted
1120 \return C pointer to the string.
1121 */
1122 const char *PR_GetString(progs_t *pr, string_t num);
1123
1124 /** Retrieve the dstring_t associated with a mutable string.
1125 \param pr pointer to ::progs_t VM struct
1126 \param num string index of the mutable string
1127 \return the dstring implementing the mutable string
1128 */
1129 struct dstring_s *PR_GetMutableString(progs_t *pr, string_t num);
1130
1131 /** Make a permanent progs string from the given C string. Will not create a
1132 duplicate permanent string (temporary and mutable strings are not checked).
1133 \param pr pointer to ::progs_t VM struct
1134 \param s C string to be made into a permanent progs string
1135 \return string index of the progs string
1136 */
1137 string_t PR_SetString(progs_t *pr, const char *s);
1138
1139 /** Make a temporary progs string that will survive across function returns.
1140 Will not duplicate a permanent string. If a new progs string is created,
1141 it will be freed after ::PR_RS_SLOTS calls to this function. ie, up to
1142 ::PR_RS_SLOTS return strings can exist at a time.
1143 \param pr pointer to ::progs_t VM struct
1144 \param s C string to be returned to the progs code
1145 \return string index of the progs string
1146 */
1147 string_t PR_SetReturnString(progs_t *pr, const char *s);
1148
1149 /** Make a temporary progs string that will be freed when the current progs
1150 stack frame is exited. Will not duplicate a permantent string.
1151 \param pr pointer to ::progs_t VM struct
1152 \param s C string
1153 \return string index of the progs string
1154 */
1155 string_t PR_SetTempString(progs_t *pr, const char *s);
1156
1157 /** Make a temporary progs string that is the concatenation of two C strings.
1158 \param pr pointer to ::progs_t VM struct
1159 \param a C string
1160 \param b C string
1161 \return string index of the progs string that represents the
1162 concatenation of strings a and b
1163 */
1164 string_t PR_CatStrings (progs_t *pr, const char *a, const char *b);
1165
1166 /** Convert a mutable string to a temporary string.
1167 \param pr pointer to ::progs_t VM struct
1168 \param str string index of the mutable string to be converted
1169 */
1170 void PR_MakeTempString(progs_t *pr, string_t str);
1171
1172 /** Create a new mutable string.
1173 \param pr pointer to ::progs_t VM struct
1174 \return string index of the newly created mutable string
1175 */
1176 string_t PR_NewMutableString (progs_t *pr);
1177
1178 /** Make a dynamic progs string from the given C string. Will not create a
1179 duplicate permanent string (temporary, dynamic and mutable strings are
1180 not checked).
1181 \param pr pointer to ::progs_t VM struct
1182 \param s C string to be made into a permanent progs string
1183 \return string index of the progs string
1184 */
1185 string_t PR_SetDynamicString (progs_t *pr, const char *s);
1186
1187 /** Clear all of the return string slots. Called at progs load.
1188 \param pr pointer to ::progs_t VM struct
1189 */
1190 void PR_ClearReturnStrings (progs_t *pr);
1191
1192 /** Destroy a mutable, dynamic or temporary string.
1193 \param pr pointer to ::progs_t VM struct
1194 \param str string index of the string to be destroyed
1195 */
1196 void PR_FreeString (progs_t *pr, string_t str);
1197
1198 /** Free all the temporary strings allocated in the current stack frame.
1199 \param pr pointer to ::progs_t VM struct
1200 */
1201 void PR_FreeTempStrings (progs_t *pr);
1202
1203 /** Formatted printing similar to C's vsprintf, but using QC types.
1204 The format string is a string of characters (other than \c \%) to be
1205 printed that includes optional format specifiers, one for each arg to be
1206 printed.
1207 A format specifier can be one of two forms:
1208 <ul>
1209 <li>\c "%%" print a single \c '\%'
1210 <li><tt>%[flags][field width][precision](conversion specifier)</tt> print a
1211 single arg of the type specified by the conversion specifier using
1212 the given format.
1213 </ul>
1214
1215 <ul>
1216 <li>flags (optional)
1217 <ul>
1218 <li>\c '#' print the value using an alternat form
1219 <li>\c '0' the value should be zero padded
1220 <li>\c '-' the value is to be left adjusted on the field bondary.
1221 <li><tt>' '</tt> A blank should be left before a positve number (or
1222 empty string) produced by a signed conversion.
1223 <li>\c '+' A sign (+ or -) will always be placed before a number
1224 produced by a signed conversion.
1225 </ul>
1226 <li>field width (optional)
1227 <ul>
1228 <li>a string of decimal digits with nonzero first digit.
1229 </ul>
1230 <li>precision (optional)
1231 <ul>
1232 <li>a string consisting of <tt>'.'</tt> followed by 0 or more decimal
1233 digits.
1234 </ul>
1235 <li>conversion specifier (mandatory)
1236 <ul>
1237 <li>\c '@' \c id Not yet implemented. Silently ignored.
1238 <li>\c 'e' \c entity Prints the edict number of the given entity ("%i")
1239 <li>\c 'i' \c integer Print a integer value. ("%i")
1240 <li>\c 'f' \c float Print a float value. ("%f")
1241 <li>\c 'g' \c float Print a float value. ("%f")
1242 <li>\c 'p' \c void * Print a pointer value. ("%#x")
1243 <li>\c 's' \c string Print a string value. ("%s")
1244 <li>\c 'v' \c vector Print a vector value. ("'%g %g %g'")
1245 <li>\c 'q' \c quaternion Print a quaternion value. ("'%g %g %g %g'")
1246 <li>\c 'x' \c uinteger Print an unsigned integer value. ("%x")
1247 </ul>
1248 </ul>
1249
1250 For details, refer to the C documentation for printf.
1251
1252 \param pr pointer to ::progs_t VM struct
1253 \param result dstring to which printing is done
1254 \param name name to be reported in case of errors
1255 \param format the format string
1256 \param count number of args
1257 \param args array of pointers to the values to be printed
1258 */
1259 void PR_Sprintf (progs_t *pr, struct dstring_s *result, const char *name,
1260 const char *format, int count, pr_type_t **args);
1261
1262 //@}
1263
1264 /** \defgroup pr_resources Resource Management
1265 \ingroup progs
1266 Builtin module private data management.
1267 */
1268 //@{
1269
1270 /** Initialize the resource management fields.
1271
1272 \param pr The VM of which the resource fields will be initialized.
1273 */
1274 void PR_Resources_Init (progs_t *pr);
1275
1276 /** Clear all resources before loading a new progs.
1277
1278 Calls the clear() callback of all registered resources.
1279
1280 \param pr The VM of which the resources will be cleared.
1281 */
1282 void PR_Resources_Clear (progs_t *pr);
1283
1284 /** Register a resource with a VM.
1285
1286 \param pr The VM to which the resource will be associated.
1287 \param name The name of the resource. Used for retrieving the
1288 resource.
1289 \param data The resource data.
1290 callback.
1291 \param clear Callback for performing any necessary cleanup. Called
1292 by PR_Resources_Clear(). The parameters are the current
1293 VM (\p pr) and \p data.
1294 \note The name should be unique to the VM, but no checking is
1295 done. If the name is not unique, the previous registered
1296 resource will break. The name of the sub-system
1297 registering the resource is a suitable name, and will
1298 probably be unique.
1299 */
1300 void PR_Resources_Register (progs_t *pr, const char *name, void *data,
1301 void (*clear)(progs_t *, void *));
1302
1303 /** Retrieve a resource registered with the VM.
1304
1305 \param pr The VM from which the resource will be retrieved.
1306 \param name The name of the resource.
1307 \return The resource, or NULL if \p name does not match any
1308 resource registered with the VM.
1309 */
1310 void *PR_Resources_Find (progs_t *pr, const char *name);
1311
1312 /** \name Resource Map support
1313
1314 These macros can be used to create functions for mapping C resources
1315 to QuakeC integer handles.
1316
1317 Valid handles are always negative.
1318
1319 \note \p map is the resource map itself, not a pointer to the
1320 resource map.
1321 */
1322 //@{
1323
1324 /** Type delcaration for the resource map.
1325
1326 \param type The type of the resource. The size must be at least
1327 as large as \c sizeof(type *).
1328 */
1329 #define PR_RESMAP(type) struct { type *_free; type **_map; unsigned _size; }
1330
1331 /** Allocate a new resource from the resource map.
1332
1333 \param type The type of the resource. Must match the \c type parameter
1334 used for PR_RESMAP.
1335 \param map The resource map.
1336 \return A pointer to the new resource, or null if no more could
1337 be allocated.
1338 */
1339 #define PR_RESNEW(type,map) \
1340 type *t; \
1341 \
1342 if (!map._free) { \
1343 int i, size; \
1344 map._size++; \
1345 size = map._size * sizeof (type *); \
1346 map._map = realloc (map._map, size); \
1347 if (!map._map) \
1348 return 0; \
1349 map._free = calloc (1024, sizeof (type)); \
1350 if (!map._free) \
1351 return 0; \
1352 map._map[map._size - 1] = map._free; \
1353 for (i = 0; i < 1023; i++) \
1354 *(type **) &map._free[i] = &map._free[i + 1]; \
1355 *(type **) &map._free[i] = 0; \
1356 } \
1357 t = map._free; \
1358 map._free = *(type **) t; \
1359 memset (t, 0, sizeof (type)); \
1360 return t
1361
1362 /** Free a resource returning it to the resource map.
1363
1364 \param type The type of the resource. Must match the \c type parameter
1365 used for PR_RESMAP.
1366 \param map The resource map.
1367 \param t Pointer to the resource to be freed.
1368 */
1369 #define PR_RESFREE(type,map,t) \
1370 memset (t, 0, sizeof (type)); \
1371 *(type **) t = map._free; \
1372 map._free = t
1373
1374 /** Free all resources in the resource map.
1375
1376 Any memory allocated to the resource must be freed before freeing the
1377 resource.
1378
1379 \param type The type of the resource. Must match the \c type parameter
1380 used for PR_RESMAP.
1381 \param map The resource map.
1382 */
1383 #define PR_RESRESET(type,map) \
1384 unsigned i, j; \
1385 if (!map._size) \
1386 return; \
1387 for (i = 0; i < map._size; i++) { \
1388 map._free = map._map[i]; \
1389 for (j = 0; j < 1023; j++) \
1390 *(type **) &map._free[j] = &map._free[j + 1]; \
1391 if (i < map._size - 1) \
1392 *(type **) &map._free[j] = &map._map[i + 1][0]; \
1393 } \
1394 map._free = map._map[0];
1395
1396 /** Retrieve a resource from the resource map using a handle.
1397
1398 \param map The resource map.
1399 \param col The handle.
1400 \return A pointer to the resource, or NULL if the handle is
1401 invalid.
1402 */
1403 #define PR_RESGET(map,col) \
1404 unsigned row = ~col / 1024; \
1405 col = ~col % 1024; \
1406 if (row >= map._size) \
1407 return 0; \
1408 return &map._map[row][col]
1409
1410 /** Convert a resource pointer to a handle.
1411
1412 \param map The resource map.
1413 \param ptr The resource pointer.
1414 \return The handle or 0 if the pointer is invalid.
1415 */
1416 #define PR_RESINDEX(map,ptr) \
1417 unsigned i; \
1418 for (i = 0; i < map._size; i++) { \
1419 long d = ptr - map._map[i]; \
1420 if (d >= 0 && d < 1024) \
1421 return ~(i * 1024 + d); \
1422 } \
1423 return 0
1424 //@}
1425
1426 //@}
1427
1428 /** \defgroup pr_zone VM memory management.
1429 \ingroup progs
1430
1431 Used to allocate and free memory in the VM address space.
1432 */
1433 //@{
1434
1435 void PR_Zone_Init (progs_t *pr);
1436 void PR_Zone_Free (progs_t *pr, void *ptr);
1437 void *PR_Zone_Malloc (progs_t *pr, pr_int_t size);
1438 void *PR_Zone_Realloc (progs_t *pr, void *ptr, pr_int_t size);
1439
1440 //@}
1441
1442 /** \defgroup debug VM Debugging
1443 \ingroup progs
1444 Progs debugging support.
1445 */
1446 //@{
1447
1448 void PR_Debug_Init (void);
1449 void PR_Debug_Init_Cvars (void);
1450 int PR_LoadDebug (progs_t *pr);
1451 void PR_Debug_Watch (progs_t *pr, const char *expr);
1452 void PR_Debug_Print (progs_t *pr, const char *expr);
1453 pr_auxfunction_t *PR_Get_Lineno_Func (progs_t *pr, pr_lineno_t *lineno);
1454 pr_uint_t PR_Get_Lineno_Addr (progs_t *pr, pr_lineno_t *lineno);
1455 pr_uint_t PR_Get_Lineno_Line (progs_t *pr, pr_lineno_t *lineno);
1456 pr_lineno_t *PR_Find_Lineno (progs_t *pr, pr_uint_t addr);
1457 const char *PR_Get_Source_File (progs_t *pr, pr_lineno_t *lineno);
1458 const char *PR_Get_Source_Line (progs_t *pr, pr_uint_t addr);
1459 ddef_t *PR_Get_Param_Def (progs_t *pr, dfunction_t *func, unsigned parm);
1460 ddef_t *PR_Get_Local_Def (progs_t *pr, pr_int_t offs);
1461 void PR_PrintStatement (progs_t *pr, dstatement_t *s, int contents);
1462 void PR_DumpState (progs_t *pr);
1463 void PR_StackTrace (progs_t *pr);
1464 void PR_Profile (progs_t *pr);
1465
1466 extern struct cvar_s *pr_debug;
1467 extern struct cvar_s *pr_deadbeef_ents;
1468 extern struct cvar_s *pr_deadbeef_locals;
1469 extern struct cvar_s *pr_boundscheck;
1470 extern struct cvar_s *pr_faultchecks;
1471
1472 //@}
1473
1474 /** \defgroup pr_cmds Quake and Quakeworld common builtins
1475 \ingroup progs
1476 \todo This really doesn't belong in progs.
1477 */
1478 //@{
1479
1480 char *PF_VarString (progs_t *pr, int first);
1481 void PR_Cmds_Init (progs_t *pr);
1482
1483 extern const char *pr_gametype;
1484
1485 //@}
1486
1487 //============================================================================
1488
1489 #define MAX_STACK_DEPTH 64
1490 #define LOCALSTACK_SIZE 4096
1491 #define PR_RS_SLOTS 16
1492
1493 typedef struct strref_s strref_t;
1494
1495 typedef struct {
1496 pr_int_t s; ///< Return statement.
1497 bfunction_t *f; ///< Calling function.
1498 strref_t *tstr; ///< Linked list of temporary strings.
1499 } prstack_t;
1500
1501 struct obj_list_s;
1502
1503 struct progs_s {
1504 int (*parse_field) (progs_t *pr, const char *key, const char *value);
1505
1506 int null_bad;
1507 int no_exec_limit;
1508
1509 void (*file_error) (progs_t *pr, const char *path);
1510 void *(*load_file) (progs_t *pr, const char *path);
1511 void *(*allocate_progs_mem) (progs_t *pr, int size);
1512 void (*free_progs_mem) (progs_t *pr, void *mem);
1513
1514 int (*resolve) (progs_t *pr);
1515
1516 const char *progs_name;
1517
1518 dprograms_t *progs;
1519 int progs_size;
1520 unsigned short crc;
1521 int denorm_found;
1522
1523 struct memzone_s *zone;
1524 int zone_size;
1525
1526 /// \name builtin functions
1527 //@{
1528 struct hashtab_s *builtin_hash;
1529 struct hashtab_s *builtin_num_hash;
1530 unsigned bi_next;
1531 unsigned (*bi_map) (progs_t *pr, unsigned binum);
1532 //@}
1533
1534 /// \name symbol management
1535 //@{
1536 struct hashtab_s *function_hash;
1537 struct hashtab_s *global_hash;
1538 struct hashtab_s *field_hash;
1539 //@}
1540
1541 /// \name load hooks
1542 //@{
1543 int num_load_funcs;
1544 int max_load_funcs;
1545 pr_load_func_t **load_funcs;
1546
1547 /// cleared each load
1548 //@{
1549 int num_load_finish_funcs;
1550 int max_load_finish_funcs;
1551 pr_load_func_t **load_finish_funcs;
1552 //@}
1553 //@}
1554
1555 /// \name string management
1556 //@{
1557 struct dstring_mem_s *ds_mem;
1558 strref_t *free_string_refs;
1559 strref_t *static_strings;
1560 strref_t **string_map;
1561 strref_t *return_strings[PR_RS_SLOTS];
1562 int rs_slot;
1563 unsigned dyn_str_size;
1564 struct hashtab_s *strref_hash;
1565 int num_strings;
1566 strref_t *pr_xtstr;
1567 //@}
1568
1569 /// \name memory map
1570 //@{
1571 dfunction_t *pr_functions;
1572 bfunction_t *function_table;
1573 char *pr_strings;
1574 int pr_stringsize;
1575 ddef_t *pr_globaldefs;
1576 ddef_t *pr_fielddefs;
1577 dstatement_t *pr_statements;
1578 pr_type_t *pr_globals;
1579 unsigned globals_size;
1580 //@}
1581
1582 /// \name parameter block
1583 //@{
1584 pr_type_t *pr_return;
1585 pr_type_t *pr_params[MAX_PARMS];
1586 pr_type_t *pr_real_params[MAX_PARMS];
1587 pr_type_t *pr_param_ptrs[2];
1588 pr_type_t *pr_saved_params;
1589 int pr_saved_argc;
1590 int pr_param_size; ///< covers both params and return
1591 //@}
1592
1593 /// \name edicts
1594 //@{
1595 edict_t **edicts;
1596 int max_edicts;
1597 int *num_edicts;
1598 int *reserved_edicts; ///< alloc will start at reserved_edicts+1
1599 void (*unlink) (edict_t *ent);
1600 void (*flush) (void);
1601 int (*prune_edict) (progs_t *pr, edict_t *ent);
1602 void (*free_edict) (progs_t *pr, edict_t *ent);
1603 int pr_edict_size; ///< in bytes
1604 int pr_edictareasize; ///< for bounds checking, starts at 0
1605 func_t edict_parse;
1606 //@}
1607
1608 /// \name execution state
1609 //@{
1610 int pr_argc;
1611
1612 qboolean pr_trace;
1613 int pr_trace_depth;
1614 bfunction_t *pr_xfunction;
1615 int pr_xstatement;
1616
1617 prstack_t pr_stack[MAX_STACK_DEPTH];
1618 int pr_depth;
1619
1620 int localstack[LOCALSTACK_SIZE];
1621 int localstack_used;
1622 //@}
1623
1624 /// \name resources
1625 //@{
1626 pr_resource_t *resources;
1627 struct hashtab_s *resource_hash;
1628 //@}
1629
1630 /// \name obj info
1631 //@{
1632 unsigned selector_index;
1633 unsigned selector_index_max;
1634 struct obj_list_s **selector_sels;
1635 string_t *selector_names;
1636 struct hashtab_s *selector_hash;
1637 struct hashtab_s *classes;
1638 struct hashtab_s *load_methods;
1639 struct obj_list_s *unresolved_classes;
1640 struct obj_list_s *unclaimed_categories;
1641 struct obj_list_s *unclaimed_proto_list;
1642 struct obj_list_s *module_list;
1643 struct obj_list_s *class_tree_list;
1644 //@}
1645
1646 /// \name debug info
1647 //@{
1648 const char *debugfile;
1649 struct pr_debug_header_s *debug;
1650 struct pr_auxfunction_s *auxfunctions;
1651 struct pr_auxfunction_s **auxfunction_map;
1652 struct pr_lineno_s *linenos;
1653 ddef_t *local_defs;
1654 pr_type_t *watch;
1655 int wp_conditional;
1656 pr_type_t wp_val;
1657 //@}
1658
1659 /// \name globals and fields needed by the VM
1660 //@{
1661 struct {
1662 float *time; ///< required for OP_STATE
1663 pr_int_t *self; ///< required for OP_STATE
1664 } globals;
1665 struct {
1666 pr_int_t nextthink; ///< required for OP_STATE
1667 pr_int_t frame; ///< required for OP_STATE
1668 pr_int_t think; ///< required for OP_STATE
1669 pr_int_t this; ///< optional for entity<->object linking
1670 } fields;
1671 //@}
1672 };
1673
1674 /** \addtogroup progs_data_access
1675 */
1676 //@{
1677
1678 /** Convert a progs offset/pointer to a C pointer.
1679 \param pr pointer to ::progs_t VM struct
1680 \param o offset into global data space
1681 \return C pointer represented by the parameter. 0 offset -> NULL
1682 */
1683 static inline pr_type_t *
PR_GetPointer(progs_t * pr,pointer_t o)1684 PR_GetPointer (progs_t *pr, pointer_t o)
1685 {
1686 return o ? pr->pr_globals + o : 0;
1687 }
1688
1689 /** Convert a C pointer to a progs offset/pointer.
1690 \param pr pointer to ::progs_t VM struct
1691 \param p C pointer to be converted.
1692 \return Progs offset/pointer represented by \c p. NULL -> 0 offset
1693 */
1694 static inline pointer_t
PR_SetPointer(progs_t * pr,void * p)1695 PR_SetPointer (progs_t *pr, void *p)
1696 {
1697 return p ? (pr_type_t *) p - pr->pr_globals : 0;
1698 }
1699
1700 //@}
1701
1702 /** \example vm-exec.c
1703 */
1704
1705 #endif//__QF_progs_h
1706