pthreadlib.c

VXWORKS源代码

/* pthreadLib.c - POSIX 1003.1c thread library interfaces */

/* Copyright 1984-2001 Wind River Systems, Inc.  */
/* Copyright (c) 1995 by Dot4, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01i,03may02,gls  updated pthread_attr_setstackaddr documentaion (SPR #76769)
01h,22apr02,gls  removed references to AE (SPR #75799)
01g,05nov01,gls  merged in code from AE
01f,24oct01,jgn  correct scheduling policy inheritance (SPR #71125)
		 (docs update - main change in _pthreadLib.c)
01e,04apr01,pfl  doc update (SPR #63976)
01d,11sep00,jgn  split into user and system level components (SPR #33375)
01c,22aug00,jgn  remove dependency on TCB spare4 field (SPR #33815) +
		 fix some memory handling & memory leaks (SPR #33554) +
		 move readdir_r() to dirLib.c (SPR #34056)
01b,15aug00,jgn  add bug fixes from DOT-4
01a,17jul00,jgn  created from DOT-4 version 1.17
*/

/*
DESCRIPTION
This library provides an implementation of POSIX 1003.1c threads for VxWorks.
This provides an increased level of compatibility between VxWorks applications
and those written for other operating systems that support the POSIX threads
model (often called <pthreads>).

VxWorks is a task based operating system, rather than one implementing the
process model in the POSIX sense. As a result of this, there are a few
restrictions in the implementation, but in general, since tasks are roughly
equivalent to threads, the <pthreads> support maps well onto VxWorks.
The restrictions are explained in more detail in the following paragraphs.

CONFIGURATION
To add POSIX threads support to a system, the component INCLUDE_POSIX_PTHREADS
must be added.

Threads support also requires the POSIX scheduler to be included (see
schedPxLib for more detail). 

THREADS
A thread is essentially a VxWorks task, with some additional characteristics.
The first is detachability, where the creator of a thread can optionally block
until the thread exits. The second is cancelability, where one task or thread
can cause a thread to exit, possibly calling cleanup handlers. The next is
private data, where data private to a thread is created, accessed and deleted
via keys. Each thread has a unique ID. A thread's ID is different than it's
VxWorks task ID.

MUTEXES
Included with the POSIX threads facility is a mutual exclusion facility, or
<mutex>. These are functionally similar to the VxWorks mutex semaphores (see
'semMLib' for more detail), and in fact are implemented using a VxWorks
mutex semaphore. The advantage they offer, like all of the POSIX libraries,
is the ability to run software designed for POSIX platforms under VxWorks.

There are two types of locking protocols available, PTHREAD_PRIO_INHERIT and
PTHREAD_PRIO_PROTECT. PTHREAD_PRIO_INHERIT maps to a semaphore create with
SEM_PRIO_INHERIT set (see 'semMCreate' for more detail). A thread locking a
mutex created with its protocol attribute set to PTHREAD_PRIO_PROTECT has its
priority elevated to that of of the prioceiling attribute of the mutex. When
the mutex is unlocked, the priority of the calling thread is restored to its
previous value.

CONDITION VARIABLES
Condition variables are another synchronization mechanism that is included
in the POSIX threads library. A condition variable allows threads
to block until some condition is met. There are really only two basic
operations that a condition variable can be involved in: waiting and
signalling. Condition variables are always associated with a mutex.

A thread can wait for a condition to become true by taking the mutex and
then calling pthread_cond_wait(). That function will release the mutex and
wait for the condition to be signalled by another thread. When the condition
is signalled, the function will re-acquire the mutex and return to the caller.

Condition variable support two types of signalling: single thread wake-up using
pthread_cond_signal(), and multiple thread wake-up using
pthread_cond_broadcast(). The latter of these will unblock all threads that
were waiting on the specified condition variable.

It should be noted that condition variable signals are not related to POSIX
signals. In fact, they are implemented using VxWorks semaphores.

RESOURCE COMPETITION
All tasks, and therefore all POSIX threads, compete for CPU time together. For
that reason the contention scope thread attribute is always
'PTHREAD_SCOPE_SYSTEM'.

NO VXWORKS EQUIVALENT
Since there is no notion of a process (in the POSIX sense), there is no
notion of sharing of locks (mutexes) and condition variables between processes.
As a result, the POSIX symbol '_POSIX_THREAD_PROCESS_SHARED' is not defined in
this implementation, and the routines pthread_condattr_getpshared(),
pthread_condattr_setpshared(), pthread_mutexattr_getpshared() are not
implemented.

Also, since there are no processes in VxWorks, fork(), wait(), and
pthread_atfork() are unimplemented.

VxWorks does not have password, user, or group databases, therefore there are
no implementations of getlogin(), getgrgid(), getpwnam(), getpwuid(),
getlogin_r(), getgrgid_r(), getpwnam_r(),  and getpwuid_r().

SCHEDULING
The default scheduling policy for a created thread is inherited from the system
setting at the time of creation.

Scheduling policies under VxWorks are global; they are not set per-thread,
as the POSIX model describes. As a result, the <pthread> scheduling routines,
as well as the POSIX scheduling routines native to VxWorks, do not allow you
to change the scheduling policy. Under VxWorks you may set the scheduling
policy in a thread, but if it does not match the system's scheduling policy,
an error is returned.

The detailed explanation for why this error occurs is a bit convoluted:
technically the scheduling policy is an attribute of a thread (in that there
are pthread_attr_getschedpolicy() and pthread_attr_setschedpolicy() functions
that define what the thread's scheduling policy will be once it is created,
and not what any thread should do at the time they are called). A situation
arises where the scheduling policy in force at the time of a thread's
creation is not the same as set in its attributes. In this case
pthread_create() fails with an otherwise undocumented error 'ENOTTY'.

The bottom line is that under VxWorks, if you wish to specify the scheduling
policy of a thread, you must set the desired global scheduling policy to match.
Threads must then adhere to that scheduling policy, or use the
PTHREAD_INHERIT_SCHED mode to inherit the current mode and creator's priority.

CREATION AND CANCELLATION
Each time a thread is created, the <pthreads> library allocates resources on
behalf of it. Each time a VxWorks task (i.e. one not created by the
pthread_create() function) uses a POSIX threads feature such as thread
private data or pushes a cleanup handler, the <pthreads> library creates
resources on behalf of that task as well.

Asynchronous thread cancellation is accomplished by way of a signal. A
special signal, SIGCANCEL, has been set aside in this version of VxWorks for
this purpose. Applications should take care not to block or handle SIGCANCEL.

SUMMARY MATRIX

.TS
tab (|);
l l l.
'<pthread> function' | 'Implemented?' | 'Note(s)'
_
pthread_attr_destroy | Yes |
pthread_attr_getdetachstate | Yes |
pthread_attr_getinheritsched | Yes |
pthread_attr_getschedparam | Yes |
pthread_attr_getschedpolicy | Yes |
pthread_attr_getscope | Yes |
pthread_attr_getstackaddr | Yes |
pthread_attr_getstacksize | Yes |
pthread_attr_init | Yes |
pthread_attr_setdetachstate | Yes |
pthread_attr_setinheritsched | Yes |
pthread_attr_setschedparam | Yes |
pthread_attr_setschedpolicy | Yes |
pthread_attr_setscope | Yes | 2
pthread_attr_setstackaddr | Yes |
pthread_attr_setstacksize | Yes |
pthread_atfork | No | 1
pthread_cancel | Yes | 5
pthread_cleanup_pop | Yes |
pthread_cleanup_push | Yes |
pthread_condattr_destroy | Yes |
pthread_condattr_getpshared | No | 3
pthread_condattr_init | Yes |
pthread_condattr_setpshared | No | 3
pthread_cond_broadcast | Yes |
pthread_cond_destroy | Yes |
pthread_cond_init | Yes |
pthread_cond_signal | Yes |
pthread_cond_timedwait | Yes |
pthread_cond_wait | Yes |
pthread_create | Yes |
pthread_detach | Yes |
pthread_equal | Yes |
pthread_exit | Yes |
pthread_getschedparam | Yes | 4
pthread_getspecific | Yes |
pthread_join | Yes |
pthread_key_create | Yes |
pthread_key_delete | Yes |
pthread_kill | Yes |
pthread_once | Yes |
pthread_self | Yes |
pthread_setcancelstate | Yes |
pthread_setcanceltype | Yes |
pthread_setschedparam | Yes | 4
pthread_setspecific | Yes |
pthread_sigmask | Yes |
pthread_testcancel | Yes |
pthread_mutexattr_destroy | Yes |
pthread_mutexattr_getprioceiling | Yes |
pthread_mutexattr_getprotocol | Yes |
pthread_mutexattr_getpshared | No | 3
pthread_mutexattr_init | Yes |
pthread_mutexattr_setprioceiling | Yes |
pthread_mutexattr_setprotocol | Yes |
pthread_mutexattr_setpshared | No | 3
pthread_mutex_destroy | Yes |
pthread_mutex_getprioceiling | Yes |
pthread_mutex_init | Yes |
pthread_mutex_lock | Yes |
pthread_mutex_setprioceiling | Yes |
pthread_mutex_trylock | Yes |
pthread_mutex_unlock | Yes |
getlogin_r | No | 6
getgrgid_r | No | 6
getpwnam_r | No | 6
getpwuid_r | No | 6
.TE

NOTES
.iP 1 4
The pthread_atfork() function is not implemented since fork() is not
implemented in VxWorks.
.iP 2
The contention scope thread scheduling attribute is always
PTHREAD_SCOPE_SYSTEM, since threads (i.e. tasks) contend for resources
with all other threads in the system.
.iP 3
The routines pthread_condattr_getpshared(), pthread_attr_setpshared(),
pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared() are not
supported, since these interfaces describe how condition variables and
mutexes relate to a process, and VxWorks does not implement a process model.
.iP 4
The default scheduling policy is inherited from the current system setting.
The POSIX model of per-thread scheduling policies is not supported, since a
basic tenet of the design of VxWorks is a system-wide scheduling policy.
.iP 5
Thread cancellation is supported in appropriate <pthread> routines and
those routines already supported by VxWorks. However, the complete list of
cancellation points specified by POSIX is not supported because routines
such as msync(), fcntl(), tcdrain(), and wait() are not implemented by
VxWorks.
.iP 6
The routines getlogin_r(), getgrgid_r(), getpwnam_r(), and getpwuid_r() are
not implemented.
.LP

INCLUDE FILES: pthread.h

SEE ALSO: taskLib, semMLib, semPxLib,
<VxWorks Programmer's Guide: Multitasking>
*/


