1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
.\" This -*- nroff -*- file has been generated from
.\" DocBook SGML with docbook-to-man on Debian GNU/Linux.
...\"
...\" transcript compatibility for postscript use.
...\"
...\" synopsis: .P! <file.ps>
...\"
.de P!
\\&.
.fl \" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl \" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u \" move below the image
..
.de pF
.ie \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie !\\*(f4 \{\
. ft \\*(f4
. ds f4\"
' br \}
.el .ie !\\*(f3 \{\
. ft \\*(f3
. ds f3\"
' br \}
.el .ie !\\*(f2 \{\
. ft \\*(f2
. ds f2\"
' br \}
.el .ie !\\*(f1 \{\
. ft \\*(f1
. ds f1\"
' br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
'\" t
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
.TH "rtlinux_sigaction, rtlinux_sigprocmask" "3"
.SH "NAME"
rtlinux_sigaction, rtlinux_sigprocmask \(em RTLinux V3 User-Level signal handling functions.
.SH "SYNOPSIS"
.PP
.nf
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
#include <rtlinux_signal.h>
int \fBrtlinux_sigaction\fP(int \fBsignum\fR, struct rtlinux_sigaction * \fBact\fR, struct rtlinux_sigaction * \fBoldact\fR);
int \fBrtlinux_sigprocmask\fP(int \fBhow\fR, rtlinux_sigset_t * \fBset\fR, rtlinux_sigset_t * \fBoldset\fR);
.fi
.SH "DESCRIPTION"
.PP
This is introduced in V3 RTLinux.
The \fBrtlinux_sigaction\fP function call is used to request
delivery of a real-time event and assign a handler for that event. Its
semantics are similar to \fBsigaction(3)\fP 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.
.PP
\fBsignum\fR specifies the signal number. Signal numbers 0 up to (but
not including) \fBRTLINUX_SIGTIMER0\fP are hardware IRQ's. So,
signal 3 represents IRQ 3. Signal numbers \fBRTLINUX_SIGTIMER0\fP
and above are timer events.
.PP
If \fBact\fR is non-NULL, the new action for signal
\fBsignum\fR is installed from \fBact\fR.
Unlike with \fBsigaction\fP, \fBoldact\fR is
ignored and may be NULL or non-NULL. The call to
\fBrtlinux_sigaction\fP does not change or read
\fBoldact\fR.
.PP
The \fBrtlinux_sigaction\fR structure is defined as
.PP
.nf
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
\f(CW struct rtlinux_sigaction
{
void (*sa_handler)(int);
rtlinux_sigset_t sa_mask;
int sa_flags;
hrtime_t sa_period;
};\fR
.fi
.PP
\fBsa_handler\fR specifies the action to be associated with
\fBsignum\fR and may be \fBRTLINUX_SIG_DFL\fP for the default action, \fBRTLINUX_SIG_IGN\fP to ignore the
signal, or a pointer to a signal handling function.
.PP
\fBsa_period\fR is the period (in nanoseconds) between signals
sent to the process when \fBsignum\fR is
\fBRTLINUX_SIGTIMER0\fP or above. Only one timer signal will
be delivered in \fBsa_period\fR nanoseconds when
\fBRTLINUX_SA_ONESHOT\fP is set in
\fBsa_flags\fR. If \fBRTLINUX_SA_ONESHOT\fP is
not set then the signal handler is automatically reinstalled each signal
delivery (this is the default behavior).
.PP
\fBsa_flags\fR 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:
.IP "\fBRTLINUX_SA_ONESHOT\fP or
\fBRTLINUX_SA_RESETHAND\fP" 10
Restore the signal action to the default state once signal
handler has been called. (NOTE: \fBRTLINUX_SA_ONESHOT\fP and
\fBRTLINUX_SA_RESETHAND\fP have the same value; read
\fBRTLINUX_SA_RESETHAND\fP as "reset the handler to the default
handler after the specified handler is called".)
.IP "RTLINUX_SA_PERIODIC" 10
Re-install the specified signal handler each signal delivery
(default behavior).
.PP
The \fBrtlinux_sigprocmask\fP call is used to change the list
of currently blocked RTLinux signals, similar to
\fBsigprocmask\fP in libc. The behavior of the call is
dependant on the value of \fBhow\fR, as follows.
.IP "\fBRTLINUX_SIG_BLOCK\fP" 10
The set of blocked signals is the union of the current set and
the \fBset\fR argument.
.IP "\fBRTLINUX_SIG_UNBLOCK\fP" 10
The signals in \fBset\fR are removed from the
current set of blocked signals. It is legal to attempt to unblock a signal
which is not blocked.
.IP "\fBRTLINUX_SIG_SETMASK\fP" 10
The set of blocked signals is set to the current argument
\fBset\fR.
.PP
If \fBoldset\fR is non-NULL, the previous value of the signal
mask is stored in \fBoldset\fR.
.SH "RETURN VALUES"
.PP
\fBrtlinux_sigaction\fP and
\fBrtlinux_sigprocmask\fP return 0 on success and -1 on error.
.SH "ERRORS"
.IP "EINVAL" 10
An invalid signal was specified.
.IP "EFAULT" 10
\fBact\fR, \fBoldact\fR,
\fBset\fR or \fBoldset\fR point to memory
which is not a valid part of the address space.
.SH "NOTES"
.PP
This function is only available in Linux user processes. RTLinux threads can not use this function.
.PP
It is necessary for the RTLinux modules to be loaded for these calls to
succeed.
.PP
During a call to rtlinux_sigaction, \fBmlockall\fP 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.
.PP
The handler assigned in the call to \fBrtlinux_sigaction\fP 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.
.PP
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.
.PP
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.
.PP
To manipulate RTLinux signal sets (rtlinux_sigset_t) use the
\fBrtlinux_sigsetops\fP(3).
To see which RTLinux signals are available, see
\fBrtlinux_signal\fP(3).
.SH "EXAMPLES"
.PP
See the RTLinux distribution examples/psc directory for further examples.
.PP
\fBrequest_irq()\fP functionality can be implemented as:
.PP
.nf
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
\f(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 irq\n");
perror("rtlinux_sigaction");
return -1;
}\fR
.fi
.PP
.PP
\fBfree_irq()\fP functionality can be implemented with:
.PP
.nf
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
\f(CW struct rtlinux_sigaction sig, oldsig;
int irq = 4;
sig.sa_handler = RTLINUX_SIG_IGN;
/* free the irq */
rtlinux_sigaction( irq, & sig, & oldsig );\fR
.fi
.PP
.SH "AUTHORS"
.PP
Cort Dougan (\fIcort@fsmlabs.com (link to URL mailto:cort@fsmlabs.com) \fR)
.PP
Nathan Paul Simons (\fInpsimons@fsmlabs.com (link to URL mailto:npsimons@fsmlabs.com) \fR)
.SH "SEE ALSO"
\fIUNIX spec sigaction(2) (link to URL ../susv2/xsh/sigaction.html) \fR, \fIUNIX spec sigprocmask(2) (link to URL ../susv2/xsh/sigprocmask.html) \fR, \fIrtlinux_sigsetops(3) (link to URL rtlinux_sigsetops.3.html) \fR, \fIrtlinux_signal(3) (link to URL rtlinux_signal.3.html) \fR
.PP
\(co2001 FSMLabs Inc.
.PP
All rights reserved.
...\" created by instant / docbook-to-man, Wed 13 Jun 2001, 17:58
|
