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