1.\" Copyright (c) 2006, 2008 Stanislav Sedov <stas@FreeBSD.org>.
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: release/10.0.0/usr.sbin/cpucontrol/cpucontrol.8 235873 2012-05-24 02:24:03Z wblock $
26.\"
27.Dd June 30, 2009
28.Dt CPUCONTROL 8
29.Os
30.Sh NAME
31.Nm cpucontrol
32.Nd control utility for the
33.Xr cpuctl 4
34device
35.Sh SYNOPSIS
36.Nm
37.Op Fl vh
38.Fl m Ar msr
39.Bk
40.Ar device
41.Ek
42.Nm
43.Op Fl vh
44.Fl m Ar msr Ns = Ns Ar value
45.Bk
46.Ar device
47.Ek
48.Nm
49.Op Fl vh
50.Fl m Ar msr Ns &= Ns Ar mask
51.Bk
52.Ar device
53.Ek
54.Nm
55.Op Fl vh
56.Fl m Ar msr Ns |= Ns Ar mask
57.Bk
58.Ar device
59.Ek
60.Nm
61.Op Fl vh
62.Fl i Ar level
63.Bk
64.Ar device
65.Ek
66.Nm
67.Op Fl vh
68.Op Fl d Ar datadir
69.Fl u
70.Bk
71.Ar device
72.Ek
73.Sh DESCRIPTION
74The
75.Nm
76utility can be used to read and write arbitrary machine-specific
77CPU registers via the
78.Xr cpuctl 4
79special device.
80It can also be used to apply CPU firmware updates.
81.Pp
82The following options are available:
83.Bl -tag -width indent
84.It Fl d Ar datadir
85Where to look for microcode images.
86The option can be specified multiple times.
87.It Fl m Ar msr Ns Op = Ns Ar value
88Show value of the specified MSR.
89MSR register number should be given as a hexadecimal number.
90.It Fl m Ar msr Ns = Ns Ar value
91Store the
92.Ar value
93in the specified MSR register.
94The
95.Ar value
96argument can be prefixed with ~ operator.
97In this case the inverted value of argument will be stored in the register.
98.It Fl m Ar msr Ns &= Ns Ar mask
99Store the result of bitwise AND operation between
100.Ar mask
101and the current MSR value in the MSR register.
102The
103.Ar mask
104argument can be prefixed with ~ operator.
105In this case the inverted value of mask will be used.
106.It Fl m Ar msr Ns |= Ns Ar mask
107Store the result of bitwise OR operation between
108.Ar mask
109and the current MSR value in the MSR register.
110The
111.Ar mask
112argument can be prefixed with ~ operator.
113In this case the inverted value of mask will be used.
114.It Fl i Ar level
115Retrieve CPUID info.
116Level should be given as a hex number.
117.It Fl u
118Apply CPU firmware updates.
119The
120.Nm
121utility will walk through the configured data directories
122and apply all firmware updates available for this CPU.
123.It Fl v
124Increase the verbosity level.
125.It Fl h
126Show help message.
127.El
128.Sh EXIT STATUS
129.Ex -std
130.Sh EXAMPLES
131The command
132.Pp
133.Dq Li "cpucontrol -m 0x10 /dev/cpuctl0"
134.Pp
135will read the contents of TSC MSR from CPU 0.
136.Pp
137To set the CPU 0 TSC MSR register value to 0x1 issue
138.Pp
139.Dq Li "cpucontrol -m 0x10=0x1 /dev/cpuctl0" .
140.Pp
141The following command will clear the second bit of TSC register:
142.Pp
143.Dq Li "cpucontrol -m 0x10&=~0x02 /dev/cpuctl0" .
144.Pp
145The following command will set the forth and second bit of TSC register:
146.Pp
147.Dq Li "cpucontrol -m 0x10|=0x0a /dev/cpuctl0" .
148.Pp
149The command
150.Pp
151.Dq Li "cpucontrol -i 0x1 /dev/cpuctl1"
152.Pp
153will retrieve the CPUID level 0x1 from CPU 1.
154.Pp
155To perform firmware updates on CPU 0 from images located at
156.Pa /usr/local/share/cpuctl/
157use the following command:
158.Pp
159.Dq Li "cpucontrol -d /usr/local/share/cpuctl/ -u /dev/cpuctl0"
160.Sh SEE ALSO
161.Xr cpuctl 4
162.Sh HISTORY
163The
164.Nm
165utility first appeared in
166.Fx 7.2 .
167.Sh AUTHORS
168The
169.Nm
170utility and this manual page was written by
171.An Stanislav Sedov Aq stas@FreeBSD.org .
172.Sh BUGS
173Yes, probably, report if any.
174