Add conventions for bignum mod and mod_raw
Signed-off-by: Werner Lewis <werner.lewis@arm.com>
diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h
index 698119e..56e5cbc 100644
--- a/library/bignum_mod_raw.h
+++ b/library/bignum_mod_raw.h
@@ -11,6 +11,49 @@
* the wrong size. The functions in bignum_mod.h provide a higher-level
* interface that includes protections against accidental misuse, at the
* expense of code size and sometimes more cumbersome memory management.
+ *
+ * The functions in this module obey the following conventions unless
+ * explicitly indicated otherwise:
+ * - **Modulus parameters**: the modulus is passed as a pointer to a structure
+ * of type #mbedtls_mpi_mod_modulus. The structure must be setup with an
+ * array of limbs storing the bignum value of the modulus. Unless otherwise
+ * specified, the modulus is called \p N and is input-only.
+ * - **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.
+ * - Bignum parameters called \p X, \p Y are outputs or input-output.
+ * The initial content of output-only parameters is ignored.
+ * - \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 by the \p limbs
+ * member of the modulus argument. Any bignum parameters must have the same
+ * number of limbs as the modulus. 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.
+ * - **Bignum representation**: the representation of inputs and outputs is
+ * specified by the \p int_rep field of the modulus for arithmetic
+ * functions. Utility functions may allow for different representation.
+ * - **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. Modulus values may not be aliased to any other parameter. Outputs
+ * may not be aliased to one another. 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 passing bignums with a different size than the
+ * modulus may lead to buffer overflows. Some functions which allocate
+ * memory or handle reading/writing of bignums will return an error if
+ * memory allocation fails or if buffer sizes are invalid.
+ * - **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).
*/
/*