README
1.0 	09 June 2000, Simon Trimmer <simon@veritas.com>
	Initial release.
1.01	19 June 2000, Simon Trimmer <simon@veritas.com>
	general tidy up and argument sequencing fix
	added default microcode filename and -u switch

***************************************************************************
>>> What it does
***************************************************************************

The microcode_ctl utility is a companion to the P6 microcode driver written
by Tigran Aivazian <tigran@veritas.com>. The utility has two uses:

a) it decodes and sends new microcode to the kernel driver to be uploaded
   to Intel P6 family processors. (Pentium Pro, PII, PIII, Xeon etc)
b) it signals the kernel driver to release any buffers it may hold

The microcode update is volatile and needs to be uploaded on each system
boot i.e. it doesn't reflash your cpu permanently, reboot and it reverts
back to the old microcode.


***************************************************************************
>>> got an AMD or any non-Intel processor?
***************************************************************************

This driver is designed for Intel P6 microprocessors only, it will not work
with AMD or any other non-Intel processors as they don't support microcode
updates or they support it in a manner different from Intel's specs.


***************************************************************************
>>> how to compile the kernel to include support for microcode update
***************************************************************************

The microcode driver is a feature of the Linux kernel added to the v2.3
stream in February 2000, it needs to be enabled at compile time and it may
be compiled as a module. This utility relates to kernel 2.4.0-test1-ac10
or newer. (microcode driver v1.04+)

CONFIG_MICROCODE is in the "Processor type and features" configuration
section.

Since 2.4.0-test1-ac10 the kernel driver supports regular misc device and
devfs. To create the device node on a non-devfs system as root type:

# mkdir -p /dev/cpu/
# mknod /dev/cpu/microcode c 10 184

If you are using devfs, then you can either access the driver via regular
file /dev/cpu/microcode or via misc characte device /dev/misc/microcode, both
of which are created automatically by devfs.

***************************************************************************
>>> how to compile it
***************************************************************************

The utility has a simple Makefile to compile and install the software;

# make
gcc -g -Wall -o microcode_ctl microcode_ctl.c

# make install
mkdir -p /usr/local/bin
install -m 755 microcode_ctl /usr/local/bin
install -m 644 microcode.dat /etc


***************************************************************************
>>> getting Intel microcode
***************************************************************************

This package has a file called microcode.dat containing Intel microcode,
normally this file will be installed as /etc/microcode.dat

Intel P6 microcode updates will be hosted on this utility's web page:
http://www.urbanmyth.org/microcode/

***************************************************************************
>>> how to invoke it
***************************************************************************

The utility installs by default into /usr/local/bin as microcode_ctl
it can be invoked simply as /usr/local/bin/microcode_ctl -f /etc/microcode

The utility will print something like:

microcode_ctl: writing microcode (length: 98304)
microcode_ctl: microcode successfuly written to /dev/cpu/microcode

The driver will send messages to the system log (/var/log/messages) like:

microcode: CPU1 updated from revision 7 to 14, date=09101999
microcode: CPU0 updated from revision 7 to 14, date=09101999

The driver won't let you downgrade or apply the same microcode as the
version it is running, it is also possible that the current version of the
microcode does not include one suitable for your processor(s). In these
cases the utility will fail with EIO and the driver will print an
explanation into the system log. For example, refusal to downgrade the
microcode produces this message in the log:

microcode: CPU1 not 'upgrading' to earlier revision 14 (current=14)
microcode: CPU0 not 'upgrading' to earlier revision 14 (current=14)

which was caused by the second invocation of microcode_ctl:

# microcode_ctl -f microcode.dat
microcode_ctl: writing microcode (length: 98304)
microcode_ctl: error writing to '/dev/cpu/microcode' errno=5 (Input/output error)
microcode_ctl: there may be messages from the driver in your system log.


***************************************************************************
>>> freeing off the internal buffer
***************************************************************************

Running the utility with the option -i will signal the driver to release
any buffers it may have. It may be used in conjunction with -f if it
precedes it.


***************************************************************************
>>> updating every system boot
***************************************************************************

To update your microcode and free the internal buffer on every system boot
you'll need to add a line like the following to /etc/rc.d/rc.local

/usr/local/bin/microcode_ctl -iu

or to specify another microcode file 

/usr/local/bin/microcode_ctl -if /etc/microcode.dat


Simple as that. Problems? Contact either myself at simon@veritas.com or
Tigran at tigran@veritas.com


***************************************************************************
>>> Special thanks
***************************************************************************

o Intel Corporation, for supplying microcode update data and publishing
  the specifications that enabled us to write microcode driver for Linux.

  
- Simon Trimmer <simon@veritas.com> http://www.urbanmyth.org