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