POWER Reference Codes

One nice advantage provided by POWER systems is the availability of structured and well-defined reference codes. Besides indicating errors or conditions that otherwise require attention, these codes are also used to indicate the progress of boots or dumps. If your system failed to boot for some reason, the last reference code on the operator’s panel (op panel) would provide a good clue as to what the system was doing just before the failure.

On Linux, besides appearing on the op panel, these reference codes are also found in events that are surfaced in servicelog. While servicelog contains a lot of details that are useful for servicing errors, more information can always be obtained by looking up the reference code.

There are a few kinds of reference codes; the key for decoding these refcodes is the IBM Hardware InfoCenter. I’ll briefly explain the three different types of reference codes (SRCs, SRNs, and menugoals) before showing how they are displayed in servicelog.

System Reference Codes

SRCs are sequences of alphanumeric characters (usually 8 — just enough to fit snugly on the display of the operator’s panel — but sometimes 6). They were first introduced on POWER5 systems, and exist on both System p and System i (formerly pSeries and iSeries). SRCs are documented in InfoCenter: “Service provider information”/”Reference codes”/”Using system reference codes”.

An example of an SRC used as a progress code is C7004091; that refcode indicates that the partition is in a standby state, and is waiting to be manually activated. If the partition is set to be activated automatically, the partition will not stop at this SRC, but will continue to the Open Firmware boot phase.

Linux does not generate SRCs as progress codes, but will generate some as error codes. Additionally, if you have a POWER5 or POWER6 system, events with SRCs may be written to servicelog to indicate platform-level errors.

Service Request Numbers

SRNs are an older formatting method for progress or error codes. They are generated by diagnostics in AIX, and by the firmware on POWER4 (and earlier) systems. If the progress/error code has 5 digits, or has a ‘-‘ character somewhere in it, it is an SRN. These are documented in InfoCenter: “Service provider information”/”Reference codes”/”Using service request numbers”.

As an example, the SRN 747-223 indicates that there was a “miscompare during the write/read of the memory I/O register.” Many SRNs point to a repair procedure called a MAP; in this case, the SRN points to MAP 0050, “SCSI bus problems”, which provides procedures for analyzing and repairing the problem.

Linux does not generate SRNs, but you may still see SRNs generated by older POWER platforms. They may also be generated if you boot the eServer Standalone Diagnostics CD to run device diagnostics.


Menugoals are reference codes that begin with a ‘#’ character. They are generated by diagnostics, and indicate procedures that can be performed by a system admin rather than by a trained service representative. Menugoals don’t typically indicate errors, but instead convey additional information about the state of the device being diagnosed. As an example, a menugoal might indicate that a tape drive requires cleaning.

Reference Codes in servicelog

Each event in servicelog has a refcode field, which will always contain a reference code (either an SRC, an SRN, or a menugoal). Here is a sample event from servicelog indicating a platform error reported by a POWER system:

PPC64 Platform Event:
Servicelog ID:      64
Event Timestamp:    Fri Dec 10 21:37:05 2004
Log Timestamp:      Wed Apr 18 00:19:12 2007
Severity:           4 (WARNING)
Version:            2
Serviceable Event:  Yes
Event Repaired:     No
Reference Code:     B125E500
Action Flags:       a800
Event Type:         224 - Platform Event
Kernel ID:          1000
Platform ID:        50929493
Creator ID:         E - Service Processor
Subsystem ID:       25 - Memory subsystem including external cache
RTAS Severity:      41 - Unrecoverable Error, bypassed with degraded performance
Event Subtype:      00 - Not applicable
Machine Type/Model: 9118-575
Machine Serial:     0SQIH47

Extended Reference Codes:
2: 030000f0  3: 28f00110  4: c13920ff  5: c1000000
6: 00811630  7: 00000001  8: 00d6000d  9: 00000000

Memory subsystem including external cache Informational (non-error) Event.
Refer to the system service documentation for more information.

