Clarify alternative ECP calling conventions
Function calls to alternative implementations have to follow certain
rules in order to preserve correct functionality. To avoid accidentally
breaking these rules we state them explicitly in the ECP module for
ourselves and every contributor to see.
diff --git a/library/ecp.c b/library/ecp.c
index e3b9106..d9a3ac2 100644
--- a/library/ecp.c
+++ b/library/ecp.c
@@ -47,6 +47,35 @@
#include MBEDTLS_CONFIG_FILE
#endif
+/**
+ * \brief Function level alternative implementation.
+ *
+ * The MBEDTLS_ECP_INTERNAL_ALT macro enables alternative implementations to
+ * replace certain functions in this module. The alternative implementations are
+ * typically hardware accelerators and need to activate the hardware before the
+ * computation starts and deactivate it after it finishes. The
+ * mbedtls_internal_ecp_init() and mbedtls_internal_ecp_free() functions serve
+ * this purpose.
+ *
+ * To preserve the correct functionality the following conditions must hold:
+ *
+ * - The alternative implementation must be activated by
+ * mbedtls_internal_ecp_init() before any of the replaceable functions is
+ * called.
+ * - mbedtls_internal_ecp_free() must \b only be called when the alternative
+ * implementation is activated.
+ * - mbedtls_internal_ecp_init() must \b not be called when the alternative
+ * implementation is activated.
+ * - Public functions must not return while the alternative implementation is
+ * activated.
+ * - Replaceable functions are guarded by \c MBEDTLS_ECP_XXX_ALT macros and
+ * before calling them an \code if( mbedtls_internal_ecp_grp_capable( grp ) )
+ * \endcode ensures that the alternative implementation supports the current
+ * group.
+ */
+#if defined(MBEDTLS_ECP_INTERNAL_ALT)
+#endif
+
#if defined(MBEDTLS_ECP_C)
#include "mbedtls/ecp.h"