Update coding convention

include/test_execution_config.h

@@ -1,7 +1,41 @@
-#ifndef _TEST_EXECUTION_CONFIG_H_
-#define _TEST_EXECUTION_CONFIG_H_
+/*
+ * FreeRTOS FreeRTOS LTS Qualification Tests preview
+ * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
 
+/**
+ * @file test_execution_config.h
+ * @brief This setup the execution configurations for LTS qualification test.
+ */
+
+#ifndef TEST_EXECUTION_CONFIG_H
+#define TEST_EXECUTION_CONFIG_H
+
+/** 
+ * @brief Configuration to enable the MQTT test.
+ */
 #define MQTT_TEST_ENABLED                 (0)
+
+/** 
+ * @brief Configuration to enable the transport interface test.
+ */
 #define TRANSPORT_INTERFACE_TEST_ENABLED  (0)
 
-#endif /* _TEST_EXECUTION_CONFIG_H_ */
+#endif /* TEST_EXECUTION_CONFIG_H */

include/test_param_config.h

@@ -1,19 +1,65 @@
-#ifndef _TEST_PARAM_CONFIG_H_
-#define _TEST_PARAM_CONFIG_H_
+/*
+ * FreeRTOS FreeRTOS LTS Qualification Tests preview
+ * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
 
-/* When FORCE_GENERATE_NEW_KEY_PAIR is set to 1, the device should generate
+/**
+ * @file test_param_config.h
+ * @brief This setup the test parameters for LTS qualification test.
+ */
+
+#ifndef TEST_PARAM_CONFIG_H
+#define TEST_PARAM_CONFIG_H
+
+/** 
+ * @brief Configuration that indicates if the device should generate a key pair.
+ * 
+ * @note When FORCE_GENERATE_NEW_KEY_PAIR is set to 1, the device should generate
  * a new on-device key pair and output public key. When set to 0, the device
  * should keep existing key pair.
  */
 #define FORCE_GENERATE_NEW_KEY_PAIR   0
 
+/**
+ * @brief Endpoint of the MQTT broker to connect to in mqtt test.
+ */
 #define MQTT_SERVER_ENDPOINT   "PLACE_HOLDER"
+
+/**
+ * @brief Port of the MQTT broker to connect to in mqtt test.
+ */
 #define MQTT_SERVER_PORT       (8883)
 
+/**
+ * @brief Endpoint of the echo server to connect to in transport interface test.
+ */
 #define ECHO_SERVER_ENDPOINT   "PLACE_HOLDER"
+
+/**
+ * @brief Port of the echo server to connect to in transport interface test.
+ */
 #define ECHO_SERVER_PORT       (9000)
 
-/* Root certificate of the echo server.
+/**
+ * @brief Root certificate of the echo server.
+ *
  * @note This certificate should be PEM-encoded.
  *
  * Must include the PEM header and footer:
@@ -23,7 +69,9 @@
  */
 #define ECHO_SERVER_ROOT_CA "PLACE_HOLDER"
 
-/* Client certificate to connect to echo server.
+/**
+ * @brief Client certificate to connect to echo server.
+ *
  * @note This certificate should be PEM-encoded.
  *
  * Must include the PEM header and footer:
@@ -33,11 +81,13 @@
  */
 #define TRANSPORT_CLIENT_CA NULL
 
-/* Client private key to connect to echo server.
+/**
+ * @brief Client private key to connect to echo server.
+ *
  * @note This is should only be used for testing purpose.
+ *
  * For qualification, the key should be generated on-device.
  */
 #define TRANSPORT_CLIENT_KEY  NULL
 
-
-#endif /* _TEST_PARAM_CONFIG_H_ */
+#endif /* TEST_PARAM_CONFIG_H */

src/common/network_connection.h

@@ -1,30 +1,76 @@
-#ifndef _NETWORK_CONNECTION_H_
-#define _NETWORK_CONNECTION_H_
+/*
+ * FreeRTOS FreeRTOS LTS Qualification Tests preview
+ * Copyright (C) 2022 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @file network_connection.h
+ * @brief Network connect/disconnect functions for test appliction.
+ */
+#ifndef NETWORK_CONNECTION_H
+#define NETWORK_CONNECTION_H
 
+/**
+ * @brief Struct to hold the host information for connection.
+ */
 typedef struct TestHostInfo
 {
     const char * pHostName; /**< @brief Server host name. The string should be nul terminated. */
     uint16_t port;          /**< @brief Server port in host-order. */
 } TestHostInfo_t;
 
 /**
- * NetworkConnectFunc is a function pointer type for functions that
- * establish a network connection with a server. It takes three arguments:
- * a void * network context,
- * a TestHostInfo_t * host info about which server to connect to,
- * a void * network credentials.
+ * @brief Network connect return status.
+ */
+typedef enum NetworkConnectStatus
+{
+    NETWORK_CONNECT_SUCCESS = 0,         /**< @brief Function successfully completed. */
+    NETWORK_CONNECT_INVALID_PARAMETER,   /**< @brief At least one parameter was invalid. */
+    NETWORK_CONNECT_INSUFFICIENT_MEMORY, /**< @brief Insufficient memory required to establish connection. */
+    NETWORK_CONNECT_INVALID_CREDENTIALS, /**< @brief Provided credentials were invalid. */
+    NETWORK_CONNECT_HANDSHAKE_FAILED,    /**< @brief Performing TLS handshake with server failed. */
+    NETWORK_CONNECT_INTERNAL_ERROR,      /**< @brief A call to a system API resulted in an internal error. */
+    NETWORK_CONNECT_FAILURE              /**< @brief Initial connection to the server failed. */
+} NetworkConnectStatus_t;
+
+/**
+ * @brief A function pointer type for function that establish a network connection
+ * with a server.
+ *
+ * @param[in] pNetworkContext Network context to setup the connection.
+ * @param[in] pHostInfo Host information for the connection.
+ * @param[in] pNetworkCredentials Network credentials for the connection.
  *
- * Network context and crendentials are defined by application implementations.
+ * @return NETWORK_CONNECT_SUCCESS if the network connection is established successfully.
+ * Otherwise, return other network connect status to indicate error.
  */
-typedef int (*NetworkConnectFunc)( void *, TestHostInfo_t *, void * );
+typedef NetworkConnectStatus_t ( * NetworkConnectFunc_t )( void * pNetworkContext,
+                                                           TestHostInfo_t * pHostInfo,
+                                                           void * pNetworkCredentials );
 
 /**
- * NetworkDisconnectFunc is a function pointer type for functions that
- * disconnect a previously established network connection. It takes one argument:
- * a void * network context.
+ * @brief A function pointer type for function that disconnect a previously established
+ * network connection with a server.
  *
- * Network context is defined by application implementations.
+ * @param[in] pNetworkContext Network context to disconnect the connection.
  */
-typedef void (*NetworkDisconnectFunc)( void * );
+typedef void ( * NetworkDisconnectFunc_t )( void * pNetworkContext );
 
-#endif /* _NETWORK_CONNECTION_H_ */
+#endif /* NETWORK_CONNECTION_H */