FreeRTOS Kernel V11.0.1

GitHub-FreeRTOS-Kernel-Home.url

@@ -5,4 +5,3 @@ URL=https://github.com/FreeRTOS/FreeRTOS-Kernel
 IconIndex=0
 IDList=
 HotKey=0
-

MISRA.md

@@ -0,0 +1,118 @@
+# MISRA Compliance
+
+FreeRTOS-Kernel conforms to [MISRA C:2012](https://www.misra.org.uk/misra-c)
+guidelines, with the deviations listed below. Compliance is checked with
+Coverity static analysis. Since the FreeRTOS kernel is designed for
+small-embedded devices, it needs to have a very small memory footprint and
+has to be efficient. To achieve that and to increase the performance, it
+deviates from some MISRA rules. The specific deviations, suppressed inline,
+are listed below.
+
+Additionally, [MISRA configuration file](examples/coverity/coverity_misra.config)
+contains project wide deviations.
+
+### Suppressed with Coverity Comments
+To find the violation references in the source files run grep on the source code
+with ( Assuming rule 8.4 violation; with justification in point 1 ):
+```
+grep 'MISRA Ref 8.4.1' . -rI
+```
+
+#### Rule 8.4
+
+MISRA C:2012 Rule 8.4: A compatible declaration shall be visible when an
+object or function with external linkage is defined.
+
+_Ref 8.4.1_
+ - pxCurrentTCB(s) is defined with external linkage but it is only referenced
+   from the assembly code in the port files. Therefore, adding a declaration in
+   header file is not useful as the assembly code will still need to declare it
+   separately.
+
+_Ref 8.4.2_
+ - xQueueRegistry is defined with external linkage because it is accessed by the
+   kernel unit tests. It is not meant to be directly accessed by the application
+   and therefore, not declared in a header file.
+
+#### Rule 8.6
+
+MISRA C:2012 Rule 8.6: An identifier with external linkage shall have exactly
+one external definition.
+
+_Ref 8.6.1_
+ - This rule prohibits an identifier with external linkage to have multiple
+   definitions or no definition. FreeRTOS hook functions are implemented in
+   the application and therefore, have no definition in the Kernel code.
+
+#### Rule 11.1
+MISRA C:2012 Rule 11.1: Conversions shall not be performed between a pointer to
+function and any other type.
+
+_Ref 11.1.1_
+ - The pointer to function is casted into void to avoid unused parameter
+   compiler warning when Stream Buffer's Tx and Rx Completed callback feature is
+   not used.
+
+#### Rule 11.3
+
+MISRA C:2012 Rule 11.3: A cast shall not be performed between a pointer to
+object type and a pointer to a different object type.
+
+_Ref 11.3.1_
+ - This rule prohibits casting a pointer to object into a pointer to a
+   different object because it may result in an incorrectly aligned pointer,
+   leading to undefined behavior. Even if the casting produces a correctly
+   aligned pointer, the behavior may be still undefined if the pointer is
+   used to access an object. FreeRTOS deliberately creates external aliases
+   for all the kernel object types (StaticEventGroup_t, StaticQueue_t,
+   StaticStreamBuffer_t, StaticTimer_t and StaticTask_t) for data hiding
+   purposes. The internal object types and the corresponding external
+   aliases are guaranteed to have the same size and alignment which is
+   checked using configASSERT.
+
+
+#### Rule 11.5
+
+MISRA C:2012 Rule 11.5: A conversion should not be performed from pointer to
+void into pointer to object.
+This rule prohibits conversion of a pointer to void into a pointer to
+object because it may result in an incorrectly aligned pointer leading
+to undefined behavior.
+
+_Ref 11.5.1_
+ - The memory blocks returned by pvPortMalloc() are guaranteed to meet the
+   architecture alignment requirements specified by portBYTE_ALIGNMENT.
+   The casting of the pointer to void returned by pvPortMalloc() is,
+   therefore, safe because it is guaranteed to be aligned.
+
+_Ref 11.5.2_
+ - The conversion from a pointer to void into a pointer to EventGroup_t is
+   safe because it is a pointer to EventGroup_t, which is returned to the
+   application at the time of event group creation for data hiding
+   purposes.
+
+_Ref 11.5.3_
+ - The conversion from a pointer to void in list macros for list item owner
+   is safe because the type of the pointer stored and retrieved is the
+   same.
+
+_Ref 11.5.4_
+ - The conversion from a pointer to void into a pointer to EventGroup_t is
+   safe because it is a pointer to EventGroup_t, which is passed as a
+   parameter to the xTimerPendFunctionCallFromISR API when the callback is
+   pended.
+
+_Ref 11.5.5_
+ - The conversion from a pointer to void into a pointer to uint8_t is safe
+   because data storage buffers are implemented as uint8_t arrays for the
+   ease of sizing, alignment and access.
+
+#### Rule 21.6
+
+MISRA C-2012 Rule 21.6: The Standard Library input/output functions shall not
+be used.
+
+_Ref 21.6.1_
+ - The Standard Library function snprintf is used in vTaskListTasks and
+   vTaskGetRunTimeStatistics APIs, both of which are utility functions only and
+   are not considered part of core kernel implementation.

Quick_Start_Guide.url

@@ -1,5 +1,5 @@
-[InternetShortcut]
-URL=https://www.FreeRTOS.org/FreeRTOS-quick-start-guide.html
-IDList=
-[{000214A0-0000-0000-C000-000000000046}]
-Prop3=19,2
+[InternetShortcut]
+URL=https://www.FreeRTOS.org/FreeRTOS-quick-start-guide.html
+IDList=
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,2

README.md

@@ -1,39 +1,182 @@
+[![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) repository, which contains pre-configured demo application projects under ```FreeRTOS/Demo``` directory. 
 
-The easiest way to use FreeRTOS is to start with one of the pre-configured demo application projects.  That way you will have the correct FreeRTOS source files included, and the correct include paths configured.  Once a demo application is building and executing you can remove the demo application files, and start to add in your own application source files.  See the [FreeRTOS Kernel Quick Start Guide](https://www.FreeRTOS.org/FreeRTOS-quick-start-guide.html) for detailed instructions and other useful links.
+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)
+repository, which contains pre-configured demo application projects under
+```FreeRTOS/Demo``` directory.
+
+The easiest way to use FreeRTOS is to start with one of the pre-configured demo
+application projects.  That way you will have the correct FreeRTOS source files
+included, and the correct include paths configured. Once a demo application is
+building and executing you can remove the demo application files, and start to
+add in your own application source files.  See the
+[FreeRTOS Kernel Quick Start Guide](https://www.FreeRTOS.org/FreeRTOS-quick-start-guide.html)
+for detailed instructions and other useful links.
+
+Additionally, for FreeRTOS kernel feature information refer to the
+[Developer Documentation](https://www.FreeRTOS.org/features.html),
+and [API Reference](https://www.FreeRTOS.org/a00106.html).
 
-Additionally, for FreeRTOS kernel feature information refer to the [Developer Documentation](https://www.FreeRTOS.org/features.html), and [API Reference](https://www.FreeRTOS.org/a00106.html).
+Also for contributing and creating a Pull Request please refer to
+[the instructions here](.github/CONTRIBUTING.md#contributing-via-pull-request).
 
 ### 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).
 
-## Cloning this repository
+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`:
+
+- Define the source and version/tag you want to use:
+
+```cmake
+FetchContent_Declare( freertos_kernel
+  GIT_REPOSITORY https://github.com/FreeRTOS/FreeRTOS-Kernel.git
+  GIT_TAG        main #Note: Best practice to use specific git-hash or tagged version
+)
+```
+
+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
+```
+
+- Add a freertos_config library (typically an INTERFACE library) The following assumes the directory structure:
+  - `include/FreeRTOSConfig.h`
+
+```cmake
+add_library(freertos_config INTERFACE)
+
+target_include_directories(freertos_config SYSTEM
+INTERFACE
+    include
+)
+
+target_compile_definitions(freertos_config
+  INTERFACE
+    projCOVERAGE_TEST=0
+)
+```
+
+In case you installed FreeRTOS-Kernel as a submodule, you will have to add it as a subdirectory:
+
+```cmake
+add_subdirectory(${FREERTOS_PATH})
+```
+
+- Configure the FreeRTOS-Kernel and make it available
+  - this particular example supports a native and cross-compiled build option.
+
+```cmake
+set( FREERTOS_HEAP "4" CACHE STRING "" FORCE)
+# Select the native compile PORT
+set( FREERTOS_PORT "GCC_POSIX" CACHE STRING "" FORCE)
+# Select the cross-compile PORT
+if (CMAKE_CROSSCOMPILING)
+  set(FREERTOS_PORT "GCC_ARM_CA9" CACHE STRING "" FORCE)
+endif()
+
+FetchContent_MakeAvailable(freertos_kernel)
+```
+
+- In case of cross compilation, you should also add the following to `freertos_config`:
+
+```cmake
+target_compile_definitions(freertos_config INTERFACE ${definitions})
+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 git@github.com: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 
+
+- 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
 is normally only used on very memory limited systems.
 
-- The ```./portable``` directory contains the files that are specific to a particular microcontroller and/or compiler. 
+- The ```./portable``` directory contains the files that are specific to a particular microcontroller and/or compiler.
 See the readme file in the ```./portable``` directory for more information.
 
 - The ```./include``` directory contains the real time kernel header files.
 
+- The ```./template_configuration``` directory contains a sample `FreeRTOSConfig.h` to help jumpstart a new project.
+See the [FreeRTOSConfig.h](examples/template_configuration/FreeRTOSConfig.h) file for instructions.
+
 ### Code Formatting
-FreeRTOS files are formatted using the "uncrustify" tool. The configuration file used by uncrustify can be found in the [FreeRTOS/FreeRTOS repository](https://github.com/FreeRTOS/FreeRTOS/blob/main/tools/uncrustify.cfg). 
 
-### Spelling
-*lexicon.txt* contains words that are not traditionally found in an English dictionary. It is used by the spellchecker to verify the various jargon, variable names, and other odd words used in the FreeRTOS code base. If your pull request fails to pass the spelling and you believe this is a mistake, then add the word to *lexicon.txt*. 
-Note that only the FreeRTOS Kernel source files are checked for proper spelling, the portable section is ignored.
+FreeRTOS files are formatted using the
+"[uncrustify](https://github.com/uncrustify/uncrustify)" tool.
+The configuration file used by uncrustify can be found in the
+[FreeRTOS/CI-CD-GitHub-Actions's](https://github.com/FreeRTOS/CI-CD-Github-Actions)
+[uncrustify.cfg](https://github.com/FreeRTOS/CI-CD-Github-Actions/tree/main/formatting)
+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
+spelling check. The config file for which can be found at [cspell.config.yaml](cspell.config.yaml)
+There is additionally a
+[cSpell plugin for VSCode](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
+that can be used as well.
+*[.cSpellWords.txt](.github/.cSpellWords.txt)* contains words that are not
+traditionally found in an English dictionary. It is used by the spellchecker
+to verify the various jargon, variable names, and other odd words used in the
+FreeRTOS code base are correct. If your pull request fails to pass the spelling
+and you believe this is a mistake, then add the word to
+*[.cSpellWords.txt](.github/.cSpellWords.txt)*. When adding a word please
+then sort the list, which can be done by running the bash command:
+`sort -u .cSpellWords.txt -o .cSpellWords.txt`
+Note that only the FreeRTOS-Kernel Source Files, [include](include),
+[portable/MemMang](portable/MemMang), and [portable/Common](portable/Common)
+files are checked for proper spelling, and formatting at this time.

cspell.config.yaml

@@ -0,0 +1,31 @@
+---
+$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json
+version: '0.2'
+# Allows things like stringLength
+allowCompoundWords: true
+
+# Read files not to spell check from the git ignore
+useGitignore: true
+
+#  Language settings for C
+languageSettings:
+  - caseSensitive: false
+    enabled: true
+    languageId: c
+    locale: "*"
+
+# Add a dictionary, and the path to the word list
+dictionaryDefinitions:
+  - name: freertos-words
+    path: '.github/.cSpellWords.txt'
+    addWords: true
+
+dictionaries:
+  - freertos-words
+
+# Paths and files to ignore
+ignorePaths:
+  - 'dependency'
+  - 'docs'
+  - 'ThirdParty'
+  - 'History.txt'

manifest.yml

@@ -1,4 +1,4 @@
 name : "FreeRTOS-Kernel"
-version: "v10.5.1"
+version: "v11.0.1"
 description: "FreeRTOS Kernel."
 license: "MIT"