Added extra functionality for MicroTBX in combination with FreeRTOS. …

…Prepared 0.9.5 release.

ChangeLog

@@ -1,4 +1,11 @@
 -----------------------------------------------------------------------------------------
+2022-03-09 Frank Voorburg <[email protected]>
+
+* Added complete API reference to the documentation.
+* Added extra functionality for usinig MicroTBX in combination with FreeRTOS.
+* Configured GitHub actions for building and publishing the documentation.
+* Public release of version 0.9.5.
+-----------------------------------------------------------------------------------------
 2021-10-29 Frank Voorburg <[email protected]>
 
 * Moved demos to a separate git repository.

docs/extra.md

@@ -0,0 +1,50 @@
+# Extra functionality
+
+You can find some optional and extra functionality in the directory `source/extra`. This section provides additional information regarding this functionality.
+
+## MicroTBX for FreeRTOS
+
+The [FreeRTOS](https://www.freertos.org) real-time operating system is widely used in the embedded industry. No wonder, because it's free, open source, high quality, MISRA compliant and maintained by [AWS](https://aws.amazon.com/). 
+
+Whenever you use both FreeRTOS and MicroTBX, a few pieces of functionality are redundant. Both MicroTBX and FreeRTOS offer heap management and assertion functionality. There is nothing wrong with using both. However, if you'd like to reap the benefits of MicroTBX, while also using FreeRTOS, consider using the files in directory:
+
+* `source/extra/freertos/`
+
+### Heap management
+
+FreeRTOS ships with a few different examples for heap management. Some allow just one-time memory allocation, some feature functionality to release allocated memory again, with minimal memory fragmentation. You can find these examples in directory:
+
+* `FreeRTOS/Source/portable/MemMang/`
+
+The file `tbxfreertos.c` offers an alternative heap management implementation, using MicroTBX's memory pools. This allows you to dynamically allocate and release memory on the heap, for your application's FreeRTOS objects.
+
+To use this solution heap management solution, you just need to remove the `heap_x.c` source file from your project and compile and link `tbxfreertos.c` instead.
+
+### Assertions
+
+In the FreeRTOS configuration header file `FreeRTOSConfig.h`, you can add and configure the `configASSERT` macro to enable assertions in the FreeRTOS code base. MicroTBX includes an assertion module that you can use for this. The easiest way to link the MicroTBX assertion `TBX_ASSERT` macro to the FreeRTOS `configASSERT` macro, is by including the `tbxfreertos.h` header file all the way at the end. Just before the last `#endif`:
+
+```c
+#define INCLUDE_vTaskCleanUpResources                 1
+#define INCLUDE_vTaskSuspend                          1
+#define INCLUDE_vTaskDelayUntil                       1
+#define INCLUDE_vTaskDelay                            1
+#define INCLUDE_uxTaskGetStackHighWaterMark           1
+
+/* Use MicroTBX assertion in FreeRTOS. */
+#include "tbxfreertos.h" /* <---- ADD THIS LINE */
+
+#endif /* FREERTOS_CONFIG_H */
+```
+
+Just make sure to add the directory, where the `tbxfreertos.h` resides, to your compiler's search path for included header files.
+
+Alternatively, you can directly add and configure the `configASSERT` macro as follows in `FreeRTOSConfig.h`:
+
+```c
+#include "microtbx.h"
+#define configASSERT( x ) TBX_ASSERT( x )
+```
+
+
+

mkdocs.yml

@@ -15,3 +15,4 @@ nav:
   - Random numbers: 'random.md'
   - Checksums: 'checksum.md'
   - Cryptography: 'crypto.md'
+  - Extra functionality: 'extra.md'

source/extra/freertos/tbxfreertos.c

@@ -0,0 +1,149 @@
+/************************************************************************************//**
+* \file         tbxfreertos.c
+* \brief        Heap management source file for FreeRTOS based on MicroTBX.
+* \internal
+*----------------------------------------------------------------------------------------
+*                          C O P Y R I G H T
+*----------------------------------------------------------------------------------------
+*   Copyright (c) 2022 by Feaser     www.feaser.com     All rights reserved
+*
+*----------------------------------------------------------------------------------------
+*                            L I C E N S E
+*----------------------------------------------------------------------------------------
+* 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.
+*
+* \endinternal
+****************************************************************************************/
+
+/*
+ * An implementation of pvPortMalloc() and vPortFree() based on the memory pools module
+ * of MicroTBX. Note that this implementation allows allocated memory to be freed again.
+ *
+ * See heap_1.c, heap_2.c, heap_3.c and heap_4.c for alternative implementations, and the
+ * memory management pages of http://www.FreeRTOS.org for more information.
+ */
+
+
+/****************************************************************************************
+* Macro definitions
+***************************************************************************************/
+/** \brief Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
+ *         all the API functions to use the MPU wrappers.  That should only be done when
+ *         task.h is included from an application file.
+ */
+#define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
+
+
+/****************************************************************************************
+* Include files
+***************************************************************************************/
+#include "microtbx.h"
+#include "FreeRTOS.h"
+#include "task.h"
+
+/****************************************************************************************
+* Macro removal
+***************************************************************************************/
+/** \brief This macro is no longer needed after including task.h from a non-application
+ *         source file.
+ */
+#undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE
+
+/****************************************************************************************
+* Configuration check
+***************************************************************************************/
+#if (configSUPPORT_DYNAMIC_ALLOCATION == 0)
+#error This file must not be used if configSUPPORT_DYNAMIC_ALLOCATION is 0
+#endif
+
+
+/****************************************************************************************
+* External function prototype
+***************************************************************************************/
+extern void vApplicationMallocFailedHook(void);
+
+
+/************************************************************************************//**
+** \brief     Dynamically allocated memory on the heap.
+** \param     xWantedSize Size of the memory to allocate in bytes.
+****************************************************************************************/
+void * pvPortMalloc(size_t xWantedSize)
+{
+  void * result;
+
+  /* Prevent the scheduler from performing a context switch, while allocating memory. */
+  vTaskSuspendAll();
+
+  /* Attempt to allocate a block from the best fitting memory pool. */
+  result = TbxMemPoolAllocate(xWantedSize);
+  /* Was the allocation not successful? */
+  if (result == NULL)
+  {
+    /* The allocation failed. This can have two reasons:
+      *   1. A memory pool for the requested size hasn't yet been created.
+      *   2. The memory pool for the requested size has no more free blocks.
+      * Both situations can be solved by calling TbxMemPoolCreate(), as this
+      * function automatically extends a memory pool, if it was created before.
+      * Note that ther is not need to check the return value, because we will
+      * attempts to allocate again right afterwards. We can catch the error
+      * there in case the allocation fails.
+      */
+    (void)TbxMemPoolCreate(1U, xWantedSize);
+
+    /* Assuming sufficient heap was available, the memory pool was extended.
+      * Attempt to allocate the block again.
+      */
+    result = TbxMemPoolAllocate(xWantedSize);
+  }
+  /* Allow memory allocation tracing. */
+  traceMALLOC( result, xWantedSize );
+
+  /* Allow the scheduler to context switch again. */
+  (void)xTaskResumeAll();
+
+#if (configUSE_MALLOC_FAILED_HOOK == 1)
+  /* Was the allocation not successful? */
+  if( result == NULL )
+  {
+    /* Inform the application about this problem. Try increasing the heap size to
+     * prevent this from happining. It's macro TBX_CONF_HEAP_SIZE in tbx_conf.h.
+     */
+    vApplicationMallocFailedHook();
+  }
+#endif
+
+  /* Give the result back to the caller. */
+  return result;
+} /*** end of pvPortMalloc ***/
+
+
+/************************************************************************************//**
+** \brief     Releases previously allocated memory, allowing it to be reused.
+** \param     pv Pointer to the previously allocated memory. It must be a pointer value
+**            that was previously returned by pvPortMalloc().
+**
+****************************************************************************************/
+void vPortFree(void * pv)
+{
+  /* Give the block back to the memory pool. */
+  TbxMemPoolRelease(pv);
+} /*** end of vPortFree ***/
+
+
+/*********************************** end of tbxfreertos.c ******************************/

source/extra/freertos/tbxfreertos.h

@@ -0,0 +1,60 @@
+/************************************************************************************//**
+* \file         tbxfreertos.h
+* \brief        MicroTBX support for FreeRTOS.
+* \internal
+*----------------------------------------------------------------------------------------
+*                          C O P Y R I G H T
+*----------------------------------------------------------------------------------------
+*   Copyright (c) 2022 by Feaser     www.feaser.com     All rights reserved
+*
+*----------------------------------------------------------------------------------------
+*                            L I C E N S E
+*----------------------------------------------------------------------------------------
+* 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.
+*
+* \endinternal
+****************************************************************************************/
+#ifndef TBX_FREERTOS_H
+#define TBX_FREERTOS_H
+
+/*
+ * Include this file at the end of FreeRTOSConfig.h to add support of MicroTBX to
+ * FreeRTOS. The current implementation remamps the assertion macro to the one from
+ * MicroTBX.
+ */
+
+/****************************************************************************************
+* Include files
+***************************************************************************************/
+#include "microtbx.h"
+
+
+/****************************************************************************************
+* Macro definitions
+***************************************************************************************/
+#ifdef configASSERT
+#undef configASSERT
+#endif
+
+/** \brief Map the MicroTBX assertions macro to FreeRTOS. */
+#define configASSERT(x) TBX_ASSERT(x)
+
+
+#endif /* TBX_FREERTOS_H */
+/*********************************** end of tbxfreertos.h ******************************/

source/microtbx.h

@@ -73,7 +73,7 @@ extern "C" {
 #define TBX_VERSION_MINOR                        (9U)
 
 /** \brief Patch number of MicroTBX. */
-#define TBX_VERSION_PATCH                        (4U)
+#define TBX_VERSION_PATCH                        (5U)
 
 
 /****************************************************************************************