SVR5

getrbuf(D3)

getrbuf -- get a raw buffer header

Synopsis

   #include <sys/buf.h>
   #include <sys/kmem.h>
   #include <sys/ddi.h>
   
   buf_t *getrbuf(intg flag);

Description

getrbuf allocates the space for a buffer header [see buf(D4)]. If flag is set to KM_SLEEP, the caller will sleep if necessary until memory is available. If flag is set to KM_NOSLEEP, the caller will not sleep, but getrbuf will return NULL if memory is not immediately available.

Arguments

flag: Indicates whether the caller should sleep for free space.

Return values

Upon successful completion, getrbuf returns a pointer to the allocated buffer header. If KM_NOSLEEP is specified and sufficient memory is not immediately available, getrbuf returns a NULL pointer.

Usage

getrbuf is used when a driver is performing raw I/O and needs to set up a buffer header that is not associated with a system-provided data buffer. The driver provides its own memory for the data buffer.

On return from getrbuf, the ``b_iodone'' field of the buffer header will be NULL (meaning take the default action on completion). Since the default action does not support driver buffers in the asynchronous case, the driver must change this to the address of a driver-specific I/O completion handler if the buffer will be used for B_ASYNC transfers.

The caller must also initialize the following fields:

b_flags: is set for a syncrhonous write transfer from main memory to the device. The druver must turn on the B_READ flag to transfer from the device to main memory. The driver may also turn on the B_ASYNC flag and set the b_iodone member for a synchronous transfer. the user's buffer.
b_addrtype: Is set to BA_KVIRT
b_bcount: Must be set to the number of bytes to transfer.
b_un.b_addr: Must be set to the virtual address of the caller-supplied buffer.
b_blkno: Must be set to the block number to be accessed.
b_resid: Must be set to the same value as b_bcount.
b_bufsize: Can be used to remember the size of the data buffer associated with the buffer header.

Typically, drivers do not allocate buffers. A buffer is allocated by the kernel and the associated buffer header is used as an argument to the driver's biostart(D2) or, for DDI versions prior to version 8, strategy(D2) routine. However, to implement some special features, such as ioctl(D2) commands that perform I/O, the driver may need its own buffer space. The driver can get the buffer space from the system by using geteblk(D3) or ngeteblk(D3). Or the driver can choose to use its own memory for the buffer and only allocate a buffer header with getrbuf.

Context and synchronization

If flag is set to KM_NOSLEEP, non-blockable, initialization, or interrupt context.

If flag is set to KM_SLEEP, user context.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

References

biodone(D3), bioreset(D3), biowait(D3), biowait_sig(D3), buf(D4), freerbuf(D3)