1*2c243e1bSbentley.\" $OpenBSD: bufq_init.9,v 1.6 2015/12/25 20:50:57 bentley Exp $ 2f316ef3eSdlg.\" 3f316ef3eSdlg.\" Copyright (c) 2013 David Gwynne <dlg@openbsd.org> 4f316ef3eSdlg.\" 5f316ef3eSdlg.\" Permission to use, copy, modify, and distribute this software for any 6f316ef3eSdlg.\" purpose with or without fee is hereby granted, provided that the above 7f316ef3eSdlg.\" copyright notice and this permission notice appear in all copies. 8f316ef3eSdlg.\" 9f316ef3eSdlg.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10f316ef3eSdlg.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11f316ef3eSdlg.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12f316ef3eSdlg.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13f316ef3eSdlg.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14f316ef3eSdlg.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15f316ef3eSdlg.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16f316ef3eSdlg.\" 17*2c243e1bSbentley.Dd $Mdocdate: December 25 2015 $ 18f316ef3eSdlg.Dt BUFQ_INIT 9 19f316ef3eSdlg.Os 20f316ef3eSdlg.Sh NAME 21f316ef3eSdlg.Nm bufq_init , 22f316ef3eSdlg.Nm bufq_switch , 23f316ef3eSdlg.Nm bufq_destroy , 24f316ef3eSdlg.Nm bufq_queue , 25f316ef3eSdlg.Nm bufq_dequeue , 26f316ef3eSdlg.Nm bufq_requeue , 27f316ef3eSdlg.Nm bufq_peek , 28f316ef3eSdlg.Nm bufq_drain 29f316ef3eSdlg.\" .Nm bufq_wait , 30f316ef3eSdlg.\" .Nm bufq_done , 31f316ef3eSdlg.\" .Nm bufq_quiesce , 32f316ef3eSdlg.\" .Nm bufq_restart 33f316ef3eSdlg.Nd buf queues 34f316ef3eSdlg.Sh SYNOPSIS 35f316ef3eSdlg.In sys/buf.h 36f316ef3eSdlg.Ft int 375dfee228Sschwarze.Fn bufq_init "struct bufq *bufq" "int type" 38f316ef3eSdlg.Ft int 395dfee228Sschwarze.Fn bufq_switch "struct bufq *bufq" "int type" 40f316ef3eSdlg.Ft void 415dfee228Sschwarze.Fn bufq_destroy "struct bufq *bufq" 42f316ef3eSdlg.Ft void 435dfee228Sschwarze.Fn bufq_queue "struct bufq *bufq" "struct buf *bp" 44f316ef3eSdlg.Ft struct buf * 455dfee228Sschwarze.Fn bufq_dequeue "struct bufq *bufq" 46f316ef3eSdlg.Ft void 475dfee228Sschwarze.Fn bufq_requeue "struct bufq *bufq" "struct buf *bp" 48f316ef3eSdlg.Ft int 495dfee228Sschwarze.Fn bufq_peek "struct bufq *bufq" 50f316ef3eSdlg.Ft void 515dfee228Sschwarze.Fn bufq_drain "struct bufq *bufq" 52f316ef3eSdlg.Sh DESCRIPTION 53f316ef3eSdlgThe bufq API implements queueing and scheduling of I/O operations on disk 54f316ef3eSdlgdevices. 55f316ef3eSdlgIt provides multiple scheduling algorithms within the API. 56f316ef3eSdlg.Pp 57f316ef3eSdlgIt is the responsibility of the disk device driver to provide 58f316ef3eSdlgpre-allocated bufq structures. 59f316ef3eSdlg.Pp 60f316ef3eSdlg.Fn bufq_init 61*2c243e1bSbentleyinitialises the 62f316ef3eSdlg.Fa bufq 63f316ef3eSdlgstructure and allocates any state required by the scheduling algorithm 64f316ef3eSdlgby the 65f316ef3eSdlg.Fa type 66f316ef3eSdlgargument. 67f316ef3eSdlg.Pp 68f316ef3eSdlg.Fn bufq_switch 69f316ef3eSdlgcan be used to change the scheduler currently used by 70f316ef3eSdlg.Fa bufq 71f316ef3eSdlgto the algorithm specified by 72f316ef3eSdlg.Fa type . 73f316ef3eSdlg.Pp 74445bf4dfSdlgThe 75445bf4dfSdlg.Fa type 76445bf4dfSdlgargument to 77445bf4dfSdlg.Fn bufq_init 78445bf4dfSdlgand 79445bf4dfSdlg.Fn bufq_switch 80445bf4dfSdlgcan be one of the following scheduling algorithms: 81445bf4dfSdlg.Pp 82445bf4dfSdlg.Bl -tag -offset indent -width BUFQ_DEFAULT -compact 83445bf4dfSdlg.It Dv BUFQ_FIFO 84445bf4dfSdlgA simple First-In First-Out queue. 85445bf4dfSdlg.It Dv BUFQ_NSCAN 86445bf4dfSdlgTakes batches of "N" bufs from the queue and sorts them for optimal 87445bf4dfSdlghead movement. 88445bf4dfSdlg.It Dv BUFQ_DEFAULT 89445bf4dfSdlgThis currently aliases 90445bf4dfSdlg.Dv BUFQ_NSCAN . 91445bf4dfSdlg.El 92445bf4dfSdlg.Pp 93f316ef3eSdlg.Fn bufq_destroy 94f316ef3eSdlgfrees any state that was used by the scheduler. 95f316ef3eSdlg.Pp 96f316ef3eSdlg.Fn bufq_queue 97f316ef3eSdlgis used to add the buf specified by 98f316ef3eSdlg.Fa bp 99f316ef3eSdlgto the 100f316ef3eSdlg.Fa bufq 101f316ef3eSdlgqueue. 102f316ef3eSdlg.Pp 103f316ef3eSdlg.Fn bufq_dequeue 104f316ef3eSdlgis used to get the next buf the 105f316ef3eSdlg.Fa bufq 106f316ef3eSdlghas scheduled to be serviced by a disk. 107f316ef3eSdlgThe buf will be removed from the queue. 108f316ef3eSdlg.Pp 109f316ef3eSdlg.Fn bufq_requeue 110f316ef3eSdlgcan be used to return a previously dequeued buf specified by 111f316ef3eSdlg.Fa bp 112f316ef3eSdlgto the head of the queue of 113f316ef3eSdlg.Fa bufq . 114f316ef3eSdlg.Pp 115f316ef3eSdlg.Fn bufq_peek 116f316ef3eSdlgallows the caller to determine if there are more bufs queued on 117f316ef3eSdlg.Fa bufq 118f316ef3eSdlgwithout modifying the list of bufs. 119f316ef3eSdlg.Pp 120f316ef3eSdlg.Fn bufq_drain 121f316ef3eSdlgis a convenience function for devices that have detached. 122f316ef3eSdlgIt removes all the bufs currently queued on 123f316ef3eSdlg.Fa bufq , 124f316ef3eSdlgmarks them as failed with an 12566eca197Sschwarze.Er ENXIO 126f316ef3eSdlgerror, and returns them to the block layer via 127f316ef3eSdlg.Xr biodone 9 . 128f316ef3eSdlg.Sh CONTEXT 129f316ef3eSdlg.Fn bufq_init , 130f316ef3eSdlg.Fn bufq_switch , 131f316ef3eSdlgand 132f316ef3eSdlg.Fn bufq_destroy 133f316ef3eSdlgcan be called during autoconf, or from process context. 134f316ef3eSdlg.Pp 135f316ef3eSdlg.Nm bufq_queue , 136f316ef3eSdlg.Nm bufq_dequeue , 137f316ef3eSdlg.Nm bufq_requeue , 138f316ef3eSdlg.Nm bufq_peek , 139f316ef3eSdlgand 140f316ef3eSdlg.Nm bufq_drain 141f316ef3eSdlgcan be called during autoconf, from process context, or from interrupt context. 142f316ef3eSdlg.Sh RETURN VALUES 143f316ef3eSdlg.Fn bufq_init 144f316ef3eSdlgand 145f316ef3eSdlg.Fn bufq_switch 146f316ef3eSdlgwill return 0 on success, or an error code as per 147f316ef3eSdlg.Xr errno 2 . 148f316ef3eSdlg.Pp 149f316ef3eSdlg.Fn bufq_dequeue 150f316ef3eSdlgreturns the next buf that is scheduled to be serviced by the disk. 151f316ef3eSdlg.Dv NULL 15266eca197Sschwarzeis returned if there are no bufs available on the queue. 153f316ef3eSdlg.Pp 154f316ef3eSdlg.Fn bufq_peek 155f316ef3eSdlgreturns 1 if there are bufs available to be scheduled on the disk, otherwise 0. 156f316ef3eSdlg.Sh SEE ALSO 157f316ef3eSdlg.Xr errno 2 , 158f316ef3eSdlg.Xr autoconf 9 , 159f316ef3eSdlg.Xr biodone 9 , 160f316ef3eSdlg.Xr disk 9 161f316ef3eSdlg.Sh HISTORY 162f316ef3eSdlgThe bufq API was written by 163f316ef3eSdlg.An Thordur I. Bjornsson 164f316ef3eSdlgand 165f316ef3eSdlg.An David Gwynne Aq Mt dlg@openbsd.org . 166f316ef3eSdlgThe bufq API first appeared in 167f316ef3eSdlg.Ox 4.8 168f316ef3eSdlgand finally succeeded in fully replacing disksort in 169f316ef3eSdlg.Ox 5.5 . 170