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.Dd January 5, 2018 26.Dt CPUCONTROL 8 27.Os 28.Sh NAME 29.Nm cpucontrol 30.Nd control utility for the 31.Xr cpuctl 4 32device 33.Sh SYNOPSIS 34.Bk 35.Nm 36.Op Fl v 37.Fl m Ar msr 38.Ar device 39.Ek 40.Bk 41.Nm 42.Op Fl v 43.Fl m Ar msr Ns = Ns Ar value 44.Ar device 45.Ek 46.Bk 47.Nm 48.Op Fl v 49.Fl m Ar msr Ns &= Ns Ar mask 50.Ar device 51.Ek 52.Bk 53.Nm 54.Op Fl v 55.Fl m Ar msr Ns |= Ns Ar mask 56.Ar device 57.Ek 58.Bk 59.Nm 60.Op Fl v 61.Fl i Ar level 62.Ar device 63.Ek 64.Bk 65.Nm 66.Op Fl v 67.Fl i Ar level,level_type 68.Ar device 69.Ek 70.Bk 71.Nm 72.Op Fl vn 73.Op Fl d Ar datadir 74.Fl u 75.Ar device 76.Ek 77.Bk 78.Nm 79.Fl e 80.Ar device 81.Ek 82.Sh DESCRIPTION 83The 84.Nm 85utility can be used to read and write arbitrary machine-specific 86CPU registers via the 87.Xr cpuctl 4 88special device. 89It can also be used to apply CPU firmware updates. 90.Pp 91The following options are available: 92.Bl -tag -width indent 93.It Fl d Ar datadir 94Directory paths where to look for microcode images. 95The option can be specified multiple times. 96The paths are added in order of the options appearance on the command 97line, default directories are appended after the user-supplied paths. 98.It Fl n 99Do not look for the microcode images in the standard directories. 100Currently standard directory to look for the microcode update files is 101.Pa /usr/local/share/cpucontrol . 102.It Fl m Ar msr 103Show value of the specified MSR. 104MSR register number should be given as a hexadecimal number. 105The high word is printed first, then the low word is printed second. 106.It Fl m Ar msr Ns = Ns Ar value 107Store the 108.Ar value 109in the specified MSR register. 110The 111.Ar value 112argument can be prefixed with ~ operator. 113In this case the inverted value of argument will be stored in the register. 114.It Fl m Ar msr Ns &= Ns Ar mask 115Store the result of bitwise AND operation between 116.Ar mask 117and the current MSR value in the MSR register. 118The 119.Ar mask 120argument can be prefixed with ~ operator. 121In this case the inverted value of mask will be used. 122.It Fl m Ar msr Ns |= Ns Ar mask 123Store the result of bitwise OR operation between 124.Ar mask 125and the current MSR value in the MSR register. 126The 127.Ar mask 128argument can be prefixed with ~ operator. 129In this case the inverted value of mask will be used. 130.It Fl i Ar level 131Retrieve CPUID info. 132Level should be given as a hex number. 133.It Fl i Ar level,level_type 134Retrieve CPUID info. 135Level and level_type should be given as hex numbers. 136.It Fl u 137Apply CPU firmware updates. 138The 139.Nm 140utility will walk through the configured data directories 141and apply all firmware updates available for this CPU. 142.It Fl e 143Re-evaluate the kernel flags indicating the present CPU features. 144This command is typically executed after a firmware update was applied 145which changes information reported by the 146.Dv CPUID 147instruction. 148.Pp 149.Bf -symbolic 150Only execute the 151.Fl e 152command after the microcode update was applied to all CPUs in the system. 153The kernel does not operate correctly if the features of processors are 154not identical. 155.Ef 156.It Fl v 157Increase the verbosity level. 158.It Fl h 159Show help message. 160.El 161.Sh EXIT STATUS 162.Ex -std 163.Sh EXAMPLES 164The command 165.Pp 166.Dq Li "cpucontrol -m 0x10 /dev/cpuctl0" 167.Pp 168will read the contents of TSC MSR from CPU 0. 169.Pp 170To set the CPU 0 TSC MSR register value to 0x1 issue 171.Pp 172.Dq Li "cpucontrol -m 0x10=0x1 /dev/cpuctl0" . 173.Pp 174The following command will clear the second bit of TSC register: 175.Pp 176.Dq Li "cpucontrol -m 0x10&=~0x02 /dev/cpuctl0" . 177.Pp 178The following command will set the forth and second bit of TSC register: 179.Pp 180.Dq Li "cpucontrol -m 0x10|=0x0a /dev/cpuctl0" . 181.Pp 182The command 183.Pp 184.Dq Li "cpucontrol -i 0x1 /dev/cpuctl1" 185.Pp 186will retrieve the CPUID level 0x1 from CPU 1. 187.Pp 188To perform firmware updates on CPU 0 from images located at 189.Pa /usr/local/share/cpuctl 190use the following command: 191.Pp 192.Dq Li "cpucontrol -nd /usr/local/share/cpuctl -u /dev/cpuctl0" 193.Sh SEE ALSO 194.Xr cpuctl 4 195.Sh HISTORY 196The 197.Nm 198utility first appeared in 199.Fx 7.2 . 200.Sh AUTHORS 201The 202.Nm 203utility and this manual page was written by 204.An Stanislav Sedov Aq Mt stas@FreeBSD.org . 205