Addition of rudimentary error tracing

.github/workflows/main.yml

@@ -134,6 +134,10 @@ jobs:
           # clang for the x86-64 architecture with restricted limb sizes
           - { BUILDOPTIONS: '--with-cc=clang --cflags=-DMP_16BIT --limit-valgrind',                                              SANITIZER: '1', COMPILE_DEBUG: '0', COMPILE_LTO: '0', CONV_WARNINGS: '',        OTHERDEPS: 'clang llvm' }
           - { BUILDOPTIONS: '--with-cc=clang --cflags=-DMP_32BIT --limit-valgrind',                                              SANITIZER: '1', COMPILE_DEBUG: '0', COMPILE_LTO: '0', CONV_WARNINGS: '',        OTHERDEPS: 'clang llvm' }
+
+          # Check error-tracing with 64 bit only, macros are independent of limb-size with the exception of the S_MP_WORD_TOO_SMALL_C branch
+          - { BUILDOPTIONS: '--with-cc=gcc --with-m64 --cflags=-DMP_ADD_ERROR_TRACING --limit-valgrind',                             SANITIZER: '1', COMPILE_DEBUG: '0', COMPILE_LTO: '0', CONV_WARNINGS: '',        OTHERDEPS: '' }
+          - { BUILDOPTIONS: '--with-cc=gcc --with-m64 --cflags=-DMP_ADD_ERROR_TRACING --cflags=-DS_MP_WORD_TOO_SMALL_C="" --limit-valgrind',  SANITIZER: '1', COMPILE_DEBUG: '0', COMPILE_LTO: '0', CONV_WARNINGS: '',        OTHERDEPS: '' }
     steps:
       - uses: actions/checkout@v3
       - name: install dependencies

CMakeLists.txt

@@ -32,6 +32,7 @@ include(sources.cmake)
 # Options
 #-----------------------------------------------------------------------------
 option(BUILD_SHARED_LIBS "Build shared library and only the shared library if \"ON\", default is static" OFF)
+option(ADD_ERROR_TRACING "Add some simple macros that allow for a primitive but useful error tracing if \"ON\", default is \"OFF\"" OFF)
 
 #-----------------------------------------------------------------------------
 # Compose CFLAGS
@@ -76,6 +77,10 @@ if(CMAKE_SYSTEM_NAME MATCHES "CYGWIN")
     list(APPEND LTM_C_FLAGS -no-undefined)
 endif()
 
+if(ADD_ERROR_TRACING)
+    list(APPEND LTM_C_FLAGS -DMP_ADD_ERROR_TRACING)
+endif()
+
 # TODO: coverage (lgcov)
 
 # If the user set the environment variables at generate-time, append them

doc/bn.tex

@@ -362,6 +362,24 @@ \subsection{Small-Stack option}
 
 C.f. \ref{ch:SMALL_STACK_API} for the API description and further details.
 
+\subsection{Error tracing}
+\label{ch:ERROR_TRACING}
+One error leads to another error and it might be a bit tedious to trace all of the errors up to the
+source, especially in deeply recursive functions. The macro \texttt{MP\_TRACE\_ERROR} defined in 
+\texttt{tommath\_private.h} tries to help with it by printing the name of the source file, the line number,
+and the name of the function to \texttt{stderr}.
+
+Include this functionality by defining \texttt{MP\_ADD\_ERROR\_TRACING} with \texttt{make} or \texttt{cmake}.
+
+\index{MP\_TRACE\_ERROR}
+\begin{alltt}
+make "LCFLAGS= -DMP_ADD_ERROR_TRACING "
+or
+cmake -DMP_ADD_ERROR_TRACING=ON .
+\end{alltt}
+
+
+
 \section{Purpose of LibTomMath}
 Unlike	GNU MP (GMP) Library, LIP, OpenSSL or various other commercial kits (Miracl), LibTomMath
 was not written with bleeding edge performance in mind.  First and foremost LibTomMath was written

