usr.sbin/smbmsg/smbmsg.8

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