|MBPOOL(9)||Kernel Developer's Manual||MBPOOL(9)|
mbpool — buffer
pools for network interfaces
mbp_create(struct mbpool **mbp,
const char *name, bus_dma_tag_t
dmat, u_int max_pages, size_t
page_size, size_t chunk_size);
mbpool *mbp, bus_addr_t
mbpool *mbp, void
*, void *);
mbpool *mbp, u_int
*used, u_int *card,
mbpool *mbp, uint32_t
mbpool *mbp, uint32_t
mbp_sync(struct mbpool *mbp,
uint32_t h, bus_addr_t off,
bus_size_t len, u_int op);
Mbuf pools are intended to help drivers for interface cards that need huge amounts of receive buffers, and additionally provides a mapping between these buffers and 32-bit handles.
An example of these cards are the Fore/Marconi ForeRunnerHE cards. These employ up to 8 receive groups, each with two buffer pools, each of which can contain up to 8192. This gives a total maximum number of more than 100000 buffers. Even with a more moderate configuration the card eats several thousand buffers. Each of these buffers must be mapped for DMA. While for machines without an IOMMU and with lesser than 4GByte memory this is not a problem, for other machines this may quickly eat up all available IOMMU address space and/or bounce buffers. On sparc64, the default I/O page size is 16k, so mapping a simple mbuf wastes 31/32 of the address space.
Another problem with most of these cards is that they support putting a 32-bit handle into the buffer descriptor together with the physical address. This handle is reflected back to the driver when the buffer is filled, and assists the driver in finding the buffer in host memory. For 32-bit machines, the virtual address of the buffer is usually used as the handle. This does not work for 64-bit machines for obvious reasons, so a mapping is needed between these handles and the buffers. This mapping should be possible without searching lists and the like.
An mbuf pool overcomes both problems by allocating DMA-able memory
page wise with a per-pool configurable page size. Each page is divided into
a number of equally-sized chunks, the last
MBPOOL_TRAILER_SIZE of which are used by the pool
code (4 bytes). The rest of each chunk is usable as a buffer. There is a
per-pool limit on pages that will be allocated.
Additionally, the code manages two flags for each buffer: “on-card” and “used”. A buffer may be in one of three states:
- None of the flags is set.
- Both flags are set. The buffer is assumed to be handed over to the card and waiting to be filled.
- The buffer was returned by the card and is now travelling through the system.
A pool is created with
This call specifies a DMA tag dmat to be used to
create and map the memory pages via bus_dmamem_alloc(9).
The chunk_size includes the pool overhead. It means
that to get buffers for 5 ATM cells (240 bytes), a chunk size of 256 should
be specified. This results in 12 unused bytes between the buffer, and the
pool overhead of four byte. The total maximum number of buffers in a pool is
max_pages * (page_size /
chunk_size). The maximum value for
max_pages is 2^14-1 (16383) and the maximum of
page_size / chunk_size is 2^9
(512). If the call is successful, a pointer to a newly allocated
struct mbpool is set into the variable pointed to by
A pool is destroyed with
This frees all pages and the pool structure itself. If compiled with
DIAGNOSTICS, the code checks that all buffers are
free. If not, a warning message is issued to the console.
A buffer is allocated with
This returns the virtual address of the buffer and stores the physical
address into the variable pointed to by pa. The handle
is stored into the variable pointed to by hp. The two
most significant bits and the 7 least significant bits of the handle are
unused by the pool code and may be used by the caller. These are
automatically stripped when passing a handle to one of the other functions.
If a buffer cannot be allocated (either because the maximum number of pages
is reached, no memory is available or the memory cannot be mapped),
NULL is returned. If a buffer could be allocated, it
is in the “on-card” state.
When the buffer is returned by the card, the driver
with the handle. This function returns the virtual address of the buffer and
clears the “on-card” bit. The buffer is now in the
“used” state. The function
mbp_get() in that it does not clear the
“on-card” bit. This can be used for buffers that are returned
“partially” by the card.
A buffer is freed by calling
with the virtual address of the buffer. This clears the “used”
bit, and puts the buffer on the free list of the pool. Note that free
buffers are NOT returned to the system. The function
can be given to
as the free function. The user argument must be the pointer to the pool.
Before using the contents of a buffer returned by
the card, the driver must call
with the appropriate parameters. This results in a call to
bus_dmamap_sync(9) for the buffer.
All buffers in the pool that are currently in
the “on-card” state can be freed with a call to
This may be called by the driver when it stops the interface. Buffers in the
“used” state are not freed by this call.
For debugging it is possible to call
This returns the number of buffers in the “used” and
“on-card” states and the number of buffers on the free
Harti Brandt <harti@FreeBSD.org>
mbp_sync() is currently a
no-op because bus_dmamap_sync(9) is missing the offset and
|July 15, 2003||Debian|