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