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.Dd April 10, 2010 33.Dt SERIALIZER 9 34.Os 35.Sh NAME 36.Nm lwkt_serialize_init , 37.Nm lwkt_serialize_enter , 38.Nm lwkt_serialize_adaptive_enter , 39.Nm lwkt_serialize_try , 40.Nm lwkt_serialize_exit , 41.Nm lwkt_serialize_handler_enable , 42.Nm lwkt_serialize_handler_disable , 43.Nm lwkt_serialize_handler_call , 44.Nm lwkt_serialize_handler_try , 45.Nm ASSERT_SERIALIZED 46.Nm ASSERT_NOT_SERIALIZED 47.Nd generic low level serializer 48.Sh SYNOPSIS 49.In sys/serialize.h 50.Ft void 51.Fn lwkt_serialize_init "lwkt_serialize_t s" 52.Ft void 53.Fn lwkt_serialize_enter "lwkt_serialize_t s" 54.Ft void 55.Fn lwkt_serialize_adaptive_enter "lwkt_serialize_t s" 56.Ft int 57.Fn lwkt_serialize_try "lwkt_serialize_t s" 58.Ft void 59.Fn lwkt_serialize_exit "lwkt_serialize_t s" 60.Ft void 61.Fn lwkt_serialize_handler_enable "lwkt_serialize_t s" 62.Ft void 63.Fn lwkt_serialize_handler_disable "lwkt_serialize_t s" 64.Ft void 65.Fo lwkt_serialize_handler_call 66.Fa "lwkt_serialize_t s" 67.Fa "void (*func)(void *, void *)" 68.Fa "void *arg" 69.Fa "void *frame" 70.Fc 71.Ft int 72.Fo lwkt_serialize_handler_try 73.Fa "lwkt_serialize_t s" 74.Fa "void (*func)(void *, void *)" 75.Fa "void *arg" 76.Fa "void *frame" 77.Fc 78.Fn ASSERT_SERIALIZED "s" 79.Fn ASSERT_NOT_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 149and 150.Fn ASSERT_NOT_SERIALIZED 151macros assert that the serializer 152.Fa s 153is being held/not held. 154.Sh RETURN VALUES 155The 156.Fn lwkt_serialize_try 157and 158.Fn lwkt_serialize_handler_try 159functions return 0 on success and 1 on failure. 160.Sh FILES 161The serializer itself is implemented in 162.Pa /sys/kern/lwkt_serialize.c . 163The header file 164.Pa /sys/sys/serialize.h 165describes the public interface and the structure of a serializer. 166.Sh SEE ALSO 167.Xr crit_enter 9 , 168.Xr spinlock 9 , 169.Xr zsleep 9 170.Sh HISTORY 171The 172.Nm serializer 173API first appeared in 174.Dx 1.3 . 175.Sh AUTHORS 176.An -nosplit 177The 178.Nm serializer 179API was written by 180.An Matt Dillon . 181This manual page was written by 182.An Hasso Tepper . 183