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

   1 /*\r
   2  * IoT Common V1.1.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 \r
  23 /**\r
  24  * @file iot_static_memory.h\r
  25  * @brief Common functions for managing static buffers. Only used when\r
  26  * @ref IOT_STATIC_MEMORY_ONLY is `1`.\r
  27  */\r
  28 \r
  29 /* The config header is always included first. */\r
  30 #include "iot_config.h"\r
  31 \r
  32 /* The functions in this file should only exist in static memory only mode, hence\r
  33  * the check for IOT_STATIC_MEMORY_ONLY in the double inclusion guard. */\r
  34 #if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 )\r
  35 #define IOT_STATIC_MEMORY_H_\r
  36 \r
  37 /* Standard includes. */\r
  38 #include <stddef.h>\r
  39 #include <stdint.h>\r
  40 \r
  41 /**\r
  42  * @functionspage{static_memory,static memory component}\r
  43  * - @functionname{static_memory_function_findfree}\r
  44  * - @functionname{static_memory_function_returninuse}\r
  45  * - @functionname{static_memory_function_messagebuffersize}\r
  46  * - @functionname{static_memory_function_mallocmessagebuffer}\r
  47  * - @functionname{static_memory_function_freemessagebuffer}\r
  48  */\r
  49 \r
  50 /*------------------------- Buffer allocation and free ----------------------*/\r
  51 \r
  52 /**\r
  53  * @functionpage{IotStaticMemory_FindFree,static_memory,findfree}\r
  54  * @functionpage{IotStaticMemory_ReturnInUse,static_memory,returninuse}\r
  55  */\r
  56 \r
  57 /**\r
  58  * @brief Find a free buffer using the "in-use" flags.\r
  59  *\r
  60  * If a free buffer is found, this function marks the buffer in-use. This function\r
  61  * is common to the static memory implementation.\r
  62  *\r
  63  * @param[in] pInUse The "in-use" flags to search.\r
  64  * @param[in] limit How many flags to check, i.e. the size of `pInUse`.\r
  65  *\r
  66  * @return The index of a free buffer; `-1` if no free buffers are available.\r
  67  *\r
  68  * <b>Example</b>:\r
  69  * @code{c}\r
  70  * // To use this function, first declare two arrays. One provides the statically-allocated\r
  71  * // objects, the other provides flags to determine which objects are in-use.\r
  72  * #define NUMBER_OF_OBJECTS    ...\r
  73  * #define OBJECT_SIZE          ...\r
  74  * static uint32_t _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };\r
  75  * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.\r
  76  *\r
  77  * // The function to statically allocate objects. Must have the same signature\r
  78  * // as malloc().\r
  79  * void * Iot_MallocObject( size_t size )\r
  80  * {\r
  81  *     int32_t freeIndex = -1;\r
  82  *     void * pNewObject = NULL;\r
  83  *\r
  84  *     // Check that sizes match. \r
  85  *     if( size != OBJECT_SIZE )\r
  86  *     {\r
  87  *         // Get the index of a free object.\r
  88  *         freeIndex = IotStaticMemory_FindFree( _pInUseMessageBuffers,\r
  89  *                                               IOT_MESSAGE_BUFFERS );\r
  90  *\r
  91  *         if( freeIndex != -1 )\r
  92  *         {\r
  93  *             pNewBuffer = &( _pMessageBuffers[ freeIndex ][ 0 ] );\r
  94  *         }\r
  95  *     }\r
  96  *\r
  97  *     return pNewBuffer;\r
  98  * }\r
  99  * @endcode\r
 100  */\r
 101 /* @[declare_static_memory_findfree] */\r
 102 int32_t IotStaticMemory_FindFree( uint32_t * pInUse,\r
 103                                   size_t limit );\r
 104 /* @[declare_static_memory_findfree] */\r
 105 \r
 106 /**\r
 107  * @brief Return an "in-use" buffer.\r
 108  *\r
 109  * This function is common to the static memory implementation.\r
 110  *\r
 111  * @param[in] ptr Pointer to the buffer to return.\r
 112  * @param[in] pPool The pool of buffers that the in-use buffer was allocated from.\r
 113  * @param[in] pInUse The "in-use" flags for pPool.\r
 114  * @param[in] limit How many buffers (and flags) to check while searching for ptr.\r
 115  * @param[in] elementSize The size of a single element in pPool.\r
 116  *\r
 117  * <b>Example</b>:\r
 118  * @code{c}\r
 119  * // To use this function, first declare two arrays. One provides the statically-allocated\r
 120  * // objects, the other provides flags to determine which objects are in-use.\r
 121  * #define NUMBER_OF_OBJECTS    ...\r
 122  * #define OBJECT_SIZE          ...\r
 123  * static uint32_t _pInUseObjects[ NUMBER_OF_OBJECTS ] = { 0 };\r
 124  * static uint8_t _pObjects[ NUMBER_OF_OBJECTS ][ OBJECT_SIZE ] = { { 0 } }; // Placeholder for objects.\r
 125  *\r
 126  * // The function to free statically-allocated objects. Must have the same signature\r
 127  * // as free().\r
 128  * void Iot_FreeObject( void * ptr )\r
 129  * {\r
 130  *     IotStaticMemory_ReturnInUse( ptr,\r
 131  *                                 _pObjects,\r
 132  *                                 _pInUseObjects,\r
 133  *                                 NUMBER_OF_OBJECTS,\r
 134  *                                 OBJECT_SIZE );\r
 135  * }\r
 136  * @endcode\r
 137  */\r
 138 /* @[declare_static_memory_returninuse] */\r
 139 void IotStaticMemory_ReturnInUse( void * ptr,\r
 140                                   void * pPool,\r
 141                                   uint32_t * pInUse,\r
 142                                   size_t limit,\r
 143                                   size_t elementSize );\r
 144 /* @[declare_static_memory_returninuse] */\r
 145 \r
 146 /*------------------------ Message buffer management ------------------------*/\r
 147 \r
 148 /**\r
 149  * @functionpage{Iot_MessageBufferSize,static_memory,messagebuffersize}\r
 150  * @functionpage{Iot_MallocMessageBuffer,static_memory,mallocmessagebuffer}\r
 151  * @functionpage{Iot_FreeMessageBuffer,static_memory,freemessagebuffer}\r
 152  */\r
 153 \r
 154 /**\r
 155  * @brief Get the fixed size of a message buffer.\r
 156  *\r
 157  * The size of the message buffers are known at compile time, but it is a [constant]\r
 158  * (@ref IOT_MESSAGE_BUFFER_SIZE) that may not be visible to all source files.\r
 159  * This function allows other source files to know the size of a message buffer.\r
 160  *\r
 161  * @return The size, in bytes, of a single message buffer.\r
 162  */\r
 163 /* @[declare_static_memory_messagebuffersize] */\r
 164 size_t Iot_MessageBufferSize( void );\r
 165 /* @[declare_static_memory_messagebuffersize] */\r
 166 \r
 167 /**\r
 168  * @brief Get an empty message buffer.\r
 169  *\r
 170  * This function is the analog of [malloc]\r
 171  * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html)\r
 172  * for message buffers.\r
 173  *\r
 174  * @param[in] size Requested size for a message buffer.\r
 175  *\r
 176  * @return Pointer to the start of a message buffer. If the `size` argument is larger\r
 177  * than the [fixed size of a message buffer](@ref IOT_MESSAGE_BUFFER_SIZE)\r
 178  * or no message buffers are available, `NULL` is returned.\r
 179  */\r
 180 /* @[declare_static_memory_mallocmessagebuffer] */\r
 181 void * Iot_MallocMessageBuffer( size_t size );\r
 182 /* @[declare_static_memory_mallocmessagebuffer] */\r
 183 \r
 184 /**\r
 185  * @brief Free an in-use message buffer.\r
 186  *\r
 187  * This function is the analog of [free]\r
 188  * (http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html)\r
 189  * for message buffers.\r
 190  *\r
 191  * @param[in] ptr Pointer to the message buffer to free.\r
 192  */\r
 193 /* @[declare_static_memory_freemessagebuffer] */\r
 194 void Iot_FreeMessageBuffer( void * ptr );\r
 195 /* @[declare_static_memory_freemessagebuffer] */\r
 196  \r
 197 #endif /* if !defined( IOT_STATIC_MEMORY_H_ ) && ( IOT_STATIC_MEMORY_ONLY == 1 ) */\r