/* includes */

#include "vxWorks.h"
#include "semLib.h"
#include "taskLib.h"
#include "timers.h"
#include "taskArchLib.h"
#include "private/timerLibP.h"
#include "types/vxTypesOld.h"
#include "private/taskLibP.h"
#include "kernelLib.h"
#include "taskHookLib.h"
#include "signal.h"
#include "stdio.h"
#include "string.h"
#include "errno.h"
#include "memLib.h"
#include "fcntl.h"
#include "ioLib.h"
#include "logLib.h"
#include "sched.h"
#include "private/schedP.h"

#ifndef _WRS_VXWORKS_5_X
#include "private/pdLibP.h"
#include "pdLib.h"
#endif

#define __PTHREAD_SRC
#include "pthread.h"

#undef PTHREADS_DEBUG

#ifdef PTHREADS_DEBUG
#undef LOCAL
#define LOCAL
#endif

/* defines */

#define INIT_MUTEX(pMutex)						\
    do									\
	{								\
	if (!pthreadLibInited)						\
	    return (EINVAL);						\
	if ((pMutex)->mutexInitted == FALSE)				\
	    {								\
	    if (vxTas(&(pMutex)->mutexIniting) == TRUE)			\
		{							\
		taskLock();  /* may not be necessary */			\
									\
		(pMutex)->mutexSemId = semMCreate(			\
		      (pMutex->mutexAttr.mutexAttrProtocol ==		\
		       PTHREAD_PRIO_INHERIT ? SEM_INVERSION_SAFE : 0) |	\
		       SEM_Q_PRIORITY);					\
									\
		if ((pMutex)->mutexSemId == NULL)			\
		    {							\
		    taskUnlock ();					\
		    return (EINVAL);	/* internal error */		\
		    }							\
									\
		(pMutex)->mutexInitted = TRUE;				\
					   				\
		taskUnlock();	/* may not be necessary */		\
		}							\
	    else							\
		{							\
	        while ((pMutex)->mutexInitted == FALSE)			\
		    ;    /* pound sand */				\
		}							\
	    }								\
	}								\
    while (0)

