Understanding the Diagnostic Subsystem for AIX

Diagnostic Object Classes

The Diagnostic Package contains ODM object classes that are used extensively by the Diagnostic components. Some object classes store 'predefined' diagnostic information about the system and resources. Other object classes store 'customized' information that is built and used during runtime operation of diagnostics.

The following is a list of the Diagnostic ODM object classes:

• PDiagRes - Predefined Diagnostic Resource Object Class
• PDiagAtt - Predefined Diagnostic Attribute Device Object Class
• PDiagTask - Predefined Diagnostic Task Object Class
• CDiagAtt - Customized Diagnostic Attribute Object Class
• TMInput - Test Mode Input Object Class
• MenuGoal - Menu Goal Object Class
• FRUB - Fru Bucket Object Class
• FRUs - Fru Reporting Object Class
• DAVars - Diagnostic Application Variables Object Class
• PDiagDev - Predefined Diagnostic Devices Object Class
• DSMOptions - Diagnostic Supervisor Menu Options Object Class

Predefined Diagnostic Resource Object Class

The Predefined Diagnostic Resource object class (PDiagRes) identifies the resources supported by diagnostics and provides additional information needed to test the resource.

The PDiagRes object class structure is defined as:

class PDiagRes {
                    char Uniquetype[48];
                    short Ports;
                    short PSet;
                    short PreTest;
                    char AttUniquetype[48];
                    short SupTests;
                    short Menu;
                    short DNext;
                    vchar DaName[255];
                    char PkgBlock[5];
                    vchar EnclDaName[255];
                    vchar SysxApp[255];
                    vchar SupTasks[255];
                    long FFC;
                    short Fru;
                    long TestSuiteId;
                    long DiagEnvironment;
                    vchar KernExt[255];
                    char Version[5];
                    };

Predefined Diagnostic Attribute Device Object Class

The Predefined Diagnostic Attribute Device object class (PDiagAtt) contains device- specific attributes for the DAs, diagnostic controller, and service aids to use.

The PDiagAtt object class structure is defined as:

class PDiagAtt {
                     char DClass[16];
                     char DSClass[16];
                     char DType[16];
                     char attribute[16];
                     vchar value[255];
                     char rep[8];
                     vchar DApp[255];
                     };

Each field has specific meaning to each application that utilizes the Predefined Diagnostic Attribute Device object class (PDiagAtt).

EXAMPLES:

• To specify the tasks that are supported by a resource, create a PDiagAtt stanza for the resource, indicating the supported tasks in the value field.

  PDiagAtt:
          DClass = "disk"
          DSClass = "scsi"
          DType = ""
          attribute = "SupTasks"
          value = "1,2,7,8,9,10,13,14,16,31,33"
          rep = "s"
  
  PDiagAtt:
          DClass = "disk"
          DSClass = "scsi"
          DType = "355mb"
          attribute = "SupTasks"
          value = "1,2,7,8,9,10,13,14,31,33"
          rep = "s"

  The search order performed by the Controller when determining the tasks a resource supports is as follows:

  DClass, DSClass, DType 
  DClass, DSClass 
  DClass

  In the above example, if the disk type is 355mb, a match on the first call to search ODM is made; if not, a match will be made on the second call.

  Note
  The 355mb does not have task id 16, which is microcode download.

• To specify the application for the Diagnostic Controller to execute for a specific resource that supports a task, then a stanza similar to the following is needed. This example tells the Controller to invoke ufd to start a format task on the selected resource that matches the diskette/siofd/fd criteria.

  PDiagAtt:
          DClass = "diskette"
          DSClass = "siofd"
          DType = "fd"
          attribute = "format"
          value = ""
          rep = "s"
          DApp = "ufd"

• The following stanza indicates the current release level of the Diagnostic Controller:

  PDiagAtt:
          DType = "Dctrl"
          attribute = "version"
          value = "4.3.4"            #This is the diagnostic
                                   #version level seen on
                                   #the Operating
                                   #Instructions Menu.
          rep = "s"

