rtlinux_sigaction, rtlinux_sigprocmask - RTLinux V3 User-Level signal handling functions.

#include <rtlinux_signal.h> 
 
int rtlinux_sigaction(int signum, struct rtlinux_sigaction * act, struct rtlinux_sigaction * oldact); 
 
int rtlinux_sigprocmask(int how, rtlinux_sigset_t * set, rtlinux_sigset_t * oldset); 

This is introduced in V3 RTLinux. The rtlinux_sigaction function call is used to request delivery of a real-time event and assign a handler for that event. Its semantics are similar to sigaction(3) for ease of programming, but it does not affect or interact with normal Linux signals. The handler is called as quickly as hardware allows and does not wait for Linux to become ready (enabling interrupts, releasing locks and so on). Latencies between the requested event and handler code being called is on the order of a few tens of micro-seconds on modern hardware. This low-latency behavior comes with restrictions listed in the NOTES section.

signum specifies the signal number. Signal numbers 0 up to (but not including) RTLINUX_SIGTIMER0 are hardware IRQ's. So, signal 3 represents IRQ 3. Signal numbers RTLINUX_SIGTIMER0 and above are timer events.

If act is non-NULL, the new action for signal signum is installed from act. Unlike with sigaction, oldact is ignored and may be NULL or non-NULL. The call to rtlinux_sigaction does not change or read oldact.

The rtlinux_sigaction structure is defined as

CW	struct rtlinux_sigaction 
{ 
void (*sa_handler)(int); 
rtlinux_sigset_t sa_mask; 
int sa_flags; 
hrtime_t sa_period; 
}; 

sa_handler specifies the action to be associated with signum and may be RTLINUX_SIG_DFL for the default action, RTLINUX_SIG_IGN to ignore the signal, or a pointer to a signal handling function.

sa_period is the period (in nanoseconds) between signals sent to the process when signum is RTLINUX_SIGTIMER0 or above. Only one timer signal will be delivered in sa_period nanoseconds when RTLINUX_SA_ONESHOT is set in sa_flags. If RTLINUX_SA_ONESHOT is not set then the signal handler is automatically reinstalled each signal delivery (this is the default behavior).

sa_flags specifies a set of flags which modify the behavior of the signal handling process. It is formed by the bitwise OR of zero or more of the following:

"RTLINUX_SA_ONESHOT

RTLINUX_SA_RESETHAND" 10 Restore the signal action to the default state once signal handler has been called. (NOTE: RTLINUX_SA_ONESHOT and RTLINUX_SA_RESETHAND have the same value; read RTLINUX_SA_RESETHAND as "reset the handler to the default handler after the specified handler is called".)

RTLINUX_SA_PERIODIC

Re-install the specified signal handler each signal delivery (default behavior).

The rtlinux_sigprocmask call is used to change the list of currently blocked RTLinux signals, similar to sigprocmask in libc. The behavior of the call is dependant on the value of how, as follows.

RTLINUX_SIG_BLOCK

The set of blocked signals is the union of the current set and the set argument.

RTLINUX_SIG_UNBLOCK

The signals in set are removed from the current set of blocked signals. It is legal to attempt to unblock a signal which is not blocked.

RTLINUX_SIG_SETMASK

The set of blocked signals is set to the current argument set.

If oldset is non-NULL, the previous value of the signal mask is stored in oldset.

rtlinux_sigaction and rtlinux_sigprocmask return 0 on success and -1 on error.

EINVAL

An invalid signal was specified.

EFAULT

act, oldact, set or oldset point to memory which is not a valid part of the address space.

This function is only available in Linux user processes. RTLinux threads can not use this function.

It is necessary for the RTLinux modules to be loaded for these calls to succeed.

During a call to rtlinux_sigaction, mlockall is called so currently swapped-in pages and future pages will be locked in memory until this process exits or unlocks its pages. As a result, this call will only succeed when made from a process running as root.

The handler assigned in the call to rtlinux_sigaction will be scheduled and executed by RTLinux and may be run when Linux is unable to provide normal services to the executing code. So, all calls made in the signal handler must be to statically linked libraries; code within the program itself cannot execute system calls. To have services perform the needed actions, one should send requests to the non-RTLinux signal handler part of the program.

Currently, in addition to its own address space, the handler executes with the kernel memory mapped in and accessible (the same as that of the parent), so programmers must take care to not change kernel data structures. This feature allows access to device address space as well.

Since RTLinux signals represent either IRQs or real-time timers, blocking an RTLinux signal will pend the IRQ or timer to which it corresponds. Blocking an IRQ will keep track of how many times that IRQ goes off, then call the installed handler that many times when the IRQ is unblocked. When a timer is blocked and then unblocked, the installed handler will only be called once if the the timer went off one or more times while blocked.

To manipulate RTLinux signal sets (rtlinux_sigset_t) use the rtlinux_sigsetops(3). To see which RTLinux signals are available, see rtlinux_signal(3).

See the RTLinux distribution examples/psc directory for further examples.

request_irq() functionality can be implemented as:

CW	struct rtlinux_sigaction sig, oldsig; 
int irq = 4; 
void handler_function(int); 
 
sig.sa_handler = handler_function; 
sig.sa_flags = RTLINUX_SA_PERIODIC; 
 
if ( rtlinux_sigaction( irq, & sig, & oldsig ) ) 
{ 
printf("Couldn't get irqn"); 
perror("rtlinux_sigaction"); 
return -1; 
} 

free_irq() functionality can be implemented with:

CW	struct rtlinux_sigaction sig, oldsig; 
int irq = 4; 
 
sig.sa_handler = RTLINUX_SIG_IGN; 
/* free the irq */ 
rtlinux_sigaction( irq, & sig, & oldsig ); 

Cort Dougan (cort@fsmlabs.com (link to URL mailto:cort@fsmlabs.com) )

Nathan Paul Simons (npsimons@fsmlabs.com (link to URL mailto:npsimons@fsmlabs.com) )

UNIX spec sigaction(2) (link to URL ../susv2/xsh/sigaction.html) , UNIX spec sigprocmask(2) (link to URL ../susv2/xsh/sigprocmask.html) , rtlinux_sigsetops(3) (link to URL rtlinux_sigsetops.3.html) , rtlinux_signal(3) (link to URL rtlinux_signal.3.html)

©2001 FSMLabs Inc.

All rights reserved.