Sample FreeRTOSConfig.h and template port (#812)

* config file experiments

* adding a config file for an example

* Added a template port and updated the CMakeLists

* template and default configuration build

* finalising the sample FreeRTOSConfig.h header file

* removed .config hidden file

* further reductions in the template port

* Uncrustify: triggered by comment.

* Uncrustify: triggered by comment.

* minor readme updates

* fixed spelling error in HTTP

* fixed a type and added a link to the sample readme

* uncrustified FreeRTOSConfig.h

* Uncrustify: triggered by comment.

* Revert "Uncrustify: triggered by comment."

This reverts commit e534f46.

* Revert "Revert "Uncrustify: triggered by comment.""

This reverts commit c9058dd.

* excluding the FreeRTOSConfig.h from copyright+license check because this file is intended to be incorporated into user code

* Removed the copyright and license from the template files

* put license copy in the template and sample files

* Uncrustify: triggered by comment.

---------

Co-authored-by: GitHub Action <[email protected]>

Author: n9wxu

.github/scripts/kernel_checker.py

@@ -38,6 +38,7 @@
     'Makefile',
     '.DS_Store',
     'cspell.config.yaml'
+    'FreeRTOSConfig.h'
 ]
 
 KERNEL_IGNORED_EXTENSIONS = [
@@ -92,7 +93,8 @@
     r'.*portable/ThirdParty/xClang/XCOREAI/*',
     r'.*IAR/ARM_C*',
     r'.*IAR/78K0R/*',
-    r'.*CCS/MSP430X/*'
+    r'.*CCS/MSP430X/*',
+    r'.*portable/template/*'
 ]
 
 KERNEL_THIRD_PARTY_PATTERNS = [

CMakeLists.txt

@@ -196,6 +196,7 @@ if(NOT FREERTOS_PORT)
         " SOFTUNE_MB91460                  - Compiler: Softune       Target: MB91460\n"
         " SOFTUNE_MB96340                  - Compiler: Softune       Target: MB96340\n"
         " TASKING_ARM_CM4F                 - Compiler: Tasking       Target: ARM Cortex-M4 with FPU\n"
+        " TEMPLATE                         - Compiler: HOST          Target: None\n"
         " CDK_THEAD_CK802                  - Compiler: CDK           Target: T-head CK802\n"
         " XCC_XTENSA                       - Compiler: XCC           Target: Xtensa\n"
         " WIZC_PIC18                       - Compiler: WizC          Target: PIC18")

README.md

