xref: /freebsd-src/usr.sbin/smbmsg/smbmsg.8 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
1325bf22bSJoerg Wunsch.\" Copyright (c) 2004 Joerg Wunsch
2325bf22bSJoerg Wunsch.\" All rights reserved.
3325bf22bSJoerg Wunsch.\"
4325bf22bSJoerg Wunsch.\" Redistribution and use in source and binary forms, with or without
5325bf22bSJoerg Wunsch.\" modification, are permitted provided that the following conditions
6325bf22bSJoerg Wunsch.\" are met:
7325bf22bSJoerg Wunsch.\" 1. Redistributions of source code must retain the above copyright
8325bf22bSJoerg Wunsch.\"    notice, this list of conditions and the following disclaimer.
9325bf22bSJoerg Wunsch.\" 2. Redistributions in binary form must reproduce the above copyright
10325bf22bSJoerg Wunsch.\"    notice, this list of conditions and the following disclaimer in the
11325bf22bSJoerg Wunsch.\"    documentation and/or other materials provided with the distribution.
12325bf22bSJoerg Wunsch.\"
13325bf22bSJoerg Wunsch.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14325bf22bSJoerg Wunsch.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15325bf22bSJoerg Wunsch.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16325bf22bSJoerg Wunsch.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17325bf22bSJoerg Wunsch.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18325bf22bSJoerg Wunsch.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19325bf22bSJoerg Wunsch.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20325bf22bSJoerg Wunsch.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21325bf22bSJoerg Wunsch.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22325bf22bSJoerg Wunsch.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23325bf22bSJoerg Wunsch.\" SUCH DAMAGE.
24325bf22bSJoerg Wunsch.\"
25325bf22bSJoerg Wunsch.Dd May 16, 2004
26325bf22bSJoerg Wunsch.Dt SMBMSG 8
27325bf22bSJoerg Wunsch.Os
28325bf22bSJoerg Wunsch.Sh NAME
29325bf22bSJoerg Wunsch.Nm smbmsg
30325bf22bSJoerg Wunsch.Nd "send or receive messages over an SMBus"
31325bf22bSJoerg Wunsch.Sh SYNOPSIS
32325bf22bSJoerg Wunsch.Nm
33325bf22bSJoerg Wunsch.Op Fl f Ar dev
34325bf22bSJoerg Wunsch.Fl p
35325bf22bSJoerg Wunsch.Pp
36325bf22bSJoerg Wunsch.Nm
37325bf22bSJoerg Wunsch.Op Fl f Ar dev
38325bf22bSJoerg Wunsch.Fl s Ar slave
39325bf22bSJoerg Wunsch.Op Fl F Ar fmt
40325bf22bSJoerg Wunsch.Op Fl c Ar cmd
41325bf22bSJoerg Wunsch.Op Fl w
42325bf22bSJoerg Wunsch.Op Fl i Ar incnt
43325bf22bSJoerg Wunsch.Op Fl o Ar outcnt
44325bf22bSJoerg Wunsch.Op Ar outdata ...
45325bf22bSJoerg Wunsch.Sh DESCRIPTION
46325bf22bSJoerg WunschThe
47325bf22bSJoerg Wunsch.Nm
4815bb4187SRuslan Ermilovutility can be used to send or receive messages over an
49325bf22bSJoerg WunschSMBus, see
50325bf22bSJoerg Wunsch.Xr smbus 4 .
51325bf22bSJoerg Wunsch.Pp
52325bf22bSJoerg WunschThe
53325bf22bSJoerg Wunsch.Nm
5415bb4187SRuslan Ermilovutility has two different modi of operation.
55325bf22bSJoerg WunschThe first form shown in the synopsis can be used to
56325bf22bSJoerg Wunsch.Dq probe
57325bf22bSJoerg Wunschthe devices on the SMBus.
58325bf22bSJoerg WunschThis is done by sending each valid device address one
59325bf22bSJoerg Wunschreceive byte, and one quick read message, respectively.
60*5c08832dSStefan EßerDevices that respond to these requests will be displayed
61325bf22bSJoerg Wunschby their device address, followed by the strings
62325bf22bSJoerg Wunsch.Ql r ,
63325bf22bSJoerg Wunsch.Ql w ,
64325bf22bSJoerg Wunschor
65325bf22bSJoerg Wunsch.Ql rw ,
66325bf22bSJoerg Wunschfor devices that are readable, writeable, or both, readable
67325bf22bSJoerg Wunschand writeable, respectively.
68325bf22bSJoerg WunschThe only valid additional option for this modus of operation (besides
69325bf22bSJoerg Wunschthe
70325bf22bSJoerg Wunsch.Fl p
71344c81a1SWarren Blockoption that chooses the modus) is
72325bf22bSJoerg Wunsch.Fl f Ar dev .
73325bf22bSJoerg WunschSee below for a description.
74325bf22bSJoerg Wunsch.Pp
75325bf22bSJoerg WunschNote that probing the bus is risky, since individual devices could
76325bf22bSJoerg Wunschperform unwanted actions upon receiving one of the mentioned messages.
77325bf22bSJoerg WunschFor example, if a particular SMBus device considers
78325bf22bSJoerg Wunsch.Em any
79325bf22bSJoerg Wunschwrite operation issued to it as a request to power off the system,
80325bf22bSJoerg Wunschthe probing would trigger this action.
81325bf22bSJoerg Wunsch.Pp
82325bf22bSJoerg WunschThe second form shown in the synopsis can be used to send or receive
83325bf22bSJoerg Wunscharbitrary messages to or from individual devices.
84325bf22bSJoerg WunschThis might be useful to explore individual devices on the SMBus, or
85325bf22bSJoerg Wunschmaybe even to write short shell scripts performing maintenance
86325bf22bSJoerg Wunschoperations on the bus.
87325bf22bSJoerg Wunsch.Pp
88325bf22bSJoerg WunschAny data values on the command-line are integer values in the
89325bf22bSJoerg Wunschrange 0 through 255 for byte values, or 0 through 65535 for
90325bf22bSJoerg Wunschword values.
91325bf22bSJoerg WunschThey can be specified using standard
92325bf22bSJoerg Wunsch.Ql C
93325bf22bSJoerg Wunschnotation (prefix 0 for octal interpretation, or 0x for
94325bf22bSJoerg Wunschhexadecimal interpretation).
95325bf22bSJoerg Wunsch.Pp
96325bf22bSJoerg WunschSince the low-order bit of the device address of SMBus devices
97325bf22bSJoerg Wunschselects between read and write operations, only even-numbered
98325bf22bSJoerg Wunschslave addresses can exist on the bus.
99325bf22bSJoerg Wunsch.Pp
100325bf22bSJoerg WunschThe options are as follows:
101325bf22bSJoerg Wunsch.Bl -tag -width ".Fl o Ar outcnt"
102325bf22bSJoerg Wunsch.It Fl F Ar fmt
103325bf22bSJoerg WunschSpecify the
104325bf22bSJoerg Wunsch.Xr printf 3
105325bf22bSJoerg Wunschformat to be used for displaying input data.
106325bf22bSJoerg WunschThis option is ignored in messages that do not read any input
107325bf22bSJoerg Wunschfrom the SMBus device.
108325bf22bSJoerg WunschThe format defaults to
109325bf22bSJoerg Wunsch.Ql 0x%02x
110325bf22bSJoerg Wunschfor byte input operations, and to
111325bf22bSJoerg Wunsch.Ql 0x%04x
112325bf22bSJoerg Wunschfor word input operations.
113325bf22bSJoerg WunschFor multi-byte input (block read), the same format is used for
114325bf22bSJoerg Wunscheach individual byte read from the SMBus.
115325bf22bSJoerg Wunsch.It Fl c Ar cmd
116325bf22bSJoerg WunschThis is the value of the
117325bf22bSJoerg Wunsch.Em command
118325bf22bSJoerg Wunschbyte to be issued as part of the SMBus message.
119325bf22bSJoerg Wunsch.It Fl f Ar dev
120325bf22bSJoerg WunschThis specifies that
121325bf22bSJoerg Wunsch.Ar dev
122325bf22bSJoerg Wunschshould be used as the connection to the SMBus, rather than the
123325bf22bSJoerg Wunschdefault of
124325bf22bSJoerg Wunsch.Pa /dev/smb0 .
125325bf22bSJoerg Wunsch.It Fl i Ar incnt
126325bf22bSJoerg WunschAn SMBus message should be generated to read
127325bf22bSJoerg Wunsch.Ar incnt
128325bf22bSJoerg Wunschbytes from the device.
129325bf22bSJoerg Wunsch.It Fl o Ar outcnt
130325bf22bSJoerg WunschAn SMBus message should be generated to write
131325bf22bSJoerg Wunsch.Ar outcnt
132325bf22bSJoerg Wunschbytes to the device.
133325bf22bSJoerg WunschThe data values to write are expected to follow all of the options
134325bf22bSJoerg Wunsch(and their arguments) on the command-line, where the number of data
135325bf22bSJoerg Wunschbytes must match the
136325bf22bSJoerg Wunsch.Ar outcnt
137325bf22bSJoerg Wunschvalue.
138325bf22bSJoerg Wunsch.It Fl p
139325bf22bSJoerg WunschThis selects the
140325bf22bSJoerg Wunsch.Em probe bus
141325bf22bSJoerg Wunschmodus of operation.
142325bf22bSJoerg Wunsch.It Fl s Ar slave
143325bf22bSJoerg WunschThe
144325bf22bSJoerg Wunsch.Ar slave
145325bf22bSJoerg Wunschparameter specifies which SMBus device to connect to.
146325bf22bSJoerg WunschThis option also selects the
147325bf22bSJoerg Wunsch.Em transfer messages from/to device
148325bf22bSJoerg Wunschmodus of operation, where a slave address is mandatory.
149325bf22bSJoerg Wunsch.It Fl w
150325bf22bSJoerg WunschThis option specifies that IO operations are word operations,
151325bf22bSJoerg Wunschrather than byte operations.
152325bf22bSJoerg WunschEither
153325bf22bSJoerg Wunsch.Ar incnt ,
154325bf22bSJoerg Wunschor
155325bf22bSJoerg Wunsch.Ar outcnt
156325bf22bSJoerg Wunsch(or both) must be equal 2 in this case.
157325bf22bSJoerg WunschNote that the SMBus byte order is defined to be little-endian
158325bf22bSJoerg Wunsch(low byte first, high byte follows).
159325bf22bSJoerg Wunsch.El
160325bf22bSJoerg Wunsch.Pp
161325bf22bSJoerg WunschNot all argument combinations make sense in order to form valid SMBus
162325bf22bSJoerg Wunschmessages.
163325bf22bSJoerg WunschIf no
164325bf22bSJoerg Wunsch.Fl c Ar cmd
165325bf22bSJoerg Wunschoption has been provided, the following messages can be
166325bf22bSJoerg Wunschissued:
167325bf22bSJoerg Wunsch.Bd -unfilled -offset indent
168325bf22bSJoerg Wunsch.TS
169325bf22bSJoerg Wunschl r r.
170325bf22bSJoerg Wunsch\fBmessage	incnt	outcnt\fR
171325bf22bSJoerg Wunschquick read	0	\&-
172325bf22bSJoerg Wunschquick write	\&-	0
173325bf22bSJoerg Wunschreceive byte	1	\&-
174325bf22bSJoerg Wunschsend byte	\&-	1
175325bf22bSJoerg Wunsch.TE
176325bf22bSJoerg Wunsch.Ed
177325bf22bSJoerg Wunsch.Pp
178325bf22bSJoerg WunschNote in particular that specifying 0 as a count value
179325bf22bSJoerg Wunschhas a different meaning than omitting the respective
180325bf22bSJoerg Wunschoption entirely.
181325bf22bSJoerg Wunsch.Pp
182325bf22bSJoerg WunschIf a command value has been given using the
183325bf22bSJoerg Wunsch.Fl c Ar cmd
184325bf22bSJoerg Wunschoption, the following messages can be generated:
185325bf22bSJoerg Wunsch.Bd -unfilled -offset indent
186325bf22bSJoerg Wunsch.TS
187325bf22bSJoerg Wunschl l r r.
188325bf22bSJoerg Wunsch\fBmessage	\&-w	incnt	outcnt\fR
189325bf22bSJoerg Wunschread byte	no	1	\&-
190325bf22bSJoerg Wunschwrite byte	no	\&-	1
191325bf22bSJoerg Wunschread word	yes	2	\&-
192325bf22bSJoerg Wunschwrite word	yes	\&-	2
193325bf22bSJoerg Wunschprocess call	yes	2	2
194325bf22bSJoerg Wunschblock read	no	\*(Ge 2	\&-
195325bf22bSJoerg Wunschblock write	no	\&-	\*(Ge 2
196325bf22bSJoerg Wunsch.TE
197325bf22bSJoerg Wunsch.Ed
198325bf22bSJoerg Wunsch.Sh FILES
199325bf22bSJoerg Wunsch.Bl -tag -width ".Pa /dev/smb0" -compact
200325bf22bSJoerg Wunsch.It Pa /dev/smb0
201325bf22bSJoerg WunschThe default device to connect to, unless
202325bf22bSJoerg Wunsch.Fl f Ar dev
203325bf22bSJoerg Wunschhas been provided.
204325bf22bSJoerg Wunsch.El
20559a3c79dSRuslan Ermilov.Sh EXIT STATUS
20659a3c79dSRuslan ErmilovExit status is 0 on success, or according to
20759a3c79dSRuslan Ermilov.Xr sysexits 3
20859a3c79dSRuslan Ermilovin case of failure.
209325bf22bSJoerg Wunsch.Sh EXAMPLES
210325bf22bSJoerg WunschTypical usage examples of the
211325bf22bSJoerg Wunsch.Nm
212325bf22bSJoerg Wunschcommand include:
213325bf22bSJoerg Wunsch.Pp
214325bf22bSJoerg Wunsch.Dl "smbmsg -f /dev/smb1 -p"
215325bf22bSJoerg Wunsch.Pp
216325bf22bSJoerg WunschProbe all devices on the SMBus attached to
217325bf22bSJoerg Wunsch.Pa /dev/smb1 .
218325bf22bSJoerg Wunsch.Pp
219325bf22bSJoerg Wunsch.Dl "smbmsg -s 0x70 -i 1"
220325bf22bSJoerg Wunsch.Pp
221325bf22bSJoerg WunschIssue a
222325bf22bSJoerg Wunsch.Em receive byte
223325bf22bSJoerg Wunschmessage to the device at address 0x70, and display
224325bf22bSJoerg Wunschthe received byte using the default format.
225325bf22bSJoerg Wunsch.Pp
226325bf22bSJoerg Wunsch.Dl "smbmsg -s 0x70 -c 0xff -i 1 -F %d"
227325bf22bSJoerg Wunsch.Pp
228325bf22bSJoerg WunschIssue a
229325bf22bSJoerg Wunsch.Em read byte
230325bf22bSJoerg Wunschmessage to the device at slave address 0x70, using
231325bf22bSJoerg Wunsch255 (0xff) as the command-byte to send to the device,
23215bb4187SRuslan Ermilovand display the result using the custom format
23315bb4187SRuslan Ermilov.Ql %d .
234325bf22bSJoerg Wunsch.Pp
235325bf22bSJoerg Wunsch.Dl "smbmsg -s 0xa0 -c 0 -o 1 0x80"
236325bf22bSJoerg Wunsch.Pp
237325bf22bSJoerg WunschSend a
238325bf22bSJoerg Wunsch.Em write byte
239325bf22bSJoerg Wunschmessage to the slave device at address 0xa0, using
240325bf22bSJoerg Wunsch0 as the command-byte value, and 0x80 as the byte to
241325bf22bSJoerg Wunschsend (after the command).
242325bf22bSJoerg WunschAssuming this might be a Philips PCF8583 real-time clock,
243325bf22bSJoerg Wunschthis would stop the clock.
244325bf22bSJoerg Wunsch.Pp
245325bf22bSJoerg Wunsch.Dl "smbmsg -s 0xa0 -c 1 -i 6 -F %02x"
246325bf22bSJoerg Wunsch.Pp
247325bf22bSJoerg WunschSend a
248325bf22bSJoerg Wunsch.Em block read
249325bf22bSJoerg Wunschcommand to device at address 0xa0, and read 6 bytes from
250325bf22bSJoerg Wunschit, using hexadecimal display.
251325bf22bSJoerg WunschAgain, assuming a PCF8583 RTC, this would display the
252325bf22bSJoerg Wunschfractions of second, seconds, minutes, hours, year/date,
253325bf22bSJoerg Wunschand weekday/month values.
254325bf22bSJoerg WunschSince this RTC uses BCD notation, the actual values displayed
255325bf22bSJoerg Wunschwere decimal then.
256325bf22bSJoerg Wunsch.Pp
257325bf22bSJoerg Wunsch.Dl "smbmsg -s 0xa0 -c 2 -o 5 0x00 0x07 0x22 0x16 0x05"
258325bf22bSJoerg Wunsch.Pp
259325bf22bSJoerg WunschSend a
260325bf22bSJoerg Wunsch.Em block write
261325bf22bSJoerg Wunschcommand to device at address 0xa0.
262325bf22bSJoerg WunschFor the PCF8583 RTC, this would set the clock to Sunday (2004%4)-05-16
263325bf22bSJoerg Wunsch22:07:00.
264a866e170SRuslan Ermilov.Sh DIAGNOSTICS
265325bf22bSJoerg WunschDiagnostic messages issued are supposed to be self-explanatory.
266325bf22bSJoerg Wunsch.Sh SEE ALSO
267325bf22bSJoerg Wunsch.Xr printf 3 ,
268325bf22bSJoerg Wunsch.Xr sysexits 3 ,
269325bf22bSJoerg Wunsch.Xr smb 4 ,
270325bf22bSJoerg Wunsch.Xr smbus 4
271325bf22bSJoerg Wunsch.Rs
272325bf22bSJoerg Wunsch.%T "The SMBus specification"
273aa4a335bSRuslan Ermilov.%U http://www.smbus.org/specs/
274325bf22bSJoerg Wunsch.Re
275325bf22bSJoerg Wunsch.Sh HISTORY
276325bf22bSJoerg WunschThe
277325bf22bSJoerg Wunsch.Nm
27815bb4187SRuslan Ermilovutility first appeared in
279325bf22bSJoerg Wunsch.Fx 5.3 .
280325bf22bSJoerg Wunsch.Sh AUTHORS
281325bf22bSJoerg WunschThe
282325bf22bSJoerg Wunsch.Nm
283325bf22bSJoerg Wunschutility and this manual page were written by
284325bf22bSJoerg Wunsch.An J\(:org Wunsch .
285