12061 Convert cb_ops(9S) to mandoc


   1 .\" Copyright (c) 2009, Sun Microsystems, Inc., All Rights Reserved
   2 .\" Copyright 2018, Joyent, Inc.
   3 .\" The contents of this file are subject to the terms of the
   4 .\" Common Development and Distribution License (the "License").
   5 .\" You may not use this file except in compliance with the License.
   6 .\"
   7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   8 .\" or http://www.opensolaris.org/os/licensing.
   9 .\" See the License for the specific language governing permissions
  10 .\" and limitations under the License.
  11 .\"
  12 .\" When distributing Covered Code, include this CDDL HEADER in each
  13 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  14 .\" If applicable, add the following below this CDDL HEADER, with the
  15 .\" fields enclosed by brackets "[]" replaced with your own identifying
  16 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  17 .Dd July 9, 2018
  18 .Dt CB_OPS 9S
  19 .Os
  20 .Sh NAME
  21 .Nm cb_ops
  22 .Nd character/block entry points structure
  23 .Sh SYNOPSIS
  24 .In sys/conf.h
  25 .In sys/ddi.h
  26 .In sys/sunddi.h
  27 .Sh INTERFACE LEVEL
  28 Solaris DDI specific (Solaris DDI)
  29 .Sh DESCRIPTION
  30 The
  31 .Nm
  32 structure contains all entry points for drivers that support
  33 both character and block entry points.
  34 All leaf device drivers that support
  35 direct user process access to a device should declare a
  36 .Nm
  37 structure.
  38 .Pp
  39 All drivers that safely allow multiple threads of execution in the driver at
  40 the same time must set the
  41 .Dv D_MP
  42 flag in the
  43 .Fa cb_flag
  44 field.
  45 See
  46 .Xr open 9E .
  47 .Pp
  48 If the driver properly handles 64-bit offsets, it should also set the
  49 .Dv D_64BIT
  50 flag in the
  51 .Fa cb_flag
  52 field.
  53 This specifies that the driver
  54 will use the
  55 .Fa uio_loffset
  56 field of the
  57 .Xr uio 9S
  58 structure.
  59 .Pp
  60 If the driver returns
  61 .Er EINTR
  62 from
  63 .Xr open 9E ,
  64 it should also set the
  65 .Dv D_OPEN_RETURNS_EINTR
  66 flag in the
  67 .Fa cb_flag
  68 field.
  69 This lets the
  70 framework know that it is safe for the driver to return
  71 .Er EINTR
  72 when waiting, to provide exclusion for a last-reference
  73 .Xr close 9E
  74 call to complete before calling
  75 .Xr open 9E .
  76 .Pp
  77 The
  78 .Xr mt-streams 9F
  79 function describes other flags that can be set in the
  80 .Fa cb_flag
  81 field.
  82 .Pp
  83 The
  84 .Fa cb_rev
  85 is the
  86 .Vt cb_ops
  87 structure revision number.
  88 This field must
  89 be set to
  90 .Dv CB_REV .
  91 .Pp
  92 .Pf Non- Ns Sy STREAMS
  93 drivers should set
  94 .Fa cb_str
  95 to
  96 .Sy NULL .
  97 .Pp
  98 The following
  99 .Sy DDI/DKI
 100 or
 101 .Sy DKI Ns -only
 102 or
 103 .Sy DDI Ns -only
 104 functions are provided in the character/block driver operations structure.
 105 .Bl -column "block/char" "Function" "Description"
 106 .It block/char  Function        Description
 107 .It b/c XXopen  DDI/DKI
 108 .It b/c XXclose DDI/DKI
 109 .It b   XXstrategy      DDI/DKI
 110 .It b   XXprint DDI/DKI
 111 .It b   XXdump  DDI(Sun)
 112 .It c   XXread  DDI/DKI
 113 .It c   XXwrite DDI/DKI
 114 .It c   XXioctl DDI/DKI
 115 .It c   XXdevmap        DDI(Sun)
 116 .It c   XXmmap  DKI
 117 .It c   XXsegmap        DKI
 118 .It c   XXchpoll        DDI/DKI
 119 .It c   XXprop_op       DDI(Sun)
 120 .It c   XXaread DDI(Sun)
 121 .It c   XXawrite        DDI(Sun)
 122 .El
 123 .Sh STRUCTURE MEMBERS
 124 .Bd -literal -offset 2n
 125 int  (*cb_open)(dev_t *devp, int flag, int otyp, cred_t *credp);
 126 int  (*cb_close)(dev_t dev, int flag, int otyp, cred_t *credp);
 127 int  (*cb_strategy)(struct buf *bp);
 128 int  (*cb_print)(dev_t dev, char *str);
 129 int  (*cb_dump)(dev_t dev, caddr_t addr, daddr_t blkno, int nblk);
 130 int  (*cb_read)(dev_t dev, struct uio *uiop, cred_t *credp);
 131 int  (*cb_write)(dev_t dev, struct uio *uiop, cred_t *credp);
 132 int  (*cb_ioctl)(dev_t dev, int cmd, intptr_t arg, int mode,
 133        cred_t *credp, int *rvalp);
 134 int  (*cb_devmap)(dev_t dev, devmap_cookie_t dhp, offset_t off,
 135        size_t len, size_t *maplen, uint_t model);
 136 int  (*cb_mmap)(dev_t dev, off_t off, int prot);
 137 int  (*cb_segmap)(dev_t dev, off_t off, struct as *asp,
 138        caddr_t *addrp, off_t len, unsigned int prot,
 139        unsigned int maxprot, unsigned int flags, cred_t *credp);
 140 int  (*cb_chpoll)(dev_t dev, short events, int anyyet,
 141        short *reventsp, struct pollhead **phpp);
 142 int  (*cb_prop_op)(dev_t dev, dev_info_t *dip,
 143        ddi_prop_op_t prop_op, int mod_flags,
 144        char *name, caddr_t valuep, int *length);
 145 struct streamtab *cb_str;   /* streams information */
 146 int  cb_flag;
 147 int  cb_rev;
 148 int  (*cb_aread)(dev_t dev, struct aio_req *aio, cred_t *credp);
 149 int  (*cb_awrite)(dev_t dev, struct aio_req *aio, cred_t *credp);
 150 .Ed
 151 .Sh SEE ALSO
 152 .Xr aread 9E ,
 153 .Xr awrite 9E ,
 154 .Xr chpoll 9E ,
 155 .Xr close 9E ,
 156 .Xr dump 9E ,
 157 .Xr ioctl 9E ,
 158 .Xr mmap 9E ,
 159 .Xr open 9E ,
 160 .Xr print 9E ,
 161 .Xr prop_op 9E ,
 162 .Xr read 9E ,
 163 .Xr segmap 9E ,
 164 .Xr strategy 9E ,
 165 .Xr write 9E ,
 166 .Xr nochpoll 9F ,
 167 .Xr nodev 9F ,
 168 .Xr nulldev 9F ,
 169 .Xr dev_ops 9S ,
 170 .Xr qinit 9S
 171 .Rs
 172 .%T Writing Device Drivers
 173 .Re
 174 .Rs
 175 .%T STREAMS Programming Guide
 176 .Re
--- EOF ---