TI-POSIX User's Guide

Table of Contents

Overview

Select features of POSIX.1 and POSIX.4 are supported. These include thread, mutex, semaphore, read-write lock, barrier, key, message queue, clock, and timer. We provide a functional implementation of these features, but in some cases, not every aspect of the feature is supported.

Contributions to the POSIX implementation come from the compiler, the C run-time library, and the kernel. Integration with these contributors is provided by the TI-POSIX package.

In general terms, the compiler provides base type definitions, the C library provides language specific features, and TI-POSIX adds features which require kernel support. The following kernels are supported:

• TI-RTOS (also known as SYS/BIOS)
• FreeRTOS

This user’s guide provides information on using POSIX with the kernels listed above. For detailed documentation on POSIX, please use the following links:

• The Open Group POSIX Specification (IEEE Std 1003.1-2008)
• POSIX Programming, Lawrence Livermore National Laboratory

Building Your Program with TI-POSIX Support

There are three steps to using the TI-POSIX support in your program:

1. Use POSIX in your source code
2. Define your include path
3. Link your program with TI-POSIX

The details of each step are given in the following sections.

Use POSIX in your source code

Include the POSIX header files in your source code using the file names defined by the Open Group Specification. For example, use the following to create a POSIX thread:

#include <pthread.h>

void *start_fxn(void *arg);
pthread_t thread;
int arg = 1;

pthread_create(&thread, NULL, start_fxn, (void *)&arg);

In previous versions of SYS/BIOS, the POSIX header files were included using a package-qualified path name. This is no longer supported. Do not use the following include statements:

#include <ti/sysbios/posix/pthread.h>       INCORRECT
#include <ti/sysbios/posix/sys/types.h>     INCORRECT

Use the following include statements:

#include <pthread.h>
#include <sys/types.h>

Define Your Include Path

The include path is used to select which TI-POSIX implementation you use at compile time. The include path must reflect which tool chain is in play. We currently support three vendors. Set your include path according to which compiler you are using.