@@ -1,6 +1,8 @@
 [![CMock Unit Tests](https://github.com/FreeRTOS/FreeRTOS-Kernel/actions/workflows/unit-tests.yml/badge.svg?branch=main&event=push)](https://github.com/FreeRTOS/FreeRTOS-Kernel/actions/workflows/unit-tests.yml?query=branch%3Amain+event%3Apush+workflow%3A%22CMock+Unit+Tests%22++)
 [![codecov](https://codecov.io/gh/FreeRTOS/FreeRTOS-Kernel/badge.svg?branch=main)](https://codecov.io/gh/FreeRTOS/FreeRTOS-Kernel)
+
 ## Getting started
+
 This repository contains FreeRTOS kernel source/header files and kernel
 ports only. This repository is referenced as a submodule in
 [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS)
@@ -20,13 +22,15 @@ Additionally, for FreeRTOS kernel feature information refer to the
 and [API Reference](https://www.FreeRTOS.org/a00106.html).
 
 ### Getting help
+
 If you have any questions or need assistance troubleshooting your FreeRTOS project,
 we have an active community that can help on the
 [FreeRTOS Community Support Forum](https://forums.freertos.org).
 
 ## To consume FreeRTOS-Kernel
 
 ### Consume with CMake
+
 If using CMake, it is recommended to use this repository using FetchContent.
 Add the following into your project's main or a subdirectory's `CMakeLists.txt`:
 
@@ -42,12 +46,13 @@ FetchContent_Declare( freertos_kernel
 In case you prefer to add it as a git submodule, do:
 
 ```bash
-$ git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel.git <path of the submodule>
-$ git submodule update --init
+git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel.git <path of the submodule>
+git submodule update --init
 ```
 
 - Add a freertos_config library (typically an INTERFACE library) The following assumes the directory structure:
   - `include/FreeRTOSConfig.h`
+
 ```cmake
 add_library(freertos_config INTERFACE)
 
@@ -93,15 +98,19 @@ target_compile_options(freertos_config INTERFACE ${options})
 ### Consuming stand-alone - Cloning this repository
 
 To clone using HTTPS:
+
 ```
 git clone https://github.com/FreeRTOS/FreeRTOS-Kernel.git
 ```
+
 Using SSH:
+
 ```
 git clone [email protected]:FreeRTOS/FreeRTOS-Kernel.git
 ```
 
 ## Repository structure
+
 - The root of this repository contains the three files that are common to
 every port - list.c, queue.c and tasks.c.  The kernel is contained within these
 three files.  croutine.c implements the optional co-routine functionality - which
@@ -112,7 +121,11 @@ See the readme file in the ```./portable``` directory for more information.
 
 - The ```./include``` directory contains the real time kernel header files.
 
+- The ```./sample_configuration``` directory contains a sample `FreeRTOSConfig.h` to help jumpstart a new project.
+See the [FreeRTOSConfig.h](sample_configuration/FreeRTOSConfig.h) file for instructions.
+
 ### Code Formatting
+
 FreeRTOS files are formatted using the
 "[uncrustify](https://github.com/uncrustify/uncrustify)" tool.
 The configuration file used by uncrustify can be found in the
@@ -121,26 +134,31 @@ The configuration file used by uncrustify can be found in the
 file.
 
 ### Line Endings
+
 File checked into the FreeRTOS-Kernel repository use unix-style LF line endings
 for the best compatibility with git.
 
 For optimal compatibility with Microsoft Windows tools, it is best to enable
 the git autocrlf feature. You can enable this setting for the current
 repository using the following command:
+
 ```
 git config core.autocrlf true
 ```
 
 ### Git History Optimizations
+
 Some commits in this repository perform large refactors which touch many lines
 and lead to unwanted behavior when using the `git blame` command. You can
 configure git to ignore the list of large refactor commits in this repository
 with the following command:
+
 ```
 git config blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
 ### Spelling and Formatting
+
 We recommend using [Visual Studio Code](https://code.visualstudio.com),
 commonly referred to as VSCode, when working on the FreeRTOS-Kernel.
 The FreeRTOS-Kernel also uses [cSpell](https://cspell.org/) as part of its

portable/CMakeLists.txt

@@ -8,7 +8,11 @@ endif()
 # FreeRTOS internal cmake file. Do not use it in user top-level project
 
 add_library(freertos_kernel_port STATIC
-    # 16-Bit DOS ports for BCC
+    # TEMPLATE Port
+    $<$<STREQUAL:${FREERTOS_PORT},TEMPLATE>:
+        template/port.c>
+
+        # 16-Bit DOS ports for BCC
     $<$<STREQUAL:${FREERTOS_PORT},BCC_16BIT_DOS_FLSH186>:
         BCC/16BitDOS/common/portcomn.c
         BCC/16BitDOS/Flsh186/port.c>
@@ -708,7 +712,10 @@ if( FREERTOS_PORT MATCHES "GCC_ARM_CM(3|4)_MPU" OR
 endif()
 
 target_include_directories(freertos_kernel_port PUBLIC
-    # 16-Bit DOS ports for BCC
+    # TEMPLATE Port
+    $<$<STREQUAL:${FREERTOS_PORT},TEMPLATE>:${CMAKE_CURRENT_LIST_DIR}/template>
+
+        # 16-Bit DOS ports for BCC
     $<$<STREQUAL:${FREERTOS_PORT},BCC_16BIT_DOS_FLSH186>:
         ${CMAKE_CURRENT_LIST_DIR}/BCC/16BitDOS/common
         ${CMAKE_CURRENT_LIST_DIR}/BCC/16BitDOS/Flsh186>

portable/template/port.c

@@ -0,0 +1,69 @@
+/*
+ * FreeRTOS Kernel <DEVELOPMENT BRANCH>
+ * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * 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
+ *
+ */
+
+#include "FreeRTOS.h"
+#include "task.h"
+
+BaseType_t xPortStartScheduler( void )
+{
+    return pdTRUE;
+}
+
+void vPortEndScheduler( void )
+{
+}
+
+StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
+                                     TaskFunction_t pxCode,
+                                     void * pvParameters )
+{
+    return NULL;
+}
+
+void vPortYield( void )
+{
+    /* Save the current Context */
+    /* Switch to the highest priority task that is ready to run. */
+    vTaskSwitchContext();
+    /* Start executing the task we have just switched to. */
+}
+
+static void prvTickISR( void )
+{
+    /* Interrupts must have been enabled for the ISR to fire, so we have to
+     * save the context with interrupts enabled. */
+
+    /* Maintain the tick count. */
+    if( xTaskIncrementTick() != pdFALSE )
+    {
+        /* Switch to the highest priority task that is ready to run. */
+        vTaskSwitchContext();
+    }
+
+    /* start executing the new task */
+}

portable/template/portmacro.h

@@ -0,0 +1,114 @@
+/*
+ * FreeRTOS Kernel <DEVELOPMENT BRANCH>
+ * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * 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
+ *
+ */
+#ifndef PORTMACRO_H
+#define PORTMACRO_H
+
+/*-----------------------------------------------------------
+ * Port specific definitions.
+ *
+ * The settings in this file configure FreeRTOS correctly for the
+ * given hardware and compiler.
+ *
+ * These settings should not be altered.
+ *-----------------------------------------------------------
+ */
+
+/* Type definitions. */
+#define portCHAR                 char
+#define portFLOAT                float
+#define portDOUBLE               double
+#define portLONG                 long
+#define portSHORT                int
+#define portSTACK_TYPE           uint8_t
+#define portBASE_TYPE            char
+
+#define portSTACK_GROWTH         ( -1 )
+#define portBYTE_ALIGNMENT       4
+#define portPOINTER_SIZE_TYPE    size_t
+typedef portSTACK_TYPE   StackType_t;
+typedef signed char      BaseType_t;
+typedef unsigned char    UBaseType_t;
+
+#if ( configTICK_TYPE_WIDTH_IN_BITS == TICK_TYPE_WIDTH_16_BITS )
+    typedef uint16_t     TickType_t;
+    #define portMAX_DELAY    ( TickType_t ) 0xffff
+#elif ( configTICK_TYPE_WIDTH_IN_BITS == TICK_TYPE_WIDTH_32_BITS )
+    typedef uint32_t     TickType_t;
+    #define portMAX_DELAY    ( TickType_t ) 0xffffffffUL
+#else
+    #error configTICK_TYPE_WIDTH_IN_BITS set to unsupported tick type width.
+#endif
+
+/* Architecture specific optimisations. */
+#ifndef configUSE_PORT_OPTIMISED_TASK_SELECTION
+    #define configUSE_PORT_OPTIMISED_TASK_SELECTION    1
+#endif
+
+#if configUSE_PORT_OPTIMISED_TASK_SELECTION == 1
+
+/* Check the configuration. */
+    #if ( configMAX_PRIORITIES > 32 )
+        #error configUSE_PORT_OPTIMISED_TASK_SELECTION can only be set to 1 when configMAX_PRIORITIES is less than or equal to 32.  It is very rare that a system requires more than 10 to 15 difference priorities as tasks that share a priority will time slice.
+    #endif
+
+/* Store/clear the ready priorities in a bit map. */
+    #define portRECORD_READY_PRIORITY( uxPriority, uxReadyPriorities )    ( uxReadyPriorities ) |= ( 1UL << ( uxPriority ) )
+    #define portRESET_READY_PRIORITY( uxPriority, uxReadyPriorities )     ( uxReadyPriorities ) &= ~( 1UL << ( uxPriority ) )
+
+/*-----------------------------------------------------------*/
+
+    #define portGET_HIGHEST_PRIORITY( uxTopPriority, uxReadyPriorities ) \
+    {                                                                    \
+        uxTopPriority = 0;                                               \
+    }                                                                    \
+    while( 0 )
+
+#endif /* configUSE_PORT_OPTIMISED_TASK_SELECTION */
+
+#define portDISABLE_INTERRUPTS()   \
+    { /* Disable the interrupts */ \
+    }
+#define portENABLE_INTERRUPTS()   \
+    { /* Enable the interrupts */ \
+    }
+
+#define portENTER_CRITICAL()                                             \
+    { /* preserve current interrupt state and then disable interrupts */ \
+    }
+#define portEXIT_CRITICAL()                              \
+    { /* restore previously preserved interrupt state */ \
+    }
+
+extern void vPortYield( void );
+#define portYIELD()                                           vPortYield()
+
+/* Task function macros as described on the FreeRTOS.org WEB site. */
+#define portTASK_FUNCTION_PROTO( vFunction, pvParameters )    void vFunction( void * pvParameters )
+#define portTASK_FUNCTION( vFunction, pvParameters )          void vFunction( void * pvParameters )
+
+#endif /* PORTMACRO_H */