kmalloc: Avoid code duplication.
[dragonfly.git] / share / man / man9 / lwbuf.9
blob60122927037a266b7c32f358652c2b384119474b
1 .\" Copyright (c) 2010 by The DragonFly Project and Samuel J. Greear.
2 .\" All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to The DragonFly Project
5 .\" by Samuel J. Greear <sjg@thesjg.com>
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\"    notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\"    notice, this list of conditions and the following disclaimer in
15 .\"    the documentation and/or other materials provided with the
16 .\"    distribution.
17 .\" 3. Neither the name of The DragonFly Project nor the names of its
18 .\"    contributors may be used to endorse or promote products derived
19 .\"    from this software without specific, prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .Dd March 17, 2010
35 .Dt LWBUF 9
36 .Os
37 .Sh NAME
38 .Nm lwbuf_alloc ,
39 .Nm lwbuf_free ,
40 .Nm lwbuf_page ,
41 .Nm lwbuf_kva ,
42 .Nm lwbuf_set_global
43 .Nd lightweight buffers
44 .Sh SYNOPSIS
45 .In cpu/lwbuf.h
46 .Ft "struct lwbuf *"
47 .Fn lwbuf_alloc "vm_page_t m" "struct lwbuf *"
48 .Ft void
49 .Fn lwbuf_free "struct lwbuf *lwb"
50 .Ft vm_page_t
51 .Fn lwbuf_page "struct lwbuf *lwb"
52 .Ft vm_offset_t
53 .Fn lwbuf_kva "struct lwbuf *lwb"
54 .Ft void
55 .Fn lwbuf_set_global "struct lwbuf *lwb"
56 .Sh DESCRIPTION
57 The
58 .Nm lwbuf
59 kernel functions are used for maintaining a lightweight reference to and
60 accessing an arbitrary
61 .Vt vm_page_t .
62 .Pp
63 .Fn lwbuf_alloc
64 returns a pointer to a lightweight buffer representing
65 .Fa m .
66 The
67 .Fa lwb
68 argument is an lwbuf structure, used to avoid allocation of an lwbuf
69 on the x86_64 architecture.
70 .Pp
71 .Fn lwbuf_free
72 frees all resources associated with the lightweight buffer
73 .Fa lwb .
74 .Pp
75 .Fn lwbuf_page
76 and
77 .Fn lwbuf_kva
78 return the associated
79 .Vt vm_page_t
81 .Vt vm_offset_t
82 of the lightweight buffer
83 .Fa lwb .
84 .Pp
85 .Fn lwbuf_set_global
86 ensures that a
87 .Vt vm_offset_t
88 previously obtained through
89 .Fa lwbuf_kva
90 will be valid on all processors without subsequent calls to
91 .Fa lwbuf_kva .
92 It should not be used.
93 .Sh IMPLEMENTATION NOTES
94 The implementation of
95 .Nm lwbuf
96 is CPU-dependent.
97 On x86_64 the
98 kernel maintains a direct map of KVA covering all physical memory.
99 .Pp
100 Lightweight buffers are thread and cross-processor safe with a number of
101 limitations.
102 Allocated buffers are not internally cached or reference counted.
103 Any consumer of lightweight buffers may elect to share allocated buffers
104 or allow them to be used in other threads or on other processors, but care
105 must be taken.
106 Buffers must be externally refcounted or in some other manner
107 freed only after last use.
108 .Sh HISTORY
110 .Nm lwbuf
111 implementation first appeared in
112 .Dx 2.5 .
113 .Sh AUTHORS
115 .Nm lwbuf
116 implementation and this manpage were written by
117 .An Samuel J. Greear .