Describe generic conventions for the bignum core module

This commit codifies some conventions that result from the original design
goals and others that have emerged after starting the implementation.

* Value ranges
* Bignum parameter naming and ordering
* Sizes
* Aliasing and overlap
* Error handling

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

library/bignum_core.h

@@ -11,6 +11,51 @@
  * as the principal representation of a number modulo 2^#biL or a smaller
  * bound.
  *
+ * The functions in this module obey the following conventions unless
+ * explicitly indicated otherwise:
+ *
+ * - **Overflow**: some functions indicate overflow from the range
+ *   [0, 2^#biL-1] by returning carry parameters, while others operate
+ *   modulo and so cannot overflow. This should be clear from the function
+ *   documentation.
+ * - **Bignum parameters**: Bignums are passed as pointers to an array of
+ *   limbs. A limb has the type #mbedtls_mpi_uint. Unless otherwise specified:
+ *     - Bignum parameters called \p A, \p B, ... are inputs, and are
+ *       not modified by the function.
+ *     - For operations modulo some number, the modulus is called \p N
+ *       and is input-only.
+ *     - Bignum parameters called \p X, \p Y are outputs or input-output.
+ *       The initial content of output-only parameters is ignored.
+ *     - Some functions use different names that reflect traditional
+ *       naming of operands of certain operations (e.g.
+ *       divisor/dividend/quotient/remainder).
+ *     - \p T is a temporary storage area. The initial content of such
+ *       parameter is ignored and the final content is unspecified.
+ * - **Bignum sizes**: bignum sizes are always expressed in limbs.
+ *   Most functions work on bignums of a given size and take a single
+ *   \p limbs parameter that applies to all parameters that are limb arrays.
+ *   All bignum sizes must be at least 1 and must be significantly less than
+ *   #SIZE_MAX. The behavior if a size is 0 is undefined. The behavior if the
+ *   total size of all parameters overflows #SIZE_MAX is undefined.
+ * - **Parameter ordering**: for bignum parameters, outputs come before inputs.
+ *   Temporaries come last.
+ * - **Aliasing**: in general, output bignums may be aliased to one or more
+ *   inputs. As an exception, parameters that are documented as a modulus value
+ *   may not be aliased to an output. Temporaries may not be aliased to
+ *   any other parameter.
+ * - **Overlap**: apart from aliasing of limb array pointers (where two
+ *   arguments are equal pointers), overlap is not supported and may result
+ *   in undefined behavior.
+ * - **Error handling**: This is a low-level module. Functions generally do not
+ *   try to protect against invalid arguments such as nonsensical sizes or
+ *   null pointers. Note that some functions that operate on bignums of
+ *   different sizes have constraints about their size, and violating those
+ *   constraints may lead to buffer overflows.
+ * - **Modular representatives**: functions that operate modulo \p N expect
+ *   all modular inputs to be in the range [0, \p N - 1] and guarantee outputs
+ *   in the range [0, \p N - 1]. If an input is out of range, outputs are
+ *   fully unspecified, though bignum values out of range should not cause
+ *   buffer overflows (beware that this is not extensively tested).
  */
 
 /*
@@ -39,9 +84,9 @@
 #include "mbedtls/bignum.h"
 #endif
 
-#define ciL    ( sizeof(mbedtls_mpi_uint) )   /* chars in limb  */
-#define biL    ( ciL << 3 )                   /* bits  in limb  */
-#define biH    ( ciL << 2 )                   /* half limb size */
+#define ciL    ( sizeof(mbedtls_mpi_uint) )   /** chars in limb  */
+#define biL    ( ciL << 3 )                   /** bits  in limb  */
+#define biH    ( ciL << 2 )                   /** half limb size */
 
 /*
  * Convert between bits/chars and number of limbs