diff doc/manual/manual_devel.tex @ 467:b47168dacba6

manual: - adding aggregate passing and returning info for x64 (win and sysv, however, *only* w/ respect to types supported by dyncall) - python binding text cleanup and sync with current binding version - added suite_aggrs description and cleaned up other test suite descriptions a bit - update list of calling convention modes - cleanup and minor other fixes (e.g. changed \newpage in many places to \clearpage to avoid hitting float limit, crlf->cr, ...)
author Tassilo Philipp
date Fri, 04 Feb 2022 23:54:42 +0100
parents 7ca46969e0ad
children 17287342e273
line wrap: on
line diff
--- a/doc/manual/manual_devel.tex	Wed Feb 02 18:30:44 2022 +0100
+++ b/doc/manual/manual_devel.tex	Fri Feb 04 23:54:42 2022 +0100
@@ -17,7 +17,7 @@
 %
 %//////////////////////////////////////////////////////////////////////////////
 
-\newpage
+\clearpage
 \section{Developers}
 
 \subsection{Noteworthy files in the project root}
@@ -45,34 +45,41 @@
 \begin{description}
 
 \item [plain] 
-Simple, identity, unary function calls for all supported return types and
-calling conventions.
+Simple, identity, mostly unary function calls for all supported return types
+and calling conventions. This is not an extensive test suite, but a good place
+to manually test certain cases.
 
 \item [plain\_c++] 
-Similar to plain, but for C++ thiscalls (GNU and MS calling convention).
+Similar to plain, but for C++ thiscalls (in different forms and fashion, with
+aggregates, vararg methots, on x86 with GNU and MS calling convention, etc.).
 
 \item [suite] 
 All combinations of parameter types and counts are tested on void function
-calls. A script written in Python ({\tt mkcase.py}) generates the tests up to
+calls. A Python script ({\tt mkcase.py}) generates the tests up to
 an upper MAXARG limit.
 
 \item [suite\_floats]
 Based on suite. Test double/float variants with up to 10 arguments.
 
+\item [suite\_aggrs]
+Tests passing and returning aggregates by value (struct/union and array members).
+Test cases can be designed in a signature-style format (and random ones generated
+via a Lua script).
+
 \item [suite\_x86win32std] 
 All combinations of parameter types and counts are tested on {\tt \_\_stdcall}
-void function calls. A script written in Python ({\tt mkcase.py}) generates
+void function calls. A Python script ({\tt mkcase.py}) generates
 the tests up to an upper MAXARG limit. This is a x86/Windows only test.
 
 \item [suite\_x86win32fast] 
 All combinations of parameter types and counts are tested on {\tt \_\_fastcall}
 (MS or GNU, depending on the build tool) void function calls.
-A script written in Python ({\tt mkcase.py}) generates the tests up to
+A Python script ({\tt mkcase.py}) generates the tests up to
 an upper MAXARG limit. This is a x86/Windows only test.
 
 \item [ellipsis]
 All combinations of parameter types and counts are tested on void ellipsis 
-function calls. A script written in Python ({\tt mkcase.py}) generates the 
+(vararg) function calls. A Python script ({\tt mkcase.py}) generates the 
 tests up to an upper MAXARG limit.
 
 \item [suite2]
@@ -99,17 +106,19 @@
 \item [call\_suite]
 General purpose test suite combining aspects from all others suites (usually enough for
 testing non-callback calls).
-A script written in Lua generates the tests.
+Test cases can be designed in a signature-style format (and random ones generated
+via a Lua script).
 
 \item [callf]
-Tests the \emph{formatted call} \product{dyncall} C API.
+Tests the \emph{formatted call/arg} \product{dyncall} C API. Tries to cover all uses of
+that API (e.g. calling convention mode switches, aggregates, ...) but is not extensive.
 
 \item [malloc\_wx]
 Tests \emph{writable and executable memory allocation} used by the
 \product{dyncallback} C API.
 
 \item [thunk]
-Tests \emph{callbacks} for the \product{dyncallback} C API.
+Tests only the \emph{callback} thunks for the \product{dyncallback} C API.
 
 \item [callback\_plain]
 Simple callback function test (useful for easy debugging of new ports).
@@ -117,8 +126,7 @@
 \item [callback\_suite]
 Mass test suite for callback function testing. Uses random function argument
 number and type.
-A script written in Lua generates the tests up to a given number of calls and
-type combinations.
+A Lua script the tests up to a given number of calls and type combinations.
 
 \item [resolv\_self]
 Test for dynload library to resolve symbols from application image itself.