tasklib.c

VXWORKS源代码

/* taskLib.c - task management library */

/* Copyright 1984-2002 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
05o,15may02,pcm  added check for valid priority level in taskInit() (SPR 77368)
05n,04jan02,hbh  Increased default extra stack size for simulators.
05m,09nov01,jhw  Revert WDB_INFO to be inside WIND_TCB.
05l,05nov01,gls  added initialization of pPthread in taskInit
05k,17oct01,jhw  Move WDB_INFO outside of WIND_TCB in task mem partition.
05j,11oct01,cjj  removed Am29k support.  Added documentation to taskSpawn()
		 regarding the use of VX_FP_TASK.
05i,10oct01,pcm  added note to taskIdVerify () about exceptions (SPR 31496)
05h,09oct01,bwa  Added event field initialization.
05g,20sep01,aeg  added init of pSelectContext and pWdbInfo in taskInit().
05f,13jul01,kab  Cleanup for merge to mainline
05e,14mar01,pcs  Added code for ALTIVEC awareness.
05d,18dec00,pes  Correct compiler warnings
05d,03mar00,zl   merged SH support into T2
05c,12mar99,dbs  add COM task-local storage to TCB
05b,09mar98,cym  increasing stack size for SIMNT.
05a,05nov98,fle  doc : allowed link to taskInfo library by putting it in bold
04g,04sep98,cdp  force entry-point in TCB to have bit zero clear for all Thumb.
04f,25sep98,cym  removed 04f.
04e,06may98,cym  changed taskDestroy for SIMNT to use the calling context.
04d,22jul96,jmb  merged ease patch,  don't reinitialize excInfo on taskRestart.
04c,12jan98,dbt  modified for new debugger scheme.
04b,08jul97,dgp  doc: correct typo per SPR 7769
04b,22aug97,cdp  force entry point in TCB to have bit zero clear for Thumb.
04a,29oct96,dgp  doc: correct spelling of checkStack() in taskSpawn()
03z,16oct96,dgp  doc: add errnos for user-visible routines per SPR 6893
03y,09oct06,dgp  doc: correct taskInit() description of *pStackBase - SPR 6828
03x,08aug96,dbt  Modified taskRestart to handle task name>20 bytes (SPR #3445).
03w,24jul96,dbt  Initialized exception info for I960 in taskInit (SPR #3092).
03v,22jul96,jmb  merged ease patch,  don't reinitialize excInfo on taskRestart.
03u,27jun96,dbt  doc : added taskLock & taskUnlock not callable from
		 interrupt service routines (SPR #2568).
		 Updated copyright.
03t,24jun96,sbs  made windview instrumentation conditionally compiled
03u,13jun96,ism  increased stack size again
03t,13feb96,ism  bumped stack size for SIMSOLARIS created tasks
03s,25jan96,ism  cleanup for vxsim/solaris.
03r,23oct95,jdi  doc: added bit values for taskSpawn() options (SPR 4276).
03q,14oct95,jdi  doc: removed SEE ALSO to vxTaskEntry(), which is not published.
03p,26may95,ms	 initialize WDB fields in the TCB
	   + rrr
03p,30oct95,ism  added SIMSPARCSOLARIS support
03o,16jan95,rhp  added expl of taskID for taskInit(), taskActivate() (SPR#3923)
03n,10nov94,ms   bumped stack size for all spawned SIMHPPA tasks.
03m,28jul94,dvs  added reset of pTaskLastFpTcb in taskDestroy. (SPR #3033)
03l,02dec93,pme  added am29K family stack support.
03k,20jul94,ms   undid some of 03j for VxSim/HPPA. Bumped restartTaskStackSize.
03j,28jan94,gae  vxsim fixes for bumping stack on sysFlag & clearing excInfo.
03n,19oct94,rdc  bug in eventlogging in taskDestroy.
		 added lockCnt to EVT_CTX_TASKINFO.
03m,14apr94,smb  modified EVT_OBJ_* macros again
03l,15mar94,smb  modified EVT_OBJ_* macros
03k,24jan94,smb  added instrumentation macros
03j,10dec93,smb  added instrumentation
03i,16sep93,jmm  added check in taskPrioritySet() to ensure priority is 0-255
03h,01mar93,jdi  doc: reinstated VX_UNBREAKABLE as publishable option, per kdl;
		 addition to taskDelay() as per rrr.
03g,27feb93,jcf  fixed race in taskDestroy() with masking signals.
03f,15feb93,jdi  fixed taskSpawn() to mention fixed argument requirement.
03e,10feb93,jdi  doc review by jcf; corrected spelling of stdlib.h.
03d,04feb93,jdi  documentation cleanup; SPR#1365: added VX_DEALLOC_STACK
		 to doc for taskSpawn().
03c,01oct92,jcf  removed deadlock with deletion of deletion safe tasks.
03b,29sep92,pme  removed failure notification in taskDestroy.
03a,31aug92,rrr  fixed taskDelay to set errno to EINTR if a signal occurs.
02z,23aug92,jcf  moved info routines to taskInfo.c.  changed bzero to bfill.
02y,02aug92,jcf  initialized pExcRegSet (taskInit) utilized in taskRegSet().
02x,29jul92,jcf  taskDestroy suspends victim; padding to account for mem tags;
		 package initialization with taskInit; documentation.
02w,27jul92,jcf  cleanup.
02v,24jul92,yao  changed to use STACK_ROUND_UP instead MEM_ROUND_UP in 
		 taskStackAllot().  bzeroed dbgInfo in taskInit().
02u,23jul92,yao  removed initialization of pDbgState.
02t,23jul92,rrr  rounded the sizeof the TCB up to the requirements of rounding
                 of the stack.
02s,23jul92,ajm  moved _sig_timeout_recalc from sigLib to shrink proms
02r,21jul92,pme  changed shared TCB free management.
                 added smObjTaskDeleteFailRtn.
02q,19jul92,pme  added shared memory objects support.
02p,19jul92,smb  Added some ANSI documentation.
02o,09jul92,rrr  changed xsignal.h to private/sigLibP.h
02n,04jul92,jcf	 changed algorithm of taskDestroy/taskRestart to avoid excJobAdd
		 tid is now valid for delete hooks.
		 stack is now not filled optionally.
		 show/info routines removed.
02m,30jun92,yao  changed to init pDbgState for all architectures.
02l,26jun92,jwt  restored 02k changes; cleaned up compiler warnings.
02k,16jun92,jwt  made register display four across; fixed rrr version numbers.
02j,26may92,rrr  the tree shuffle
02i,30apr92,rrr  added signal restarting
02h,18mar92,yao  removed macro MEM_ROUND_UP.  removed conditional definition
		 STACK_GROWS_DOWN/UP.  abstracted taskStackAllot() from
		 taskArchLib.c.  removed unneccesary if conditionals for
		 calls to taskRegsInit() in taskInit().  changed taskRegsShow()
		 to be within 80 columns per line.
02g,12mar92,yao  added taskRegsShow().  changed copyright notice.
02f,04oct91,rrr  passed through the ansification filter
                  -changed functions to ansi style
		  -changed includes to have absolute path from h/
		  -fixed #else and #endif
		  -changed VOID to void
		  -changed copyright notice
02e,11sep91,hdn  Init pDbgState for TRON.
02d,21aug91,ajm  made MIPS stacksize bounded on 8 bytes for varargs.
02c,14aug91,del  padded qInit and excJobAdd call's with 0's.
		 Init pDbgState for I960 only.
02b,10jun91,gae  fixed typo in taskOptionString to not say VX_FP_STACK.
02a,23may91,jwt  modifed roundup from 4 to 8 bytes for SPARC only.
01z,26apr91,hdn  added conditional checks for TRON architecture.
01y,20apr91,del  fixed bug in taskInfoGet() for checking the stack high mark.
		 For STACK_GROWS_UP (i960) version.
01x,05apr91,jdi	 documentation -- removed header parens and x-ref numbers;
		 doc review by dnw.
01w,31mar91,del  added I960 specifics.
01v,24mar91,jdi  documentation cleanup.
01u,25oct90,dnw  made taskTerminate() NOMANUAL.
01t,05oct90,dnw  added forward declarations.
01s,30sep90,jcf  added taskDeleteForce().
01r,31aug90,jcf  documentation.
01q,30jul90,jcf  changed task{Lock,Unlock,Safe,Unsafe} to return STATUS
01p,17jul90,dnw  changed to call to objAlloc() to objAllocExtra().
01o,13jul90,rdc  taskInit zeros environment var and select stuff in tcb.
01n,05jul90,jcf  added STACK_GROWS_XX to resolve stack growth direction issues.
		 renamed stack variables.
		 changed taskSuspend to disregard task deletion safety.
01m,26jun90,jcf  added taskStackAllot()
		 changed taskNames to use taskStackAllot()
		 removed taskFppHook.
		 general cleanup.
01l,15apr90,jcf  changed nameForNameless from task<%d> to t<%d>
01k,28aug89,jcf  modified to version 2.0 of wind.
01j,09aug89,gae  undid varargs stuff.
01i,28apr89,mcl  added some initializations in WIND_TCB (applies to
		   both SPARC & 68k); fixes alignment check in taskIdVerify.
01h,07apr89,mcl  SPARC floating point.
01g,12dec88,ecs  gave it some sparc.
		 added include of varargs.h.
01f,19nov88,jcf  taskDelay can not be called from interrupt level.
                   task ids of zero are translated to taskCurrentId here now.
01e,23sep88,gae  documentation touchup.
01d,07sep88,gae  documentation.
01c,23aug88,gae  documentation.
01b,20jul88,jcf  clean up.
01a,10mar88,jcf  written.
*/

