drivers/edac/edac_mc.h

   1 /*
   2  * Defines, structures, APIs for edac_mc module
   3  *
   4  * (C) 2007 Linux Networx (http://lnxi.com)
   5  * This file may be distributed under the terms of the
   6  * GNU General Public License.
   7  *
   8  * Written by Thayne Harbaugh
   9  * Based on work by Dan Hollis <goemon at anime dot net> and others.
  10  *      http://www.anime.net/~goemon/linux-ecc/
  11  *
  12  * NMI handling support added by
  13  *     Dave Peterson <dsp@llnl.gov> <dave_peterson@pobox.com>
  14  *
  15  * Refactored for multi-source files:
  16  *      Doug Thompson <norsk5@xmission.com>
  17  *
  18  * Please look at Documentation/driver-api/edac.rst for more info about
  19  * EDAC core structs and functions.
  20  */
  21
  22 #ifndef _EDAC_MC_H_
  23 #define _EDAC_MC_H_
  24
  25 #include <linux/kernel.h>
  26 #include <linux/types.h>
  27 #include <linux/module.h>
  28 #include <linux/spinlock.h>
  29 #include <linux/smp.h>
  30 #include <linux/pci.h>
  31 #include <linux/time.h>
  32 #include <linux/nmi.h>
  33 #include <linux/rcupdate.h>
  34 #include <linux/completion.h>
  35 #include <linux/kobject.h>
  36 #include <linux/platform_device.h>
  37 #include <linux/workqueue.h>
  38 #include <linux/edac.h>
  39
  40 #if PAGE_SHIFT < 20
  41 #define PAGES_TO_MiB(pages)     ((pages) >> (20 - PAGE_SHIFT))
  42 #define MiB_TO_PAGES(mb)        ((mb) << (20 - PAGE_SHIFT))
  43 #else                           /* PAGE_SHIFT > 20 */
  44 #define PAGES_TO_MiB(pages)     ((pages) << (PAGE_SHIFT - 20))
  45 #define MiB_TO_PAGES(mb)        ((mb) >> (PAGE_SHIFT - 20))
  46 #endif
  47
  48 #define edac_printk(level, prefix, fmt, arg...) \
  49         printk(level "EDAC " prefix ": " fmt, ##arg)
  50
  51 #define edac_mc_printk(mci, level, fmt, arg...) \
  52         printk(level "EDAC MC%d: " fmt, mci->mc_idx, ##arg)
  53
  54 #define edac_mc_chipset_printk(mci, level, prefix, fmt, arg...) \
  55         printk(level "EDAC " prefix " MC%d: " fmt, mci->mc_idx, ##arg)
  56
  57 #define edac_device_printk(ctl, level, fmt, arg...) \
  58         printk(level "EDAC DEVICE%d: " fmt, ctl->dev_idx, ##arg)
  59
  60 #define edac_pci_printk(ctl, level, fmt, arg...) \
  61         printk(level "EDAC PCI%d: " fmt, ctl->pci_idx, ##arg)
  62
  63 /* prefixes for edac_printk() and edac_mc_printk() */
  64 #define EDAC_MC "MC"
  65 #define EDAC_PCI "PCI"
  66 #define EDAC_DEBUG "DEBUG"
  67
  68 extern const char * const edac_mem_types[];
  69
  70 #ifdef CONFIG_EDAC_DEBUG
  71 extern int edac_debug_level;
  72
  73 #define edac_dbg(level, fmt, ...)                                       \
  74 do {                                                                    \
  75         if (level <= edac_debug_level)                                  \
  76                 edac_printk(KERN_DEBUG, EDAC_DEBUG,                     \
  77                             "%s: " fmt, __func__, ##__VA_ARGS__);       \
  78 } while (0)
  79
  80 #else                           /* !CONFIG_EDAC_DEBUG */
  81
  82 #define edac_dbg(level, fmt, ...)                                       \
  83 do {                                                                    \
  84         if (0)                                                          \
  85                 edac_printk(KERN_DEBUG, EDAC_DEBUG,                     \
  86                             "%s: " fmt, __func__, ##__VA_ARGS__);       \
  87 } while (0)
  88
  89 #endif                          /* !CONFIG_EDAC_DEBUG */
  90
  91 #define PCI_VEND_DEV(vend, dev) PCI_VENDOR_ID_ ## vend, \
  92         PCI_DEVICE_ID_ ## vend ## _ ## dev
  93
  94 #define edac_dev_name(dev) (dev)->dev_name
  95
  96 #define to_mci(k) container_of(k, struct mem_ctl_info, dev)
  97
  98 /**
  99  * edac_mc_alloc() - Allocate and partially fill a struct &mem_ctl_info.
 100  *
 101  * @mc_num:             Memory controller number
 102  * @n_layers:           Number of MC hierarchy layers
 103  * @layers:             Describes each layer as seen by the Memory Controller
 104  * @sz_pvt:             size of private storage needed
 105  *
 106  *
 107  * Everything is kmalloc'ed as one big chunk - more efficient.
 108  * Only can be used if all structures have the same lifetime - otherwise
 109  * you have to allocate and initialize your own structures.
 110  *
 111  * Use edac_mc_free() to free mc structures allocated by this function.
 112  *
 113  * .. note::
 114  *
 115  *   drivers handle multi-rank memories in different ways: in some
 116  *   drivers, one multi-rank memory stick is mapped as one entry, while, in
 117  *   others, a single multi-rank memory stick would be mapped into several
 118  *   entries. Currently, this function will allocate multiple struct dimm_info
 119  *   on such scenarios, as grouping the multiple ranks require drivers change.
 120  *
 121  * Returns:
 122  *      On success, return a pointer to struct mem_ctl_info pointer;
 123  *      %NULL otherwise
 124  */
 125 struct mem_ctl_info *edac_mc_alloc(unsigned int mc_num,
 126                                    unsigned int n_layers,
 127                                    struct edac_mc_layer *layers,
 128                                    unsigned int sz_pvt);
 129
 130 /**
 131  * edac_get_owner - Return the owner's mod_name of EDAC MC
 132  *
 133  * Returns:
 134  *      Pointer to mod_name string when EDAC MC is owned. NULL otherwise.
 135  */
 136 extern const char *edac_get_owner(void);
 137
 138 /*
 139  * edac_mc_add_mc_with_groups() - Insert the @mci structure into the mci
 140  *      global list and create sysfs entries associated with @mci structure.
 141  *
 142  * @mci: pointer to the mci structure to be added to the list
 143  * @groups: optional attribute groups for the driver-specific sysfs entries
 144  *
 145  * Returns:
 146  *      0 on Success, or an error code on failure
 147  */
 148 extern int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
 149                                       const struct attribute_group **groups);
 150 #define edac_mc_add_mc(mci)     edac_mc_add_mc_with_groups(mci, NULL)
 151
 152 /**
 153  * edac_mc_free() -  Frees a previously allocated @mci structure
 154  *
 155  * @mci: pointer to a struct mem_ctl_info structure
 156  */
 157 extern void edac_mc_free(struct mem_ctl_info *mci);
 158
 159 /**
 160  * edac_has_mcs() - Check if any MCs have been allocated.
 161  *
 162  * Returns:
 163  *      True if MC instances have been registered successfully.
 164  *      False otherwise.
 165  */
 166 extern bool edac_has_mcs(void);
 167
 168 /**
 169  * edac_mc_find() - Search for a mem_ctl_info structure whose index is @idx.
 170  *
 171  * @idx: index to be seek
 172  *
 173  * If found, return a pointer to the structure.
 174  * Else return NULL.
 175  */
 176 extern struct mem_ctl_info *edac_mc_find(int idx);
 177
 178 /**
 179  * find_mci_by_dev() - Scan list of controllers looking for the one that
 180  *      manages the @dev device.
 181  *
 182  * @dev: pointer to a struct device related with the MCI
 183  *
 184  * Returns: on success, returns a pointer to struct &mem_ctl_info;
 185  * %NULL otherwise.
 186  */
 187 extern struct mem_ctl_info *find_mci_by_dev(struct device *dev);
 188
 189 /**
 190  * edac_mc_del_mc() - Remove sysfs entries for mci structure associated with
 191  *      @dev and remove mci structure from global list.
 192  *
 193  * @dev: Pointer to struct &device representing mci structure to remove.
 194  *
 195  * Returns: pointer to removed mci structure, or %NULL if device not found.
 196  */
 197 extern struct mem_ctl_info *edac_mc_del_mc(struct device *dev);
 198
 199 /**
 200  * edac_mc_find_csrow_by_page() - Ancillary routine to identify what csrow
 201  *      contains a memory page.
 202  *
 203  * @mci: pointer to a struct mem_ctl_info structure
 204  * @page: memory page to find
 205  *
 206  * Returns: on success, returns the csrow. -1 if not found.
 207  */
 208 extern int edac_mc_find_csrow_by_page(struct mem_ctl_info *mci,
 209                                       unsigned long page);
 210
 211 /**
 212  * edac_raw_mc_handle_error() - Reports a memory event to userspace without
 213  *      doing anything to discover the error location.
 214  *
 215  * @e:                  error description
 216  *
 217  * This raw function is used internally by edac_mc_handle_error(). It should
 218  * only be called directly when the hardware error come directly from BIOS,
 219  * like in the case of APEI GHES driver.
 220  */
 221 void edac_raw_mc_handle_error(struct edac_raw_error_desc *e);
 222
 223 /**
 224  * edac_mc_handle_error() - Reports a memory event to userspace.
 225  *
 226  * @type:               severity of the error (CE/UE/Fatal)
 227  * @mci:                a struct mem_ctl_info pointer
 228  * @error_count:        Number of errors of the same type
 229  * @page_frame_number:  mem page where the error occurred
 230  * @offset_in_page:     offset of the error inside the page
 231  * @syndrome:           ECC syndrome
 232  * @top_layer:          Memory layer[0] position
 233  * @mid_layer:          Memory layer[1] position
 234  * @low_layer:          Memory layer[2] position
 235  * @msg:                Message meaningful to the end users that
 236  *                      explains the event
 237  * @other_detail:       Technical details about the event that
 238  *                      may help hardware manufacturers and
 239  *                      EDAC developers to analyse the event
 240  */
 241 void edac_mc_handle_error(const enum hw_event_mc_err_type type,
 242                           struct mem_ctl_info *mci,
 243                           const u16 error_count,
 244                           const unsigned long page_frame_number,
 245                           const unsigned long offset_in_page,
 246                           const unsigned long syndrome,
 247                           const int top_layer,
 248                           const int mid_layer,
 249                           const int low_layer,
 250                           const char *msg,
 251                           const char *other_detail);
 252
 253 /*
 254  * edac misc APIs
 255  */
 256 extern char *edac_op_state_to_string(int op_state);
 257
 258 #endif                          /* _EDAC_MC_H_ */