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