siglib.c

VXWORKS源代码

/* 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 code
01l,20apr00,hk   changed sysBErrVecNum to excBErrVecNum for SH.
01k,03mar00,zl   merged SH support into T2
01j,18aug98,tpr  added PowerPC EC 603 support.
02l,08may98,pr   added extra parameter in WV macro
02k,23jan98,pr   commented out some of the WindView code
02j,13dec97,pr   added ifdef WV_INSTRUMENTATION to the WindView code
02i,13nov96,dgp  doc: add PowerPC info to table
02h,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 cleanup
02e,16jan95,rhp  add pointer to POSIX 1003.1b fns in library man page
01w,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_SIGSUSPEND
02a,24mar94,smb  fixed event collection for sigsuspend
01z,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,2227
01u,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_mask
01r,03feb93,jdi  documentation cleanup for 5.1; augmented arch-specific
		 exception tables.
01q,13nov92,dnw  added include of smObjLib.h
01p,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 vector
01m,18aug92,rrr  bug fix for timers.
01l,31jul92,rrr  changed _sig_timeout_recalc to _func_sigTimeoutRecalc
01k,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 scripts
01g,27jul92,rrr  a quick checkin to test timers, still more testing needed.
01f,23jul92,ajm  moved _sig_timeout_recalc to taskLib to shrink proms
01e,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.
*/

