*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> mbp_alloc (9)              



NAME    [Toc]    [Back]

     mbpool -- Buffer pools for network interfaces

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <machine/bus.h>
     #include <sys/mbpool.h>

     struct mbpool;

     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);

     mbp_destroy(struct mbpool *mbp);

     void *
     mbp_alloc(struct mbpool *mbp, bus_addr_t *pa, uint32_t *hp);

     mbp_free(struct mbpool *mbp, void *p);

     mbp_ext_free(void *, void *);

     mbp_card_free(struct mbpool *mbp);

     mbp_count(struct mbpool *mbp, u_int *used, u_int *card, u_int *free);

     void *
     mbp_get(struct mbpool *mbp, uint32_t h);

     void *
     mbp_get_keep(struct mbpool *mbp, uint32_t h);

     mbp_sync(struct mbpool *mbp, uint32_t h, bus_addr_t off, bus_size_t len,
	 u_int op);

     MODULE_DEPEND(your_module, libmbpool, 1, 1, 1);

     options LIBMBPOOL

DESCRIPTION    [Toc]    [Back]

     Mbuf pools are intented 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 the sparc64 the
     default IO 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 usually the virtual address of the buffer is used as the
     handle. This does not work for 64-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 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
     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 mbp_create().  This call specifies a DMA tag dmat
     to be used to create and map the memory pages via bus_dmamem_alloc().
     The chunk_size includes the pool overhead. That means 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 sucessful a pointer to a newly allocated struct mbpool is set
     into the variable pointed to by mpb.

     A pool is destroyed with mbp_destroy().  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 allocate with mbp_alloc().  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 oncard

     When the buffer is returned by the card the driver calls mbp_get() 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_keep() differs from 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 mbp_free() 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 mbp_ext_free(can, be, given, to) m_extadd() as the free function.
 The user argument must be the pointer to the pool.

     Before useing the contents of a buffer returned by the card the driver
     must call mbp_sync() with the appropriate parameters. This results in a
     call to bus_dmamap_sync() for the buffer.

     All buffers in the pool that are currently in the on-card state can be
     freed with a call to mbp_card_free().  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 mbp_count().	This returns the number
 of buffers in the used and on-card states and the number of buffers
     on the free list.

SEE ALSO    [Toc]    [Back]


CAVEATS    [Toc]    [Back]

     The function mbp_sync() is currently a NOP because bus_dmamap_sync() is
     missing the offset and length parameters.

AUTHOR    [Toc]    [Back]

     Harti Brandt <harti@freebsd.org>.

FreeBSD 			 July 15, 2003			       FreeBSD
[ Back ]
 Similar pages
Name OS Title
altq NetBSD kernel interfaces for manipulating output queues on network interfaces
altq OpenBSD kernel interfaces for manipulating output queues on network interfaces
ifaddr FreeBSD kernel interfaces for manipulating network interfaces
ifqueue FreeBSD kernel interfaces for manipulating network interfaces
ifnet FreeBSD kernel interfaces for manipulating network interfaces
if_data FreeBSD kernel interfaces for manipulating network interfaces
configNetIf IRIX configure the network interfaces
nameif Linux name network interfaces based on MAC addresses
atmelan Tru64 Configures LAN-Emulation clients as network interfaces.
ifmib FreeBSD Management Information Base for network interfaces
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service