Merge pull request #4259 from dgarske/cleanups

Cleanups for memory docs and Arduino

IDE/ARDUINO/README.md

@@ -17,8 +17,8 @@ Step 2: Copy the directory wolfSSL that was just created to:
 
 Step 3: Edit `<arduino-libraries>/wolfSSL/user_settings.h`
 If building for Intel Galileo platform add: `#define INTEL_GALILEO`.
-Add any other custom settings, for a good start see the below in wolfssl root.
+Add any other custom settings, for a good start see the examples in wolfssl root
-(See wolfssl/IDE/ROWLEY-CROSSWORKS-ARM/user_settings.h)
+"/examples/configs/user_settings_*.h"
 
 Step 4: If you experience any issues with custom user_settings.h see the wolfssl
 porting guide here for more assistance: https://www.wolfssl.com/docs/porting-guide/

IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino

@@ -24,8 +24,8 @@
 #include <wolfssl/ssl.h>
 #include <Ethernet.h>
 
-const char host[] = "192.168.1.148"; // server to connect to
+const char host[] = "192.168.1.148"; /* server to connect to */
-const int port = 11111; // port on server to connect to
+const int port = 11111; /* port on server to connect to */
 
 int EthernetSend(WOLFSSL* ssl, char* msg, int sz, void* ctx);
 int EthernetReceive(WOLFSSL* ssl, char* reply, int sz, void* ctx);
@@ -51,7 +51,7 @@ void setup() {
     Serial.println("unable to get ctx");
     return;
   }
-  // initialize wolfSSL using callback functions
+  /* initialize wolfSSL using callback functions */
   wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);
   wolfSSL_SetIOSend(ctx, EthernetSend);
   wolfSSL_SetIORecv(ctx, EthernetReceive);
