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