/*
DESCRIPTION
This library provides the interface to the VxWorks task management facilities.
Task control services are provided by the VxWorks kernel, which is comprised
of kernelLib, taskLib, semLib, tickLib, msgQLib, and `wdLib'.  Programmatic
access to task information and debugging features is provided by `taskInfo'.
Higher-level task information display routines are provided by `taskShow'.

TASK CREATION
Tasks are created with the general-purpose routine taskSpawn().  Task
creation consists of the following:  allocation of memory for the stack
and task control block (WIND_TCB), initialization of the WIND_TCB, and
activation of the WIND_TCB.  Special needs may require the use of the
lower-level routines taskInit() and taskActivate(), which are the underlying
primitives of taskSpawn().

Tasks in VxWorks execute in the most privileged state of the underlying
architecture.  In a shared address space, processor privilege offers no
protection advantages and actually hinders performance.

There is no limit to the number of tasks created in VxWorks, as long as
sufficient memory is available to satisfy allocation requirements.

The routine sp() is provided in usrLib as a convenient abbreviation for
spawning tasks.  It calls taskSpawn() with default parameters.

TASK DELETION
If a task exits its "main" routine, specified during task creation, the
kernel implicitly calls exit() to delete the task.  Tasks can be
explicitly deleted with the taskDelete() or exit() routine.

Task deletion must be handled with extreme care, due to the inherent
difficulties of resource reclamation.  Deleting a task that owns a
critical resource can cripple the system, since the resource may no longer
be available.  Simply returning a resource to an available state is not a
viable solution, since the system can make no assumption as to the state
of a particular resource at the time a task is deleted.

The solution to the task deletion problem lies in deletion protection,
rather than overly complex deletion facilities.  Tasks may be protected
from unexpected deletion using taskSafe() and taskUnsafe().  While a task
is safe from deletion, deleters will block until it is safe to proceed.
Also, a task can protect itself from deletion by taking a mutual-exclusion
semaphore created with the SEM_DELETE_SAFE option, which enables an implicit
taskSafe() with each semTake(), and a taskUnsafe() with each semGive()
(see semMLib for more information).
Many VxWorks system resources are protected in this manner, and
application designers may wish to consider this facility where dynamic
task deletion is a possibility.

The sigLib facility may also be used to allow a task to
execute clean-up code before actually expiring.

TASK CONTROL
Tasks are manipulated by means of an ID that is returned when a task is
created.  VxWorks uses the convention that specifying a task ID of NULL
in a task control function signifies the calling task.

The following routines control task state:  taskResume(), taskSuspend(),
taskDelay(), taskRestart(), taskPrioritySet(), and taskRegsSet().

TASK SCHEDULING
VxWorks schedules tasks on the basis of priority.  Tasks may have
priorities ranging from 0, the highest priority, to 255, the lowest
priority.  The priority of a task in VxWorks is dynamic, and an existing
task's priority can be changed using taskPrioritySet().

INTERNAL:
	WINDVIEW INSTRUMENTATION
Level 1:
	taskInit() causes EVENT_TASKSPAWN
	taskDestroy() causes EVENT_TASKDESTROY
	taskSuspend() causes EVENT_TASKSUSPEND
	taskResume() causes EVENT_TASKRESUME
	taskPrioritySet() causes EVENT_TASKPRIORITYSET
	taskUnsafe() causes EVENT_TASKUNSAFE

Level 2:
	taskDestroy() causes EVENT_OBJ_TASK
	taskUnlock() causes EVENT_OBJ_TASK
	taskUnsafe() causes EVENT_OBJ_TASK

Level 3:
	taskInit() causes EVENT_TASKNAME
	taskUnlock() causes EVENT_TASKUNLOCK

INCLUDE FILES: taskLib.h

SEE ALSO: `taskInfo', taskShow, taskHookLib, taskVarLib, semLib, semMLib, 
kernelLib,
.pG "Basic OS"
*/

#include "vxWorks.h"
#include "errno.h"
#include "semLib.h"
#include "string.h"
#include "regs.h"
#include "intLib.h"
#include "taskArchLib.h"
#include "stdio.h"
#include "memLib.h"
#include "qFifoGLib.h"
#include "sysLib.h"		/* CPU==SIM* */
#include "private/eventLibP.h"
#include "private/sigLibP.h"
#include "private/classLibP.h"
#include "private/objLibP.h"
#include "private/smObjLibP.h"
#include "private/smFixBlkLibP.h"
#include "private/taskLibP.h"
#include "private/kernelLibP.h"
#include "private/workQLibP.h"
#include "private/windLibP.h"
#include "private/eventP.h"


/* locals */

LOCAL OBJ_CLASS	taskClass;			/* task object class */
LOCAL int	nameForNameless;		/* name for nameless tasks */
LOCAL BOOL	taskLibInstalled;		/* protect from double inits */

/* globals */

FUNCPTR		smObjTcbFreeRtn;		/* shared TCB free routine */
FUNCPTR		smObjTcbFreeFailRtn;		/* shared TCB free fail rtn */
FUNCPTR		smObjTaskDeleteFailRtn;		/* windDelete free fail rtn */
FUNCPTR		taskBpHook;			/* hook for VX_UNBREAKABLE */
FUNCPTR		taskCreateTable   [VX_MAX_TASK_CREATE_RTNS + 1];
FUNCPTR		taskSwitchTable   [VX_MAX_TASK_SWITCH_RTNS + 1];
FUNCPTR 	taskDeleteTable   [VX_MAX_TASK_DELETE_RTNS + 1];
FUNCPTR 	taskSwapTable     [VX_MAX_TASK_SWAP_RTNS   + 1];
int		taskSwapReference [VX_MAX_TASK_SWAP_RTNS   + 1];
WIND_TCB *	taskIdCurrent;				/* current task ID */
CLASS_ID	taskClassId   		= &taskClass;	/* task class ID */
char *		namelessPrefix		= "t";		/* nameless prefix */
char *		restartTaskName		= "tRestart";	/* restart name */
int		restartTaskPriority	= 0;		/* restart priority */
int		restartTaskStackSize	= 6000;		/* default stack size */
int		restartTaskOptions	= VX_NO_STACK_FILL | VX_UNBREAKABLE;
BOOL		taskPriRangeCheck	= TRUE; /* limit priorities to 0-255 */
WIND_TCB *	pTaskLastFpTcb          = NULL; /* pTcb for fppSwapHook */
WIND_TCB *	pTaskLastDspTcb         = NULL; /* pTcb for dspSwapHook */
#ifdef _WRS_ALTIVEC_SUPPORT
WIND_TCB *      pTaskLastAltivecTcb     = NULL; /* pTcb for altivecSwapHook */
#endif  /* _WRS_ALTIVEC_SUPPORT */

