embTCP - with Integrated FreeRTOS

On this page:

  1. Introduction

  2. FreeRTOS Included in embTCP



Introduction


embTCP with FreeRTOS

The embTCP libraries from InterNiche Technologies, Inc. are built with FreeRTOS V7.0.1 included in the library. It is not necessary to have knowledge of FreeRTOS in order to use embTCP, just follow the usage instructions that accompany your purchased embTCP package.

This page provides additional, and optional, introductory information on FreeRTOS itself, and specifically the version of FreeRTOS included in embTCP. It is provided for the convenience of those embTCP users who wish to go further than just using the TCP/IP related functionality, and make their own direct use of the integrated FreeRTOS component.


About FreeRTOS

FreeRTOS is a real time kernel designed specifically for use on microcontrollers. Supporting more than 28 different microcontroller cores, and being downloaded more than 80,000 times per year, FreeRTOS has become a cross platform, market leading, solution for microcontroller applications.

FreeRTOS can be used in commercial applications without any requirement to expose your proprietary source code. Information on how FreeRTOS is licensed can be found on the License Details page of the FreeRTOS.org web site.


FreeRTOS Reference Information

FreeRTOS is completely documented and distributed on the http://www.FreeRTOS.org web site, which includes a quick start guide to assist orientation. This page highlights the API functions that are available in FreeRTOS V7.0.1.

Additional educational resources, including training, tutorial books, and reference manuals, are also available.



FreeRTOS Included in embTCP


Library Files, Source Files, and Header Files

embTCP is supplied as a pre-built library that can be linked into your source code project. The embTCP library includes a pre-built version of FreeRTOS V7.0.1, and is supplied with the relevant FreeRTOS V7.0.1 source files. Source code for all the various versions of FreeRTOS can also be downloaded directly from SourceForge.

Having FreeRTOS included in the embTCP library itself means it is not necessary to build the FreeRTOS source files along with your application code. To use the embTCP and FreeRTOS functionality, it is only necessary to:

  1. Include the supplied, pre-built, embTCP library in your project.
  2. Ensure the supplied FreeRTOS header files can be located by your compiler's pre-processor (store the header files in a convenient directory, then ensure the chosen directory is included in the compilers 'include' path).
If desired, you can update the version of FreeRTOS used by embTCP, or include additional FreeRTOS functionality, by including alternative FreeRTOS source files in your project. The linker will then use the version included in your project rather than the version it finds in the embTCP library. Note however, that using embTCP with any build or version of FreeRTOS other than that directly included in the embTCP library will result in usage of the embTCP library in a configuration that has not been tested by InterNiche Technologies, Inc..


Configuring FreeRTOS

embTCP is delivered with a FreeRTOSConfig.h header file that has been customised by InterNiche Technologies, Inc., and used to build the embTCP library. Ensure to read the comments in the delivered FreeRTOSConfig.h before editing the file. Following are some notes specific to the used and delivered FreeRTOSConfig.h header file:


Memory Management

The RTOS kernel has to allocate RAM each time a task, queue, semaphore or timer is created, all of which are normally created during system start up and initialisation. One embedded / real time system can have very different RAM and timing requirements to another - so a single RAM allocation algorithm will only ever be appropriate for a subset of applications.

To get around this problem, the FreeRTOS memory allocation API is included in the RTOS portable layer. Therefore, when FreeRTOS requires RAM, instead of calling malloc() directly, it instead calls pvPortMalloc(). Likewise, when RAM is released, instead of calling free() directly, FreeRTOS instead calls vPortFree(). An application that uses FreeRTOS can define pvPortMalloc() and vPortFree() as appropriate for their application. FreeRTOS itself provides three example implementations - each of which are suitable for different usage scenarios. embTCP make use of what is delivered with FreeRTOS as the heap_3.c example implementation. heap_3.c just provides a mutual exclusion wrapper around the standard C library malloc() and free() functions. Therefore, a build environment that uses the embTCP library must be configured to provide standard C library malloc() and free() implementations.


Additional FreeRTOS related embTCP Usage Notes

Every FreeRTOS port has at least one demo application, and every FreeRTOS demo application includes usage notes specific to the port. Please ensure to read the usage notes for the port being used. They contain, among other things, details on how to write FreeRTOS compatible interrupt service routines.


FreeRTOS Application Programming Interface (API)

The full FreeRTOS API is documented on the FreeRTOS.org web site. The embTCP library includes the subset of the API functions listed below.

Note that, although the source files that implement FreeRTOS's software timer and co-routine functionality are provided with the embTCP library, the entire software timer and co-routine API is omitted.

The Coding Standard and Style Guide page on the FreeRTOS web site describes the API function naming convention.





Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.