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:

# ndctl check-labels nmem3

To check the labels on multiple devices:

# ndctl check-labels nmem3 nmem0 nmem2

To check the labels on all devices:

# ndctl check-labels all

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

# ndctl check-labels nmem3 -v

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.

 usage: ndctl init-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
    -f, --force           force initialization even if existing index-block present
    -V, --label-version <version-number>
                          namespace label specification version (default: 1.1)

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.

# ndctl init-labels nmem3 nmem2
nmem3: regions active, abort label write
nmem2: regions active, abort label write

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

# ndctl list -DRN
{
  "dimms":[
    {
      "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
    }
  ],
  "regions":[
    {
      "dev":"region1",
      "size":534723428352,
      "available_size":0,
      "type":"pmem",
      "iset_id":3026489321642266624,
      "mappings":[
        {
          "dimm":"nmem3",
          "offset":268435456,
          "length":267361714176,
          "position":1
        },
        {
          "dimm":"nmem2",
          "offset":268435456,
          "length":267361714176,
          "position":0
        }
      ],
      "persistence_domain":"memory_controller",
      "namespaces":[
        {
          "dev":"namespace1.0",
          "mode":"fsdax",
          "map":"dev",
          "size":526366277632,
          "uuid":"76fc4dd1-e793-4eee-81ed-2f31275eb820",
          "blockdev":"pmem1"
        }
      ]
    },
    {
      "dev":"region0",
      "size":267361714176,
      "available_size":0,
      "max_available_extent":0,
      "type":"pmem",
      "mappings":[
        {
          "dimm":"nmem0",
          "offset":268435456,
          "length":267361714176,
          "position":0
        }
      ],
      "persistence_domain":"memory_controller"
    }
  ]
}

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

# ndctl destroy-namespace -f namespace1.0
- or -
# ndctl disable-namespace namespace1.0
# ndctl destroy-namespace namespace1.0

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

# ndctl disable-region region1

4) Initialize the labels

# ndctl init-labels nmem2 nmem3

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:

# ndctl list -iR
[
  {
    "dev":"region1",
    "size":534723428352,
    "available_size":534723428352,
    "type":"pmem",
    "iset_id":3026489321642266624,
    "state":"disabled",
    "persistence_domain":"memory_controller"
  },
  {
    "dev":"region0",
    "size":267361714176,
    "available_size":0,
    "max_available_extent":0,
    "type":"pmem",
    "persistence_domain":"memory_controller"
  }
]

Activate any disabled regions

# ndctl enable-region region1

