Add MQTT Agent submodule (#551)

* Add MQTT Agent submodule

* Add MQTT agent platform files

Co-authored-by: abhidixi11 <44424462+abhidixi11@users.noreply.github.com>
Co-authored-by: Joseph Julicher <jjulicher@mac.com>

7 files changed, 394 insertions, 0 deletions

diff --git a/.gitmodules b/.gitmodules
index 902969180..6d2043a22 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -43,3 +43,6 @@
 [submodule "FreeRTOS/Test/aws-build-accumulator"]
 	path = FreeRTOS/Test/litani
 	url = https://github.com/awslabs/aws-build-accumulator.git
+[submodule "FreeRTOS-Plus/Source/Application-Protocols/coreMQTT-Agent"]
+	path = FreeRTOS-Plus/Source/Application-Protocols/coreMQTT-Agent
+	url = https://github.com/FreeRTOS/coreMQTT-Agent.git
diff --git a/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_agent_message.c b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_agent_message.c
new file mode 100644
index 000000000..0ab66a961
--- /dev/null
+++ b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_agent_message.c
@@ -0,0 +1,74 @@
+/*
+ * FreeRTOS V202012.00
+ * Copyright (C) 2020 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.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+/**
+ * @file freertos_agent_message.c
+ * @brief Implements functions to interact with queues.
+ */
+
+/* Standard includes. */
+#include <string.h>
+#include <stdio.h>
+
+/* Kernel includes. */
+#include "FreeRTOS.h"
+#include "semphr.h"
+
+/* Header include. */
+#include "freertos_agent_message.h"
+#include "agent_message.h"
+
+/*-----------------------------------------------------------*/
+
+bool Agent_MessageSend( const AgentMessageContext_t * pMsgCtx,
+                        const void * pData,
+                        uint32_t blockTimeMs )
+{
+    BaseType_t queueStatus = pdFAIL;
+
+    if( ( pMsgCtx != NULL ) && ( pData != NULL ) )
+    {
+        queueStatus = xQueueSendToBack( pMsgCtx->queue, pData, pdMS_TO_TICKS( blockTimeMs ) );
+    }
+
+    return ( queueStatus == pdPASS ) ? true : false;
+}
+
+/*-----------------------------------------------------------*/
+
+bool Agent_MessageReceive( const AgentMessageContext_t * pMsgCtx,
+                           void * pBuffer,
+                           uint32_t blockTimeMs )
+{
+    BaseType_t queueStatus = pdFAIL;
+
+    if( ( pMsgCtx != NULL ) && ( pBuffer != NULL ) )
+    {
+        queueStatus = xQueueReceive( pMsgCtx->queue, pBuffer, pdMS_TO_TICKS( blockTimeMs ) );
+    }
+
+    return ( queueStatus == pdPASS ) ? true : false;
+}
diff --git a/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_command_pool.c b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_command_pool.c
new file mode 100644
index 000000000..bfbd6b052
--- /dev/null
+++ b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/freertos_command_pool.c
@@ -0,0 +1,147 @@
+/*
+ * FreeRTOS V202012.00
+ * Copyright (C) 2020 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.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+/**
+ * @file freertos_command_pool.c
+ * @brief Implements functions to obtain and release commands.
+ */
+
+/* Standard includes. */
+#include <string.h>
+#include <stdio.h>
+
+/* Kernel includes. */
+#include "FreeRTOS.h"
+#include "semphr.h"
+
+/* Header include. */
+#include "freertos_command_pool.h"
+#include "freertos_agent_message.h"
+
+/*-----------------------------------------------------------*/
+
+#define QUEUE_NOT_INITIALIZED    ( 0U )
+#define QUEUE_INITIALIZED        ( 1U )
+
+/**
+ * @brief The pool of command structures used to hold information on commands (such
+ * as PUBLISH or SUBSCRIBE) between the command being created by an API call and
+ * completion of the command by the execution of the command's callback.
+ */
+static Command_t commandStructurePool[ MQTT_COMMAND_CONTEXTS_POOL_SIZE ];
+
+/**
+ * @brief The message context used to guard the pool of Command_t structures.
+ * For FreeRTOS, this is implemented with a queue. Structures may be
+ * obtained by receiving a pointer from the queue, and returned by
+ * sending the pointer back into it.
+ */
+static AgentMessageContext_t commandStructMessageCtx;
+
+/**
+ * @brief Initialization status of the queue.
+ */
+static volatile uint8_t initStatus = QUEUE_NOT_INITIALIZED;
+
+/*-----------------------------------------------------------*/
+
+void Agent_InitializePool( void )
+{
+    size_t i;
+    Command_t * pCommand;
+    static uint8_t staticQueueStorageArea[ MQTT_COMMAND_CONTEXTS_POOL_SIZE * sizeof( Command_t * ) ];
+    static StaticQueue_t staticQueueStructure;
+    bool commandAdded = false;
+
+    if( initStatus == QUEUE_NOT_INITIALIZED )
+    {
+        memset( ( void * ) commandStructurePool, 0x00, sizeof( commandStructurePool ) );
+        commandStructMessageCtx.queue = xQueueCreateStatic( MQTT_COMMAND_CONTEXTS_POOL_SIZE,
+                                                       sizeof( Command_t * ),
+                                                       staticQueueStorageArea,
+                                                       &staticQueueStructure );
+        configASSERT( commandStructMessageCtx.queue );
+
+        /* Populate the queue. */
+        for( i = 0; i < MQTT_COMMAND_CONTEXTS_POOL_SIZE; i++ )
+        {
+            /* Store the address as a variable. */
+            pCommand = &commandStructurePool[ i ];
+            /* Send the pointer to the queue. */
+            commandAdded = Agent_MessageSend( &commandStructMessageCtx, &pCommand, 0U );
+            configASSERT( commandAdded );
+        }
+
+        initStatus = QUEUE_INITIALIZED;
+    }
+}
+
+/*-----------------------------------------------------------*/
+
+Command_t * Agent_GetCommand( uint32_t blockTimeMs )
+{
+    Command_t * structToUse = NULL;
+    size_t i;
+    bool structRetrieved = false;
+
+    /* Check queue has been created. */
+    configASSERT( initStatus == QUEUE_INITIALIZED );
+
+    /* Retrieve a struct from the queue. */
+    structRetrieved = Agent_MessageReceive( &commandStructMessageCtx, &( structToUse ), blockTimeMs );
+
+    if( !structRetrieved )
+    {
+        LogError( ( "No command structure available." ) );
+    }
+
+    return structToUse;
+}
+
+/*-----------------------------------------------------------*/
+
+bool Agent_ReleaseCommand( Command_t * pCommandToRelease )
+{
+    size_t i;
+    bool structReturned = false;
+
+    configASSERT( initStatus == QUEUE_INITIALIZED );
+
+    /* See if the structure being returned is actually from the pool. */
+    if( ( pCommandToRelease >= commandStructurePool ) &&
+        ( pCommandToRelease < ( commandStructurePool + MQTT_COMMAND_CONTEXTS_POOL_SIZE ) ) )
+    {
+        structReturned = Agent_MessageSend( &commandStructMessageCtx, &pCommandToRelease, 0U );
+
+        /* The send should not fail as the queue was created to hold every command
+         * in the pool. */
+        configASSERT( structReturned );
+        LogDebug( ( "Returned Command Context %d to pool",
+                    ( int ) ( pCommandToRelease - commandStructurePool ) ) );
+    }
+
+    return structReturned;
+}
diff --git a/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_agent_message.h b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_agent_message.h
new file mode 100644
index 000000000..47458519a
--- /dev/null
+++ b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_agent_message.h
@@ -0,0 +1,84 @@
+/*
+ * FreeRTOS V202012.00
+ * Copyright (C) 2020 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.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+/**
+ * @file freertos_agent_message.h
+ * @brief Functions to interact with queues.
+ */
+#ifndef FREERTOS_AGENT_MESSAGE_H
+#define FREERTOS_AGENT_MESSAGE_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+/* FreeRTOS includes. */
+#include "FreeRTOS.h"
+#include "queue.h"
+
+/* Include MQTT agent messaging interface. */
+#include "agent_message.h"
+
+/**
+ * @ingroup mqtt_agent_struct_types
+ * @brief Context with which tasks may deliver messages to the agent.
+ */
+struct AgentMessageContext
+{
+    QueueHandle_t queue;
+};
+
+/*-----------------------------------------------------------*/
+
+/**
+ * @brief Send a message to the specified context.
+ * Must be thread safe.
+ *
+ * @param[in] pMsgCtx An #AgentMessageContext_t.
+ * @param[in] pData Pointer to element to send to queue.
+ * @param[in] blockTimeMs Block time to wait for a send.
+ *
+ * @return `true` if send was successful, else `false`.
+ */
+bool Agent_MessageSend( const AgentMessageContext_t * pMsgCtx,
+                        const void * pData,
+                        uint32_t blockTimeMs );
+
+/**
+ * @brief Receive a message from the specified context.
+ * Must be thread safe.
+ *
+ * @param[in] pMsgCtx An #AgentMessageContext_t.
+ * @param[in] pBuffer Pointer to buffer to write received data.
+ * @param[in] blockTimeMs Block time to wait for a receive.
+ *
+ * @return `true` if receive was successful, else `false`.
+ */
+bool Agent_MessageReceive( const AgentMessageContext_t * pMsgCtx,
+                           void * pBuffer,
+                           uint32_t blockTimeMs );
+
+#endif /* FREERTOS_AGENT_MESSAGE_H */
diff --git a/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_command_pool.h b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_command_pool.h
new file mode 100644
index 000000000..598099d11
--- /dev/null
+++ b/FreeRTOS-Plus/Demo/Common/coreMQTT_Agent_Interface/include/freertos_command_pool.h
@@ -0,0 +1,83 @@
+/*
+ * FreeRTOS V202012.00
+ * Copyright (C) 2020 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.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+/**
+ * @file freertos_command_pool.h
+ * @brief Functions to obtain and release a command.
+ */
+#ifndef FREERTOS_COMMAND_POOL_H
+#define FREERTOS_COMMAND_POOL_H
+
+/* MQTT agent includes. */
+#include "mqtt_agent.h"
+
+/**
+ * @brief Initialize the common task pool. Not thread safe.
+ */
+void Agent_InitializePool( void );
+
+/**
+ * @brief Obtain a Command_t structure from the pool of structures managed by the agent.
+ *
+ * @note Command_t structures hold everything the MQTT agent needs to process a
+ * command that originates from application.  Examples of commands are PUBLISH and
+ * SUBSCRIBE.  The Command_t structure must persist for the duration of the command's
+ * operation so are obtained from a pool of statically allocated structures when a
+ * new command is created, and returned to the pool when the command is complete.
+ * The MQTT_COMMAND_CONTEXTS_POOL_SIZE configuration file constant defines how many
+ * structures the pool contains.
+ *
+ * @param[in] blockTimeMs The length of time the calling task should remain in the
+ * Blocked state (so not consuming any CPU time) to wait for a Command_t structure to
+ * become available should one not be immediately at the time of the call.
+ *
+ * @return A pointer to a Command_t structure if one becomes available before
+ * blockTimeMs time expired, otherwise NULL.
+ */
+Command_t * Agent_GetCommand( uint32_t blockTimeMs );
+
+/**
+ * @brief Give a Command_t structure back to the the pool of structures managed by
+ * the agent.
+ *
+ * @note Command_t structures hold everything the MQTT agent needs to process a
+ * command that originates from application.  Examples of commands are PUBLISH and
+ * SUBSCRIBE.  The Command_t structure must persist for the duration of the command's
+ * operation so are obtained from a pool of statically allocated structures when a
+ * new command is created, and returned to the pool when the command is complete.
+ * The MQTT_COMMAND_CONTEXTS_POOL_SIZE configuration file constant defines how many
+ * structures the pool contains.
+ *
+ * @param[in] pCommandToRelease A pointer to the Command_t structure to return to
+ * the pool.  The structure must first have been obtained by calling
+ * Agent_GetCommand(), otherwise Agent_ReleaseCommand() will
+ * have no effect.
+ *
+ * @return true if the Command_t structure was returned to the pool, otherwise false.
+ */
+bool Agent_ReleaseCommand( Command_t * pCommandToRelease );
+
+#endif /* FREERTOS_COMMAND_POOL_H */
diff --git a/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT-Agent b/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT-Agent
new file mode 160000
+Subproject 541402274fc6bf52f35e14f39c0c1dd2f9205ad
diff --git a/FreeRTOS-Plus/Source/Application-Protocols/readme.txt b/FreeRTOS-Plus/Source/Application-Protocols/readme.txt
index 956c32b92..08e930aeb 100644
--- a/FreeRTOS-Plus/Source/Application-Protocols/readme.txt
+++ b/FreeRTOS-Plus/Source/Application-Protocols/readme.txt
@@ -9,6 +9,9 @@ Directories:
 + coreMQTT contains the implementation of the coreMQTT library.  See:
   https://www.freertos.org/mqtt
 
++ coreMQTT-Agent contains the implementation of the coreMQTT Agent library.  See:
+  https://www.freertos.org/mqtt/mqtt-agent-demo
+
 + network_transport contains the transport interface definition.  See the
   comment above and https://www.freertos.org/network-interface.html