SVR5 and SCO OpenServer 5
esballoc(D3str)
esballoc --
allocate a message block using an externally-supplied buffer
Synopsis
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/ddi.h>
mblk_t *esballoc(uchar_t *base, int size,
int pri, frtn_t *fr_rtnp);
Description
esballoc( )
creates a STREAMS message
and attaches a driver-supplied data buffer
in place of a STREAMS data buffer.
It allocates a message and data block header only.
The driver-supplied data buffer, pointed to by base,
is used as the data buffer for the message.
Arguments
base-
Address of driver-supplied data buffer.
size-
Number of bytes in data buffer.
pri-
Priority of allocation request,
which gives hint to the allocator
indicating how badly the message block is needed.
Valid values are:
BPRI_LO-
Use for normal data allocations.
BPRI_MED-
Use for other non-critical allocations.
BPRI_HI-
Use for allocations that absolutely must succeed,
although success is not guaranteed.
Some implementations may choose to ignore this argument.
fr_rtnp-
Pointer to the free-routine data structure.
Return values
On success, a pointer to the newly allocated message block is returned.
On failure, NULL is returned.
Usage
Instead of requiring a specific number of arguments,
the free_arg
field is defined of type char *.
This way, the driver can pass a pointer to a structure
if more than one argument is needed.
STREAMS does not guarantee successful buffer allocation;
any set of resources can be exhausted
under the right conditions.
DDI drivers can call the
esbbcall(D3str)
function and ODDI drivers can call the
bufcall(D3str)
function to recover from buffer allocation failures.
When
freeb(D3str)
is called to free the message,
on the last reference to the message,
the driver's free-routine,
specified by the free_func
member in the
free_rtn(D4str)
structure,
is called with one argument,
specified by the free_arg
member,
to free the data buffer.
When the free_func
function runs,
interrupts from all STREAMS devices are blocked.
It has no user context
and may not call any routine that blocks.
The function may not access
any dynamically allocated data structures
that might no longer exist when it runs.
DDI 8 drivers that will use the allocated block
for DMA operations must call
msgpullup_physreq(D3str)
after calling
esballoc( ).
Context
Base or Interrupt.
Synchronization constraints
Does not block.
Driver-defined basic locks, read/write locks, and sleep locks
may be held across calls to this function.
Hardware applicability
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
oddi:
1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp
Differences between versions
For the SVR5 Release 7.1 release,
esballoc( )
can handle base addresses above 4GB;
it will reallocate memory above 4GB
to memory in the lower regions.
Note that this is implemented in the operating system itself
and not as part of the DDI specification;
for earlier versions of SVR5
esballoc( )
cannot be used for addresses above 4GB.
Earlier releases of ODDI defined the
last argument of this function differently.
Using the free_rtn * structure would work
for this argument, but it is not the preferred syntax.
Future directions
Additional changes to
esballoc( )
are planned to provide full support
for 64-bit network cards.
References
allocb(D3str),
bufcall(D3str),
esbbcall(D3str),
freeb(D3str),
free_rtn(D4str),
msgpullup_physreq(D3str),
``Scatter/gather operations'' in HDK Technical Reference
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005