@@ -119,7 +119,10 @@ void loop() {
       if ((wolfSSL_write(ssl, msg, msgSz)) == msgSz) {
         
         Serial.print("Server response: ");
-        while (client.available() || wolfSSL_pending(ssl)) {
+        /* wait for data */
+        while (!client.available()) {}
+        /* read data */
+        while (wolfSSL_pending(ssl)) {
           input = wolfSSL_read(ssl, reply, sizeof(reply) - 1);
           total_input += input;
           if (input < 0) {

IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino

@@ -31,7 +31,7 @@
   #error Please undefine NO_WOLFSSL_SERVER for this example
 #endif
 
-const int port = 11111; // port to listen on
+const int port = 11111; /* port to listen on */
 
 int EthernetSend(WOLFSSL* ssl, char* msg, int sz, void* ctx);
 int EthernetReceive(WOLFSSL* ssl, char* reply, int sz, void* ctx);
@@ -59,12 +59,12 @@ void setup() {
     return;
   }
 
-  // initialize wolfSSL using callback functions
+  /* initialize wolfSSL using callback functions */
   wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);
   wolfSSL_SetIOSend(ctx, EthernetSend);
   wolfSSL_SetIORecv(ctx, EthernetReceive);
 
-  // setup the private key and certificate
+  /* setup the private key and certificate */
   err = wolfSSL_CTX_use_PrivateKey_buffer(ctx, ecc_key_der_256, 
     sizeof_ecc_key_der_256, WOLFSSL_FILETYPE_ASN1);
   if (err != WOLFSSL_SUCCESS) {
@@ -78,7 +78,7 @@ void setup() {
     return;
   }
 
-  // Start the server
+  /* Start the server */
   server.begin();
   
   return;
@@ -110,7 +110,7 @@ void loop() {
   int replySz = 0;
   const char* cipherName;
 
-  // Listen for incoming client requests.
+  /* Listen for incoming client requests. */
   client = server.available();
   if (!client) {
     return;
@@ -142,7 +142,10 @@ void loop() {
     Serial.println(cipherName);
 
     Serial.print("Server Read: ");
-    while (client.available() || wolfSSL_pending(ssl)) {
+    /* wait for data */
+    while (!client.available()) {}
+    /* read data */
+    while (wolfSSL_pending(ssl)) {
       input = wolfSSL_read(ssl, reply, sizeof(reply) - 1);
       if (input < 0) {
         err = wolfSSL_get_error(ssl, 0);
@@ -159,7 +162,7 @@ void loop() {
       }
     }
 
-    // echo data
+    /* echo data */
     if ((wolfSSL_write(ssl, reply, replySz)) != replySz) {
       err = wolfSSL_get_error(ssl, 0);
       wolfSSL_ERR_error_string(err, errBuf);

IDE/ARDUINO/wolfssl-arduino.sh

@@ -11,20 +11,29 @@ space(){
 }
 
 if [ "$DIR" = "ARDUINO" ]; then
-	rm -rf wolfSSL
+	if [ ! -d "wolfSSL" ]; then
-	mkdir wolfSSL
+	    mkdir wolfSSL
+    fi
 
     cp ../../src/*.c ./wolfSSL
     cp ../../wolfcrypt/src/*.c ./wolfSSL
 
-    mkdir wolfSSL/wolfssl
+    if [ ! -d "wolfSSL/wolfssl" ]; then
+	    mkdir wolfSSL/wolfssl
+    fi
     cp ../../wolfssl/*.h ./wolfSSL/wolfssl
-    mkdir wolfSSL/wolfssl/wolfcrypt
+    if [ ! -d "wolfSSL/wolfssl/wolfcrypt" ]; then
+        mkdir wolfSSL/wolfssl/wolfcrypt
+    fi
     cp ../../wolfssl/wolfcrypt/*.h ./wolfSSL/wolfssl/wolfcrypt
 
     # support misc.c as include in wolfcrypt/src
-    mkdir ./wolfSSL/wolfcrypt
+    if [ ! -d "./wolfSSL/wolfcrypt" ]; then
-    mkdir ./wolfSSL/wolfcrypt/src
+        mkdir ./wolfSSL/wolfcrypt
+    fi
+    if [ ! -d "./wolfSSL/wolfcrypt/src" ]; then
+        mkdir ./wolfSSL/wolfcrypt/src
+    fi
     cp ../../wolfcrypt/src/misc.c ./wolfSSL/wolfcrypt/src
     cp ../../wolfcrypt/src/asm.c  ./wolfSSL/wolfcrypt/src
 
@@ -37,31 +46,36 @@ if [ "$DIR" = "ARDUINO" ]; then
     cp ./wolfSSL/wolfssl/bio.c ./wolfSSL/wolfcrypt/src/bio.c
     
     # copy openssl compatibility headers to their appropriate location
-    mkdir ./wolfSSL/wolfssl/openssl
+    if [ ! -d "./wolfSSL/wolfssl/openssl" ]; then
+        mkdir ./wolfSSL/wolfssl/openssl
+    fi
     cp ../../wolfssl/openssl/* ./wolfSSL/wolfssl/openssl
 
     echo "/* Generated wolfSSL header file for Arduino */" > ./wolfSSL/wolfssl.h
+    echo "#include <user_settings.h>" >> ./wolfSSL/wolfssl.h
     echo "#include <wolfssl/wolfcrypt/settings.h>" >> ./wolfSSL/wolfssl.h
     echo "#include <wolfssl/ssl.h>" >> ./wolfSSL/wolfssl.h
 
-    echo "/* Generated wolfSSL user_settings.h file for Arduino */" > ./wolfSSL/user_settings.h
+    if [ ! -f "./wolfSSL/user_settings.h" ]; then
-    echo "#ifndef ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h
+        echo "/* Generated wolfSSL user_settings.h file for Arduino */" > ./wolfSSL/user_settings.h
-    echo "#define ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h
+        echo "#ifndef ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h
-    space wolfSSL/user_settings.h
+        echo "#define ARDUINO_USER_SETTINGS_H" >> ./wolfSSL/user_settings.h
-    echo "/* Platform */" >> ./wolfSSL/user_settings.h
+        space ./wolfSSL/user_settings.h
-    echo "#define WOLFSSL_ARDUINO" >> ./wolfSSL/user_settings.h
+        echo "/* Platform */" >> ./wolfSSL/user_settings.h
-    space wolfSSL/user_settings.h
+        echo "#define WOLFSSL_ARDUINO" >> ./wolfSSL/user_settings.h
-    echo "/* Math library (remove this to use normal math)*/" >>  ./wolfSSL/user_settings.h
+        space ./wolfSSL/user_settings.h
-    echo "#define USE_FAST_MATH" >> ./wolfSSL/user_settings.h
+        echo "/* Math library (remove this to use normal math)*/" >>  ./wolfSSL/user_settings.h
-    echo "#define TFM_NO_ASM" >> ./wolfSSL/user_settings.h
+        echo "#define USE_FAST_MATH" >> ./wolfSSL/user_settings.h
-    space wolfSSL/user_settings.h
+        echo "#define TFM_NO_ASM" >> ./wolfSSL/user_settings.h
-    echo "/* RNG DEFAULT !!FOR TESTING ONLY!! */" >>  ./wolfSSL/user_settings.h
+        space ./wolfSSL/user_settings.h
-    echo "/* comment out the error below to get started w/ bad entropy source" >>  ./wolfSSL/user_settings.h
+        echo "/* RNG DEFAULT !!FOR TESTING ONLY!! */" >>  ./wolfSSL/user_settings.h
-    echo " * This will need fixed before distribution but is OK to test with */" >>  ./wolfSSL/user_settings.h
+        echo "/* comment out the error below to get started w/ bad entropy source" >>  ./wolfSSL/user_settings.h
-    echo "#error \"needs solved, see: https://www.wolfssl.com/docs/porting-guide/\"" >>  ./wolfSSL/user_settings.h
+        echo " * This will need fixed before distribution but is OK to test with */" >>  ./wolfSSL/user_settings.h
-    echo "#define WOLFSSL_GENSEED_FORTEST" >> ./wolfSSL/user_settings.h
+        echo "#error \"needs solved, see: https://www.wolfssl.com/docs/porting-guide/\"" >>  ./wolfSSL/user_settings.h
-    space wolfSSL/user_settings.h
+        echo "#define WOLFSSL_GENSEED_FORTEST" >> ./wolfSSL/user_settings.h
-    echo "#endif /* ARDUINO_USER_SETTINGS_H */" >> ./wolfSSL/user_settings.h
+        space ./wolfSSL/user_settings.h
+        echo "#endif /* ARDUINO_USER_SETTINGS_H */" >> ./wolfSSL/user_settings.h
+    fi
 
     cp wolfSSL/wolfssl/wolfcrypt/settings.h wolfSSL/wolfssl/wolfcrypt/settings.h.bak
     echo " /* wolfSSL Generated ARDUINO settings */" > ./wolfSSL/wolfssl/wolfcrypt/settings.h

doc/dox_comments/header_files/memory.h

@@ -1,17 +1,21 @@
 /*!
     \ingroup Memory
 
-    \brief This function calls the custom malloc function, if one has been
+    \brief This function is similar to malloc(), but calls the memory
-    defined, or simply calls the default C malloc function if no custom
+    allocation function which wolfSSL has been configured to use. By default,
-    function exists. It is not called directly by wolfSSL, but instead
+    wolfSSL uses malloc().  This can be changed using the wolfSSL memory
-    generally called by using XMALLOC, which may be replaced by
+    abstraction layer - see wolfSSL_SetAllocators(). Note wolfSSL_Malloc is not 
-    wolfSSL_Malloc during preprocessing.
+    called directly by wolfSSL, but instead called by macro XMALLOC.
+    For the default build only the size argument exists. If using 
+    WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
 
-    \return Success On successfully allocating the desired memory,
+    \return pointer If successful, this function returns a pointer to
-    returns a void* to that location
+    allocated memory.
-    \return NULL Returned when there is a failure to allocate memory
+    \return error If there is an error, NULL will be returned.
 
     \param size size, in bytes, of the memory to allocate
+    \param heap heap hint to use for memory. Can be NULL
+    \param type dynamic type (see DYNAMIC_TYPE_ list in types.h)
 
     _Example_
     \code
@@ -20,24 +24,29 @@
 
     \sa wolfSSL_Free
     \sa wolfSSL_Realloc
+    \sa wolfSSL_SetAllocators
     \sa XMALLOC
     \sa XFREE
     \sa XREALLOC
 */
-WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char* func, unsigned int line);
+WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
 
 /*!
     \ingroup Memory
 
-    \brief This function calls a custom free function, if one has been
+    \brief This function is similar to free(), but calls the memory free
-    defined, or simply calls the default C free function if no custom
+    function which wolfSSL has been configured to use. By default, wolfSSL
-    function exists. It is not called directly by wolfSSL, but instead
+    uses free(). This can be changed using the wolfSSL memory abstraction
-    generally called by using XFREE, which may be replaced by wolfSSL_Free
+    layer - see wolfSSL_SetAllocators(). Note wolfSSL_Free is not 
-    during preprocessing.
+    called directly by wolfSSL, but instead called by macro XFREE.
+    For the default build only the ptr argument exists. If using 
+    WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
 
     \return none No returns.
 
-    \param ptr pointer to the memory to free
+    \param ptr pointer to the memory to be freed.
+    \param heap heap hint to use for memory. Can be NULL
+    \param type dynamic type (see DYNAMIC_TYPE_ list in types.h)
 
     _Example_
     \code
@@ -49,74 +58,14 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type, const char*
     }
     \endcode
 
-    \sa wolfSSL_Malloc
+    \sa wolfSSL_Alloc
-    \sa wolfSSL_Realloc
-    \sa XMALLOC
-    \sa XFREE
-    \sa XREALLOC
-*/
-WOLFSSL_API void  wolfSSL_Free(void *ptr, void* heap, int type, const char* func, unsigned int line);
-
-/*!
-    \ingroup Memory
-
-    \brief This function calls a custom realloc function, if one has been
-    defined, or simply calls the default C realloc function if no custom
-    function exists. It is not called directly by wolfSSL, but instead
-    generally called by using XREALLOC, which may be replaced by
-    wolfSSL_Realloc during preprocessing.
-
-    \return Success On successfully reallocating the desired memory,
-    returns a void* to that location
-    \return NULL Returned when there is a failure to reallocate memory
-
-    \param ptr pointer to the memory to the memory to reallocate
-    \param size desired size after reallocation
-
-    _Example_
-    \code
-    int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
-    int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2);
-    \endcode
-
-    \sa wolfSSL_Malloc
-    \sa wolfSSL_Free
-    \sa XMALLOC
-    \sa XFREE
-    \sa XREALLOC
-*/
-WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type, const char* func, unsigned int line);
-
-/*!
-    \ingroup Memory
-
-    \brief This function is similar to malloc(), but calls the memory
-    allocation function which wolfSSL has been configured to use. By default,
-    wolfSSL uses malloc().  This can be changed using the wolfSSL memory
-    abstraction layer - see wolfSSL_SetAllocators().
-
-    \return pointer If successful, this function returns a pointer to
-    allocated memory.
-    \return error If there is an error, NULL will be returned.
-    \return other Specific return values may be dependent on the underlying
-    memory allocation function being used (if not using the default malloc()).
-
-    \param size number of bytes to allocate.
-
-    _Example_
-    \code
-    char* buffer;
-    buffer = (char*) wolfSSL_Malloc(20);
-    if (buffer == NULL) {
-	    // failed to allocate memory
-    }
-    \endcode
-
-    \sa wolfSSL_Free
     \sa wolfSSL_Realloc
     \sa wolfSSL_SetAllocators
+    \sa XMALLOC
+    \sa XFREE
+    \sa XREALLOC
 */
-WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
+WOLFSSL_API void  wolfSSL_Free(void *ptr, void* heap, int type);
 
 /*!
     \ingroup Memory
@@ -124,60 +73,36 @@ WOLFSSL_API void* wolfSSL_Malloc(size_t size, void* heap, int type);
     \brief This function is similar to realloc(), but calls the memory
     re-allocation function which wolfSSL has been configured to use.
     By default, wolfSSL uses realloc().  This can be changed using the
-    wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().
+    wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). 
+    Note wolfSSL_Realloc is not called directly by wolfSSL, but instead called 
+    by macro XREALLOC. For the default build only the size argument exists.
+    If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
 
     \return pointer If successful, this function returns a pointer to
     re-allocated memory. This may be the same pointer as ptr, or a
     new pointer location.
     \return Null If there is an error, NULL will be returned.
-    \return other Specific return values may be dependent on the
-    underlying memory re-allocation function being used
-    (if not using the default realloc()).
 
     \param ptr pointer to the previously-allocated memory, to be reallocated.
     \param size number of bytes to allocate.
+    \param heap heap hint to use for memory. Can be NULL
+    \param type dynamic type (see DYNAMIC_TYPE_ list in types.h)
 
     _Example_
     \code
-    char* buffer;
+    int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
-
+    int* twentyInts = (int*)wolfSSL_Realloc(tenInts, sizeof(int)*20);
-    buffer = (char*) wolfSSL_Realloc(30);
-    if (buffer == NULL) {
-    	// failed to re-allocate memory
-    }
     \endcode
 
     \sa wolfSSL_Free
     \sa wolfSSL_Malloc
     \sa wolfSSL_SetAllocators
+    \sa XMALLOC
+    \sa XFREE
+    \sa XREALLOC
 */
 WOLFSSL_API void* wolfSSL_Realloc(void *ptr, size_t size, void* heap, int type);
 
-/*!
-    \ingroup Memory
-
-    \brief This function is similar to free(), but calls the memory free
-    function which wolfSSL has been configured to use. By default, wolfSSL
-    uses free(). This can be changed using the wolfSSL memory abstraction
-    layer - see wolfSSL_SetAllocators().
-
-    \return none No returns.
-
-    \param ptr pointer to the memory to be freed.
-
-    _Example_
-    \code
-    char* buffer;
-    ...
-    wolfSSL_Free(buffer);
-    \endcode
-
-    \sa wolfSSL_Alloc
-    \sa wolfSSL_Realloc
-    \sa wolfSSL_SetAllocators
-*/
-WOLFSSL_API void  wolfSSL_Free(void *ptr, const char* func, unsigned int line);
-
 /*!
     \ingroup Memory
 
@@ -199,32 +124,26 @@ WOLFSSL_API void  wolfSSL_Free(void *ptr, const char* func, unsigned int line);
 
     _Example_
     \code
-    int ret = 0;
+    static void* MyMalloc(size_t size)
-    // Memory function prototypes
-    void* MyMalloc(size_t size);
-    void  MyFree(void* ptr);
-    void* MyRealloc(void* ptr, size_t size);
-
-    // Register custom memory functions with wolfSSL
-    ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc);
-    if (ret != 0) {
-    	// failed to set memory functions
-    }
-
-    void* MyMalloc(size_t size)
     {
     	// custom malloc function
     }
 
-    void MyFree(void* ptr)
+    static void MyFree(void* ptr)
     {
     	// custom free function
     }
 
-    void* MyRealloc(void* ptr, size_t size)
+    static void* MyRealloc(void* ptr, size_t size)
     {
     	// custom realloc function
     }
+
+    // Register custom memory functions with wolfSSL
+    int ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc);
+    if (ret != 0) {
+    	// failed to set memory functions
+    }
     \endcode
 
     \sa none

doc/dox_comments/header_files/types.h

@@ -33,11 +33,10 @@
 	
 	_Example_
 	\code
-	int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER);
+	int* tenInts = XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
-
+    if (tenInts == NULL) {
-    if ( ints == NULL) {
+	    // error allocating space
-	// error allocating space
+	    return MEMORY_E;
-	return MEMORY_E;
     }
 	\endcode
 	
@@ -84,7 +83,9 @@ WOLFSSL_API void* XMALLOC(size_t n, void* heap, int type);
 	
 	_Example_
 	\code
-	none
+	int* tenInts = (int*)XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
+    int* twentyInts = (int*)XREALLOC(tenInts, sizeof(int)*20, NULL,
+        DYNAMIC_TYPE_TMP_BUFFER);
 	\endcode
 	
 	\sa wolfSSL_Malloc
@@ -127,9 +128,8 @@ WOLFSSL_API void* XREALLOC(void *p, size_t n, void* heap, int type);
 	
 	_Example_
 	\code
-	int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER);
+	int* tenInts = XMALLOC(sizeof(int) * 10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
-
+    if (tenInts == NULL) {
-    if ( ints == NULL) {
 	    // error allocating space
 	    return MEMORY_E;
     }