share/man/man9/serializer.9

   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.2 2007/04/03 09:14:33 swildner Exp $
  33 .\"
  34 .Dd March 31, 2007
  35 .Os
  36 .Dt SERIALIZER 9
  37 .Sh NAME
  38 .Nm lwkt_serialize_init ,
  39 .Nm lwkt_serialize_enter ,
  40 .Nm lwkt_serialize_try ,
  41 .Nm lwkt_serialize_exit ,
  42 .Nm lwkt_serialize_handler_enable ,
  43 .Nm lwkt_serialize_handler_disable ,
  44 .Nm lwkt_serialize_handler_call ,
  45 .Nm lwkt_serialize_handler_try ,
  46 .Nm ASSERT_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 int
  55 .Fn lwkt_serialize_try "lwkt_serialize_t s"
  56 .Ft void
  57 .Fn lwkt_serialize_exit "lwkt_serialize_t s"
  58 .Ft void
  59 .Fn lwkt_serialize_handler_enable "lwkt_serialize_t s"
  60 .Ft void
  61 .Fn lwkt_serialize_handler_disable "lwkt_serialize_t s"
  62 .Ft void
  63 .Fo lwkt_serialize_handler_call
  64 .Fa "lwkt_serialize_t s"
  65 .Fa "void (*func)(void *, void *)"
  66 .Fa "void *arg"
  67 .Fa "void *frame"
  68 .Fc
  69 .Ft int
  70 .Fo lwkt_serialize_handler_try
  71 .Fa "lwkt_serialize_t s"
  72 .Fa "void (*func)(void *, void *)"
  73 .Fa "void *arg"
  74 .Fa "void *frame"
  75 .Fc
  76 .Fn ASSERT_SERIALIZED "s"
  77 .Sh DESCRIPTION
  78 The
  79 .Nm serializer
  80 API provides a fast locked-bus-cycle-based serialization facility
  81 that will serialize across blocking conditions.
  82 It is very similar to a lock but much faster for the common case.
  83 .Pp
  84 This API was initially designed to be a replacement for SPL calls, but
  85 may be used whenever a low level exclusive lock (serialization) and/or
  86 interrupt/device interaction is required.
  87 Unlike tokens this serialization is not safe from deadlocks nor is it
  88 recursive, and care must be taken when using it.
  89 Note that
  90 .Xr tsleep 9
  91 will not release a serializer that is being held.
  92 .Pp
  93 There are two primary facilities \(em the serializer facility itself and
  94 an integrated non-stackable interrupt handler disablement facility
  95 used by drivers.
  96 .Pp
  97 .Fn lwkt_serialize_init ,
  98 .Fn lwkt_serialize_enter
  99 and
 100 .Fn lwkt_serialize_exit
 101 respectively initialize, hold and release the serializer
 102 .Fa s .
 103 .Fn lwkt_serialize_try
 104 is a non-blocking version of
 105 .Fn lwkt_serialize_enter .
 106 .Pp
 107 .Fn lwkt_serialize_handler_disable ,
 108 .Fn lwkt_serialize_handler_enable
 109 and
 110 .Fn lwkt_serialize_handler_call
 111 respectively disable, enable and call an interrupt handler
 112 .Fa func
 113 for the serializer
 114 .Fa s .
 115 The arguments
 116 .Fa arg
 117 and
 118 .Fa frame
 119 will be passed to the handler.
 120 .Fn lwkt_serialize_handler_try
 121 is a non-blocking version of
 122 .Fn lwkt_serialize_handler_call .
 123 .Pp
 124 The
 125 .Fn ASSERT_SERIALIZED
 126 macro asserts that the serializer
 127 .Fa s
 128 is being held.
 129 .Sh RETURN VALUES
 130 The
 131 .Fn lwkt_serialize_try
 132 and
 133 .Fn lwkt_serialize_handler_try
 134 functions return 0 on success and 1 on failure.
 135 .Sh FILES
 136 .Pa sys/kern/lwkt_serialize.c
 137 .Sh SEE ALSO
 138 .Xr crit_enter 9 ,
 139 .Xr spinlock 9
 140 .Sh HISTORY
 141 The
 142 .Nm serializer
 143 API first appeared in
 144 .Dx 1.3 .
 145 .Sh AUTHORS
 146 .An -nosplit
 147 The
 148 .Nm serializer
 149 API was written by
 150 .An Matt Dillon .
 151 This manual page was written by
 152 .An Hasso Tepper .