#define INIT_COND(pCond)						\
    do									\
	{								\
	if (!pthreadLibInited)						\
	    return (EINVAL);						\
	if ((pCond)->condInitted == FALSE)				\
	    {								\
	    if (vxTas(&(pCond)->condIniting) == TRUE)			\
		{							\
		taskLock();  /* may not be necessary */			\
									\
		(pCond)->condSemId = semBCreate(SEM_Q_PRIORITY,		\
						SEM_EMPTY);		\
									\
		if ((pCond)->condSemId == NULL)				\
		    {							\
		    taskUnlock ();					\
		    return (EINVAL); /* internal error */		\
		    }							\
									\
		(pCond)->condInitted = TRUE;				\
									\
		taskUnlock(); /* may not be necessary */		\
		}							\
	    else							\
		{							\
	    	while ((pCond)->condInitted == FALSE)			\
		    ;    /* pound sand */				\
		}							\
	    }								\
	}								\
    while (0)

#ifndef _WRS_VXWORKS_5_X
#define VALID_PTHREAD(pThread, pLcb) \
		((pThread) && ((pThread)->flags & VALID) && \
		((pLcb) = taskLcbGet((pThread)->taskId)) && \
		(pLcb)->pPthread && \
		(pLcb)->pPthread == (pThread))
