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