changeset 508:1aa2af848e8a

- callback_suite: updated readme to reflect changes and general cleanup
author Tassilo Philipp
date Sat, 09 Apr 2022 14:44:33 +0200
parents 5a3c07a0f376
children f3d44195dbdf
files test/callback_suite/README.txt
diffstat 1 files changed, 19 insertions(+), 28 deletions(-) [+]
line wrap: on
line diff
--- a/test/callback_suite/README.txt	Sat Apr 09 14:00:59 2022 +0200
+++ b/test/callback_suite/README.txt	Sat Apr 09 14:44:33 2022 +0200
@@ -1,27 +1,19 @@
-Callback Test Suite 2 
+Callback Test Suite
-- dyncall
-- ANSI C compiler
-- lua (tested with 5.1)
-  edit config.lua and run "make config".
+  needs lua: edit config.lua and run "make config".
 Generates a set of callback invokers in C using lua as a preprocessor.
-The invokers put up an argument vector using a global Value-Matrix which
-holds a specific type-specific value pattern as a function of position.
-The Value-Matrix
-The value-matrix is a data structure consisting of n x m elements of
-type DCValueSet which can store distinct numbers for each type.
+The invokers pass arguments to the callback to test from a set of reference
+values which are argument type- and position-specific.
-It is used in the body of the auto-generated callback invokers (C code).
 The Callback Invocation Body
@@ -31,29 +23,28 @@
 void f19(void* addr) 
   Result.p = ((CONFIG_API p(*)(d,p,d,f))addr)(ValueMatrix[0].d,ValueMatrix[1].p,ValueMatrix[2].d,ValueMatrix[3].f);
-}              ^^^^^^^^^^- calling convention
+}              ^^^^^^^^^^- specific calling convention
                           ^^^^^^^^^^^^^- signature
          ^- return type signature
-                                                  ^- arg signature char 0 (later expected) value
+                                                  ^- arg signature char 0 value (to be retrieved in handler)
-Result (type DCValue)  and ValueMatrix (type DCValueSet[MAXARGS]) are globals. 
-The ValueMatrix is initialized once from main.c for all combinations of types
-and argument position.
-See globals.* files for details.
+Result (type DCValue) and ValueMatrix (type DCValueSet[MAXARGS], holding the
+reference values) are globals, as well as an Args (type DCValue) array, which
+is used by the callback handler to write the received argument values to.
 Reference argument and result value
-The value is generated by a pure function get_reference_arg and
-get_reference_result (file globals.c). They have formals position and type 
-and are pure without any side-effects (means the function value does only
-relay on the input arguments - if called with same arguments it will reveal
-the same value.
+The reference values are generated by get_reference_arg() and
+get_reference_result(), which always return the exact same value for the a
+given set of arguments.
+ValueMatrix was filled by those functions and thus holds a temporary copy,
+which is useful to test whether any input argument was modified (which should
+never be the case).
-It defined in globals.c.
-Tssting for exotic calling conventions on Windows:
+Testing for exotic calling conventions on Windows
 Specify 'api' and 'ccprefix' accordingly:
@@ -62,5 +53,5 @@
 "__fastcall" "_f" for gcc compiler
              "_F" for microsoft compiler
+See the dyncall documentation for other/more calling convention prefixes.