Add documentation for new bignum functions

Signed-off-by: Gabor Mezei <gabor.mezei@arm.com>

library/bignum_core.h

@@ -42,28 +42,97 @@
 #define BITS_TO_LIMBS(i)  ( (i) / biL + ( (i) % biL != 0 ) )
 #define CHARS_TO_LIMBS(i) ( (i) / ciL + ( (i) % ciL != 0 ) )
 
+/** Count leading zero bits in a given integer.
+ *
+ * \param x     Integer to count leading zero bits.
+ *
+ * \return      Tne munber of leading zero bits in \p x.
+ */
 size_t mbedtls_mpi_core_clz( const mbedtls_mpi_uint x );
 
+/** Return the number of bits of an MPI.
+ *
+ * \param X     The address of the MPI.
+ * \param nx    The number of limbs of \p X.
+ *
+ * \return      Tne number of bits in \p X.
+ */
 size_t mbedtls_mpi_core_bitlen( const mbedtls_mpi_uint *X, size_t nx );
 
+/** Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint
+ * into the storage form used by mbedtls_mpi.
+ *
+ * \param X     The address of the MPI.
+ * \param limbs The number of limbs of \p X.
+ */
 void mbedtls_mpi_core_bigendian_to_host( mbedtls_mpi_uint * const X,
                                          size_t limbs );
 
+/** Import X from unsigned binary data, little endian.
+ *
+ * This function is guaranteed to return an MPI with at least the necessary
+ * number of limbs (in particular, it does not skip 0s in the input).
+ *
+ * \param X      The address of the MPI.
+ * \param nx     The number of limbs of \p X.
+ * \param buf    The input buffer to import from.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't
+ *               large enough to hold the value in \p buf.
+ */
 int mbedtls_mpi_core_read_le( mbedtls_mpi_uint *X,
                               size_t nx,
                               const unsigned char *buf,
                               size_t buflen );
 
+/** Import X from unsigned binary data, big endian.
+ *
+ * This function is guaranteed to return an MPI with exactly the necessary
+ * number of limbs (in particular, it does not skip 0s in the input).
+ *
+ * \param X      The address of the MPI.
+ * \param nx     The number of limbs of \p X.
+ * \param buf    The input buffer to import from.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't
+ *               large enough to hold the value in \p buf.
+ */
 int mbedtls_mpi_core_read_be( mbedtls_mpi_uint *X,
                               size_t nx,
                               const unsigned char *buf,
                               size_t buflen );
 
+/** Export X into unsigned binary data, little endian.
+ *
+ * \param X      The address of the MPI.
+ * \param nx     The number of limbs of \p X.
+ * \param buf    The output buffer to import.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ *               large enough to hold the value of \p X.
+ */
 int mbedtls_mpi_core_write_le( const mbedtls_mpi_uint *X,
                                size_t nx,
                                unsigned char *buf,
                                size_t buflen );
 
+/** Export X into unsigned binary data, big endian.
+ *
+ * \param X      The address of the MPI.
+ * \param nx     The number of limbs of \p X.
+ * \param buf    The output buffer to import.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ *               large enough to hold the value of \p X.
+ */
 int mbedtls_mpi_core_write_be( const mbedtls_mpi_uint *X,
                                size_t nx,
                                unsigned char *buf,

library/bignum_mod.h

@@ -63,21 +63,57 @@ typedef enum
     MBEDTLS_MPI_MOD_EXT_REP_BE
 } mbedtls_mpi_mod_ext_rep;
 
-void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r );
 
+/** Setup a residue structure.
+ *
+ * \param r     The address of residue to setup. The size is determined by \p m.
+ * \param m     The address of a modulus related to \p r.
+ * \param p     The address of the MPI used for \p r.
+ * \param pn    The number of limbs of \p p.
+ *
+ * \return      \c 0 if successful.
+ * \return      #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p r, \p m or \p p is
+ *              #NULL pointer or if \p p is less then \p m.
+ */
 int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r,
                                    mbedtls_mpi_mod_modulus *m,
                                    mbedtls_mpi_uint *p,
                                    size_t pn );
 