The compiler’s include directory is always added implicitly as the last entry on the include path. Thus, when an application includes a POSIX header file (e.g. #include <fcntl.h) which is not provided by TI-POSIX, it will get the one from the compiler. In some cases, the compiler does not provide the header file (e.g. #include <mqueue.h>) but it is provided by TI-POSIX. When a header file is provided by the compiler but needs additional content (e.g. errno.h), TI-POSIX will proxy the header file, include the same file from the compiler, and then add the necessary content.

For example, TI ARM compiler provides errno.h but does not define the ECONNREFUSED error code. When you compile your source code with TI-POSIX on the include path, this error code will be added.

#include <errno.h>

if (errno == ECONNREFUSED) {
    /* handle error */
}

When you compile this source file with TI-POSIX on the include path, the file include chain looks like this:

. /.../ti/posix/ccs/errno.h
.. /.../ti_cgt_arm/include/errno.h

After the compiler’s errno.h has been included, the TI-POSIX errno.h will reflect on the existing definitions, and if an error code is still missing, it will be added.

#ifndef ECONNREFUSED
#define ECONNREFUSED 111
#endif

This approach ensures all code remains compatible with existing error codes while only defining new error codes which are absent.

A similar approach is taken for other POSIX types and functions.

Link your program with TI-POSIX

The TI-POSIX implementation must be compiled and linked into your program. The details depend on which RTOS kernel you are using.

Using TI-POSIX with TI-RTOS

To use TI-POSIX with the TI-RTOS kernel, simply add the following line to your kernel or application configuration script:

xdc.useModule('ti.posix.tirtos.Settings');

This will modify the kernel build such that the TI-POSIX implementation is compiled into the kernel library.

The Settings module is used to configure the behavior of the TI-POSIX implementation on TI-RTOS.

Settings.enableMutexPriority

This is a Boolean parameter that defaults to false. If set to true, the priority inheritance and priority ceiling mutex protocols will be available, which also increases code size. If these mutex protocols are not needed, leave the parameter at its default value.

Example configuration:

var Settings = xdc.useModule('ti.posix.tirtos.Settings');
Settings.enableMutexPriority = true;

Using TI-POSIX with FreeRTOS

We recommend you compile the TI-POSIX implementation along with the FreeRTOS kernel sources into the kernel library. To do this, simply add the following source files to your kernel build. Note that some compilers require additional source files.

ti/posix/freertos/clock.c
ti/posix/freertos/memory.c
ti/posix/freertos/mqueue.c
ti/posix/freertos/pthread_barrier.c
ti/posix/freertos/pthread_cond.c
ti/posix/freertos/pthread.c
ti/posix/freertos/pthread_mutex.c
ti/posix/freertos/pthread_rwlock.c
ti/posix/freertos/sched.c
ti/posix/freertos/semaphore.c
ti/posix/freertos/sleep.c
ti/posix/freertos/timer.c

Texas Instruments Compiler

ti/posix/freertos/PTLS.c
ti/posix/freertos/aeabi_portable.c

IAR Compiler

ti/posix/freertos/Mtx.c

Note that Texas Instruments does not provide a FreeRTOS port for all devices. When a FreeRTOS port is not available for a particular device, you must use TI-POSIX with TI-RTOS.

Binary Compatibility between TI-RTOS and FreeRTOS

When Texas Instruments provides both TI-RTOS and FreeRTOS for a given device, TI-POSIX supports binary compatibility between both kernels. This is useful when you are shipping libraries which use TI-POSIX. Such a library can be linked with either kernel.

To achieve binary compatibility without binding to a kernel, the POSIX object definitions have been constructed using opaque objects. This allows the compiler to allocate the proper space without binding the source code to kernel header files. However, this approach incurs a memory cost as the object size must be large enough to contain the kernel object with the largest footprint, regardless which kernel is in play. Also, the opaque object definitions are sensitive to changes in the kernel objects.

Therefore, be mindful of the kernel versions. Binary compatibility is only supported between the kernel versions which ship in a given SDK. Binary compatibility is not guaranteed when upgrading to a kernel version not shipped in the SDK. Please consult the SDK documentation to see which kernel versions are supported in that SDK release.

System Error Numbers

The compiler provides a definition for the errno symbol. In a single-thread application, errno may be a global identifier declared with external linkage. But in a multi-thread application, errno is typically stored in thread-local storage (TLS). This requires integration with the kernel. Each compiler provides a different implementation.

The TI-POSIX implementation is partitioned by compiler vendor.

CCS Compiler

By default, the compiler provides one global identifier for errno. However, when _AEABI_PORTABILITY_LEVEL is defined, errno becomes a function call to __aeabi_errno_addr(). The errno.h provided by TI-POSIX asserts this definition before including the compiler errno.h. In addition, TI-POSIX provides an implementation of __aeabi_errno_addr() which uses TLS. Finally, the TI-POSIX errno.h defines error codes which are omitted from the compiler header file.

#define _AEABI_PORTABILITY_LEVEL 1

/* include compiler header file */
#include <../include/errno.h>

#ifndef EAGAIN
#define EAGAIN 11
#endif

The CCS ARM compiler does not provide any TLS support. Therefore, the implementation of __aeabi_errno_addr() is pure kernel implementation. However, the CCS C6x compiler does support TLS. With that compiler, the kernel integration makes use of the compiler TLS support functions.

GNU Compiler

TBD

IAR Compiler

TBD

Summary of functions supported in TI-POSIX

The following tables show the calling context for the POSIX functions supported in TI-POSIX. A supported function does not guarantee that all features of the API are available. Names with strike-through marks are not supported.

In the context of an RTOS, there are three execution contexts:

• main - in the function main(), before invoking the RTOS scheduler
• task - in a native RTOS thread (i.e. not from a pthread)
• interrupt - in an interrupt service routine

All supported POSIX functions may be invoked from a pthread.

A few POSIX functions may be invoked from main context or from task context (i.e. a native RTOS thread). These functions are typically used for creating a POSIX thread (i.e. pthread). The tables below indicate the valid calling context.

Although POSIX is a thread level API, a few functions have been implemented to support interrupt execution context. Keep in mind, that code written for interrupt context must always run to completion; do not make any blocking calls. These functions are listed below.

Thread Function Calling Context

• [1] The mutex must be using protocol PTHREAD_PRIO_PROTECT.
• [2] May change the priority of the calling thread if it owns the mutex.
• [3] Not available with minimal pthread configuration.

Miscellaneous Function Calling Context

Interrupt Calling Context

The following functions may be invoked from interrupt context. Note the non-blocking requirement.

Implementation Notes

The following sections provide some notes on the TI-POSIX implementation details.

Thread default stack size and thread default priority

int pthread_attr_init(pthread_attr_t *attr)

pthread_attr_init() initializes the pthread_attr_t object pointed to by attr with default values, which includes the stack size and thread priority.

On TI-RTOS, the default stack size is defined in the configuration script.

var Task = xdc.useModule('ti.sysbios.knl.Task');
Task.defaultStackSize = 0x800;

On FreeRTOS, the default stack size is computed as follows using values defined in FreeRTOSConfig.h and portmacro.h header files.

configPOSIX_STACK_SIZE * sizeof(portSTACK_TYPE)

Note that configPOSIX_STACK_SIZE is a custom symbol defined the FreeRTOSConfig.h header file which is shipped in the SDK. The portmacro.h header file is shipped in the FreeRTOS distribution.

The priority is set to 1, which is the lowest priority allowed for a task other than the Idle task, which is priority 0.

Thread scheduling policy

int pthread_getschedparam(pthread_t pthread, int *policy, struct sched_param *param)
int pthread_setschedparam(pthread_t pthread, int policy, const struct sched_param *param)

The RTOS kernel uses a priority-based scheduler. The policy parameter is ignored in these functions.

TI-POSIX on FreeRTOS

Best effort has been made to provide the same support between TI-RTOS and FreeRTOS. However, there are some exceptions, which are noted here.

There is no way to pass a stack to xTaskCreate()

pthread_attr_setstack() - not supported on FreeRTOS

Priority inheritance for mutexes is handled by FreeRTOS. The priority of a task that owns a mutex is temporarily raised, if a task of higher priority attempts to acquire the mutex. Therefore, mutex protocols are not supported on FreeRTOS.

pthread_mutexattr_getprotocol() - not supported for FreeRTOS
pthread_mutexattr_setprotocol() - not supported for FreeRTOS
pthread_mutexattr_getprioceiling() - not supported for FreeRTOS
pthread_mutexattr_setprioceiling() - not supported for FreeRTOS

Only CLOCK_REALTIME is supported with clock_settime().

timer_settime() - this is a blocking call, unlike on TI-RTOS

Task cleanup is done by the Idle task in FreeRTOS. If pthreads are deleted, make sure the Idle task gets a chance to run to free allocated memory for the deleted thread.