ndctl inject-error <namespace> [<options>]
The capacity of an NVDIMM REGION (contiguous span of persistent memory) is accessed via one or more NAMESPACE devices. REGION is the Linux term for what ACPI and UEFI call a DIMM-interleave-set, or a system-physical-address-range that is striped (by the memory controller) across one or more memory modules.
The UEFI specification defines the NVDIMM Label Protocol as the combination of label area access methods and a data format for provisioning one or more NAMESPACE objects from a REGION. Note that label support is optional and if Linux does not detect the label capability it will automatically instantiate a "label-less" namespace per region. Examples of label-less namespaces are the ones created by the kernel's memmap=ss!nn command line option (see the nvdimm wiki on kernel.org), or NVDIMMs without a valid namespace index in their label area.
Label-less namespaces lack many of the features of their label-rich cousins. For example, their size cannot be modified, or they cannot be fully destroyed (i.e. the space reclaimed). A destroy operation will zero any mode-specific metadata. Finally, for create-namespace operations on label-less namespaces, ndctl bypasses the region capacity availability checks, and always satisfies the request using the full region capacity. The only reconfiguration operation supported on a label-less namespace is changing its mode.
A namespace can be provisioned to operate in one of 4 modes, fsdax, devdax, sector, and raw. Here are the expected usage models for these modes:
ndctl-inject-error can be used to ask the platform to simulate media errors in the NVDIMM address space to aid debugging and development of features related to error handling.
By default, injecting an error actually only injects an error to the first n bytes of the block, where n is the output of ndctl_cmd_ars_cap_get_size(). In other words, we only inject one ars_unit per sector. This is sufficient for Linux to mark the whole sector as bad, and will show up as such in the various badblocks lists in the kernel. If multiple blocks are being injected, only the first n bytes of each block specified will be injected as errors. This can be overridden by the --saturate option, which will force the entire block to be injected as an error.
These commands are DANGEROUS and can cause data loss. They are only provided for testing and debugging purposes.
Inject errors in namespace0.0 at block 12 for 2 blocks (i.e. 12, 13)
ndctl inject-error --block=12 --count=2 namespace0.0
Check status of injected errors on namespace0.0
ndctl inject-error --status namespace0.0
Uninject errors at block 12 for 2 blocks on namespace0.0
ndctl inject-error --uninject --block=12 --count=2 namespace0.0
NOTE: The offset is interpreted in different ways based on the "mode" of the namespace. For "raw" mode, the offset is the base namespace offset. For "fsdax" mode (i.e. a "pfn" namespace), the offset is relative to the user-visible part of the namespace, and the offset introduced by the kernel's metadata will be accounted for. For a "sector" mode namespace (i.e. a "BTT" namespace), the offset is relative to the base namespace, as the BTT translation details are internal to the kernel, and can't be accounted for while injecting errors.
WARNING: This will not clear the kernel's internal badblock tracking, those can only be cleared by doing a write to the affected locations. Hence use the --clear option only if you know exactly what you are doing. For normal usage, injected errors should only be cleared by doing writes. Do not expect have the original data intact after injecting an error, and clearing it using --clear - it will be lost, as the only "real" way to clear the error location is to write to it or zero it (truncate/hole-punch).
Copyright (c) 2016 - 2019, Intel Corporation. License GPLv2: GNU GPL version 2 <URL: http://gnu.org/licenses/gpl.html >. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.