// SPDX-License-Identifier: GPL-2.0

ndctl-write-infoblock(1)
========================

NAME
----
ndctl-write-infoblock - generate and write an infoblock

SYNOPSIS
--------
[verse]
'ndctl write-infoblock' [<namespaceX.Y> | -o <file> | --stdout] [<options>]

DESCRIPTION
-----------
As described in the theory of operation section of
linkndctl:ndctl-create-namespace[1], the raw capacity of a namespace may
encapsulate a personality, or mode of operation. Specifically, the mode
may be set to one of "sector", "fsdax", and "devdax". Each of those
modes is defined by an info-block format that uniquely identifies the
mode of operation. The write-infoblock command knows how to generate an
"fsdax" or "devdax" info-block relative to the specified image size.

The generated block can be written to an existing namespace (provided
that namespace is not presently active), written to a file, or piped to
standard-out.

WARNING: This command is a debug facility that can generate image files
with valid infoblocks, but also invalid infoblocks for testing the
kernel. Use the --offset and --align options with care. Namely --offset
must match the actual physical address offset of the namespace it is
applied to, and --align must be one of the architectures supported page
sizes.

EXAMPLE
-------

[verse]
ndctl write-infoblock -s 1T -c | ndctl read-infoblock -j
wrote 1 infoblock
[
  {
    "file":"<stdin>",
    "signature":"NVDIMM_PFN_INFO",
    "uuid":"42e1d574-76ac-402c-9132-5436e31528c0",
    "parent_uuid":"ef83e49c-4c4a-4fae-b908-72e94675b1b7",
    "flags":0,
    "version":"1.4",
    "dataoff":17196646400,
    "npfns":264237056,
    "mode":2,
    "start_pad":0,
    "end_trunc":0,
    "align":16777216,
    "page_size":4096,
    "page_struct_size":64
  }
]
read 1 infoblock

OPTIONS
-------
<namespace(s)>::
	One or more 'namespaceX.Y' device names. The keyword 'all' can be specified to
	operate on every namespace in the system, optionally filtered by bus id (see
        --bus= option), or region id (see --region= option).

-c::
--stdout::
	Write the infoblock to stdout

-o::
--output=::
	Write the infoblock to the given file (mutually
	exclusive with --stdout).

-m::
--mode=::
	Select the infoblock mode between 'fsdax' and 'devdax'. See
	linkndctl:ndctl-create-namespace[1] for details on --mode.

-s::
--size=::
	Override the default size determined from the size of the file
	specified to --output. In the --stdout case, this option is
	required.

-a::
--align=::
	Specify the "align" value in the infoblock. In the --mode=devdax
	case "align" designates a page mapping size. There is no
	validation of this value relative to the page mapping
	capabilities of the platform.

-u::
--uuid=::
	Override the default autogenerated UUID with the given
	value.

-M::
--map=::
	Select whether the page map array is allocated from the
	device or from "System RAM". Defaults to the device. See
	linkndctl:ndctl-create-namespace[1] for more details.

-p::
--parent-uuid=::
	When the infoblock is stored on a labelled namespace the UUID of
	the namespace must match the "parent uuid" attribute in the
	infoblock. This option defaults to the UUID of the namespace
	when --output and --stdout are not used, otherwise it defaults
	to a NULL UUID (all zeroes).

-O::
--offset=::
	By default the assumption is that the infoblock is being written
	to a namespace or namespace-image that is aligned to its size.
	Specify this EXPERT/DEBUG option to experiment / test the
	kernel's handling of namespaces that violate that assumption.

-r::
--region=::
include::xable-region-options.txt[]

include::../copyright.txt[]

SEE ALSO
--------
linkndctl:ndctl-create-namespace[1],
http://www.uefi.org/sites/default/files/resources/UEFI_Spec_2_7.pdf[UEFI NVDIMM Label Protocol]

