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: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.1
usage: ndctl check-labels <nmem0> [<nmem1>..<nmemN>] [<options>]
2
​
3
-b, --bus <bus-id> <nmem> must be on a bus with an id/provider of <bus-id>
4
-v, --verbose turn on debug
Copied!
1) Identify the NVDIMMs (nmem's) in the host using the
ndctl list -D command:1
# ndctl list -D
2
[
3
{
4
"dev":"nmem3",
5
"id":"8089-a1-1811-0000005d",
6
"handle":4353,
7
"phys_id":68
8
},
9
{
10
"dev":"nmem0",
11
"id":"8089-a1-1811-00000058",
12
"handle":1,
13
"phys_id":32
14
},
15
{
16
"dev":"nmem2",
17
"id":"8089-a1-1811-00000068",
18
"handle":4097,
19
"phys_id":56
20
}
21
]
Copied!
2) Check the labels of one or more devices.
To check the labels on a single device:
1
# ndctl check-labels nmem3
Copied!
To check the labels on multiple devices:
1
# ndctl check-labels nmem3 nmem0 nmem2
Copied!
To check the labels on all devices:
1
# ndctl check-labels all
Copied!
To display more information, if available, use the
-v option:1
# ndctl check-labels nmem3 -v
Copied!
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.
1
usage: ndctl init-labels <nmem0> [<nmem1>..<nmemN>] [<options>]
2
​
3
-b, --bus <bus-id> <nmem> must be on a bus with an id/provider of <bus-id>
4
-v, --verbose turn on debug
5
-f, --force force initialization even if existing index-block present
6
-V, --label-version <version-number>
7
namespace label specification version (default: 1.1)
Copied!
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
# ndctl init-labels nmem3 nmem2
2
nmem3: regions active, abort label write
3
nmem2: regions active, abort label write
Copied!
1) Identify the active/enabled NVDIMM devices, Regions, and Namespaces
1
# ndctl list -DRN
2
{
3
"dimms":[
4
{
5
"dev":"nmem3",
6
"id":"8089-a1-1811-0000005d",
7
"handle":4353,
8
"phys_id":68
9
},
10
{
11
"dev":"nmem0",
12
"id":"8089-a1-1811-00000058",
13
"handle":1,
14
"phys_id":32
15
},
16
{
17
"dev":"nmem2",
18
"id":"8089-a1-1811-00000068",
19
"handle":4097,
20
"phys_id":56
21
}
22
],
23
"regions":[
24
{
25
"dev":"region1",
26
"size":534723428352,
27
"available_size":0,
28
"type":"pmem",
29
"iset_id":3026489321642266624,
30
"mappings":[
31
{
32
"dimm":"nmem3",
33
"offset":268435456,
34
"length":267361714176,
35
"position":1
36
},
37
{
38
"dimm":"nmem2",
39
"offset":268435456,
40
"length":267361714176,
41
"position":0
42
}
43
],
44
"persistence_domain":"memory_controller",
45
"namespaces":[
46
{
47
"dev":"namespace1.0",
48
"mode":"fsdax",
49
"map":"dev",
50
"size":526366277632,
51
"uuid":"76fc4dd1-e793-4eee-81ed-2f31275eb820",
52
"blockdev":"pmem1"
53
}
54
]
55
},
56
{
57
"dev":"region0",
58
"size":267361714176,
59
"available_size":0,
60
"max_available_extent":0,
61
"type":"pmem",
62
"mappings":[
63
{
64
"dimm":"nmem0",
65
"offset":268435456,
66
"length":267361714176,
67
"position":0
68
}
69
],
70
"persistence_domain":"memory_controller"
71
}
72
]
73
}
Copied!
2) Destroy or disable the namespace(s) belonging to the NVDIMMs (nmem's) that require re-initializing.
1
# ndctl destroy-namespace -f namespace1.0
2
- or -
3
# ndctl disable-namespace namespace1.0
4
# ndctl destroy-namespace namespace1.0
Copied!
3) Disable the region(s) belonging to the NVDIMMs (nmem's) that require re-initializing.
1
# ndctl disable-region region1
Copied!
4) Initialize the labels
1
# ndctl init-labels nmem2 nmem3
Copied!
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:
1
# ndctl list -iR
2
[
3
{
4
"dev":"region1",
5
"size":534723428352,
6
"available_size":534723428352,
7
"type":"pmem",
8
"iset_id":3026489321642266624,
9
"state":"disabled",
10
"persistence_domain":"memory_controller"
11
},
12
{
13
"dev":"region0",
14
"size":267361714176,
15
"available_size":0,
16
"max_available_extent":0,
17
"type":"pmem",
18
"persistence_domain":"memory_controller"
19
}
20
]
Copied!
Activate any disabled regions
1
# ndctl enable-region region1
2
​
3
# ndctl list -iR
4
[
5
{
6
"dev":"region1",
7
"size":534723428352,
8
"available_size":534723428352,
9
"type":"pmem",
10
"iset_id":3026489321642266624,
11
"persistence_domain":"memory_controller"
12
},
13
{
14
"dev":"region0",
15
"size":267361714176,
16
"available_size":0,
17
"max_available_extent":0,
18
"type":"pmem",
19
"persistence_domain":"memory_controller"
20
}
21
]
Copied!
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:
1
ndctl read-labels <nmem0> [<nmem1>..<nmemN>] [<options>]
2
​
3
OPTIONS
4
<memory device(s)>
5
A nmemX device name, or a dimm id number. Restrict the operation to the specified dimm(s). The keyword all can be specified to
6
indicate the lack of any restriction, however this is the same as not supplying a --dimm option at all.
7
​
8
-s, --size=
9
Limit the operation to the given number of bytes. A size of 0 indicates to operate over the entire label capacity.
10
​
11
-O, --offset=
12
Begin the operation at the given offset into the label area.
13
​
14
-b, --bus=
15
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
16
specified to indicate the lack of any restriction, however this is the same as not supplying a --bus option at all.
17
​
18
-v
19
Turn on verbose debug messages in the library (if ndctl was built with logging and debug enabled).
20
​
21
-I, --index
22
Limit the span of the label operation to just the index-block area. This is useful to determine if the dimm label area is
23
initialized. Note that this option and --size/--offset are mutually exclusive.
24
​
25
-o, --output
26
output file
27
​
28
-j, --json
29
parse the label data into json assuming the NVDIMM Namespace Specification format.
30
​
31
-u, --human
32
enable json output and convert number formats to human readable strings, for example show the size in terms of "KB", "MB", "GB", etc
33
instead of a signed 64-bit numbers per the JSON interchange format (implies --json).
Copied!
The following shows a label from nvdimm0 (nmem0) printed to stdout in JSON format.
1
# ndctl read-labels -j nmem0
2
{
3
"dev":"nmem0",
4
"index":[
5
{
6
"signature":"NAMESPACE_INDEX",
7
"major":1,
8
"minor":2,
9
"labelsize":256,
10
"seq":2,
11
"nslot":510
12
},
13
{
14
"signature":"NAMESPACE_INDEX",
15
"major":1,
16
"minor":2,
17
"labelsize":256,
18
"seq":1,
19
"nslot":510
20
}
21
],
22
"label":[
23
{
24
"uuid":"9ed56df2-c0a9-4e17-b82d-28f642f95a22",
25
"name":"",
26
"slot":0,
27
"position":0,
28
"nlabel":1,
29
"isetcookie":710683120631319073,
30
"lbasize":512,
31
"dpa":268435456,
32
"rawsize":267361714176,
33
"type_guid":"79d3f066-f3b4-7440-ac43-0d3318b78cdb",
34
"abstraction_guid":"ba006426-9ffb-7746-bcb0-968f11d0d225"
35
}
36
]
37
}
38
read 1 nmem
Copied!
To backup an NVDIMM label using the raw format, use:
1
# ndctl read-labels nmem0 > nmem0.lsa
Copied!
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.
1
$ ndctl read-labels nmem0 -o nmem0.label.backup.raw
2
$ ndctl write-labels nmem1 -i nmem0.label.backup.raw
Copied!
The above read-label raw output can be piped directly to the write-label command using:
1
$ ndctl read-labels nmem0 | ndctl write-labels nmem1
Copied!
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
1
# ndctl list -DRN
2
{
3
"dimms":[
4
{
5
"dev":"nmem3",
6
"id":"8089-a1-1811-0000005d",
7
"handle":4353,
8
"phys_id":68
9
},
10
{
11
"dev":"nmem0",
12
"id":"8089-a1-1811-00000058",
13
"handle":1,
14
"phys_id":32
15
},
16
{
17
"dev":"nmem2",
18
"id":"8089-a1-1811-00000068",
19
"handle":4097,
20
"phys_id":56
21
}
22
],
23
"regions":[
24
{
25
"dev":"region1",
26
"size":534723428352,
27
"available_size":0,
28
"type":"pmem",
29
"iset_id":3026489321642266624,
30
"mappings":[
31
{
32
"dimm":"nmem3",
33
"offset":268435456,
34
"length":267361714176,
35
"position":1
36
},
37
{
38
"dimm":"nmem2",
39
"offset":268435456,
40
"length":267361714176,
41
"position":0
42
}
43
],
44
"persistence_domain":"memory_controller",
45
"namespaces":[
46
{
47
"dev":"namespace1.0",
48
"mode":"fsdax",
49
"map":"dev",
50
"size":526366277632,
51
"uuid":"76fc4dd1-e793-4eee-81ed-2f31275eb820",
52
"blockdev":"pmem1"
53
}
54
]
55
},
56
{
57
"dev":"region0",
58
"size":267361714176,
59
"available_size":0,
60
"max_available_extent":0,
61
"type":"pmem",
62
"mappings":[
63
{
64
"dimm":"nmem0",
65
"offset":268435456,
66
"length":267361714176,
67
"position":0
68
}
69
],
70
"persistence_domain":"memory_controller"
71
}
72
]
73
}
Copied!
2) Destroy or disable the namespace(s) belonging to the NVDIMMs (nmem's) that require re-initializing.
1
# ndctl destroy-namespace -f namespace1.0
2
- or -
3
# ndctl disable-namespace namespace1.0
4
# ndctl destroy-namespace namespace1.0
Copied!
3) Disable the region(s) belonging to the NVDIMMs (nmem's) that require re-initializing.
1
# ndctl disable-region region1
Copied!
4) To erase the labels on a single 'nmem0' device.
1
$ ndctl zero-labels nmem0
Copied!
To erase labels on multiple devices, use:
1
$ ndctl zero-labels nmem0 nmem2 nmem3
Copied!
5) Enable the region(s). After initializing the labels, the region(s) may not be brought online automatically. List the active and disabled regions:
1
# ndctl list -iR
2
[
3
{
4
"dev":"region1",
5
"size":534723428352,
6
"available_size":534723428352,
7
"type":"pmem",
8
"iset_id":3026489321642266624,
9
"state":"disabled",
10
"persistence_domain":"memory_controller"
11
},
12
{
13
"dev":"region0",
14
"size":267361714176,
15
"available_size":0,
16
"max_available_extent":0,
17
"type":"pmem",
18
"persistence_domain":"memory_controller"
19
}
20
]
Copied!
Activate any 'disabled' regions
1
# ndctl enable-region region1
2
​
3
# ndctl list -iR
4
[
5
{
6
"dev":"region1",
7
"size":534723428352,
8
"available_size":534723428352,
9
"type":"pmem",
10
"iset_id":3026489321642266624,
11
"persistence_domain":"memory_controller"
12
},
13
{
14
"dev":"region0",
15
"size":267361714176,
16
"available_size":0,
17
"max_available_extent":0,
18
"type":"pmem",
19
"persistence_domain":"memory_controller"
20
}
21
]
Copied!
Last modified 3mo ago