From: dlg Date: Thu, 24 Jul 2014 01:18:23 +0000 (+0000) Subject: this is start on documenting bufqs. it covers the bits disk drivers need X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=f316ef3e8689d9464966c3bd2ad645811c1b4c1d;p=openbsd 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@ --- 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 .