+/** Unbind elements of a residue structure.
+ *
+ * \param r     The address of residue to release.
+ */
+void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r );
+
+/** Initialize a modulus structure.
+ *
+ * \param m     The address of a modulus.
+ */
 void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m );
 
-void mbedtls_mpi_mod_modulus_free( mbedtls_mpi_mod_modulus *m );
+/** Setup a residue structure.
-
+ *
+ * \param m         The address of a modulus.
+ * \param p         The address of the MPI used for \p m.
+ * \param pn        The number of limbs of \p p.
+ * \param ext_rep   The external representation of \p m (eg. byte order).
+ * \param int_rep   The selector which representation is used.
+ *
+ * \return      \c 0 if successful.
+ * \return      #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p m or \p p is
+ *              #NULL pointer or if \p ext_rep or \p int_rep is invalid.
+ */
 int mbedtls_mpi_mod_modulus_setup( mbedtls_mpi_mod_modulus *m,
                                    mbedtls_mpi_uint *p,
                                    size_t pn,
                                    int ext_rep,
                                    int int_rep );
 
+/** Unbind elements of a modulus structure.
+ *
+ * \param m     The address of a modulus.
+ */
+void mbedtls_mpi_mod_modulus_free( mbedtls_mpi_mod_modulus *m );
+
 #endif /* MBEDTLS_BIGNUM_MOD_H */

library/bignum_mod_raw.h

@@ -26,11 +26,40 @@
 #include "mbedtls/bignum.h"
 #endif
 
+/** Import X from unsigned binary data.
+ *
+ * This function is guaranteed to return an MPI with exactly the necessary
+ * number of limbs (in particular, it does not skip 0s in the input).
+ *
+ * \param X      The address of the MPI. The size is determined by \p m.
+ * \param m      The address of a modulus related to \p X.
+ * \param buf    The input buffer to import from.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't
+ *               large enough to hold the value in \p buf.
+ * \return       #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external reprezentation
+ *               of \p m is invalid or \p X is less then \p m.
+ */
 int mbedtls_mpi_mod_raw_read( mbedtls_mpi_uint *X,
                               mbedtls_mpi_mod_modulus *m,
                               unsigned char *buf,
                               size_t buflen );
 
+/** Export X into unsigned binary data.
+ *
+ * \param X      The address of the MPI. The size is determined by \p m.
+ * \param m      The address of a modulus related to \p X.
+ * \param buf    The output buffer to import.
+ * \param buflen Tne length in bytes of \p buf.
+ *
+ * \return       \c 0 if successful.
+ * \return       #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ *               large enough to hold the value of \p X.
+ * \return       #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external reprezentation
+ *               of \p m is invalid.
+ */
 int mbedtls_mpi_mod_raw_write( mbedtls_mpi_uint *X,
                                mbedtls_mpi_mod_modulus *m,
                                unsigned char *buf,

library/bignum_new.c

@@ -82,15 +82,6 @@ size_t mbedtls_mpi_core_bitlen( const mbedtls_mpi_uint *X, size_t nx )
 #define GET_BYTE( X, i )                                \
     ( ( ( X )[( i ) / ciL] >> ( ( ( i ) % ciL ) * 8 ) ) & 0xff )
 
-void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r )
-{
-    if ( r == NULL )
-        return;
-
-    r->n = 0;
-    r->p = NULL;
-}
-
 int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r,
                                    mbedtls_mpi_mod_modulus *m,
                                    mbedtls_mpi_uint *p,
@@ -108,6 +99,15 @@ int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r,
     return( 0 );
 }
 
+void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r )
+{
+    if ( r == NULL )
+        return;
+
+    r->n = 0;
+    r->p = NULL;
+}
+
 void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m )
 {
     if ( m == NULL )
@@ -206,7 +206,6 @@ static int mpi_core_clear( mbedtls_mpi_uint *X,
 
 /* Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint
  * into the storage form used by mbedtls_mpi. */
-
 static mbedtls_mpi_uint mpi_bigendian_to_host_c( mbedtls_mpi_uint x )
 {
     uint8_t i;