share/man/man4/smb.4

   1 .\" Copyright (c) 1998, Nicolas Souchu
   2 .\" Copyright (c) 2004, Joerg Wunsch
   3 .\" Copyright (c) 2015, Michael Gmelin <freebsd@grem.de>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd April 25, 2015
  30 .Dt SMB 4
  31 .Os
  32 .Sh NAME
  33 .Nm smb
  34 .Nd SMB generic I/O device driver
  35 .Sh SYNOPSIS
  36 .Cd "device smb"
  37 .Sh DESCRIPTION
  38 The
  39 .Em smb
  40 character device driver provides generic i/o to any
  41 .Xr smbus 4
  42 instance.
  43 In order to control SMB devices, use
  44 .Pa /dev/smb?
  45 with the ioctls described below.
  46 Any of these ioctl commands takes a pointer to
  47 .Vt struct smbcmd
  48 as its argument.
  49 .Bd -literal
  50 #include <sys/types.h>
  51
  52 struct smbcmd {
  53         u_char cmd;
  54         u_char reserved;
  55         u_short op;
  56         union {
  57                 char    byte;
  58                 char    buf[2];
  59                 short   word;
  60         } wdata;
  61         union {
  62                 char    byte;
  63                 char    buf[2];
  64                 short   word;
  65         } rdata;
  66         int  slave;
  67         char *wbuf;     /* use wdata if NULL */
  68         int  wcount;
  69         char *rbuf;     /* use rdata if NULL */
  70         int  rcount;
  71 };
  72 .Ed
  73 .Pp
  74 The
  75 .Fa slave
  76 field is always used, and provides the address of the
  77 SMBus slave device to talk to.
  78 The slave address is specified in the seven most significant bits
  79 .Pq i.e. Dq "left-justified" .
  80 The least significant bit of the slave address must be zero.
  81 .Pp
  82 .Bl -column ".Dv SMB_QUICK_WRITE" -compact
  83 .It Em Ioctl Ta Em Description
  84 .Pp
  85 .It Dv SMB_QUICK_WRITE Ta
  86 The
  87 .Em QuickWrite
  88 command just issues the device address with write intent
  89 to the bus, without transferring any data.
  90 .It Dv SMB_QUICK_READ Ta
  91 The
  92 .Em QuickRead
  93 command just issues the device address with read intent
  94 to the bus, without transferring any data.
  95 .It Dv SMB_SENDB Ta
  96 The
  97 .Em SendByte
  98 command sends the byte provided in the
  99 .Fa cmd
 100 field to the device.
 101 .It Dv SMB_RECVB Ta
 102 The
 103 .Em ReceiveByte
 104 command reads a single byte from the device which will
 105 be returned in the
 106 .Fa cmd
 107 field.
 108 .It Dv SMB_WRITEB Ta
 109 The
 110 .Em WriteByte
 111 command first sends the byte from the
 112 .Fa cmd
 113 field to the device, followed by the byte given in
 114 .Fa wdata.byte .
 115 .It Dv SMB_WRITEW Ta
 116 The
 117 .Em WriteWord
 118 command first sends the byte from the
 119 .Fa cmd
 120 field to the device, followed by the word given in
 121 .Fa wdata.word .
 122 Note that the SMBus byte-order is little-endian by definition.
 123 .It Dv SMB_READB Ta
 124 The
 125 .Em ReadByte
 126 command first sends the byte from the
 127 .Fa cmd
 128 field to the device, and then reads one byte of data from
 129 the device.
 130 The returned data will be stored in
 131 .Fa rdata.byte .
 132 .It Dv SMB_READW Ta
 133 The
 134 .Em ReadWord
 135 command first sends the byte from the
 136 .Fa cmd
 137 field to the device, and then reads one word of data from
 138 the device.
 139 The returned data will be stored in
 140 .Fa rdata.word .
 141 .It Dv SMB_PCALL Ta
 142 The
 143 .Em ProcedureCall
 144 command first sends the byte from the
 145 .Fa cmd
 146 field to the device, followed by the word provided in
 147 .Fa wdata.word .
 148 It then reads one word of data from the device, and returns it
 149 in
 150 .Fa rdata.word .
 151 .It Dv SMB_BWRITE Ta
 152 The
 153 .Em BlockWrite
 154 command first sends the byte from the
 155 .Fa cmd
 156 field to the device, followed by
 157 .Fa wcount
 158 bytes of data that are taken from the buffer pointed to by
 159 .Fa wbuf .
 160 The SMBus specification mandates that no more than 32 bytes of
 161 data can be transferred in a single block read or write command,
 162 but since
 163 .Xr smbus 4
 164 is also used to access I2C devices, the limit has been increased
 165 to 1024.
 166 This value is available in the constant
 167 .Dv SMB_MAXBLOCKSIZE .
 168 .It Dv SMB_BREAD Ta
 169 The
 170 .Em BlockRead
 171 command first sends the byte from the
 172 .Fa cmd
 173 field to the device, and then reads
 174 .Fa rcount
 175 bytes of data that from the device.
 176 These data will be returned in the buffer pointed to by
 177 .Fa rbuf .
 178 .It Dv SMB_TRANS Ta
 179 The
 180 .Em Trans
 181 command sends an SMB roll-up transaction with flags that also allow it to
 182 be used for (mostly) I2C pass-through and with with 10-bit addresses.
 183 This function can be used to roll up all of the above functions.
 184 It first sends the byte from the
 185 .Fa cmd
 186 field to the device, followed by
 187 .Fa wcount
 188 bytes of data that are taken from the buffer pointed to by
 189 .Fa wbuf ,
 190 then reads
 191 .Fa rcount
 192 bytes of data that from the device.
 193 These data will be returned in the buffer pointed to by
 194 .Fa rbuf .
 195 .Pp
 196 The following flags are allowed in
 197 .Fa op :
 198 .Pp
 199 .Bd -literal -compact
 200 SMB_TRANS_NOSTOP  Do not send STOP at end
 201 SMB_TRANS_NOCMD   Ignore cmd field (do not tx)
 202 SMB_TRANS_NOCNT   Do not tx or rx count field
 203 SMB_TRANS_7BIT    Change address mode to 7-bit
 204 SMB_TRANS_10BIT   Change address mode to 10-bit
 205 .Ed
 206 .El
 207 .Pp
 208 The
 209 .Xr read 2
 210 and
 211 .Xr write 2
 212 system calls are not implemented by this driver.
 213 .Sh ERRORS
 214 The
 215 .Xr ioctl 2
 216 commands can cause the following driver-specific errors:
 217 .Bl -tag -width Er
 218 .It Bq Er ENXIO
 219 Device did not respond to selection.
 220 .It Bq Er EBUSY
 221 Device still in use.
 222 .It Bq Er ENODEV
 223 Operation not supported by device (not supposed to happen).
 224 .It Bq Er EINVAL
 225 General argument error.
 226 .It Bq Er EWOULDBLOCK
 227 SMBus transaction timed out.
 228 .El
 229 .Sh SEE ALSO
 230 .Xr ioctl 2 ,
 231 .Xr smbus 4
 232 .Sh HISTORY
 233 The
 234 .Nm
 235 manual page first appeared in
 236 .Fx 3.0 .
 237 .Sh AUTHORS
 238 This
 239 manual page was written by
 240 .An Nicolas Souchu
 241 and extended by
 242 .An Michael Gmelin Aq freebsd@grem.de
 243 .