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 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.
  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 .Em QuickWrite
  87 does not transfer any data.
  88 It just issues the device address with write intent to the bus.
  89 .It Dv SMB_QUICK_READ Ta
  90 .Em QuickRead
  91 does not transfer any data.
  92 It just issues the device address with read intent to the bus.
  93 .It Dv SMB_SENDB Ta
  94 .Em SendByte
  95 sends the byte provided in
  96 .Fa cmd
  97 to the device.
  98 .It Dv SMB_RECVB Ta
  99 .Em ReceiveByte
 100 reads a single byte from the device which is returned in
 101 .Fa cmd .
 102 .It Dv SMB_WRITEB Ta
 103 .Em WriteByte
 104 first sends the byte from
 105 .Fa cmd
 106 to the device, followed by the byte given in
 107 .Fa wdata.byte .
 108 .It Dv SMB_WRITEW Ta
 109 .Em WriteWord
 110 first sends the byte from
 111 .Fa cmd
 112 to the device, followed by the word given in
 113 .Fa wdata.word .
 114 Note that the SMBus byte-order is little-endian by definition.
 115 .It Dv SMB_READB Ta
 116 .Em ReadByte
 117 first sends the byte from
 118 .Fa cmd
 119 to the device, then reads one byte of data from
 120 the device.
 121 Returned data is stored in
 122 .Fa rdata.byte .
 123 .It Dv SMB_READW Ta
 124 .Em ReadWord
 125 first sends the byte from
 126 .Fa cmd
 127 to the device, then reads one word of data from
 128 the device.
 129 Returned data is stored in
 130 .Fa rdata.word .
 131 .It Dv SMB_PCALL Ta
 132 .Em ProcedureCall
 133 first sends the byte from
 134 .Fa cmd
 135 to the device, followed by the word provided in
 136 .Fa wdata.word .
 137 It then reads one word of data from the device and returns it
 138 in
 139 .Fa rdata.word .
 140 .It Dv SMB_BWRITE Ta
 141 .Em BlockWrite
 142 first sends the byte from
 143 .Fa cmd
 144 to the device, followed by
 145 .Fa wcount
 146 bytes of data that are taken from the buffer pointed to by
 147 .Fa wbuf .
 148 The SMBus specification mandates that no more than 32 bytes of
 149 data can be transferred in a single block read or write command,
 150 but since
 151 .Xr smbus 4
 152 is also used to access I2C devices, the limit has been increased
 153 to 1024.
 154 This value can be read from the constant
 155 .Dv SMB_MAXBLOCKSIZE .
 156 .It Dv SMB_BREAD Ta
 157 .Em BlockRead
 158 first sends the byte from
 159 .Fa cmd
 160 to the device, then reads
 161 .Fa rcount
 162 bytes of data that from the device.
 163 This data is returned in the buffer pointed to by
 164 .Fa rbuf .
 165 .It Dv SMB_TRANS Ta
 166 .Em Trans
 167 sends an SMB roll-up transaction with flags that also allow it to
 168 be used for (mostly) I2C pass-through and with 10-bit addresses.
 169 This function can be utilized to roll up all of the above functions.
 170 It first sends the byte from
 171 .Fa cmd
 172 to the device, followed by
 173 .Fa wcount
 174 bytes of data that are taken from the buffer pointed to by
 175 .Fa wbuf ,
 176 then reads
 177 .Fa rcount
 178 bytes of data that from the device.
 179 This data is returned in the buffer pointed to by
 180 .Fa rbuf .
 181 .Pp
 182 The following flags are allowed in
 183 .Fa op :
 184 .Pp
 185 .Bd -literal -compact
 186 SMB_TRANS_NOSTOP  Do not send STOP at end
 187 SMB_TRANS_NOCMD   Ignore cmd field (do not tx)
 188 SMB_TRANS_NOCNT   Do not tx or rx count field
 189 SMB_TRANS_7BIT    Change address mode to 7-bit
 190 SMB_TRANS_10BIT   Change address mode to 10-bit
 191 .Ed
 192 .El
 193 .Pp
 194 The
 195 .Xr read 2
 196 and
 197 .Xr write 2
 198 system calls are not implemented by this driver.
 199 .Sh ERRORS
 200 The
 201 .Xr ioctl 2
 202 commands can cause the following driver-specific errors:
 203 .Bl -tag -width Er
 204 .It Bq Er ENXIO
 205 Device did not respond to selection.
 206 .It Bq Er EBUSY
 207 Device still in use.
 208 .It Bq Er ENODEV
 209 Operation not supported by device (not supposed to happen).
 210 .It Bq Er EINVAL
 211 General argument error.
 212 .It Bq Er EWOULDBLOCK
 213 SMBus transaction timed out.
 214 .El
 215 .Sh SEE ALSO
 216 .Xr ioctl 2 ,
 217 .Xr smbus 4
 218 .Sh HISTORY
 219 The
 220 .Nm
 221 manual page first appeared in
 222 .Fx 3.0 .
 223 .Sh AUTHORS
 224 This
 225 manual page was written by
 226 .An Nicolas Souchu
 227 and extended by
 228 .An Michael Gmelin Aq freebsd@grem.de .