/*
DESCRIPTION
This library provides a signal interface for tasks.  Signals are used to
alter the flow control of tasks by communicating asynchronous events
within or between task contexts.  Any task or interrupt service can
"raise" (or send) a signal to a particular task.  The task being signaled
will immediately suspend its current thread of execution and invoke a
task-specified "signal handler" routine.  The signal handler is a
user-supplied routine that is bound to a specific signal and performs
whatever actions are necessary whenever the signal is received.  Signals
are most appropriate for error and exception handling, rather than as a
general purpose intertask communication mechanism.

This library has both a BSD 4.3 and POSIX signal interface.  The POSIX
interface provides a standardized interface which is more functional than
the traditional BSD 4.3 interface.  The chart below shows the correlation
between BSD 4.3 and POSIX 1003.1 functions.  An application should use only one
form of interface and not intermix them.

.TS
tab(|);
lf3 lf3
l   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()
.TE

POSIX 1003.1b (Real-Time Extensions) also specifies a queued-signal
facility that involves four additional routines: sigqueue(),
sigwaitinfo(), and sigtimedwait().

In many ways, signals are analogous to hardware interrupts.  The signal
facility provides a set of 31 distinct signals.  A signal can be raised by
calling kill(), which is analogous to an interrupt or hardware exception.
A signal handler is bound to a particular signal with sigaction() in much
the same way that an interrupt service routine is connected to an
interrupt vector with intConnect().  Signals are blocked for the duration
of the signal handler, just as interrupts are locked out for the duration
of the interrupt service routine.  Tasks can block the occurrence of
certain signals with sigprocmask(), just as the interrupt level can be
raised or lowered to block out levels of interrupts.  If a signal is
blocked when it is raised, its handler routine will be called when the
signal 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 RESTARTING
If a task is pended (for instance, by waiting for a semaphore to become
available) and a signal is sent to the task for which the task has a
handler installed, then the handler will run before the semaphore is
taken.  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 the
signal handler and goes back to being pended.

Signal handlers are typically defined as:
.ne 7
.CS
    void sigHandler
        (
	int sig,			/@ signal number                 @/
        )
	{
            ...
        }
.CE
In VxWorks, the signal handler is passed additional arguments and can be
defined as:
.ne 9
.CS
    void sigHandler
        (
	int sig,			/@ signal number                 @/
        int code,			/@ additional code               @/
        struct sigcontext *pSigContext	/@ context of task before signal @/
        )
	{
            ...
        }
.CE
The parameter <code> is valid only for signals caused by hardware
exceptions.  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 compiler
may issue warnings.)

SIGNAL HANDLER DEFINITION
Signal handling routines must follow one of two specific formats, so that they
may 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 the
POSIX Real-Time Extensions (P1003.1b) support the passing of an additional
application-specific value to the handler routine.  These include signals
generated by the sigqueue() call, by asynchronous I/O, by POSIX real-time
timers, 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 which
is a parameter to the sigaction() routine.  Such routines must take the
following form:

.CS
	void sigHandler (int sigNum, siginfo_t * pInfo, void * pContext);
.CE

Traditional signal handling routines must not set SA_SIGINFO in the sa_flags
field, and must take the form of:

.CS
        void sigHandler (int sigNum);
.CE

EXCEPTION PROCESSING:
Certain signals, defined below, are raised automatically when
hardware exceptions are encountered.  This mechanism allows user-defined
exception handlers to be installed.  This is useful for recovering from
catastrophic events such as bus or arithmetic errors.  Typically, setjmp()
is called to define the point in the program where control will be
restored, and longjmp() is called in the signal handler to restore that
context.  Note that longjmp() restores the state of the task's signal
mask.  If a user-defined handler is not installed or the installed handler
returns for a signal raised by a hardware exception, then the task is
suspended and a message is logged to the console.

The following is a list of hardware exceptions caught by VxWorks and delivered
to the offending task.  The user may include the higher-level header file
sigCodes.h in order to access the appropriate architecture-specific header file
containing the code value.
.SS "Motorola 68K"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal  | Code               | Exception
_
SIGSEGV | NULL               | bus error
SIGBUS  | BUS_ADDERR         | address error
SIGILL  | ILL_ILLINSTR_FAULT | illegal instruction
SIGFPE  | FPE_INTDIV_TRAP    | zero divide
SIGFPE  | FPE_CHKINST_TRAP   | chk trap
SIGFPE  | FPE_TRAPV_TRAP     | trapv trap
SIGILL  | ILL_PRIVVIO_FAULT  | privilege violation
SIGTRAP | NULL               | trace exception
SIGEMT  | EMT_EMU1010        | line 1010 emulator
SIGEMT  | EMT_EMU1111        | line 1111 emulator
SIGILL  | ILL_ILLINSTR_FAULT | coprocessor protocol violation
SIGFMT  | NULL               | format error
SIGFPE  | FPE_FLTBSUN_TRAP   | compare unordered
SIGFPE  | FPE_FLTINEX_TRAP   | inexact result
SIGFPE  | FPE_FLTDIV_TRAP    | divide by zero
SIGFPE  | FPE_FLTUND_TRAP    | underflow
SIGFPE  | FPE_FLTOPERR_TRAP  | operand error
SIGFPE  | FPE_FLTOVF_TRAP    | overflow
SIGFPE  | FPE_FLTNAN_TRAP    | signaling "Not A Number"
.TE
.SS "SPARC"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal | Code                | Exception
_
SIGBUS | BUS_INSTR_ACCESS    | bus error on instruction fetch
SIGBUS | BUS_ALIGN           | address error (bad alignment)
SIGBUS | BUS_DATA_ACCESS     | bus error on data access
SIGILL | ILL_ILLINSTR_FAULT  | illegal instruction
SIGILL | ILL_PRIVINSTR_FAULT | privilege violation
SIGILL | ILL_COPROC_DISABLED | coprocessor disabled
SIGILL | ILL_COPROC_EXCPTN   | coprocessor exception
SIGILL | ILL_TRAP_FAULT(n)   | uninitialized user trap
SIGFPE | FPE_FPA_ENABLE      | floating point disabled
SIGFPE | FPE_FPA_ERROR       | floating point exception
SIGFPE | FPE_INTDIV_TRAP     | zero divide
SIGEMT | EMT_TAG             | tag overflow
.TE
.SS "Intel i960"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal  | Code                           | Exception
_
SIGBUS  | BUS_UNALIGNED                  | address error (bad alignment)
SIGBUS  | BUS_BUSERR                     | bus error
SIGILL  | ILL_INVALID_OPCODE             | invalid instruction
SIGILL  | ILL_UNIMPLEMENTED              | instr fetched from on-chip RAM
SIGILL  | ILL_INVALID_OPERAND            | invalid operand
SIGILL  | ILL_CONSTRAINT_RANGE           | constraint range failure
SIGILL  | ILL_PRIVILEGED                 | privilege violation
SIGILL  | ILL_LENGTH                     | bad index to sys procedure table
SIGILL  | ILL_TYPE_MISMATCH              | privilege violation
SIGTRAP | TRAP_INSTRUCTION_TRACE         | instruction trace fault
SIGTRAP | TRAP_BRANCH_TRACE              | branch trace fault
SIGTRAP | TRAP_CALL_TRACE                | call trace fault
SIGTRAP | TRAP_RETURN_TRACE              | return trace fault
SIGTRAP | TRAP_PRERETURN_TRACE           | pre-return trace fault
SIGTRAP | TRAP_SUPERVISOR_TRACE          | supervisor trace fault
SIGTRAP | TRAP_BREAKPOINT_TRACE          | breakpoint trace fault
SIGFPE  | FPE_INTEGER_OVERFLOW           | integer overflow
SIGFPE  | FST_ZERO_DIVIDE                | integer zero divide
SIGFPE  | FPE_FLOATING_OVERFLOW          | floating point overflow
SIGFPE  | FPE_FLOATING_UNDERFLOW         | floating point underflow
SIGFPE  | FPE_FLOATING_INVALID_OPERATION | invalid floating point operation
SIGFPE  | FPE_FLOATING_ZERO_DIVIDE       | floating point zero divide
SIGFPE  | FPE_FLOATING_INEXACT           | floating point inexact
SIGFPE  | FPE_FLOATING_RESERVED_ENCODING | floating point reserved encoding
.TE
.SS "MIPS R3000/R4000"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal  | Code | Exception
_
SIGBUS  | BUS_TLBMOD          | TLB modified
SIGBUS  | BUS_TLBL            | TLB miss on a load instruction
SIGBUS  | BUS_TLBS            | TLB miss on a store instruction
SIGBUS  | BUS_ADEL            | address error (bad alignment) on load instr
SIGBUS  | BUS_ADES            | address error (bad alignment) on store instr
SIGSEGV | SEGV_IBUS           | bus error (instruction)
SIGSEGV | SEGV_DBUS           | bus error (data)
SIGTRAP | TRAP_SYSCALL        | syscall instruction executed
SIGTRAP | TRAP_BP             | break instruction executed
SIGILL  | ILL_ILLINSTR_FAULT  | reserved instruction
SIGILL  | ILL_COPROC_UNUSABLE | coprocessor unusable
SIGFPE  | FPE_FPA_UIO, SIGFPE | unimplemented FPA operation
SIGFPE  | FPE_FLTNAN_TRAP     | invalid FPA operation
SIGFPE  | FPE_FLTDIV_TRAP     | FPA divide by zero
SIGFPE  | FPE_FLTOVF_TRAP     | FPA overflow exception
SIGFPE  | FPE_FLTUND_TRAP     | FPA underflow exception
SIGFPE  | FPE_FLTINEX_TRAP    | FPA inexact operation
.TE
.SS "Intel i386/i486"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal  | Code                 | Exception
_
SIGILL  | ILL_DIVIDE_ERROR     | divide error
SIGEMT  | EMT_DEBUG            | debugger call
SIGILL  | ILL_NON_MASKABLE     | NMI interrupt
SIGEMT  | EMT_BREAKPOINT       | breakpoint
SIGILL  | ILL_OVERFLOW         | INTO-detected overflow
SIGILL  | ILL_BOUND            | bound range exceeded
SIGILL  | ILL_INVALID_OPCODE   | invalid opcode
SIGFPE  | FPE_NO_DEVICE        | device not available
SIGILL  | ILL_DOUBLE_FAULT     | double fault
SIGFPE  | FPE_CP_OVERRUN       | coprocessor segment overrun
SIGILL  | ILL_INVALID_TSS      | invalid task state segment
SIGBUS  | BUS_NO_SEGMENT       | segment not present
SIGBUS  | BUS_STACK_FAULT      | stack exception
SIGILL  | ILL_PROTECTION_FAULT | general protection
SIGBUS  | BUS_PAGE_FAULT       | page fault
SIGILL  | ILL_RESERVED         | (intel reserved)
SIGFPE  | FPE_CP_ERROR         | coprocessor error
SIGBUS  | BUS_ALIGNMENT        | alignment check
.TE
.SS "PowerPC"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal  | Code                 | Exception
_
SIGBUS  | _EXC_OFF_MACH        | machine check
SIGBUS  | _EXC_OFF_INST        | instruction access
SIGBUS  | _EXC_OFF_ALIGN       | alignment
SIGILL  | _EXC_OFF_PROG        | program
SIGBUS  | _EXC_OFF_DATA        | data access
SIGFPE  | _EXC_OFF_FPU         | floating point unavailable
SIGTRAP | _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"
.TS
tab(|);
lf3 lf3 lf3
l1p8 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 write
SIGSEGV | 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 instruction
SIGILL  | ILLEGAL_SLOT_INSTR         | slot illegal instruction
SIGFPE  | FPE_INTDIV_TRAP            | integer zero divide
.TE
.SS "Hitachi SH7604/SH704x/SH703x/SH702x"
.TS
tab(|);
lf3 lf3 lf3
l1p8 l0p8 l.
Signal | Code                 | Exception
_
SIGILL | ILL_ILLINSTR_GENERAL | general illegal instruction
SIGILL | ILL_ILLINSTR_SLOT    | slot illegal instruction
SIGBUS | BUS_ADDERR_CPU       | CPU address error
SIGBUS | BUS_ADDERR_DMA       | DMA address error
SIGFPE | FPE_INTDIV_TRAP      | integer zero divide
.TE

Two signals are provided for application use: SIGUSR1 and SIGUSR2.  
VxWorks will never use these signals; however, other signals may be used by
VxWorks in the future.

INTERNAL:
	WINDVIEW INSTRUMENTATION
Level 1:
        signal() causes EVENT_SIGNAL
        sigsuspend() causes EVENT_SIGSUSPEND
        pause() causes EVENT_PAUSE
        kill() causes EVENT_KILL
        sigWrapper() causes EVENT_SIGWRAPPER

Level 2:
        sigsuspend() causes EVENT_OBJ_SIGSUSPEND
        pause() causes EVENT_OBJ_SIGPAUSE
        sigtimedwait() causes EVENT_OBJ_SIGWAIT
        sigWindPendKill() causes EVENT_OBJ_SIGKILL

Level 3:
        N/A

INTERNAL:
  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 signal

The 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		signal

The only major difference between this and posix is that the default action
when a signal occurs in vxWorks is to ignore it and in Posix is to kill the
process.

INCLUDE FILES: signal.h

SEE ALSO: intLib, IEEE 
.I "POSIX 1003.1b,"