/* 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 taskInit05k,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 mainline05e,14mar01,pcs  Added code for ALTIVEC awareness.05d,18dec00,pes  Correct compiler warnings05d,03mar00,zl   merged SH support into T205c,12mar99,dbs  add COM task-local storage to TCB05b,09mar98,cym  increasing stack size for SIMNT.05a,05nov98,fle  doc : allowed link to taskInfo library by putting it in bold04g,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 776904b,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 689303y,09oct06,dgp  doc: correct taskInit() description of *pStackBase - SPR 682803x,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 compiled03u,13jun96,ism  increased stack size again03t,13feb96,ism  bumped stack size for SIMSOLARIS created tasks03s,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	   + rrr03p,30oct95,ism  added SIMSPARCSOLARIS support03o,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 again03l,15mar94,smb  modified EVT_OBJ_* macros03k,24jan94,smb  added instrumentation macros03j,10dec93,smb  added instrumentation03i,16sep93,jmm  added check in taskPrioritySet() to ensure priority is 0-25503h,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 proms02r,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.h02n,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 shuffle02i,30apr92,rrr  added signal restarting02h,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 notice02e,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 STATUS01p,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.*//*DESCRIPTIONThis library provides the interface to the VxWorks task management facilities.Task control services are provided by the VxWorks kernel, which is comprisedof kernelLib, taskLib, semLib, tickLib, msgQLib, and `wdLib'.  Programmaticaccess to task information and debugging features is provided by `taskInfo'.Higher-level task information display routines are provided by `taskShow'.TASK CREATIONTasks are created with the general-purpose routine taskSpawn().  Taskcreation consists of the following:  allocation of memory for the stackand task control block (WIND_TCB), initialization of the WIND_TCB, andactivation of the WIND_TCB.  Special needs may require the use of thelower-level routines taskInit() and taskActivate(), which are the underlyingprimitives of taskSpawn().Tasks in VxWorks execute in the most privileged state of the underlyingarchitecture.  In a shared address space, processor privilege offers noprotection advantages and actually hinders performance.There is no limit to the number of tasks created in VxWorks, as long assufficient memory is available to satisfy allocation requirements.The routine sp() is provided in usrLib as a convenient abbreviation forspawning tasks.  It calls taskSpawn() with default parameters.TASK DELETIONIf a task exits its "main" routine, specified during task creation, thekernel implicitly calls exit() to delete the task.  Tasks can beexplicitly deleted with the taskDelete() or exit() routine.Task deletion must be handled with extreme care, due to the inherentdifficulties of resource reclamation.  Deleting a task that owns acritical resource can cripple the system, since the resource may no longerbe available.  Simply returning a resource to an available state is not aviable solution, since the system can make no assumption as to the stateof 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 protectedfrom unexpected deletion using taskSafe() and taskUnsafe().  While a taskis safe from deletion, deleters will block until it is safe to proceed.Also, a task can protect itself from deletion by taking a mutual-exclusionsemaphore created with the SEM_DELETE_SAFE option, which enables an implicittaskSafe() with each semTake(), and a taskUnsafe() with each semGive()(see semMLib for more information).Many VxWorks system resources are protected in this manner, andapplication designers may wish to consider this facility where dynamictask deletion is a possibility.The sigLib facility may also be used to allow a task toexecute clean-up code before actually expiring.TASK CONTROLTasks are manipulated by means of an ID that is returned when a task iscreated.  VxWorks uses the convention that specifying a task ID of NULLin a task control function signifies the calling task.The following routines control task state:  taskResume(), taskSuspend(),taskDelay(), taskRestart(), taskPrioritySet(), and taskRegsSet().TASK SCHEDULINGVxWorks schedules tasks on the basis of priority.  Tasks may havepriorities ranging from 0, the highest priority, to 255, the lowestpriority.  The priority of a task in VxWorks is dynamic, and an existingtask's priority can be changed using taskPrioritySet().INTERNAL:	WINDVIEW INSTRUMENTATIONLevel 1:	taskInit() causes EVENT_TASKSPAWN	taskDestroy() causes EVENT_TASKDESTROY	taskSuspend() causes EVENT_TASKSUSPEND	taskResume() causes EVENT_TASKRESUME	taskPrioritySet() causes EVENT_TASKPRIORITYSET	taskUnsafe() causes EVENT_TASKUNSAFELevel 2:	taskDestroy() causes EVENT_OBJ_TASK	taskUnlock() causes EVENT_OBJ_TASK	taskUnsafe() causes EVENT_OBJ_TASKLevel 3:	taskInit() causes EVENT_TASKNAME	taskUnlock() causes EVENT_TASKUNLOCKINCLUDE FILES: taskLib.hSEE 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_SUPPORTWIND_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