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