[PATCH 1/2] ABI: rtc-ab8500: fix rtc_calibration documentation
The "What:" field at the ABI should describe the location of the ABI, e. g. the position under a mounted sysfs. Fix it. Cc: Mark Godfrey Cc: Linus Walleij Cc: Alessandro Zummo Cc: Alexandre Belloni Cc: linux-arm-ker...@lists.infradead.org Cc: rtc-li...@googlegroups.com Signed-off-by: Mauro Carvalho Chehab --- .../ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration index 4cf1e7d9..ec950c93e5c6 100644 --- a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration +++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration @@ -1,8 +1,9 @@ -What: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock +What: /sys/class/rtc/rtc0/device/rtc_calibration Date: Oct 2011 KernelVersion: 3.0 Contact:Mark Godfrey -Description:The rtc_calibration attribute allows the userspace to +Description:Attribute for calibrating ST-Ericsson AB8500 Real Time Clock + The rtc_calibration attribute allows the userspace to calibrate the AB8500.s 32KHz Real Time Clock. Every 60 seconds the AB8500 will correct the RTC's value by adding to it the value of this attribute. -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 2/2] ABI: ibm_rtl: the "What:" fields are incomplete
The "What:" field at the ABI should describe the location of the ABI, e. g. the position under a mounted sysfs. However, this file has only the basename without the path. Fix it. Cc: Vernon Mauery Cc: Darren Hart Cc: platform-driver-...@vger.kernel.org Signed-off-by: Mauro Carvalho Chehab --- Documentation/ABI/testing/sysfs-devices-system-ibm-rtl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl index b82deeaec314..470def06ab0a 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl +++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl @@ -1,4 +1,4 @@ -What: state +What: /sys/devices/system/ibm_rtl/state Date: Sep 2010 KernelVersion: 2.6.37 Contact:Vernon Mauery @@ -10,7 +10,7 @@ Description:The state file allows a means by which to change in and Users: The ibm-prtm userspace daemon uses this interface. -What: version +What: /sys/devices/system/ibm_rtl/version Date: Sep 2010 KernelVersion: 2.6.37 Contact:Vernon Mauery -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/2] ABI: rtc-ab8500: fix rtc_calibration documentation
On Sat, Oct 29, 2016 at 12:10 PM, Mauro Carvalho Chehab wrote: > The "What:" field at the ABI should describe the location of > the ABI, e. g. the position under a mounted sysfs. > > Fix it. > > Cc: Mark Godfrey > Cc: Linus Walleij > Cc: Alessandro Zummo > Cc: Alexandre Belloni > Cc: linux-arm-ker...@lists.infradead.org > Cc: rtc-li...@googlegroups.com > Signed-off-by: Mauro Carvalho Chehab Acked-by: Linus Walleij Yours, Linus Walleij -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 3/3] doc-rst: add an ABI book
Em Fri, 28 Oct 2016 17:57:29 -0400 Greg Kroah-Hartman escreveu: > On Fri, Oct 28, 2016 at 11:33:51AM -0200, Mauro Carvalho Chehab wrote: > > Em Fri, 28 Oct 2016 08:49:12 -0400 > > Greg Kroah-Hartman escreveu: > > > > > On Fri, Oct 28, 2016 at 08:31:57AM -0400, Greg Kroah-Hartman wrote: > > > > On Fri, Oct 28, 2016 at 10:19:47AM -0200, Mauro Carvalho Chehab wrote: > > > > > > > > > Use a script to parse the Documenation/ABI directory and output > > > > > it at the admin-guide. > > > > > > > > > > Signed-off-by: Mauro Carvalho Chehab > > > > > --- > > > > > Documentation/admin-guide/abi.rst | 5 + > > > > > Documentation/admin-guide/index.rst | 1 + > > > > > Documentation/sphinx/abi_book.pl| 208 > > > > > > > > > > 3 files changed, 214 insertions(+) > > > > > create mode 100644 Documentation/admin-guide/abi.rst > > > > > create mode 100755 Documentation/sphinx/abi_book.pl > > > > > > > > Any hint as to what the output of this actually looks like? > > > > > > Doh, you already showed it in patch 0/3, that's what I get for never > > > reading cover letters... > > > > :-) > > > > > sorry for the noise, > > > > No problem. > > > > Btw, looking at the output of the script, I noticed a > > few files where "What" doesn't point to configfs/sysfs/procfs: > > > > - Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration > > What: Attribute for calibrating ST-Ericsson AB8500 Real Time > > Clock > > > > This is probably a sysfs interface, so, IMHO, "What" here is wrong. > > > > From the name of the file, I suspect that it should be, instead: > > What: /sysfs/class/rtc/rtc0/device/rtc_calibration > > > > Looks right, but the original authors would know more. Patch sent, c/c authors/maintainers of the driver. > > > - Documentation/ABI/stable/thermal-notification > > What: A notification mechanism for thermal related events > > > > Not sure what kind of interface this is referring to. Perhaps a > > sysctl interface? > > It's a netlink api, odd, haven't seen that before. > > - Documentation/ABI/stable/syscalls > > What: The kernel syscall interface > > > > This sounds OK, although it probably makes sense to document > > each system call. > > Heh, that's the whole man page project, I don't think we want to suck > that into the kernel just yet :) Perhaps we could prefix those "What:" entries that doesn't start with a "/" with something else. The issue with a random string at What: is that, when sorting the entries before output the database, they'll be after all others that start with "/". > > - Documentation/ABI/testing/sysfs-devices-system-ibm-rtl > > What: state > > What: version > > > > According with their descriptions, both are needed for the > > "ibm-prtm" userspace daemon, but it provides no glue where > > this should be located. Looking at its source file, it seems > > that they should be located at [1]: > > > > /sys/devices/system/ibm_rtl/state > > and > > /proc/version > > > > Btw, IMHO, it doesn't make much sense to document /proc/version > > inside sysfs-devices-system-ibm-rtl. > > That might be a sysfs version file, not /proc/version, as it doesn't > look like /proc/version is described that way. Yeah, you're right: the driver also defines a "version". Weird enough, the daemon meant to use this driver seems to look only at /proc/version. Anyway, patch sent, c/c authors/maintainers of the driver. > > thanks, > > greg k-h Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 12/19] edac: move documentation from edac_device to edac_core.h
Several functions are documented at edac_device.c.
As we'll be including edac_core.h at drivers-api book, move those,
in order for the kernel-doc markups be part of the API
documentation book.
As several of those kernel-doc macros are not in the right format,
fix them.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_device.c | 58 --
drivers/edac/edac_device.h | 51
2 files changed, 51 insertions(+), 58 deletions(-)
diff --git a/drivers/edac/edac_device.c b/drivers/edac/edac_device.c
index 046ab7794fc2..de4d5d08af9e 100644
--- a/drivers/edac/edac_device.c
+++ b/drivers/edac/edac_device.c
@@ -47,21 +47,6 @@ static void edac_device_dump_device(struct
edac_device_ctl_info *edac_dev)
}
#endif /* CONFIG_EDAC_DEBUG */
-
-/*
- * edac_device_alloc_ctl_info()
- * Allocate a new edac device control info structure
- *
- * The control structure is allocated in complete chunk
- * from the OS. It is in turn sub allocated to the
- * various objects that compose the structure
- *
- * The structure has a 'nr_instance' array within itself.
- * Each instance represents a major component
- * Example: L1 cache and L2 cache are 2 instance components
- *
- * Within each instance is an array of 'nr_blocks' blockoffsets
- */
struct edac_device_ctl_info *edac_device_alloc_ctl_info(
unsigned sz_private,
char *edac_device_name, unsigned nr_instances,
@@ -241,11 +226,6 @@ struct edac_device_ctl_info *edac_device_alloc_ctl_info(
}
EXPORT_SYMBOL_GPL(edac_device_alloc_ctl_info);
-/*
- * edac_device_free_ctl_info()
- * frees the memory allocated by the edac_device_alloc_ctl_info()
- * function
- */
void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info)
{
edac_device_unregister_sysfs_main_kobj(ctl_info);
@@ -457,12 +437,6 @@ void edac_device_reset_delay_period(struct
edac_device_ctl_info *edac_dev,
edac_mod_work(&edac_dev->work, jiffs);
}
-/*
- * edac_device_alloc_index: Allocate a unique device index number
- *
- * Return:
- * allocated index number
- */
int edac_device_alloc_index(void)
{
static atomic_t device_indexes = ATOMIC_INIT(0);
@@ -471,17 +445,6 @@ int edac_device_alloc_index(void)
}
EXPORT_SYMBOL_GPL(edac_device_alloc_index);
-/**
- * edac_device_add_device: Insert the 'edac_dev' structure into the
- * edac_device global list and create sysfs entries associated with
- * edac_device structure.
- * @edac_device: pointer to the edac_device structure to be added to the list
- * 'edac_device' structure.
- *
- * Return:
- * 0 Success
- * !0 Failure
- */
int edac_device_add_device(struct edac_device_ctl_info *edac_dev)
{
edac_dbg(0, "\n");
@@ -538,19 +501,6 @@ int edac_device_add_device(struct edac_device_ctl_info
*edac_dev)
}
EXPORT_SYMBOL_GPL(edac_device_add_device);
-/**
- * edac_device_del_device:
- * Remove sysfs entries for specified edac_device structure and
- * then remove edac_device structure from global list
- *
- * @dev:
- * Pointer to 'struct device' representing edac_device
- * structure to remove.
- *
- * Return:
- * Pointer to removed edac_device structure,
- * OR NULL if device not found.
- */
struct edac_device_ctl_info *edac_device_del_device(struct device *dev)
{
struct edac_device_ctl_info *edac_dev;
@@ -605,10 +555,6 @@ static inline int edac_device_get_panic_on_ue(struct
edac_device_ctl_info
return edac_dev->panic_on_ue;
}
-/*
- * edac_device_handle_ce
- * perform a common output and handling of an 'edac_dev' CE event
- */
void edac_device_handle_ce(struct edac_device_ctl_info *edac_dev,
int inst_nr, int block_nr, const char *msg)
{
@@ -651,10 +597,6 @@ void edac_device_handle_ce(struct edac_device_ctl_info
*edac_dev,
}
EXPORT_SYMBOL_GPL(edac_device_handle_ce);
-/*
- * edac_device_handle_ue
- * perform a common output and handling of an 'edac_dev' UE event
- */
void edac_device_handle_ue(struct edac_device_ctl_info *edac_dev,
int inst_nr, int block_nr, const char *msg)
{
diff --git a/drivers/edac/edac_device.h b/drivers/edac/edac_device.h
index eb1204408529..1aaba74ae411 100644
--- a/drivers/edac/edac_device.h
+++ b/drivers/edac/edac_device.h
@@ -257,12 +257,63 @@ extern struct edac_device_ctl_info
*edac_device_alloc_ctl_info(
extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
+/**
+ * edac_device_add_device: Insert the 'edac_dev' structure into the
+ * edac_device global list and create sysfs entries associated with
+ * edac_device structure.
+ *
+ * @edac_dev: pointer to edac_device structure to be added to the list
+ * 'edac_device' structure.
+ *
+ * Returns:
+ * 0 on Success, or an error code on failure
+ */
extern int edac_device_add_device(struct edac_device_ct
[PATCH v2 17/19] edac: fix kernel-doc tags at the drivers/edac_*.h
Some kernel-doc tags don't provide good descriptions or use
a different style. Adjust them.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/admin-guide/ras.rst | 2 +-
drivers/edac/edac_mc.h| 60 ---
2 files changed, 38 insertions(+), 24 deletions(-)
diff --git a/Documentation/admin-guide/ras.rst
b/Documentation/admin-guide/ras.rst
index 2f8706bae5a4..d71340e86c27 100644
--- a/Documentation/admin-guide/ras.rst
+++ b/Documentation/admin-guide/ras.rst
@@ -843,7 +843,7 @@ Module parameters
EDAC device type
-In the header file, edac_core.h, there is a series of edac_device structures
+In the header file, edac_pci.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.
diff --git a/drivers/edac/edac_mc.h b/drivers/edac/edac_mc.h
index 97ee6a91f633..db466b37cd7a 100644
--- a/drivers/edac/edac_mc.h
+++ b/drivers/edac/edac_mc.h
@@ -15,6 +15,8 @@
* Refactored for multi-source files:
* Doug Thompson
*
+ * Please look at Documentation/driver-api/edac.rst for more info about
+ * EDAC core structs and functions.
*/
#ifndef _EDAC_MC_H_
@@ -94,7 +96,8 @@ do {
\
#define to_mci(k) container_of(k, struct mem_ctl_info, dev)
/**
- * edac_mc_alloc: Allocate and partially fill a struct mem_ctl_info structure
+ * edac_mc_alloc() - Allocate and partially fill a struct &mem_ctl_info.
+ *
* @mc_num:Memory controller number
* @n_layers: Number of MC hierarchy layers
* @layers:Describes each layer as seen by the Memory Controller
@@ -116,8 +119,8 @@ do {
\
* on such scenarios, as grouping the multiple ranks require drivers change.
*
* Returns:
- * On failure: NULL
- * On success: struct mem_ctl_info pointer
+ * On success, return a pointer to struct mem_ctl_info pointer;
+ * %NULL otherwise
*/
struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
unsigned n_layers,
@@ -125,62 +128,73 @@ struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
unsigned sz_pvt);
/**
- * edac_mc_add_mc_with_groups: Insert the 'mci' structure into the mci
- * global list and create sysfs entries associated with mci structure
+ * edac_mc_add_mc_with_groups() - Insert the @mci structure into the mci
+ * global list and create sysfs entries associated with @mci structure.
+ *
* @mci: pointer to the mci structure to be added to the list
* @groups: optional attribute groups for the driver-specific sysfs entries
*
- * Return:
- * 0 Success
- * !0 Failure
+ * Returns:
+ * 0 on Success, or an error code on failure
*/
extern int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
const struct attribute_group **groups);
#define edac_mc_add_mc(mci)edac_mc_add_mc_with_groups(mci, NULL)
/**
- * edac_mc_free
- * 'Free' a previously allocated 'mci' structure
+ * edac_mc_free() - Frees a previously allocated @mci structure
+ *
* @mci: pointer to a struct mem_ctl_info structure
*/
extern void edac_mc_free(struct mem_ctl_info *mci);
/**
- * edac_mc_find: Search for a mem_ctl_info structure whose index is @idx.
+ * edac_mc_find() - Search for a mem_ctl_info structure whose index is @idx.
*
* @idx: index to be seek
*
- * If found, return a pointer to the structure.
- * Else return NULL.
+ * .. note:: Caller must hold mem_ctls_mutex.
*
- * Caller must hold mem_ctls_mutex.
+ * Returns: If found, return a pointer to the structure; %NULL otherwise.
*/
extern struct mem_ctl_info *edac_mc_find(int idx);
/**
- * find_mci_by_dev
+ * find_mci_by_dev() - Scan list of controllers looking for the one that
+ * manages the @dev device.
*
- * scan list of controllers looking for the one that manages
- * the 'dev' device
* @dev: pointer to a struct device related with the MCI
+ *
+ * Returns: on success, returns a pointer to struct &mem_ctl_info;
+ * %NULL otherwise.
*/
extern struct mem_ctl_info *find_mci_by_dev(struct device *dev);
/**
- * edac_mc_del_mc: Remove sysfs entries for specified mci structure and
- * remove mci structure from global list
+ * edac_mc_del_mc() - Remove sysfs entries for mci structure associated with
+ * @dev and remove mci structure from global list.
*
* @dev: Pointer to struct &device representing mci structure to remove.
*
- * Returns: pointer to removed mci structure, or NULL if device not found.
+ * Returns: pointer to removed mci structure, or %NULL if device not found.
*/
extern struct mem_ctl_info *edac_mc_del_mc(struct device *dev);
+
+/**
+ * edac_mc_find_csrow_by_page() - Ancillary routine to identify what csrow
+ * contains a mem
[PATCH v2 02/19] edac: edac_core.h: remove prototype for edac_pci_reset_delay_period()
This function doesn't exist. So, remove its prototype. Signed-off-by: Mauro Carvalho Chehab --- drivers/edac/edac_core.h | 3 --- 1 file changed, 3 deletions(-) diff --git a/drivers/edac/edac_core.h b/drivers/edac/edac_core.h index 58d66da56486..1723f3643e75 100644 --- a/drivers/edac/edac_core.h +++ b/drivers/edac/edac_core.h @@ -493,9 +493,6 @@ extern struct edac_pci_ctl_info *edac_pci_alloc_ctl_info(unsigned int sz_pvt, extern void edac_pci_free_ctl_info(struct edac_pci_ctl_info *pci); -extern void edac_pci_reset_delay_period(struct edac_pci_ctl_info *pci, - unsigned long value); - extern int edac_pci_alloc_index(void); extern int edac_pci_add_device(struct edac_pci_ctl_info *pci, int edac_idx); extern struct edac_pci_ctl_info *edac_pci_del_device(struct device *dev); -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 01/19] edac: edac_core.h: get rid of unused kobj_complete
This element of struct edac_pci_ctl_info is never used. So,
get rid of it.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_core.h | 1 -
1 file changed, 1 deletion(-)
diff --git a/drivers/edac/edac_core.h b/drivers/edac/edac_core.h
index 4861542163d7..58d66da56486 100644
--- a/drivers/edac/edac_core.h
+++ b/drivers/edac/edac_core.h
@@ -380,7 +380,6 @@ struct edac_pci_ctl_info {
* device this structure controls
*/
struct kobject kobj;
- struct completion kobj_complete;
};
#define to_edac_pci_ctl_work(w) \
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 04/19] edac.txt: convert EDAC documentation to ReST
Converts the EDAC driver subsystem documentation to ReST: - Put paragraph titles in lower case; - Add code blocks where needed; - Convert tables to ReST markup; - Mark filesystem and module names as verbatim; - Adjust document to be properly displayed in html. Signed-off-by: Mauro Carvalho Chehab --- Documentation/edac.txt | 551 ++--- 1 file changed, 295 insertions(+), 256 deletions(-) diff --git a/Documentation/edac.txt b/Documentation/edac.txt index 502988524519..316456ba2e0a 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -1,29 +1,34 @@ +.. include:: + += EDAC - Error Detection And Correction = -"bluesmoke" was the name for this device driver when it -was "out-of-tree" and maintained at sourceforge.net - -bluesmoke.sourceforge.net. That site is mostly archaic now and can be -used only for historical purposes. +.. note:: -When the subsystem was pushed into 2.6.16 for the first time, it was -renamed to 'EDAC'. + "bluesmoke" was the name for this device driver when it + was "out-of-tree" and maintained at http://bluesmoke.sourceforge.net. + That site is mostly archaic now and can be used only for historical + purposes. -PURPOSE + When the subsystem was pushed into 2.6.16 for the first time, it was + renamed to ``EDAC``. + +Purpose --- -The 'edac' kernel module's goal is to detect and report hardware errors +The ``edac`` kernel module's goal is to detect and report hardware errors that occur within the computer system running under linux. -MEMORY +Memory -- Memory Correctable Errors (CE) and Uncorrectable Errors (UE) are the primary errors being harvested. These types of errors are harvested by -the 'edac_mc' device. +the ``edac_mc`` device. Detecting CE events, then harvesting those events and reporting them, -*can* but must not necessarily be a predictor of future UE events. With +**can** but must not necessarily be a predictor of future UE events. With CE events only, the system can and will continue to operate as no data has been damaged yet. @@ -31,10 +36,10 @@ However, preventive maintenance and proactive part replacement of memory DIMMs exhibiting CEs can reduce the likelihood of the dreaded UE events and system panics. -OTHER HARDWARE ELEMENTS +Other hardware elements --- -A new feature for EDAC, the edac_device class of device, was added in +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 @@ -48,14 +53,14 @@ reports it, then a edac_device device probably can be constructed to harvest and present that to userspace. -PCI BUS SCANNING +PCI bus scanning In addition, PCI devices are scanned for PCI Bus Parity and SERR Errors in order to determine if errors are occurring during 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 +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 @@ -63,62 +68,64 @@ can "float" giving false positives. 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 -scanning is skipped for that device. The attribute is: +scanning is skipped for that device. The attribute is:: broken_parity_status -and is located in /sys/devices/pci/:XX:YY.Z directories for +and is located in ``/sys/devices/pci/:XX:YY.Z`` directories for PCI devices. -VERSIONING +Versioning -- -EDAC is composed of a "core" module (edac_core.ko) and several Memory +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 +``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 +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 +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
[PATCH v2 07/19] edac.txt: Improve documentation, adding RAS introduction
The edac.txt assumes that the reader has already deep knowledge on RAS features. However, this may not be the case. So, add an introduction chapter explaining the main concepts that are used by the EDAC subsystem and by other RAS drivers within the Kernel. Signed-off-by: Mauro Carvalho Chehab --- Documentation/edac.txt | 281 ++--- 1 file changed, 245 insertions(+), 36 deletions(-) diff --git a/Documentation/edac.txt b/Documentation/edac.txt index 0c9161c9ed7a..2f8706bae5a4 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -1,18 +1,218 @@ .. include:: -= + +Reliability, Availability and Serviceability + + +RAS concepts + + +Reliability, Availability and Serviceability (RAS) is a concept used on +servers meant to measure their robusteness. + +Reliability + is the probability that a system will produce correct outputs. + + * Generally measured as Mean Time Between Failures (MTBF) + * Enhanced by features that help to avoid, detect and repair hardware faults + +Availability + is the probability that a system is operational at a given time + + * Generally measured as a percentage of downtime per a period of time + * Often uses mechanisms to detect and correct hardware faults in +runtime; + +Serviceability (or maintainability) + is the simplicity and speed with which a system can be repaired or + maintained + + * Generally measured on Mean Time Between Repair (MTBR) + +Improving RAS +- + +In order to reduce systems downtime, a system should be capable of detecting +hardware errors, and, when possible correcting them in runtime. It should +also provide mechanisms to detect hardware degradation, in order to warn +the system administrator to take the action of replacing a component before +it causes data loss or system downtime. + +Among the monitoring measures, the most usual ones include: + +* CPU – detect errors at instruction execution and at L1/L2/L3 caches; +* Memory – add error correction logic (ECC) to detect and correct errors; +* I/O – add CRC checksums for tranfered data; +* Storage – RAID, journal file systems, checksums, + Self-Monitoring, Analysis and Reporting Technology (SMART). + +By monitoring the number of occurrences of error detections, it is possible +to identify if the probability of hardware errors is increasing, and, on such +case, do a preventive maintainance to replace a degrated component while +those errors are correctable. + +Types of errors +--- + +Most mechanisms used on modern systems use use technologies like Hamming +Codes that allow error correction when the number of errors on a bit packet +is below a threshold. If the number of errors is above, those mechanisms +can indicate with a high degree of confidence that an error happened, but +they can't correct. + +Also, sometimes an error occur on a component that it is not used. For +example, a part of the memory that it is not currently allocated. + +That defines some categories of errors: + +* **Correctable Error (CE)** - the error detection mechanism detected and + corrected the error. Such errors are usually not fatal, although some + Kernel mechanisms allow the system administrator to consider them as fatal. + +* **Uncorrected Error (UE)** - the amount of errors happened above the error + correction threshold, and the system was unable to auto-correct. + +* **Fatal Error** - when an UE error happens on a critical component of the + system (for example, a piece of the Kernel got corrupted by an UE), the + only reliable way to avoid data corruption is to hang or reboot the machine. + +* **Non-fatal Error** - when an UE error happens on an unused component, + like a CPU in power down state or an unused memory bank, the system may + still run, eventually replacing the affected hardware by a hot spare, + if available. + + Also, when an error happens on an userspace process, it is also possible to + kill such process and let userspace restart it. + +The mechanism for handling non-fatal errors is usually complex and may +require the help of some userspace application, in order to apply the +policy desired by the system administrator. + +Identifying a bad hardware component + + +Just detecting a hardware flaw is usually not enough, as the system needs +to pinpoint to the minimal replaceable unit (MRU) that should be exchanged +to make the hardware reliable again. + +So, it requires not only error logging facilities, but also mechanisms that +will translate the error message to the silkscreen or component label for +the MRU. + +Typically, it is very complex for memory, as modern CPUs interlace memory +from different memory modules, in order to provide a better performance. The +DMI BIOS usually have a list of memory module labels, with can be obtained
[PATCH v2 16/19] edac: adjust docs location at MAINTAINERS and 00-INDEX
Update MAINTAINERS and 00-INDEX to reflect the location of edac.rst and ras.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 4 ++-- MAINTAINERS| 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 903ebc494f29..9497119fc10d 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -170,8 +170,8 @@ dynamic-debug-howto.txt - how to use the dynamic debug (dyndbg) feature. early-userspace/ - info about initramfs, klibc, and userspace early during boot. -edac.txt - - information on EDAC - Error Detection And Correction +admin-guide/ras.rst + - information on Reliability, Availability and Serviceability efi-stub.txt - How to use the EFI boot stub to bypass GRUB or elilo on EFI systems. eisa.txt diff --git a/MAINTAINERS b/MAINTAINERS index 69820b75b2e0..60e7b61c8605 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4475,7 +4475,8 @@ L:linux-e...@vger.kernel.org T: git git://git.kernel.org/pub/scm/linux/kernel/git/bp/bp.git for-next T: git git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-edac.git linux_next S: Supported -F: Documentation/edac.txt +F: Documentation/admin-guide/ras.rst +F: Documentation/driver-api/edac.rst F: drivers/edac/ F: include/linux/edac.h -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 09/19] edac: move EDAC PCI definitions to drivers/edac/edac_pci.h
The edac_core.h header contain data structures and function
definitions for the 3 parts of EDAC: MC, PCI and device.
Let's move the PCI ones to a separate header file, as part
of a header reorganization.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_core.h | 145 +--
drivers/edac/edac_pci.c | 19 ++---
drivers/edac/edac_pci.h | 173 ++
drivers/edac/edac_pci_sysfs.c | 2 +-
include/linux/edac.h | 2 +
5 files changed, 185 insertions(+), 156 deletions(-)
create mode 100644 drivers/edac/edac_pci.h
diff --git a/drivers/edac/edac_core.h b/drivers/edac/edac_core.h
index 1723f3643e75..8c7cca2d6e40 100644
--- a/drivers/edac/edac_core.h
+++ b/drivers/edac/edac_core.h
@@ -35,8 +35,7 @@
#include
#include
-#define EDAC_DEVICE_NAME_LEN 31
-#define EDAC_ATTRIB_VALUE_LEN 15
+#include "edac_pci.h"
#if PAGE_SHIFT < 20
#define PAGES_TO_MiB(pages)((pages) >> (20 - PAGE_SHIFT))
@@ -321,128 +320,6 @@ extern struct edac_device_ctl_info
*edac_device_alloc_ctl_info(
extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
-#ifdef CONFIG_PCI
-
-struct edac_pci_counter {
- atomic_t pe_count;
- atomic_t npe_count;
-};
-
-/*
- * Abstract edac_pci control info structure
- *
- */
-struct edac_pci_ctl_info {
- /* for global list of edac_pci_ctl_info structs */
- struct list_head link;
-
- int pci_idx;
-
- struct bus_type *edac_subsys; /* pointer to subsystem */
-
- /* the internal state of this controller instance */
- int op_state;
- /* work struct for this instance */
- struct delayed_work work;
-
- /* pointer to edac polling checking routine:
-* If NOT NULL: points to polling check routine
-* If NULL: Then assumes INTERRUPT operation, where
-* MC driver will receive events
-*/
- void (*edac_check) (struct edac_pci_ctl_info * edac_dev);
-
- struct device *dev; /* pointer to device structure */
-
- const char *mod_name; /* module name */
- const char *ctl_name; /* edac controller name */
- const char *dev_name; /* pci/platform/etc... name */
-
- void *pvt_info; /* pointer to 'private driver' info */
-
- unsigned long start_time; /* edac_pci load start time (jiffies) */
-
- struct completion complete;
-
- /* sysfs top name under 'edac' directory
-* and instance name:
-* cpu/cpu0/...
-* cpu/cpu1/...
-* cpu/cpu2/...
-* ...
-*/
- char name[EDAC_DEVICE_NAME_LEN + 1];
-
- /* Event counters for the this whole EDAC Device */
- struct edac_pci_counter counters;
-
- /* edac sysfs device control for the 'name'
-* device this structure controls
-*/
- struct kobject kobj;
-};
-
-#define to_edac_pci_ctl_work(w) \
- container_of(w, struct edac_pci_ctl_info,work)
-
-/* write all or some bits in a byte-register*/
-static inline void pci_write_bits8(struct pci_dev *pdev, int offset, u8 value,
- u8 mask)
-{
- if (mask != 0xff) {
- u8 buf;
-
- pci_read_config_byte(pdev, offset, &buf);
- value &= mask;
- buf &= ~mask;
- value |= buf;
- }
-
- pci_write_config_byte(pdev, offset, value);
-}
-
-/* write all or some bits in a word-register*/
-static inline void pci_write_bits16(struct pci_dev *pdev, int offset,
- u16 value, u16 mask)
-{
- if (mask != 0x) {
- u16 buf;
-
- pci_read_config_word(pdev, offset, &buf);
- value &= mask;
- buf &= ~mask;
- value |= buf;
- }
-
- pci_write_config_word(pdev, offset, value);
-}
-
-/*
- * pci_write_bits32
- *
- * edac local routine to do pci_write_config_dword, but adds
- * a mask parameter. If mask is all ones, ignore the mask.
- * Otherwise utilize the mask to isolate specified bits
- *
- * write all or some bits in a dword-register
- */
-static inline void pci_write_bits32(struct pci_dev *pdev, int offset,
- u32 value, u32 mask)
-{
- if (mask != 0x) {
- u32 buf;
-
- pci_read_config_dword(pdev, offset, &buf);
- value &= mask;
- buf &= ~mask;
- value |= buf;
- }
-
- pci_write_config_dword(pdev, offset, value);
-}
-
-#endif /* CONFIG_PCI */
-
struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
unsigned n_layers,
struct edac_mc_layer *layers,
@@ -486,26 +363,6 @@ extern int edac_device_alloc_index(void);
extern const char *edac_layer_name[];
/*
- * edac_pci APIs
- */
-exter
[PATCH v2 13/19] edac: move documentation from edac_pci*.c to edac_pci.h
Several functions are documented at edac_pci.c and edac_pci_sysfs.c.
As we'll be including edac_pci.h at drivers-api book, move those,
in order for the kernel-doc markups be part of the API
documentation book.
As several of those kernel-doc macros are not in the right format,
fix them.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_pci.c | 65
drivers/edac/edac_pci.h | 98 +++
drivers/edac/edac_pci_sysfs.c | 11 -
3 files changed, 98 insertions(+), 76 deletions(-)
diff --git a/drivers/edac/edac_pci.c b/drivers/edac/edac_pci.c
index 02a0af4f53b3..4e9d5632041a 100644
--- a/drivers/edac/edac_pci.c
+++ b/drivers/edac/edac_pci.c
@@ -28,13 +28,6 @@ static DEFINE_MUTEX(edac_pci_ctls_mutex);
static LIST_HEAD(edac_pci_list);
static atomic_t pci_indexes = ATOMIC_INIT(0);
-/*
- * edac_pci_alloc_ctl_info
- *
- * The alloc() function for the 'edac_pci' control info
- * structure. The chip driver will allocate one of these for each
- * edac_pci it is going to control/register with the EDAC CORE.
- */
struct edac_pci_ctl_info *edac_pci_alloc_ctl_info(unsigned int sz_pvt,
const char *edac_pci_name)
{
@@ -65,16 +58,6 @@ struct edac_pci_ctl_info *edac_pci_alloc_ctl_info(unsigned
int sz_pvt,
}
EXPORT_SYMBOL_GPL(edac_pci_alloc_ctl_info);
-/*
- * edac_pci_free_ctl_info()
- *
- * Last action on the pci control structure.
- *
- * call the remove sysfs information, which will unregister
- * this control struct's kobj. When that kobj's ref count
- * goes to zero, its release function will be call and then
- * kfree() the memory.
- */
void edac_pci_free_ctl_info(struct edac_pci_ctl_info *pci)
{
edac_dbg(1, "\n");
@@ -212,31 +195,12 @@ static void edac_pci_workq_function(struct work_struct
*work_req)
mutex_unlock(&edac_pci_ctls_mutex);
}
-/*
- * edac_pci_alloc_index: Allocate a unique PCI index number
- *
- * Return:
- * allocated index number
- *
- */
int edac_pci_alloc_index(void)
{
return atomic_inc_return(&pci_indexes) - 1;
}
EXPORT_SYMBOL_GPL(edac_pci_alloc_index);
-/*
- * edac_pci_add_device: Insert the 'edac_dev' structure into the
- * edac_pci global list and create sysfs entries associated with
- * edac_pci structure.
- * @pci: pointer to the edac_device structure to be added to the list
- * @edac_idx: A unique numeric identifier to be assigned to the
- * 'edac_pci' structure.
- *
- * Return:
- * 0 Success
- * !0 Failure
- */
int edac_pci_add_device(struct edac_pci_ctl_info *pci, int edac_idx)
{
edac_dbg(0, "\n");
@@ -282,19 +246,6 @@ int edac_pci_add_device(struct edac_pci_ctl_info *pci, int
edac_idx)
}
EXPORT_SYMBOL_GPL(edac_pci_add_device);
-/*
- * edac_pci_del_device()
- * Remove sysfs entries for specified edac_pci structure and
- * then remove edac_pci structure from global list
- *
- * @dev:
- * Pointer to 'struct device' representing edac_pci structure
- * to remove
- *
- * Return:
- * Pointer to removed edac_pci structure,
- * or NULL if device not found
- */
struct edac_pci_ctl_info *edac_pci_del_device(struct device *dev)
{
struct edac_pci_ctl_info *pci;
@@ -348,17 +299,6 @@ struct edac_pci_gen_data {
int edac_idx;
};
-/*
- * edac_pci_create_generic_ctl
- *
- * A generic constructor for a PCI parity polling device
- * Some systems have more than one domain of PCI busses.
- * For systems with one domain, then this API will
- * provide for a generic poller.
- *
- * This routine calls the edac_pci_alloc_ctl_info() for
- * the generic device, with default values
- */
struct edac_pci_ctl_info *edac_pci_create_generic_ctl(struct device *dev,
const char *mod_name)
{
@@ -391,11 +331,6 @@ struct edac_pci_ctl_info
*edac_pci_create_generic_ctl(struct device *dev,
}
EXPORT_SYMBOL_GPL(edac_pci_create_generic_ctl);
-/*
- * edac_pci_release_generic_ctl
- *
- * The release function of a generic EDAC PCI polling device
- */
void edac_pci_release_generic_ctl(struct edac_pci_ctl_info *pci)
{
edac_dbg(0, "pci mod=%s\n", pci->mod_name);
diff --git a/drivers/edac/edac_pci.h b/drivers/edac/edac_pci.h
index 9da0c6fb0634..5175f5724cfa 100644
--- a/drivers/edac/edac_pci.h
+++ b/drivers/edac/edac_pci.h
@@ -153,21 +153,119 @@ static inline void pci_write_bits32(struct pci_dev
*pdev, int offset,
#endif /* CONFIG_PCI */
+/*
+ * edac_pci APIs
+ */
+
+/**
+ * edac_pci_alloc_ctl_info:
+ * The alloc() function for the 'edac_pci' control info
+ * structure.
+ *
+ * @sz_pvt: size of the private info at struct &edac_pci_ctl_info
+ * @edac_pci_name: name of the PCI device
+ *
+ * The chip driver will allocate one of these for each
+ * edac_pci it is going to control/register with the EDAC CORE.
+ *
+ * Returns:
[PATCH v2 08/19] docs-rst: admin-guide: add documentation for EDAC
EDAC is part of the Kernel's RAS facilities, with is useful for
system admins to detect errors. So, add it to the admin's guide.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/admin-guide/index.rst | 2 +-
Documentation/{edac.txt => admin-guide/ras.rst} | 0
2 files changed, 1 insertion(+), 1 deletion(-)
rename Documentation/{edac.txt => admin-guide/ras.rst} (100%)
diff --git a/Documentation/admin-guide/index.rst
b/Documentation/admin-guide/index.rst
index fb779e67097b..c4c87bbd19a6 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -32,6 +32,7 @@ Contents:
java
bad-memory
basic-profiling
+ ras
.. only:: subproject and html
@@ -39,4 +40,3 @@ Contents:
===
* :ref:`genindex`
-
diff --git a/Documentation/edac.txt b/Documentation/admin-guide/ras.rst
similarity index 100%
rename from Documentation/edac.txt
rename to Documentation/admin-guide/ras.rst
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 10/19] edac: move EDAC device definitions to drivers/edac/edac_device.h
The edac_core.h header contain data structures and function
definitions for both EDAC MC and EDAC device.
Let's move the devices ones to a separate header file, as part
of a header reorganization.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_core.h | 238 +-
drivers/edac/edac_device.c | 21 ++-
drivers/edac/edac_device.h | 269 +++
drivers/edac/edac_device_sysfs.c | 4 +-
4 files changed, 281 insertions(+), 251 deletions(-)
create mode 100644 drivers/edac/edac_device.h
diff --git a/drivers/edac/edac_core.h b/drivers/edac/edac_core.h
index 8c7cca2d6e40..3e11d9d85462 100644
--- a/drivers/edac/edac_core.h
+++ b/drivers/edac/edac_core.h
@@ -36,6 +36,7 @@
#include
#include "edac_pci.h"
+#include "edac_device.h"
#if PAGE_SHIFT < 20
#define PAGES_TO_MiB(pages)((pages) >> (20 - PAGE_SHIFT))
@@ -95,231 +96,6 @@ do {
\
#define to_mci(k) container_of(k, struct mem_ctl_info, dev)
-/*
- * The following are the structures to provide for a generic
- * or abstract 'edac_device'. This set of structures and the
- * code that implements the APIs for the same, provide for
- * registering EDAC type devices which are NOT standard memory.
- *
- * CPU caches (L1 and L2)
- * DMA engines
- * Core CPU switches
- * Fabric switch units
- * PCIe interface controllers
- * other EDAC/ECC type devices that can be monitored for
- * errors, etc.
- *
- * It allows for a 2 level set of hierarchy. For example:
- *
- * cache could be composed of L1, L2 and L3 levels of cache.
- * Each CPU core would have its own L1 cache, while sharing
- * L2 and maybe L3 caches.
- *
- * View them arranged, via the sysfs presentation:
- * /sys/devices/system/edac/..
- *
- * mc/
- * cpu/cpu0/..
- * /L1-cache/ce_count
- * /ue_count
- * /L2-cache/ce_count
- * /ue_count
- * cpu/cpu1/..
- * /L1-cache/ce_count
- * /ue_count
- * /L2-cache/ce_count
- * /ue_count
- * ...
- *
- * the L1 and L2 directories would be "edac_device_block's"
- */
-
-struct edac_device_counter {
- u32 ue_count;
- u32 ce_count;
-};
-
-/* forward reference */
-struct edac_device_ctl_info;
-struct edac_device_block;
-
-/* edac_dev_sysfs_attribute structure
- * used for driver sysfs attributes in mem_ctl_info
- * for extra controls and attributes:
- * like high level error Injection controls
- */
-struct edac_dev_sysfs_attribute {
- struct attribute attr;
- ssize_t (*show)(struct edac_device_ctl_info *, char *);
- ssize_t (*store)(struct edac_device_ctl_info *, const char *, size_t);
-};
-
-/* edac_dev_sysfs_block_attribute structure
- *
- * used in leaf 'block' nodes for adding controls/attributes
- *
- * each block in each instance of the containing control structure
- * can have an array of the following. The show and store functions
- * will be filled in with the show/store function in the
- * low level driver.
- *
- * The 'value' field will be the actual value field used for
- * counting
- */
-struct edac_dev_sysfs_block_attribute {
- struct attribute attr;
- ssize_t (*show)(struct kobject *, struct attribute *, char *);
- ssize_t (*store)(struct kobject *, struct attribute *,
- const char *, size_t);
- struct edac_device_block *block;
-
- unsigned int value;
-};
-
-/* device block control structure */
-struct edac_device_block {
- struct edac_device_instance *instance; /* Up Pointer */
- char name[EDAC_DEVICE_NAME_LEN + 1];
-
- struct edac_device_counter counters;/* basic UE and CE counters */
-
- int nr_attribs; /* how many attributes */
-
- /* this block's attributes, could be NULL */
- struct edac_dev_sysfs_block_attribute *block_attributes;
-
- /* edac sysfs device control */
- struct kobject kobj;
-};
-
-/* device instance control structure */
-struct edac_device_instance {
- struct edac_device_ctl_info *ctl; /* Up pointer */
- char name[EDAC_DEVICE_NAME_LEN + 4];
-
- struct edac_device_counter counters;/* instance counters */
-
- u32 nr_blocks; /* how many blocks */
- struct edac_device_block *blocks; /* block array */
-
- /* edac sysfs device control */
- struct kobject kobj;
-};
-
-
-/*
- * Abstract edac_device control info structure
- *
- */
-struct edac_device_ctl_info {
- /* for global list of edac_device_ctl_info structs */
- struct list_head link;
-
- struct module *owner; /* Module owner of this control struct */
-
- int dev_idx;
-
- /* Per instance controls for this edac_device */
- int log_ue; /* boolean f
[PATCH v2 03/19] edac.txt: add a section explaining the dimmX and rankX directories
Documentation for those are missing at the EDAC description. I guess we end by moving such descriptions in the past to the ABI document (or only added it there), but it means that the EDAC documentation is incomplete. So, add it there. Signed-off-by: Mauro Carvalho Chehab --- Documentation/edac.txt | 120 + 1 file changed, 120 insertions(+) diff --git a/Documentation/edac.txt b/Documentation/edac.txt index f89cfd85ae13..502988524519 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -208,6 +208,126 @@ For a description of the sysfs API, please see: Documentation/ABI/testing/sysfs-devices-edac +``dimmX`` or ``rankX`` directories +-- + +The recommended way to use the EDAC subsystem is to look at the information +provided by the ``dimmX`` or ``rankX`` directories [#f5]_. + +A typical EDAC system has the following structure under +``/sys/devices/system/edac/``\ [#f6]_:: + + /sys/devices/system/edac/ + ├── mc + │ ├── mc0 + │ │ ├── ce_count + │ │ ├── ce_noinfo_count + │ │ ├── dimm0 + │ │ │ ├── dimm_dev_type + │ │ │ ├── dimm_edac_mode + │ │ │ ├── dimm_label + │ │ │ ├── dimm_location + │ │ │ ├── dimm_mem_type + │ │ │ ├── size + │ │ │ └── uevent + │ │ ├── max_location + │ │ ├── mc_name + │ │ ├── reset_counters + │ │ ├── seconds_since_reset + │ │ ├── size_mb + │ │ ├── ue_count + │ │ ├── ue_noinfo_count + │ │ └── uevent + │ ├── mc1 + │ │ ├── ce_count + │ │ ├── ce_noinfo_count + │ │ ├── dimm0 + │ │ │ ├── dimm_dev_type + │ │ │ ├── dimm_edac_mode + │ │ │ ├── dimm_label + │ │ │ ├── dimm_location + │ │ │ ├── dimm_mem_type + │ │ │ ├── size + │ │ │ └── uevent + │ │ ├── max_location + │ │ ├── mc_name + │ │ ├── reset_counters + │ │ ├── seconds_since_reset + │ │ ├── size_mb + │ │ ├── ue_count + │ │ ├── ue_noinfo_count + │ │ └── uevent + │ └── uevent + └── uevent + +In the ``dimmX`` directories are EDAC control and attribute files for +this ``X`` memory module: + +- ``size`` - Total memory managed by this csrow attribute file + + This attribute file displays, in count of megabytes, the memory + that this csrow contains. + +- ``dimm_dev_type`` - Device type attribute file + + This attribute file will display what type of DRAM device is + being utilized on this DIMM. + Examples: + + - x1 + - x2 + - x4 + - x8 + +- ``dimm_edac_mode`` - EDAC Mode of operation attribute file + + This attribute file will display what type of Error detection + and correction is being utilized. + +- ``dimm_label`` - memory module label control file + + 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. + +- ``dimm_location`` - location of the memory module + + The location can have up to 3 levels, and describe how the + memory controller identifies the location of a memory module. + Depending on the type of memory and memory controller, it + can be: + + - *csrow* and *channel* - used when the memory controller + doesn't identify a single DIMM - e. g. in ``rankX`` dir; + - *branch*, *channel*, *slot* - typically used on FB-DIMM memory + controllers; + - *channel*, *slot* - used on Nehalem and newer Intel drivers. + +- ``dimm_mem_type`` - Memory Type attribute file + + 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 + +.. [#f5] On some systems, the memory controller doesn't have any logic + to identify the memory module. On such systems, the directory is called ``rankX`` and works on a similar way as the ``csrowX`` directories. + On modern Intel memory controllers, the memory controller identifies the + memory modules directly. On such systems, the directory is called ``dimmX``. + +.. [#f6] There are also some ``power
[PATCH v2 05/19] edac.txt: remove info that the Nehalem EDAC is experimental
This driver has been there for almost 3 years, without any conceptual changes. So, it is not experimental anymore, and won't likely have any changes at the API or on log outputs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/edac.txt | 4 1 file changed, 4 deletions(-) diff --git a/Documentation/edac.txt b/Documentation/edac.txt index 316456ba2e0a..fba193044af0 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -744,10 +744,6 @@ http://bluesmoke.sourceforge.net project site for EDAC. Nehalem Usage of EDAC APIs -- -This chapter documents some EXPERIMENTAL mappings for EDAC API to handle -Nehalem EDAC driver. They will likely be changed on future versions -of the driver. - Due to the way Nehalem exports Memory Controller data, some adjustments were done at i7core_edac driver. This chapter will cover those differences -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 11/19] edac: rename edac_core.h to edac_mc.h
Now, all left at edac_core.h are at drivers/edac/edac_mc.c,
so rename it to edac_mc.h.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/altera_edac.c | 1 -
drivers/edac/amd64_edac.h | 2 +-
drivers/edac/amd76x_edac.c | 2 +-
drivers/edac/amd8111_edac.c | 1 -
drivers/edac/amd8131_edac.c | 1 -
drivers/edac/cell_edac.c| 2 +-
drivers/edac/cpc925_edac.c | 1 -
drivers/edac/e752x_edac.c | 2 +-
drivers/edac/e7xxx_edac.c | 2 +-
drivers/edac/edac_mc.c | 2 +-
drivers/edac/{edac_core.h => edac_mc.h} | 11 ---
drivers/edac/edac_mc_sysfs.c| 2 +-
drivers/edac/edac_module.c | 2 +-
drivers/edac/edac_module.h | 4 +++-
drivers/edac/fsl_ddr_edac.c | 1 -
drivers/edac/ghes_edac.c| 2 +-
drivers/edac/highbank_l2_edac.c | 1 -
drivers/edac/highbank_mc_edac.c | 1 -
drivers/edac/i3000_edac.c | 2 +-
drivers/edac/i3200_edac.c | 2 +-
drivers/edac/i5000_edac.c | 2 +-
drivers/edac/i5100_edac.c | 1 -
drivers/edac/i5400_edac.c | 2 +-
drivers/edac/i7300_edac.c | 2 +-
drivers/edac/i7core_edac.c | 2 +-
drivers/edac/i82443bxgx_edac.c | 2 +-
drivers/edac/i82860_edac.c | 2 +-
drivers/edac/i82875p_edac.c | 2 +-
drivers/edac/i82975x_edac.c | 2 +-
drivers/edac/ie31200_edac.c | 2 +-
drivers/edac/layerscape_edac.c | 2 +-
drivers/edac/mpc85xx_edac.c | 1 -
drivers/edac/mv64x60_edac.c | 1 -
drivers/edac/octeon_edac-l2c.c | 1 -
drivers/edac/octeon_edac-lmc.c | 1 -
drivers/edac/octeon_edac-pc.c | 1 -
drivers/edac/octeon_edac-pci.c | 1 -
drivers/edac/pasemi_edac.c | 2 +-
drivers/edac/ppc4xx_edac.c | 2 +-
drivers/edac/r82600_edac.c | 2 +-
drivers/edac/sb_edac.c | 2 +-
drivers/edac/skx_edac.c | 2 +-
drivers/edac/synopsys_edac.c| 2 +-
drivers/edac/tile_edac.c| 2 +-
drivers/edac/x38_edac.c | 2 +-
drivers/edac/xgene_edac.c | 1 -
46 files changed, 36 insertions(+), 52 deletions(-)
rename drivers/edac/{edac_core.h => edac_mc.h} (95%)
diff --git a/drivers/edac/altera_edac.c b/drivers/edac/altera_edac.c
index 58d3e2b39b5b..798e9440d338 100644
--- a/drivers/edac/altera_edac.c
+++ b/drivers/edac/altera_edac.c
@@ -35,7 +35,6 @@
#include
#include "altera_edac.h"
-#include "edac_core.h"
#include "edac_module.h"
#define EDAC_MOD_STR "altera_edac"
diff --git a/drivers/edac/amd64_edac.h b/drivers/edac/amd64_edac.h
index c08870479054..35e1f9e14777 100644
--- a/drivers/edac/amd64_edac.h
+++ b/drivers/edac/amd64_edac.h
@@ -17,7 +17,7 @@
#include
#include
#include
-#include "edac_core.h"
+#include "edac_module.h"
#include "mce_amd.h"
#define amd64_debug(fmt, arg...) \
diff --git a/drivers/edac/amd76x_edac.c b/drivers/edac/amd76x_edac.c
index 3a501b530e11..a7450275ad28 100644
--- a/drivers/edac/amd76x_edac.c
+++ b/drivers/edac/amd76x_edac.c
@@ -17,7 +17,7 @@
#include
#include
#include
-#include "edac_core.h"
+#include "edac_module.h"
#define AMD76X_REVISION" Ver: 2.0.2"
#define EDAC_MOD_STR "amd76x_edac"
diff --git a/drivers/edac/amd8111_edac.c b/drivers/edac/amd8111_edac.c
index 2b63f7c2d6d2..b5786cfded3a 100644
--- a/drivers/edac/amd8111_edac.c
+++ b/drivers/edac/amd8111_edac.c
@@ -29,7 +29,6 @@
#include
#include
-#include "edac_core.h"
#include "edac_module.h"
#include "amd8111_edac.h"
diff --git a/drivers/edac/amd8131_edac.c b/drivers/edac/amd8131_edac.c
index a5c680561c73..8851c33d7d24 100644
--- a/drivers/edac/amd8131_edac.c
+++ b/drivers/edac/amd8131_edac.c
@@ -29,7 +29,6 @@
#include
#include
-#include "edac_core.h"
#include "edac_module.h"
#include "amd8131_edac.h"
diff --git a/drivers/edac/cell_edac.c b/drivers/edac/cell_edac.c
index a9259b069dcd..bc1f3416400e 100644
--- a/drivers/edac/cell_edac.c
+++ b/drivers/edac/cell_edac.c
@@ -19,7 +19,7 @@
#include
#include
-#include "edac_core.h"
+#include "edac_module.h"
struct cell_edac_priv
{
diff --git a/drivers/edac/cpc925_edac.c b/drivers/edac/cpc925_edac.c
index 682288ced4ac..837b62c4993d 100644
--- a/drivers/edac/cpc925_edac.c
+++ b/drivers/edac/cpc925_edac.c
@@ -27,7 +27,6 @@
#include
#include
-#include "edac_core.h"
#include "edac_module.h"
#define CPC925_EDAC_REVISION " Ver: 1.0.0"
diff --git a/drivers/edac/e752x_edac.c b/drivers/edac/e752x_edac.c
index b2d71388172b..1a352cae1f52 100644
--- a/drivers/edac/e752x_edac.c
+++ b/drivers/edac/e752x_edac.c
@@ -24,7 +24,7 @@
#include
#include
#include
-#include "edac_core.h"
+#include "edac_module.h"
#define E7
[PATCH v2 00/19] Put the EDAC documentation at the Sphinx books
This patch series convert the Documentation/edac.txt book to ReST and
add an EDAC documentation to the driver-api book.
The first 2 patches on this series are just cleanups to the headers,
removing two unused stuff and using -EINVAL instead of -1 on
one of the functions.
The next 6 patches convert Documentation/edac.txt to ReST, improve
it and rename to ras.rst, moving it to the admin-guide.
The remaining patches move existing documentation to edac_mc.h,
edac_device.h and edac_pci.h, improving the documentation provided
on them in order to be properly parsed by kernel-doc script.
Regards,
Mauro
- version 2:
- don't change the return code for edac_mc_find_csrow_by_page();
- split edac_core.h into 3 headers, one per each EDAC API
(memory controller, PCI and device);
- add linux/include/edac.h at the driver-api book.
NOTE: Originally, I was wanting to break the edac_core.h into 6 headers,
adding one header also for the edac_*_sysfs.c files. However, at the
end, it will be too messy, as the sysfs data structures should be embedded
at the structures inside edac_mc.h, edac_pci.h and edac_device.h. I might
have added only the function calls on at the edac_*_sysfs.h, but that would
mean to include just two functions for each.
Mauro Carvalho Chehab (19):
edac: edac_core.h: get rid of unused kobj_complete
edac: edac_core.h: remove prototype for edac_pci_reset_delay_period()
edac.txt: add a section explaining the dimmX and rankX directories
edac.txt: convert EDAC documentation to ReST
edac.txt: remove info that the Nehalem EDAC is experimental
edac.txt: update information about newer Intel CPUs
edac.txt: Improve documentation, adding RAS introduction
docs-rst: admin-guide: add documentation for EDAC
edac: move EDAC PCI definitions to drivers/edac/edac_pci.h
edac: move EDAC device definitions to drivers/edac/edac_device.h
edac: rename edac_core.h to edac_mc.h
edac: move documentation from edac_device to edac_core.h
edac: move documentation from edac_pci*.c to edac_pci.h
edac: move documentation from edac_mc.c to edac_core.h
driver-api: create an edac.rst file with EDAC documentation
edac: adjust docs location at MAINTAINERS and 00-INDEX
edac: fix kernel-doc tags at the drivers/edac_*.h
edac: fix kenel-doc markups at edac.h
edac.rst: move concepts dictionary from edac.h
Documentation/00-INDEX |4 +-
Documentation/admin-guide/index.rst |2 +-
Documentation/admin-guide/ras.rst | 1190 +++
Documentation/driver-api/edac.rst | 178
Documentation/driver-api/index.rst |1 +
Documentation/edac.txt | 812 --
MAINTAINERS |3 +-
drivers/edac/altera_edac.c |1 -
drivers/edac/amd64_edac.h |2 +-
drivers/edac/amd76x_edac.c |2 +-
drivers/edac/amd8111_edac.c |1 -
drivers/edac/amd8131_edac.c |1 -
drivers/edac/cell_edac.c|2 +-
drivers/edac/cpc925_edac.c |1 -
drivers/edac/e752x_edac.c |2 +-
drivers/edac/e7xxx_edac.c |2 +-
drivers/edac/edac_device.c | 79 +-
drivers/edac/{edac_core.h => edac_device.h} | 315 ++-
drivers/edac/edac_device_sysfs.c|4 +-
drivers/edac/edac_mc.c | 93 +--
drivers/edac/edac_mc.h | 246 ++
drivers/edac/edac_mc_sysfs.c|2 +-
drivers/edac/edac_module.c |2 +-
drivers/edac/edac_module.h |4 +-
drivers/edac/edac_pci.c | 84 +-
drivers/edac/edac_pci.h | 271 ++
drivers/edac/edac_pci_sysfs.c | 13 +-
drivers/edac/fsl_ddr_edac.c |1 -
drivers/edac/ghes_edac.c|2 +-
drivers/edac/highbank_l2_edac.c |1 -
drivers/edac/highbank_mc_edac.c |1 -
drivers/edac/i3000_edac.c |2 +-
drivers/edac/i3200_edac.c |2 +-
drivers/edac/i5000_edac.c |2 +-
drivers/edac/i5100_edac.c |1 -
drivers/edac/i5400_edac.c |2 +-
drivers/edac/i7300_edac.c |2 +-
drivers/edac/i7core_edac.c |2 +-
drivers/edac/i82443bxgx_edac.c |2 +-
drivers/edac/i82860_edac.c |2 +-
drivers/edac/i82875p_edac.c |2 +-
drivers/edac/i82975x_edac.c |2 +-
drivers/edac/ie31200_edac.c |2 +-
drivers/edac/layerscape_edac.c |2 +-
drivers/edac/mpc85xx_edac.c |1 -
drivers/edac/mv64x60_edac.c |1 -
drivers/edac/octeon_edac-l2c.c |1 -
drivers/edac
[PATCH v2 18/19] edac: fix kenel-doc markups at edac.h
As this file was never added to the driver-api, the kernel-doc
markups there were never tested. Some of them have issues.
Fix them.
Signed-off-by: Mauro Carvalho Chehab
---
include/linux/edac.h | 40
1 file changed, 24 insertions(+), 16 deletions(-)
diff --git a/include/linux/edac.h b/include/linux/edac.h
index de67193f8bdb..9bff82497ddf 100644
--- a/include/linux/edac.h
+++ b/include/linux/edac.h
@@ -132,6 +132,8 @@ enum dev_type {
* it for example, by re-trying the operation).
* @HW_EVENT_ERR_FATAL:Fatal Error - Uncorrected error that
could not
* be recovered.
+ * @HW_EVENT_ERR_INFO: Informational - The CPER spec defines a forth
+ * type of error: informational logs.
*/
enum hw_event_mc_err_type {
HW_EVENT_ERR_CORRECTED,
@@ -159,7 +161,7 @@ static inline char *mc_event_error_type(const unsigned int
err_type)
* enum mem_type - memory types. For a more detailed reference, please see
* http://en.wikipedia.org/wiki/DRAM
*
- * @MEM_EMPTY Empty csrow
+ * @MEM_EMPTY: Empty csrow
* @MEM_RESERVED: Reserved csrow type
* @MEM_UNKNOWN: Unknown csrow type
* @MEM_FPM: FPM - Fast Page Mode, used on systems up to 1995.
@@ -194,7 +196,7 @@ static inline char *mc_event_error_type(const unsigned int
err_type)
* @MEM_DDR3: DDR3 RAM
* @MEM_RDDR3: Registered DDR3 RAM
* This is a variant of the DDR3 memories.
- * @MEM_LRDDR3 Load-Reduced DDR3 memory.
+ * @MEM_LRDDR3:Load-Reduced DDR3 memory.
* @MEM_DDR4: Unbuffered DDR4 RAM
* @MEM_RDDR4: Registered DDR4 RAM
* This is a variant of the DDR4 memories.
@@ -280,7 +282,7 @@ enum edac_type {
/**
* enum scrub_type - scrubbing capabilities
- * @SCRUB_UNKNOWN Unknown if scrubber is available
+ * @SCRUB_UNKNOWN: Unknown if scrubber is available
* @SCRUB_NONE:No scrubber
* @SCRUB_SW_PROG: SW progressive (sequential) scrubbing
* @SCRUB_SW_SRC: Software scrub only errors
@@ -289,7 +291,7 @@ enum edac_type {
* @SCRUB_HW_PROG: HW progressive (sequential) scrubbing
* @SCRUB_HW_SRC: Hardware scrub only errors
* @SCRUB_HW_PROG_SRC: Progressive hardware scrub from an error
- * SCRUB_HW_TUNABLE: Hardware scrub frequency is tunable
+ * @SCRUB_HW_TUNABLE: Hardware scrub frequency is tunable
*/
enum scrub_type {
SCRUB_UNKNOWN = 0,
@@ -454,7 +456,7 @@ enum edac_mc_layer_type {
/**
* struct edac_mc_layer - describes the memory controller hierarchy
- * @layer: layer type
+ * @type: layer type
* @size: number of components per layer. For example,
* if the channel layer has two channels, size = 2
* @is_virt_csrow: This layer is part of the "csrow" when old API
@@ -477,24 +479,28 @@ struct edac_mc_layer {
#define EDAC_MAX_LAYERS3
/**
- * EDAC_DIMM_OFF - Macro responsible to get a pointer offset inside a pointer
array
- *for the element given by [layer0,layer1,layer2] position
+ * EDAC_DIMM_OFF - Macro responsible to get a pointer offset inside a pointer
+ *array for the element given by [layer0,layer1,layer2]
+ *position
*
* @layers:a struct edac_mc_layer array, describing how many elements
* were allocated for each layer
- * @n_layers: Number of layers at the @layers array
+ * @nlayers: Number of layers at the @layers array
* @layer0:layer0 position
* @layer1:layer1 position. Unused if n_layers < 2
* @layer2:layer2 position. Unused if n_layers < 3
*
- * For 1 layer, this macro returns &var[layer0] - &var
+ * For 1 layer, this macro returns "var[layer0] - var";
+ *
* For 2 layers, this macro is similar to allocate a bi-dimensional array
- * and to return "&var[layer0][layer1] - &var"
+ * and to return "var[layer0][layer1] - var";
+ *
* For 3 layers, this macro is similar to allocate a tri-dimensional array
- * and to return "&var[layer0][layer1][layer2] - &var"
+ * and to return "var[layer0][layer1][layer2] - var".
*
* A loop could be used here to make it more generic, but, as we only have
* 3 layers, this is a little faster.
+ *
* By design, layers can never be 0 or more than 3. If that ever happens,
* a NULL is returned, causing an OOPS during the memory allocation routine,
* with would point to the developer that he's doing something wrong.
@@ -521,16 +527,18 @@ struct edac_mc_layer {
* were allocated for each layer
* @var: name of the var where we want to get the pointer
* (like mci->dimms)
- * @n_layers: Number of layers at the @layers array
+ *
[PATCH v2 14/19] edac: move documentation from edac_mc.c to edac_core.h
Several functions are documented at edac_mc.c.
As we'll be including edac_core.h at drivers-api book, move
those, in order for the kernel-doc markups be part of the API
documentation book.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/edac/edac_mc.c | 91
drivers/edac/edac_mc.h | 101 +
2 files changed, 101 insertions(+), 91 deletions(-)
diff --git a/drivers/edac/edac_mc.c b/drivers/edac/edac_mc.c
index 6f08dfa18e5e..d50653d36918 100644
--- a/drivers/edac/edac_mc.c
+++ b/drivers/edac/edac_mc.c
@@ -239,30 +239,6 @@ static void _edac_mc_free(struct mem_ctl_info *mci)
kfree(mci);
}
-/**
- * edac_mc_alloc: Allocate and partially fill a struct mem_ctl_info structure
- * @mc_num:Memory controller number
- * @n_layers: Number of MC hierarchy layers
- * layers: Describes each layer as seen by the Memory Controller
- * @size_pvt: size of private storage needed
- *
- *
- * Everything is kmalloc'ed as one big chunk - more efficient.
- * Only can be used if all structures have the same lifetime - otherwise
- * you have to allocate and initialize your own structures.
- *
- * Use edac_mc_free() to free mc structures allocated by this function.
- *
- * NOTE: drivers handle multi-rank memories in different ways: in some
- * drivers, one multi-rank memory stick is mapped as one entry, while, in
- * others, a single multi-rank memory stick would be mapped into several
- * entries. Currently, this function will allocate multiple struct dimm_info
- * on such scenarios, as grouping the multiple ranks require drivers change.
- *
- * Returns:
- * On failure: NULL
- * On success: struct mem_ctl_info pointer
- */
struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
unsigned n_layers,
struct edac_mc_layer *layers,
@@ -460,11 +436,6 @@ struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
}
EXPORT_SYMBOL_GPL(edac_mc_alloc);
-/**
- * edac_mc_free
- * 'Free' a previously allocated 'mci' structure
- * @mci: pointer to a struct mem_ctl_info structure
- */
void edac_mc_free(struct mem_ctl_info *mci)
{
edac_dbg(1, "\n");
@@ -483,13 +454,6 @@ void edac_mc_free(struct mem_ctl_info *mci)
EXPORT_SYMBOL_GPL(edac_mc_free);
-/**
- * find_mci_by_dev
- *
- * scan list of controllers looking for the one that manages
- * the 'dev' device
- * @dev: pointer to a struct device related with the MCI
- */
struct mem_ctl_info *find_mci_by_dev(struct device *dev)
{
struct mem_ctl_info *mci;
@@ -635,14 +599,6 @@ static int del_mc_from_global_list(struct mem_ctl_info
*mci)
return handlers;
}
-/**
- * edac_mc_find: Search for a mem_ctl_info structure whose index is 'idx'.
- *
- * If found, return a pointer to the structure.
- * Else return NULL.
- *
- * Caller must hold mem_ctls_mutex.
- */
struct mem_ctl_info *edac_mc_find(int idx)
{
struct list_head *item;
@@ -663,16 +619,6 @@ struct mem_ctl_info *edac_mc_find(int idx)
}
EXPORT_SYMBOL(edac_mc_find);
-/**
- * edac_mc_add_mc_with_groups: Insert the 'mci' structure into the mci
- * global list and create sysfs entries associated with mci structure
- * @mci: pointer to the mci structure to be added to the list
- * @groups: optional attribute groups for the driver-specific sysfs entries
- *
- * Return:
- * 0 Success
- * !0 Failure
- */
/* FIXME - should a warning be printed if no error detection? correction? */
int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
@@ -763,13 +709,6 @@ int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
}
EXPORT_SYMBOL_GPL(edac_mc_add_mc_with_groups);
-/**
- * edac_mc_del_mc: Remove sysfs entries for specified mci structure and
- * remove mci structure from global list
- * @pdev: Pointer to 'struct device' representing mci structure to remove.
- *
- * Return pointer to removed mci structure, or NULL if device not found.
- */
struct mem_ctl_info *edac_mc_del_mc(struct device *dev)
{
struct mem_ctl_info *mci;
@@ -1033,18 +972,6 @@ static void edac_ue_error(struct mem_ctl_info *mci,
edac_inc_ue_error(mci, enable_per_layer_report, pos, error_count);
}
-/**
- * edac_raw_mc_handle_error - reports a memory event to userspace without doing
- * anything to discover the error location
- *
- * @type: severity of the error (CE/UE/Fatal)
- * @mci: a struct mem_ctl_info pointer
- * @e: error description
- *
- * This raw function is used internally by edac_mc_handle_error(). It should
- * only be called directly when the hardware error come directly from BIOS,
- * like in the case of APEI GHES driver.
- */
void edac_raw_mc_handle_error(const enum hw_event_mc_err_type type,
struct mem_ctl_info *mci,
st
[PATCH v2 19/19] edac.rst: move concepts dictionary from edac.h
Instead of storing the concepts dictionary inside header file,
move it to the subsystem documentation.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/driver-api/edac.rst | 106 +
include/linux/edac.h | 108 --
2 files changed, 106 insertions(+), 108 deletions(-)
diff --git a/Documentation/driver-api/edac.rst
b/Documentation/driver-api/edac.rst
index 3771e768fda1..b8c742aa0a71 100644
--- a/Documentation/driver-api/edac.rst
+++ b/Documentation/driver-api/edac.rst
@@ -1,6 +1,112 @@
Error Detection And Correction (EDAC) Devices
=
+Main Concepts used at the EDAC subsystem
+
+
+There are several things to be aware of that aren't at all obvious, like
+*sockets, *socket sets*, *banks*, *rows*, *chip-select rows*, *channels*,
+etc...
+
+These are some of the many terms that are thrown about that don't always
+mean what people think they mean (Inconceivable!). In the interest of
+creating a common ground for discussion, terms and their definitions
+will be established.
+
+* Memory devices
+
+The individual DRAM chips on a memory stick. These devices commonly
+output 4 and 8 bits each (x4, x8). Grouping several of these in parallel
+provides the number of bits that the memory controller expects:
+typically 72 bits, in order to provide 64 bits + 8 bits of ECC data.
+
+* Memory Stick
+
+A printed circuit board that aggregates multiple memory devices in
+parallel. In general, this is the Field Replaceable Unit (FRU) which
+gets replaced, in the case of excessive errors. Most often it is also
+called DIMM (Dual Inline Memory Module).
+
+* Memory Socket
+
+A physical connector on the motherboard that accepts a single memory
+stick. Also called as "slot" on several datasheets.
+
+* Channel
+
+A memory controller channel, responsible to communicate with a group of
+DIMMs. Each channel has its own independent control (command) and data
+bus, and can be used independently or grouped with other channels.
+
+* Branch
+
+It is typically the highest hierarchy on a Fully-Buffered DIMM memory
+controller. Typically, it contains two channels. Two channels at the
+same branch can be used in single mode or in lockstep mode. When
+lockstep is enabled, the cacheline is doubled, but it generally brings
+some performance penalty. Also, it is generally not possible to point to
+just one memory stick when an error occurs, as the error correction code
+is calculated using two DIMMs instead of one. Due to that, it is capable
+of correcting more errors than on single mode.
+
+* Single-channel
+
+The data accessed by the memory controller is contained into one dimm
+only. E. g. if the data is 64 bits-wide, the data flows to the CPU using
+one 64 bits parallel access. Typically used with SDR, DDR, DDR2 and DDR3
+memories. FB-DIMM and RAMBUS use a different concept for channel, so
+this concept doesn't apply there.
+
+* Double-channel
+
+The data size accessed by the memory controller is interlaced into two
+dimms, accessed at the same time. E. g. if the DIMM is 64 bits-wide (72
+bits with ECC), the data flows to the CPU using a 128 bits parallel
+access.
+
+* Chip-select row
+
+This is the name of the DRAM signal used to select the DRAM ranks to be
+accessed. Common chip-select rows for single channel are 64 bits, for
+dual channel 128 bits. It may not be visible by the memory controller,
+as some DIMM types have a memory buffer that can hide direct access to
+it from the Memory Controller.
+
+* Single-Ranked stick
+
+A Single-ranked stick has 1 chip-select row of memory. Motherboards
+commonly drive two chip-select pins to a memory stick. A single-ranked
+stick, will occupy only one of those rows. The other will be unused.
+
+.. _doubleranked:
+
+* Double-Ranked stick
+
+A double-ranked stick has two chip-select rows which access different
+sets of memory devices. The two rows cannot be accessed concurrently.
+
+* Double-sided stick
+
+**DEPRECATED TERM**, see :ref:`Double-Ranked stick `.
+
+A double-sided stick has two chip-select rows which access different sets
+of memory devices. The two rows cannot be accessed concurrently.
+"Double-sided" is irrespective of the memory devices being mounted on
+both sides of the memory stick.
+
+* Socket set
+
+All of the memory sticks that are required for a single memory access or
+all of the memory sticks spanned by a chip-select row. A single socket
+set has two chip-select rows and if double-sided sticks are used these
+will occupy those chip-select rows.
+
+* Bank
+
+This term is avoided because it is unclear when needing to distinguish
+between chip-select rows and socket sets.
+
+
Memory Controllers
--
diff --git a/include/linux/edac.h b/include/linux/edac.h
index 9bff82497ddf..773a8e8700c8 100644
--- a/include/linux/edac.h
+++ b/include/linux/edac.h
@@ -324,114 +324,6 @@ enum scrub_type {
[PATCH v2 06/19] edac.txt: update information about newer Intel CPUs
There's a chapter at edac.rst written by the time Nehalem support was added. Such information is used not only by the Nehalem driver (i7core_edac), but by all newer Intel CPU architectures that are supported by i7core_edac, sb_edac and sbx_edac drivers. Update the information to reflect that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/edac.txt | 44 +--- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/Documentation/edac.txt b/Documentation/edac.txt index fba193044af0..0c9161c9ed7a 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -741,13 +741,25 @@ The ``test_device_edac`` sample driver is located at the http://bluesmoke.sourceforge.net project site for EDAC. -Nehalem Usage of EDAC APIs --- +Usage of EDAC APIs on Nehalem and newer Intel CPUs +-- -Due to the way Nehalem exports Memory Controller data, some adjustments -were done at i7core_edac driver. This chapter will cover those differences +On older Intel architectures, the memory controller was part of the North +Bridge chipset. Nehalem, Sandy Bridge, Ivy Bridge, Haswell, Sky Lake and +newer Intel architectures integrated an enhanced version of the memory +controller (MC) inside the CPUs. -1) On Nehalem, there is one Memory Controller per Quick Patch Interconnect +This chapter will cover the differences of the enhanced memory controllers +found on newer Intel CPUs, such as ``i7core_edac``, ``sb_edac`` and +``sbx_edac`` drivers. + +.. note:: + + The Xeon E7 processor families use a separate chip for the memory + controller, called Intel Scalable Memory Buffer. This section doesn't + apply for such families. + +1) There is one Memory Controller per Quick Patch Interconnect (QPI). At the driver, the term "socket" means one QPI. This is associated with a physical CPU socket. @@ -757,7 +769,7 @@ were done at i7core_edac driver. This chapter will cover those differences The minimum known unity is DIMMs. There are no information about csrows. As EDAC API maps the minimum unity is csrows, the driver sequentially - maps channel/dimm into different csrows. + maps channel/DIMM into different csrows. For example, supposing the following layout:: @@ -780,8 +792,8 @@ were done at i7core_edac driver. This chapter will cover those differences Each QPI is exported as a different memory controller. -2) Nehalem MC has the ability to generate errors. The driver implements this - functionality via some error injection nodes: +2) The MC has the ability to inject errors to test drivers. The drivers + implement this functionality via some error injection nodes: For injecting a memory error, there are some sysfs nodes, under ``/sys/devices/system/edac/mc/mc?/``: @@ -855,13 +867,14 @@ were done at i7core_edac driver. This chapter will cover those differences EDAC MC0: UE row 0, channel-a= 0 channel-b= 0 labels "-": NON_FATAL (addr = 0x0075b980, socket=0, Dimm=0, Channel=2, syndrome=0x0040, count=1, Err=8c41009f:480482 (read error: read ECC error)) -3) Nehalem specific Corrected Error memory counters +3) Corrected Error memory register counters - Nehalem have some registers to count memory errors. The driver uses those - registers to report Corrected Errors on devices with Registered Dimms. + Those newer MCs have some registers to count memory errors. The driver + uses those registers to report Corrected Errors on devices with Registered + DIMMs. - However, those counters don't work with Unregistered Dimms. As the chipset - offers some counters that also work with UDIMMS (but with a worse level of + However, those counters don't work with Unregistered DIMM. As the chipset + offers some counters that also work with UDIMMs (but with a worse level of granularity than the default ones), the driver exposes those registers for UDIMM memories. @@ -896,8 +909,8 @@ were done at i7core_edac driver. This chapter will cover those differences 4) Standard error counters The standard error counters are generated when an mcelog error is received - by the driver. Since, with udimm, this is counted by software, it is - possible that some errors could be lost. With rdimm's, they display the + by the driver. Since, with UDIMM, this is counted by software, it is + possible that some errors could be lost. With RDIMM's, they display the contents of the registers Reference documents used on ``amd64_edac`` @@ -958,6 +971,7 @@ Credits * |copy| Mauro Carvalho Chehab - 05 Aug 2009Nehalem interface + - 26 Oct 2016 Converted to ReST and cleanups at the Nehalem section * EDAC authors/maintainers: -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org
[PATCH v2 15/19] driver-api: create an edac.rst file with EDAC documentation
Currently, there's no device driver documentation for the EDAC subsystem at the driver-api book. Fill in the blanks for the structures and functions that misses documentation, uniform the word on the existing ones, and add a new edac.rst file at driver-api, in order to document the EDAC subsystem. Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/edac.rst | 72 ++ Documentation/driver-api/index.rst | 1 + 2 files changed, 73 insertions(+) create mode 100644 Documentation/driver-api/edac.rst diff --git a/Documentation/driver-api/edac.rst b/Documentation/driver-api/edac.rst new file mode 100644 index ..3771e768fda1 --- /dev/null +++ b/Documentation/driver-api/edac.rst @@ -0,0 +1,72 @@ +Error Detection And Correction (EDAC) Devices += + +Memory Controllers +-- + +Most of the EDAC core is focused on doing Memory Controller error detection. +The :c:func:`edac_mc_alloc`. It uses internally the struct ``mem_ctl_info`` +to describe the memory controllers, with is an opaque struct for the EDAC +drivers. Only the EDAC core is allowed to touch it. + +.. kernel-doc:: include/linux/edac.h + +.. kernel-doc:: drivers/edac/edac_mc.h + +PCI Controllers +--- + +The EDAC subsystem provides a mechanism to handle PCI controllers by calling +the :c:func:`edac_pci_alloc_ctl_info`. It will use the struct +:c:type:`edac_pci_ctl_info` to describe the PCI controllers. + +.. kernel-doc:: drivers/edac/edac_pci.h + +EDAC Blocks +--- + +The EDAC subsystem also provides a generic mechanism to report errors on +other parts of the hardware via :c:func:`edac_device_alloc_ctl_info` function. + +The structures :c:type:`edac_dev_sysfs_block_attribute`, +:c:type:`edac_device_block`, :c:type:`edac_device_instance` and +:c:type:`edac_device_ctl_info` provide a generic or abstract 'edac_device' +representation at sysfs. + +This set of structures and the code that implements the APIs for the same, provide for registering EDAC type devices which are NOT standard memory or +PCI, like: + +- CPU caches (L1 and L2) +- DMA engines +- Core CPU switches +- Fabric switch units +- PCIe interface controllers +- other EDAC/ECC type devices that can be monitored for + errors, etc. + +It allows for a 2 level set of hierarchy. + +For example, a cache could be composed of L1, L2 and L3 levels of cache. +Each CPU core would have its own L1 cache, while sharing L2 and maybe L3 +caches. On such case, those can be represented via the following sysfs +nodes:: + + /sys/devices/system/edac/.. + + pci/ + mc/ + cpu/cpu0/.. + /L1-cache/ce_count +/ue_count + /L2-cache/ce_count +/ue_count + cpu/cpu1/.. + /L1-cache/ce_count +/ue_count + /L2-cache/ce_count +/ue_count + ... + + the L1 and L2 directories would be "edac_device_block's" + +.. kernel-doc:: drivers/edac/edac_device.h diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index e18135b513e2..01e22444bad4 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -23,6 +23,7 @@ available subsections can be seen below. spi i2c hsi + edac miscellaneous vme -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
