|free||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.|
|used||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
to be used to create and map the memory pages via
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.
maximum number of buffers in a pool is
The maximum value for
is 2^14-1 (16383) and the maximum of
is 2^9 (512).
If the call is successful, a pointer to a newly allocated
.Vt 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 allocated 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 "on-card" state.
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 using 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(9) 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.
.An Harti Brandt Aq harti@FreeBSD.org
The function mbp_sync is currently a no-op because bus_dmamap_sync(9) is missing the offset and length parameters.