.\"
.\" Copyright (C) 2002 - 2013 International Business Machines
.\" Todd Inglett <tinglett@vnet.ibm.com>
.\" Michael Strosaker <strosake@us.ibm.com>
.\" Vasant Hegde <hegdevasant@linux.vnet.ibm.com>
.\"
.TH UPDATE_FLASH 8 "8 May 2013" Linux "PowerLinux Service Tools"
.SH NAME
update_flash \- manage system and service processor firmware
.SH SYNOPSIS
.nf
\fB/usr/sbin/update_flash \fR[\fB-v|-n\fR] \fB-f \fIfirmware.img
.B /usr/sbin/update_flash -h
.B /usr/sbin/update_flash -c
.B /usr/sbin/update_flash -r
.B /usr/sbin/update_flash -s
.fi
.SH DESCRIPTION
.P
The
.I update_flash
script is used to validate, update and manage firmware on an IBM Power
Systems servers.
.TP
.nf
.B VALIDATION
.fi
When used with the
.B -v
option, the script will ONLY perform validation of the image file. Regardless
of the outcome of the validation, no actual flash will occur. This option is
only useful on machines that support validation of firmware images.
.TP
.nf
.B UPDATE
.fi
When used with only the
.B -f
option and an image file name, the script will attempt to update the system
firmware with the given image. If the machine has the ability to pre-validate
the image, this will be done automatically before the flash. If the machine
is not capable of pre-validation, or if validation passes, this script will
upload the firmware image into the kernel and will perform a
.B shutdown -r now
which will reboot the system.  The flash will occur at the end of the reboot
process.

.B WARNING:
The system WILL be rebooted!  Wait until the flash process has completed. This
can be anywhere from 2 minutes to 20 minutes (or more) depending on the system.
The control panel display will show that the system is flashing.  Failure to
wait may render a system inoperable.

.B NOTE:
If machine supports two firmware image areas, update is always applied to the
temporary image area. The
.B -c
option is the normal means by which a temporary image is committed to the
permanent side (see MANAGEMENT). However, if a platform is running from a
temporary image when an update is to be applied, then the platform may
automatically commit the current temporary image to the permanent side to
allow the new image to be updated to the temporary image area. The
.B -v
option can be used to determine what would result from an attempt to update
a flash image.

The
.B -n
option will prevent the automatic overwrite of the permanent image area
and abandon the update entirely.

To apply an update to the temporary image area without overwriting the
permanent image area, the system must first be running with the permanent
image. The temporary image can then be rejected (see MANAGEMENT).
Subsequently, the update can be applied.
.TP
.nf
.B MANAGEMENT
.fi
When used with the
.B -c
option, the script will commit the temporary image to the permanent side.
In order to use this, the machine must be running on the temporary image.
This option is only useful on machines supporting two firmware image areas.

When used with the
.B -r
option, the script will reject the temporary image. In order to use this,
the machine must be running on the permanent image. To switch from the
temporary image to the permanent image, you must reboot from the permanent
image -- for example, using the ASMI or HMC. This option is only useful on
machines supporting two firmware image areas.

.SH OPTIONS
.TP
.B \-h
Print the usage message and exit.
.TP
\fB\-f \fIfilename
Supply the filename to flash (required).
.TP
.B \-v
Validate ONLY with specified image file.
.TP
.B \-n
Do not overwrite permanent side image automatically.
.TP
.B \-c
Commit temporary image to permanent side.
.TP
.B \-r
Reject temporary image.
.TP
.B \-s
Determine if partition has access to perform flash image management.

.SH EXAMPLES
.P
To determine if partition has authority to flash image:

# update_flash -s

.P
For a typical firmware update (this may commit temporary to permanent):

# update_flash -f 01AL740_100_042.img

.P
To update only if permanent side will not be overwritten:

# update_flash -n -f 01AL740_100_042.img

.P
To validate an image:

# update_flash -v -f 01AL740_100_042.img

.P
To commit temporary image to permanent (note that the system
must be running on temporary image):

# update_flash -c

.P
To reject temporary image, and copy to permanent to temporary
(note that the system must be running on permanent image):

# update_flash -r

.SH EXIT STATUS
.TP
.nf
All cases:
 3 - Usage error
 4 - Permission error
 6 - Unexpected problem with /proc filesystem access
 7 - Error loading module
 8 - RTAS(pSeries)/OPAL(PowerNV) call failed
 9 - User aborted operation
.fi
.TP
.nf
Determine if partition has authority to manage image (-s):
 0 - Flash image management is supported
 1 - Flash image management is not supported on this system
.fi
.TP
.nf
Validation (-v):
 0 - Validation successful
.fi
.TP
.nf
Update ([-n] -f):
 5 - Image file error
10 - Auto overwrite permanent side image
15 - Update Access Key Expired
.fi
.TP
.nf
Manage (-c|-r):
 0 - Temporary image commit/reject successful
.fi

.SH FILES
.TP
.nf
pSeries
  rtas_flash kernel module
  /proc/ppc64/rtas/firmware_flash (provided by kernel module)
.fi
.TP
.nf
PowerNV
  /sys/firmware/opal/image
  /sys/firmware/opal/{validate/manage/update}_flash
.fi
.SH NOTES
.B Download firmware
.fi
Firmware may be downloaded from the IBM website. Instructions for
downloading and installing the firmware image are also there, and
information there will be more up-to-date than this page.

.P
.B Firmware update failure
.fi
Various conditions can lead to a firmware update failure. If you
receive an authentication-related error, such as:
.P
.nf
update_flash: RTAS: validate() Partition does not have authority
-or-
update_flash: System does not have authority to perform firmware update.
.fi
.P
This can reflect either 1) That the permission is not set (correctable
through the ASM interface, System -> Firmware Update Policy, or through an
HMC if attached.
.P
-or-
.P
2) Firmware still believes an HMC is attached.  This can be corrected by
following the steps outlined here:
.P
http://publib.boulder.ibm.com/infocenter/powersys/v3r1m5/index.jsp?topic=/p7hatl/iphblresetserverp6.htm

.P
.B RPM format image
.fi
For "rpm format" images, the file will have a .rpm extension. It can be extracted
using below command:

       rpm2cpio <rpm filename> | cpio -idmv
.fi
.P
This will extract files under current directory. Pass <image>.img file to this script.

.P
.B AIX format image
.fi
For older "AIX format" images, the file will have a .BIN extension. This
zip file happens to be an AIX binary, but it can be extracted with the
unzip command (with password from the web page):

       unzip 70286C4F.BIN

This should produce a file with a .img extension. This image file is what
should be flashed.