POSIX Facilities
INCLUDE_POSIX_PTHREAD_SCHEDULE, and INCLUDE_PTHREAD_CPUTIME
9 POSIX Facilities .13 POSIX Threads
9.13 POSIX Threads
POSIX threads (also known as pthreads) are similar to VxWorks tasks, but with additional characteristics. In VxWorks pthreads are implemented on top of native tasks, but maintain pthread IDs that differ from the IDs of the underlying tasks.
The main reasons for including POSIX thread support in VxWorks are the following:
■ For porting POSIX applications to VxWorks.
■ To make use of the POSIX thread scheduler in real-time processes (including concurrent scheduling policies).
For information about POSIX thread scheduler, see 9.15 POSIX and VxWorks Scheduling, p.189.
9.13.1 POSIX Thread Stack Guard Zones
Execution-stack guard zones can be used with POSIX threads. A SIGSEGV signal is then generated when a stack overflow or underflow occurs.
Execution stack overflow protection can be provided for individual pthreads with a call to the pthread_attr_setguardsize( ) routine before the pthread is created. By default the size of a pthread guard zone is one architecture-specific page
(VM_PAGESIZE). It can be set to any value with the pthread_attr_setguardsize( ) routine, but the actual size is always rounded to a multiple of a number of memory pages.
The size of the guard area must be set in a pthread attribute before a thread is created that uses the attribute. Once a thread is created, the size of its stack guard cannot be changed. If the size attribute is changed after the thread is created, it does not affect the thread that has already been created, but it does apply to the next thread created that uses the attribute. If a pthread's stack is created with guard protection, the pthread_attr_getguardsize( ) routine can be used to get the size of the guard zone.
Note that the default overflow guard zone size for pthreads is independent of the size of the execution stack overflow guard zone for tasks (with is defined globally for tasks, and provided for them with the INCLUDE_RTP component).
Also note that pthreads are provided with execution stack underflow guard zones by default (they are provided for both pthreads and tasks by the INCLUDE_RTP component).
For information about task guard zones, see 6.5.5 Task Stack, p.112.
! CAUTION: POSIX thread APIs must not be invoked in the context of custom system call handlers—either directly by system call handler itself or by any routine that the system call handler may use. Use of POSIX thread APIs in the context of system call handlers produces unspecified behavior and execution failure. For
information about custom system calls, see the VxWorks Kernel Programmer’s Guide.
9.13.2 POSIX Thread Attributes
A major difference between VxWorks tasks and POSIX threads is the way in which options and settings are specified. For VxWorks tasks these options are set with the task creation API, usually taskSpawn( ).
POSIX threads, on the other hand, have characteristics that are called attributes.
Each attribute contains a set of values, and a set of access routines to retrieve and set those values. You specify all pthread attributes before pthread creation in the attributes object pthread_attr_t. In a few cases, you can dynamically modify the attribute values of a pthread after its creation.
9.13.3 VxWorks-Specific Pthread Attributes
The VxWorks implementation of POSIX threads provides two additional pthread attributes (which are POSIX extensions)—pthread name and pthread options—as well as routines for accessing them.
Pthread Name
While POSIX threads are not named entities, the VxWorks tasks upon which they are based are named. By default the underlying task elements are named
pthrNumber (for example, pthr3). The number part of the name is incremented each time a new thread is created (with a roll-over at 2^32 - 1). It is, however, possible to name these tasks using the thread name attribute.
■ Attribute Name: threadname
■ Possible Values: a null-terminated string of characters
■ Default Value: none (the default naming policy is used)
■ Access Functions (VxWorks-specific POSIX extensions):
pthread_attr_setname( ) and pthread_attr_getname( )
Pthread Options
POSIX threads are agnostic with regard to target architecture. Some VxWorks tasks, on the other hand, may be created with specific options in order to benefit from certain features of the architecture. For example, for the Altivec-capable PowerPC architecture, tasks must be created with the VX_ALTIVEC_TASK in order to make use of the Altivec processor. The pthread options attribute can be used to set such options for the VxWorks task upon which the POSIX thread is based.
■ Attribute Name: threadoptions
■ Possible Values: the same as the VxWorks task options. See taskLib.h
■ Default Value: none (the default task options are used)
■ Access Functions (VxWorks-specific POSIX extensions):
pthread_attr_setopt( ) and pthread_attr_getopt( )
9.13.4 Specifying Attributes when Creating Pthreads
The following examples create a pthread using the default attributes and use explicit attributes.
9 POSIX Facilities 9.13 POSIX Threads
Example 9-2 Creating a pthread Using Explicit Scheduling Attributes
pthread_t tid;
pthread_attr_t attr;
int ret;
pthread_attr_init(&attr);
/* set the inheritsched attribute to explicit */
pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);
/* set the schedpolicy attribute to SCHED_FIFO */
pthread_attr_setschedpolicy(&attr, SCHED_FIFO);
/* create the pthread */
ret = pthread_create(&tid, &attr, entryFunction, entryArg);
Example 9-3 Creating a pthread Using Default Attributes
pthread_t tid;
int ret;
/* create the pthread with NULL attributes to designate default values */
ret = pthread_create(&tid, NULL, entryFunction, entryArg);
Example 9-4 Designating Your Own Stack for a pthread
pthread_t threadId;
pthread_attr_t attr;
void * stackaddr = NULL;
int stacksize = 0;
/* initialize the thread's attributes */
pthread_attr_init (&attr);
/*
* Allocate memory for a stack region for the thread. Malloc() is used * for simplification since a real-life case is likely to use memPartAlloc() * on the kernel side, or mmap() on the user side.
*/
stacksize = 2 * 4096 /* let's allocate two pages */ stackaddr = malloc (stacksize);
if (stackbase == NULL) {
printf ("FAILED: mystack: malloc failed\n");
return (-1);
}
/* set the stackaddr attribute */
pthread_attr_setstackaddr (&attr, stackaddr);
/* set the stacksize attribute */
pthread_attr_setstacksize (&attr, stacksize);
/* set the schedpolicy attribute to SCHED_FIFO */
pthread_attr_setschedpolicy (&attr, SCHED_FIFO);
/* create the pthread */
ret = pthread_create (&threadId, &attr, mystack_thread, 0);
9.13.5 POSIX Thread Creation and Management
VxWorks provides many POSIX thread routines. Table 9-8 lists a few that are directly relevant to pthread creation or execution. See the VxWorks API reference for information about the other routines, and more details about all of them.
9.13.6 POSIX Thread Attribute Access
The POSIX attribute-access routines are described in Table 9-9. The VxWorks-specific POSIX extension routines are described in section 9.13.3 VxWorks-Specific Pthread Attributes, p.180.
Table 9-8 POSIX Thread Routines
Routine Description
pthread_create( ) Create a pthread.
pthread_cancel( ) Cancel the execution of a pthread
pthread_detach( ) Detach a running pthread so that it cannot be joined by another pthread.
pthread_join( ) Wait for a pthread to terminate.
pthread_getschedparam( ) Dynamically set value of scheduling priority attribute.
pthread_setschedparam( ) Dynamically set scheduling priority and policy parameter.
pthread_setschedprio( ) Dynamically set scheduling priority parameter.
sched_get_priority_max( ) Get the maximum priority that a pthread can get.
sched_get_priority_min( ) Get the minimum priority that a pthread can get.
sched_rr_get_interval( ) Get the time quantum of execution of the round-robin policy.
sched_yield( ) Relinquishes the CPU.
pthread_getconcurrency( ) Get level of concurrency.
In VxWorks this routine does nothing.
pthread_setconcurrency( ) Set level of concurrency
In VxWorks this routine does nothing.
Table 9-9 POSIX Thread Attribute-Access Routines
Routine Description
pthread_attr_getstacksize( ) Get value of the stack size attribute.
pthread_attr_setstacksize( ) Set the stack size attribute.
pthread_attr_getstackaddr( ) Get value of stack address attribute.
pthread_attr_setstackaddr( ) Set value of stack address attribute.