xref: /dflybsd-src/share/man/man9/lwbuf.9 (revision cf37dc2040cea9f384bd7d3dcaf24014f441b8a6)
15c5185aeSSamuel J. Greear.\" Copyright (c) 2010 by The DragonFly Project and Samuel J. Greear.
25c5185aeSSamuel J. Greear.\" All rights reserved.
35c5185aeSSamuel J. Greear.\"
45c5185aeSSamuel J. Greear.\" This code is derived from software contributed to The DragonFly Project
55c5185aeSSamuel J. Greear.\" by Samuel J. Greear <sjg@thesjg.com>
65c5185aeSSamuel J. Greear.\"
75c5185aeSSamuel J. Greear.\" Redistribution and use in source and binary forms, with or without
85c5185aeSSamuel J. Greear.\" modification, are permitted provided that the following conditions
95c5185aeSSamuel J. Greear.\" are met:
105c5185aeSSamuel J. Greear.\"
115c5185aeSSamuel J. Greear.\" 1. Redistributions of source code must retain the above copyright
125c5185aeSSamuel J. Greear.\"    notice, this list of conditions and the following disclaimer.
135c5185aeSSamuel J. Greear.\" 2. Redistributions in binary form must reproduce the above copyright
145c5185aeSSamuel J. Greear.\"    notice, this list of conditions and the following disclaimer in
155c5185aeSSamuel J. Greear.\"    the documentation and/or other materials provided with the
165c5185aeSSamuel J. Greear.\"    distribution.
175c5185aeSSamuel J. Greear.\" 3. Neither the name of The DragonFly Project nor the names of its
185c5185aeSSamuel J. Greear.\"    contributors may be used to endorse or promote products derived
195c5185aeSSamuel J. Greear.\"    from this software without specific, prior written permission.
205c5185aeSSamuel J. Greear.\"
215c5185aeSSamuel J. Greear.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
225c5185aeSSamuel J. Greear.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
235c5185aeSSamuel J. Greear.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
245c5185aeSSamuel J. Greear.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
255c5185aeSSamuel J. Greear.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
265c5185aeSSamuel J. Greear.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
275c5185aeSSamuel J. Greear.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
285c5185aeSSamuel J. Greear.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
295c5185aeSSamuel J. Greear.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
305c5185aeSSamuel J. Greear.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
315c5185aeSSamuel J. Greear.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
325c5185aeSSamuel J. Greear.\" SUCH DAMAGE.
3368f9b4e3SSascha Wildner.\"
345c5185aeSSamuel J. Greear.Dd March 17, 2010
354041d919SSascha Wildner.Dt LWBUF 9
36fb5b3747SSascha Wildner.Os
375c5185aeSSamuel J. Greear.Sh NAME
385c5185aeSSamuel J. Greear.Nm lwbuf_alloc ,
395c5185aeSSamuel J. Greear.Nm lwbuf_free ,
405c5185aeSSamuel J. Greear.Nm lwbuf_page ,
415c5185aeSSamuel J. Greear.Nm lwbuf_kva ,
425c5185aeSSamuel J. Greear.Nm lwbuf_set_global
4368f9b4e3SSascha Wildner.Nd lightweight buffers
445c5185aeSSamuel J. Greear.Sh SYNOPSIS
455c5185aeSSamuel J. Greear.In cpu/lwbuf.h
465c5185aeSSamuel J. Greear.Ft "struct lwbuf *"
4744c00bd8SVenkatesh Srinivas.Fn lwbuf_alloc "vm_page_t m" "struct lwbuf *"
485c5185aeSSamuel J. Greear.Ft void
495c5185aeSSamuel J. Greear.Fn lwbuf_free "struct lwbuf *lwb"
505c5185aeSSamuel J. Greear.Ft vm_page_t
515c5185aeSSamuel J. Greear.Fn lwbuf_page "struct lwbuf *lwb"
525c5185aeSSamuel J. Greear.Ft vm_offset_t
535c5185aeSSamuel J. Greear.Fn lwbuf_kva "struct lwbuf *lwb"
545c5185aeSSamuel J. Greear.Ft void
555c5185aeSSamuel J. Greear.Fn lwbuf_set_global "struct lwbuf *lwb"
565c5185aeSSamuel J. Greear.Sh DESCRIPTION
575c5185aeSSamuel J. GreearThe
5868f9b4e3SSascha Wildner.Nm lwbuf
595c5185aeSSamuel J. Greearkernel functions are used for maintaining a lightweight reference to and
605c5185aeSSamuel J. Greearaccessing an arbitrary
6168f9b4e3SSascha Wildner.Vt vm_page_t .
625c5185aeSSamuel J. Greear.Pp
635c5185aeSSamuel J. Greear.Fn lwbuf_alloc
645c5185aeSSamuel J. Greearreturns a pointer to a lightweight buffer representing
655c5185aeSSamuel J. Greear.Fa m .
6644c00bd8SVenkatesh SrinivasThe
6744c00bd8SVenkatesh Srinivas.Fa lwb
6844c00bd8SVenkatesh Srinivasargument is an lwbuf structure, used to avoid allocation of an lwbuf
69*cf37dc20SSascha Wildneron the x86_64 architecture.
705c5185aeSSamuel J. Greear.Pp
715c5185aeSSamuel J. Greear.Fn lwbuf_free
725c5185aeSSamuel J. Greearfrees all resources associated with the lightweight buffer
735c5185aeSSamuel J. Greear.Fa lwb .
745c5185aeSSamuel J. Greear.Pp
755c5185aeSSamuel J. Greear.Fn lwbuf_page
765c5185aeSSamuel J. Greearand
775c5185aeSSamuel J. Greear.Fn lwbuf_kva
785c5185aeSSamuel J. Greearreturn the associated
7968f9b4e3SSascha Wildner.Vt vm_page_t
805c5185aeSSamuel J. Greearor
8168f9b4e3SSascha Wildner.Vt vm_offset_t
825c5185aeSSamuel J. Greearof the lightweight buffer
835c5185aeSSamuel J. Greear.Fa lwb .
845c5185aeSSamuel J. Greear.Pp
855c5185aeSSamuel J. Greear.Fn lwbuf_set_global
8668f9b4e3SSascha Wildnerensures that a
8768f9b4e3SSascha Wildner.Vt vm_offset_t
8868f9b4e3SSascha Wildnerpreviously obtained through
895c5185aeSSamuel J. Greear.Fa lwbuf_kva
905c5185aeSSamuel J. Greearwill be valid on all processors without subsequent calls to
915c5185aeSSamuel J. Greear.Fa lwbuf_kva .
925c5185aeSSamuel J. GreearIt should not be used.
935c5185aeSSamuel J. Greear.Sh IMPLEMENTATION NOTES
945c5185aeSSamuel J. GreearThe implementation of
9568f9b4e3SSascha Wildner.Nm lwbuf
9668f9b4e3SSascha Wildneris CPU-dependent.
97*cf37dc20SSascha WildnerOn x86_64 the
985c5185aeSSamuel J. Greearkernel maintains a direct map of KVA covering all physical memory.
995c5185aeSSamuel J. Greear.Pp
1005c5185aeSSamuel J. GreearLightweight buffers are thread and cross-processor safe with a number of
10168f9b4e3SSascha Wildnerlimitations.
10268f9b4e3SSascha WildnerAllocated buffers are not internally cached or reference counted.
1035c5185aeSSamuel J. GreearAny consumer of lightweight buffers may elect to share allocated buffers
1045c5185aeSSamuel J. Greearor allow them to be used in other threads or on other processors, but care
10568f9b4e3SSascha Wildnermust be taken.
10668f9b4e3SSascha WildnerBuffers must be externally refcounted or in some other manner
1075c5185aeSSamuel J. Greearfreed only after last use.
1085c5185aeSSamuel J. Greear.Sh HISTORY
1095c5185aeSSamuel J. GreearA
1105c5185aeSSamuel J. Greear.Nm lwbuf
1115c5185aeSSamuel J. Greearimplementation first appeared in
1125c5185aeSSamuel J. Greear.Dx 2.5 .
11368f9b4e3SSascha Wildner.Sh AUTHORS
1145c5185aeSSamuel J. GreearThe
1155c5185aeSSamuel J. Greear.Nm lwbuf
1165c5185aeSSamuel J. Greearimplementation and this manpage were written by
1175c5185aeSSamuel J. Greear.An Samuel J. Greear .
118