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_ */
259