1.\" 2.\" Copyright (c) 2007 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $DragonFly: src/share/man/man9/serializer.9,v 1.4 2008/05/07 20:03:09 swildner Exp $ 33.\" 34.Dd May 7, 2008 35.Os 36.Dt SERIALIZER 9 37.Sh NAME 38.Nm lwkt_serialize_init , 39.Nm lwkt_serialize_enter , 40.Nm lwkt_serialize_adaptive_enter , 41.Nm lwkt_serialize_try , 42.Nm lwkt_serialize_exit , 43.Nm lwkt_serialize_handler_enable , 44.Nm lwkt_serialize_handler_disable , 45.Nm lwkt_serialize_handler_call , 46.Nm lwkt_serialize_handler_try , 47.Nm ASSERT_SERIALIZED 48.Nd generic low level serializer 49.Sh SYNOPSIS 50.In sys/serialize.h 51.Ft void 52.Fn lwkt_serialize_init "lwkt_serialize_t s" 53.Ft void 54.Fn lwkt_serialize_enter "lwkt_serialize_t s" 55.Ft void 56.Fn lwkt_serialize_adaptive_enter "lwkt_serialize_t s" 57.Ft int 58.Fn lwkt_serialize_try "lwkt_serialize_t s" 59.Ft void 60.Fn lwkt_serialize_exit "lwkt_serialize_t s" 61.Ft void 62.Fn lwkt_serialize_handler_enable "lwkt_serialize_t s" 63.Ft void 64.Fn lwkt_serialize_handler_disable "lwkt_serialize_t s" 65.Ft void 66.Fo lwkt_serialize_handler_call 67.Fa "lwkt_serialize_t s" 68.Fa "void (*func)(void *, void *)" 69.Fa "void *arg" 70.Fa "void *frame" 71.Fc 72.Ft int 73.Fo lwkt_serialize_handler_try 74.Fa "lwkt_serialize_t s" 75.Fa "void (*func)(void *, void *)" 76.Fa "void *arg" 77.Fa "void *frame" 78.Fc 79.Fn ASSERT_SERIALIZED "s" 80.Sh DESCRIPTION 81The 82.Nm serializer 83API provides a fast locked-bus-cycle-based serialization facility 84that will serialize across blocking conditions. 85It is very similar to a lock but much faster for the common case. 86.Pp 87This API was initially designed to be a replacement for SPL calls, but 88may be used whenever a low level exclusive lock (serialization) and/or 89interrupt/device interaction is required. 90Unlike tokens this serialization is not safe from deadlocks nor is it 91recursive, and care must be taken when using it. 92Note that 93.Xr tsleep 9 94will not release a serializer that is being held. 95.Pp 96There are two primary facilities \(em the serializer facility itself and 97an integrated non-stackable interrupt handler disablement facility 98used by drivers. 99.Pp 100.Fn lwkt_serialize_init , 101.Fn lwkt_serialize_enter 102and 103.Fn lwkt_serialize_exit 104respectively initialize, hold and release the serializer 105.Fa s . 106.Fn lwkt_serialize_try 107is a non-blocking version of 108.Fn lwkt_serialize_enter . 109.Pp 110.Fn lwkt_serialize_adaptive_enter 111is a special version of 112.Fn lwkt_serialize_enter 113which will try to spin a bit before the current thread is put to sleep 114if the serializer 115.Fa s 116is contended. 117By default, 118.Fn lwkt_serialize_adaptive_enter 119favors spinning over sleeping. 120This behavior can be changed by tuning the 121.Va debug.serialize_bolimit 122and 123.Va debug.serialize_boround 124.Xr sysctl 8 125variables. 126Note that 127.Fn lwkt_serialize_adaptive_enter 128is only available in SMP kernels. 129.Pp 130.Fn lwkt_serialize_handler_disable , 131.Fn lwkt_serialize_handler_enable 132and 133.Fn lwkt_serialize_handler_call 134respectively disable, enable and call an interrupt handler 135.Fa func 136for the serializer 137.Fa s . 138The arguments 139.Fa arg 140and 141.Fa frame 142will be passed to the handler. 143.Fn lwkt_serialize_handler_try 144is a non-blocking version of 145.Fn lwkt_serialize_handler_call . 146.Pp 147The 148.Fn ASSERT_SERIALIZED 149macro asserts that the serializer 150.Fa s 151is being held. 152.Sh RETURN VALUES 153The 154.Fn lwkt_serialize_try 155and 156.Fn lwkt_serialize_handler_try 157functions return 0 on success and 1 on failure. 158.Sh FILES 159.Pa sys/kern/lwkt_serialize.c 160.Sh SEE ALSO 161.Xr crit_enter 9 , 162.Xr serialize_sleep 9 , 163.Xr spinlock 9 164.Sh HISTORY 165The 166.Nm serializer 167API first appeared in 168.Dx 1.3 . 169.Sh AUTHORS 170.An -nosplit 171The 172.Nm serializer 173API was written by 174.An Matt Dillon . 175This manual page was written by 176.An Hasso Tepper . 177