<< Callout 1 >>
Priority            M
Type                16
Repair Event Key:   0
Procedure Id:       n/a
Location:           U787D.001.0481682-P2
FRU:                80P4180
Serial:             YH3016129997
CCIN:               260D

The error description provides some details concerning the failure, and the FRU callout indicates which part to repair in order to fix the problem. The refcode field contains an SRC, B125E500; looking that SRC up in InfoCenter shows the following details:

  • B1 indicates it was reported by the service processor
  • 25 indicates that it is an “external cache event or error reported by the service processor”
  • E500 indicates that it is a result of processor runtime diagnostics (PRD)

In addition to that, the InfoCenter entry for B125E500 indicates that this event is the result of a hardware failure. The FRU callout indicates which piece of hardware should be replaced to resolve the error.


Kernel Markers Wiki

I wrote a little bit about kernel markers before, but I’ve since found a wiki with some more information: http://sourceware.org/systemtap/wiki/UsingMarkers. Besides information on adding new markers to the kernel source and building kernels that include marker support, it also has information on using markers in SystemTap.

It certainly does seem to make SystemTap scripts easier to write:

probe kernel.mark("some_marker") { printf("some_marker hit: %p, %d\n",                                                                                                             
                                                 $arg1, $arg2) }

The obvious first question from someone sitting down to write a SystemTap script that uses markers: where are the markers, what are their labels, and what are the arguments you can access using them? Perhaps the marker developers could write a tool that parses the kernel source and spits out a document that provides the names and locations of the available markers, along with the arguments that they expose.

The wiki page notes another failing with the current implementation: if a marker is a structure pointer, the struct type can’t be obtained from a SystemTap script. Consequently, the members of the struct are not easily accessible. Perhaps the documentation that results from post-processing the source could also be used to provide the type of each of the arguments. Just a suggestion.

POWER, Linux, and IBM Software Demonstrations

DEMOcentralI’ve spent a little time recently looking through IBM’s DEMOcentral, a repository that collects and displays demonstrations of both software and hardware products, and found several of interest. These pre-recorded and sometimes interactive demos play in a browser window, are available in several languages, and range from high-level overviews to tutorials covering installation or specific features; if you’re interested in IBM systems, WebSphere, Tivoli, or any other IBM software technologies, it’s well worth your time to browse through the collection. Here’s a quick tour of what I found to be interesting.

Hardware Flyovers

Hardware “flyovers” are interactive demos that show IBM systems, inside and out, with annotations that pop up when you mouse over the various components. For example:

  • The JS21 flyover shows the blade from the front and back, as well as inside the cover.
  • The System p 570 flyover shows the system from the front (with or without the cover) and the back, and allows you to zoom i to view the detail of the processor books (other flyovers allow that as well, like the p5 550Q flyover). It also shows how to interconnect multiple systems to make an 8-, 12-, or 16-core system (select the “upgrade” graphic to see the interconnections).
  • For the big iron junkies, there are even System p5 590/595 and System z9 flyovers.

Unfortunately, I haven’t found any flyovers of POWER6 systems yet; I assume it’s just a matter of time.

Recorded Software Demos

There are a number of recorded demos that are of interest to users of IBM systems, describing things like the BladeCenter Management Module, IBM Director, PowerExecutive, and IBM Virtualization Manager. There are many more; look at the complete list of systems demos to see if any others interest you.

Besides the systems demos, there are also demos of many IBM software products. For example, here is a demo detailing how to install DB2 Express on Linux. In addition to DB2/Information Management, there’s a several demo collections that cover topics like Workplace, SOA, WebSphere Portal, Rational and other software development tools, the OmniFind Yahoo! Edition, even Lotus Notes and Sametime.

DLPAR Tools Open Sourced

The latest version of the powerpc-utils and powerpc-utils-papr packages have been released; source tarballs are available at http://powerpc-utils.ozlabs.org.

In addition to a few minor bug fixes there is a significant addition to the powerpc-utils-papr package: the newly open sourced DLPAR (Dynamic Logical PARtitioning) tools. These new tools are the drmgr and lsslot commands. Both of these commands were previously shipped from the IBM website in the (proprietary) rpa-dlpar and rpa-pci-hotplug packages. The inclusion of these tools in the powerpc-utils-papr package will now mean that DLPAR capabilities will be present at system install instead of having to download and install additional packages to enable this on System p.