#ifdef WV_INSTRUMENTATION
/* instrumentation declarations */

LOCAL OBJ_CLASS taskInstClass;			/* task object class */
CLASS_ID 	taskInstClassId 	= &taskInstClass; /* instrumented task */
#endif

/* forward declarations */

int		taskCreat ();
WIND_TCB *	taskTcb ();			/* get pTcb from tid */


/*******************************************************************************
*
* taskLibInit - initialize kernel task library
*
* INTERNAL
* Tasks are a class of object in VxWorks.  This routine initializes the task
* task class object.  Once initialized, tasks can be created/deleted/etc via
* objLib.  No other task related routine may be executed prior to the call
* to this routine.  The sizeof the WIND_TCB is goosed up by 16 bytes
* bytes so we can protect the starting portion of a task's tcb during 
* deletion, in the case of STACK_GROWS_UP, or a portion of the top of the 
* task's top of stack in the case of STACK_GROWS_DOWN.  This portion is 
* clobbered with a FREE_BLOCK during objFree().
*
* NOMANUAL
*/

STATUS taskLibInit (void)
    {
    if ((!taskLibInstalled) &&
        (classInit (taskClassId, STACK_ROUND_UP(sizeof(WIND_TCB) + 16),
                    OFFSET(WIND_TCB, objCore), (FUNCPTR) taskCreat,
                    (FUNCPTR) taskInit, (FUNCPTR) taskDestroy) == OK))
        {
#ifdef WV_INSTRUMENTATION
	taskClassId->initRtn = taskInstClassId;
	classInstrument (taskClassId, taskInstClassId);
#endif
        taskLibInstalled = TRUE;
        }

    return ((taskLibInstalled) ? OK : ERROR);
    }

/*******************************************************************************
*
* taskSpawn - spawn a task
*
* This routine creates and activates a new task with a specified priority
* and options and returns a system-assigned ID.  See taskInit() and
* taskActivate() for the building blocks of this routine.
*
* A task may be assigned a name as a debugging aid.  This name will appear
* in displays generated by various system information facilities such as
* i().  The name may be of arbitrary length and content, but the current
* VxWorks convention is to limit task names to ten characters and prefix