2 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
35 .Nd "buffer pools for network interfaces"
43 .Fa "struct mbpool **mbp" "const char *name" "bus_dma_tag_t dmat"
44 .Fa "u_int max_pages" "size_t page_size" "size_t chunk_size"
47 .Fn mbp_destroy "struct mbpool *mbp"
49 .Fn mbp_alloc "struct mbpool *mbp" "bus_addr_t *pa" "uint32_t *hp"
51 .Fn mbp_free "struct mbpool *mbp" "void *p"
53 .Fn mbp_ext_free "void *" "void *"
55 .Fn mbp_card_free "struct mbpool *mbp"
57 .Fn mbp_count "struct mbpool *mbp" "u_int *used" "u_int *card" "u_int *free"
59 .Fn mbp_get "struct mbpool *mbp" "uint32_t h"
61 .Fn mbp_get_keep "struct mbpool *mbp" "uint32_t h"
64 .Fa "struct mbpool *mbp" "uint32_t h" "bus_addr_t off" "bus_size_t len"
68 .Fn MODULE_DEPEND "your_module" "libmbpool" 1 1 1
70 .Cd "options LIBMBPOOL"
72 Mbuf pools are intended to help drivers for interface cards that need huge
73 amounts of receive buffers, and additionally provides a mapping between these
74 buffers and 32-bit handles.
76 An example of these cards are the Fore/Marconi ForeRunnerHE cards.
78 employ up to 8 receive groups, each with two buffer pools, each of which
79 can contain up to 8192.
80 This gives a total maximum number of more than
82 Even with a more moderate configuration the card eats several
84 Each of these buffers must be mapped for DMA.
86 machines without an IOMMU and with lesser than 4GByte memory this is not
87 a problem, for other machines this may quickly eat up all available IOMMU
88 address space and/or bounce buffers.
89 On sparc64, the default I/O page size
90 is 16k, so mapping a simple mbuf wastes 31/32 of the address space.
92 Another problem with most of these cards is that they support putting a 32-bit
93 handle into the buffer descriptor together with the physical address.
94 This handle is reflected back to the driver when the buffer is filled, and
95 assists the driver in finding the buffer in host memory.
97 the virtual address of the buffer is usually used as the handle.
99 work for 64-bit machines for obvious reasons, so a mapping is needed between
100 these handles and the buffers.
101 This mapping should be possible without
102 searching lists and the like.
104 An mbuf pool overcomes both problems by allocating DMA-able memory page wise
105 with a per-pool configurable page size.
106 Each page is divided into a number of
107 equally-sized chunks, the last
108 .Dv MBPOOL_TRAILER_SIZE
109 of which are used by the pool code (4 bytes).
110 The rest of each chunk is
112 There is a per-pool limit on pages that will be allocated.
114 Additionally, the code manages two flags for each buffer:
118 A buffer may be in one of three states:
119 .Bl -tag -width "on-card"
121 None of the flags is set.
124 The buffer is assumed to be handed over to the card and
125 waiting to be filled.
127 The buffer was returned by the card and is now travelling through the system.
130 A pool is created with
132 This call specifies a DMA tag
134 to be used to create and map the memory pages via
135 .Xr bus_dmamem_alloc 9 .
138 includes the pool overhead.
139 It means that to get buffers for 5 ATM cells
140 (240 bytes), a chunk size of 256 should be specified.
141 This results in 12 unused
142 bytes between the buffer, and the pool overhead of four byte.
144 maximum number of buffers in a pool is
150 The maximum value for
152 is 2^14-1 (16383) and the maximum of
157 If the call is successful, a pointer to a newly allocated
159 is set into the variable pointed to by
162 A pool is destroyed with
164 This frees all pages and the pool structure itself.
167 the code checks that all buffers are free.
168 If not, a warning message is issued
171 A buffer is allocated with
173 This returns the virtual address of the buffer and stores the physical
174 address into the variable pointed to by
176 The handle is stored into the variable pointed to by
178 The two most significant bits and the 7 least significant bits of the handle
179 are unused by the pool code and may be used by the caller.
181 automatically stripped when passing a handle to one of the other functions.
182 If a buffer cannot be allocated (either because the maximum number of pages
183 is reached, no memory is available or the memory cannot be mapped),
186 If a buffer could be allocated, it is in the
190 When the buffer is returned by the card, the driver calls
193 This function returns the virtual address of the buffer
197 The buffer is now in the
204 in that it does not clear the
207 This can be used for buffers
212 A buffer is freed by calling
214 with the virtual address of the buffer.
218 puts the buffer on the free list of the pool.
219 Note that free buffers
220 are NOT returned to the system.
225 as the free function.
226 The user argument must be the pointer to
229 Before using the contents of a buffer returned by the card, the driver
232 with the appropriate parameters.
233 This results in a call to
234 .Xr bus_dmamap_sync 9
237 All buffers in the pool that are currently in the
242 This may be called by the driver when it stops the interface.
245 state are not freed by this call.
247 For debugging it is possible to call
249 This returns the number of buffers in the
254 the number of buffers on the free list.
260 is currently a no-op because
261 .Xr bus_dmamap_sync 9
262 is missing the offset and length parameters.
264 .An Harti Brandt Aq harti@FreeBSD.org