Print this page
9249 System crash dump to NVME not working
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Reviewed by: Evan Layton <evan.layton@nexenta.com>
Reviewed by: Rick McNeal <rick.mcneal@nexenta.com>
Reviewed by: Ryan Zezeski <rpz@joyent.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9f/semaphore.9f
+++ new/usr/src/man/man9f/semaphore.9f
1 -'\" te
2 -.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
3 -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH SEMAPHORE 9F "May 7, 1997"
7 -.SH NAME
8 -semaphore, sema_init, sema_destroy, sema_p, sema_p_sig, sema_v, sema_tryp \-
9 -semaphore functions
10 -.SH SYNOPSIS
11 -.LP
12 -.nf
13 -#include <sys/ksynch.h>
14 -
15 -
16 -
17 -\fBvoid\fR \fBsema_init\fR(\fBksema_t *\fR\fIsp\fR, \fBuint_t\fR \fIval\fR, \fBchar *\fR\fIname\fR, \fBksema_type_t\fR \fItype\fR,
18 - \fBvoid *\fR\fIarg\fR);
19 -.fi
20 -
21 -.LP
22 -.nf
23 -\fBvoid\fR \fBsema_destroy\fR(\fBksema_t *\fR\fIsp\fR);
24 -.fi
25 -
26 -.LP
27 -.nf
28 -\fBvoid\fR \fBsema_p\fR(\fBksema_t *\fR\fIsp\fR);
29 -.fi
30 -
31 -.LP
32 -.nf
33 -\fBvoid\fR \fBsema_v\fR(\fBksema_t *\fR\fIsp\fR);
34 -.fi
35 -
36 -.LP
37 -.nf
38 -\fBint\fR \fBsema_p_sig\fR(\fBksema_t *\fR\fIsp\fR);
39 -.fi
40 -
41 -.LP
42 -.nf
43 -\fBint\fR \fBsema_tryp\fR(\fBksema_t *\fR\fIsp\fR);
44 -.fi
45 -
46 -.SH INTERFACE LEVEL
47 -.sp
48 -.LP
49 -Solaris \fBDDI\fR specific (Solaris \fBDDI\fR).
50 -.SH PARAMETERS
51 -.sp
52 -.ne 2
53 -.na
54 -\fB\fIsp\fR\fR
55 -.ad
56 -.RS 8n
57 -A pointer to a semaphore, type \fBksema_t\fR.
58 -.RE
59 -
60 -.sp
61 -.ne 2
62 -.na
63 -\fB\fIval\fR\fR
64 -.ad
65 -.RS 8n
1 +.\"
2 +.\" The contents of this file are subject to the terms of the
3 +.\" Common Development and Distribution License (the "License").
4 +.\" You may not use this file except in compliance with the License.
5 +.\"
6 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 +.\" or http://www.opensolaris.org/os/licensing.
8 +.\" See the License for the specific language governing permissions
9 +.\" and limitations under the License.
10 +.\"
11 +.\" When distributing Covered Code, include this CDDL HEADER in each
12 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 +.\" If applicable, add the following below this CDDL HEADER, with the
14 +.\" fields enclosed by brackets "[]" replaced with your own identifying
15 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
16 +.\"
17 +.\"
18 +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
19 +.\" Copyright 2018 Nexenta Systems, Inc.
20 +.\"
21 +.Dd July 30, 2018
22 +.Dt SEMAPHORE 9F
23 +.Os
24 +.Sh NAME
25 +.Nm semaphore ,
26 +.Nm sema_init ,
27 +.Nm sema_destroy ,
28 +.Nm sema_p ,
29 +.Nm sema_p_sig ,
30 +.Nm sema_v ,
31 +.Nm sema_tryp
32 +.Nd semaphore functions
33 +.Sh SYNOPSIS
34 +.In sys/ksynch.h
35 +.Ft void
36 +.Fo sema_init
37 +.Fa "ksema_t *sp"
38 +.Fa "uint_t val"
39 +.Fa "char *name"
40 +.Fa "ksema_type_t type"
41 +.Fa "void *arg"
42 +.Fc
43 +.Ft void
44 +.Fo sema_destroy
45 +.Fa "ksema_t *sp"
46 +.Fc
47 +.Ft void
48 +.Fo sema_p
49 +.Fa "ksema_t *sp"
50 +.Fc
51 +.Ft void
52 +.Fo sema_v
53 +.Fa "ksema_t *sp"
54 +.Fc
55 +.Ft int
56 +.Fo sema_p_sig
57 +.Fa "ksema_t *sp"
58 +.Fc
59 +.Ft int
60 +.Fo sema_tryp
61 +.Fa "ksema_t *sp"
62 +.Fc
63 +.Sh INTERFACE LEVEL
64 +illumos DDI specific (illumos DDI).
65 +.Sh PARAMETERS
66 +.Bl -tag -width Ds
67 +.It Fa sp
68 +A pointer to a semaphore, type
69 +.Vt ksema_t .
70 +.It Fa val
66 71 Initial value for semaphore.
67 -.RE
68 -
69 -.sp
70 -.ne 2
71 -.na
72 -\fB\fIname\fR\fR
73 -.ad
74 -.RS 8n
75 -Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR
76 -strings are legal, but they are a waste of kernel memory.)
77 -.RE
78 -
79 -.sp
80 -.ne 2
81 -.na
82 -\fB\fItype\fR\fR
83 -.ad
84 -.RS 8n
85 -Variant type of the semaphore. Currently, only \fBSEMA_DRIVER\fR is supported.
86 -.RE
87 -
88 -.sp
89 -.ne 2
90 -.na
91 -\fB\fIarg\fR\fR
92 -.ad
93 -.RS 8n
94 -Type-specific argument; should be \fINULL\fR.
95 -.RE
96 -
97 -.SH DESCRIPTION
98 -.sp
99 -.LP
100 -These functions implement counting semaphores as described by Dijkstra. A
101 -semaphore has a value which is atomically decremented by \fBsema_p()\fR and
102 -atomically incremented by \fBsema_v()\fR. The value must always be greater than
103 -or equal to zero. If \fBsema_p()\fR is called and the value is zero, the
104 -calling thread is blocked until another thread performs a \fBsema_v()\fR
72 +.It Fa name
73 +Descriptive string.
74 +This is obsolete and should be
75 +.Dv NULL .
76 +.Po Non- Ns
77 +.Dv NULL
78 +strings are legal, but they are a waste of kernel memory.
79 +.Pc
80 +.It Fa type
81 +Variant type of the semaphore.
82 +Currently, only
83 +.Dv SEMA_DRIVER
84 +is supported.
85 +.It Fa arg
86 +Type-specific argument; should be
87 +.Dv NULL .
88 +.El
89 +.Sh DESCRIPTION
90 +These functions implement counting semaphores as described by Dijkstra.
91 +A semaphore has a value which is atomically decremented by
92 +.Fn sema_p
93 +and atomically incremented by
94 +.Fn sema_v .
95 +The value must always be greater than or equal to zero.
96 +If
97 +.Fn sema_p
98 +is called and the value is zero, the calling thread is blocked until another
99 +thread performs a
100 +.Fn sema_v
105 101 operation on the semaphore.
106 -.sp
107 -.LP
108 -Semaphores are initialized by calling \fBsema_init()\fR. The argument,
109 -\fBval\fR, gives the initial value for the semaphore. The semaphore storage is
110 -provided by the caller but more may be dynamically allocated, if necessary, by
111 -\fBsema_init()\fR. For this reason, \fBsema_destroy()\fR should be called
112 -before deallocating the storage containing the semaphore.
113 -.sp
114 -.LP
115 -The \fBsema_p_sig()\fR function decrements the semaphore, as does
116 -\fBsema_p()\fR. However, if the semaphore value is zero, \fBsema_p_sig()\fR
117 -will return without decrementing the value if a signal (that is, from
118 -\fBkill\fR(2)) is pending for the thread.
119 -.sp
120 -.LP
121 -The \fBsema_tryp()\fR function will decrement the semaphore value only if it is
122 -greater than zero, and will not block.
123 -.SH RETURN VALUES
124 -.sp
125 -.ne 2
126 -.na
127 -\fB\fB0\fR\fR
128 -.ad
129 -.RS 5n
130 -\fBsema_tryp()\fR could not decrement the semaphore value because it was zero.
131 -.RE
132 -
133 -.sp
134 -.ne 2
135 -.na
136 -\fB\fB1\fR\fR
137 -.ad
138 -.RS 5n
139 -\fBsema_p_sig()\fR was not able to decrement the semaphore value and detected a
140 -pending signal.
141 -.RE
142 -
143 -.SH CONTEXT
144 -.sp
145 -.LP
102 +.Pp
103 +Semaphores are initialized by calling
104 +.Fn sema_init .
105 +The argument,
106 +.Fa val ,
107 +gives the initial value for the semaphore.
108 +The semaphore storage is provided by the caller but more may be dynamically
109 +allocated, if necessary, by
110 +.Fn sema_init .
111 +For this reason,
112 +.Fn sema_destroy
113 +should be called before deallocating the storage containing the semaphore.
114 +.Pp
115 +The
116 +.Fn sema_p_sig
117 +function decrements the semaphore, as does
118 +.Fn sema_p .
119 +However, if the semaphore value is zero,
120 +.Fn sema_p_sig
121 +will return without decrementing the value if a signal
122 +.Po that is, from
123 +.Xr kill 2
124 +.Pc
125 +is pending for the thread.
126 +.Pp
127 +The
128 +.Fn sema_tryp
129 +function will decrement the semaphore value only if it is greater than zero, and
130 +will not block.
131 +.Sh CONTEXT
146 132 These functions can be called from user, interrupt, or kernel context, except
147 -for \fBsema_init()\fR and \fBsema_destroy()\fR, which can be called from user
148 -or kernel context only. None of these functions can be called from a high-level
149 -interrupt context. In most cases, \fBsema_v()\fR and \fBsema_p()\fR should not
150 -be called from any interrupt context.
151 -.sp
152 -.LP
153 -If \fBsema_p()\fR is used from interrupt context, lower-priority interrupts
154 -will not be serviced during the wait. This means that if the thread that will
155 -eventually perform the \fBsema_v()\fR becomes blocked on anything that requires
156 -the lower-priority interrupt, the system will hang.
157 -.sp
158 -.LP
159 -For example, the thread that will perform the \fBsema_v()\fR may need to first
160 -allocate memory. This memory allocation may require waiting for paging
161 -\fBI/O\fR to complete, which may require a lower-priority disk or network
162 -interrupt to be serviced. In general, situations like this are hard to predict,
163 -so it is advisable to avoid waiting on semaphores or condition variables in an
164 -interrupt context.
165 -.SH SEE ALSO
166 -.sp
167 -.LP
168 -\fBkill\fR(2), \fBcondvar\fR(9F), \fBmutex\fR(9F)
169 -.sp
170 -.LP
171 -\fIWriting Device Drivers\fR
133 +for
134 +.Fn sema_init
135 +and
136 +.Fn sema_destroy ,
137 +which can be called from user or kernel context only.
138 +None of these functions can be called from a high-level interrupt context.
139 +In most cases,
140 +.Fn sema_v
141 +and
142 +.Fn sema_p
143 +should not be called from any interrupt context.
144 +.Pp
145 +If
146 +.Fn sema_p
147 +is used from interrupt context, lower-priority interrupts will not be serviced
148 +during the wait.
149 +This means that if the thread that will eventually perform the
150 +.Fn sema_v
151 +becomes blocked on anything that requires the lower-priority interrupt, the
152 +system will hang.
153 +.Pp
154 +For example, the thread that will perform the
155 +.Fn sema_v
156 +may need to first allocate memory.
157 +This memory allocation may require waiting for paging I/O to complete, which may
158 +require a lower-priority disk or network interrupt to be serviced.
159 +In general, situations like this are hard to predict, so it is advisable to
160 +avoid waiting on semaphores or condition variables in an interrupt context.
161 +.Pp
162 +Similar to many other synchronization mechanisms, semaphores should not be used
163 +in any code path that requires synchronization while handling system panic, at
164 +which time many of the semaphore operations become no-ops.
165 +.Sh RETURN VALUES
166 +.Bl -tag -width Ds
167 +.It Li 0
168 +.Fn sema_tryp
169 +could not decrement the semaphore value because it was zero.
170 +.It Li 1
171 +.Fn sema_p_sig
172 +was not able to decrement the semaphore value and detected a pending signal.
173 +.El
174 +.Sh SEE ALSO
175 +.Xr kill 2 ,
176 +.Xr condvar 9F ,
177 +.Xr mutex 9F
178 +.Pp
179 +.Em Writing Device Drivers
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX