Documentation/edac.txt

   1 .. include:: <isonum.txt>
   2
   3 =====================================
   4 EDAC - Error Detection And Correction
   5 =====================================
   6
   7 .. note::
   8
   9    "bluesmoke" was the name for this device driver when it
  10    was "out-of-tree" and maintained at http://bluesmoke.sourceforge.net.
  11    That site is mostly archaic now and can be used only for historical
  12    purposes.
  13
  14    When the subsystem was pushed into 2.6.16 for the first time, it was
  15    renamed to ``EDAC``.
  16
  17 Purpose
  18 -------
  19
  20 The ``edac`` kernel module's goal is to detect and report hardware errors
  21 that occur within the computer system running under linux.
  22
  23 Memory
  24 ------
  25
  26 Memory Correctable Errors (CE) and Uncorrectable Errors (UE) are the
  27 primary errors being harvested. These types of errors are harvested by
  28 the ``edac_mc`` device.
  29
  30 Detecting CE events, then harvesting those events and reporting them,
  31 **can** but must not necessarily be a predictor of future UE events. With
  32 CE events only, the system can and will continue to operate as no data
  33 has been damaged yet.
  34
  35 However, preventive maintenance and proactive part replacement of memory
  36 DIMMs exhibiting CEs can reduce the likelihood of the dreaded UE events
  37 and system panics.
  38
  39 Other hardware elements
  40 -----------------------
  41
  42 A new feature for EDAC, the ``edac_device`` class of device, was added in
  43 the 2.6.23 version of the kernel.
  44
  45 This new device type allows for non-memory type of ECC hardware detectors
  46 to have their states harvested and presented to userspace via the sysfs
  47 interface.
  48
  49 Some architectures have ECC detectors for L1, L2 and L3 caches,
  50 along with DMA engines, fabric switches, main data path switches,
  51 interconnections, and various other hardware data paths. If the hardware
  52 reports it, then a edac_device device probably can be constructed to
  53 harvest and present that to userspace.
  54
  55
  56 PCI bus scanning
  57 ----------------
  58
  59 In addition, PCI devices are scanned for PCI Bus Parity and SERR Errors
  60 in order to determine if errors are occurring during data transfers.
  61
  62 The presence of PCI Parity errors must be examined with a grain of salt.
  63 There are several add-in adapters that do **not** follow the PCI specification
  64 with regards to Parity generation and reporting. The specification says
  65 the vendor should tie the parity status bits to 0 if they do not intend
  66 to generate parity.  Some vendors do not do this, and thus the parity bit
  67 can "float" giving false positives.
  68
  69 There is a PCI device attribute located in sysfs that is checked by
  70 the EDAC PCI scanning code. If that attribute is set, PCI parity/error
  71 scanning is skipped for that device. The attribute is::
  72
  73         broken_parity_status
  74
  75 and is located in ``/sys/devices/pci<XXX>/0000:XX:YY.Z`` directories for
  76 PCI devices.
  77
  78
  79 Versioning
  80 ----------
  81
  82 EDAC is composed of a "core" module (``edac_core.ko``) and several Memory
  83 Controller (MC) driver modules. On a given system, the CORE is loaded
  84 and one MC driver will be loaded. Both the CORE and the MC driver (or
  85 ``edac_device`` driver) have individual versions that reflect current
  86 release level of their respective modules.
  87
  88 Thus, to "report" on what version a system is running, one must report
  89 both the CORE's and the MC driver's versions.
  90
  91
  92 Loading
  93 -------
  94
  95 If ``edac`` was statically linked with the kernel then no loading
  96 is necessary. If ``edac`` was built as modules then simply modprobe
  97 the ``edac`` pieces that you need. You should be able to modprobe
  98 hardware-specific modules and have the dependencies load the necessary
  99 core modules.
 100
 101 Example::
 102
 103         $ modprobe amd76x_edac
 104
 105 loads both the ``amd76x_edac.ko`` memory controller module and the
 106 ``edac_mc.ko`` core module.
 107
 108
 109 Sysfs interface
 110 ---------------
 111
 112 EDAC presents a ``sysfs`` interface for control and reporting purposes. It
 113 lives in the /sys/devices/system/edac directory.
 114
 115 Within this directory there currently reside 2 components:
 116
 117         ======= ==============================
 118         mc      memory controller(s) system
 119         pci     PCI control and status system
 120         ======= ==============================
 121
 122
 123
 124 Memory Controller (mc) Model
 125 ----------------------------
 126
 127 Each ``mc`` device controls a set of DIMM memory modules. These modules
 128 are laid out in a Chip-Select Row (``csrowX``) and Channel table (``chX``).
 129 There can be multiple csrows and multiple channels.
 130
 131 Memory controllers allow for several csrows, with 8 csrows being a
 132 typical value. Yet, the actual number of csrows depends on the layout of
 133 a given motherboard, memory controller and DIMM characteristics.
 134
 135 Dual channels allows for 128 bit data transfers to/from the CPU from/to
 136 memory. Some newer chipsets allow for more than 2 channels, like Fully
 137 Buffered DIMMs (FB-DIMMs). The following example will assume 2 channels:
 138
 139         +--------+-----------+-----------+
 140         |        | Channel 0 | Channel 1 |
 141         +========+===========+===========+
 142         | csrow0 |  DIMM_A0  |  DIMM_B0  |
 143         +--------+           |           |
 144         | csrow1 |           |           |
 145         +--------+-----------+-----------+
 146         | csrow2 |  DIMM_A1  | DIMM_B1   |
 147         +--------+           |           |
 148         | csrow3 |           |           |
 149         +--------+-----------+-----------+
 150
 151 In the above example table there are 4 physical slots on the motherboard
 152 for memory DIMMs:
 153
 154         - DIMM_A0
 155         - DIMM_B0
 156         - DIMM_A1
 157         - DIMM_B1
 158
 159 Labels for these slots are usually silk-screened on the motherboard.
 160 Slots labeled ``A`` are channel 0 in this example. Slots labeled ``B`` are
 161 channel 1. Notice that there are two csrows possible on a physical DIMM.
 162 These csrows are allocated their csrow assignment based on the slot into
 163 which the memory DIMM is placed. Thus, when 1 DIMM is placed in each
 164 Channel, the csrows cross both DIMMs.
 165
 166 Memory DIMMs come single or dual "ranked". A rank is a populated csrow.
 167 Thus, 2 single ranked DIMMs, placed in slots DIMM_A0 and DIMM_B0 above
 168 will have 1 csrow, csrow0. csrow1 will be empty. On the other hand,
 169 when 2 dual ranked DIMMs are similarly placed, then both csrow0 and
 170 csrow1 will be populated. The pattern repeats itself for csrow2 and
 171 csrow3.
 172
 173 The representation of the above is reflected in the directory
 174 tree in EDAC's sysfs interface. Starting in directory
 175 /sys/devices/system/edac/mc each memory controller will be represented
 176 by its own ``mcX`` directory, where ``X`` is the index of the MC::
 177
 178         ..../edac/mc/
 179                    |
 180                    |->mc0
 181                    |->mc1
 182                    |->mc2
 183                    ....
 184
 185 Under each ``mcX`` directory each ``csrowX`` is again represented by a
 186 ``csrowX``, where ``X`` is the csrow index::
 187
 188         .../mc/mc0/
 189                 |
 190                 |->csrow0
 191                 |->csrow2
 192                 |->csrow3
 193                 ....
 194
 195 Notice that there is no csrow1, which indicates that csrow0 is composed
 196 of a single ranked DIMMs. This should also apply in both Channels, in
 197 order to have dual-channel mode be operational. Since both csrow2 and
 198 csrow3 are populated, this indicates a dual ranked set of DIMMs for
 199 channels 0 and 1.
 200
 201
 202 Within each of the ``mcX`` and ``csrowX`` directories are several EDAC
 203 control and attribute files.
 204
 205
 206 ``mcX`` directories
 207 -------------------
 208
 209 In ``mcX`` directories are EDAC control and attribute files for
 210 this ``X`` instance of the memory controllers.
 211
 212 For a description of the sysfs API, please see:
 213
 214         Documentation/ABI/testing/sysfs-devices-edac
 215
 216
 217 ``dimmX`` or ``rankX`` directories
 218 ----------------------------------
 219
 220 The recommended way to use the EDAC subsystem is to look at the information
 221 provided by the ``dimmX`` or ``rankX`` directories [#f5]_.
 222
 223 A typical EDAC system has the following structure under
 224 ``/sys/devices/system/edac/``\ [#f6]_::
 225
 226         /sys/devices/system/edac/
 227         ├── mc
 228         │   ├── mc0
 229         │   │   ├── ce_count
 230         │   │   ├── ce_noinfo_count
 231         │   │   ├── dimm0
 232         │   │   │   ├── dimm_dev_type
 233         │   │   │   ├── dimm_edac_mode
 234         │   │   │   ├── dimm_label
 235         │   │   │   ├── dimm_location
 236         │   │   │   ├── dimm_mem_type
 237         │   │   │   ├── size
 238         │   │   │   └── uevent
 239         │   │   ├── max_location
 240         │   │   ├── mc_name
 241         │   │   ├── reset_counters
 242         │   │   ├── seconds_since_reset
 243         │   │   ├── size_mb
 244         │   │   ├── ue_count
 245         │   │   ├── ue_noinfo_count
 246         │   │   └── uevent
 247         │   ├── mc1
 248         │   │   ├── ce_count
 249         │   │   ├── ce_noinfo_count
 250         │   │   ├── dimm0
 251         │   │   │   ├── dimm_dev_type
 252         │   │   │   ├── dimm_edac_mode
 253         │   │   │   ├── dimm_label
 254         │   │   │   ├── dimm_location
 255         │   │   │   ├── dimm_mem_type
 256         │   │   │   ├── size
 257         │   │   │   └── uevent
 258         │   │   ├── max_location
 259         │   │   ├── mc_name
 260         │   │   ├── reset_counters
 261         │   │   ├── seconds_since_reset
 262         │   │   ├── size_mb
 263         │   │   ├── ue_count
 264         │   │   ├── ue_noinfo_count
 265         │   │   └── uevent
 266         │   └── uevent
 267         └── uevent
 268
 269 In the ``dimmX`` directories are EDAC control and attribute files for
 270 this ``X`` memory module:
 271
 272 - ``size`` - Total memory managed by this csrow attribute file
 273
 274         This attribute file displays, in count of megabytes, the memory
 275         that this csrow contains.
 276
 277 - ``dimm_dev_type``  - Device type attribute file
 278
 279         This attribute file will display what type of DRAM device is
 280         being utilized on this DIMM.
 281         Examples:
 282
 283                 - x1
 284                 - x2
 285                 - x4
 286                 - x8
 287
 288 - ``dimm_edac_mode`` - EDAC Mode of operation attribute file
 289
 290         This attribute file will display what type of Error detection
 291         and correction is being utilized.
 292
 293 - ``dimm_label`` - memory module label control file
 294
 295         This control file allows this DIMM to have a label assigned
 296         to it. With this label in the module, when errors occur
 297         the output can provide the DIMM label in the system log.
 298         This becomes vital for panic events to isolate the
 299         cause of the UE event.
 300
 301         DIMM Labels must be assigned after booting, with information
 302         that correctly identifies the physical slot with its
 303         silk screen label. This information is currently very
 304         motherboard specific and determination of this information
 305         must occur in userland at this time.
 306
 307 - ``dimm_location`` - location of the memory module
 308
 309         The location can have up to 3 levels, and describe how the
 310         memory controller identifies the location of a memory module.
 311         Depending on the type of memory and memory controller, it
 312         can be:
 313
 314                 - *csrow* and *channel* - used when the memory controller
 315                   doesn't identify a single DIMM - e. g. in ``rankX`` dir;
 316                 - *branch*, *channel*, *slot* - typically used on FB-DIMM memory
 317                   controllers;
 318                 - *channel*, *slot* - used on Nehalem and newer Intel drivers.
 319
 320 - ``dimm_mem_type`` - Memory Type attribute file
 321
 322         This attribute file will display what type of memory is currently
 323         on this csrow. Normally, either buffered or unbuffered memory.
 324         Examples:
 325
 326                 - Registered-DDR
 327                 - Unbuffered-DDR
 328
 329 .. [#f5] On some systems, the memory controller doesn't have any logic
 330   to identify the memory module. On such systems, the directory is called ``rankX`` and works on a similar way as the ``csrowX`` directories.
 331   On modern Intel memory controllers, the memory controller identifies the
 332   memory modules directly. On such systems, the directory is called ``dimmX``.
 333
 334 .. [#f6] There are also some ``power`` directories and ``subsystem``
 335   symlinks inside the sysfs mapping that are automatically created by
 336   the sysfs subsystem. Currently, they serve no purpose.
 337
 338 ``csrowX`` directories
 339 ----------------------
 340
 341 When CONFIG_EDAC_LEGACY_SYSFS is enabled, sysfs will contain the csrowX
 342 directories. As this API doesn't work properly for Rambus, FB-DIMMs and
 343 modern Intel Memory Controllers, this is being deprecated in favor of
 344 dimmX directories.
 345
 346 In the ``csrowX`` directories are EDAC control and attribute files for
 347 this ``X`` instance of csrow:
 348
 349
 350 - ``ue_count`` - Total Uncorrectable Errors count attribute file
 351
 352         This attribute file displays the total count of uncorrectable
 353         errors that have occurred on this csrow. If panic_on_ue is set
 354         this counter will not have a chance to increment, since EDAC
 355         will panic the system.
 356
 357
 358 - ``ce_count`` - Total Correctable Errors count attribute file
 359
 360         This attribute file displays the total count of correctable
 361         errors that have occurred on this csrow. This count is very
 362         important to examine. CEs provide early indications that a
 363         DIMM is beginning to fail. This count field should be
 364         monitored for non-zero values and report such information
 365         to the system administrator.
 366
 367
 368 - ``size_mb`` - Total memory managed by this csrow attribute file
 369
 370         This attribute file displays, in count of megabytes, the memory
 371         that this csrow contains.
 372
 373
 374 - ``mem_type`` - Memory Type attribute file
 375
 376         This attribute file will display what type of memory is currently
 377         on this csrow. Normally, either buffered or unbuffered memory.
 378         Examples:
 379
 380                 - Registered-DDR
 381                 - Unbuffered-DDR
 382
 383
 384 - ``edac_mode`` - EDAC Mode of operation attribute file
 385
 386         This attribute file will display what type of Error detection
 387         and correction is being utilized.
 388
 389
 390 - ``dev_type`` - Device type attribute file
 391
 392         This attribute file will display what type of DRAM device is
 393         being utilized on this DIMM.
 394         Examples:
 395
 396                 - x1
 397                 - x2
 398                 - x4
 399                 - x8
 400
 401
 402 - ``ch0_ce_count`` - Channel 0 CE Count attribute file
 403
 404         This attribute file will display the count of CEs on this
 405         DIMM located in channel 0.
 406
 407
 408 - ``ch0_ue_count`` - Channel 0 UE Count attribute file
 409
 410         This attribute file will display the count of UEs on this
 411         DIMM located in channel 0.
 412
 413
 414 - ``ch0_dimm_label`` - Channel 0 DIMM Label control file
 415
 416
 417         This control file allows this DIMM to have a label assigned
 418         to it. With this label in the module, when errors occur
 419         the output can provide the DIMM label in the system log.
 420         This becomes vital for panic events to isolate the
 421         cause of the UE event.
 422
 423         DIMM Labels must be assigned after booting, with information
 424         that correctly identifies the physical slot with its
 425         silk screen label. This information is currently very
 426         motherboard specific and determination of this information
 427         must occur in userland at this time.
 428
 429
 430 - ``ch1_ce_count`` - Channel 1 CE Count attribute file
 431
 432
 433         This attribute file will display the count of CEs on this
 434         DIMM located in channel 1.
 435
 436
 437 - ``ch1_ue_count`` - Channel 1 UE Count attribute file
 438
 439
 440         This attribute file will display the count of UEs on this
 441         DIMM located in channel 0.
 442
 443
 444 - ``ch1_dimm_label`` - Channel 1 DIMM Label control file
 445
 446         This control file allows this DIMM to have a label assigned
 447         to it. With this label in the module, when errors occur
 448         the output can provide the DIMM label in the system log.
 449         This becomes vital for panic events to isolate the
 450         cause of the UE event.
 451
 452         DIMM Labels must be assigned after booting, with information
 453         that correctly identifies the physical slot with its
 454         silk screen label. This information is currently very
 455         motherboard specific and determination of this information
 456         must occur in userland at this time.
 457
 458
 459 System Logging
 460 --------------
 461
 462 If logging for UEs and CEs is enabled, then system logs will contain
 463 information indicating that errors have been detected::
 464
 465   EDAC MC0: CE page 0x283, offset 0xce0, grain 8, syndrome 0x6ec3, row 0, channel 1 "DIMM_B1": amd76x_edac
 466   EDAC MC0: CE page 0x1e5, offset 0xfb0, grain 8, syndrome 0xb741, row 0, channel 1 "DIMM_B1": amd76x_edac
 467
 468
 469 The structure of the message is:
 470
 471         +---------------------------------------+-------------+
 472         | Content                               + Example     |
 473         +=======================================+=============+
 474         | The memory controller                 | MC0         |
 475         +---------------------------------------+-------------+
 476         | Error type                            | CE          |
 477         +---------------------------------------+-------------+
 478         | Memory page                           | 0x283       |
 479         +---------------------------------------+-------------+
 480         | Offset in the page                    | 0xce0       |
 481         +---------------------------------------+-------------+
 482         | The byte granularity                  | grain 8     |
 483         | or resolution of the error            |             |
 484         +---------------------------------------+-------------+
 485         | The error syndrome                    | 0xb741      |
 486         +---------------------------------------+-------------+
 487         | Memory row                            | row 0       +
 488         +---------------------------------------+-------------+
 489         | Memory channel                        | channel 1   |
 490         +---------------------------------------+-------------+
 491         | DIMM label, if set prior              | DIMM B1     |
 492         +---------------------------------------+-------------+
 493         | And then an optional, driver-specific |             |
 494         | message that may have additional      |             |
 495         | information.                          |             |
 496         +---------------------------------------+-------------+
 497
 498 Both UEs and CEs with no info will lack all but memory controller, error
 499 type, a notice of "no info" and then an optional, driver-specific error
 500 message.
 501
 502
 503 PCI Bus Parity Detection
 504 ------------------------
 505
 506 On Header Type 00 devices, the primary status is looked at for any
 507 parity error regardless of whether parity is enabled on the device or
 508 not. (The spec indicates parity is generated in some cases). On Header
 509 Type 01 bridges, the secondary status register is also looked at to see
 510 if parity occurred on the bus on the other side of the bridge.
 511
 512
 513 Sysfs configuration
 514 -------------------
 515
 516 Under ``/sys/devices/system/edac/pci`` are control and attribute files as
 517 follows:
 518
 519
 520 - ``check_pci_parity`` - Enable/Disable PCI Parity checking control file
 521
 522         This control file enables or disables the PCI Bus Parity scanning
 523         operation. Writing a 1 to this file enables the scanning. Writing
 524         a 0 to this file disables the scanning.
 525
 526         Enable::
 527
 528                 echo "1" >/sys/devices/system/edac/pci/check_pci_parity
 529
 530         Disable::
 531
 532                 echo "0" >/sys/devices/system/edac/pci/check_pci_parity
 533
 534
 535 - ``pci_parity_count`` - Parity Count
 536
 537         This attribute file will display the number of parity errors that
 538         have been detected.
 539
 540
 541 Module parameters
 542 -----------------
 543
 544 - ``edac_mc_panic_on_ue`` - Panic on UE control file
 545
 546         An uncorrectable error will cause a machine panic.  This is usually
 547         desirable.  It is a bad idea to continue when an uncorrectable error
 548         occurs - it is indeterminate what was uncorrected and the operating
 549         system context might be so mangled that continuing will lead to further
 550         corruption. If the kernel has MCE configured, then EDAC will never
 551         notice the UE.
 552
 553         LOAD TIME::
 554
 555                 module/kernel parameter: edac_mc_panic_on_ue=[0|1]
 556
 557         RUN TIME::
 558
 559                 echo "1" > /sys/module/edac_core/parameters/edac_mc_panic_on_ue
 560
 561
 562 - ``edac_mc_log_ue`` - Log UE control file
 563
 564
 565         Generate kernel messages describing uncorrectable errors.  These errors
 566         are reported through the system message log system.  UE statistics
 567         will be accumulated even when UE logging is disabled.
 568
 569         LOAD TIME::
 570
 571                 module/kernel parameter: edac_mc_log_ue=[0|1]
 572
 573         RUN TIME::
 574
 575                 echo "1" > /sys/module/edac_core/parameters/edac_mc_log_ue
 576
 577
 578 - ``edac_mc_log_ce`` - Log CE control file
 579
 580
 581         Generate kernel messages describing correctable errors.  These
 582         errors are reported through the system message log system.
 583         CE statistics will be accumulated even when CE logging is disabled.
 584
 585         LOAD TIME::
 586
 587                 module/kernel parameter: edac_mc_log_ce=[0|1]
 588
 589         RUN TIME::
 590
 591                 echo "1" > /sys/module/edac_core/parameters/edac_mc_log_ce
 592
 593
 594 - ``edac_mc_poll_msec`` - Polling period control file
 595
 596
 597         The time period, in milliseconds, for polling for error information.
 598         Too small a value wastes resources.  Too large a value might delay
 599         necessary handling of errors and might loose valuable information for
 600         locating the error.  1000 milliseconds (once each second) is the current
 601         default. Systems which require all the bandwidth they can get, may
 602         increase this.
 603
 604         LOAD TIME::
 605
 606                 module/kernel parameter: edac_mc_poll_msec=[0|1]
 607
 608         RUN TIME::
 609
 610                 echo "1000" > /sys/module/edac_core/parameters/edac_mc_poll_msec
 611
 612
 613 - ``panic_on_pci_parity`` - Panic on PCI PARITY Error
 614
 615
 616         This control file enables or disables panicking when a parity
 617         error has been detected.
 618
 619
 620         module/kernel parameter::
 621
 622                         edac_panic_on_pci_pe=[0|1]
 623
 624         Enable::
 625
 626                 echo "1" > /sys/module/edac_core/parameters/edac_panic_on_pci_pe
 627
 628         Disable::
 629
 630                 echo "0" > /sys/module/edac_core/parameters/edac_panic_on_pci_pe
 631
 632
 633
 634 EDAC device type
 635 ----------------
 636
 637 In the header file, edac_core.h, there is a series of edac_device structures
 638 and APIs for the EDAC_DEVICE.
 639
 640 User space access to an edac_device is through the sysfs interface.
 641
 642 At the location ``/sys/devices/system/edac`` (sysfs) new edac_device devices
 643 will appear.
 644
 645 There is a three level tree beneath the above ``edac`` directory. For example,
 646 the ``test_device_edac`` device (found at the http://bluesmoke.sourceforget.net
 647 website) installs itself as::
 648
 649         /sys/devices/system/edac/test-instance
 650
 651 in this directory are various controls, a symlink and one or more ``instance``
 652 directories.
 653
 654 The standard default controls are:
 655
 656         ==============  =======================================================
 657         log_ce          boolean to log CE events
 658         log_ue          boolean to log UE events
 659         panic_on_ue     boolean to ``panic`` the system if an UE is encountered
 660                         (default off, can be set true via startup script)
 661         poll_msec       time period between POLL cycles for events
 662         ==============  =======================================================
 663
 664 The test_device_edac device adds at least one of its own custom control:
 665
 666         ==============  ==================================================
 667         test_bits       which in the current test driver does nothing but
 668                         show how it is installed. A ported driver can
 669                         add one or more such controls and/or attributes
 670                         for specific uses.
 671                         One out-of-tree driver uses controls here to allow
 672                         for ERROR INJECTION operations to hardware
 673                         injection registers
 674         ==============  ==================================================
 675
 676 The symlink points to the 'struct dev' that is registered for this edac_device.
 677
 678 Instances
 679 ---------
 680
 681 One or more instance directories are present. For the ``test_device_edac``
 682 case:
 683
 684         +----------------+
 685         | test-instance0 |
 686         +----------------+
 687
 688
 689 In this directory there are two default counter attributes, which are totals of
 690 counter in deeper subdirectories.
 691
 692         ==============  ====================================
 693         ce_count        total of CE events of subdirectories
 694         ue_count        total of UE events of subdirectories
 695         ==============  ====================================
 696
 697 Blocks
 698 ------
 699
 700 At the lowest directory level is the ``block`` directory. There can be 0, 1
 701 or more blocks specified in each instance:
 702
 703         +-------------+
 704         | test-block0 |
 705         +-------------+
 706
 707 In this directory the default attributes are:
 708
 709         ==============  ================================================
 710         ce_count        which is counter of CE events for this ``block``
 711                         of hardware being monitored
 712         ue_count        which is counter of UE events for this ``block``
 713                         of hardware being monitored
 714         ==============  ================================================
 715
 716
 717 The ``test_device_edac`` device adds 4 attributes and 1 control:
 718
 719         ================== ====================================================
 720         test-block-bits-0       for every POLL cycle this counter
 721                                 is incremented
 722         test-block-bits-1       every 10 cycles, this counter is bumped once,
 723                                 and test-block-bits-0 is set to 0
 724         test-block-bits-2       every 100 cycles, this counter is bumped once,
 725                                 and test-block-bits-1 is set to 0
 726         test-block-bits-3       every 1000 cycles, this counter is bumped once,
 727                                 and test-block-bits-2 is set to 0
 728         ================== ====================================================
 729
 730
 731         ================== ====================================================
 732         reset-counters          writing ANY thing to this control will
 733                                 reset all the above counters.
 734         ================== ====================================================
 735
 736
 737 Use of the ``test_device_edac`` driver should enable any others to create their own
 738 unique drivers for their hardware systems.
 739
 740 The ``test_device_edac`` sample driver is located at the
 741 http://bluesmoke.sourceforge.net project site for EDAC.
 742
 743
 744 Usage of EDAC APIs on Nehalem and newer Intel CPUs
 745 --------------------------------------------------
 746
 747 On older Intel architectures, the memory controller was part of the North
 748 Bridge chipset. Nehalem, Sandy Bridge, Ivy Bridge, Haswell, Sky Lake and
 749 newer Intel architectures integrated an enhanced version of the memory
 750 controller (MC) inside the CPUs.
 751
 752 This chapter will cover the differences of the enhanced memory controllers
 753 found on newer Intel CPUs, such as ``i7core_edac``, ``sb_edac`` and
 754 ``sbx_edac`` drivers.
 755
 756 .. note::
 757
 758    The Xeon E7 processor families use a separate chip for the memory
 759    controller, called Intel Scalable Memory Buffer. This section doesn't
 760    apply for such families.
 761
 762 1) There is one Memory Controller per Quick Patch Interconnect
 763    (QPI). At the driver, the term "socket" means one QPI. This is
 764    associated with a physical CPU socket.
 765
 766    Each MC have 3 physical read channels, 3 physical write channels and
 767    3 logic channels. The driver currently sees it as just 3 channels.
 768    Each channel can have up to 3 DIMMs.
 769
 770    The minimum known unity is DIMMs. There are no information about csrows.
 771    As EDAC API maps the minimum unity is csrows, the driver sequentially
 772    maps channel/DIMM into different csrows.
 773
 774    For example, supposing the following layout::
 775
 776         Ch0 phy rd0, wr0 (0x063f4031): 2 ranks, UDIMMs
 777           dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
 778           dimm 1 1024 Mb offset: 4, bank: 8, rank: 1, row: 0x4000, col: 0x400
 779         Ch1 phy rd1, wr1 (0x063f4031): 2 ranks, UDIMMs
 780           dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
 781         Ch2 phy rd3, wr3 (0x063f4031): 2 ranks, UDIMMs
 782           dimm 0 1024 Mb offset: 0, bank: 8, rank: 1, row: 0x4000, col: 0x400
 783
 784    The driver will map it as::
 785
 786         csrow0: channel 0, dimm0
 787         csrow1: channel 0, dimm1
 788         csrow2: channel 1, dimm0
 789         csrow3: channel 2, dimm0
 790
 791    exports one DIMM per csrow.
 792
 793    Each QPI is exported as a different memory controller.
 794
 795 2) The MC has the ability to inject errors to test drivers. The drivers
 796    implement this functionality via some error injection nodes:
 797
 798    For injecting a memory error, there are some sysfs nodes, under
 799    ``/sys/devices/system/edac/mc/mc?/``:
 800
 801    - ``inject_addrmatch/*``:
 802       Controls the error injection mask register. It is possible to specify
 803       several characteristics of the address to match an error code::
 804
 805          dimm = the affected dimm. Numbers are relative to a channel;
 806          rank = the memory rank;
 807          channel = the channel that will generate an error;
 808          bank = the affected bank;
 809          page = the page address;
 810          column (or col) = the address column.
 811
 812       each of the above values can be set to "any" to match any valid value.
 813
 814       At driver init, all values are set to any.
 815
 816       For example, to generate an error at rank 1 of dimm 2, for any channel,
 817       any bank, any page, any column::
 818
 819                 echo 2 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/dimm
 820                 echo 1 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/rank
 821
 822         To return to the default behaviour of matching any, you can do::
 823
 824                 echo any >/sys/devices/system/edac/mc/mc0/inject_addrmatch/dimm
 825                 echo any >/sys/devices/system/edac/mc/mc0/inject_addrmatch/rank
 826
 827    - ``inject_eccmask``:
 828           specifies what bits will have troubles,
 829
 830    - ``inject_section``:
 831        specifies what ECC cache section will get the error::
 832
 833                 3 for both
 834                 2 for the highest
 835                 1 for the lowest
 836
 837    - ``inject_type``:
 838        specifies the type of error, being a combination of the following bits::
 839
 840                 bit 0 - repeat
 841                 bit 1 - ecc
 842                 bit 2 - parity
 843
 844    - ``inject_enable``:
 845        starts the error generation when something different than 0 is written.
 846
 847    All inject vars can be read. root permission is needed for write.
 848
 849    Datasheet states that the error will only be generated after a write on an
 850    address that matches inject_addrmatch. It seems, however, that reading will
 851    also produce an error.
 852
 853    For example, the following code will generate an error for any write access
 854    at socket 0, on any DIMM/address on channel 2::
 855
 856         echo 2 >/sys/devices/system/edac/mc/mc0/inject_addrmatch/channel
 857         echo 2 >/sys/devices/system/edac/mc/mc0/inject_type
 858         echo 64 >/sys/devices/system/edac/mc/mc0/inject_eccmask
 859         echo 3 >/sys/devices/system/edac/mc/mc0/inject_section
 860         echo 1 >/sys/devices/system/edac/mc/mc0/inject_enable
 861         dd if=/dev/mem of=/dev/null seek=16k bs=4k count=1 >& /dev/null
 862
 863    For socket 1, it is needed to replace "mc0" by "mc1" at the above
 864    commands.
 865
 866    The generated error message will look like::
 867
 868         EDAC MC0: UE row 0, channel-a= 0 channel-b= 0 labels "-": NON_FATAL (addr = 0x0075b980, socket=0, Dimm=0, Channel=2, syndrome=0x00000040, count=1, Err=8c0000400001009f:4000080482 (read error: read ECC error))
 869
 870 3) Corrected Error memory register counters
 871
 872    Those newer MCs have some registers to count memory errors. The driver
 873    uses those registers to report Corrected Errors on devices with Registered
 874    DIMMs.
 875
 876    However, those counters don't work with Unregistered DIMM. As the chipset
 877    offers some counters that also work with UDIMMs (but with a worse level of
 878    granularity than the default ones), the driver exposes those registers for
 879    UDIMM memories.
 880
 881    They can be read by looking at the contents of ``all_channel_counts/``::
 882
 883      $ for i in /sys/devices/system/edac/mc/mc0/all_channel_counts/*; do echo $i; cat $i; done
 884         /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm0
 885         0
 886         /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm1
 887         0
 888         /sys/devices/system/edac/mc/mc0/all_channel_counts/udimm2
 889         0
 890
 891    What happens here is that errors on different csrows, but at the same
 892    dimm number will increment the same counter.
 893    So, in this memory mapping::
 894
 895         csrow0: channel 0, dimm0
 896         csrow1: channel 0, dimm1
 897         csrow2: channel 1, dimm0
 898         csrow3: channel 2, dimm0
 899
 900    The hardware will increment udimm0 for an error at the first dimm at either
 901    csrow0, csrow2  or csrow3;
 902
 903    The hardware will increment udimm1 for an error at the second dimm at either
 904    csrow0, csrow2  or csrow3;
 905
 906    The hardware will increment udimm2 for an error at the third dimm at either
 907    csrow0, csrow2  or csrow3;
 908
 909 4) Standard error counters
 910
 911    The standard error counters are generated when an mcelog error is received
 912    by the driver. Since, with UDIMM, this is counted by software, it is
 913    possible that some errors could be lost. With RDIMM's, they display the
 914    contents of the registers
 915
 916 Reference documents used on ``amd64_edac``
 917 ------------------------------------------
 918
 919 ``amd64_edac`` module is based on the following documents
 920 (available from http://support.amd.com/en-us/search/tech-docs):
 921
 922 1. :Title:  BIOS and Kernel Developer's Guide for AMD Athlon 64 and AMD
 923            Opteron Processors
 924    :AMD publication #: 26094
 925    :Revision: 3.26
 926    :Link: http://support.amd.com/TechDocs/26094.PDF
 927
 928 2. :Title:  BIOS and Kernel Developer's Guide for AMD NPT Family 0Fh
 929            Processors
 930    :AMD publication #: 32559
 931    :Revision: 3.00
 932    :Issue Date: May 2006
 933    :Link: http://support.amd.com/TechDocs/32559.pdf
 934
 935 3. :Title:  BIOS and Kernel Developer's Guide (BKDG) For AMD Family 10h
 936            Processors
 937    :AMD publication #: 31116
 938    :Revision: 3.00
 939    :Issue Date: September 07, 2007
 940    :Link: http://support.amd.com/TechDocs/31116.pdf
 941
 942 4. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h
 943           Models 30h-3Fh Processors
 944    :AMD publication #: 49125
 945    :Revision: 3.06
 946    :Issue Date: 2/12/2015 (latest release)
 947    :Link: http://support.amd.com/TechDocs/49125_15h_Models_30h-3Fh_BKDG.pdf
 948
 949 5. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h
 950           Models 60h-6Fh Processors
 951    :AMD publication #: 50742
 952    :Revision: 3.01
 953    :Issue Date: 7/23/2015 (latest release)
 954    :Link: http://support.amd.com/TechDocs/50742_15h_Models_60h-6Fh_BKDG.pdf
 955
 956 6. :Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 16h
 957           Models 00h-0Fh Processors
 958    :AMD publication #: 48751
 959    :Revision: 3.03
 960    :Issue Date: 2/23/2015 (latest release)
 961    :Link: http://support.amd.com/TechDocs/48751_16h_bkdg.pdf
 962
 963 Credits
 964 =======
 965
 966 * Written by Doug Thompson <dougthompson@xmission.com>
 967
 968   - 7 Dec 2005
 969   - 17 Jul 2007 Updated
 970
 971 * |copy| Mauro Carvalho Chehab
 972
 973   - 05 Aug 2009 Nehalem interface
 974   - 26 Oct 2016 Converted to ReST and cleanups at the Nehalem section
 975
 976 * EDAC authors/maintainers:
 977
 978   - Doug Thompson, Dave Jiang, Dave Peterson et al,
 979   - Mauro Carvalho Chehab
 980   - Borislav Petkov
 981   - original author: Thayne Harbaugh