share/man/man4/smb.4

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