Ctrlk
HomePMDKNDCTLBlog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Managing Label Storage Areas (LSA)

The namespace label area is a small persistent partition of capacity available on some NVDIMM devices. The label area is used to store the definition of any NVDIMM namespaces.

The labels on the NVDIMMs cannot be edited directly. Changing the configuration can be achieved using the ndctl create or destroy commands. See Managing Namespaces and Managing Regions. ndctl provides several label related commands shown below:

  • check-labels - determine if the given dimm(s) have a valid namespace index block

  • init-labels - initialize the label data area on a dimm or set of dimms

  • read-labels - read out the label area on a dimm or set of dimms

  • write-labels - write data to the label area on a dimm

  • zero-labels - zero out the label area on a dimm or set of dimms

Checking Labels

The check-labels command validates the index block within the label storage area on the specified NVDIMMs. If issues are found, running the command in verbose mode using the -v option, reports the reason the index block is deemed invalid.

usage: ndctl check-labels <nmem0> [<nmem1>..<nmemN>] [<options>]

    -b, --bus <bus-id>    <nmem> must be on a bus with an id/provider of <bus-id>
    -v, --verbose         turn on debug

1) Identify the NVDIMMs (nmem's) in the host using the ndctl list -D command:

# ndctl list -D
[
  {
    "dev":"nmem3",
    "id":"8089-a1-1811-0000005d",
    "handle":4353,
    "phys_id":68
  },
  {
    "dev":"nmem0",
    "id":"8089-a1-1811-00000058",
    "handle":1,
    "phys_id":32
  },
  {
    "dev":"nmem2",
    "id":"8089-a1-1811-00000068",
    "handle":4097,
    "phys_id":56
  }
]

2) Check the labels of one or more devices.

To check the labels on a single device:

To check the labels on multiple devices:

To check the labels on all devices:

To display more information, if available, use the -v option:

Note: The -v option may not produce any additional information if the labels are valid or ndctl was not built with logging or debug options.

Initializing Labels

This command can be used to initialize the namespace index block if it is missing or reinitialize it if it is damaged or was previously zero'd. Note that reinitialization effectively destroys all existing namespace labels on the DIMM.

This is an expert mode operation. Overwriting labels will cause data loss. Backup all data prior to overwriting labels.

Before initializing the labels, all namespaces and regions must be destroyed or disabled. A warning message is displayed when attempting to initialize labels on active regions.

1) Identify the active/enabled NVDIMM devices, Regions, and Namespaces

2) Destroy or disable the namespace(s) belonging to the NVDIMMs (nmem's) that require re-initializing.

3) Disable the region(s) belonging to the NVDIMMs (nmem's) that require re-initializing.

4) Initialize the labels

If the init-labels command returns "error: labels already initialized", use the -f, --force option.

5) Enable the region(s). After initializing the labels, the region(s) may not be brought online automatically. List the active and disabled regions:

Activate any disabled regions

6) New namespaces can now be created on the regions. See Managing Namespaces for more information.

Reading Labels

The read-labels command dumps the data in a dimm’s label area to stdout or a file in raw or JSON format. When multiple dimms (nmem's) are specified, the data is concatenated.

Usage:

The following shows a label from nvdimm0 (nmem0) printed to stdout in JSON format.

To backup an NVDIMM label using the raw format, use:

Writing Labels

This is an expert mode operation. Overwriting labels will cause data loss. Backup all data prior to overwriting labels.

Writing labels overwrites the current label with the contents of the specified file, or stdin, collected from a read-labels operation from a different label, or a previous label backup.

Read data from the input filename, or stdin, and write it to the given device. The device being written to must not be active in any region, otherwise the kernel will not allow write access to the device’s label data area.

The following shows how a raw label from an active nvdimm can be written to an inactive nvdimm.

The above read-label raw output can be piped directly to the write-label command using:

Erasing/Zeroing Labels

The zero-labels command resets the device to its default state by deleting all labels.

This operation cannot be undone unless a previous backup of the labels was created using the read-labels command.

All data on the device will be destroyed. Create a backup before proceeding.

Before erasing/zeroing the labels, all namespaces and regions must be destroyed or disabled.

1) Identify the active/enabled NVDIMM devices, Regions, and Namespaces

2) Destroy or disable the namespace(s) belonging to the NVDIMMs (nmem's) that require re-initializing.

3) Disable the region(s) belonging to the NVDIMMs (nmem's) that require re-initializing.

4) To erase the labels on a single 'nmem0' device.

To erase labels on multiple devices, use:

5) Enable the region(s). After initializing the labels, the region(s) may not be brought online automatically. List the active and disabled regions:

Activate any 'disabled' regions

6) New namespaces can now be created on the regions. See Managing Namespaces for more information.

PreviousManaging RegionsNextManaging Namespaces

Last updated

Was this helpful?