
	System Diagnostics Command - sysdiag
	====================================


Version: 0.1.0 *DRAFT*
May 14, 2003

Contents
--------

1. Introduction
2. Requirements
3. Definitions
4. Overview
5. Architecture
   5.1 Libsysfs
   5.2 Event Logging and Syslog
   5.3 Existing Diagnostics
   5.4 sysdiag Command
6. Usage
   6.1 Listing Devices
   6.2 Listing Device Logs
   6.3 Listing Device VPD Information
   6.4 Running Device Diagnostics
7. Conclusion


1. Introduction
---------------

The system diagnostics command's purpose is to diagnose a normal running
Linux system. Administrators, service engineers, and normal users can use
it to list the devices on the system, the logs  for the devices, and 
the Vital Product Data for the devices. They can also use the command 
to run diagnostics on the listed devices. The command is meant to be 
flexible, allowing use of existing diagnostics. The goal is to provide 
one command to run diagnostics on a system.


2. Requirements
---------------

The system diagnostic command must satisfy the following requirements:

- It must be able to list all devices on the system.

- It must be able to list all Vital Product Data (VPD) for every device
  on the system. 

- It must list logs for each device on the system.

- It must work with Enterprise Event Logging.

- It must use sysfs as a system's device tree.

- It must be ableto run diagnostics on all devices on the system.

- It must be make use of existing diagnostics, such as Ethtool and
  the SCSI Generic Utilities.

- It must be lightweight as possible available at early boot.

- It must be able to be used in scripting.

- It must work with the Error Logging Analysis piece being worked on by
  LTC RAS. ELA will call sysdiag in error situations to check out 
  devices.


3. Definitions
--------------

- sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that
  presents a hierarchical representation of all system physical and
  virtual devices. It presents system devices by bus, by class, and
  by topology. Callbacks to device drivers are exposed as files in
  device directories. Sysfs, for all purposes, is our tree of system
  devices. For more information, please see:

	http://www.kernel.org/pub/linux/kernel/people/mochel/doc/

- Vital Product Data (VPD): All the necessary information to uniquely
  identify a device. Includes the following information and more: vendor, 
  serial number, revision level, driver name, and driver version. 

- Ethtool: Configuration and diagnostic tool for ethernet devices. For
  more information, please see:

	http://www.gnu.org/directory/sysadmin/monitor/ethtool.html

- SCSI Generic Utilities (sgutils): The SCSI generic driver (sg) is a
  pass through upper level driver for Linux SCSI devices. There are a
  number of utilties for configuring and diagnosing SCSI devices that
  use the generic driver. For more information, please see:

	http://www.torque.net/sg/

- libsysfs: Application Programming Interface to system devices exported
  through sysfs.

- System Utilities Package (sysutils): A package that will include a 
  number of utilities for managing and diagnosing a Linux system.


4. Overview
-----------

Through the system diagnostics command, or sysdiag, administrators,
service engineers, and normal people will be able to view and diagnose
all devices on the system. The command will perform the following
functions:

    a. List all devices on the system
    b. List logs for all devices on the system
    c. List VPD information for all devices on the system
    d. Run diagnostics on one or all devices on the system

The command will provide a shell-like environment that will be
easy to navigate and easy to script. The sysdiag command will make use
of our sysfs library for querying system device information and will
be included in our System Utilities, or sysutils, package. It will also
be configurable, allowing people to designate what existing diagnostics
the tool will use.


5. Architecture
---------------

The sysdiag command will be a command-line interface to start, making use
of existing work for querying system devices and running device diagnostics.


5.1 Libsysfs
------------

The system diagnostics command will access our libsysfs API for querying
the devices on the system and those devices' VPD information. Libsysfs 
will provide routines to query devices by bus, class, and topology. 


5.2 Event Logging and Syslog
----------------------------

The command will make use of Event Logging when installed and Syslog to 
query log information for specific devices. If Event Logging is installed,
sysdiag will be able to use evlview to query Event Log records for 
specific information by device, facility, severity, etc. Should Event Logging
not be installed, sysdiag will default to parsing /var/log/messages. 

The LTC RAS' printk macro project will assist sysdiag to retrieve
messages in Syslog. The macros supply a standard prefix identifying
devices for every message. The command can parse messages based on that 
format.


5.3 Existing Diagnostics
------------------------

The system diagnostics command will function much like a wrapper around
existing diagnostics. There are various existing diagnositc tools in 
Linux today for specific types of devices. Instead of writing diagnostics
from scratch, we propose using what's already used and accepted. The
command, in the beginning, will simply launch the diagnostic application.
In the future we may decide to use the existing diagnostic's defined
ioctls instead of exec'ing the command directly. The two most used
diagnostic tools are Ethtool for ethernet devices and sgutils for 
SCSI devices.

The sysdiag command will include a configuration file that people will 
edit to define what diagnostics are available for specific device 
classes. For instance, users may wish to use Ethtool to diagnose all
network class devices on the system. They'd need to edit the configuration
file and add a reference defining net class device diagnostics will be
handled by Ethtool. 

The format of the configuration file will be decided upon later.


5.4 sysdiag Command
-------------------

The sysdiag comand will act like a shell for ease of use and for easy
scripting. It can be run interactively or as a single command. Eventually,
we will add a menu mode.

To start, the command can be invoked from the command line in a call,
such as:

	$ sysdiag show bus pci devices

Or, it can be used interactively:

	$ sysdiag
	[sysdiag]> show
		root
		|-- devices
		|-- bus
		`-- class

	[sysdiag]> cd bus
	[sysdiag]> show
		bus
		|-- pci
		|-- scsi
		`-- usb

	[sysdiag]> cd pci
	[sysdiag]> show devices


The sysdiag command will model its use on how sysfs exposes devices to
User Space. Devices will be show by bus, by class, and by where they 
are in relation to root. Internally, it has yet to be decided if we'll
use the filesystem directly or use our own internal data structures.
			
Sysdiag will be enabled in this way to speed up how someone access it 
and to allow easy scripting. The navigation and commands will mirror
shell-like commands like "ls" and "cd" for navigating a filesystem. 

The command will be written in C. While Perl was considered, we believe
implementing in C will lend it to being available in early boot when
/usr and the perl binary aren't yet mounted and available.


6. Usage
--------

Needs to be defined.


6.1 Listing Devices
-------------------

Needs to be defined.


6.2 Listing Device Logs
-----------------------

Needs to be defined.


6.3 Listing Device VPD Information
----------------------------------

Needs to be defined.


6.4 Running Device Diagnostics
------------------------------

Needs to be defined.


7. Conclusion
-------------

The system diagnostics command is a tool to help people diagnose Linux
systems. They can use the tool to list devices on the system, device
logs, and device VPD information. More importantly, sysdiag is a single
command to run diagnostics on system devices, rather than having to
rely on numerous commands for specific devices. Sysdiag is configurable
to take advantage of the existing diagnostics. It is also easy to use
and to script, being developed in command and interactive modes. 
