Add FreeRTOS-Kernel source code

Author: JalonWong

freertos-cargo-build/src/lib.rs

@@ -9,7 +9,7 @@ use walkdir::WalkDir;
 /// The Kernel can be found at Github: https://github.com/FreeRTOS/FreeRTOS-Kernel
 ///
 /// When not set, you can use the Builder to specify the path
-const ENV_KEY_FREERTOS_SRC: &str = "FREERTOS_SRC";
+const ENV_KEY_FREERTOS_SRC: &str = "DEP_FREERTOS_KERNEL";
 
 /// The FREERTOS_CONFIG variable must point to the directory
 /// where the FreeRTOSConfig.h file is located for the current project.

freertos-rust-examples/build.rs

@@ -13,8 +13,6 @@ fn main() {
 
     let mut b = freertos_build::Builder::new();
 
-    b.freertos("FreeRTOS-Kernel/");
-
     // Windows example specific stuff.
     if target_family == "windows" {
         b.freertos_config("examples/win");

freertos-rust/FreeRTOS-Kernel/CMakeLists.txt

@@ -0,0 +1,7 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,2
+[InternetShortcut]
+URL=https://github.com/FreeRTOS/FreeRTOS-Kernel
+IconIndex=0
+IDList=
+HotKey=0

freertos-rust/FreeRTOS-Kernel/GitHub-FreeRTOS-Kernel-Home.url

@@ -0,0 +1,19 @@
+MIT License
+
+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.

freertos-rust/FreeRTOS-Kernel/History.txt

@@ -0,0 +1,145 @@
+# 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 version 2023.6.1. 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
+```
+
+#### Dir 4.7
+MISRA C:2012 Dir 4.7: If a function returns error information, then that error
+information shall be tested.
+
+_Ref 4.7.1_
+ - `taskENTER_CRITICAL_FROM_ISR` returns the interrupt mask and not any error
+    information. Therefore, there is no need test the return value.
+
+#### 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 14.3
+
+MISRA C-2012 Rule 14.3: Controlling expressions shall not be invariant.
+
+_Ref 14.3_
+ - The `configMAX_TASK_NAME_LEN` , `taskRESERVED_TASK_NAME_LENGTH` and `SIZE_MAX`
+   are evaluated to constants at compile time and may vary based on the build
+   configuration.
+
+#### Rule 18.1
+
+MISRA C-2012 Rule 18.1: A pointer resulting from arithmetic on a pointer operand
+shall address an element of the same array as that pointer operand.
+
+_Ref 18.1_
+ - Array access remains within bounds since either the null terminator in
+   the IDLE task name will break the loop, or the loop will break normally
+   if the array size is smaller than the IDLE task name length.
+
+#### 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.

freertos-rust/FreeRTOS-Kernel/LICENSE.md

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

freertos-rust/FreeRTOS-Kernel/MISRA.md

@@ -0,0 +1,192 @@
+[![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/Documentation/01-FreeRTOS-quick-start/01-Beginners-guide/02-Quick-start-guide)
+for detailed instructions and other useful links.
+
+Additionally, for FreeRTOS kernel feature information refer to the
+[Developer Documentation](https://www.freertos.org/Documentation/02-Kernel/02-Kernel-features/00-Developer-docs),
+and [API Reference](https://www.freertos.org/Documentation/02-Kernel/04-API-references/01-Task-creation/00-TaskHandle).
+
+Also for contributing and creating a Pull Request please refer to
+[the instructions here](.github/CONTRIBUTING.md#contributing-via-pull-request).
+
+**FreeRTOS-Kernel V11.1.0
+[source code](https://github.com/FreeRTOS/FreeRTOS-Kernel/tree/V11.1.0) is part
+of the
+[FreeRTOS 202406.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202406-LTS)
+release.**
+
+### 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`:
+
+- 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 [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
+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.
+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](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.
+
+## Third Party Tools
+Visit [this link](.github/third_party_tools.md) for detailed information about
+third-party tools with FreeRTOS support.