root/drivers/edac/edac_mc.c

/* [<][>][^][v][top][bottom][index][help] */

DEFINITIONS

This source file includes following definitions.
  1. edac_get_report_status
  2. edac_set_report_status
  3. edac_report_set
  4. edac_report_get
  5. edac_dimm_info_location
  6. edac_mc_dump_channel
  7. edac_mc_dump_dimm
  8. edac_mc_dump_csrow
  9. edac_mc_dump_mci
  10. edac_align_ptr
  11. _edac_mc_free
  12. edac_mc_alloc
  13. edac_mc_free
  14. edac_has_mcs
  15. __find_mci_by_dev
  16. find_mci_by_dev
  17. edac_mc_workq_function
  18. edac_mc_reset_delay_period
  19. add_mc_to_global_list
  20. del_mc_from_global_list
  21. edac_mc_find
  22. edac_get_owner
  23. edac_mc_add_mc_with_groups
  24. edac_mc_del_mc
  25. edac_mc_scrub_block
  26. edac_mc_find_csrow_by_page
  27. edac_inc_ce_error
  28. edac_inc_ue_error
  29. edac_ce_error
  30. edac_ue_error
  31. edac_raw_mc_handle_error
  32. edac_mc_handle_error

   1 /*
   2  * edac_mc kernel module
   3  * (C) 2005, 2006 Linux Networx (http://lnxi.com)
   4  * This file may be distributed under the terms of the
   5  * GNU General Public License.
   6  *
   7  * Written by Thayne Harbaugh
   8  * Based on work by Dan Hollis <goemon at anime dot net> and others.
   9  *      http://www.anime.net/~goemon/linux-ecc/
  10  *
  11  * Modified by Dave Peterson and Doug Thompson
  12  *
  13  */
  14 
  15 #include <linux/module.h>
  16 #include <linux/proc_fs.h>
  17 #include <linux/kernel.h>
  18 #include <linux/types.h>
  19 #include <linux/smp.h>
  20 #include <linux/init.h>
  21 #include <linux/sysctl.h>
  22 #include <linux/highmem.h>
  23 #include <linux/timer.h>
  24 #include <linux/slab.h>
  25 #include <linux/jiffies.h>
  26 #include <linux/spinlock.h>
  27 #include <linux/list.h>
  28 #include <linux/ctype.h>
  29 #include <linux/edac.h>
  30 #include <linux/bitops.h>
  31 #include <linux/uaccess.h>
  32 #include <asm/page.h>
  33 #include "edac_mc.h"
  34 #include "edac_module.h"
  35 #include <ras/ras_event.h>
  36 
  37 #ifdef CONFIG_EDAC_ATOMIC_SCRUB
  38 #include <asm/edac.h>
  39 #else
  40 #define edac_atomic_scrub(va, size) do { } while (0)
  41 #endif
  42 
  43 int edac_op_state = EDAC_OPSTATE_INVAL;
  44 EXPORT_SYMBOL_GPL(edac_op_state);
  45 
  46 static int edac_report = EDAC_REPORTING_ENABLED;
  47 
  48 /* lock to memory controller's control array */
  49 static DEFINE_MUTEX(mem_ctls_mutex);
  50 static LIST_HEAD(mc_devices);
  51 
  52 /*
  53  * Used to lock EDAC MC to just one module, avoiding two drivers e. g.
  54  *      apei/ghes and i7core_edac to be used at the same time.
  55  */
  56 static const char *edac_mc_owner;
  57 
  58 int edac_get_report_status(void)
  59 {
  60         return edac_report;
  61 }
  62 EXPORT_SYMBOL_GPL(edac_get_report_status);
  63 
  64 void edac_set_report_status(int new)
  65 {
  66         if (new == EDAC_REPORTING_ENABLED ||
  67             new == EDAC_REPORTING_DISABLED ||
  68             new == EDAC_REPORTING_FORCE)
  69                 edac_report = new;
  70 }
  71 EXPORT_SYMBOL_GPL(edac_set_report_status);
  72 
  73 static int edac_report_set(const char *str, const struct kernel_param *kp)
  74 {
  75         if (!str)
  76                 return -EINVAL;
  77 
  78         if (!strncmp(str, "on", 2))
  79                 edac_report = EDAC_REPORTING_ENABLED;
  80         else if (!strncmp(str, "off", 3))
  81                 edac_report = EDAC_REPORTING_DISABLED;
  82         else if (!strncmp(str, "force", 5))
  83                 edac_report = EDAC_REPORTING_FORCE;
  84 
  85         return 0;
  86 }
  87 
  88 static int edac_report_get(char *buffer, const struct kernel_param *kp)
  89 {
  90         int ret = 0;
  91 
  92         switch (edac_report) {
  93         case EDAC_REPORTING_ENABLED:
  94                 ret = sprintf(buffer, "on");
  95                 break;
  96         case EDAC_REPORTING_DISABLED:
  97                 ret = sprintf(buffer, "off");
  98                 break;
  99         case EDAC_REPORTING_FORCE:
 100                 ret = sprintf(buffer, "force");
 101                 break;
 102         default:
 103                 ret = -EINVAL;
 104                 break;
 105         }
 106 
 107         return ret;
 108 }
 109 
 110 static const struct kernel_param_ops edac_report_ops = {
 111         .set = edac_report_set,
 112         .get = edac_report_get,
 113 };
 114 
 115 module_param_cb(edac_report, &edac_report_ops, &edac_report, 0644);
 116 
 117 unsigned int edac_dimm_info_location(struct dimm_info *dimm, char *buf,
 118                                      unsigned int len)
 119 {
 120         struct mem_ctl_info *mci = dimm->mci;
 121         int i, n, count = 0;
 122         char *p = buf;
 123 
 124         for (i = 0; i < mci->n_layers; i++) {
 125                 n = snprintf(p, len, "%s %d ",
 126                               edac_layer_name[mci->layers[i].type],
 127                               dimm->location[i]);
 128                 p += n;
 129                 len -= n;
 130                 count += n;
 131                 if (!len)
 132                         break;
 133         }
 134 
 135         return count;
 136 }
 137 
 138 #ifdef CONFIG_EDAC_DEBUG
 139 
 140 static void edac_mc_dump_channel(struct rank_info *chan)
 141 {
 142         edac_dbg(4, "  channel->chan_idx = %d\n", chan->chan_idx);
 143         edac_dbg(4, "    channel = %p\n", chan);
 144         edac_dbg(4, "    channel->csrow = %p\n", chan->csrow);
 145         edac_dbg(4, "    channel->dimm = %p\n", chan->dimm);
 146 }
 147 
 148 static void edac_mc_dump_dimm(struct dimm_info *dimm, int number)
 149 {
 150         char location[80];
 151 
 152         edac_dimm_info_location(dimm, location, sizeof(location));
 153 
 154         edac_dbg(4, "%s%i: %smapped as virtual row %d, chan %d\n",
 155                  dimm->mci->csbased ? "rank" : "dimm",
 156                  number, location, dimm->csrow, dimm->cschannel);
 157         edac_dbg(4, "  dimm = %p\n", dimm);
 158         edac_dbg(4, "  dimm->label = '%s'\n", dimm->label);
 159         edac_dbg(4, "  dimm->nr_pages = 0x%x\n", dimm->nr_pages);
 160         edac_dbg(4, "  dimm->grain = %d\n", dimm->grain);
 161         edac_dbg(4, "  dimm->nr_pages = 0x%x\n", dimm->nr_pages);
 162 }
 163 
 164 static void edac_mc_dump_csrow(struct csrow_info *csrow)
 165 {
 166         edac_dbg(4, "csrow->csrow_idx = %d\n", csrow->csrow_idx);
 167         edac_dbg(4, "  csrow = %p\n", csrow);
 168         edac_dbg(4, "  csrow->first_page = 0x%lx\n", csrow->first_page);
 169         edac_dbg(4, "  csrow->last_page = 0x%lx\n", csrow->last_page);
 170         edac_dbg(4, "  csrow->page_mask = 0x%lx\n", csrow->page_mask);
 171         edac_dbg(4, "  csrow->nr_channels = %d\n", csrow->nr_channels);
 172         edac_dbg(4, "  csrow->channels = %p\n", csrow->channels);
 173         edac_dbg(4, "  csrow->mci = %p\n", csrow->mci);
 174 }
 175 
 176 static void edac_mc_dump_mci(struct mem_ctl_info *mci)
 177 {
 178         edac_dbg(3, "\tmci = %p\n", mci);
 179         edac_dbg(3, "\tmci->mtype_cap = %lx\n", mci->mtype_cap);
 180         edac_dbg(3, "\tmci->edac_ctl_cap = %lx\n", mci->edac_ctl_cap);
 181         edac_dbg(3, "\tmci->edac_cap = %lx\n", mci->edac_cap);
 182         edac_dbg(4, "\tmci->edac_check = %p\n", mci->edac_check);
 183         edac_dbg(3, "\tmci->nr_csrows = %d, csrows = %p\n",
 184                  mci->nr_csrows, mci->csrows);
 185         edac_dbg(3, "\tmci->nr_dimms = %d, dimms = %p\n",
 186                  mci->tot_dimms, mci->dimms);
 187         edac_dbg(3, "\tdev = %p\n", mci->pdev);
 188         edac_dbg(3, "\tmod_name:ctl_name = %s:%s\n",
 189                  mci->mod_name, mci->ctl_name);
 190         edac_dbg(3, "\tpvt_info = %p\n\n", mci->pvt_info);
 191 }
 192 
 193 #endif                          /* CONFIG_EDAC_DEBUG */
 194 
 195 const char * const edac_mem_types[] = {
 196         [MEM_EMPTY]     = "Empty",
 197         [MEM_RESERVED]  = "Reserved",
 198         [MEM_UNKNOWN]   = "Unknown",
 199         [MEM_FPM]       = "FPM",
 200         [MEM_EDO]       = "EDO",
 201         [MEM_BEDO]      = "BEDO",
 202         [MEM_SDR]       = "Unbuffered-SDR",
 203         [MEM_RDR]       = "Registered-SDR",
 204         [MEM_DDR]       = "Unbuffered-DDR",
 205         [MEM_RDDR]      = "Registered-DDR",
 206         [MEM_RMBS]      = "RMBS",
 207         [MEM_DDR2]      = "Unbuffered-DDR2",
 208         [MEM_FB_DDR2]   = "FullyBuffered-DDR2",
 209         [MEM_RDDR2]     = "Registered-DDR2",
 210         [MEM_XDR]       = "XDR",
 211         [MEM_DDR3]      = "Unbuffered-DDR3",
 212         [MEM_RDDR3]     = "Registered-DDR3",
 213         [MEM_LRDDR3]    = "Load-Reduced-DDR3-RAM",
 214         [MEM_DDR4]      = "Unbuffered-DDR4",
 215         [MEM_RDDR4]     = "Registered-DDR4",
 216         [MEM_LRDDR4]    = "Load-Reduced-DDR4-RAM",
 217         [MEM_NVDIMM]    = "Non-volatile-RAM",
 218 };
 219 EXPORT_SYMBOL_GPL(edac_mem_types);
 220 
 221 /**
 222  * edac_align_ptr - Prepares the pointer offsets for a single-shot allocation
 223  * @p:          pointer to a pointer with the memory offset to be used. At
 224  *              return, this will be incremented to point to the next offset
 225  * @size:       Size of the data structure to be reserved
 226  * @n_elems:    Number of elements that should be reserved
 227  *
 228  * If 'size' is a constant, the compiler will optimize this whole function
 229  * down to either a no-op or the addition of a constant to the value of '*p'.
 230  *
 231  * The 'p' pointer is absolutely needed to keep the proper advancing
 232  * further in memory to the proper offsets when allocating the struct along
 233  * with its embedded structs, as edac_device_alloc_ctl_info() does it
 234  * above, for example.
 235  *
 236  * At return, the pointer 'p' will be incremented to be used on a next call
 237  * to this function.
 238  */
 239 void *edac_align_ptr(void **p, unsigned int size, int n_elems)
 240 {
 241         unsigned int align, r;
 242         void *ptr = *p;
 243 
 244         *p += size * n_elems;
 245 
 246         /*
 247          * 'p' can possibly be an unaligned item X such that sizeof(X) is
 248          * 'size'.  Adjust 'p' so that its alignment is at least as
 249          * stringent as what the compiler would provide for X and return
 250          * the aligned result.
 251          * Here we assume that the alignment of a "long long" is the most
 252          * stringent alignment that the compiler will ever provide by default.
 253          * As far as I know, this is a reasonable assumption.
 254          */
 255         if (size > sizeof(long))
 256                 align = sizeof(long long);
 257         else if (size > sizeof(int))
 258                 align = sizeof(long);
 259         else if (size > sizeof(short))
 260                 align = sizeof(int);
 261         else if (size > sizeof(char))
 262                 align = sizeof(short);
 263         else
 264                 return (char *)ptr;
 265 
 266         r = (unsigned long)p % align;
 267 
 268         if (r == 0)
 269                 return (char *)ptr;
 270 
 271         *p += align - r;
 272 
 273         return (void *)(((unsigned long)ptr) + align - r);
 274 }
 275 
 276 static void _edac_mc_free(struct mem_ctl_info *mci)
 277 {
 278         struct csrow_info *csr;
 279         int i, chn, row;
 280 
 281         if (mci->dimms) {
 282                 for (i = 0; i < mci->tot_dimms; i++)
 283                         kfree(mci->dimms[i]);
 284                 kfree(mci->dimms);
 285         }
 286 
 287         if (mci->csrows) {
 288                 for (row = 0; row < mci->nr_csrows; row++) {
 289                         csr = mci->csrows[row];
 290                         if (!csr)
 291                                 continue;
 292 
 293                         if (csr->channels) {
 294                                 for (chn = 0; chn < mci->num_cschannel; chn++)
 295                                         kfree(csr->channels[chn]);
 296                                 kfree(csr->channels);
 297                         }
 298                         kfree(csr);
 299                 }
 300                 kfree(mci->csrows);
 301         }
 302         kfree(mci);
 303 }
 304 
 305 struct mem_ctl_info *edac_mc_alloc(unsigned int mc_num,
 306                                    unsigned int n_layers,
 307                                    struct edac_mc_layer *layers,
 308                                    unsigned int sz_pvt)
 309 {
 310         struct mem_ctl_info *mci;
 311         struct edac_mc_layer *layer;
 312         struct csrow_info *csr;
 313         struct rank_info *chan;
 314         struct dimm_info *dimm;
 315         u32 *ce_per_layer[EDAC_MAX_LAYERS], *ue_per_layer[EDAC_MAX_LAYERS];
 316         unsigned int pos[EDAC_MAX_LAYERS];
 317         unsigned int size, tot_dimms = 1, count = 1;
 318         unsigned int tot_csrows = 1, tot_channels = 1, tot_errcount = 0;
 319         void *pvt, *p, *ptr = NULL;
 320         int i, j, row, chn, n, len, off;
 321         bool per_rank = false;
 322 
 323         BUG_ON(n_layers > EDAC_MAX_LAYERS || n_layers == 0);
 324         /*
 325          * Calculate the total amount of dimms and csrows/cschannels while
 326          * in the old API emulation mode
 327          */
 328         for (i = 0; i < n_layers; i++) {
 329                 tot_dimms *= layers[i].size;
 330                 if (layers[i].is_virt_csrow)
 331                         tot_csrows *= layers[i].size;
 332                 else
 333                         tot_channels *= layers[i].size;
 334 
 335                 if (layers[i].type == EDAC_MC_LAYER_CHIP_SELECT)
 336                         per_rank = true;
 337         }
 338 
 339         /* Figure out the offsets of the various items from the start of an mc
 340          * structure.  We want the alignment of each item to be at least as
 341          * stringent as what the compiler would provide if we could simply
 342          * hardcode everything into a single struct.
 343          */
 344         mci = edac_align_ptr(&ptr, sizeof(*mci), 1);
 345         layer = edac_align_ptr(&ptr, sizeof(*layer), n_layers);
 346         for (i = 0; i < n_layers; i++) {
 347                 count *= layers[i].size;
 348                 edac_dbg(4, "errcount layer %d size %d\n", i, count);
 349                 ce_per_layer[i] = edac_align_ptr(&ptr, sizeof(u32), count);
 350                 ue_per_layer[i] = edac_align_ptr(&ptr, sizeof(u32), count);
 351                 tot_errcount += 2 * count;
 352         }
 353 
 354         edac_dbg(4, "allocating %d error counters\n", tot_errcount);
 355         pvt = edac_align_ptr(&ptr, sz_pvt, 1);
 356         size = ((unsigned long)pvt) + sz_pvt;
 357 
 358         edac_dbg(1, "allocating %u bytes for mci data (%d %s, %d csrows/channels)\n",
 359                  size,
 360                  tot_dimms,
 361                  per_rank ? "ranks" : "dimms",
 362                  tot_csrows * tot_channels);
 363 
 364         mci = kzalloc(size, GFP_KERNEL);
 365         if (mci == NULL)
 366                 return NULL;
 367 
 368         /* Adjust pointers so they point within the memory we just allocated
 369          * rather than an imaginary chunk of memory located at address 0.
 370          */
 371         layer = (struct edac_mc_layer *)(((char *)mci) + ((unsigned long)layer));
 372         for (i = 0; i < n_layers; i++) {
 373                 mci->ce_per_layer[i] = (u32 *)((char *)mci + ((unsigned long)ce_per_layer[i]));
 374                 mci->ue_per_layer[i] = (u32 *)((char *)mci + ((unsigned long)ue_per_layer[i]));
 375         }
 376         pvt = sz_pvt ? (((char *)mci) + ((unsigned long)pvt)) : NULL;
 377 
 378         /* setup index and various internal pointers */
 379         mci->mc_idx = mc_num;
 380         mci->tot_dimms = tot_dimms;
 381         mci->pvt_info = pvt;
 382         mci->n_layers = n_layers;
 383         mci->layers = layer;
 384         memcpy(mci->layers, layers, sizeof(*layer) * n_layers);
 385         mci->nr_csrows = tot_csrows;
 386         mci->num_cschannel = tot_channels;
 387         mci->csbased = per_rank;
 388 
 389         /*
 390          * Alocate and fill the csrow/channels structs
 391          */
 392         mci->csrows = kcalloc(tot_csrows, sizeof(*mci->csrows), GFP_KERNEL);
 393         if (!mci->csrows)
 394                 goto error;
 395         for (row = 0; row < tot_csrows; row++) {
 396                 csr = kzalloc(sizeof(**mci->csrows), GFP_KERNEL);
 397                 if (!csr)
 398                         goto error;
 399                 mci->csrows[row] = csr;
 400                 csr->csrow_idx = row;
 401                 csr->mci = mci;
 402                 csr->nr_channels = tot_channels;
 403                 csr->channels = kcalloc(tot_channels, sizeof(*csr->channels),
 404                                         GFP_KERNEL);
 405                 if (!csr->channels)
 406                         goto error;
 407 
 408                 for (chn = 0; chn < tot_channels; chn++) {
 409                         chan = kzalloc(sizeof(**csr->channels), GFP_KERNEL);
 410                         if (!chan)
 411                                 goto error;
 412                         csr->channels[chn] = chan;
 413                         chan->chan_idx = chn;
 414                         chan->csrow = csr;
 415                 }
 416         }
 417 
 418         /*
 419          * Allocate and fill the dimm structs
 420          */
 421         mci->dimms  = kcalloc(tot_dimms, sizeof(*mci->dimms), GFP_KERNEL);
 422         if (!mci->dimms)
 423                 goto error;
 424 
 425         memset(&pos, 0, sizeof(pos));
 426         row = 0;
 427         chn = 0;
 428         for (i = 0; i < tot_dimms; i++) {
 429                 chan = mci->csrows[row]->channels[chn];
 430                 off = EDAC_DIMM_OFF(layer, n_layers, pos[0], pos[1], pos[2]);
 431                 if (off < 0 || off >= tot_dimms) {
 432                         edac_mc_printk(mci, KERN_ERR, "EDAC core bug: EDAC_DIMM_OFF is trying to do an illegal data access\n");
 433                         goto error;
 434                 }
 435 
 436                 dimm = kzalloc(sizeof(**mci->dimms), GFP_KERNEL);
 437                 if (!dimm)
 438                         goto error;
 439                 mci->dimms[off] = dimm;
 440                 dimm->mci = mci;
 441 
 442                 /*
 443                  * Copy DIMM location and initialize it.
 444                  */
 445                 len = sizeof(dimm->label);
 446                 p = dimm->label;
 447                 n = snprintf(p, len, "mc#%u", mc_num);
 448                 p += n;
 449                 len -= n;
 450                 for (j = 0; j < n_layers; j++) {
 451                         n = snprintf(p, len, "%s#%u",
 452                                      edac_layer_name[layers[j].type],
 453                                      pos[j]);
 454                         p += n;
 455                         len -= n;
 456                         dimm->location[j] = pos[j];
 457 
 458                         if (len <= 0)
 459                                 break;
 460                 }
 461 
 462                 /* Link it to the csrows old API data */
 463                 chan->dimm = dimm;
 464                 dimm->csrow = row;
 465                 dimm->cschannel = chn;
 466 
 467                 /* Increment csrow location */
 468                 if (layers[0].is_virt_csrow) {
 469                         chn++;
 470                         if (chn == tot_channels) {
 471                                 chn = 0;
 472                                 row++;
 473                         }
 474                 } else {
 475                         row++;
 476                         if (row == tot_csrows) {
 477                                 row = 0;
 478                                 chn++;
 479                         }
 480                 }
 481 
 482                 /* Increment dimm location */
 483                 for (j = n_layers - 1; j >= 0; j--) {
 484                         pos[j]++;
 485                         if (pos[j] < layers[j].size)
 486                                 break;
 487                         pos[j] = 0;
 488                 }
 489         }
 490 
 491         mci->op_state = OP_ALLOC;
 492 
 493         return mci;
 494 
 495 error:
 496         _edac_mc_free(mci);
 497 
 498         return NULL;
 499 }
 500 EXPORT_SYMBOL_GPL(edac_mc_alloc);
 501 
 502 void edac_mc_free(struct mem_ctl_info *mci)
 503 {
 504         edac_dbg(1, "\n");
 505 
 506         if (device_is_registered(&mci->dev))
 507                 edac_unregister_sysfs(mci);
 508 
 509         _edac_mc_free(mci);
 510 }
 511 EXPORT_SYMBOL_GPL(edac_mc_free);
 512 
 513 bool edac_has_mcs(void)
 514 {
 515         bool ret;
 516 
 517         mutex_lock(&mem_ctls_mutex);
 518 
 519         ret = list_empty(&mc_devices);
 520 
 521         mutex_unlock(&mem_ctls_mutex);
 522 
 523         return !ret;
 524 }
 525 EXPORT_SYMBOL_GPL(edac_has_mcs);
 526 
 527 /* Caller must hold mem_ctls_mutex */
 528 static struct mem_ctl_info *__find_mci_by_dev(struct device *dev)
 529 {
 530         struct mem_ctl_info *mci;
 531         struct list_head *item;
 532 
 533         edac_dbg(3, "\n");
 534 
 535         list_for_each(item, &mc_devices) {
 536                 mci = list_entry(item, struct mem_ctl_info, link);
 537 
 538                 if (mci->pdev == dev)
 539                         return mci;
 540         }
 541 
 542         return NULL;
 543 }
 544 
 545 /**
 546  * find_mci_by_dev
 547  *
 548  *      scan list of controllers looking for the one that manages
 549  *      the 'dev' device
 550  * @dev: pointer to a struct device related with the MCI
 551  */
 552 struct mem_ctl_info *find_mci_by_dev(struct device *dev)
 553 {
 554         struct mem_ctl_info *ret;
 555 
 556         mutex_lock(&mem_ctls_mutex);
 557         ret = __find_mci_by_dev(dev);
 558         mutex_unlock(&mem_ctls_mutex);
 559 
 560         return ret;
 561 }
 562 EXPORT_SYMBOL_GPL(find_mci_by_dev);
 563 
 564 /*
 565  * edac_mc_workq_function
 566  *      performs the operation scheduled by a workq request
 567  */
 568 static void edac_mc_workq_function(struct work_struct *work_req)
 569 {
 570         struct delayed_work *d_work = to_delayed_work(work_req);
 571         struct mem_ctl_info *mci = to_edac_mem_ctl_work(d_work);
 572 
 573         mutex_lock(&mem_ctls_mutex);
 574 
 575         if (mci->op_state != OP_RUNNING_POLL) {
 576                 mutex_unlock(&mem_ctls_mutex);
 577                 return;
 578         }
 579 
 580         if (edac_op_state == EDAC_OPSTATE_POLL)
 581                 mci->edac_check(mci);
 582 
 583         mutex_unlock(&mem_ctls_mutex);
 584 
 585         /* Queue ourselves again. */
 586         edac_queue_work(&mci->work, msecs_to_jiffies(edac_mc_get_poll_msec()));
 587 }
 588 
 589 /*
 590  * edac_mc_reset_delay_period(unsigned long value)
 591  *
 592  *      user space has updated our poll period value, need to
 593  *      reset our workq delays
 594  */
 595 void edac_mc_reset_delay_period(unsigned long value)
 596 {
 597         struct mem_ctl_info *mci;
 598         struct list_head *item;
 599 
 600         mutex_lock(&mem_ctls_mutex);
 601 
 602         list_for_each(item, &mc_devices) {
 603                 mci = list_entry(item, struct mem_ctl_info, link);
 604 
 605                 if (mci->op_state == OP_RUNNING_POLL)
 606                         edac_mod_work(&mci->work, value);
 607         }
 608         mutex_unlock(&mem_ctls_mutex);
 609 }
 610 
 611 
 612 
 613 /* Return 0 on success, 1 on failure.
 614  * Before calling this function, caller must
 615  * assign a unique value to mci->mc_idx.
 616  *
 617  *      locking model:
 618  *
 619  *              called with the mem_ctls_mutex lock held
 620  */
 621 static int add_mc_to_global_list(struct mem_ctl_info *mci)
 622 {
 623         struct list_head *item, *insert_before;
 624         struct mem_ctl_info *p;
 625 
 626         insert_before = &mc_devices;
 627 
 628         p = __find_mci_by_dev(mci->pdev);
 629         if (unlikely(p != NULL))
 630                 goto fail0;
 631 
 632         list_for_each(item, &mc_devices) {
 633                 p = list_entry(item, struct mem_ctl_info, link);
 634 
 635                 if (p->mc_idx >= mci->mc_idx) {
 636                         if (unlikely(p->mc_idx == mci->mc_idx))
 637                                 goto fail1;
 638 
 639                         insert_before = item;
 640                         break;
 641                 }
 642         }
 643 
 644         list_add_tail_rcu(&mci->link, insert_before);
 645         return 0;
 646 
 647 fail0:
 648         edac_printk(KERN_WARNING, EDAC_MC,
 649                 "%s (%s) %s %s already assigned %d\n", dev_name(p->pdev),
 650                 edac_dev_name(mci), p->mod_name, p->ctl_name, p->mc_idx);
 651         return 1;
 652 
 653 fail1:
 654         edac_printk(KERN_WARNING, EDAC_MC,
 655                 "bug in low-level driver: attempt to assign\n"
 656                 "    duplicate mc_idx %d in %s()\n", p->mc_idx, __func__);
 657         return 1;
 658 }
 659 
 660 static int del_mc_from_global_list(struct mem_ctl_info *mci)
 661 {
 662         list_del_rcu(&mci->link);
 663 
 664         /* these are for safe removal of devices from global list while
 665          * NMI handlers may be traversing list
 666          */
 667         synchronize_rcu();
 668         INIT_LIST_HEAD(&mci->link);
 669 
 670         return list_empty(&mc_devices);
 671 }
 672 
 673 struct mem_ctl_info *edac_mc_find(int idx)
 674 {
 675         struct mem_ctl_info *mci;
 676         struct list_head *item;
 677 
 678         mutex_lock(&mem_ctls_mutex);
 679 
 680         list_for_each(item, &mc_devices) {
 681                 mci = list_entry(item, struct mem_ctl_info, link);
 682                 if (mci->mc_idx == idx)
 683                         goto unlock;
 684         }
 685 
 686         mci = NULL;
 687 unlock:
 688         mutex_unlock(&mem_ctls_mutex);
 689         return mci;
 690 }
 691 EXPORT_SYMBOL(edac_mc_find);
 692 
 693 const char *edac_get_owner(void)
 694 {
 695         return edac_mc_owner;
 696 }
 697 EXPORT_SYMBOL_GPL(edac_get_owner);
 698 
 699 /* FIXME - should a warning be printed if no error detection? correction? */
 700 int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
 701                                const struct attribute_group **groups)
 702 {
 703         int ret = -EINVAL;
 704         edac_dbg(0, "\n");
 705 
 706 #ifdef CONFIG_EDAC_DEBUG
 707         if (edac_debug_level >= 3)
 708                 edac_mc_dump_mci(mci);
 709 
 710         if (edac_debug_level >= 4) {
 711                 int i;
 712 
 713                 for (i = 0; i < mci->nr_csrows; i++) {
 714                         struct csrow_info *csrow = mci->csrows[i];
 715                         u32 nr_pages = 0;
 716                         int j;
 717 
 718                         for (j = 0; j < csrow->nr_channels; j++)
 719                                 nr_pages += csrow->channels[j]->dimm->nr_pages;
 720                         if (!nr_pages)
 721                                 continue;
 722                         edac_mc_dump_csrow(csrow);
 723                         for (j = 0; j < csrow->nr_channels; j++)
 724                                 if (csrow->channels[j]->dimm->nr_pages)
 725                                         edac_mc_dump_channel(csrow->channels[j]);
 726                 }
 727                 for (i = 0; i < mci->tot_dimms; i++)
 728                         if (mci->dimms[i]->nr_pages)
 729                                 edac_mc_dump_dimm(mci->dimms[i], i);
 730         }
 731 #endif
 732         mutex_lock(&mem_ctls_mutex);
 733 
 734         if (edac_mc_owner && edac_mc_owner != mci->mod_name) {
 735                 ret = -EPERM;
 736                 goto fail0;
 737         }
 738 
 739         if (add_mc_to_global_list(mci))
 740                 goto fail0;
 741 
 742         /* set load time so that error rate can be tracked */
 743         mci->start_time = jiffies;
 744 
 745         mci->bus = edac_get_sysfs_subsys();
 746 
 747         if (edac_create_sysfs_mci_device(mci, groups)) {
 748                 edac_mc_printk(mci, KERN_WARNING,
 749                         "failed to create sysfs device\n");
 750                 goto fail1;
 751         }
 752 
 753         if (mci->edac_check) {
 754                 mci->op_state = OP_RUNNING_POLL;
 755 
 756                 INIT_DELAYED_WORK(&mci->work, edac_mc_workq_function);
 757                 edac_queue_work(&mci->work, msecs_to_jiffies(edac_mc_get_poll_msec()));
 758 
 759         } else {
 760                 mci->op_state = OP_RUNNING_INTERRUPT;
 761         }
 762 
 763         /* Report action taken */
 764         edac_mc_printk(mci, KERN_INFO,
 765                 "Giving out device to module %s controller %s: DEV %s (%s)\n",
 766                 mci->mod_name, mci->ctl_name, mci->dev_name,
 767                 edac_op_state_to_string(mci->op_state));
 768 
 769         edac_mc_owner = mci->mod_name;
 770 
 771         mutex_unlock(&mem_ctls_mutex);
 772         return 0;
 773 
 774 fail1:
 775         del_mc_from_global_list(mci);
 776 
 777 fail0:
 778         mutex_unlock(&mem_ctls_mutex);
 779         return ret;
 780 }
 781 EXPORT_SYMBOL_GPL(edac_mc_add_mc_with_groups);
 782 
 783 struct mem_ctl_info *edac_mc_del_mc(struct device *dev)
 784 {
 785         struct mem_ctl_info *mci;
 786 
 787         edac_dbg(0, "\n");
 788 
 789         mutex_lock(&mem_ctls_mutex);
 790 
 791         /* find the requested mci struct in the global list */
 792         mci = __find_mci_by_dev(dev);
 793         if (mci == NULL) {
 794                 mutex_unlock(&mem_ctls_mutex);
 795                 return NULL;
 796         }
 797 
 798         /* mark MCI offline: */
 799         mci->op_state = OP_OFFLINE;
 800 
 801         if (del_mc_from_global_list(mci))
 802                 edac_mc_owner = NULL;
 803 
 804         mutex_unlock(&mem_ctls_mutex);
 805 
 806         if (mci->edac_check)
 807                 edac_stop_work(&mci->work);
 808 
 809         /* remove from sysfs */
 810         edac_remove_sysfs_mci_device(mci);
 811 
 812         edac_printk(KERN_INFO, EDAC_MC,
 813                 "Removed device %d for %s %s: DEV %s\n", mci->mc_idx,
 814                 mci->mod_name, mci->ctl_name, edac_dev_name(mci));
 815 
 816         return mci;
 817 }
 818 EXPORT_SYMBOL_GPL(edac_mc_del_mc);
 819 
 820 static void edac_mc_scrub_block(unsigned long page, unsigned long offset,
 821                                 u32 size)
 822 {
 823         struct page *pg;
 824         void *virt_addr;
 825         unsigned long flags = 0;
 826 
 827         edac_dbg(3, "\n");
 828 
 829         /* ECC error page was not in our memory. Ignore it. */
 830         if (!pfn_valid(page))
 831                 return;
 832 
 833         /* Find the actual page structure then map it and fix */
 834         pg = pfn_to_page(page);
 835 
 836         if (PageHighMem(pg))
 837                 local_irq_save(flags);
 838 
 839         virt_addr = kmap_atomic(pg);
 840 
 841         /* Perform architecture specific atomic scrub operation */
 842         edac_atomic_scrub(virt_addr + offset, size);
 843 
 844         /* Unmap and complete */
 845         kunmap_atomic(virt_addr);
 846 
 847         if (PageHighMem(pg))
 848                 local_irq_restore(flags);
 849 }
 850 
 851 /* FIXME - should return -1 */
 852 int edac_mc_find_csrow_by_page(struct mem_ctl_info *mci, unsigned long page)
 853 {
 854         struct csrow_info **csrows = mci->csrows;
 855         int row, i, j, n;
 856 
 857         edac_dbg(1, "MC%d: 0x%lx\n", mci->mc_idx, page);
 858         row = -1;
 859 
 860         for (i = 0; i < mci->nr_csrows; i++) {
 861                 struct csrow_info *csrow = csrows[i];
 862                 n = 0;
 863                 for (j = 0; j < csrow->nr_channels; j++) {
 864                         struct dimm_info *dimm = csrow->channels[j]->dimm;
 865                         n += dimm->nr_pages;
 866                 }
 867                 if (n == 0)
 868                         continue;
 869 
 870                 edac_dbg(3, "MC%d: first(0x%lx) page(0x%lx) last(0x%lx) mask(0x%lx)\n",
 871                          mci->mc_idx,
 872                          csrow->first_page, page, csrow->last_page,
 873                          csrow->page_mask);
 874 
 875                 if ((page >= csrow->first_page) &&
 876                     (page <= csrow->last_page) &&
 877                     ((page & csrow->page_mask) ==
 878                      (csrow->first_page & csrow->page_mask))) {
 879                         row = i;
 880                         break;
 881                 }
 882         }
 883 
 884         if (row == -1)
 885                 edac_mc_printk(mci, KERN_ERR,
 886                         "could not look up page error address %lx\n",
 887                         (unsigned long)page);
 888 
 889         return row;
 890 }
 891 EXPORT_SYMBOL_GPL(edac_mc_find_csrow_by_page);
 892 
 893 const char *edac_layer_name[] = {
 894         [EDAC_MC_LAYER_BRANCH] = "branch",
 895         [EDAC_MC_LAYER_CHANNEL] = "channel",
 896         [EDAC_MC_LAYER_SLOT] = "slot",
 897         [EDAC_MC_LAYER_CHIP_SELECT] = "csrow",
 898         [EDAC_MC_LAYER_ALL_MEM] = "memory",
 899 };
 900 EXPORT_SYMBOL_GPL(edac_layer_name);
 901 
 902 static void edac_inc_ce_error(struct mem_ctl_info *mci,
 903                               bool enable_per_layer_report,
 904                               const int pos[EDAC_MAX_LAYERS],
 905                               const u16 count)
 906 {
 907         int i, index = 0;
 908 
 909         mci->ce_mc += count;
 910 
 911         if (!enable_per_layer_report) {
 912                 mci->ce_noinfo_count += count;
 913                 return;
 914         }
 915 
 916         for (i = 0; i < mci->n_layers; i++) {
 917                 if (pos[i] < 0)
 918                         break;
 919                 index += pos[i];
 920                 mci->ce_per_layer[i][index] += count;
 921 
 922                 if (i < mci->n_layers - 1)
 923                         index *= mci->layers[i + 1].size;
 924         }
 925 }
 926 
 927 static void edac_inc_ue_error(struct mem_ctl_info *mci,
 928                                     bool enable_per_layer_report,
 929                                     const int pos[EDAC_MAX_LAYERS],
 930                                     const u16 count)
 931 {
 932         int i, index = 0;
 933 
 934         mci->ue_mc += count;
 935 
 936         if (!enable_per_layer_report) {
 937                 mci->ue_noinfo_count += count;
 938                 return;
 939         }
 940 
 941         for (i = 0; i < mci->n_layers; i++) {
 942                 if (pos[i] < 0)
 943                         break;
 944                 index += pos[i];
 945                 mci->ue_per_layer[i][index] += count;
 946 
 947                 if (i < mci->n_layers - 1)
 948                         index *= mci->layers[i + 1].size;
 949         }
 950 }
 951 
 952 static void edac_ce_error(struct mem_ctl_info *mci,
 953                           const u16 error_count,
 954                           const int pos[EDAC_MAX_LAYERS],
 955                           const char *msg,
 956                           const char *location,
 957                           const char *label,
 958                           const char *detail,
 959                           const char *other_detail,
 960                           const bool enable_per_layer_report,
 961                           const unsigned long page_frame_number,
 962                           const unsigned long offset_in_page,
 963                           long grain)
 964 {
 965         unsigned long remapped_page;
 966         char *msg_aux = "";
 967 
 968         if (*msg)
 969                 msg_aux = " ";
 970 
 971         if (edac_mc_get_log_ce()) {
 972                 if (other_detail && *other_detail)
 973                         edac_mc_printk(mci, KERN_WARNING,
 974                                        "%d CE %s%son %s (%s %s - %s)\n",
 975                                        error_count, msg, msg_aux, label,
 976                                        location, detail, other_detail);
 977                 else
 978                         edac_mc_printk(mci, KERN_WARNING,
 979                                        "%d CE %s%son %s (%s %s)\n",
 980                                        error_count, msg, msg_aux, label,
 981                                        location, detail);
 982         }
 983         edac_inc_ce_error(mci, enable_per_layer_report, pos, error_count);
 984 
 985         if (mci->scrub_mode == SCRUB_SW_SRC) {
 986                 /*
 987                         * Some memory controllers (called MCs below) can remap
 988                         * memory so that it is still available at a different
 989                         * address when PCI devices map into memory.
 990                         * MC's that can't do this, lose the memory where PCI
 991                         * devices are mapped. This mapping is MC-dependent
 992                         * and so we call back into the MC driver for it to
 993                         * map the MC page to a physical (CPU) page which can
 994                         * then be mapped to a virtual page - which can then
 995                         * be scrubbed.
 996                         */
 997                 remapped_page = mci->ctl_page_to_phys ?
 998                         mci->ctl_page_to_phys(mci, page_frame_number) :
 999                         page_frame_number;
1000 
1001                 edac_mc_scrub_block(remapped_page,
1002                                         offset_in_page, grain);
1003         }
1004 }
1005 
1006 static void edac_ue_error(struct mem_ctl_info *mci,
1007                           const u16 error_count,
1008                           const int pos[EDAC_MAX_LAYERS],
1009                           const char *msg,
1010                           const char *location,
1011                           const char *label,
1012                           const char *detail,
1013                           const char *other_detail,
1014                           const bool enable_per_layer_report)
1015 {
1016         char *msg_aux = "";
1017 
1018         if (*msg)
1019                 msg_aux = " ";
1020 
1021         if (edac_mc_get_log_ue()) {
1022                 if (other_detail && *other_detail)
1023                         edac_mc_printk(mci, KERN_WARNING,
1024                                        "%d UE %s%son %s (%s %s - %s)\n",
1025                                        error_count, msg, msg_aux, label,
1026                                        location, detail, other_detail);
1027                 else
1028                         edac_mc_printk(mci, KERN_WARNING,
1029                                        "%d UE %s%son %s (%s %s)\n",
1030                                        error_count, msg, msg_aux, label,
1031                                        location, detail);
1032         }
1033 
1034         if (edac_mc_get_panic_on_ue()) {
1035                 if (other_detail && *other_detail)
1036                         panic("UE %s%son %s (%s%s - %s)\n",
1037                               msg, msg_aux, label, location, detail, other_detail);
1038                 else
1039                         panic("UE %s%son %s (%s%s)\n",
1040                               msg, msg_aux, label, location, detail);
1041         }
1042 
1043         edac_inc_ue_error(mci, enable_per_layer_report, pos, error_count);
1044 }
1045 
1046 void edac_raw_mc_handle_error(const enum hw_event_mc_err_type type,
1047                               struct mem_ctl_info *mci,
1048                               struct edac_raw_error_desc *e)
1049 {
1050         char detail[80];
1051         int pos[EDAC_MAX_LAYERS] = { e->top_layer, e->mid_layer, e->low_layer };
1052 
1053         /* Memory type dependent details about the error */
1054         if (type == HW_EVENT_ERR_CORRECTED) {
1055                 snprintf(detail, sizeof(detail),
1056                         "page:0x%lx offset:0x%lx grain:%ld syndrome:0x%lx",
1057                         e->page_frame_number, e->offset_in_page,
1058                         e->grain, e->syndrome);
1059                 edac_ce_error(mci, e->error_count, pos, e->msg, e->location, e->label,
1060                               detail, e->other_detail, e->enable_per_layer_report,
1061                               e->page_frame_number, e->offset_in_page, e->grain);
1062         } else {
1063                 snprintf(detail, sizeof(detail),
1064                         "page:0x%lx offset:0x%lx grain:%ld",
1065                         e->page_frame_number, e->offset_in_page, e->grain);
1066 
1067                 edac_ue_error(mci, e->error_count, pos, e->msg, e->location, e->label,
1068                               detail, e->other_detail, e->enable_per_layer_report);
1069         }
1070 
1071 
1072 }
1073 EXPORT_SYMBOL_GPL(edac_raw_mc_handle_error);
1074 
1075 void edac_mc_handle_error(const enum hw_event_mc_err_type type,
1076                           struct mem_ctl_info *mci,
1077                           const u16 error_count,
1078                           const unsigned long page_frame_number,
1079                           const unsigned long offset_in_page,
1080                           const unsigned long syndrome,
1081                           const int top_layer,
1082                           const int mid_layer,
1083                           const int low_layer,
1084                           const char *msg,
1085                           const char *other_detail)
1086 {
1087         char *p;
1088         int row = -1, chan = -1;
1089         int pos[EDAC_MAX_LAYERS] = { top_layer, mid_layer, low_layer };
1090         int i, n_labels = 0;
1091         u8 grain_bits;
1092         struct edac_raw_error_desc *e = &mci->error_desc;
1093 
1094         edac_dbg(3, "MC%d\n", mci->mc_idx);
1095 
1096         /* Fills the error report buffer */
1097         memset(e, 0, sizeof (*e));
1098         e->error_count = error_count;
1099         e->top_layer = top_layer;
1100         e->mid_layer = mid_layer;
1101         e->low_layer = low_layer;
1102         e->page_frame_number = page_frame_number;
1103         e->offset_in_page = offset_in_page;
1104         e->syndrome = syndrome;
1105         e->msg = msg;
1106         e->other_detail = other_detail;
1107 
1108         /*
1109          * Check if the event report is consistent and if the memory
1110          * location is known. If it is known, enable_per_layer_report will be
1111          * true, the DIMM(s) label info will be filled and the per-layer
1112          * error counters will be incremented.
1113          */
1114         for (i = 0; i < mci->n_layers; i++) {
1115                 if (pos[i] >= (int)mci->layers[i].size) {
1116 
1117                         edac_mc_printk(mci, KERN_ERR,
1118                                        "INTERNAL ERROR: %s value is out of range (%d >= %d)\n",
1119                                        edac_layer_name[mci->layers[i].type],
1120                                        pos[i], mci->layers[i].size);
1121                         /*
1122                          * Instead of just returning it, let's use what's
1123                          * known about the error. The increment routines and
1124                          * the DIMM filter logic will do the right thing by
1125                          * pointing the likely damaged DIMMs.
1126                          */
1127                         pos[i] = -1;
1128                 }
1129                 if (pos[i] >= 0)
1130                         e->enable_per_layer_report = true;
1131         }
1132 
1133         /*
1134          * Get the dimm label/grain that applies to the match criteria.
1135          * As the error algorithm may not be able to point to just one memory
1136          * stick, the logic here will get all possible labels that could
1137          * pottentially be affected by the error.
1138          * On FB-DIMM memory controllers, for uncorrected errors, it is common
1139          * to have only the MC channel and the MC dimm (also called "branch")
1140          * but the channel is not known, as the memory is arranged in pairs,
1141          * where each memory belongs to a separate channel within the same
1142          * branch.
1143          */
1144         p = e->label;
1145         *p = '\0';
1146 
1147         for (i = 0; i < mci->tot_dimms; i++) {
1148                 struct dimm_info *dimm = mci->dimms[i];
1149 
1150                 if (top_layer >= 0 && top_layer != dimm->location[0])
1151                         continue;
1152                 if (mid_layer >= 0 && mid_layer != dimm->location[1])
1153                         continue;
1154                 if (low_layer >= 0 && low_layer != dimm->location[2])
1155                         continue;
1156 
1157                 /* get the max grain, over the error match range */
1158                 if (dimm->grain > e->grain)
1159                         e->grain = dimm->grain;
1160 
1161                 /*
1162                  * If the error is memory-controller wide, there's no need to
1163                  * seek for the affected DIMMs because the whole
1164                  * channel/memory controller/...  may be affected.
1165                  * Also, don't show errors for empty DIMM slots.
1166                  */
1167                 if (e->enable_per_layer_report && dimm->nr_pages) {
1168                         if (n_labels >= EDAC_MAX_LABELS) {
1169                                 e->enable_per_layer_report = false;
1170                                 break;
1171                         }
1172                         n_labels++;
1173                         if (p != e->label) {
1174                                 strcpy(p, OTHER_LABEL);
1175                                 p += strlen(OTHER_LABEL);
1176                         }
1177                         strcpy(p, dimm->label);
1178                         p += strlen(p);
1179                         *p = '\0';
1180 
1181                         /*
1182                          * get csrow/channel of the DIMM, in order to allow
1183                          * incrementing the compat API counters
1184                          */
1185                         edac_dbg(4, "%s csrows map: (%d,%d)\n",
1186                                  mci->csbased ? "rank" : "dimm",
1187                                  dimm->csrow, dimm->cschannel);
1188                         if (row == -1)
1189                                 row = dimm->csrow;
1190                         else if (row >= 0 && row != dimm->csrow)
1191                                 row = -2;
1192 
1193                         if (chan == -1)
1194                                 chan = dimm->cschannel;
1195                         else if (chan >= 0 && chan != dimm->cschannel)
1196                                 chan = -2;
1197                 }
1198         }
1199 
1200         if (!e->enable_per_layer_report) {
1201                 strcpy(e->label, "any memory");
1202         } else {
1203                 edac_dbg(4, "csrow/channel to increment: (%d,%d)\n", row, chan);
1204                 if (p == e->label)
1205                         strcpy(e->label, "unknown memory");
1206                 if (type == HW_EVENT_ERR_CORRECTED) {
1207                         if (row >= 0) {
1208                                 mci->csrows[row]->ce_count += error_count;
1209                                 if (chan >= 0)
1210                                         mci->csrows[row]->channels[chan]->ce_count += error_count;
1211                         }
1212                 } else
1213                         if (row >= 0)
1214                                 mci->csrows[row]->ue_count += error_count;
1215         }
1216 
1217         /* Fill the RAM location data */
1218         p = e->location;
1219 
1220         for (i = 0; i < mci->n_layers; i++) {
1221                 if (pos[i] < 0)
1222                         continue;
1223 
1224                 p += sprintf(p, "%s:%d ",
1225                              edac_layer_name[mci->layers[i].type],
1226                              pos[i]);
1227         }
1228         if (p > e->location)
1229                 *(p - 1) = '\0';
1230 
1231         /* Sanity-check driver-supplied grain value. */
1232         if (WARN_ON_ONCE(!e->grain))
1233                 e->grain = 1;
1234 
1235         grain_bits = fls_long(e->grain - 1);
1236 
1237         /* Report the error via the trace interface */
1238         if (IS_ENABLED(CONFIG_RAS))
1239                 trace_mc_event(type, e->msg, e->label, e->error_count,
1240                                mci->mc_idx, e->top_layer, e->mid_layer,
1241                                e->low_layer,
1242                                (e->page_frame_number << PAGE_SHIFT) | e->offset_in_page,
1243                                grain_bits, e->syndrome, e->other_detail);
1244 
1245         edac_raw_mc_handle_error(type, mci, e);
1246 }
1247 EXPORT_SYMBOL_GPL(edac_mc_handle_error);

/* [<][>][^][v][top][bottom][index][help] */