So, what do these fancy new tools do? Good question. The drmgr command enables users to dynamically (at runtime) add and remove I/O, processors and memory. (Yes, memory remove is not currently supported on Linux for System p but that will be changing soon.) The drmgr command is meant to be driven from the HMC/IVM, not the command line, although it can be. This explains its slightly cryptic usage and limitations when used directly.

The lsslot is a command line tool that lists all DLPAR or hotplug capable I/O, PHBs (PCI Host Bridges), processors and memory slots on the system. Although its (unfortunate) naming implies that it will list all slots on the system, it does not.

Hopefully the powerpc-utils and powerpc-utils-papr packages are familiar to you. If not you may recognize the names they appear as in the various distros such as ppc64-utils on RHEL or just powerpc-utils on SuSE. Both of these distros combine the packages into one, whereas Gentoo ships them separately. Merging the packages is most likely a hold-over from when the they were the combined ppc64-utils package. Community requests asked to split the previous ppc64-utils package into a set of tools generic to the POWER platform (powerpc-utils) and those specific to PAPR based POWER platforms (powerpc-utils-papr).

Predictive Self Healing on Linux on POWER

Sun frequently touts their “predictive self-healing” implementation in Solaris 10. I wonder if that bullet point would be further down the list if they were familiar with the error detection, prediction, and correction capabilities of Linux on POWER platforms. In fact, the Linux on POWER implementation precedes the Solaris 10 implementation by at least a year (Solaris 10 was released in January 2005; SLES 8 had this solution for POWER in 2003, and RHEL 3 had it in 2004 at the latest).

I’ll take a moment to explain the superior aspects of the Linux on POWER implementation. The Solaris implementation consists of a number of diagnostics in the operating system that poll hardware devices for errors, and then perform notifications and/or recovery actions if a problem is detected. On POWER, hardware problem detection is largely done by the hypervisor and low-level firmware. That’s where it should be done; it means that the OS doesn’t even need to be booted for detection to occur, and doesn’t need to waste cycles polling. A huge number of devices are monitored this way: memory, CPUs, caches, fans, power supplies, VPD cards, voltage regulator modules, I/O subsystems, service processors, risers, even I/O drawers (and the fans, power supplies, etc. that those drawers may contain). PCI devices are also monitored; more details on that later.

If a failure (or impending failure) is detected, the hypervisor provides a report to every affected operating system installed on the system and to Hardware Management Consoles, if any are attached. On Linux partitions, the data is logged to the syslog and servicelog, and a number of actions may occur. Predictive CPU failures will cause the affected CPUs to be automatically removed via hotplug, so that the operating system may continue to run even after a catastrophic CPU or cache failure occurs. Severe thermal or voltage issues, and fan or power supply failures when redundant units aren’t available, will result in a shutdown to prevent hardware damage. In many cases, failures are automatically recovered by the hardware or firmware (for example, single- and double-bit memory errors are corrected via ECC, memory scrubbing, redundant bit-steering, and Chipkill), and the message to the OS is simply an FYI, or possibly an indication that the degraded device should be serviced at the administrator’s convenience. When a repair action is needed (device replacement, microcode updates, etc.), administrators are notified of the location code of the FRU and an indication of which repair procedure to follow (as documented in InfoCenter).

On a side note, the fact that this monitoring is done at such a low level means that self-healing on POWER platforms is completely OS agnostic; the reports are provided to Linux, AIX, and i5/OS partitions. The OS just has to know how to get out of the way. For that matter, there doesn’t even need to be an OS installed: the platform error log is viewable using the service processor, which is also capable of driving repair procedures. Conversely, if you are running something besides Solaris on Sun hardware, or if the error occurs during boot time, Sun’s “self-healing” feature is useless.

