From f316ef3e8689d9464966c3bd2ad645811c1b4c1d Mon Sep 17 00:00:00 2001 From: dlg Date: Thu, 24 Jul 2014 01:18:23 +0000 Subject: [PATCH] this is start on documenting bufqs. it covers the bits disk drivers need to know. the grubby bits the midlayer touches on them will get written up soon. ok deraadt@ --- share/man/man9/Makefile | 9 ++- share/man/man9/bufq_init.9 | 150 +++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/bufq_init.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index c69a8933ce9..5ca494d4e0a 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.217 2014/07/13 23:49:40 uebayasi Exp $ +# $OpenBSD: Makefile,v 1.218 2014/07/24 01:18:23 dlg Exp $ # $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -7,7 +7,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \ atomic_dec_int.9 atomic_inc_int.9 atomic_setbits_int.9 \ atomic_sub_int.9 atomic_swap_uint.9 \ audio.9 autoconf.9 \ - bemtoh32.9 bio_register.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \ + bemtoh32.9 bio_register.9 boot.9 buffercache.9 bufq_init.9 bus_dma.9 \ + bus_space.9 \ copy.9 config_attach.9 crypto.9 delay.9 \ disk.9 disklabel.9 dma_alloc.9 dohooks.9 dopowerhooks.9 \ domountroothooks.9 doshutdownhooks.9 dostartuphooks.9 \ @@ -71,6 +72,10 @@ MLINKS+=buffercache.9 bread.9 buffercache.9 breadn.9 \ buffercache.9 geteblk.9 buffercache.9 incore.9 \ buffercache.9 allocbuf.9 buffercache.9 brelse.9 \ buffercache.9 biodone.9 buffercache.9 biowait.9 +MLINKS+=bufq_init.9 bufq_switch.9 bufq_init.9 bufq_destroy.9 \ + bufq_init.9 bufq_queue.9 bufq_init.9 bufq_dequeue.9 \ + bufq_init.9 bufq_requeue.9 bufq_init.9 bufq_peek.9 \ + bufq_init.9 bufq_drain.9 MLINKS+=bus_dma.9 bus_dmamap_create.9 bus_dma.9 bus_dmamap_destroy.9 \ bus_dma.9 bus_dmamap_load.9 bus_dma.9 bus_dmamap_load_mbuf.9 \ bus_dma.9 bus_dmamap_load_uio.9 bus_dma.9 bus_dmamap_load_raw.9 \ diff --git a/share/man/man9/bufq_init.9 b/share/man/man9/bufq_init.9 new file mode 100644 index 00000000000..ae2a1835f20 --- /dev/null +++ b/share/man/man9/bufq_init.9 @@ -0,0 +1,150 @@ +.\" $OpenBSD: bufq_init.9,v 1.1 2014/07/24 01:18:23 dlg Exp $ +.\" +.\" Copyright (c) 2013 David Gwynne +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: July 24 2014 $ +.Dt BUFQ_INIT 9 +.Os +.Sh NAME +.Nm bufq_init , +.Nm bufq_switch , +.Nm bufq_destroy , +.Nm bufq_queue , +.Nm bufq_dequeue , +.Nm bufq_requeue , +.Nm bufq_peek , +.Nm bufq_drain +.\" .Nm bufq_wait , +.\" .Nm bufq_done , +.\" .Nm bufq_quiesce , +.\" .Nm bufq_restart +.Nd buf queues +.Sh SYNOPSIS +.In sys/buf.h +.Ft int +.Fn "bufq_init" "struct bufq *bufq" "int type" +.Ft int +.Fn "bufq_switch" "struct bufq *bufq" "int type" +.Ft void +.Fn "bufq_destroy" "struct bufq *bufq" +.Ft void +.Fn "bufq_queue" "struct bufq *bufq" "struct buf *bp" +.Ft struct buf * +.Fn "bufq_dequeue" "struct bufq *bufq" +.Ft void +.Fn "bufq_requeue" "struct bufq *bufq" "struct buf *bp" +.Ft int +.Fn "bufq_peek" "struct bufq *bufq" +.Ft void +.Fn "bufq_drain" "struct bufq *bufq" +.Sh DESCRIPTION +The bufq API implements queueing and scheduling of I/O operations on disk +devices. +It provides multiple scheduling algorithms within the API. +.Pp +It is the responsibility of the disk device driver to provide +pre-allocated bufq structures. +.Pp +.Fn bufq_init +initialiases the +.Fa bufq +structure and allocates any state required by the scheduling algorithm +by the +.Fa type +argument. +.Pp +.Fn bufq_switch +can be used to change the scheduler currently used by +.Fa bufq +to the algorithm specified by +.Fa type . +.Pp +.Fn bufq_destroy +frees any state that was used by the scheduler. +.Pp +.Fn bufq_queue +is used to add the buf specified by +.Fa bp +to the +.Fa bufq +queue. +.Pp +.Fn bufq_dequeue +is used to get the next buf the +.Fa bufq +has scheduled to be serviced by a disk. +The buf will be removed from the queue. +.Pp +.Fn bufq_requeue +can be used to return a previously dequeued buf specified by +.Fa bp +to the head of the queue of +.Fa bufq . +.Pp +.Fn bufq_peek +allows the caller to determine if there are more bufs queued on +.Fa bufq +without modifying the list of bufs. +.Pp +.Fn bufq_drain +is a convenience function for devices that have detached. +It removes all the bufs currently queued on +.Fa bufq , +marks them as failed with an +.Dv ENXIO +error, and returns them to the block layer via +.Xr biodone 9 . +.Sh CONTEXT +.Fn bufq_init , +.Fn bufq_switch , +and +.Fn bufq_destroy +can be called during autoconf, or from process context. +.Pp +.Nm bufq_queue , +.Nm bufq_dequeue , +.Nm bufq_requeue , +.Nm bufq_peek , +and +.Nm bufq_drain +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn bufq_init +and +.Fn bufq_switch +will return 0 on success, or an error code as per +.Xr errno 2 . +.Pp +.Fn bufq_dequeue +returns the next buf that is scheduled to be serviced by the disk. +.Dv NULL +is returned If there are no bufs available on the queue. +.Pp +.Fn bufq_peek +returns 1 if there are bufs available to be scheduled on the disk, otherwise 0. +.Sh SEE ALSO +.Xr errno 2 , +.Xr autoconf 9 , +.Xr biodone 9 , +.Xr disk 9 +.Sh HISTORY +The bufq API was written by +.An Thordur I. Bjornsson +and +.An David Gwynne Aq Mt dlg@openbsd.org . +The bufq API first appeared in +.Ox 4.8 +and finally succeeded in fully replacing disksort in +.Ox 5.5 . -- 2.20.1