te
Copyright 1989 AT&T
Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
Copyright 2021 Tintri by DDN, Inc. All rights reserved.
The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
esballoc, desballoc esballoca, desballoca - allocate a message block using a caller-supplied buffer

#include <sys/stream.h>

mblk_t *esballoc(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

mblk_t *desballoc(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

#include <sys/strsubr.h>

mblk_t *esballoca(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

mblk_t *desballoca(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

mblk_t *esballoc_wait(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

mblk_t *esballoca_wait(uchar_t *base, size_t size, uint_t pri,
 frtn_t *fr_rtnp);

esballoc(): Architecture independent level 1 (DDI/DKI)

esballoca(): illumos DDI specific (illumos DDI)
desballoc(): illumos DDI specific (illumos DDI)
desballoca(): illumos DDI specific (illumos DDI)

esballoc_wait(): Volatile (private DDI function)
esballoca_wait(): Volatile (private DDI function)

 PARAMETERS
base

Address of caller-supplied data buffer.


size

Number of bytes in data buffer.


pri

Priority of the request (no longer used).


fr_rtnp

Free routine data structure.


 DESCRIPTION
The esballoc(), esballoca(), desballoc() and
desballoca() functions operate identically to allocb(9F),
except that the data buffer to associate with the message is specified
by the caller. The allocated message will have both the b_wptr
and b_rptr set to the supplied data buffer starting at base. Only
the buffer itself can be specified by the caller. The message block and data
block header are allocated as if by allocb(9F).

When freeb(9F) is called to free the message, the driver's
message-freeing routine, referenced through the free_rtn(9S) structure,
is called with appropriate arguments to free the data buffer.

The free_rtn(9S) structure includes the following members:
void (*free_func)(); /* caller's freeing routine */
caddr_t free_arg; /* argument to free_func() */



Instead of requiring a specific number of arguments, the free_arg field
is defined of type caddr_t. This way, the driver can pass a pointer to a
structure if more than one argument is needed. Note that the address of the
free_rtn(9S) structure passed to esballoc() is used when the
returned mblk/dblk pair is freed, and must remain valid until then.

If esballoc() or esballoca() was used, then free_func will
be called asynchronously at some point after the message is no longer
referenced. If desballoc() or desballoca() was used, then
free_func will be called synchronously by the thread releasing
the final reference. See freeb(9F).

The free_func routine must not sleep, and must not access any dynamically
allocated data structures that could be freed before or during its execution.
In addition, because messages allocated with desballoc() or
desballoca() are freed in the context of the caller, free_func
must not call another module's put procedure, or attempt to acquire a
private module lock which might be held by another thread across a call to a
STREAMS utility routine that could free a message block. Finally,
free_func routines specified using desballoc() or
desballoca() may run in interrupt context and thus must only use
synchronization primitives that include an interrupt priority returned from
ddi_intr_get_pri(9F) or ddi_intr_get_softint_pri(9F). If any of
these restrictions are not followed, the possibility of lock recursion or
deadlock exists.

The variants ending with 'a' (esballoca() or desballoca()
add an "extra" ref to the dblk returned, also setting an internal flag
so that freeb(9F) handles the extra ref. The point of this
extra ref is so that any streams code handling this data block knows
that the data should not be modified without taking a copy. This is
used by callers sending external buffers that must not be modified.

The variants ending with "_wait" do a sleeping allocation, where
the ordinary esballoc() functions can return NULL when the
system is low on free memory.
 RETURN VALUES
On success, a pointer to the newly allocated message block is returned.
On failure, esballoc(), esballoca(), desballoc() and
desballoca() return NULL.
The functions esballoc_wait() and esballoca_wait()
do not return errors, and instead sleep until memory is available.
 CONTEXT
The esballoc(), esballoca(), desballoc() and
desballoca() functions can be called from user,
interrupt, or kernel context.
The functions esballoc_wait() and esballoca_wait()
can block and should not be called from interrupt context.
 ATTRIBUTES
See attributes(7) for descriptions of the following attributes:




ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed
Interface Stability Volatile


 SEE ALSO
 allocb (9F),  ddi_intr_get_pri (9F),  ddi_intr_get_softint_pri (9F),  freeb (9F),  datab (9S),  free_rtn (9S) 

Writing Device Drivers

STREAMS Programming Guide