• The NoScreen attribute is used by Display Test Pattern Service Aid to determine when a graphics adapter specific application should be used to display the screens for the service aid.

  PDiagAtt:
          DType = "2b101a05"
          DSClass = "pci"
          attribute = "NoScreen"
          value = "/usr/lpp/diagnostics/da/dsage -P"
          rep = "NotOpen"
          DClass = "adapter"
          DApp = "u5081"

  The service aid that uses this stanza is /usr/lpp/diagnostics/bin/u5081. The command that is built and executed is:

   /usr/lpp/diagnostics/da/dsage <device name> -P 

• The platform_task+ attribute allows third parties to add tasks to the Task List based on the hardware platform. The DApp field specifies the platform for the tasks in the Task List. The value field of the stanza contains a comma delimited list of the task IDs to be added.

  PDiagAtt:
          DType = ""
          DSClass = ""
          attribute = "platform_task+"
          value = "101,102,110"
          rep = ""
          DClass = ""
          DApp = "rspc"

  In the example above, the tasks whose IDs are 101, 102 and 110 will be included in the task list on an ISA-bus based platform. Multiple PDiagAtt stanzas with the platform_task+ attribute are allowed.

  Note
  The platform value for the DApp field is the string obtained by using the bootinfo -p command.

Predefined Diagnostic Task Object Class

The Predefined Diagnostic Task object class (PDiagTask) identifies the tasks supported by diagnostics and provides additional information needed to execute the task.

The PDiagTask object class structure is:

class PDiagTask {
                     long TaskId;
                     long SetId;
                     long MsgId;
                     long Multisession;
                     short Order;
                     long ResourceFlag;
                     long DiagEnvironment;
                     short Builtin;
                     vchar Action[255];
                     vchar Catalog[255];
                     vchar KernExt[255];
                     short DescriptionSetId;
                     short DescriptionMsgId;
                     char PkgBlock[5];
                     };

Customized Diagnostic Attribute Object Class

The Customized Diagnostic Attribute object class (CDiagAtt) contains customized entries for selected devices found in the current configuration, which is supported by diagnostics. The CDiagAtt object class indicates specialized diagnostic attribute status of the device. It is used to maintain diagnostic information about devices found in the current configuration across sessions.

The CDiagAtt object class structure is defined as:

class CDiagAtt {
                     char name[16];
                     char attribute[16];
                     vchar value[255];
                     char type[8];
                     char rep[8];
                     };

Examples:

• The Diagnostic Controller creates a CDiagAtt entry for each device that is tested periodically by the Diagnostic daemon. The format of the stanza looks like:

  CDiagAtt:
      name = "hdisk0"                 Resource to test
      attribute = "p_test_time"     Attribute: periodic-test-time
      value = "0300"                Test time ( 3AM )
      type = "T"                    Data type of 'text'
      rep = "s"                     'String' representation
  
  CDiagAtt:
      name = "ent0"                              Resource name
      attribute = "p_test_time"
      value = "9999"                             Not tested
   indication
          type = "T"
          rep = "s"

• The Diagnostic Controller creates a CDiagAtt entry for each device that has been deleted from the resource list. The format of the stanza looks like:

  CDiagAtt:
      name = "mem0"                           Resource name
      attribute = "not_in_tst_list"    Device has been deleted from
      value = "1"                           the Resource List
      type = "T"
      rep = "n"

Test Mode Input Object Class

The input parameters to the Diagnostic Application are stored in the TMInput object class. The subroutine getdainput should be used to retrieve the test mode input data values from this object class.

The TMInput object class structure is defined as:

class TMInput {
                     short exenv;
                     short advanced;
                     short system;
                     short dmode;
                     char date[80];
                     short loopmode;
                     short lcount;
                     short lerrors;
                     short console;
                     char parent[16];
                     char parentloc[16];
                     char dname[16];
                     char dnameloc[16];
                     char child1[16];
                     short state1;
                     char childloc1[16];
                     char child2[16];
                     short state2;
                     char childloc2[16];
                     long pid;
                     short cpuid;
                     };

All values can be found in /usr/include/diag/tmdefs.h.

Menu Goal Object Class

The Menu Goal object class (MenuGoal) is used to store additional text information that the Diagnostic Application wants to pass back to the Diagnostic Controller. This text information is displayed to the user. This information is usually additional information that would be useful to the user concerning the state of the resource. One example would be that the Tape Drive requires cleaning.

All applications using the MenuGoal capability must use the menugoal diagnostic library subroutine.

The MenuGoal object class structure is defined as:

class MenuGoal {
 		    char dname[16];
                    longchar tbuffer1[1000];
                    longchar tbuffer2[1000];
                    };

FRU Bucket Object Class

The Fru Bucket Object Class (FRUB) is used to store failing replaceable unit information. This information is specified by the Diagnostic Application and passed back to the Diagnostic Controller after an error has been detected.

All applications using the FRU capability must use the addfrub diagnostic library subroutine.

The FRUB object class structure is defined as:

class FRUB {
                    char dname[16];
                    short ftype;
                    short sn;
                    short rcode;
                    short rmsg;
                    char timestamp[80];
                    };

SSS - RRR

dname: <device name under test>
vname: Error_code           "Error_code is an ascii string"
vtype: DIAG_STRING          "Literal value"
val: <8 digit hex character string>

FRU Reporting Object Class

The Fru Reporting Object Class (FRUs) is used to store failing replaceable unit information. This information is specified by the Diagnostic Application and passed back to the Diagnostic Controller after an error has been detected.

All applications using the FRU capability must use the addfrub diagnostic library subroutine.

The FRUs object class structure is defined as:

class FRUs {
                    char dname[16];
                    char fname[16];
                    char floc[16];
                    short ftype;
                    short fmsg;
                    short conf;
                    };

Diagnostic Application Variables Object Class

The Diagnostic Application Variables Object Class (DAVars) is used to store run time information needed by the Diagnostic Application. This object class is used to store state variables to support Loop Testing.

All applications using the DAVars capability must use the getdavar/putdavar diagnostic library subroutine.

The DAVars object class structure is defined as:

class DAVars {
                    char dname[16];
                    char vname[30];
                    short vtype;
                    char vvalue[30];
                    long ivalue;
                    };

Predefined Diagnostic Devices Object Class

The Predefined Diagnostic Devices object class (PDiagDev) identifies the resources supported by AIX 4.1 diagnostics and provides additional information needed to test the resource. This object class is recognized by the operating system for backlevel compatibility purposes. For development purposes, use PDiagRes instead.

The PDiagDev object class structure is defined as:

class PDiagDev {
                    char DType[16];
                    char DSClass[16];
                    short Ports;
                    short PSet;
                    short PreTest;
                    char AttDType[16];
                    char AttSClass[16];
                    short Conc;
                    short SupTests;
                    short Menu;
                    short DNext;
                    vchar DaName[255];
                    char  Diskette[5];
                    vchar EnclDaName[255];
                    short Sysxflg;
                    char DClass[16];
                    };

Diagnostic Supervisor Menu Options Object Class

The Diagnostic Supervisor Menu Options object class (DSMOptions) contains stanzas describing AIX 4.1 Diagnostic Service Aids. This object class is recognized by the operating system for backlevel compatibility purposes. For development purposes, use PDiagRes instead.

The DSMOptions object class structure is defined as:

class DSMOptions {
                    char msgkey[4];
                    vchar catalogue[255];
                    short order;
                    short setid;
                    short msgid;
                    vchar action[255];
                    char  Diskette[5];
                    };