mp_2expt.c

@@ -10,26 +10,26 @@
  */
 mp_err mp_2expt(mp_int *a, int b)
 {
-   mp_err    err;
+   mp_err err = MP_OKAY;
 
    if (b < 0) {
-      return MP_VAL;
+      err = MP_VAL;
+      MP_TRACE_ERROR(err, LTM_ERR);
    }
 
    /* zero a as per default */
    mp_zero(a);
 
    /* grow a to accommodate the single bit */
-   if ((err = mp_grow(a, (b / MP_DIGIT_BIT) + 1)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_grow(a, (b / MP_DIGIT_BIT) + 1)) != MP_OKAY)            MP_TRACE_ERROR(err, LTM_ERR);
 
    /* set the used count of where the bit will go */
    a->used = (b / MP_DIGIT_BIT) + 1;
 
    /* put the single bit in its place */
    a->dp[b / MP_DIGIT_BIT] = (mp_digit)1 << (mp_digit)(b % MP_DIGIT_BIT);
 
-   return MP_OKAY;
+LTM_ERR:
+   return err;
 }
 #endif

mp_abs.c

@@ -9,16 +9,15 @@
  */
 mp_err mp_abs(const mp_int *a, mp_int *b)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
 
    /* copy a to b */
-   if ((err = mp_copy(a, b)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_copy(a, b)) != MP_OKAY)                       MP_TRACE_ERROR(err, LTM_ERR);
 
    /* force the sign of b to positive */
    b->sign = MP_ZPOS;
 
-   return MP_OKAY;
+LTM_ERR:
+   return err;
 }
 #endif

mp_add.c

@@ -6,12 +6,14 @@
 /* high level addition (handles signs) */
 mp_err mp_add(const mp_int *a, const mp_int *b, mp_int *c)
 {
+   mp_err err = MP_OKAY;
    /* handle two cases, not four */
    if (a->sign == b->sign) {
       /* both positive or both negative */
       /* add their magnitudes, copy the sign */
       c->sign = a->sign;
-      return s_mp_add(a, b, c);
+      if ((err = s_mp_add(a, b, c)) != MP_OKAY)                         MP_TRACE_ERROR(err, LTM_ERR);
+      return err;
    }
 
    /* one positive, the other negative */
@@ -23,7 +25,10 @@ mp_err mp_add(const mp_int *a, const mp_int *b, mp_int *c)
    }
 
    c->sign = a->sign;
-   return s_mp_sub(a, b, c);
+   if ((err = s_mp_sub(a, b, c)) != MP_OKAY)                            MP_TRACE_ERROR(err, LTM_ERR);
+
+LTM_ERR:
+   return err;
 }
 
 #endif

mp_add_d.c

@@ -6,7 +6,7 @@
 /* single digit addition */
 mp_err mp_add_d(const mp_int *a, mp_digit b, mp_int *c)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
    int oldused;
 
    /* fast path for a == c */
@@ -25,9 +25,7 @@ mp_err mp_add_d(const mp_int *a, mp_digit b, mp_int *c)
    }
 
    /* grow c as required */
-   if ((err = mp_grow(c, a->used + 1)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_grow(c, a->used + 1)) != MP_OKAY)                       MP_TRACE_ERROR(err, LTM_ERR);
 
    /* if a is negative and |a| >= b, call c = |a| - b */
    if (mp_isneg(a) && ((a->used > 1) || (a->dp[0] >= b))) {
@@ -36,7 +34,7 @@ mp_err mp_add_d(const mp_int *a, mp_digit b, mp_int *c)
       a_.sign = MP_ZPOS;
 
       /* c = |a| - b */
-      err = mp_sub_d(&a_, b, c);
+      if ((err = mp_sub_d(&a_, b, c)) != MP_OKAY)                       MP_TRACE_ERROR(err, LTM_ERR);
 
       /* fix sign  */
       c->sign = MP_NEG;
@@ -80,7 +78,8 @@ mp_err mp_add_d(const mp_int *a, mp_digit b, mp_int *c)
    s_mp_zero_digs(c->dp + c->used, oldused - c->used);
    mp_clamp(c);
 
-   return MP_OKAY;
+LTM_ERR:
+   return err;
 }
 
 #endif

