'\" t
.\"     Title: ndctl-list
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 1.5.7.1
.\"      Date: 2018-11-27
.\"    Manual: ndctl Manual
.\"    Source: ndctl
.\"  Language: English
.\"
.TH "NDCTL\-LIST" "1" "2018-11-27" "ndctl" "ndctl Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ndctl\-list \- dump the platform nvdimm device topology and attributes in json
.SH "SYNOPSIS"
.sp
.nf
\fIndctl list\fP [<options>]
.fi
.br
.sp
Walk all the nvdimm buses in the system and list all attached devices
along with some of their major attributes.
.sp
Options can be specified to limit the output to devices of a certain
class.  Where the classes are buses, dimms, regions, and namespaces.  By
default, \fIndctl list\fP with no options is equivalent to:
.sp
.nf
ndctl list \-\-namespaces \-\-bus=all \-\-region=all
.fi
.br
.SH "EXAMPLE"
.sp
.if n .RS 4
.nf
# ndctl list \-\-buses \-\-namespaces

{
  "provider":"nfit_test.1",
  "dev":"ndbus2",
  "namespaces":[
    {
      "dev":"namespace9.0",
      "mode":"raw",
      "size":33554432,
      "blockdev":"pmem9"
    }
  ]
}
{
  "provider":"nfit_test.0",
  "dev":"ndbus1"
}
{
  "provider":"e820",
  "dev":"ndbus0",
  "namespaces":[
    {
      "dev":"namespace0.0",
      "mode":"fsdax",
      "size":8589934592,
      "blockdev":"pmem0"
    }
  ]
}
.fi
.if n .RE
.SH "OPTIONS"
.sp
\-r, \-\-region=
.RS 4
.sp
.if n .RS 4
.nf
A \(aqregionX\(aq device name, or a region id number. The keyword \(aqall\(aq can
be specified to carry out the operation on every region in the system,
optionally filtered by bus id (see \-\-bus= option).
.fi
.if n .RE
.RE
.sp
\-b, \-\-bus=
.RS 4
Enforce that the operation only be carried on devices that are
attached to the given bus. Where \fIbus\fP can be a provider name or a bus
id number.
.RE
.sp
\-d, \-\-dimm=
.RS 4
An \fInmemX\fP device name, or dimm id number. The dimm id number
here is X in \fInmemX\fP. Filter listing by devices that reference
the given dimm. For example to see all namespaces comprised
of storage capacity on nmem0:
.RE
.sp
.if n .RS 4
.nf
# ndctl list \-\-dimm=nmem0 \-\-namespaces
.fi
.if n .RE
.sp
\-n, \-\-namespace=
.RS 4
An \fInamespaceX.Y\fP device name, or namespace region plus id tuple
\fIX.Y\fP. Limit the namespace list to the single identified device
if present.
.RE
.sp
\-t, \-\-type=
.RS 4
Filter listing by region type (\fIpmem\fP or \fIblk\fP)
.RE
.sp
\-m, \-\-mode=
.RS 4
Filter listing by the mode (\fIraw\fP, \fIfsdax\fP, \fIsector\fP or \fIdevdax\fP)
of the namespace(s).
.RE
.sp
\-U, \-\-numa\-node=
.RS 4
Filter listing by numa node
.RE
.sp
\-B, \-\-buses
.RS 4
Include bus info in the listing
.RE
.sp
\-D, \-\-dimms
.RS 4
Include dimm info in the listing
.RE
.sp
\-H, \-\-health
.RS 4
Include dimm health info in the listing.  For example:
.RE
.sp
.nf
{
  "dev":"nmem0",
  "health":{
    "health_state":"non\-critical",
    "temperature_celsius":23,
    "spares_percentage":75,
    "alarm_temperature":true,
    "alarm_spares":true,
    "temperature_threshold":40,
    "spares_threshold":5,
    "life_used_percentage":5,
    "shutdown_state":"clean"
  }
}
.fi
.br
.sp
\-F, \-\-firmware
.RS 4
Include dimm firmware info in the listing. For example:
.RE
.sp
.nf
{
  "dev":"nmem0",
  "firmware":{
      "current_version":0,
      "next_version":1,
      "need_powercycle":true
  }
}
.fi
.br
.sp
\-X, \-\-device\-dax
.RS 4
Include device\-dax ("daxregion") details when a namespace is in
"devdax" mode.
.RE
.sp
.nf
{
  "dev":"namespace0.0",
  "mode":"devdax",
  "size":4225761280,
  "uuid":"18ae1bbb\-bb62\-4efc\-86df\-4a5caacb5dcc",
  "daxregion":{
    "id":0,
    "size":4225761280,
    "align":2097152,
    "devices":[
      {
        "chardev":"dax0.0",
        "size":4225761280
      }
    ]
  }
}
.fi
.br
.sp
\-R, \-\-regions
.RS 4
Include region info in the listing
.RE
.sp
\-N, \-\-namespaces
.RS 4
Include namespace info in the listing.  Namespace info is
listed by default if no other options are specified to the command.
.RE
.sp
\-i, \-\-idle
.RS 4
Include idle (not enabled) devices in the listing
.RE
.sp
\-M, \-\-media\-errors
.RS 4
Include media errors (badblocks) in the listing. Note that the
\fIbadblock_count\fP property is included in the listing by default
when the count is non\-zero, otherwise it is hidden. Also, if the
namespace is in \fIsector\fP mode the \fIbadblocks\fP listing is not
included and \fIbadblock_count\fP property may include blocks that are
located in metadata, or unused capacity in the namespace. Convert
a \fIsector\fP namespace into \fIraw\fP mode to list precise \fIbadblocks\fP
offsets.
.RE
.sp
.nf
{
  "dev":"namespace7.0",
  "mode":"raw",
  "size":33554432,
  "blockdev":"pmem7",
  "badblock_count":17,
  "badblocks":[
    {
      "offset":4,
      "length":1
    },
    {
      "offset":32768,
      "length":8
    },
    {
      "offset":65528,
      "length":8
    }
  ]
}
.fi
.br
.sp
\-v, \-\-verbose
.RS 4
Increase verbosity of the output. This can be specified
multiple times to be even more verbose on the informational and
miscellaneous output, and can be used to override omitted flags
for showing specific information.
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB\-v\fP
In addition to the enabled namespaces default output, show the
numa_node, raw_uuid, and bad block media errors.
.br
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB\-vv\fP
Everything \fI\-v\fP provides, plus automatically enable \-\-dimms,
\-\-buses, and \-\-regions.
.br
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB\-vvv\fP
Everything \fI\-vv\fP provides, plus \-\-health, \-\-idle, and \-\-firmware.
.RE
.RE
.sp
\-u, \-\-human
.RS 4
Format numbers representing storage sizes, or offsets as human
readable strings with units instead of the default machine\-friendly
raw\-integer data. Convert other numeric fields into hexadecimal strings.
.RE
.sp
.if n .RS 4
.nf
# ndctl list \-\-region=7
{
  "dev":"region7",
  "size":67108864,
  "available_size":67108864,
  "type":"pmem",
  "iset_id":\-6382611090938810793,
  "badblock_count":8
}
.fi
.if n .RE
.sp
.if n .RS 4
.nf
# ndctl list \-\-human \-\-region=7
{
  "dev":"region7",
  "size":"64.00 MiB (67.11 MB)",
  "available_size":"64.00 MiB (67.11 MB)",
  "type":"pmem",
  "iset_id":"0xa76c6907811fae57",
  "badblock_count":8
}
.fi
.if n .RE
.SH "COPYRIGHT"
.sp
Copyright (c) 2016 \- 2018, Intel Corporation. License GPLv2: GNU GPL
version 2 \c
.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.
.SH "SEE ALSO"
.sp
ndctl\-create\-namespace(1)