An OpenSolaris presentation that I found indicates that their Fault Management includes “improved resilience for all PCI I/O failures,” but is vague on details. I’d like to compare it to PCI Error Recovery/EEH on Linux on POWER, but it is difficult to do so without more information. It seems to be (again) an OS-only implementation, which almost certainly wouldn’t be able to match the functionality provided by POWER platforms. On POWER, the hardware and hypervisor again provide assistance by fencing off adapters the instant a problem is detected (to avoid the possibility of data corruption) and then notifying the operating system, which then directs the appropriate device drivers to restart the failed adapter.

Predictive Self-Healing always tops the list of Solaris 10 features (along with ZFS, Containers, and DTrace, which are reserved for other posts and/or other bloggers to discuss). Hopefully I’ve shown why it shouldn’t.

The Problems with EDAC

I’ve been looking into EDAC (Error Detection and Correction) a bit recently, to see how it compares with the error detection that is native to IBM’s POWER machines (and to see if there are any features we can better exploit on POWER). If you aren’t familiar with EDAC, it’s a collection of modules for querying the internal registers on some devices (most notably memory modules and PCI devices) to gather failure statistics. To some extent, EDAC is also moving to take action based on those statistics.

Here is the first and most difficult problem: How do you know what number of errors is acceptable before a device should be replaced? It’s entirely acceptable for a device to experience an occasional, sporadic failure; they are typically recovered by the hardware itself (parity or ECC within a memory module, for example), with only a minute effect on performance (if any). A repair action should only be taken when these problems become more common. A good metric in this case would be the number of errors within the past hour; if the error count exceeds a threshold, then the device should be replaced. That threshold is the nut of the problem, as it can vary wildly depending on the device.

On POWER machines, the firmware takes care of thresholding these errors, and sends an event to the OS (including Linux) when the threshold is exceeded. The users don’t need to know how many errors have occurred; all they need to know is that the device at a specific location code is failing, and should be repaired.

Here’s another issue: EDAC polls, say once per second, and reads status registers on certain devices. It then clears the contents of those registers so that only new errors will be registered on the next poll. On many enterprise systems appropriately equipped, the service processor will also poll those same registers to perform predictive failure analysis (PFA). Unfortunately if EDAC is running on the system and clearing the registers, the service processor will be unable to obtain an accurate count of errors for thresholding.

When it comes to PCI errors, POWER includes EEH support for both detection and seamless recovery. EEH seems to be vastly superior in this regard, as the system firmware will cause the bus to be immediately frozen (to ensure that erroneous data is not written or read), and the Linux kernel/driver will reset the device and bring it back online, frequently within the space of a second. I’m not sure how well EDAC plays with AER (Advanced Error Reporting, for PCI-Express systems); I’ll probably write about that when I learn more.

EDAC in its current form seems to be only useful for home users, who are using systems that are not equipped with service processors and who are wondering why their system is suddenly misbehaving. I think it has promise for the enterprise space, but step one is to have it not stomp on any data gathering done by service processors, and step two is to provide information on when the error statistics become meaningful (thresholds).

Sample Real-World Use of SystemTap

SystemTap has been sometimes plagued with “solution in search of a problem” complaints. It was interesting to run across an example of SystemTap being used to solve a real-world problem. A developer discovered an OOM (Out Of Memory) condition in the upstream kernel. In the quest to obtain additional information regarding the issue, the kernel refused to boot with additional debug printk()’s added to quicklist.c. The developer, being familiar with SystemTap, used the following script:

probe kernel.statement("quicklist_trim@mm/quicklist.c:56")
        printf(" q->nr_pages is %d, min_pages is %d ----> %s\n",
               $q->nr_pages, $min_pages, execname());

The SystemTap scripting language takes a little getting used to, but the intent here is clear: each time quicklist_trim() is run in quicklist.c, a message should be printed that displays some kernel data.

