usr.sbin/smbmsg/smbmsg.8

   1 .\" Copyright (c) 2004 Joerg Wunsch
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd May 16, 2004
  28 .Dt SMBMSG 8
  29 .Os
  30 .Sh NAME
  31 .Nm smbmsg
  32 .Nd "send or receive messages over an SMBus"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl f Ar dev
  36 .Fl p
  37 .Pp
  38 .Nm
  39 .Op Fl f Ar dev
  40 .Fl s Ar slave
  41 .Op Fl F Ar fmt
  42 .Op Fl c Ar cmd
  43 .Op Fl w
  44 .Op Fl i Ar incnt
  45 .Op Fl o Ar outcnt
  46 .Op Ar outdata ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility can be used to send or receive messages over an
  51 SMBus, see
  52 .Xr smbus 4 .
  53 .Pp
  54 The
  55 .Nm
  56 utility has two different modi of operation.
  57 The first form shown in the synopsis can be used to
  58 .Dq probe
  59 the devices on the SMBus.
  60 This is done by sending each valid device address one
  61 receive byte, and one quick read message, respectively.
  62 Devices that respond to these requests will by displayed
  63 by their device address, followed by the strings
  64 .Ql r ,
  65 .Ql w ,
  66 or
  67 .Ql rw ,
  68 for devices that are readable, writeable, or both, readable
  69 and writeable, respectively.
  70 The only valid additional option for this modus of operation (besides
  71 the
  72 .Fl p
  73 option that chooses the modus) is
  74 .Fl f Ar dev .
  75 See below for a description.
  76 .Pp
  77 Note that probing the bus is risky, since individual devices could
  78 perform unwanted actions upon receiving one of the mentioned messages.
  79 For example, if a particular SMBus device considers
  80 .Em any
  81 write operation issued to it as a request to power off the system,
  82 the probing would trigger this action.
  83 .Pp
  84 The second form shown in the synopsis can be used to send or receive
  85 arbitrary messages to or from individual devices.
  86 This might be useful to explore individual devices on the SMBus, or
  87 maybe even to write short shell scripts performing maintenance
  88 operations on the bus.
  89 .Pp
  90 Any data values on the command-line are integer values in the
  91 range 0 through 255 for byte values, or 0 through 65535 for
  92 word values.
  93 They can be specified using standard
  94 .Ql C
  95 notation (prefix 0 for octal interpretation, or 0x for
  96 hexadecimal interpretation).
  97 .Pp
  98 Since the low-order bit of the device address of SMBus devices
  99 selects between read and write operations, only even-numbered
 100 slave addresses can exist on the bus.
 101 .Pp
 102 The options are as follows:
 103 .Bl -tag -width ".Fl o Ar outcnt"
 104 .It Fl F Ar fmt
 105 Specify the
 106 .Xr printf 3
 107 format to be used for displaying input data.
 108 This option is ignored in messages that do not read any input
 109 from the SMBus device.
 110 The format defaults to
 111 .Ql 0x%02x
 112 for byte input operations, and to
 113 .Ql 0x%04x
 114 for word input operations.
 115 For multi-byte input (block read), the same format is used for
 116 each individual byte read from the SMBus.
 117 .It Fl c Ar cmd
 118 This is the value of the
 119 .Em command
 120 byte to be issued as part of the SMBus message.
 121 .It Fl f Ar dev
 122 This specifies that
 123 .Ar dev
 124 should be used as the connection to the SMBus, rather than the
 125 default of
 126 .Pa /dev/smb0 .
 127 .It Fl i Ar incnt
 128 An SMBus message should be generated to read
 129 .Ar incnt
 130 bytes from the device.
 131 .It Fl o Ar outcnt
 132 An SMBus message should be generated to write
 133 .Ar outcnt
 134 bytes to the device.
 135 The data values to write are expected to follow all of the options
 136 (and their arguments) on the command-line, where the number of data
 137 bytes must match the
 138 .Ar outcnt
 139 value.
 140 .It Fl p
 141 This selects the
 142 .Em probe bus
 143 modus of operation.
 144 .It Fl s Ar slave
 145 The
 146 .Ar slave
 147 parameter specifies which SMBus device to connect to.
 148 This option also selects the
 149 .Em transfer messages from/to device
 150 modus of operation, where a slave address is mandatory.
 151 .It Fl w
 152 This option specifies that IO operations are word operations,
 153 rather than byte operations.
 154 Either
 155 .Ar incnt ,
 156 or
 157 .Ar outcnt
 158 (or both) must be equal 2 in this case.
 159 Note that the SMBus byte order is defined to be little-endian
 160 (low byte first, high byte follows).
 161 .El
 162 .Pp
 163 Not all argument combinations make sense in order to form valid SMBus
 164 messages.
 165 If no
 166 .Fl c Ar cmd
 167 option has been provided, the following messages can be
 168 issued:
 169 .Bd -unfilled -offset indent
 170 .TS
 171 l r r.
 172 \fBmessage      incnt   outcnt\fR
 173 quick read      0       \&-
 174 quick write     \&-     0
 175 receive byte    1       \&-
 176 send byte       \&-     1
 177 .TE
 178 .Ed
 179 .Pp
 180 Note in particular that specifying 0 as a count value
 181 has a different meaning than omitting the respective
 182 option entirely.
 183 .Pp
 184 If a command value has been given using the
 185 .Fl c Ar cmd
 186 option, the following messages can be generated:
 187 .Bd -unfilled -offset indent
 188 .TS
 189 l l r r.
 190 \fBmessage      \&-w    incnt   outcnt\fR
 191 read byte       no      1       \&-
 192 write byte      no      \&-     1
 193 read word       yes     2       \&-
 194 write word      yes     \&-     2
 195 process call    yes     2       2
 196 block read      no      \*(Ge 2 \&-
 197 block write     no      \&-     \*(Ge 2
 198 .TE
 199 .Ed
 200 .Sh FILES
 201 .Bl -tag -width ".Pa /dev/smb0" -compact
 202 .It Pa /dev/smb0
 203 The default device to connect to, unless
 204 .Fl f Ar dev
 205 has been provided.
 206 .El
 207 .Sh EXIT STATUS
 208 Exit status is 0 on success, or according to
 209 .Xr sysexits 3
 210 in case of failure.
 211 .Sh EXAMPLES
 212 Typical usage examples of the
 213 .Nm
 214 command include:
 215 .Pp
 216 .Dl "smbmsg -f /dev/smb1 -p"
 217 .Pp
 218 Probe all devices on the SMBus attached to
 219 .Pa /dev/smb1 .
 220 .Pp
 221 .Dl "smbmsg -s 0x70 -i 1"
 222 .Pp
 223 Issue a
 224 .Em receive byte
 225 message to the device at address 0x70, and display
 226 the received byte using the default format.
 227 .Pp
 228 .Dl "smbmsg -s 0x70 -c 0xff -i 1 -F %d"
 229 .Pp
 230 Issue a
 231 .Em read byte
 232 message to the device at slave address 0x70, using
 233 255 (0xff) as the command-byte to send to the device,
 234 and display the result using the custom format
 235 .Ql %d .
 236 .Pp
 237 .Dl "smbmsg -s 0xa0 -c 0 -o 1 0x80"
 238 .Pp
 239 Send a
 240 .Em write byte
 241 message to the slave device at address 0xa0, using
 242 0 as the command-byte value, and 0x80 as the byte to
 243 send (after the command).
 244 Assuming this might be a Philips PCF8583 real-time clock,
 245 this would stop the clock.
 246 .Pp
 247 .Dl "smbmsg -s 0xa0 -c 1 -i 6 -F %02x"
 248 .Pp
 249 Send a
 250 .Em block read
 251 command to device at address 0xa0, and read 6 bytes from
 252 it, using hexadecimal display.
 253 Again, assuming a PCF8583 RTC, this would display the
 254 fractions of second, seconds, minutes, hours, year/date,
 255 and weekday/month values.
 256 Since this RTC uses BCD notation, the actual values displayed
 257 were decimal then.
 258 .Pp
 259 .Dl "smbmsg -s 0xa0 -c 2 -o 5 0x00 0x07 0x22 0x16 0x05"
 260 .Pp
 261 Send a
 262 .Em block write
 263 command to device at address 0xa0.
 264 For the PCF8583 RTC, this would set the clock to Sunday (2004%4)-05-16
 265 22:07:00.
 266 .Sh DIAGNOSTICS
 267 Diagnostic messages issued are supposed to be self-explanatory.
 268 .Sh SEE ALSO
 269 .Xr printf 3 ,
 270 .Xr sysexits 3 ,
 271 .Xr smb 4 ,
 272 .Xr smbus 4
 273 .Rs
 274 .%T "The SMBus specification"
 275 .%U http://www.smbus.org/specs/
 276 .Re
 277 .Sh HISTORY
 278 The
 279 .Nm
 280 utility first appeared in
 281 .Fx 5.3 .
 282 .Sh AUTHORS
 283 The
 284 .Nm
 285 utility and this manual page were written by
 286 .An J\(:org Wunsch .