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