This sort of usage is interesting for two reasons:

  1. Kernel developers understand that there are places in the kernel that cannot be debugged by the printk() method; kprobes (simplified via SystemTap) provide a method to extract debug data from many of those locations, and this is an example of that in action.
  2. When using SystemTap to gather debug data, the system doesn’t need to be rebooted with a new kernel. In this particular scenario, that didn’t matter so much, as the problem was discovered by a developer who could modify his own kernel and reboot the system as needed. However, if an issue is discovered on a production system, this allows for root cause analysis to proceed without the need to take the system out of production.

Servicelog Source Available

Source code for the servicelog library and utilities is now available from the linux-diag project on SourceForge: http://linux-diag.sourceforge.net/servicelog.html. There is user-level documentation (PDF) for servicelog available on SourceForge as well.

Why is servicelog different than other logging mechanisms, such as syslog? It’s intended to store entries that are only relevant to system service. The concept of a serviceable event is introduced, which is a single servicelog entry that contains enough information to identify a failure and to indicate how to repair it. This information will typically include:

  • a short description of the failure, including a reference code
  • identification of the physical location of a failing component (via location code, for example)
  • indication of severity of the failure and/or priority of the repair
  • pointers to documented procedures for repairing the failure (for example, PCI hotplug instructions for replacing a failing PCI adapter)

System management tools can register to be notified when new serviceable events are created (the Service Focal Point on the Hardware Management Console will be updated when a serviceable event is logged on a Linux partition on System p). When a failure is fixed (for example, a failed PCI adapter is replaced via a hotplug action), a repair action should be logged to servicelog, which will cause all of the relevant open serviceable events to be marked as “closed” (i.e., fixed). This will provide a complete history of all of the failures that have occurred on a system, as well as all of the repair actions that have taken place.

Servicelog is particularly useful with Linux on System p right now. The superior First Failure Data Capture (FFDC) facilities provided by System p will result in very informative servicelog entries to indicate a wide range of possible platform failures, and each reference code and repair procedure is documented in IBM’s eServer hardware InfoCenter.

Hardware Inventory with lsvpd

VPD, Vital Product Data, is information associated with system hardware that is useful for easing system configuration and service. The lsvpd package for Linux provides commands that can be used to retrieve an inventory of system hardware, along with the VPD associated with each device. The lsvpd package will install three commands: lsvpd (“list VPD”), lscfg (“list configuration”), and lsmcode (“list microcode”). The lscfg command is the human-readable command of the three; lsvpd and lsmcode provide output that is more easily read by scripts/applications.

The lsvpd package requires the libvpd library. The libvpd library can also be used to retrieve inventory data from within an application; in fact, that’s how lsvpd, lscfg, and lsmcode work.

Types of Vital Product Data

Running lscfg by itself will list each device, along with its location code. More detailed VPD for each device on that list can be obtained by running “lscfg -vl <device>“. The following examples illustrate the type of data that can be retrieved from the lsvpd package:

# lscfg -vl eth0
  eth0             U787A.001.DNZ00Z5-P1-T5
                                         Port 1 - IBM 2 PORT 10/100/1000
                                         Base-TX PCI-X Adapter (14108902)

        Manufacturer................Intel Corporation
        Machine Type and Model......82546EB Gigabit Ethernet Controller
        Network Address.............00096b6b0591
        Device Specific.(YL)........U787A.001.DNZ00Z5-P1-T5

The description, manufacturer, model number, MAC address, and location code of the eth0 device are all noted in the output. Here is another example, for a hard drive:

# lscfg -vl sda
  sda              U787A.001.DNZ00Z5-P1-T10-L8-L0
                                         16 Bit LVD SCSI Disk Drive (73400 MB)

        Machine Type and Model......ST373453LC
        FRU Number..................00P2685
        ROS Level and ID............43353141
        Serial Number...............0007EA3B
        EC Level....................H12094
        Part Number.................00P2684
        Device Specific.(Z0)........000003129F00013E
        Device Specific.(Z1)........0626C51A
        Device Specific.(Z2)........0002
        Device Specific.(Z3)........04112
        Device Specific.(Z4)........0001
        Device Specific.(Z5)........22
        Device Specific.(Z6)........H12094
        Device Specific.(YL)........U787A.001.DNZ00Z5-P1-T10-L8-L0

