git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/common/include/private/iot_static_memory.h

   1 /*\r
   2  * Amazon FreeRTOS Common V1.0.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_static_memory.h\r
  28  * @brief Common functions for managing static buffers. Only used when\r
  29  * @ref IOT_STATIC_MEMORY_ONLY is `1`.\r
  30  */\r
  31 \r
  32 /* The config header is always included first. */\r
  33 #include "iot_config.h"\r
  34 \r
  35 /* The functions in this file should only exist in static memory only mode, hence\r
  36  * the check for IOT_STATIC_MEMORY_ONLY in the double inclusion guard. */\r
  37 #if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 )\r
  38 #define IOT_STATIC_MEMORY_H_\r
  39 \r
  40 /* Standard includes. */\r
  41 #include <stdbool.h>\r
  42 #include <stddef.h>\r
  43 #include <stdint.h>\r
  44 \r
  45 /**\r
  46  * @functionspage{static_memory,static memory component}\r
  47  * - @functionname{static_memory_function_init}\r
  48  * - @functionname{static_memory_function_cleanup}\r
  49  * - @functionname{static_memory_function_findfree}\r
  50  * - @functionname{static_memory_function_returninuse}\r
  51  * - @functionname{static_memory_function_messagebuffersize}\r
  52  * - @functionname{static_memory_function_mallocmessagebuffer}\r
  53  * - @functionname{static_memory_function_freemessagebuffer}\r
  54  */\r
  55 \r
  56 /*----------------------- Initialization and cleanup ------------------------*/\r
  57 \r
  58 /**\r
  59  * @functionpage{IotStaticMemory_Init,static_memory,init}\r
  60  * @functionpage{IotStaticMemory_Cleanup,static_memory,cleanup}\r
  61  */\r
  62 \r
  63 /**\r
  64  * @brief One-time initialization function for static memory.\r
  65  *\r
  66  * This function performs internal setup of static memory. <b>It must be called\r
  67  * once (and only once) before calling any other static memory function.</b>\r
  68  * Calling this function more than once without first calling\r
  69  * @ref static_memory_function_cleanup may result in a crash.\r
  70  *\r
  71  * @return `true` if initialization succeeded; `false` otherwise.\r
  72  *\r
  73  * @attention This function is called by `IotSdk_Init` and does not need to be\r
  74  * called by itself.\r
  75  *\r
  76  * @warning No thread-safety guarantees are provided for this function.\r
  77  *\r
  78  * @see static_memory_function_cleanup\r
  79  */\r
  80 /* @[declare_static_memory_init] */\r
  81 bool IotStaticMemory_Init( void );\r
  82 /* @[declare_static_memory_init] */\r
  83 \r
  84 /**\r
  85  * @brief One-time deinitialization function for static memory.\r
  86  *\r
  87  * This function frees resources taken in @ref static_memory_function_init.\r
  88  * It should be called after to clean up static memory. After this function\r
  89  * returns, @ref static_memory_function_init must be called again before\r
  90  * calling any other static memory function.\r
  91  *\r
  92  * @attention This function is called by `IotSdk_Cleanup` and does not need\r
  93  * to be called by itself.\r
  94  *\r
  95  * @warning No thread-safety guarantees are provided for this function.\r
  96  *\r
  97  * @see static_memory_function_init\r
  98  */\r
  99 /* @[declare_static_memory_cleanup] */\r
 100 void IotStaticMemory_Cleanup( void );\r
 101 /* @[declare_static_memory_cleanup] */\r
 102 \r
 103 /*------------------------- Buffer allocation and free ----------------------*/\r
 104 \r
 105 /**\r
 106  * @functionpage{IotStaticMemory_FindFree,static_memory,findfree}\r
 107  * @functionpage{IotStaticMemory_ReturnInUse,static_memory,returninuse}\r
 108  */\r
 109 \r
 110 /**\r
 111  * @brief Find a free buffer using the "in-use" flags.\r
 112  *\r
 113  * If a free buffer is found, this function marks the buffer in-use. This function\r
 114  * is common to the static memory implementation.\r
 115  *\r
 116  * @param[in] pInUse The "in-use" flags to search.\r
 117  * @param[in] limit How many flags to check, i.e. the size of `pInUse`.\r
 118  *\r
 119  * @return The index of a free buffer; `-1` if no free buffers are available.\r
 120  *\r
 121  * <b>Example</b>:\r
 122  * @code{c}\r
 123  * // To use this function, first declare two arrays. One provides the statically-allocated\r
 124  * // objects, the other provides flags to determine which objects are in-use.\r
 125  * #define NUMBER_OF_OBJECTS    ...\r
 126  * #define OBJECT_SIZE          ...\r
 127  * static bool _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };\r
 128  * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.\r
 129  *\r
 130  * // The function to statically allocate objects. Must have the same signature\r
 131  * // as malloc().\r
 132  * void * Iot_MallocObject( size_t size )\r
 133  * {\r
 134  *     int32_t freeIndex = -1;\r
 135  *     void * pNewObject = NULL;\r
 136  *\r
 137  *     // Check that sizes match. \r
 138  *     if( size != OBJECT_SIZE )\r
 139  *     {\r
 140  *         // Get the index of a free object.\r
 141  *         freeIndex = IotStaticMemory_FindFree( _pInUseMessageBuffers,\r
 142  *                                               IOT_MESSAGE_BUFFERS );\r
 143  *\r
 144  *         if( freeIndex != -1 )\r
 145  *         {\r
 146  *             pNewBuffer = &( _pMessageBuffers[ freeIndex ][ 0 ] );\r
 147  *         }\r
 148  *     }\r
 149  *\r
 150  *     return pNewBuffer;\r
 151  * }\r
 152  * @endcode\r
 153  */\r
 154 /* @[declare_static_memory_findfree] */\r
 155 int32_t IotStaticMemory_FindFree( bool * pInUse,\r
 156                                   size_t limit );\r
 157 /* @[declare_static_memory_findfree] */\r
 158 \r
 159 /**\r
 160  * @brief Return an "in-use" buffer.\r
 161  *\r
 162  * This function is common to the static memory implementation.\r
 163  *\r
 164  * @param[in] ptr Pointer to the buffer to return.\r
 165  * @param[in] pPool The pool of buffers that the in-use buffer was allocated from.\r
 166  * @param[in] pInUse The "in-use" flags for pPool.\r
 167  * @param[in] limit How many buffers (and flags) to check while searching for ptr.\r
 168  * @param[in] elementSize The size of a single element in pPool.\r
 169  *\r
 170  * <b>Example</b>:\r
 171  * @code{c}\r
 172  * // To use this function, first declare two arrays. One provides the statically-allocated\r
 173  * // objects, the other provides flags to determine which objects are in-use.\r
 174  * #define NUMBER_OF_OBJECTS    ...\r
 175  * #define OBJECT_SIZE          ...\r
 176  * static bool _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };\r
 177  * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.\r
 178  *\r
 179  * // The function to free statically-allocated objects. Must have the same signature\r
 180  * // as free().\r
 181  * void Iot_FreeObject( void * ptr )\r
 182  * {\r
 183  *     IotStaticMemory_ReturnInUse( ptr,\r
 184  *                                 _pObjects,\r
 185  *                                 _pInUseObjects,\r
 186  *                                 NUMBER_OF_OBJECTS,\r
 187  *                                 OBJECT_SIZE );\r
 188  * }\r
 189  * @endcode\r
 190  */\r
 191 /* @[declare_static_memory_returninuse] */\r
 192 void IotStaticMemory_ReturnInUse( void * ptr,\r
 193                                   void * pPool,\r
 194                                   bool * pInUse,\r
 195                                   size_t limit,\r
 196                                   size_t elementSize );\r
 197 /* @[declare_static_memory_returninuse] */\r
 198 \r
 199 /*------------------------ Message buffer management ------------------------*/\r
 200 \r
 201 /**\r
 202  * @functionpage{Iot_MessageBufferSize,static_memory,messagebuffersize}\r
 203  * @functionpage{Iot_MallocMessageBuffer,static_memory,mallocmessagebuffer}\r
 204  * @functionpage{Iot_FreeMessageBuffer,static_memory,freemessagebuffer}\r
 205  */\r
 206 \r
 207 /**\r
 208  * @brief Get the fixed size of a message buffer.\r
 209  *\r
 210  * The size of the message buffers are known at compile time, but it is a [constant]\r
 211  * (@ref IOT_MESSAGE_BUFFER_SIZE) that may not be visible to all source files.\r
 212  * This function allows other source files to know the size of a message buffer.\r
 213  *\r
 214  * @return The size, in bytes, of a single message buffer.\r
 215  */\r
 216 /* @[declare_static_memory_messagebuffersize] */\r
 217 size_t Iot_MessageBufferSize( void );\r
 218 /* @[declare_static_memory_messagebuffersize] */\r
 219 \r
 220 /**\r
 221  * @brief Get an empty message buffer.\r
 222  *\r
 223  * This function is the analog of [malloc]\r
 224  * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html)\r
 225  * for message buffers.\r
 226  *\r
 227  * @param[in] size Requested size for a message buffer.\r
 228  *\r
 229  * @return Pointer to the start of a message buffer. If the `size` argument is larger\r
 230  * than the [fixed size of a message buffer](@ref IOT_MESSAGE_BUFFER_SIZE)\r
 231  * or no message buffers are available, `NULL` is returned.\r
 232  */\r
 233 /* @[declare_static_memory_mallocmessagebuffer] */\r
 234 void * Iot_MallocMessageBuffer( size_t size );\r
 235 /* @[declare_static_memory_mallocmessagebuffer] */\r
 236 \r
 237 /**\r
 238  * @brief Free an in-use message buffer.\r
 239  *\r
 240  * This function is the analog of [free]\r
 241  * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html)\r
 242  * for message buffers.\r
 243  *\r
 244  * @param[in] ptr Pointer to the message buffer to free.\r
 245  */\r
 246 /* @[declare_static_memory_freemessagebuffer] */\r
 247 void Iot_FreeMessageBuffer( void * ptr );\r
 248 /* @[declare_static_memory_freemessagebuffer] */\r
 249  \r
 250 #endif /* if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 ) */\r