AIX Version 7.1 Understanding the Diagnostic Subsystem for AIX IBM Note Before using this information and the product it supports, read the information in “Notices” on page 247 . This edition applies to AIX Version 7.1 and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 2010, 2014. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents About this document..............................................................................................v Highlighting...................................................................................................................................................v Case sensitivity in AIX.................................................................................................................................. v ISO 9000.......................................................................................................................................................v Understanding the Diagnostic Subsystem for AIX................................................... 1 Diagnostic subsystem for AIX concepts......................................................................................................1 Structure of diagnostics......................................................................................................................... 1 Strategy for diagnostics..........................................................................................................................3 Diagnostic commands............................................................................................................................ 5 Operating Environments.............................................................................................................................. 6 Online Diagnostics..................................................................................................................................6 Standalone diagnostics (POWER® processor-based systems only)......................................................7 NIM Diagnostics......................................................................................................................................8 Diagnostic components............................................................................................................................... 9 Diagnostic controller.............................................................................................................................. 9 Diagnostic applications........................................................................................................................ 12 Tasks and service aids..........................................................................................................................20 Application test units........................................................................................................................... 45 Test unit 64-bit porting guideline........................................................................................................ 60 Diagnostic kernel extension.................................................................................................................63 Diagnostic library............................................................................................................................... 100 Diagnostic object classes...................................................................................................................170 Diagnostic header files.......................................................................................................................190 Diagnostic user interface................................................................................................................... 190 Examples: Diagnostic menus.............................................................................................................198 Diagnostic features..................................................................................................................................205 Missing Options Resolution................................................................................................................205 Error log analysis................................................................................................................................208 Periodic diagnostics........................................................................................................................... 209 Automatic error log analysis (DIAGELA)............................................................................................210 Loop testing........................................................................................................................................211 Diagnostic Packaging...............................................................................................................................212 Hardfile packaging............................................................................................................................. 212 CDROM packaging (POWER® processor-based only)........................................................................ 213 Diagnostic supplemental media........................................................................................................ 213 Diagnostic debugging hints..................................................................................................................... 217 Debugging hints for diagnostic applications..................................................................................... 217 Debugging hints for diagnostic kernel extension.............................................................................. 218 Diagnostic patch diskette procedure.................................................................................................221 Code examples........................................................................................................................................ 222 Example {DEVICE}_ERR_DETAIL.H: TU specific outputs................................................................. 222 Example {DEVICE}_INPUT_PARAMS.H: TU specific inputs..............................................................223 Example TU local leader file.............................................................................................................. 223 Example TU exectu function..............................................................................................................224 Example TU open/close device interface.......................................................................................... 226 Example TU makefiles....................................................................................................................... 230 Example C source file for TU interrupt handler.................................................................................231 Example TU interrupt handler makefile............................................................................................ 232 Example diagnostic application.........................................................................................................233 iii Example diagnostic application message file................................................................................... 241 Diagnostic task matrix............................................................................................................................. 243 Notices..............................................................................................................247 Privacy policy considerations..................................................................................................................248 Trademarks.............................................................................................................................................. 249 Index................................................................................................................ 251 iv About this document This document provides application developers with complete information about writing their own diagnostic applications or service aids for the AIX® operating system. Programmers can use this topic collection to gain knowledge of the hardware diagnostic subsystem and the databases used to perform hardware diagnostics. Topics include operating environments, diagnostic components, features and packaging, debugging hints, and code examples. Highlighting The following highlighting conventions are used in this document: Bold Identifies commands, subroutines, keywords, files, structures, directories, and other items whose names are predefined by the system. Bold highlighting also identifies graphical objects, such as buttons, labels, and icons that the you select. Italics Identifies parameters for actual names or values that you supply. Identifies examples of specific data values, examples of text similar to what you Monospace might see displayed, examples of portions of program code similar to what you might write as a programmer, messages from the system, or text that you must type. Case sensitivity in AIX Everything in the AIX® operating system is case sensitive, which means that it distinguishes between uppercase and lowercase letters. For example, you can use the ls command