1*64216313SJoyce McIntosh.\" 2*64216313SJoyce McIntosh.\" The contents of this file are subject to the terms of the 3*64216313SJoyce McIntosh.\" Common Development and Distribution License (the "License"). 4*64216313SJoyce McIntosh.\" You may not use this file except in compliance with the License. 5*64216313SJoyce McIntosh.\" 6*64216313SJoyce McIntosh.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7*64216313SJoyce McIntosh.\" or http://www.opensolaris.org/os/licensing. 8*64216313SJoyce McIntosh.\" See the License for the specific language governing permissions 9*64216313SJoyce McIntosh.\" and limitations under the License. 10*64216313SJoyce McIntosh.\" 11*64216313SJoyce McIntosh.\" When distributing Covered Code, include this CDDL HEADER in each 12*64216313SJoyce McIntosh.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13*64216313SJoyce McIntosh.\" If applicable, add the following below this CDDL HEADER, with the 14*64216313SJoyce McIntosh.\" fields enclosed by brackets "[]" replaced with your own identifying 15*64216313SJoyce McIntosh.\" information: Portions Copyright [yyyy] [name of copyright owner] 16*64216313SJoyce McIntosh.\" 17*64216313SJoyce McIntosh.\" 18c10c16deSRichard Lowe.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved 19*64216313SJoyce McIntosh.\" Copyright 2018 Nexenta Systems, Inc. 20*64216313SJoyce McIntosh.\" 21*64216313SJoyce McIntosh.Dd July 30, 2018 22*64216313SJoyce McIntosh.Dt SEMAPHORE 9F 23*64216313SJoyce McIntosh.Os 24*64216313SJoyce McIntosh.Sh NAME 25*64216313SJoyce McIntosh.Nm semaphore , 26*64216313SJoyce McIntosh.Nm sema_init , 27*64216313SJoyce McIntosh.Nm sema_destroy , 28*64216313SJoyce McIntosh.Nm sema_p , 29*64216313SJoyce McIntosh.Nm sema_p_sig , 30*64216313SJoyce McIntosh.Nm sema_v , 31*64216313SJoyce McIntosh.Nm sema_tryp 32*64216313SJoyce McIntosh.Nd semaphore functions 33*64216313SJoyce McIntosh.Sh SYNOPSIS 34*64216313SJoyce McIntosh.In sys/ksynch.h 35*64216313SJoyce McIntosh.Ft void 36*64216313SJoyce McIntosh.Fo sema_init 37*64216313SJoyce McIntosh.Fa "ksema_t *sp" 38*64216313SJoyce McIntosh.Fa "uint_t val" 39*64216313SJoyce McIntosh.Fa "char *name" 40*64216313SJoyce McIntosh.Fa "ksema_type_t type" 41*64216313SJoyce McIntosh.Fa "void *arg" 42*64216313SJoyce McIntosh.Fc 43*64216313SJoyce McIntosh.Ft void 44*64216313SJoyce McIntosh.Fo sema_destroy 45*64216313SJoyce McIntosh.Fa "ksema_t *sp" 46*64216313SJoyce McIntosh.Fc 47*64216313SJoyce McIntosh.Ft void 48*64216313SJoyce McIntosh.Fo sema_p 49*64216313SJoyce McIntosh.Fa "ksema_t *sp" 50*64216313SJoyce McIntosh.Fc 51*64216313SJoyce McIntosh.Ft void 52*64216313SJoyce McIntosh.Fo sema_v 53*64216313SJoyce McIntosh.Fa "ksema_t *sp" 54*64216313SJoyce McIntosh.Fc 55*64216313SJoyce McIntosh.Ft int 56*64216313SJoyce McIntosh.Fo sema_p_sig 57*64216313SJoyce McIntosh.Fa "ksema_t *sp" 58*64216313SJoyce McIntosh.Fc 59*64216313SJoyce McIntosh.Ft int 60*64216313SJoyce McIntosh.Fo sema_tryp 61*64216313SJoyce McIntosh.Fa "ksema_t *sp" 62*64216313SJoyce McIntosh.Fc 63*64216313SJoyce McIntosh.Sh INTERFACE LEVEL 64*64216313SJoyce McIntoshillumos DDI specific (illumos DDI). 65*64216313SJoyce McIntosh.Sh PARAMETERS 66*64216313SJoyce McIntosh.Bl -tag -width Ds 67*64216313SJoyce McIntosh.It Fa sp 68*64216313SJoyce McIntoshA pointer to a semaphore, type 69*64216313SJoyce McIntosh.Vt ksema_t . 70*64216313SJoyce McIntosh.It Fa val 71c10c16deSRichard LoweInitial value for semaphore. 72*64216313SJoyce McIntosh.It Fa name 73*64216313SJoyce McIntoshDescriptive string. 74*64216313SJoyce McIntoshThis is obsolete and should be 75*64216313SJoyce McIntosh.Dv NULL . 76*64216313SJoyce McIntosh.Po Non- Ns 77*64216313SJoyce McIntosh.Dv NULL 78*64216313SJoyce McIntoshstrings are legal, but they are a waste of kernel memory. 79*64216313SJoyce McIntosh.Pc 80*64216313SJoyce McIntosh.It Fa type 81*64216313SJoyce McIntoshVariant type of the semaphore. 82*64216313SJoyce McIntoshCurrently, only 83*64216313SJoyce McIntosh.Dv SEMA_DRIVER 84*64216313SJoyce McIntoshis supported. 85*64216313SJoyce McIntosh.It Fa arg 86*64216313SJoyce McIntoshType-specific argument; should be 87*64216313SJoyce McIntosh.Dv NULL . 88*64216313SJoyce McIntosh.El 89*64216313SJoyce McIntosh.Sh DESCRIPTION 90*64216313SJoyce McIntoshThese functions implement counting semaphores as described by Dijkstra. 91*64216313SJoyce McIntoshA semaphore has a value which is atomically decremented by 92*64216313SJoyce McIntosh.Fn sema_p 93*64216313SJoyce McIntoshand atomically incremented by 94*64216313SJoyce McIntosh.Fn sema_v . 95*64216313SJoyce McIntoshThe value must always be greater than or equal to zero. 96*64216313SJoyce McIntoshIf 97*64216313SJoyce McIntosh.Fn sema_p 98*64216313SJoyce McIntoshis called and the value is zero, the calling thread is blocked until another 99*64216313SJoyce McIntoshthread performs a 100*64216313SJoyce McIntosh.Fn sema_v 101c10c16deSRichard Loweoperation on the semaphore. 102*64216313SJoyce McIntosh.Pp 103*64216313SJoyce McIntoshSemaphores are initialized by calling 104*64216313SJoyce McIntosh.Fn sema_init . 105*64216313SJoyce McIntoshThe argument, 106*64216313SJoyce McIntosh.Fa val , 107*64216313SJoyce McIntoshgives the initial value for the semaphore. 108*64216313SJoyce McIntoshThe semaphore storage is provided by the caller but more may be dynamically 109*64216313SJoyce McIntoshallocated, if necessary, by 110*64216313SJoyce McIntosh.Fn sema_init . 111*64216313SJoyce McIntoshFor this reason, 112*64216313SJoyce McIntosh.Fn sema_destroy 113*64216313SJoyce McIntoshshould be called before deallocating the storage containing the semaphore. 114*64216313SJoyce McIntosh.Pp 115*64216313SJoyce McIntoshThe 116*64216313SJoyce McIntosh.Fn sema_p_sig 117*64216313SJoyce McIntoshfunction decrements the semaphore, as does 118*64216313SJoyce McIntosh.Fn sema_p . 119*64216313SJoyce McIntoshHowever, if the semaphore value is zero, 120*64216313SJoyce McIntosh.Fn sema_p_sig 121*64216313SJoyce McIntoshwill return without decrementing the value if a signal 122*64216313SJoyce McIntosh.Po that is, from 123*64216313SJoyce McIntosh.Xr kill 2 124*64216313SJoyce McIntosh.Pc 125*64216313SJoyce McIntoshis pending for the thread. 126*64216313SJoyce McIntosh.Pp 127*64216313SJoyce McIntoshThe 128*64216313SJoyce McIntosh.Fn sema_tryp 129*64216313SJoyce McIntoshfunction will decrement the semaphore value only if it is greater than zero, and 130*64216313SJoyce McIntoshwill not block. 131*64216313SJoyce McIntosh.Sh CONTEXT 132c10c16deSRichard LoweThese functions can be called from user, interrupt, or kernel context, except 133*64216313SJoyce McIntoshfor 134*64216313SJoyce McIntosh.Fn sema_init 135*64216313SJoyce McIntoshand 136*64216313SJoyce McIntosh.Fn sema_destroy , 137*64216313SJoyce McIntoshwhich can be called from user or kernel context only. 138*64216313SJoyce McIntoshNone of these functions can be called from a high-level interrupt context. 139*64216313SJoyce McIntoshIn most cases, 140*64216313SJoyce McIntosh.Fn sema_v 141*64216313SJoyce McIntoshand 142*64216313SJoyce McIntosh.Fn sema_p 143*64216313SJoyce McIntoshshould not be called from any interrupt context. 144*64216313SJoyce McIntosh.Pp 145*64216313SJoyce McIntoshIf 146*64216313SJoyce McIntosh.Fn sema_p 147*64216313SJoyce McIntoshis used from interrupt context, lower-priority interrupts will not be serviced 148*64216313SJoyce McIntoshduring the wait. 149*64216313SJoyce McIntoshThis means that if the thread that will eventually perform the 150*64216313SJoyce McIntosh.Fn sema_v 151*64216313SJoyce McIntoshbecomes blocked on anything that requires the lower-priority interrupt, the 152*64216313SJoyce McIntoshsystem will hang. 153*64216313SJoyce McIntosh.Pp 154*64216313SJoyce McIntoshFor example, the thread that will perform the 155*64216313SJoyce McIntosh.Fn sema_v 156*64216313SJoyce McIntoshmay need to first allocate memory. 157*64216313SJoyce McIntoshThis memory allocation may require waiting for paging I/O to complete, which may 158*64216313SJoyce McIntoshrequire a lower-priority disk or network interrupt to be serviced. 159*64216313SJoyce McIntoshIn general, situations like this are hard to predict, so it is advisable to 160*64216313SJoyce McIntoshavoid waiting on semaphores or condition variables in an interrupt context. 161*64216313SJoyce McIntosh.Pp 162*64216313SJoyce McIntoshSimilar to many other synchronization mechanisms, semaphores should not be used 163*64216313SJoyce McIntoshin any code path that requires synchronization while handling system panic, at 164*64216313SJoyce McIntoshwhich time many of the semaphore operations become no-ops. 165*64216313SJoyce McIntosh.Sh RETURN VALUES 166*64216313SJoyce McIntosh.Bl -tag -width Ds 167*64216313SJoyce McIntosh.It Li 0 168*64216313SJoyce McIntosh.Fn sema_tryp 169*64216313SJoyce McIntoshcould not decrement the semaphore value because it was zero. 170*64216313SJoyce McIntosh.It Li 1 171*64216313SJoyce McIntosh.Fn sema_p_sig 172*64216313SJoyce McIntoshwas not able to decrement the semaphore value and detected a pending signal. 173*64216313SJoyce McIntosh.El 174*64216313SJoyce McIntosh.Sh SEE ALSO 175*64216313SJoyce McIntosh.Xr kill 2 , 176*64216313SJoyce McIntosh.Xr condvar 9F , 177*64216313SJoyce McIntosh.Xr mutex 9F 178*64216313SJoyce McIntosh.Pp 179*64216313SJoyce McIntosh.Em Writing Device Drivers 180