embTCP - with Integrated FreeRTOS
On this page:
-
Introduction
- 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:
- Include the supplied, pre-built, embTCP library in your project.
- 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).
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:- The maximum number of task priorities has been set to eight. That means tasks can be assigned priorities between zero and seven. Zero is the lowest priority.
- The queue registry has space for ten registered queues (and semaphores). The queue registry is only needed when FreeRTOS is used with a FreeRTOS kernel aware debugger.
- The tick hook function is used by the embTCP TCP/IP functionality, so is not readily available to the application. If the application provides its own tick hook function, then the application writer must ensure that is also calls the appropriate TCP/IP processing functions.
- The tick interrupt frequency is set to 100Hz, and should not be modified.
- Stack overflow protection is included - method two is used. It is therefore necessary to provide a stack overflow hook function.
- Counting semaphore, idle hook, and malloc failed hook functionality is excluded from the library.
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.
-
Task Creation Functions
-
Task Control Functions
- vTaskDelay()
- vTaskDelayUntil()
- uxTaskPriorityGet()
- vTaskPrioritySet()
- vTaskSuspend()
- vTaskResume()
- xTaskResumeFromISR()
-
Task Utility Functions
- xTaskGetCurrentTaskHandle()
- uxTaskGetStackHighWaterMark()
- xTaskGetTickCount()
- xTaskGetTickCountFromISR()
- xTaskGetSchedulerState()
- uxTaskGetNumberOfTasks()
- vTaskList()
- vTaskSetApplicationTag()
- xTaskCallApplicationTaskHook()
-
Kernel Control Functions
- taskYIELD()
- taskENTER_CRITICAL()
- taskEXIT_CRITICAL()
- taskDISABLE_INTERRUPTS()
- taskENABLE_INTERRUPTS()
- vTaskStartScheduler()
- vTaskEndScheduler()
- vTaskSuspendAll()
- vTaskResumeAll()
-
Queue Functions
- uxQueueMessagesWaiting()
- xQueueCreate()
- vQueueDelete()
- xQueueSend()
- xQueueSendToBack()
- xQueueSendToFront()
- xQueueReceive()
- xQueuePeek()
- xQueueSendFromISR()
- xQueueSendToBackFromISR()
- xQueueSendToFrontFromISR()
- xQueueReceiveFromISR()
- vQueueAddToRegistry()
- vQueueUnregisterQueue()
-
Semaphore/Mutex Functions
- vSemaphoreCreateBinary()
- xSemaphoreCreateCounting()
- xSemaphoreCreateMutex()
- xSemaphoreCreateRecursiveMutex()
- xSemaphoreTake()
- xSemaphoreTakeRecursive()
- xSemaphoreGive()
- xSemaphoreGiveRecursive()
- xSemaphoreGiveFromISR()