/*
 * FreeRTOS Common V1.1.1
 * 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.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */

/**
 * @file iot_static_memory.h
 * @brief Common functions for managing static buffers. Only used when
 * @ref IOT_STATIC_MEMORY_ONLY is `1`.
 */

/* The config header is always included first. */
#include "iot_config.h"

/* The functions in this file should only exist in static memory only mode, hence
 * the check for IOT_STATIC_MEMORY_ONLY in the double inclusion guard. */
#if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 )
    #define IOT_STATIC_MEMORY_H_

/* Standard includes. */
    #include <stdbool.h>
    #include <stddef.h>
    #include <stdint.h>

/**
 * @functions_page{static_memory, Static Memory}
 * @functions_brief{static memory component}
 * - @function_name{static_memory_function_init}
 * @function_brief{static_memory_function_init}
 * - @function_name{static_memory_function_cleanup}
 * @function_brief{static_memory_function_cleanup}
 * - @function_name{static_memory_function_findfree}
 * @function_brief{static_memory_function_findfree}
 * - @function_name{static_memory_function_returninuse}
 * @function_brief{static_memory_function_returninuse}
 * - @function_name{static_memory_function_messagebuffersize}
 * @function_brief{static_memory_function_messagebuffersize}
 * - @function_name{static_memory_function_mallocmessagebuffer}
 * @function_brief{static_memory_function_mallocmessagebuffer}
 * - @function_name{static_memory_function_freemessagebuffer}
 * @function_brief{static_memory_function_freemessagebuffer}
 */

/*----------------------- Initialization and cleanup ------------------------*/

/**
 * @function_page{IotStaticMemory_Init,static_memory,init}
 * @function_snippet{static_memory,init,this}
 * @copydoc IotStaticMemory_Init
 * @function_page{IotStaticMemory_Cleanup,static_memory,cleanup}
 * @function_snippet{static_memory,cleanup,this}
 * @copydoc IotStaticMemory_Cleanup
 */

/**
 * @brief One-time initialization function for static memory.
 *
 * This function performs internal setup of static memory. <b>It must be called
 * once (and only once) before calling any other static memory function.</b>
 * Calling this function more than once without first calling
 * @ref static_memory_function_cleanup may result in a crash.
 *
 * @return `true` if initialization succeeded; `false` otherwise.
 *
 * @attention This function is called by `IotSdk_Init` and does not need to be
 * called by itself.
 *
 * @warning No thread-safety guarantees are provided for this function.
 *
 * @see static_memory_function_cleanup
 */
/* @[declare_static_memory_init] */
    bool IotStaticMemory_Init( void );
/* @[declare_static_memory_init] */

/**
 * @brief One-time deinitialization function for static memory.
 *
 * This function frees resources taken in @ref static_memory_function_init.
 * It should be called after to clean up static memory. After this function
 * returns, @ref static_memory_function_init must be called again before
 * calling any other static memory function.
 *
 * @attention This function is called by `IotSdk_Cleanup` and does not need
 * to be called by itself.
 *
 * @warning No thread-safety guarantees are provided for this function.
 *
 * @see static_memory_function_init
 */
/* @[declare_static_memory_cleanup] */
    void IotStaticMemory_Cleanup( void );
/* @[declare_static_memory_cleanup] */

/*------------------------- Buffer allocation and free ----------------------*/

/**
 * @function_page{IotStaticMemory_FindFree,static_memory,findfree}
 * @function_snippet{static_memory,findfree,this}
 * @copydoc IotStaticMemory_FindFree
 * @function_page{IotStaticMemory_ReturnInUse,static_memory,returninuse}
 * @function_snippet{static_memory,returninuse,this}
 * @copydoc IotStaticMemory_ReturnInUse
 */

/**
 * @brief Find a free buffer using the "in-use" flags.
 *
 * If a free buffer is found, this function marks the buffer in-use. This function
 * is common to the static memory implementation.
 *
 * @param[in] pInUse The "in-use" flags to search.
 * @param[in] limit How many flags to check, i.e. the size of `pInUse`.
 *
 * @return The index of a free buffer; `-1` if no free buffers are available.
 *
 * <b>Example</b>:
 * @code{c}
 * // To use this function, first declare two arrays. One provides the statically-allocated
 * // objects, the other provides flags to determine which objects are in-use.
 * #define NUMBER_OF_OBJECTS    ...
 * #define OBJECT_SIZE          ...
 * static bool _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };
 * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.
 *
 * // The function to statically allocate objects. Must have the same signature
 * // as malloc().
 * void * Iot_MallocObject( size_t size )
 * {
 *     int32_t freeIndex = -1;
 *     void * pNewObject = NULL;
 *
 *     // Check that sizes match.
 *     if( size != OBJECT_SIZE )
 *     {
 *         // Get the index of a free object.
 *         freeIndex = IotStaticMemory_FindFree( _pInUseMessageBuffers,
 *                                               IOT_MESSAGE_BUFFERS );
 *
 *         if( freeIndex != -1 )
 *         {
 *             pNewBuffer = &( _pMessageBuffers[ freeIndex ][ 0 ] );
 *         }
 *     }
 *
 *     return pNewBuffer;
 * }
 * @endcode
 */