# ndctl list -iR
[
  {
    "dev":"region1",
    "size":534723428352,
    "available_size":534723428352,
    "type":"pmem",
    "iset_id":3026489321642266624,
    "persistence_domain":"memory_controller"
  },
  {
    "dev":"region0",
    "size":267361714176,
    "available_size":0,
    "max_available_extent":0,
    "type":"pmem",
    "persistence_domain":"memory_controller"
  }
]

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 DIMMs label area to stdout, or a file in raw or JSON format. When multiple DIMMs (nmem's) are specified, the data is concatenated.

Usage:

       ndctl read-labels <nmem0> [<nmem1>..<nmemN>] [<options>]

OPTIONS
       <memory device(s)>
           A nmemX device name, or a dimm id number. Restrict the operation to the specified dimm(s). The keyword all can be specified to
           indicate the lack of any restriction, however this is the same as not supplying a --dimm option at all.

       -s, --size=
           Limit the operation to the given number of bytes. A size of 0 indicates to operate over the entire label capacity.

       -O, --offset=
           Begin the operation at the given offset into the label area.

       -b, --bus=
           A bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict the operation to the specified bus(es). The keyword all can be
           specified to indicate the lack of any restriction, however this is the same as not supplying a --bus option at all.

       -v
           Turn on verbose debug messages in the library (if ndctl was built with logging and debug enabled).

       -I, --index
           Limit the span of the label operation to just the index-block area. This is useful to determine if the dimm label area is
           initialized. Note that this option and --size/--offset are mutually exclusive.

       -o, --output
           output file

       -j, --json
           parse the label data into json assuming the NVDIMM Namespace Specification format.

       -u, --human
           enable json output and convert number formats to human readable strings, for example show the size in terms of "KB", "MB", "GB", etc
           instead of a signed 64-bit numbers per the JSON interchange format (implies --json).

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

# ndctl read-labels -j nmem0
{
  "dev":"nmem0",
  "index":[
    {
      "signature":"NAMESPACE_INDEX",
      "major":1,
      "minor":2,
      "labelsize":256,
      "seq":2,
      "nslot":510
    },
    {
      "signature":"NAMESPACE_INDEX",
      "major":1,
      "minor":2,
      "labelsize":256,
      "seq":1,
      "nslot":510
    }
  ],
  "label":[
    {
      "uuid":"9ed56df2-c0a9-4e17-b82d-28f642f95a22",
      "name":"",
      "slot":0,
      "position":0,
      "nlabel":1,
      "isetcookie":710683120631319073,
      "lbasize":512,
      "dpa":268435456,
      "rawsize":267361714176,
      "type_guid":"79d3f066-f3b4-7440-ac43-0d3318b78cdb",
      "abstraction_guid":"ba006426-9ffb-7746-bcb0-968f11d0d225"
    }
  ]
}
read 1 nmem

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

# ndctl read-labels nmem0 > nmem0.lsa

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.

$ ndctl read-labels nmem0 -o nmem0.label.backup.raw
$ ndctl write-labels nmem1 -i nmem0.label.backup.raw

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

$ ndctl read-labels nmem0 | ndctl write-labels nmem1

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

# ndctl list -DRN
{
  "dimms":[
    {
      "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
    }
  ],
  "regions":[
    {
      "dev":"region1",
      "size":534723428352,
      "available_size":0,
      "type":"pmem",
      "iset_id":3026489321642266624,
      "mappings":[
        {
          "dimm":"nmem3",
          "offset":268435456,
          "length":267361714176,
          "position":1
        },
        {
          "dimm":"nmem2",
          "offset":268435456,
          "length":267361714176,
          "position":0
        }
      ],
      "persistence_domain":"memory_controller",
      "namespaces":[
        {
          "dev":"namespace1.0",
          "mode":"fsdax",
          "map":"dev",
          "size":526366277632,
          "uuid":"76fc4dd1-e793-4eee-81ed-2f31275eb820",
          "blockdev":"pmem1"
        }
      ]
    },
    {
      "dev":"region0",
      "size":267361714176,
      "available_size":0,
      "max_available_extent":0,
      "type":"pmem",
      "mappings":[
        {
          "dimm":"nmem0",
          "offset":268435456,
          "length":267361714176,
          "position":0
        }
      ],
      "persistence_domain":"memory_controller"
    }
  ]
}

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

# ndctl destroy-namespace -f namespace1.0
- or -
# ndctl disable-namespace namespace1.0
# ndctl destroy-namespace namespace1.0

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

# ndctl disable-region region1

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

$ ndctl zero-labels nmem0

To erase labels on multiple devices, use:

$ ndctl zero-labels nmem0 nmem2 nmem3

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

# ndctl list -iR
[
  {
    "dev":"region1",
    "size":534723428352,
    "available_size":534723428352,
    "type":"pmem",
    "iset_id":3026489321642266624,
    "state":"disabled",
    "persistence_domain":"memory_controller"
  },
  {
    "dev":"region0",
    "size":267361714176,
    "available_size":0,
    "max_available_extent":0,
    "type":"pmem",
    "persistence_domain":"memory_controller"
  }
]

Activate any 'disabled' regions

# ndctl enable-region region1

# ndctl list -iR
[
  {
    "dev":"region1",
    "size":534723428352,
    "available_size":534723428352,
    "type":"pmem",
    "iset_id":3026489321642266624,
    "persistence_domain":"memory_controller"
  },
  {
    "dev":"region0",
    "size":267361714176,
    "available_size":0,
    "max_available_extent":0,
    "type":"pmem",
    "persistence_domain":"memory_controller"
  }
]

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