mp_addmod.c

@@ -6,10 +6,11 @@
 /* d = a + b (mod c) */
 mp_err mp_addmod(const mp_int *a, const mp_int *b, const mp_int *c, mp_int *d)
 {
-   mp_err err;
-   if ((err = mp_add(a, b, d)) != MP_OKAY) {
-      return err;
-   }
-   return mp_mod(d, c, d);
+   mp_err err = MP_OKAY;
+   if ((err = mp_add(a, b, d)) != MP_OKAY)                               MP_TRACE_ERROR(err, LTM_ERR);
+   if ((err = mp_mod(d, c, d)) != MP_OKAY)                              MP_TRACE_ERROR(err, LTM_ERR);
+
+LTM_ERR:
+   return err;
 }
 #endif

mp_and.c

@@ -7,13 +7,11 @@
 mp_err mp_and(const mp_int *a, const mp_int *b, mp_int *c)
 {
    int used = MP_MAX(a->used, b->used) + 1, i;
-   mp_err err;
+   mp_err err = MP_OKAY;
    mp_digit ac = 1, bc = 1, cc = 1;
    bool neg = (mp_isneg(a) && mp_isneg(b));
 
-   if ((err = mp_grow(c, used)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_grow(c, used)) != MP_OKAY)                              MP_TRACE_ERROR(err, LTM_ERR);
 
    for (i = 0; i < used; i++) {
       mp_digit x, y;
@@ -49,6 +47,8 @@ mp_err mp_and(const mp_int *a, const mp_int *b, mp_int *c)
    c->used = used;
    c->sign = (neg ? MP_NEG : MP_ZPOS);
    mp_clamp(c);
-   return MP_OKAY;
+
+LTM_ERR:
+   return err;
 }
 #endif

mp_complement.c

@@ -6,8 +6,11 @@
 /* b = ~a */
 mp_err mp_complement(const mp_int *a, mp_int *b)
 {
+   mp_err err = MP_OKAY;
    mp_int a_ = *a;
    a_.sign = ((a_.sign == MP_ZPOS) && !mp_iszero(a)) ? MP_NEG : MP_ZPOS;
-   return mp_sub_d(&a_, 1uL, b);
+   if ((err = mp_sub_d(&a_, 1uL, b)) != MP_OKAY)                        MP_TRACE_ERROR(err, LTM_ERR);
+LTM_ERR:
+   return err;
 }
 #endif

mp_copy.c

@@ -6,24 +6,23 @@
 /* copy, b = a */
 mp_err mp_copy(const mp_int *a, mp_int *b)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
 
    /* if dst == src do nothing */
    if (a == b) {
-      return MP_OKAY;
+      return err;
    }
 
    /* grow dest */
-   if ((err = mp_grow(b, a->used)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_grow(b, a->used)) != MP_OKAY)                           MP_TRACE_ERROR(err, LTM_ERR);
 
    /* copy everything over and zero high digits */
    s_mp_copy_digs(b->dp, a->dp, a->used);
    s_mp_zero_digs(b->dp + a->used, b->used - a->used);
    b->used = a->used;
    b->sign = a->sign;
 
-   return MP_OKAY;
+LTM_ERR:
+   return err;
 }
 #endif

mp_div.c

