move edac.txt two levels up
authorAdrian Bunk <bunk@kernel.org>
Thu, 7 Feb 2008 08:13:33 +0000 (00:13 -0800)
committerLinus Torvalds <torvalds@woody.linux-foundation.org>
Thu, 7 Feb 2008 16:42:17 +0000 (08:42 -0800)
There's no reason for edac.txt for being at this unusual place.

Signed-off-by: Adrian Bunk <bunk@kernel.org>
Acked-by: Alan Cox <alan@redhat.com>
Cc: Doug Thompson <norsk5@yahoo.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Documentation/00-INDEX
Documentation/drivers/edac/edac.txt [deleted file]
Documentation/edac.txt [new file with mode: 0644]

index 40ac7759c3bb5342edf9168153edbf1f1ff05e79..c1067e48b529aac5305f80ef91fdb5d0a3d0763d 100644 (file)
@@ -132,12 +132,12 @@ dontdiff
        - file containing a list of files that should never be diff'ed.
 driver-model/
        - directory with info about Linux driver model.
-drivers/
-       - directory with driver documentation (currently only EDAC).
 dvb/
        - info on Linux Digital Video Broadcast (DVB) subsystem.
 early-userspace/
        - info about initramfs, klibc, and userspace early during boot.
+edac.txt
+       - information on EDAC - Error Detection And Correction
 eisa.txt
        - info on EISA bus support.
 exception.txt
