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