usr/src/man/man9f/biodone.9f

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 2006 Sun Microsystems, Inc.  All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH BIODONE 9F "Jan 16, 2006"
   8 .SH NAME
   9 biodone \- release buffer after buffer I/O transfer and notify blocked threads
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/buf.h>
  15
  16
  17
  18 \fBvoid\fR \fBbiodone\fR(\fBstruct buf *\fR\fIbp\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Architecture independent level 1 (DDI/DKI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIbp\fR\fR
  30 .ad
  31 .RS 6n
  32 Pointer to a \fBbuf\fR(9S) structure.
  33 .RE
  34
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 The \fBbiodone()\fR function notifies blocked processes waiting for the\fB
  39 I/O\fR to complete, sets the \fBB_DONE\fR flag in the \fBb_flags\fR field of
  40 the \fBbuf\fR(9S) structure, and releases the buffer if the \fBI/O\fR is
  41 asynchronous. \fBbiodone()\fR is called by either the driver interrupt or
  42 \fBstrategy\fR(9E) routines when a buffer \fBI/O\fR request is complete.
  43 .sp
  44 .LP
  45 The \fBbiodone()\fR function provides the capability to call a completion
  46 routine if \fIbp\fR describes a kernel buffer. The address of the routine is
  47 specified in the \fBb_iodone\fR field of the \fBbuf\fR(9S) structure. If such a
  48 routine is specified, \fBbiodone()\fR calls it and returns without performing
  49 any other actions. Otherwise, it performs the steps above.
  50 .SH CONTEXT
  51 .sp
  52 .LP
  53 The \fBbiodone()\fR function can be called from user, interrupt, or kernel
  54 context.
  55 .SH EXAMPLES
  56 .sp
  57 .LP
  58 Generally, the first validation test performed by any block device
  59 \fBstrategy\fR(9E) routine is a check for an end-of-file (\fBEOF\fR) condition.
  60 The \fBstrategy\fR(9E) routine is responsible for determining an \fBEOF\fR
  61 condition when the device is accessed directly. If a \fBread\fR(2) request is
  62 made for one block beyond the limits of the device (line 10), it will report an
  63 \fBEOF\fR condition.  Otherwise, if the request is outside the limits of the
  64 device, the routine will report an error condition.  In either case, report the
  65 \fBI/O\fR operation as complete (line 27).
  66 .sp
  67 .in +2
  68 .nf
  69  1   #define RAMDNBLK   1000    /* Number of blocks in RAM disk */
  70  2   #define RAMDBSIZ   512     /* Number of bytes per block */
  71  3   char ramdblks[RAMDNBLK][RAMDBSIZ]; /* Array containing RAM disk */
  72  4
  73  5   static int
  74  6   ramdstrategy(struct buf *bp)
  75  7   {
  76  8      daddr_t blkno = bp->b_blkno;    /* get block number */
  77  9
  78 10      if ((blkno < 0) || (blkno >= RAMDNBLK)) {
  79 11            /*
  80 12             * If requested block is outside RAM disk
  81 13             * limits, test for EOF which could result
  82 14             * from a direct (physio) request.
  83 15             */
  84 16            if ((blkno == RAMDNBLK) && (bp->b_flags & B_READ)) {
  85 17             /*
  86 18              * If read is for block beyond RAM disk
  87 19              * limits, mark EOF condition.
  88 20              */
  89 21              bp->b_resid = bp->b_bcount;     /* compute return value */
  90 22
  91 23           } else {   /* I/O attempt is beyond */
  92 24              bp->b_error = ENXIO;    /*    limits of RAM disk */
  93 25              bp->b_flags |= B_ERROR; /* return error */
  94 26           }
  95 27           biodone(bp);       /* mark I/O complete (B_DONE) */
  96 28             /*
  97 29              * Wake any processes awaiting this I/O
  98 30              * or release buffer for asynchronous
  99 31              * (B_ASYNC) request.
 100 32              */
 101 33           return (0);
 102 34      }
 103            .\|.\|.\|
 104 .fi
 105 .in -2
 106
 107 .SH SEE ALSO
 108 .sp
 109 .LP
 110 \fBread\fR(2), \fBstrategy\fR(9E), \fBbiowait\fR(9F), \fBddi_add_intr\fR(9F),
 111 \fBdelay\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F), \fBbuf\fR(9S)
 112 .sp
 113 .LP
 114 \fIWriting Device Drivers\fR
 115 .SH WARNINGS
 116 .sp
 117 .LP
 118 After calling \fBbiodone()\fR, \fIbp\fR is no longer available to be referred
 119 to by the driver. If the driver makes any reference to \fIbp\fR after calling
 120 \fBbiodone()\fR, a panic may result.
 121 .SH NOTES
 122 .sp
 123 .LP
 124 Drivers that use the \fBb_iodone\fR field of the \fBbuf\fR(9S) structure to
 125 specify a substitute completion routine should save the value of \fBb_iodone\fR
 126 before changing it, and then restore the old value before calling
 127 \fBbiodone()\fR to release the buffer.