/* @[declare_static_memory_findfree] */
    int32_t IotStaticMemory_FindFree( bool * pInUse,
                                      size_t limit );
/* @[declare_static_memory_findfree] */

/**
 * @brief Return an "in-use" buffer.
 *
 * This function is common to the static memory implementation.
 *
 * @param[in] ptr Pointer to the buffer to return.
 * @param[in] pPool The pool of buffers that the in-use buffer was allocated from.
 * @param[in] pInUse The "in-use" flags for pPool.
 * @param[in] limit How many buffers (and flags) to check while searching for ptr.
 * @param[in] elementSize The size of a single element in pPool.
 *
 * <b>Example</b>:
 * @code{c}
 * // To use this function, first declare two arrays. One provides the statically-allocated
 * // objects, the other provides flags to determine which objects are in-use.
 * #define NUMBER_OF_OBJECTS    ...
 * #define OBJECT_SIZE          ...
 * static bool _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };
 * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.
 *
 * // The function to free statically-allocated objects. Must have the same signature
 * // as free().
 * void Iot_FreeObject( void * ptr )
 * {
 *     IotStaticMemory_ReturnInUse( ptr,
 *                                 _pObjects,
 *                                 _pInUseObjects,
 *                                 NUMBER_OF_OBJECTS,
 *                                 OBJECT_SIZE );
 * }
 * @endcode
 */
/* @[declare_static_memory_returninuse] */
    void IotStaticMemory_ReturnInUse( void * ptr,
                                      void * pPool,
                                      bool * pInUse,
                                      size_t limit,
                                      size_t elementSize );
/* @[declare_static_memory_returninuse] */

/*------------------------ Message buffer management ------------------------*/

/**
 * @function_page{Iot_MessageBufferSize,static_memory,messagebuffersize}
 * @function_snippet{static_memory,messagebuffersize,this}
 * @copydoc Iot_MessageBufferSize
 * @function_page{Iot_MallocMessageBuffer,static_memory,mallocmessagebuffer}
 * @function_snippet{static_memory,mallocmessagebuffer,this}
 * @copydoc Iot_MallocMessageBuffer
 * @function_page{Iot_FreeMessageBuffer,static_memory,freemessagebuffer}
 * @function_snippet{static_memory,freemessagebuffer,this}
 * @copydoc Iot_FreeMessageBuffer
 */

/**
 * @brief Get the fixed size of a message buffer.
 *
 * The size of the message buffers are known at compile time, but it is a [constant]
 * (@ref IOT_MESSAGE_BUFFER_SIZE) that may not be visible to all source files.
 * This function allows other source files to know the size of a message buffer.
 *
 * @return The size, in bytes, of a single message buffer.
 */
/* @[declare_static_memory_messagebuffersize] */
    size_t Iot_MessageBufferSize( void );
/* @[declare_static_memory_messagebuffersize] */

/**
 * @brief Get an empty message buffer.
 *
 * This function is the analog of [malloc]
 * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html)
 * for message buffers.
 *
 * @param[in] size Requested size for a message buffer.
 *
 * @return Pointer to the start of a message buffer. If the `size` argument is larger
 * than the [fixed size of a message buffer](@ref IOT_MESSAGE_BUFFER_SIZE)
 * or no message buffers are available, `NULL` is returned.
 */
/* @[declare_static_memory_mallocmessagebuffer] */
    void * Iot_MallocMessageBuffer( size_t size );
/* @[declare_static_memory_mallocmessagebuffer] */

/**
 * @brief Free an in-use message buffer.
 *
 * This function is the analog of [free]
 * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html)
 * for message buffers.
 *
 * @param[in] ptr Pointer to the message buffer to free.
 */
/* @[declare_static_memory_freemessagebuffer] */
    void Iot_FreeMessageBuffer( void * ptr );
/* @[declare_static_memory_freemessagebuffer] */

#endif /* if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 ) */