drivers/edac/edac_mc.h

0001 /*
0002  * Defines, structures, APIs for edac_mc module
0003  *
0004  * (C) 2007 Linux Networx (http://lnxi.com)
0005  * This file may be distributed under the terms of the
0006  * GNU General Public License.
0007  *
0008  * Written by Thayne Harbaugh
0009  * Based on work by Dan Hollis <goemon at anime dot net> and others.
0010  *  http://www.anime.net/~goemon/linux-ecc/
0011  *
0012  * NMI handling support added by
0013  *     Dave Peterson <dsp@llnl.gov> <dave_peterson@pobox.com>
0014  *
0015  * Refactored for multi-source files:
0016  *  Doug Thompson <norsk5@xmission.com>
0017  *
0018  * Please look at Documentation/driver-api/edac.rst for more info about
0019  * EDAC core structs and functions.
0020  */
0021
0022 #ifndef _EDAC_MC_H_
0023 #define _EDAC_MC_H_
0024
0025 #include <linux/kernel.h>
0026 #include <linux/types.h>
0027 #include <linux/module.h>
0028 #include <linux/spinlock.h>
0029 #include <linux/smp.h>
0030 #include <linux/pci.h>
0031 #include <linux/time.h>
0032 #include <linux/nmi.h>
0033 #include <linux/rcupdate.h>
0034 #include <linux/completion.h>
0035 #include <linux/kobject.h>
0036 #include <linux/platform_device.h>
0037 #include <linux/workqueue.h>
0038 #include <linux/edac.h>
0039
0040 #if PAGE_SHIFT < 20
0041 #define PAGES_TO_MiB(pages) ((pages) >> (20 - PAGE_SHIFT))
0042 #define MiB_TO_PAGES(mb)    ((mb) << (20 - PAGE_SHIFT))
0043 #else               /* PAGE_SHIFT > 20 */
0044 #define PAGES_TO_MiB(pages) ((pages) << (PAGE_SHIFT - 20))
0045 #define MiB_TO_PAGES(mb)    ((mb) >> (PAGE_SHIFT - 20))
0046 #endif
0047
0048 #define edac_printk(level, prefix, fmt, arg...) \
0049     printk(level "EDAC " prefix ": " fmt, ##arg)
0050
0051 #define edac_mc_printk(mci, level, fmt, arg...) \
0052     printk(level "EDAC MC%d: " fmt, mci->mc_idx, ##arg)
0053
0054 #define edac_mc_chipset_printk(mci, level, prefix, fmt, arg...) \
0055     printk(level "EDAC " prefix " MC%d: " fmt, mci->mc_idx, ##arg)
0056
0057 #define edac_device_printk(ctl, level, fmt, arg...) \
0058     printk(level "EDAC DEVICE%d: " fmt, ctl->dev_idx, ##arg)
0059
0060 #define edac_pci_printk(ctl, level, fmt, arg...) \
0061     printk(level "EDAC PCI%d: " fmt, ctl->pci_idx, ##arg)
0062
0063 /* prefixes for edac_printk() and edac_mc_printk() */
0064 #define EDAC_MC "MC"
0065 #define EDAC_PCI "PCI"
0066 #define EDAC_DEBUG "DEBUG"
0067
0068 extern const char * const edac_mem_types[];
0069
0070 #ifdef CONFIG_EDAC_DEBUG
0071 extern int edac_debug_level;
0072
0073 #define edac_dbg(level, fmt, ...)                   \
0074 do {                                    \
0075     if (level <= edac_debug_level)                  \
0076         edac_printk(KERN_DEBUG, EDAC_DEBUG,         \
0077                 "%s: " fmt, __func__, ##__VA_ARGS__);   \
0078 } while (0)
0079
0080 #else               /* !CONFIG_EDAC_DEBUG */
0081
0082 #define edac_dbg(level, fmt, ...)                   \
0083 do {                                    \
0084     if (0)                              \
0085         edac_printk(KERN_DEBUG, EDAC_DEBUG,         \
0086                 "%s: " fmt, __func__, ##__VA_ARGS__);   \
0087 } while (0)
0088
0089 #endif              /* !CONFIG_EDAC_DEBUG */
0090
0091 #define PCI_VEND_DEV(vend, dev) PCI_VENDOR_ID_ ## vend, \
0092     PCI_DEVICE_ID_ ## vend ## _ ## dev
0093
0094 #define edac_dev_name(dev) (dev)->dev_name
0095
0096 #define to_mci(k) container_of(k, struct mem_ctl_info, dev)
0097
0098 /**
0099  * edac_mc_alloc() - Allocate and partially fill a struct &mem_ctl_info.
0100  *
0101  * @mc_num:     Memory controller number
0102  * @n_layers:       Number of MC hierarchy layers
0103  * @layers:     Describes each layer as seen by the Memory Controller
0104  * @sz_pvt:     size of private storage needed
0105  *
0106  *
0107  * Everything is kmalloc'ed as one big chunk - more efficient.
0108  * Only can be used if all structures have the same lifetime - otherwise
0109  * you have to allocate and initialize your own structures.
0110  *
0111  * Use edac_mc_free() to free mc structures allocated by this function.
0112  *
0113  * .. note::
0114  *
0115  *   drivers handle multi-rank memories in different ways: in some
0116  *   drivers, one multi-rank memory stick is mapped as one entry, while, in
0117  *   others, a single multi-rank memory stick would be mapped into several
0118  *   entries. Currently, this function will allocate multiple struct dimm_info
0119  *   on such scenarios, as grouping the multiple ranks require drivers change.
0120  *
0121  * Returns:
0122  *  On success, return a pointer to struct mem_ctl_info pointer;
0123  *  %NULL otherwise
0124  */
0125 struct mem_ctl_info *edac_mc_alloc(unsigned int mc_num,
0126                    unsigned int n_layers,
0127                    struct edac_mc_layer *layers,
0128                    unsigned int sz_pvt);
0129
0130 /**
0131  * edac_get_owner - Return the owner's mod_name of EDAC MC
0132  *
0133  * Returns:
0134  *  Pointer to mod_name string when EDAC MC is owned. NULL otherwise.
0135  */
0136 extern const char *edac_get_owner(void);
0137
0138 /*
0139  * edac_mc_add_mc_with_groups() - Insert the @mci structure into the mci
0140  *  global list and create sysfs entries associated with @mci structure.
0141  *
0142  * @mci: pointer to the mci structure to be added to the list
0143  * @groups: optional attribute groups for the driver-specific sysfs entries
0144  *
0145  * Returns:
0146  *  0 on Success, or an error code on failure
0147  */
0148 extern int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
0149                       const struct attribute_group **groups);
0150 #define edac_mc_add_mc(mci) edac_mc_add_mc_with_groups(mci, NULL)
0151
0152 /**
0153  * edac_mc_free() -  Frees a previously allocated @mci structure
0154  *
0155  * @mci: pointer to a struct mem_ctl_info structure
0156  */
0157 extern void edac_mc_free(struct mem_ctl_info *mci);
0158
0159 /**
0160  * edac_has_mcs() - Check if any MCs have been allocated.
0161  *
0162  * Returns:
0163  *  True if MC instances have been registered successfully.
0164  *  False otherwise.
0165  */
0166 extern bool edac_has_mcs(void);
0167
0168 /**
0169  * edac_mc_find() - Search for a mem_ctl_info structure whose index is @idx.
0170  *
0171  * @idx: index to be seek
0172  *
0173  * If found, return a pointer to the structure.
0174  * Else return NULL.
0175  */
0176 extern struct mem_ctl_info *edac_mc_find(int idx);
0177
0178 /**
0179  * find_mci_by_dev() - Scan list of controllers looking for the one that
0180  *  manages the @dev device.
0181  *
0182  * @dev: pointer to a struct device related with the MCI
0183  *
0184  * Returns: on success, returns a pointer to struct &mem_ctl_info;
0185  * %NULL otherwise.
0186  */
0187 extern struct mem_ctl_info *find_mci_by_dev(struct device *dev);
0188
0189 /**
0190  * edac_mc_del_mc() - Remove sysfs entries for mci structure associated with
0191  *  @dev and remove mci structure from global list.
0192  *
0193  * @dev: Pointer to struct &device representing mci structure to remove.
0194  *
0195  * Returns: pointer to removed mci structure, or %NULL if device not found.
0196  */
0197 extern struct mem_ctl_info *edac_mc_del_mc(struct device *dev);
0198
0199 /**
0200  * edac_mc_find_csrow_by_page() - Ancillary routine to identify what csrow
0201  *  contains a memory page.
0202  *
0203  * @mci: pointer to a struct mem_ctl_info structure
0204  * @page: memory page to find
0205  *
0206  * Returns: on success, returns the csrow. -1 if not found.
0207  */
0208 extern int edac_mc_find_csrow_by_page(struct mem_ctl_info *mci,
0209                       unsigned long page);
0210
0211 /**
0212  * edac_raw_mc_handle_error() - Reports a memory event to userspace without
0213  *  doing anything to discover the error location.
0214  *
0215  * @e:          error description
0216  *
0217  * This raw function is used internally by edac_mc_handle_error(). It should
0218  * only be called directly when the hardware error come directly from BIOS,
0219  * like in the case of APEI GHES driver.
0220  */
0221 void edac_raw_mc_handle_error(struct edac_raw_error_desc *e);
0222
0223 /**
0224  * edac_mc_handle_error() - Reports a memory event to userspace.
0225  *
0226  * @type:       severity of the error (CE/UE/Fatal)
0227  * @mci:        a struct mem_ctl_info pointer
0228  * @error_count:    Number of errors of the same type
0229  * @page_frame_number:  mem page where the error occurred
0230  * @offset_in_page: offset of the error inside the page
0231  * @syndrome:       ECC syndrome
0232  * @top_layer:      Memory layer[0] position
0233  * @mid_layer:      Memory layer[1] position
0234  * @low_layer:      Memory layer[2] position
0235  * @msg:        Message meaningful to the end users that
0236  *          explains the event
0237  * @other_detail:   Technical details about the event that
0238  *          may help hardware manufacturers and
0239  *          EDAC developers to analyse the event
0240  */
0241 void edac_mc_handle_error(const enum hw_event_mc_err_type type,
0242               struct mem_ctl_info *mci,
0243               const u16 error_count,
0244               const unsigned long page_frame_number,
0245               const unsigned long offset_in_page,
0246               const unsigned long syndrome,
0247               const int top_layer,
0248               const int mid_layer,
0249               const int low_layer,
0250               const char *msg,
0251               const char *other_detail);
0252
0253 /*
0254  * edac misc APIs
0255  */
0256 extern char *edac_op_state_to_string(int op_state);
0257
0258 #endif              /* _EDAC_MC_H_ */