The location code, description, model, and manufacturer are all there, along with the FRU and part numbers (for ordering new parts), the serial number of the device, and its current microcode level (“ROS Level and ID”).

The -A flag to lsmcode will list all the microcode levels on the system, including the system firmware level:

# lsmcode -A
sys0!system:SF240_320 (t) SF220_051 (p) SF240_320 (t)|service:
sg6 1:255:255:255 !570B001.0FC93FFC0FC93FFC
sg5 1:0:4:0 sdd !HUS103036FL3800.0FC94004100698C86F7374
sg4 1:0:3:0 sdc !HUS103036FL3800.0FC942E40FC942E40620
sg3 0:255:255:255 !570B001.0FC940040FC940040FC93FF410193860
sg2 0:0:15:0 !VSBPD3E   U4SCSI.0FC9420C0FC9420C0620
sg1 0:0:5:0 sdb !ST336607LC.0FC9420C0FC9420C0620
sg0 0:0:3:0 sda !ST373453LC.0FC942040FC942040620

See my previous article on pSeries and System p firmware for a description of the dual firmware banks, and information on updating your system firmware level. Currently, device microcode must be updated using a microcode update utility specific to the device in question (iprutils for the onboard RAID SCSI HBAs on POWER5, for example).

Refreshing the VPD Database

Unfortunately, the data in the lsvpd database can become stale as devices are added or changed (via hotplug or DLPAR, for example). Running /usr/sbin/vpdupdate will cause the data to be refreshed. The developers of lsvpd are currently working on having vpdudpate run automatically in response to hotplug events.

Other Tools for Hardware Inventory

Besides lsvpd, there are several other Linux tools that can assist with hardware inventory for system configuration or service:

  • HAL (Hardware Abstraction Layer): run hal-device for a list of devices
  • Open Firmware device tree (on Power): stored in /proc/device-tree
  • The sysfs filesystem (usually mounted on /sys)

Location Codes on POWER

Hardware location codes provide a method for mapping connectors or logical functions to their physical locations in the system’s enclosure. For example, it allows you to easily identify the physical port on the system that corresponds with eth0, or to identify which of the fans on the system is failing. Besides hardware inventory and diagnostics, location codes are also used on HMCs (hardware management consoles) and IVMs (integrated virtualization managers) to identify the devices to be assigned to (or moved between) logical partitions.

Starting with POWER5, both System p and System i started using the same format for location codes. The POWER4 (and POWER3 and JS20) location codes are much shorter (and differ between pSeries and iSeries), but you’ll be able to deal with them once you get the hang of POWER5 (and later) location codes.

In case it matters, location codes are limited to 80 characters in length (to fit on the display on the operator’s panel on the front of the system). They are composed only of uppercase characters, digits, periods, and dashes. They consist of labels separated by dashes. This is an example of a location code representing a PCI slot:


The initial U indicates that the label represents a “unit” (like a CEC, central electronics complex, or an I/O drawer). The DNZ00Z5 at the end of the label is the serial number of the unit. The “P1” indicates the first planar on the system (i.e. the motherboard). The “C3” indicates the third PCI slot on that planar. Looking for labels on the system chassis will help you find the C3 slot, or the slot might also include an LED that can be turned on to identify the slot (with the usysident command, to be detailed in a near-future article).

Some of the other labels you may run into with location codes:

  • An: the nth air handler (fan, blower, etc.)
  • En: the nth electrical unit (power supply)
  • Dn: the nth device (hard drive, SES device, etc.)
  • Ln: the nth logical path (IDE address, SCSI target, fibre channel LUN, etc.)
  • Tn: the nth port (on a multi-port ethernet adapter, for example)

In other articles on this site, I explain how you can obtain and use location codes using hardware inventory and diagnostic tools. Quick preview: you can use the lscfg command to view a list of devices with their location codes, and several diagnostic tools will provide the location codes of failing components.

[Edit 2007-10-13:  Updated with pointer to article about lsvpd for hardware inventory.]