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 January 17, 2014 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 LWKT_SERIALIZE_INITIALIZER , 46.Nm ASSERT_SERIALIZED , 47.Nm ASSERT_NOT_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.Pp 80.Nm LWKT_SERIALIZE_INITIALIZER ; 81.Fn ASSERT_SERIALIZED "s" 82.Fn ASSERT_NOT_SERIALIZED "s" 83.Sh DESCRIPTION 84The 85.Nm serializer 86API provides a fast locked-bus-cycle-based serialization facility 87that will serialize across blocking conditions. 88It is very similar to a lock but much faster for the common case. 89.Pp 90This API was initially designed to be a replacement for SPL calls, 91but may be used whenever a low level exclusive lock (serialization) 92and/or interrupt/device interaction is required. 93If it is used by interrupt, 94callers should enter critical section to prevent the current thread 95holding the serializer being preempted by interrupt thread 96which may try to hold the same serializer. 97Unlike tokens this serialization is not safe from deadlocks 98nor is it recursive, 99and care must be taken when using it. 100Note that 101.Xr tsleep 9 102will not release a serializer that is being held. 103.Pp 104There are two primary facilities \(em the serializer facility itself and 105an integrated non-stackable interrupt handler disablement facility 106used by drivers. 107.Pp 108.Fn lwkt_serialize_init , 109.Fn lwkt_serialize_enter 110and 111.Fn lwkt_serialize_exit 112respectively initialize, hold and release the serializer 113.Fa s . 114.Fn lwkt_serialize_try 115is a non-blocking version of 116.Fn lwkt_serialize_enter . 117.Pp 118.Fn lwkt_serialize_adaptive_enter 119is a special version of 120.Fn lwkt_serialize_enter 121which will try to spin a bit before the current thread is put to sleep 122if the serializer 123.Fa s 124is contended. 125By default, 126.Fn lwkt_serialize_adaptive_enter 127favors spinning over sleeping. 128.Pp 129.Fn lwkt_serialize_handler_disable , 130.Fn lwkt_serialize_handler_enable 131and 132.Fn lwkt_serialize_handler_call 133respectively disable, enable and call an interrupt handler 134.Fa func 135for the serializer 136.Fa s . 137The arguments 138.Fa arg 139and 140.Fa frame 141will be passed to the handler. 142.Fn lwkt_serialize_handler_try 143is a non-blocking version of 144.Fn lwkt_serialize_handler_call . 145.Pp 146The macro 147.Nm LWKT_SERIALIZE_INITIALIZER 148evaluates to an initializer for the serializer. 149.Pp 150The 151.Fn ASSERT_SERIALIZED 152and 153.Fn ASSERT_NOT_SERIALIZED 154macros assert that the serializer 155.Fa s 156is being held/not held. 157.Sh RETURN VALUES 158The 159.Fn lwkt_serialize_handler_try 160function return 0 on success and 1 on failure. 161The 162.Fn lwkt_serialize_try 163function return 1 on success and 0 on failure. 164.Sh FILES 165The serializer itself is implemented in 166.Pa /sys/kern/lwkt_serialize.c . 167The header file 168.Pa /sys/sys/serialize.h 169describes the public interface and the structure of a serializer. 170.Sh SEE ALSO 171.Xr crit_enter 9 , 172.Xr locking 9 , 173.Xr spinlock 9 , 174.Xr zsleep 9 175.Sh HISTORY 176The 177.Nm serializer 178API first appeared in 179.Dx 1.3 . 180.Sh AUTHORS 181.An -nosplit 182The 183.Nm serializer 184API was written by 185.An Matt Dillon . 186This manual page was written by 187.An Hasso Tepper . 188