# HG changeset patch
# User Tassilo Philipp
# Date 1649508273 -7200
# Node ID 1aa2af848e8a805c459f738ef43355229d17a673
# Parent  5a3c07a0f376ee85ba1c42099a5044afce884aec
- callback_suite: updated readme to reflect changes and general cleanup

diff -r 5a3c07a0f376 -r 1aa2af848e8a test/callback_suite/README.txt
--- 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
+-------------------
 
-REQUIREMENTS
-- dyncall
-- ANSI C compiler
-- lua (tested with 5.1)
 
 CONFIGURE SUITE
 
-  edit config.lua and run "make config".
+  needs lua: edit config.lua and run "make config".
+
 
 DESCRIPTION
 
 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.
 
-