NAME
bufq,
bufq_init,
bufq_register,
bufq_unregister,
bufq_state,
bufq_alloc,
bufq_drain,
bufq_free,
bufq_getstrategyname,
bufq_move,
bufq_put,
bufq_get,
bufq_peek,
bufq_cancel —
device buffer queues
SYNOPSIS
#include <sys/bufq.h>
void
bufq_init(
void);
int
bufq_register(
struct
bufq_strat *);
int
bufq_unregister(
struct
bufq_strat *);
int
bufq_alloc(
struct
bufq_state **bufq,
const
char *strategy,
int
flags);
void
bufq_drain(
struct
bufq_state *bufq);
void
bufq_free(
struct
bufq_state *bufq);
const char *
bufq_getstrategyname(
struct
bufq_state *bufq);
void
bufq_move(
struct
bufq_state *dst,
struct
bufq_state *src);
void
bufq_put(
struct
bufq_state *bufq,
struct
buf *bp);
struct buf *
bufq_get(
struct
bufq_state *bufq);
struct buf *
bufq_peek(
struct
bufq_state *bufq);
struct buf *
bufq_cancel(
struct
bufq_state *bufq,
struct
buf *bp);
DESCRIPTION
The
bufq subsystem is a set of operations for the management
of device buffer queues. Various strategies for ordering of entries in the
buffer queues can be provided by loadable kernel modules (see
module(9)). By default, the
BUFQ_FCFS
and
BUFQ_DISKSORT
strategies are included in the kernel; see
options(4) for more details.
The primary data type for using the operations is the
bufq_state structure, which is opaque for users. Each buffer
queue strategy module is defined by the
bufq_strat
structure, which is also opaque for users.
FUNCTIONS
-
-
- bufq_init(void)
- Initialize the bufq subsystem. This
routine must be called before any other bufq
routines.
-
-
- bufq_register(bs)
- Registers the specified buffer queue strategy module so it
can be used in subsequent operations.
-
-
- bufq_unregister(bs)
- Unregisters the specified buffer queue strategy module. The
routine will fail if any buffer queues for the specified strategy are in
use (see bufq_alloc() below).
-
-
- bufq_alloc(bufq,
strategy, flags)
- Allocate and initialize a bufq_state
descriptor.
The argument strategy specifies a buffer queue
strategy to be used for this buffer queue. The following special values
can be used:
BUFQ_STRAT_ANY
- Let bufq_alloc() select a
strategy.
BUFQ_DISK_DEFAULT_STRAT
- Let bufq_alloc() select a strategy,
assuming it will be used for a normal disk device.
Valid bits for the flags are:
BUFQ_SORT_RAWBLOCK
- sort by b_rawblkno
BUFQ_SORT_CYLINDER
- sort by b_cylinder and then by
b_rawblkno
BUFQ_EXACT
- Fail if a strategy specified by
strategy is not available. In that case,
bufq_alloc returns
ENOENT
. If this flag is not specified,
bufq_alloc() will silently use one of available
strategies.
If a specific strategy is specified but not currently available, the
bufq subsystem will attempt to auto-load the
corresponding kernel module using
module_autoload(9).
-
-
- bufq_drain(bufq)
- Drain a bufq_state descriptor.
-
-
- bufq_free(bufq)
- Destroy a bufq_state descriptor.
-
-
- bufq_getstrategyname(bufq)
- Get a strategy identifier of a buffer queue, the string
returned will be NUL-terminated and it always will be a valid strategy
name.
-
-
- bufq_move(dst,
src)
- Move all requests from the buffer queue
src to the buffer queue
dst.
-
-
- bufq_put(bufq,
bp)
- Put the buf bp in the queue.
-
-
- bufq_get(bufq)
- Get the next buf from the queue and remove it from the
queue. Returns
NULL
if the queue is empty.
-
-
- bufq_peek(bufq)
- Get the next buf from the queue without removal. The next
buf will remain the same until bufq_get(),
bufq_put(), or bufq_drain() is called.
Returns
NULL
if the queue is empty.
-
-
- bufq_cancel(bufq,
bp)
- Cancel the buf bp issued earlier on
the queue. Returns
NULL
if the element can not be
found on the queue or bp if it has been found and
removed. This operation can be computationally expensive if there are a
lot of buffers queued.
CODE REFERENCES
The actual code implementing the device buffer queues can be found in the file
sys/kern/subr_bufq.c. The code implementing specific buffer
queue strategies can be found in the files
sys/kern/bufq_*.c.
NOTES
A list of currently available buffer queue strategies is available via the
“kern.bufq.strategies”
sysctl(7) variables.
HISTORY
The
bufq subsystem appeared in
NetBSD
2.0.
AUTHORS
The
bufq subsystem was written by
Jürgen
Hannken-Illjes ⟨hannken@NetBSD.org⟩.