/* sigLib.c - software signal facility library *//* Copyright 1984-2002 Wind River Systems, Inc. */#include "copyright_wrs.h"/*modification history--------------------01m,17jul00,jgn  merge DOT-4 pthreads code01l,20apr00,hk   changed sysBErrVecNum to excBErrVecNum for SH.01k,03mar00,zl   merged SH support into T201j,18aug98,tpr  added PowerPC EC 603 support.02l,08may98,pr   added extra parameter in WV macro02k,23jan98,pr   commented out some of the WindView code02j,13dec97,pr   added ifdef WV_INSTRUMENTATION to the WindView code02i,13nov96,dgp  doc: add PowerPC info to table02h,11jun96,dbt  fixed spr 5789. Added brackets for errnoSet in function		 sigtimedwait().02g,25nov95,jdi  removed 29k stuff.02f,02feb95,rhp  correct argument refs in signal() man page,                 and misc doc cleanup02e,16jan95,rhp  add pointer to POSIX 1003.1b fns in library man page01w,19oct93,cd   added R4000 to documentation.01w,03feb94,hdn  fixed spr 2996. for-loop in sigExcKill() ends if both are 0.		 added a comment for I80X86 support.01w,20mar94,pme  Added Am29030 and Am29200 exception signals definitions.02d,06jul94,rrr  added save/restore of resumption record for the I960KB.02c,08apr94,dvs  added doc on signal handler definition (SPR #3222).02b,07apr94,smb  changed parameter to EVENT_SIGSUSPEND02a,24mar94,smb  fixed event collection for sigsuspend01z,02feb94,kdl  fixed condition around ffsMsb() prototype; deleted sigwait()		 from structure diagram.01y,28jan94,kdl  added declaration of sigEvtRtn (from sigLibP.h); added include		 of sysLib.h; added prototype for ffsMsb()..01x,24jan94,smb  added instrumentation macros.		 changed description for 01w.01w,10dec93,smb  added instrumentation and POSIX phase 1 additions.01v,16sep93,rrr  fixed spr 2226,222701u,01mar93,jdi  doc: additions to section on signal handlers.01t,09feb93,rrr  fixed spelling in doc, removed sigstack() and sigreturn()		 from table correlating bsd and posix interface.01s,03feb93,rrr  fixed src 1903,1904,1905 which are not reseting the handler		 and corrected the use of sa_mask01r,03feb93,jdi  documentation cleanup for 5.1; augmented arch-specific		 exception tables.01q,13nov92,dnw  added include of smObjLib.h01p,15oct92,rrr  Fixed alignment of stack for 960 and sparc (spr #1628)01o,29sep92,rrr  NOMANUAL a bunch of routines. The function signal produces                 an error with mangen (but the output looks ok).01n,31aug92,rrr  fixed the code passed from excLib to be the exception vector01m,18aug92,rrr  bug fix for timers.01l,31jul92,rrr  changed _sig_timeout_recalc to _func_sigTimeoutRecalc01k,30jul92,rrr  undo of 01j (now back to 01i)01j,30jul92,kdl  backed out 01i changes pending rest of exc handling.01i,29jul92,rrr  added in hook for exceptions to call signals directly.01h,28jul92,jcf  falsed out delete hook that was causing grief for shell scripts01g,27jul92,rrr  a quick checkin to test timers, still more testing needed.01f,23jul92,ajm  moved _sig_timeout_recalc to taskLib to shrink proms01e,27jul92,rrr  added install of signals to excLib 01d,19jul92,pme  changed sigWindRestart() to handle shared semaphore take.		 added include stddef.h.01c,18jul92,smb  Changed errno.h to errnoLib.h.01b,10jul92,rrr  removed setjmp (now it is a macro in setjmp.h)01a,31jan92,rrr  written.*//*DESCRIPTIONThis library provides a signal interface for tasks.  Signals are used toalter the flow control of tasks by communicating asynchronous eventswithin or between task contexts.  Any task or interrupt service can"raise" (or send) a signal to a particular task.  The task being signaledwill immediately suspend its current thread of execution and invoke atask-specified "signal handler" routine.  The signal handler is auser-supplied routine that is bound to a specific signal and performswhatever actions are necessary whenever the signal is received.  Signalsare most appropriate for error and exception handling, rather than as ageneral purpose intertask communication mechanism.This library has both a BSD 4.3 and POSIX signal interface.  The POSIXinterface provides a standardized interface which is more functional thanthe traditional BSD 4.3 interface.  The chart below shows the correlationbetween BSD 4.3 and POSIX 1003.1 functions.  An application should use only oneform of interface and not intermix them..TStab(|);lf3 lf3l   l..ne 4\%BSD 4.3    | POSIX 1003.1_sigmask()    | sigemptyset(), sigfillset(), sigaddset(),	     |    sigdelset(), sigismember()sigblock()   | sigprocmask()sigsetmask() | sigprocmask()pause()      | sigsuspend()sigvec()     | sigaction()(none)       | sigpending()signal()     | signal()kill()       | kill().TEPOSIX 1003.1b (Real-Time Extensions) also specifies a queued-signalfacility that involves four additional routines: sigqueue(),sigwaitinfo(), and sigtimedwait().In many ways, signals are analogous to hardware interrupts.  The signalfacility provides a set of 31 distinct signals.  A signal can be raised bycalling kill(), which is analogous to an interrupt or hardware exception.A signal handler is bound to a particular signal with sigaction() in muchthe same way that an interrupt service routine is connected to aninterrupt vector with intConnect().  Signals are blocked for the durationof the signal handler, just as interrupts are locked out for the durationof the interrupt service routine.  Tasks can block the occurrence ofcertain signals with sigprocmask(), just as the interrupt level can beraised or lowered to block out levels of interrupts.  If a signal isblocked when it is raised, its handler routine will be called when thesignal becomes unblocked.Several routines (sigprocmask(), sigpending(), and sigsuspend()) take `sigset_t' data structures as parameters.  These data structures are used to specify signal set masks.  Several routines are provided for manipulating these data structures: sigemptyset() clears all the bits in a `segset_t',  sigfillset() sets all the bits in a `sigset_t', sigaddset() sets the bit in a `sigset_t' corresponding to a particular signal number, sigdelset() resets the bit in a `sigset_t' corresponding to a particular signal number, and sigismember() tests to see if the bit corresponding to a particular signal number is set.FUNCTION RESTARTINGIf a task is pended (for instance, by waiting for a semaphore to becomeavailable) and a signal is sent to the task for which the task has ahandler installed, then the handler will run before the semaphore istaken.  When the handler is done, the task will go back to being pended(waiting for the semaphore).  If there was a timeout used for the pend,then the original value will be used again when the task returns from thesignal handler and goes back to being pended.Signal handlers are typically defined as:.ne 7.CS    void sigHandler        (	int sig,			/@ signal number                 @/        )	{            ...        }.CEIn VxWorks, the signal handler is passed additional arguments and can bedefined as:.ne 9.CS    void sigHandler        (	int sig,			/@ signal number                 @/        int code,			/@ additional code               @/        struct sigcontext *pSigContext	/@ context of task before signal @/        )	{            ...        }.CEThe parameter <code> is valid only for signals caused by hardwareexceptions.  In this case, it is used to distinguish signal variants.For example, both numeric overflow and zero divide raise SIGFPE(floating-point exception) but have different values for <code>.(Note that when the above VxWorks extensions are used, the compilermay issue warnings.)SIGNAL HANDLER DEFINITIONSignal handling routines must follow one of two specific formats, so that theymay be correctly called by the operating system when a signal occurs.  Traditional signal handlers receive the signal number as the sole input parameter.  However, certain signals generated by routines which make up thePOSIX Real-Time Extensions (P1003.1b) support the passing of an additionalapplication-specific value to the handler routine.  These include signalsgenerated by the sigqueue() call, by asynchronous I/O, by POSIX real-timetimers, and by POSIX message queues.If a signal handler routine is to receive these additional parameters,SA_SIGINFO must be set in the sa_flags field of the sigaction structure whichis a parameter to the sigaction() routine.  Such routines must take thefollowing form:.CS	void sigHandler (int sigNum, siginfo_t * pInfo, void * pContext);.CETraditional signal handling routines must not set SA_SIGINFO in the sa_flagsfield, and must take the form of:.CS        void sigHandler (int sigNum);.CEEXCEPTION PROCESSING:Certain signals, defined below, are raised automatically whenhardware exceptions are encountered.  This mechanism allows user-definedexception handlers to be installed.  This is useful for recovering fromcatastrophic events such as bus or arithmetic errors.  Typically, setjmp()is called to define the point in the program where control will berestored, and longjmp() is called in the signal handler to restore thatcontext.  Note that longjmp() restores the state of the task's signalmask.  If a user-defined handler is not installed or the installed handlerreturns for a signal raised by a hardware exception, then the task issuspended and a message is logged to the console.The following is a list of hardware exceptions caught by VxWorks and deliveredto the offending task.  The user may include the higher-level header filesigCodes.h in order to access the appropriate architecture-specific header filecontaining the code value..SS "Motorola 68K".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code               | Exception_SIGSEGV | NULL               | bus errorSIGBUS  | BUS_ADDERR         | address errorSIGILL  | ILL_ILLINSTR_FAULT | illegal instructionSIGFPE  | FPE_INTDIV_TRAP    | zero divideSIGFPE  | FPE_CHKINST_TRAP   | chk trapSIGFPE  | FPE_TRAPV_TRAP     | trapv trapSIGILL  | ILL_PRIVVIO_FAULT  | privilege violationSIGTRAP | NULL               | trace exceptionSIGEMT  | EMT_EMU1010        | line 1010 emulatorSIGEMT  | EMT_EMU1111        | line 1111 emulatorSIGILL  | ILL_ILLINSTR_FAULT | coprocessor protocol violationSIGFMT  | NULL               | format errorSIGFPE  | FPE_FLTBSUN_TRAP   | compare unorderedSIGFPE  | FPE_FLTINEX_TRAP   | inexact resultSIGFPE  | FPE_FLTDIV_TRAP    | divide by zeroSIGFPE  | FPE_FLTUND_TRAP    | underflowSIGFPE  | FPE_FLTOPERR_TRAP  | operand errorSIGFPE  | FPE_FLTOVF_TRAP    | overflowSIGFPE  | FPE_FLTNAN_TRAP    | signaling "Not A Number".TE.SS "SPARC".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal | Code                | Exception_SIGBUS | BUS_INSTR_ACCESS    | bus error on instruction fetchSIGBUS | BUS_ALIGN           | address error (bad alignment)SIGBUS | BUS_DATA_ACCESS     | bus error on data accessSIGILL | ILL_ILLINSTR_FAULT  | illegal instructionSIGILL | ILL_PRIVINSTR_FAULT | privilege violationSIGILL | ILL_COPROC_DISABLED | coprocessor disabledSIGILL | ILL_COPROC_EXCPTN   | coprocessor exceptionSIGILL | ILL_TRAP_FAULT(n)   | uninitialized user trapSIGFPE | FPE_FPA_ENABLE      | floating point disabledSIGFPE | FPE_FPA_ERROR       | floating point exceptionSIGFPE | FPE_INTDIV_TRAP     | zero divideSIGEMT | EMT_TAG             | tag overflow.TE.SS "Intel i960".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code                           | Exception_SIGBUS  | BUS_UNALIGNED                  | address error (bad alignment)SIGBUS  | BUS_BUSERR                     | bus errorSIGILL  | ILL_INVALID_OPCODE             | invalid instructionSIGILL  | ILL_UNIMPLEMENTED              | instr fetched from on-chip RAMSIGILL  | ILL_INVALID_OPERAND            | invalid operandSIGILL  | ILL_CONSTRAINT_RANGE           | constraint range failureSIGILL  | ILL_PRIVILEGED                 | privilege violationSIGILL  | ILL_LENGTH                     | bad index to sys procedure tableSIGILL  | ILL_TYPE_MISMATCH              | privilege violationSIGTRAP | TRAP_INSTRUCTION_TRACE         | instruction trace faultSIGTRAP | TRAP_BRANCH_TRACE              | branch trace faultSIGTRAP | TRAP_CALL_TRACE                | call trace faultSIGTRAP | TRAP_RETURN_TRACE              | return trace faultSIGTRAP | TRAP_PRERETURN_TRACE           | pre-return trace faultSIGTRAP | TRAP_SUPERVISOR_TRACE          | supervisor trace faultSIGTRAP | TRAP_BREAKPOINT_TRACE          | breakpoint trace faultSIGFPE  | FPE_INTEGER_OVERFLOW           | integer overflowSIGFPE  | FST_ZERO_DIVIDE                | integer zero divideSIGFPE  | FPE_FLOATING_OVERFLOW          | floating point overflowSIGFPE  | FPE_FLOATING_UNDERFLOW         | floating point underflowSIGFPE  | FPE_FLOATING_INVALID_OPERATION | invalid floating point operationSIGFPE  | FPE_FLOATING_ZERO_DIVIDE       | floating point zero divideSIGFPE  | FPE_FLOATING_INEXACT           | floating point inexactSIGFPE  | FPE_FLOATING_RESERVED_ENCODING | floating point reserved encoding.TE.SS "MIPS R3000/R4000".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code | Exception_SIGBUS  | BUS_TLBMOD          | TLB modifiedSIGBUS  | BUS_TLBL            | TLB miss on a load instructionSIGBUS  | BUS_TLBS            | TLB miss on a store instructionSIGBUS  | BUS_ADEL            | address error (bad alignment) on load instrSIGBUS  | BUS_ADES            | address error (bad alignment) on store instrSIGSEGV | SEGV_IBUS           | bus error (instruction)SIGSEGV | SEGV_DBUS           | bus error (data)SIGTRAP | TRAP_SYSCALL        | syscall instruction executedSIGTRAP | TRAP_BP             | break instruction executedSIGILL  | ILL_ILLINSTR_FAULT  | reserved instructionSIGILL  | ILL_COPROC_UNUSABLE | coprocessor unusableSIGFPE  | FPE_FPA_UIO, SIGFPE | unimplemented FPA operationSIGFPE  | FPE_FLTNAN_TRAP     | invalid FPA operationSIGFPE  | FPE_FLTDIV_TRAP     | FPA divide by zeroSIGFPE  | FPE_FLTOVF_TRAP     | FPA overflow exceptionSIGFPE  | FPE_FLTUND_TRAP     | FPA underflow exceptionSIGFPE  | FPE_FLTINEX_TRAP    | FPA inexact operation.TE.SS "Intel i386/i486".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code                 | Exception_SIGILL  | ILL_DIVIDE_ERROR     | divide errorSIGEMT  | EMT_DEBUG            | debugger callSIGILL  | ILL_NON_MASKABLE     | NMI interruptSIGEMT  | EMT_BREAKPOINT       | breakpointSIGILL  | ILL_OVERFLOW         | INTO-detected overflowSIGILL  | ILL_BOUND            | bound range exceededSIGILL  | ILL_INVALID_OPCODE   | invalid opcodeSIGFPE  | FPE_NO_DEVICE        | device not availableSIGILL  | ILL_DOUBLE_FAULT     | double faultSIGFPE  | FPE_CP_OVERRUN       | coprocessor segment overrunSIGILL  | ILL_INVALID_TSS      | invalid task state segmentSIGBUS  | BUS_NO_SEGMENT       | segment not presentSIGBUS  | BUS_STACK_FAULT      | stack exceptionSIGILL  | ILL_PROTECTION_FAULT | general protectionSIGBUS  | BUS_PAGE_FAULT       | page faultSIGILL  | ILL_RESERVED         | (intel reserved)SIGFPE  | FPE_CP_ERROR         | coprocessor errorSIGBUS  | BUS_ALIGNMENT        | alignment check.TE.SS "PowerPC".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code                 | Exception_SIGBUS  | _EXC_OFF_MACH        | machine checkSIGBUS  | _EXC_OFF_INST        | instruction accessSIGBUS  | _EXC_OFF_ALIGN       | alignmentSIGILL  | _EXC_OFF_PROG        | programSIGBUS  | _EXC_OFF_DATA        | data accessSIGFPE  | _EXC_OFF_FPU         | floating point unavailableSIGTRAP | _EXC_OFF_DBG         | debug exception (PPC403)SIGTRAP | _EXC_OFF_INST_BRK    | inst. breakpoint (PPC603, PPCEC603, PPC604)SIGTRAP | _EXC_OFF_TRACE       | trace (PPC603, PPCEC603, PPC604, PPC860)SIGBUS  | _EXC_OFF_CRTL        | critical interrupt (PPC403)SIGILL  | _EXC_OFF_SYSCALL     | system call.TE.SS "Hitachi SH770x".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal  | Code                       | Exception_SIGSEGV | TLB_LOAD_MISS              | TLB miss/invalid (load)SIGSEGV | TLB_STORE_MISS             | TLB miss/invalid (store)SIGSEGV | TLB_INITITIAL_PAGE_WRITE   | Initial page writeSIGSEGV | TLB_LOAD_PROTEC_VIOLATION  | TLB protection violation (load)SIGSEGV | TLB_STORE_PROTEC_VIOLATION | TLB protection violation (store)SIGBUS  | BUS_LOAD_ADDRESS_ERROR     | Address error (load)SIGBUS  | BUS_STORE_ADDRESS_ERROR    | Address error (store)SIGILL  | ILLEGAL_INSTR_GENERAL      | general illegal instructionSIGILL  | ILLEGAL_SLOT_INSTR         | slot illegal instructionSIGFPE  | FPE_INTDIV_TRAP            | integer zero divide.TE.SS "Hitachi SH7604/SH704x/SH703x/SH702x".TStab(|);lf3 lf3 lf3l1p8 l0p8 l.Signal | Code                 | Exception_SIGILL | ILL_ILLINSTR_GENERAL | general illegal instructionSIGILL | ILL_ILLINSTR_SLOT    | slot illegal instructionSIGBUS | BUS_ADDERR_CPU       | CPU address errorSIGBUS | BUS_ADDERR_DMA       | DMA address errorSIGFPE | FPE_INTDIV_TRAP      | integer zero divide.TETwo signals are provided for application use: SIGUSR1 and SIGUSR2.  VxWorks will never use these signals; however, other signals may be used byVxWorks in the future.INTERNAL:	WINDVIEW INSTRUMENTATIONLevel 1:        signal() causes EVENT_SIGNAL        sigsuspend() causes EVENT_SIGSUSPEND        pause() causes EVENT_PAUSE        kill() causes EVENT_KILL        sigWrapper() causes EVENT_SIGWRAPPERLevel 2:        sigsuspend() causes EVENT_OBJ_SIGSUSPEND        pause() causes EVENT_OBJ_SIGPAUSE        sigtimedwait() causes EVENT_OBJ_SIGWAIT        sigWindPendKill() causes EVENT_OBJ_SIGKILLLevel 3:        N/AINTERNAL:  raise                           sigreturn                         sigwaitinfo    |                                   \                             /  kill         sigPendKill            sigprocmask  sigsuspend  sigtimedwait    |               |                       \_________/            |sigWindKill         |                            |                 |    |               |                            |                 |     \_____   _____/                             |                 |           \ /                              sigPendRun             |      sigWindPendKill                            |                 |            |                                    |\_______   _____/            |\__________________________________ |        \ /            |    (->if I sent myself a sig ->)  \|     sigPendGet            |                                    |            |                                    |            |\_sigWindRestart                    |            |\__sigCtxStackEnd                   |             \__sigCtxSetup         _sigCtxSave_/                                       _________________________________________                  |                                       |                  |        ----------->sigWrapper         |                  |                        |              |                  |                    sigreturn          |                  |_______________________________________|                   ran in context of task receiving signalThe function sigstack is not, and will not be implemented.All other functions below are done.		BSD 4.3		POSIX	-------		-----	sigmask		sigemptyset sigfillset sigaddset sigdelset sigismember	sigblock	sigprocmask	sigsetmask	sigprocmask	pause		sigsuspend	sigvec		sigaction	sigstack	(none)	sigreturn	(none)	(none)		sigpending	signal		signalThe only major difference between this and posix is that the default actionwhen a signal occurs in vxWorks is to ignore it and in Posix is to kill theprocess.INCLUDE FILES: signal.hSEE ALSO: intLib, IEEE .I "POSIX 1003.1b,"