#else
#define VALID_PTHREAD(pThread, pTcb) \
		((pThread) && ((pThread)->flags & VALID) && \
		((pTcb) = (WIND_TCB *)(pThread)->taskId) && \
		(pTcb)->pPthread && \
		(pTcb)->pPthread == (pThread))
#endif


#define MY_PTHREAD ((internalPthread *)(taskIdCurrent->pPthread))
#define LOCK_PTHREAD(pThread)   semTake((pThread)->mutexSemId, WAIT_FOREVER)
#define UNLOCK_PTHREAD(pThread) semGive((pThread)->mutexSemId)
#define CANCEL_LOCK(pThread)    semTake((pThread)->cancelSemId, WAIT_FOREVER)
#define CANCEL_UNLOCK(pThread)  semGive((pThread)->cancelSemId)

/* numeric boundary check for priority. no mention of meaning of value */
#define PRIO_LOWER_BOUND 0
#define PRIO_UPPER_BOUND 255
#define VALID_PRIORITY(pri)     (PRIO_LOWER_BOUND <= (pri) && \
				 (pri) <= PRIO_UPPER_BOUND)

#define DEF_PRIORITY	(PRIO_LOWER_BOUND + \
		      		(PRIO_UPPER_BOUND - PRIO_LOWER_BOUND) / 2)

/*
 * Make sure we free memory from the PD's heap, even when called from a kernel
 * task, or a delete hook...
 */

/* typedefs */

typedef struct
    {
    pthread_mutex_t    mutex;
    long               count;
    void               (*destructor)();
    } pthread_key;

/* globals */

/*
 * This is a common. DO NOT INITIALISE IT - doing so will break the scalability
 * that relies on its status as a common.
 */

FUNCPTR _pthread_setcanceltype;

/* locals */

LOCAL pthread_key	key_table[_POSIX_THREAD_KEYS_MAX];
LOCAL SEM_ID		key_mutex		= NULL;
LOCAL BOOL		pthreadLibInited	= FALSE;

/* The default mutex, condition variable and thread creation attribute objects
 * and initializers - either POSIX or implementation-defined.
 * Used by:
 *  pthread_mutex_init()
 *  pthread_cond_init()
 *  pthread_create()
 *
 * For mutexes and condition variables,
 * only the 'process-shared' attribute is defined.
 */

LOCAL pthread_mutexattr_t defaultMutexAttr =
    {
    PTHREAD_INITIALIZED, PTHREAD_PRIO_INHERIT, 0
    };

/* forward declarations */

LOCAL void self_become_pthread(void);
LOCAL void pthreadDeleteTask (internalPthread * pThread);
LOCAL void threadExitCleanup (internalPthread * pThread);
LOCAL void cleanupPrivateData (internalPthread * pThread);

/* externals */

IMPORT BOOL	vxTas (void *addr);

/*******************************************************************************
*
* pthreadLibInit - initialize POSIX threads support
*
* This routine initializes the POSIX threads (<pthreads>) support for
* VxWorks. It should be called before any POSIX threads functions are used;
* normally it will be called as part of the kernel's initialization sequence.
*
* RETURNS: N/A
*/

void pthreadLibInit (void)
    {
    if (_pthreadLibInit ((FUNCPTR) pthreadDeleteTask) != ERROR)
	{
	/* Create the thread specific data key */

	key_mutex = semMCreate(SEM_Q_PRIORITY | SEM_INVERSION_SAFE);

	/*
	 * Initialise the function pointer for user level access to this