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