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, then the byte from
 145 .Fa wcount
 146 followed by
 147 .Fa wcount
 148 bytes of data that are taken from the buffer pointed to by
 149 .Fa wbuf .
 150 The SMBus specification mandates that no more than 32 bytes of
 151 data can be transferred in a single block read or write command.
 152 This value can be read from the constant
 153 .Dv SMB_MAXBLOCKSIZE .
 154 .It Dv SMB_BREAD Ta
 155 .Em BlockRead
 156 first sends the byte from
 157 .Fa cmd
 158 to the device, then reads a count of data bytes that the device
 159 is going to provide and then reads that many bytes.
 160 The count is returned in
 161 .Fa rcount.
 162 The data is returned in the buffer pointed to by
 163 .Fa rbuf .
 164 .El
 165 .Pp
 166 The
 167 .Xr read 2
 168 and
 169 .Xr write 2
 170 system calls are not implemented by this driver.
 171 .Sh ERRORS
 172 The
 173 .Xr ioctl 2
 174 commands can cause the following driver-specific errors:
 175 .Bl -tag -width Er
 176 .It Bq Er ENXIO
 177 Device did not respond to selection.
 178 .It Bq Er EBUSY
 179 Device still in use.
 180 .It Bq Er ENODEV
 181 Operation not supported by device (not supposed to happen).
 182 .It Bq Er EINVAL
 183 General argument error.
 184 .It Bq Er EWOULDBLOCK
 185 SMBus transaction timed out.
 186 .El
 187 .Sh SEE ALSO
 188 .Xr ioctl 2 ,
 189 .Xr smbus 4
 190 .Sh HISTORY
 191 The
 192 .Nm
 193 manual page first appeared in
 194 .Fx 3.0 .
 195 .Sh AUTHORS
 196 This
 197 manual page was written by
 198 .An Nicolas Souchu
 199 and extended by
 200 .An Michael Gmelin Aq freebsd@grem.de .