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 .Pp
  49 .Bd -literal
  50 #include <sys/types.h>
  51
  52 struct smbcmd {
  53         char cmd;
  54         int count;
  55         u_char slave;
  56         union {
  57                 char byte;
  58                 short word;
  59
  60                 char *byte_ptr;
  61                 short *word_ptr;
  62
  63                 struct {
  64                         short sdata;
  65                         short *rdata;
  66                 } process;
  67         } data;
  68 };
  69 .Ed
  70 .Pp
  71 The
  72 .Fa slave
  73 field is always used, and provides the address of the
  74 SMBus slave device to talk to.
  75 The slave address is specified in the seven most significant bits
  76 .Pq i.e. Dq "left-justified" .
  77 The least significant bit of the slave address must be zero.
  78 .Pp
  79 .Bl -column ".Dv SMB_QUICK_WRITE" -compact
  80 .It Em Ioctl Ta Em Description
  81 .Pp
  82 .It Dv SMB_QUICK_WRITE Ta
  83 The
  84 .Em QuickWrite
  85 command just issues the device address with write intent
  86 to the bus, without transferring any data.
  87 .It Dv SMB_QUICK_READ Ta
  88 The
  89 .Em QuickRead
  90 command just issues the device address with read intent
  91 to the bus, without transferring any data.
  92 .It Dv SMB_SENDB Ta
  93 The
  94 .Em SendByte
  95 command sends the byte provided in the
  96 .Fa cmd
  97 field to the device.
  98 .It Dv SMB_RECVB Ta
  99 The
 100 .Em ReceiveByte
 101 command reads a single byte from the device which will
 102 be returned in the
 103 .Fa cmd
 104 field.
 105 .It Dv SMB_WRITEB Ta
 106 The
 107 .Em WriteByte
 108 command first sends the byte from the
 109 .Fa cmd
 110 field to the device, followed by the byte given in
 111 .Fa data.byte .
 112 .It Dv SMB_WRITEW Ta
 113 The
 114 .Em WriteWord
 115 command first sends the byte from the
 116 .Fa cmd
 117 field to the device, followed by the word given in
 118 .Fa data.word .
 119 Note that the SMBus byte-order is little-endian by definition.
 120 .It Dv SMB_READB Ta
 121 The
 122 .Em ReadByte
 123 command first sends the byte from the
 124 .Fa cmd
 125 field to the device, and then reads one byte of data from
 126 the device.
 127 The returned data will be stored in the location pointed to by
 128 .Fa data.byte_ptr .
 129 .It Dv SMB_READW Ta
 130 The
 131 .Em ReadWord
 132 command first sends the byte from the
 133 .Fa cmd
 134 field to the device, and then reads one word of data from
 135 the device.
 136 The returned data will be stored in the location pointed to by
 137 .Fa data.word_ptr .
 138 .It Dv SMB_PCALL Ta
 139 The
 140 .Em ProcedureCall
 141 command first sends the byte from the
 142 .Fa cmd
 143 field to the device, followed by the word provided in
 144 .Fa data.process.sdata .
 145 It then reads one word of data from the device, and returns it
 146 in the location pointed to by
 147 .Fa data.process.rdata .
 148 .It Dv SMB_BWRITE Ta
 149 The
 150 .Em BlockWrite
 151 command first sends the byte from the
 152 .Fa cmd
 153 field to the device, followed by
 154 .Fa count
 155 bytes of data that are taken from the buffer pointed to by
 156 .Fa data.byte_ptr .
 157 The SMBus specification mandates that no more than 32 bytes of
 158 data can be transferred in a single block read or write command.
 159 This value is available in the constant
 160 .Dv SMB_MAXBLOCKSIZE .
 161 .It Dv SMB_BREAD Ta
 162 The
 163 .Em BlockRead
 164 command first sends the byte from the
 165 .Fa cmd
 166 field to the device, and then reads
 167 .Fa count
 168 bytes of data that from the device.
 169 These data will be returned in the buffer pointed to by
 170 .Fa data.byte_ptr .
 171 .El
 172 .Pp
 173 The
 174 .Xr read 2
 175 and
 176 .Xr write 2
 177 system calls are not implemented by this driver.
 178 .Sh ERRORS
 179 The
 180 .Xr ioctl 2
 181 commands can cause the following driver-specific errors:
 182 .Bl -tag -width Er
 183 .It Bq Er ENXIO
 184 Device did not respond to selection.
 185 .It Bq Er EBUSY
 186 Device still in use.
 187 .It Bq Er ENODEV
 188 Operation not supported by device (not supposed to happen).
 189 .It Bq Er EINVAL
 190 General argument error.
 191 .It Bq Er EWOULDBLOCK
 192 SMBus transaction timed out.
 193 .El
 194 .Sh SEE ALSO
 195 .Xr ioctl 2 ,
 196 .Xr smbus 4
 197 .Sh HISTORY
 198 The
 199 .Nm
 200 manual page first appeared in
 201 .Fx 3.0 .
 202 .Sh AUTHORS
 203 This
 204 manual page was written by
 205 .An Nicolas Souchu .