share/man/man4/cpuctl.4

   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: head/share/man/man4/cpuctl.4 267938 2014-06-26 21:46:14Z bapt $
  26 .\"
  27 .Dd April 12, 2016
  28 .Dt CPUCTL 4
  29 .Os
  30 .Sh NAME
  31 .Nm cpuctl
  32 .Nd cpuctl pseudo device
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following lines in your kernel
  36 configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device cpuctl"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the driver as a module
  42 at boot time, place the following in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 cpuctl_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The special device
  49 .Pa /dev/cpuctl
  50 presents interface to the system CPU.
  51 It provides functionality to retrieve
  52 CPUID information, read/write machine specific registers (MSR) and perform
  53 CPU firmware updates.
  54 .Pp
  55 For each CPU present in the system, the special device
  56 .Pa /dev/cpuctl%d
  57 with the appropriate index will be created.
  58 For multicore CPUs such a
  59 special device will be created for each core.
  60 .Pp
  61 Currently, only x86_64 processors are supported.
  62 .Sh IOCTL INTERFACE
  63 All of the supported operations are invoked using the
  64 .Xr ioctl 2
  65 system call.
  66 Currently, the following ioctls are defined:
  67 .Bl -tag -width ".Dv CPUCTL_CPUID_COUNT"
  68 .It Dv CPUCTL_RDMSR Fa cpuctl_msr_args_t *args
  69 .It Dv CPUCTL_WRMSR Fa cpuctl_msr_args_t *args
  70 Read/write CPU machine specific register.
  71 The
  72 .Vt cpuctl_msr_args_t
  73 structure is defined in
  74 .In sys/cpuctl.h
  75 as:
  76 .Bd -literal
  77 typedef struct {
  78         int             msr;    /* MSR to read */
  79         uint64_t        data;
  80 } cpuctl_msr_args_t;
  81 .Ed
  82 .It Dv CPUCTL_MSRSBIT Fa cpuctl_msr_args_t *args
  83 .It Dv CPUCTL_MSRCBIT Fa cpuctl_msr_args_t *args
  84 Set/clear MSR bits according to the mask given in the
  85 .Va data
  86 field.
  87 .It Dv CPUCTL_CPUID Fa cpuctl_cpuid_args_t *args
  88 Retrieve CPUID information.
  89 Arguments are supplied in the following structure:
  90 .Bd -literal
  91 typedef struct {
  92         int             level;          /* CPUID level */
  93         uint32_t        data[4];
  94 } cpuctl_cpuid_args_t;
  95 .Ed
  96 It is equivalent to the
  97 .Dv CPUCTL_CPUID_COUNT
  98 request with
  99 .Va level_type
 100 set to 0.
 101 .It Dv CPUCTL_CPUID_COUNT Fa cpuctl_cpuid_count_args_t *args
 102 Retrieve CPUID information.
 103 Arguments are supplied in the following structure:
 104 .Bd -literal
 105 typedef struct {
 106         int             level;          /* CPUID level */
 107         int             level_type;     /* CPUID level type */
 108         uint32_t        data[4];
 109 } cpuctl_cpuid_count_args_t;
 110 .Ed
 111 The
 112 .Va level
 113 field indicates the CPUID level to retrieve,
 114 it is loaded into the
 115 .Va %eax
 116 register before the CPUID instruction is executed,
 117 The
 118 .Va level_type
 119 field indicates the CPUID level type to retrieve,
 120 it is loaded into the
 121 .Va %ecx
 122 register.
 123 .Pp
 124 The
 125 .Va data
 126 field is used to store the received CPUID data.
 127 That is,
 128 .Va data[0]
 129 contains the value of
 130 .Va %eax
 131 register after the CPUID instruction is executed,
 132 .Va data[1]
 133 is for
 134 .Va %ebx ,
 135 .Va data[2]
 136 for
 137 .Va %ecx ,
 138 and
 139 .Va data[3]
 140 for
 141 .Va %edx .
 142 .It Dv CPUCTL_UPDATE cpuctl_update_args_t *args
 143 Update CPU firmware (microcode).
 144 The structure is defined in
 145 .In sys/cpuctl.h
 146 as:
 147 .Bd -literal
 148 typedef struct {
 149         void    *data;
 150         size_t  size;
 151 } cpuctl_update_args_t;
 152 .Ed
 153 .Pp
 154 The
 155 .Va data
 156 field should point to the firmware image of size
 157 .Va size .
 158 .El
 159 .Pp
 160 For additional information refer to
 161 .Pa cpuctl.h .
 162 .Sh FILES
 163 .Bl -tag -width /dev/cpuctl -compact
 164 .It Pa /dev/cpuctl
 165 .El
 166 .Sh ERRORS
 167 .Bl -tag -width Er
 168 .It Bq Er ENXIO
 169 The operation requested is not supported by the device (e.g., unsupported
 170 architecture or the CPU is disabled).
 171 .It Bq Er EINVAL
 172 Incorrect request was supplied, or microcode image is not correct.
 173 .It Bq Er ENOMEM
 174 No physical memory was available to complete the request.
 175 .It Bq Er EFAULT
 176 The firmware image address points outside the process address space.
 177 .El
 178 .Sh SEE ALSO
 179 .\".Xr hwpmc 4 ,
 180 .Xr cpucontrol 8
 181 .Sh HISTORY
 182 The
 183 .Nm
 184 driver first appeared in
 185 .Fx 7.2 .
 186 .Sh AUTHORS
 187 The
 188 .Nm
 189 module and this manual page were written by
 190 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
 191 .Sh BUGS
 192 Yes, probably, report if any.