diff --git a/Documentation/drivers/edac/edac.txt b/Documentation/drivers/edac/edac.txt
deleted file mode 100644 (file)
index a5c3684..0000000
+++ /dev/null
@@ -1,727 +0,0 @@
-
-
-EDAC - Error Detection And Correction
-
-Written by Doug Thompson <dougthompson@xmission.com>
-7 Dec 2005
-17 Jul 2007    Updated
-
-
-EDAC is maintained and written by:
-
-       Doug Thompson, Dave Jiang, Dave Peterson et al,
-       original author: Thayne Harbaugh,
-
-Contact:
-       website:        bluesmoke.sourceforge.net
-       mailing list:   bluesmoke-devel@lists.sourceforge.net
-
-"bluesmoke" was the name for this device driver when it was "out-of-tree"
-and maintained at sourceforge.net.  When it was pushed into 2.6.16 for the
-first time, it was renamed to 'EDAC'.
-
-The bluesmoke project at sourceforge.net is now utilized as a 'staging area'
-for EDAC development, before it is sent upstream to kernel.org
-
-At the bluesmoke/EDAC project site, is a series of quilt patches against
-recent kernels, stored in a SVN respository. For easier downloading, there
-is also a tarball snapshot available.
-
-============================================================================
-EDAC PURPOSE
-
-The 'edac' kernel module goal is to detect and report errors that occur
-within the computer system running under linux.
-
-MEMORY
-
-In the initial release, memory Correctable Errors (CE) and Uncorrectable
-Errors (UE) are the primary errors being harvested. These types of errors
-are harvested by the 'edac_mc' class of device.
-
-Detecting CE events, then harvesting those events and reporting them,
-CAN be a predictor of future UE events.  With CE events, the system can
-continue to operate, but with less safety. Preventive maintenance and
-proactive part replacement of memory DIMMs exhibiting CEs can reduce
-the likelihood of the dreaded UE events and system 'panics'.
-
-NON-MEMORY
-
-A new feature for EDAC, the edac_device class of device, was added in
-the 2.6.23 version of the kernel.
-
-This new device type allows for non-memory type of ECC hardware detectors
-to have their states harvested and presented to userspace via the sysfs
-interface.
-
-Some architectures have ECC detectors for L1, L2 and L3 caches, along with DMA
-engines, fabric switches, main data path switches, interconnections,
-and various other hardware data paths. If the hardware reports it, then
-a edac_device device probably can be constructed to harvest and present
-that to userspace.
-
-
-PCI BUS SCANNING
-
-In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices
-in order to determine if errors are occurring on data transfers.
-
-The presence of PCI Parity errors must be examined with a grain of salt.
-There are several add-in adapters that do NOT follow the PCI specification
-with regards to Parity generation and reporting. The specification says
-the vendor should tie the parity status bits to 0 if they do not intend
-to generate parity.  Some vendors do not do this, and thus the parity bit
-can "float" giving false positives.
-
-In the kernel there is a pci device attribute located in sysfs that is
-checked by the EDAC PCI scanning code. If that attribute is set,
-PCI parity/error scannining is skipped for that device. The attribute
-is:
-
-       broken_parity_status
-
-as is located in /sys/devices/pci<XXX>/0000:XX:YY.Z directorys for
-PCI devices.
-
-FUTURE HARDWARE SCANNING
-
-EDAC will have future error detectors that will be integrated with
-EDAC or added to it, in the following list:
-
-       MCE     Machine Check Exception
-       MCA     Machine Check Architecture
-       NMI     NMI notification of ECC errors
-       MSRs    Machine Specific Register error cases
-       and other mechanisms.
-
-These errors are usually bus errors, ECC errors, thermal throttling
-and the like.
-
-
-============================================================================
-EDAC VERSIONING
-
-EDAC is composed of a "core" module (edac_core.ko) and several Memory
-Controller (MC) driver modules. On a given system, the CORE
-is loaded and one MC driver will be loaded. Both the CORE and
-the MC driver (or edac_device driver) have individual versions that reflect
-current release level of their respective modules.
-
-Thus, to "report" on what version a system is running, one must report both
-the CORE's and the MC driver's versions.
-
-
-LOADING
-
-If 'edac' was statically linked with the kernel then no loading is
-necessary.  If 'edac' was built as modules then simply modprobe the
-'edac' pieces that you need.  You should be able to modprobe
-hardware-specific modules and have the dependencies load the necessary core
-modules.
-
-Example:
-
-$> modprobe amd76x_edac
-
-loads both the amd76x_edac.ko memory controller module and the edac_mc.ko
-core module.
-
-
-============================================================================
-EDAC sysfs INTERFACE
-
-EDAC presents a 'sysfs' interface for control, reporting and attribute
-reporting purposes.
-
-EDAC lives in the /sys/devices/system/edac directory.
-
-Within this directory there currently reside 2 'edac' components:
-
-       mc      memory controller(s) system
-       pci     PCI control and status system
-
-
-============================================================================
-Memory Controller (mc) Model
-
-First a background on the memory controller's model abstracted in EDAC.
-Each 'mc' device controls a set of DIMM memory modules. These modules are
-laid out in a Chip-Select Row (csrowX) and Channel table (chX). There can
-be multiple csrows and multiple channels.
-
-Memory controllers allow for several csrows, with 8 csrows being a typical value.
-Yet, the actual number of csrows depends on the electrical "loading"
-of a given motherboard, memory controller and DIMM characteristics.
-
-Dual channels allows for 128 bit data transfers to the CPU from memory.
-Some newer chipsets allow for more than 2 channels, like Fully Buffered DIMMs
-(FB-DIMMs). The following example will assume 2 channels:
-
-
-               Channel 0       Channel 1
-       ===================================
-       csrow0  | DIMM_A0       | DIMM_B0 |
-       csrow1  | DIMM_A0       | DIMM_B0 |
-       ===================================
-
-       ===================================
-       csrow2  | DIMM_A1       | DIMM_B1 |
-       csrow3  | DIMM_A1       | DIMM_B1 |
-       ===================================
-
-In the above example table there are 4 physical slots on the motherboard
-for memory DIMMs:
-
-       DIMM_A0
-       DIMM_B0
-       DIMM_A1
-       DIMM_B1
-
-Labels for these slots are usually silk screened on the motherboard. Slots
-labeled 'A' are channel 0 in this example. Slots labeled 'B'
-are channel 1. Notice that there are two csrows possible on a
-physical DIMM. These csrows are allocated their csrow assignment
-based on the slot into which the memory DIMM is placed. Thus, when 1 DIMM
-is placed in each Channel, the csrows cross both DIMMs.
-
-Memory DIMMs come single or dual "ranked". A rank is a populated csrow.
-Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above
-will have 1 csrow, csrow0. csrow1 will be empty. On the other hand,
-when 2 dual ranked DIMMs are similarly placed, then both csrow0 and
-csrow1 will be populated. The pattern repeats itself for csrow2 and
-csrow3.
-
-The representation of the above is reflected in the directory tree
-in EDAC's sysfs interface. Starting in directory
-/sys/devices/system/edac/mc each memory controller will be represented
-by its own 'mcX' directory, where 'X" is the index of the MC.
-
-
-       ..../edac/mc/
-                  |
-                  |->mc0
-                  |->mc1
-                  |->mc2
-                  ....
-
-Under each 'mcX' directory each 'csrowX' is again represented by a
-'csrowX', where 'X" is the csrow index:
-
-
-       .../mc/mc0/
-               |
-               |->csrow0
-               |->csrow2
-               |->csrow3
-               ....
-
-Notice that there is no csrow1, which indicates that csrow0 is
-composed of a single ranked DIMMs. This should also apply in both
-Channels, in order to have dual-channel mode be operational. Since
-both csrow2 and csrow3 are populated, this indicates a dual ranked
-set of DIMMs for channels 0 and 1.
-
-
-Within each of the 'mc','mcX' and 'csrowX' directories are several
-EDAC control and attribute files.
-
-
-============================================================================
-DIRECTORY 'mc'
-
-In directory 'mc' are EDAC system overall control and attribute files:
-
-
-Panic on UE control file:
-
-       'edac_mc_panic_on_ue'
-
-       An uncorrectable error will cause a machine panic.  This is usually
-       desirable.  It is a bad idea to continue when an uncorrectable error
-       occurs - it is indeterminate what was uncorrected and the operating
-       system context might be so mangled that continuing will lead to further
-       corruption. If the kernel has MCE configured, then EDAC will never
-       notice the UE.
-
-       LOAD TIME: module/kernel parameter: panic_on_ue=[0|1]
-
-       RUN TIME:  echo "1" >/sys/devices/system/edac/mc/edac_mc_panic_on_ue
-
-
-Log UE control file:
-
-       'edac_mc_log_ue'
-
-       Generate kernel messages describing uncorrectable errors.  These errors
-       are reported through the system message log system.  UE statistics
-       will be accumulated even when UE logging is disabled.
-
-       LOAD TIME: module/kernel parameter: log_ue=[0|1]
-
-       RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ue
-
-
-Log CE control file:
-
-       'edac_mc_log_ce'
-
-       Generate kernel messages describing correctable errors.  These
-       errors are reported through the system message log system.
-       CE statistics will be accumulated even when CE logging is disabled.
-
-       LOAD TIME: module/kernel parameter: log_ce=[0|1]
-
-       RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ce
-
-
-Polling period control file:
-
-       'edac_mc_poll_msec'
-
-       The time period, in milliseconds, for polling for error information.
-       Too small a value wastes resources.  Too large a value might delay
-       necessary handling of errors and might loose valuable information for
-       locating the error.  1000 milliseconds (once each second) is the current
-       default. Systems which require all the bandwidth they can get, may
-       increase this.
-
-       LOAD TIME: module/kernel parameter: poll_msec=[0|1]
-
-       RUN TIME: echo "1000" >/sys/devices/system/edac/mc/edac_mc_poll_msec
-
-
-============================================================================
-'mcX' DIRECTORIES
-
-
-In 'mcX' directories are EDAC control and attribute files for
-this 'X" instance of the memory controllers:
-
-
-Counter reset control file:
-
-       'reset_counters'
-
-       This write-only control file will zero all the statistical counters
-       for UE and CE errors.  Zeroing the counters will also reset the timer
-       indicating how long since the last counter zero.  This is useful
-       for computing errors/time.  Since the counters are always reset at
-       driver initialization time, no module/kernel parameter is available.
-
-       RUN TIME: echo "anything" >/sys/devices/system/edac/mc/mc0/counter_reset
-
-               This resets the counters on memory controller 0
-
-
-Seconds since last counter reset control file:
-
-       'seconds_since_reset'
-
-       This attribute file displays how many seconds have elapsed since the
-       last counter reset. This can be used with the error counters to
-       measure error rates.
-
-
-
-Memory Controller name attribute file:
-
-       'mc_name'
-
-       This attribute file displays the type of memory controller
-       that is being utilized.
-
-
-Total memory managed by this memory controller attribute file:
-
-       'size_mb'
-
-       This attribute file displays, in count of megabytes, of memory
-       that this instance of memory controller manages.
-
-
-Total Uncorrectable Errors count attribute file:
-
-       'ue_count'
-
-       This attribute file displays the total count of uncorrectable
-       errors that have occurred on this memory controller. If panic_on_ue
-       is set this counter will not have a chance to increment,
-       since EDAC will panic the system.
-
-
-Total UE count that had no information attribute fileY:
-
-       'ue_noinfo_count'
-
-       This attribute file displays the number of UEs that
-       have occurred have occurred with  no informations as to which DIMM
-       slot is having errors.
-
-
-Total Correctable Errors count attribute file:
-
-       'ce_count'
-
-       This attribute file displays the total count of correctable
-       errors that have occurred on this memory controller. This
-       count is very important to examine. CEs provide early
-       indications that a DIMM is beginning to fail. This count
-       field should be monitored for non-zero values and report
-       such information to the system administrator.
-
-
-Total Correctable Errors count attribute file:
-
-       'ce_noinfo_count'
-
-       This attribute file displays the number of CEs that
-       have occurred wherewith no informations as to which DIMM slot
-       is having errors. Memory is handicapped, but operational,
-       yet no information is available to indicate which slot
-       the failing memory is in. This count field should be also
-       be monitored for non-zero values.
-
-Device Symlink:
-
-       'device'
-
-       Symlink to the memory controller device.
-
-Sdram memory scrubbing rate:
-
-       'sdram_scrub_rate'
-
-       Read/Write attribute file that controls memory scrubbing. The scrubbing
-       rate is set by writing a minimum bandwith in bytes/sec to the attribute
-       file. The rate will be translated to an internal value that gives at
-       least the specified rate.
-
-       Reading the file will return the actual scrubbing rate employed.
-
-       If configuration fails or memory scrubbing is not implemented, the value
-       of the attribute file will be -1.
-
-
-
-============================================================================
-'csrowX' DIRECTORIES
-
-In the 'csrowX' directories are EDAC control and attribute files for
-this 'X" instance of csrow:
-
-
-Total Uncorrectable Errors count attribute file:
-
-       'ue_count'
-
-       This attribute file displays the total count of uncorrectable
-       errors that have occurred on this csrow. If panic_on_ue is set
-       this counter will not have a chance to increment, since EDAC
-       will panic the system.
-
-
-Total Correctable Errors count attribute file:
-
-       'ce_count'
-
-       This attribute file displays the total count of correctable
-       errors that have occurred on this csrow. This
-       count is very important to examine. CEs provide early
-       indications that a DIMM is beginning to fail. This count
-       field should be monitored for non-zero values and report
-       such information to the system administrator.
-
-
-Total memory managed by this csrow attribute file:
-
-       'size_mb'
-
-       This attribute file displays, in count of megabytes, of memory
-       that this csrow contains.
-
-
-Memory Type attribute file:
-
-       'mem_type'
-
-       This attribute file will display what type of memory is currently
-       on this csrow. Normally, either buffered or unbuffered memory.
-       Examples:
-               Registered-DDR
-               Unbuffered-DDR
-
-
-EDAC Mode of operation attribute file:
-
-       'edac_mode'
-
-       This attribute file will display what type of Error detection
-       and correction is being utilized.
-
-
-Device type attribute file:
-
-       'dev_type'
-
-       This attribute file will display what type of DRAM device is
-       being utilized on this DIMM.
-       Examples:
-               x1
-               x2
-               x4
-               x8
-
-
-Channel 0 CE Count attribute file:
-
-       'ch0_ce_count'
-
-       This attribute file will display the count of CEs on this
-       DIMM located in channel 0.
-
-
-Channel 0 UE Count attribute file:
-
-       'ch0_ue_count'
-
-       This attribute file will display the count of UEs on this
-       DIMM located in channel 0.
-
-
-Channel 0 DIMM Label control file:
-
-       'ch0_dimm_label'
-
-       This control file allows this DIMM to have a label assigned
-       to it. With this label in the module, when errors occur
-       the output can provide the DIMM label in the system log.
-       This becomes vital for panic events to isolate the
-       cause of the UE event.
-
-       DIMM Labels must be assigned after booting, with information
-       that correctly identifies the physical slot with its
-       silk screen label. This information is currently very
-       motherboard specific and determination of this information
-       must occur in userland at this time.
-
-
-Channel 1 CE Count attribute file:
-
-       'ch1_ce_count'
-
-       This attribute file will display the count of CEs on this
-       DIMM located in channel 1.
-
-
-Channel 1 UE Count attribute file:
-
-       'ch1_ue_count'
-
-       This attribute file will display the count of UEs on this
-       DIMM located in channel 0.
-
-
-Channel 1 DIMM Label control file:
-
-       'ch1_dimm_label'
-
-       This control file allows this DIMM to have a label assigned
-       to it. With this label in the module, when errors occur
-       the output can provide the DIMM label in the system log.
-       This becomes vital for panic events to isolate the
-       cause of the UE event.
-
-       DIMM Labels must be assigned after booting, with information
-       that correctly identifies the physical slot with its
-       silk screen label. This information is currently very
-       motherboard specific and determination of this information
-       must occur in userland at this time.
-
-
-============================================================================
-SYSTEM LOGGING
-
-If logging for UEs and CEs are enabled then system logs will have
-error notices indicating errors that have been detected:
-
-EDAC MC0: CE page 0x283, offset 0xce0, grain 8, syndrome 0x6ec3, row 0,
-channel 1 "DIMM_B1": amd76x_edac
-
-EDAC MC0: CE page 0x1e5, offset 0xfb0, grain 8, syndrome 0xb741, row 0,
-channel 1 "DIMM_B1": amd76x_edac
-
-
-The structure of the message is:
-       the memory controller                   (MC0)
-       Error type                              (CE)
-       memory page                             (0x283)
-       offset in the page                      (0xce0)
-       the byte granularity                    (grain 8)
-               or resolution of the error
-       the error syndrome                      (0xb741)
-       memory row                              (row 0)
-       memory channel                          (channel 1)
-       DIMM label, if set prior                (DIMM B1
-       and then an optional, driver-specific message that may
-               have additional information.
-
-Both UEs and CEs with no info will lack all but memory controller,
-error type, a notice of "no info" and then an optional,
-driver-specific error message.
-
-
-
-============================================================================
-PCI Bus Parity Detection
-
-
-On Header Type 00 devices the primary status is looked at
-for any parity error regardless of whether Parity is enabled on the
-device.  (The spec indicates parity is generated in some cases).
-On Header Type 01 bridges, the secondary status register is also
-looked at to see if parity occurred on the bus on the other side of
-the bridge.
-
-
-SYSFS CONFIGURATION
-
-Under /sys/devices/system/edac/pci are control and attribute files as follows:
-
-
-Enable/Disable PCI Parity checking control file:
-
-       'check_pci_parity'
-
-
-       This control file enables or disables the PCI Bus Parity scanning
-       operation. Writing a 1 to this file enables the scanning. Writing
-       a 0 to this file disables the scanning.
-
-       Enable:
-       echo "1" >/sys/devices/system/edac/pci/check_pci_parity
-
-       Disable:
-       echo "0" >/sys/devices/system/edac/pci/check_pci_parity
-
-
-
-Panic on PCI PARITY Error:
-
-       'panic_on_pci_parity'
-
-
-       This control files enables or disables panicking when a parity
-       error has been detected.
-
-
-       module/kernel parameter: panic_on_pci_parity=[0|1]
-
-       Enable:
-       echo "1" >/sys/devices/system/edac/pci/panic_on_pci_parity
-
-       Disable:
-       echo "0" >/sys/devices/system/edac/pci/panic_on_pci_parity
-
-
-Parity Count:
-
-       'pci_parity_count'
-
-       This attribute file will display the number of parity errors that
-       have been detected.
-
-
-
-=======================================================================
-
-
-EDAC_DEVICE type of device
-
-In the header file, edac_core.h, there is a series of edac_device structures
-and APIs for the EDAC_DEVICE.
-
-User space access to an edac_device is through the sysfs interface.
-
-At the location /sys/devices/system/edac (sysfs) new edac_device devices will
-appear.
-
-There is a three level tree beneath the above 'edac' directory. For example,
-the 'test_device_edac' device (found at the bluesmoke.sourceforget.net website)
-installs itself as:
-
-       /sys/devices/systm/edac/test-instance
-
-in this directory are various controls, a symlink and one or more 'instance'
-directorys.
-
-The standard default controls are:
-
-       log_ce          boolean to log CE events
-       log_ue          boolean to log UE events
-       panic_on_ue     boolean to 'panic' the system if an UE is encountered
-                       (default off, can be set true via startup script)
-       poll_msec       time period between POLL cycles for events
-
-The test_device_edac device adds at least one of its own custom control:
-
-       test_bits       which in the current test driver does nothing but
-                       show how it is installed. A ported driver can
-                       add one or more such controls and/or attributes
-                       for specific uses.
-                       One out-of-tree driver uses controls here to allow
-                       for ERROR INJECTION operations to hardware
-                       injection registers
-
-The symlink points to the 'struct dev' that is registered for this edac_device.
-
-INSTANCES
-
-One or more instance directories are present. For the 'test_device_edac' case:
-
-       test-instance0
-
-
-In this directory there are two default counter attributes, which are totals of
-counter in deeper subdirectories.
-
-       ce_count        total of CE events of subdirectories
-       ue_count        total of UE events of subdirectories
-
-BLOCKS
-
-At the lowest directory level is the 'block' directory. There can be 0, 1
-or more blocks specified in each instance.
-
-       test-block0
-
-
-In this directory the default attributes are:
-
-       ce_count        which is counter of CE events for this 'block'
-                       of hardware being monitored
-       ue_count        which is counter of UE events for this 'block'
-                       of hardware being monitored
-
-
-The 'test_device_edac' device adds 4 attributes and 1 control:
-
-       test-block-bits-0       for every POLL cycle this counter
-                               is incremented
-       test-block-bits-1       every 10 cycles, this counter is bumped once,
-                               and test-block-bits-0 is set to 0
-       test-block-bits-2       every 100 cycles, this counter is bumped once,
-                               and test-block-bits-1 is set to 0
-       test-block-bits-3       every 1000 cycles, this counter is bumped once,
-                               and test-block-bits-2 is set to 0
-
-
-       reset-counters          writing ANY thing to this control will
-                               reset all the above counters.
-
-
-Use of the 'test_device_edac' driver should any others to create their own
-unique drivers for their hardware systems.
-
-The 'test_device_edac' sample driver is located at the
-bluesmoke.sourceforge.net project site for EDAC.
-
diff --git a/Documentation/edac.txt b/Documentation/edac.txt
new file mode 100644 (file)
index 0000000..a5c3684
--- /dev/null
@@ -0,0 +1,727 @@
+
+
+EDAC - Error Detection And Correction
+
+Written by Doug Thompson <dougthompson@xmission.com>
+7 Dec 2005
+17 Jul 2007    Updated
+
+
+EDAC is maintained and written by:
+
+       Doug Thompson, Dave Jiang, Dave Peterson et al,
+       original author: Thayne Harbaugh,
+
+Contact:
+       website:        bluesmoke.sourceforge.net
+       mailing list:   bluesmoke-devel@lists.sourceforge.net
+
+"bluesmoke" was the name for this device driver when it was "out-of-tree"
+and maintained at sourceforge.net.  When it was pushed into 2.6.16 for the
+first time, it was renamed to 'EDAC'.
+
+The bluesmoke project at sourceforge.net is now utilized as a 'staging area'
+for EDAC development, before it is sent upstream to kernel.org
+
+At the bluesmoke/EDAC project site, is a series of quilt patches against
+recent kernels, stored in a SVN respository. For easier downloading, there
+is also a tarball snapshot available.
+
+============================================================================
+EDAC PURPOSE
+
+The 'edac' kernel module goal is to detect and report errors that occur
+within the computer system running under linux.
+
+MEMORY
+
+In the initial release, memory Correctable Errors (CE) and Uncorrectable
+Errors (UE) are the primary errors being harvested. These types of errors
+are harvested by the 'edac_mc' class of device.
+
+Detecting CE events, then harvesting those events and reporting them,
+CAN be a predictor of future UE events.  With CE events, the system can
+continue to operate, but with less safety. Preventive maintenance and
+proactive part replacement of memory DIMMs exhibiting CEs can reduce
+the likelihood of the dreaded UE events and system 'panics'.
+
+NON-MEMORY
+
+A new feature for EDAC, the edac_device class of device, was added in
+the 2.6.23 version of the kernel.
+
+This new device type allows for non-memory type of ECC hardware detectors
+to have their states harvested and presented to userspace via the sysfs
+interface.
+
+Some architectures have ECC detectors for L1, L2 and L3 caches, along with DMA
+engines, fabric switches, main data path switches, interconnections,
+and various other hardware data paths. If the hardware reports it, then
+a edac_device device probably can be constructed to harvest and present
+that to userspace.
+
+
+PCI BUS SCANNING
+
+In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices
+in order to determine if errors are occurring on data transfers.
+
+The presence of PCI Parity errors must be examined with a grain of salt.
+There are several add-in adapters that do NOT follow the PCI specification
+with regards to Parity generation and reporting. The specification says
+the vendor should tie the parity status bits to 0 if they do not intend
+to generate parity.  Some vendors do not do this, and thus the parity bit
+can "float" giving false positives.
+
+In the kernel there is a pci device attribute located in sysfs that is
+checked by the EDAC PCI scanning code. If that attribute is set,
+PCI parity/error scannining is skipped for that device. The attribute
+is:
+
+       broken_parity_status
+
+as is located in /sys/devices/pci<XXX>/0000:XX:YY.Z directorys for
+PCI devices.
+
+FUTURE HARDWARE SCANNING
+
+EDAC will have future error detectors that will be integrated with
+EDAC or added to it, in the following list:
+
+       MCE     Machine Check Exception
+       MCA     Machine Check Architecture
+       NMI     NMI notification of ECC errors
+       MSRs    Machine Specific Register error cases
+       and other mechanisms.
+
+These errors are usually bus errors, ECC errors, thermal throttling
+and the like.
+
+
+============================================================================
+EDAC VERSIONING
+
+EDAC is composed of a "core" module (edac_core.ko) and several Memory
+Controller (MC) driver modules. On a given system, the CORE
+is loaded and one MC driver will be loaded. Both the CORE and
+the MC driver (or edac_device driver) have individual versions that reflect
+current release level of their respective modules.
+
+Thus, to "report" on what version a system is running, one must report both
+the CORE's and the MC driver's versions.
+
+
+LOADING
+
+If 'edac' was statically linked with the kernel then no loading is
+necessary.  If 'edac' was built as modules then simply modprobe the
+'edac' pieces that you need.  You should be able to modprobe
+hardware-specific modules and have the dependencies load the necessary core
+modules.
+
+Example:
+
+$> modprobe amd76x_edac
+
+loads both the amd76x_edac.ko memory controller module and the edac_mc.ko
+core module.
+
+
+============================================================================
+EDAC sysfs INTERFACE
+
+EDAC presents a 'sysfs' interface for control, reporting and attribute
+reporting purposes.
+
+EDAC lives in the /sys/devices/system/edac directory.
+
+Within this directory there currently reside 2 'edac' components:
+
+       mc      memory controller(s) system
+       pci     PCI control and status system
+
+
+============================================================================
+Memory Controller (mc) Model
+
+First a background on the memory controller's model abstracted in EDAC.
+Each 'mc' device controls a set of DIMM memory modules. These modules are
+laid out in a Chip-Select Row (csrowX) and Channel table (chX). There can
+be multiple csrows and multiple channels.
+
+Memory controllers allow for several csrows, with 8 csrows being a typical value.
+Yet, the actual number of csrows depends on the electrical "loading"
+of a given motherboard, memory controller and DIMM characteristics.
+
+Dual channels allows for 128 bit data transfers to the CPU from memory.
+Some newer chipsets allow for more than 2 channels, like Fully Buffered DIMMs
+(FB-DIMMs). The following example will assume 2 channels:
+
+
+               Channel 0       Channel 1
+       ===================================
+       csrow0  | DIMM_A0       | DIMM_B0 |
+       csrow1  | DIMM_A0       | DIMM_B0 |
+       ===================================
+
+       ===================================
+       csrow2  | DIMM_A1       | DIMM_B1 |
+       csrow3  | DIMM_A1       | DIMM_B1 |
+       ===================================
+
+In the above example table there are 4 physical slots on the motherboard
+for memory DIMMs:
+
+       DIMM_A0
+       DIMM_B0
+       DIMM_A1
+       DIMM_B1
+
+Labels for these slots are usually silk screened on the motherboard. Slots
+labeled 'A' are channel 0 in this example. Slots labeled 'B'
+are channel 1. Notice that there are two csrows possible on a
+physical DIMM. These csrows are allocated their csrow assignment
+based on the slot into which the memory DIMM is placed. Thus, when 1 DIMM
+is placed in each Channel, the csrows cross both DIMMs.
+
+Memory DIMMs come single or dual "ranked". A rank is a populated csrow.
+Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above
+will have 1 csrow, csrow0. csrow1 will be empty. On the other hand,
+when 2 dual ranked DIMMs are similarly placed, then both csrow0 and
+csrow1 will be populated. The pattern repeats itself for csrow2 and
+csrow3.
+
+The representation of the above is reflected in the directory tree
+in EDAC's sysfs interface. Starting in directory
+/sys/devices/system/edac/mc each memory controller will be represented
+by its own 'mcX' directory, where 'X" is the index of the MC.
+
+
+       ..../edac/mc/
+                  |
+                  |->mc0
+                  |->mc1
+                  |->mc2
+                  ....
+
+Under each 'mcX' directory each 'csrowX' is again represented by a
+'csrowX', where 'X" is the csrow index:
+
+
+       .../mc/mc0/
+               |
+               |->csrow0
+               |->csrow2
+               |->csrow3
+               ....
+
+Notice that there is no csrow1, which indicates that csrow0 is
+composed of a single ranked DIMMs. This should also apply in both
+Channels, in order to have dual-channel mode be operational. Since
+both csrow2 and csrow3 are populated, this indicates a dual ranked
+set of DIMMs for channels 0 and 1.
+
+
+Within each of the 'mc','mcX' and 'csrowX' directories are several
+EDAC control and attribute files.
+
+
+============================================================================
+DIRECTORY 'mc'
+
+In directory 'mc' are EDAC system overall control and attribute files:
+
+
+Panic on UE control file:
+
+       'edac_mc_panic_on_ue'
+
+       An uncorrectable error will cause a machine panic.  This is usually
+       desirable.  It is a bad idea to continue when an uncorrectable error
+       occurs - it is indeterminate what was uncorrected and the operating
+       system context might be so mangled that continuing will lead to further
+       corruption. If the kernel has MCE configured, then EDAC will never
+       notice the UE.
+
+       LOAD TIME: module/kernel parameter: panic_on_ue=[0|1]
+
+       RUN TIME:  echo "1" >/sys/devices/system/edac/mc/edac_mc_panic_on_ue
+
+
+Log UE control file:
+
+       'edac_mc_log_ue'
+
+       Generate kernel messages describing uncorrectable errors.  These errors
+       are reported through the system message log system.  UE statistics
+       will be accumulated even when UE logging is disabled.
+
+       LOAD TIME: module/kernel parameter: log_ue=[0|1]
+
+       RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ue
+
+
+Log CE control file:
+
+       'edac_mc_log_ce'
+
+       Generate kernel messages describing correctable errors.  These
+       errors are reported through the system message log system.
+       CE statistics will be accumulated even when CE logging is disabled.
+
+       LOAD TIME: module/kernel parameter: log_ce=[0|1]
+
+       RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ce
+
+
+Polling period control file:
+
+       'edac_mc_poll_msec'
+
+       The time period, in milliseconds, for polling for error information.
+       Too small a value wastes resources.  Too large a value might delay
+       necessary handling of errors and might loose valuable information for
+       locating the error.  1000 milliseconds (once each second) is the current
+       default. Systems which require all the bandwidth they can get, may
+       increase this.
+
+       LOAD TIME: module/kernel parameter: poll_msec=[0|1]
+
+       RUN TIME: echo "1000" >/sys/devices/system/edac/mc/edac_mc_poll_msec
+
+
+============================================================================
+'mcX' DIRECTORIES
+
+
+In 'mcX' directories are EDAC control and attribute files for
+this 'X" instance of the memory controllers:
+
+
+Counter reset control file:
+
+       'reset_counters'
+
+       This write-only control file will zero all the statistical counters
+       for UE and CE errors.  Zeroing the counters will also reset the timer
+       indicating how long since the last counter zero.  This is useful
+       for computing errors/time.  Since the counters are always reset at
+       driver initialization time, no module/kernel parameter is available.
+
+       RUN TIME: echo "anything" >/sys/devices/system/edac/mc/mc0/counter_reset
+
+               This resets the counters on memory controller 0
+
+
+Seconds since last counter reset control file:
+
+       'seconds_since_reset'
+
+       This attribute file displays how many seconds have elapsed since the
+       last counter reset. This can be used with the error counters to
+       measure error rates.
+
+
+
+Memory Controller name attribute file:
+
+       'mc_name'
+
+       This attribute file displays the type of memory controller
+       that is being utilized.
+
+
+Total memory managed by this memory controller attribute file:
+
+       'size_mb'
+
+       This attribute file displays, in count of megabytes, of memory
+       that this instance of memory controller manages.
+
+
+Total Uncorrectable Errors count attribute file:
+
+       'ue_count'
+
+       This attribute file displays the total count of uncorrectable
+       errors that have occurred on this memory controller. If panic_on_ue
+       is set this counter will not have a chance to increment,
+       since EDAC will panic the system.
+
+
+Total UE count that had no information attribute fileY:
+
+       'ue_noinfo_count'
+
+       This attribute file displays the number of UEs that
+       have occurred have occurred with  no informations as to which DIMM
+       slot is having errors.
+
+
+Total Correctable Errors count attribute file:
+
+       'ce_count'
+
+       This attribute file displays the total count of correctable
+       errors that have occurred on this memory controller. This
+       count is very important to examine. CEs provide early
+       indications that a DIMM is beginning to fail. This count
+       field should be monitored for non-zero values and report
+       such information to the system administrator.
+
+
+Total Correctable Errors count attribute file:
+
+       'ce_noinfo_count'
+
+       This attribute file displays the number of CEs that
+       have occurred wherewith no informations as to which DIMM slot
+       is having errors. Memory is handicapped, but operational,
+       yet no information is available to indicate which slot
+       the failing memory is in. This count field should be also
+       be monitored for non-zero values.
+
+Device Symlink:
+
+       'device'
+
+       Symlink to the memory controller device.
+
+Sdram memory scrubbing rate:
+
+       'sdram_scrub_rate'
+
+       Read/Write attribute file that controls memory scrubbing. The scrubbing
+       rate is set by writing a minimum bandwith in bytes/sec to the attribute
+       file. The rate will be translated to an internal value that gives at
+       least the specified rate.
+
+       Reading the file will return the actual scrubbing rate employed.
+
+       If configuration fails or memory scrubbing is not implemented, the value
+       of the attribute file will be -1.
+
+
+
+============================================================================
+'csrowX' DIRECTORIES
+
+In the 'csrowX' directories are EDAC control and attribute files for
+this 'X" instance of csrow:
+
+
+Total Uncorrectable Errors count attribute file:
+
+       'ue_count'
+
+       This attribute file displays the total count of uncorrectable
+       errors that have occurred on this csrow. If panic_on_ue is set
+       this counter will not have a chance to increment, since EDAC
+       will panic the system.
+
+
+Total Correctable Errors count attribute file:
+
+       'ce_count'
+
+       This attribute file displays the total count of correctable
+       errors that have occurred on this csrow. This
+       count is very important to examine. CEs provide early
+       indications that a DIMM is beginning to fail. This count
+       field should be monitored for non-zero values and report
+       such information to the system administrator.
+
+
+Total memory managed by this csrow attribute file:
+
+       'size_mb'
+
+       This attribute file displays, in count of megabytes, of memory
+       that this csrow contains.
+
+
+Memory Type attribute file:
+
+       'mem_type'
+
+       This attribute file will display what type of memory is currently
+       on this csrow. Normally, either buffered or unbuffered memory.
+       Examples:
+               Registered-DDR
+               Unbuffered-DDR
+
+
+EDAC Mode of operation attribute file:
+
+       'edac_mode'
+
+       This attribute file will display what type of Error detection
+       and correction is being utilized.
+
+
+Device type attribute file:
+
+       'dev_type'
+
+       This attribute file will display what type of DRAM device is
+       being utilized on this DIMM.
+       Examples:
+               x1
+               x2
+               x4
+               x8
+
+
+Channel 0 CE Count attribute file:
+
+       'ch0_ce_count'
+
+       This attribute file will display the count of CEs on this
+       DIMM located in channel 0.
+
+
+Channel 0 UE Count attribute file:
+
+       'ch0_ue_count'
+
+       This attribute file will display the count of UEs on this
+       DIMM located in channel 0.
+
+
+Channel 0 DIMM Label control file:
+
+       'ch0_dimm_label'
+
+       This control file allows this DIMM to have a label assigned
+       to it. With this label in the module, when errors occur
+       the output can provide the DIMM label in the system log.
+       This becomes vital for panic events to isolate the
+       cause of the UE event.
+
+       DIMM Labels must be assigned after booting, with information
+       that correctly identifies the physical slot with its
+       silk screen label. This information is currently very
+       motherboard specific and determination of this information
+       must occur in userland at this time.
+
+
+Channel 1 CE Count attribute file:
+
+       'ch1_ce_count'
+
+       This attribute file will display the count of CEs on this
+       DIMM located in channel 1.
+
+
+Channel 1 UE Count attribute file:
+
+       'ch1_ue_count'
+
+       This attribute file will display the count of UEs on this
+       DIMM located in channel 0.
+
+
+Channel 1 DIMM Label control file:
+
+       'ch1_dimm_label'
+
+       This control file allows this DIMM to have a label assigned
+       to it. With this label in the module, when errors occur
+       the output can provide the DIMM label in the system log.
+       This becomes vital for panic events to isolate the
+       cause of the UE event.
+
+       DIMM Labels must be assigned after booting, with information
+       that correctly identifies the physical slot with its
+       silk screen label. This information is currently very
+       motherboard specific and determination of this information
+       must occur in userland at this time.
+
+
+============================================================================
+SYSTEM LOGGING
+
+If logging for UEs and CEs are enabled then system logs will have
+error notices indicating errors that have been detected:
+
+EDAC MC0: CE page 0x283, offset 0xce0, grain 8, syndrome 0x6ec3, row 0,
+channel 1 "DIMM_B1": amd76x_edac
+
+EDAC MC0: CE page 0x1e5, offset 0xfb0, grain 8, syndrome 0xb741, row 0,
+channel 1 "DIMM_B1": amd76x_edac
+
+
+The structure of the message is:
+       the memory controller                   (MC0)
+       Error type                              (CE)
+       memory page                             (0x283)
+       offset in the page                      (0xce0)
+       the byte granularity                    (grain 8)
+               or resolution of the error
+       the error syndrome                      (0xb741)
+       memory row                              (row 0)
+       memory channel                          (channel 1)
+       DIMM label, if set prior                (DIMM B1
+       and then an optional, driver-specific message that may
+               have additional information.
+
+Both UEs and CEs with no info will lack all but memory controller,
+error type, a notice of "no info" and then an optional,
+driver-specific error message.
+
+
+
+============================================================================
+PCI Bus Parity Detection
+
+
+On Header Type 00 devices the primary status is looked at
+for any parity error regardless of whether Parity is enabled on the
+device.  (The spec indicates parity is generated in some cases).
+On Header Type 01 bridges, the secondary status register is also
+looked at to see if parity occurred on the bus on the other side of
+the bridge.
+
+
+SYSFS CONFIGURATION
+
+Under /sys/devices/system/edac/pci are control and attribute files as follows:
+
+
+Enable/Disable PCI Parity checking control file:
+
+       'check_pci_parity'
+
+
+       This control file enables or disables the PCI Bus Parity scanning
+       operation. Writing a 1 to this file enables the scanning. Writing
+       a 0 to this file disables the scanning.
+
+       Enable:
+       echo "1" >/sys/devices/system/edac/pci/check_pci_parity
+
+       Disable:
+       echo "0" >/sys/devices/system/edac/pci/check_pci_parity
+
+
+
+Panic on PCI PARITY Error:
+
+       'panic_on_pci_parity'
+
+
+       This control files enables or disables panicking when a parity
+       error has been detected.
+
+
+       module/kernel parameter: panic_on_pci_parity=[0|1]
+
+       Enable:
+       echo "1" >/sys/devices/system/edac/pci/panic_on_pci_parity
+
+       Disable:
+       echo "0" >/sys/devices/system/edac/pci/panic_on_pci_parity
+
+
+Parity Count:
+
+       'pci_parity_count'
+
+       This attribute file will display the number of parity errors that
+       have been detected.
+
+
+
+=======================================================================
+
+
+EDAC_DEVICE type of device
+
+In the header file, edac_core.h, there is a series of edac_device structures
+and APIs for the EDAC_DEVICE.
+
+User space access to an edac_device is through the sysfs interface.
+
+At the location /sys/devices/system/edac (sysfs) new edac_device devices will
+appear.
+
+There is a three level tree beneath the above 'edac' directory. For example,
+the 'test_device_edac' device (found at the bluesmoke.sourceforget.net website)
+installs itself as:
+
+       /sys/devices/systm/edac/test-instance
+
+in this directory are various controls, a symlink and one or more 'instance'
+directorys.
+
+The standard default controls are:
+
+       log_ce          boolean to log CE events
+       log_ue          boolean to log UE events
+       panic_on_ue     boolean to 'panic' the system if an UE is encountered
+                       (default off, can be set true via startup script)
+       poll_msec       time period between POLL cycles for events
+
+The test_device_edac device adds at least one of its own custom control:
+
+       test_bits       which in the current test driver does nothing but
+                       show how it is installed. A ported driver can
+                       add one or more such controls and/or attributes
+                       for specific uses.
+                       One out-of-tree driver uses controls here to allow
+                       for ERROR INJECTION operations to hardware
+                       injection registers
+
+The symlink points to the 'struct dev' that is registered for this edac_device.
+
+INSTANCES
+
+One or more instance directories are present. For the 'test_device_edac' case:
+
+       test-instance0
+
+
+In this directory there are two default counter attributes, which are totals of
+counter in deeper subdirectories.
+
+       ce_count        total of CE events of subdirectories
+       ue_count        total of UE events of subdirectories
+
+BLOCKS
+
+At the lowest directory level is the 'block' directory. There can be 0, 1
+or more blocks specified in each instance.
+
+       test-block0
+
+
+In this directory the default attributes are:
+
+       ce_count        which is counter of CE events for this 'block'
+                       of hardware being monitored
+       ue_count        which is counter of UE events for this 'block'
+                       of hardware being monitored
+
+
+The 'test_device_edac' device adds 4 attributes and 1 control:
+
+       test-block-bits-0       for every POLL cycle this counter
+                               is incremented
+       test-block-bits-1       every 10 cycles, this counter is bumped once,
+                               and test-block-bits-0 is set to 0
+       test-block-bits-2       every 100 cycles, this counter is bumped once,
+                               and test-block-bits-1 is set to 0
+       test-block-bits-3       every 1000 cycles, this counter is bumped once,
+                               and test-block-bits-2 is set to 0
+
+
+       reset-counters          writing ANY thing to this control will
+                               reset all the above counters.
+
+
+Use of the 'test_device_edac' driver should any others to create their own
+unique drivers for their hardware systems.
+
+The 'test_device_edac' sample driver is located at the
+bluesmoke.sourceforge.net project site for EDAC.
+