@@ -5,19 +5,18 @@
 
 mp_err mp_div(const mp_int *a, const mp_int *b, mp_int *c, mp_int *d)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
 
    /* is divisor zero ? */
    if (mp_iszero(b)) {
-      return MP_VAL;
+      err = MP_VAL;
+      MP_TRACE_ERROR(err, LTM_ERR);
    }
 
    /* if a < b then q = 0, r = a */
    if (mp_cmp_mag(a, b) == MP_LT) {
       if (d != NULL) {
-         if ((err = mp_copy(a, d)) != MP_OKAY) {
-            return err;
-         }
+         if ((err = mp_copy(a, d)) != MP_OKAY)                           MP_TRACE_ERROR(err, LTM_ERR);
       }
       if (c != NULL) {
          mp_zero(c);
@@ -28,15 +27,17 @@ mp_err mp_div(const mp_int *a, const mp_int *b, mp_int *c, mp_int *d)
    if (MP_HAS(S_MP_DIV_RECURSIVE)
        && (b->used > (2 * MP_MUL_KARATSUBA_CUTOFF))
        && (b->used <= ((a->used/3)*2))) {
-      err = s_mp_div_recursive(a, b, c, d);
+      if ((err = s_mp_div_recursive(a, b, c, d)) != MP_OKAY)            MP_TRACE_ERROR(err, LTM_ERR);
    } else if (MP_HAS(S_MP_DIV_SCHOOL)) {
-      err = s_mp_div_school(a, b, c, d);
+      if ((err = s_mp_div_school(a, b, c, d)) != MP_OKAY)               MP_TRACE_ERROR(err, LTM_ERR);
    } else if (MP_HAS(S_MP_DIV_SMALL)) {
-      err = s_mp_div_small(a, b, c, d);
+      if ((err = s_mp_div_small(a, b, c, d)) != MP_OKAY)                MP_TRACE_ERROR(err, LTM_ERR);
    } else {
       err = MP_VAL;
+      MP_TRACE_ERROR(err, LTM_ERR);
    }
 
+LTM_ERR:
    return err;
 }
 #endif

mp_div_2.c

@@ -6,13 +6,11 @@
 /* b = a/2 */
 mp_err mp_div_2(const mp_int *a, mp_int *b)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
    int x, oldused;
    mp_digit r;
 
-   if ((err = mp_grow(b, a->used)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_grow(b, a->used)) != MP_OKAY)                           MP_TRACE_ERROR(err, LTM_ERR);
 
    oldused = b->used;
    b->used = a->used;
@@ -35,6 +33,8 @@ mp_err mp_div_2(const mp_int *a, mp_int *b)
 
    b->sign = a->sign;
    mp_clamp(b);
-   return MP_OKAY;
+
+LTM_ERR:
+   return err;
 }
 #endif

mp_div_2d.c

@@ -6,23 +6,20 @@
 /* shift right by a certain bit count (store quotient in c, optional remainder in d) */
 mp_err mp_div_2d(const mp_int *a, int b, mp_int *c, mp_int *d)
 {
-   mp_err err;
+   mp_err err = MP_OKAY;
 
    if (b < 0) {
-      return MP_VAL;
+      err =  MP_VAL;
+      MP_TRACE_ERROR(err, LTM_ERR);
    }
 
-   if ((err = mp_copy(a, c)) != MP_OKAY) {
-      return err;
-   }
+   if ((err = mp_copy(a, c)) != MP_OKAY)                                 MP_TRACE_ERROR(err, LTM_ERR);
 
    /* 'a' should not be used after here - it might be the same as d */
 
    /* get the remainder */
    if (d != NULL) {
-      if ((err = mp_mod_2d(a, b, d)) != MP_OKAY) {
-         return err;
-      }
+      if ((err = mp_mod_2d(a, b, d)) != MP_OKAY)                         MP_TRACE_ERROR(err, LTM_ERR);
    }
 
    /* shift by as many digits in the bit count */
@@ -56,6 +53,8 @@ mp_err mp_div_2d(const mp_int *a, int b, mp_int *c, mp_int *d)
       }
    }
    mp_clamp(c);
-   return MP_OKAY;
+
+LTM_ERR:
+   return err;
 }
 #endif