<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> <meta name="generator" content="AsciiDoc 10.2.0" /> <title>nvme-format(1)</title> <style type="text/css"> /* Shared CSS for AsciiDoc xhtml11 and html5 backends */ /* Default font. */ body { font-family: Georgia,serif; } /* Title font. */ h1, h2, h3, h4, h5, h6, div.title, caption.title, thead, p.table.header, #toctitle, #author, #revnumber, #revdate, #revremark, #footer { font-family: Arial,Helvetica,sans-serif; } body { margin: 1em 5% 1em 5%; } a { color: blue; text-decoration: underline; } a:visited { color: fuchsia; } em { font-style: italic; color: navy; } strong { font-weight: bold; color: #083194; } h1, h2, h3, h4, h5, h6 { color: #527bbd; margin-top: 1.2em; margin-bottom: 0.5em; line-height: 1.3; } h1, h2, h3 { border-bottom: 2px solid silver; } h2 { padding-top: 0.5em; } h3 { float: left; } h3 + * { clear: left; } h5 { font-size: 1.0em; } div.sectionbody { margin-left: 0; } hr { border: 1px solid silver; } p { margin-top: 0.5em; margin-bottom: 0.5em; } ul, ol, li > p { margin-top: 0; } ul > li { color: #aaa; } ul > li > * { color: black; } .monospaced, code, pre { font-family: "Courier New", Courier, monospace; font-size: inherit; color: navy; padding: 0; margin: 0; } pre { white-space: pre-wrap; } #author { color: #527bbd; font-weight: bold; font-size: 1.1em; } #email { } #revnumber, #revdate, #revremark { } #footer { font-size: small; border-top: 2px solid silver; padding-top: 0.5em; margin-top: 4.0em; } #footer-text { float: left; padding-bottom: 0.5em; } #footer-badges { float: right; padding-bottom: 0.5em; } #preamble { margin-top: 1.5em; margin-bottom: 1.5em; } div.imageblock, div.exampleblock, div.verseblock, div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, div.admonitionblock { margin-top: 1.0em; margin-bottom: 1.5em; } div.admonitionblock { margin-top: 2.0em; margin-bottom: 2.0em; margin-right: 10%; color: #606060; } div.content { /* Block element content. */ padding: 0; } /* Block element titles. */ div.title, caption.title { color: #527bbd; font-weight: bold; text-align: left; margin-top: 1.0em; margin-bottom: 0.5em; } div.title + * { margin-top: 0; } td div.title:first-child { margin-top: 0.0em; } div.content div.title:first-child { margin-top: 0.0em; } div.content + div.title { margin-top: 0.0em; } div.sidebarblock > div.content { background: #ffffee; border: 1px solid #dddddd; border-left: 4px solid #f0f0f0; padding: 0.5em; } div.listingblock > div.content { border: 1px solid #dddddd; border-left: 5px solid #f0f0f0; background: #f8f8f8; padding: 0.5em; } div.quoteblock, div.verseblock { padding-left: 1.0em; margin-left: 1.0em; margin-right: 10%; border-left: 5px solid #f0f0f0; color: #888; } div.quoteblock > div.attribution { padding-top: 0.5em; text-align: right; } div.verseblock > pre.content { font-family: inherit; font-size: inherit; } div.verseblock > div.attribution { padding-top: 0.75em; text-align: left; } /* DEPRECATED: Pre version 8.2.7 verse style literal block. */ div.verseblock + div.attribution { text-align: left; } div.admonitionblock .icon { vertical-align: top; font-size: 1.1em; font-weight: bold; text-decoration: underline; color: #527bbd; padding-right: 0.5em; } div.admonitionblock td.content { padding-left: 0.5em; border-left: 3px solid #dddddd; } div.exampleblock > div.content { border-left: 3px solid #dddddd; padding-left: 0.5em; } div.imageblock div.content { padding-left: 0; } span.image img { border-style: none; vertical-align: text-bottom; } a.image:visited { color: white; } dl { margin-top: 0.8em; margin-bottom: 0.8em; } dt { margin-top: 0.5em; margin-bottom: 0; font-style: normal; color: navy; } dd > *:first-child { margin-top: 0.1em; } ul, ol { list-style-position: outside; } ol.arabic { list-style-type: decimal; } ol.loweralpha { list-style-type: lower-alpha; } ol.upperalpha { list-style-type: upper-alpha; } ol.lowerroman { list-style-type: lower-roman; } ol.upperroman { list-style-type: upper-roman; } div.compact ul, div.compact ol, div.compact p, div.compact p, div.compact div, div.compact div { margin-top: 0.1em; margin-bottom: 0.1em; } tfoot { font-weight: bold; } td > div.verse { white-space: pre; } div.hdlist { margin-top: 0.8em; margin-bottom: 0.8em; } div.hdlist tr { padding-bottom: 15px; } dt.hdlist1.strong, td.hdlist1.strong { font-weight: bold; } td.hdlist1 { vertical-align: top; font-style: normal; padding-right: 0.8em; color: navy; } td.hdlist2 { vertical-align: top; } div.hdlist.compact tr { margin: 0; padding-bottom: 0; } .comment { background: yellow; } .footnote, .footnoteref { font-size: 0.8em; } span.footnote, span.footnoteref { vertical-align: super; } #footnotes { margin: 20px 0 20px 0; padding: 7px 0 0 0; } #footnotes div.footnote { margin: 0 0 5px 0; } #footnotes hr { border: none; border-top: 1px solid silver; height: 1px; text-align: left; margin-left: 0; width: 20%; min-width: 100px; } div.colist td { padding-right: 0.5em; padding-bottom: 0.3em; vertical-align: top; } div.colist td img { margin-top: 0.3em; } @media print { #footer-badges { display: none; } } #toc { margin-bottom: 2.5em; } #toctitle { color: #527bbd; font-size: 1.1em; font-weight: bold; margin-top: 1.0em; margin-bottom: 0.1em; } div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { margin-top: 0; margin-bottom: 0; } div.toclevel2 { margin-left: 2em; font-size: 0.9em; } div.toclevel3 { margin-left: 4em; font-size: 0.9em; } div.toclevel4 { margin-left: 6em; font-size: 0.9em; } span.aqua { color: aqua; } span.black { color: black; } span.blue { color: blue; } span.fuchsia { color: fuchsia; } span.gray { color: gray; } span.green { color: green; } span.lime { color: lime; } span.maroon { color: maroon; } span.navy { color: navy; } span.olive { color: olive; } span.purple { color: purple; } span.red { color: red; } span.silver { color: silver; } span.teal { color: teal; } span.white { color: white; } span.yellow { color: yellow; } span.aqua-background { background: aqua; } span.black-background { background: black; } span.blue-background { background: blue; } span.fuchsia-background { background: fuchsia; } span.gray-background { background: gray; } span.green-background { background: green; } span.lime-background { background: lime; } span.maroon-background { background: maroon; } span.navy-background { background: navy; } span.olive-background { background: olive; } span.purple-background { background: purple; } span.red-background { background: red; } span.silver-background { background: silver; } span.teal-background { background: teal; } span.white-background { background: white; } span.yellow-background { background: yellow; } span.big { font-size: 2em; } span.small { font-size: 0.6em; } span.underline { text-decoration: underline; } span.overline { text-decoration: overline; } span.line-through { text-decoration: line-through; } div.unbreakable { page-break-inside: avoid; } /* * xhtml11 specific * * */ div.tableblock { margin-top: 1.0em; margin-bottom: 1.5em; } div.tableblock > table { border: 3px solid #527bbd; } thead, p.table.header { font-weight: bold; color: #527bbd; } p.table { margin-top: 0; } /* Because the table frame attribute is overridden by CSS in most browsers. */ div.tableblock > table[frame="void"] { border-style: none; } div.tableblock > table[frame="hsides"] { border-left-style: none; border-right-style: none; } div.tableblock > table[frame="vsides"] { border-top-style: none; border-bottom-style: none; } /* * html5 specific * * */ table.tableblock { margin-top: 1.0em; margin-bottom: 1.5em; } thead, p.tableblock.header { font-weight: bold; color: #527bbd; } p.tableblock { margin-top: 0; } table.tableblock { border-width: 3px; border-spacing: 0px; border-style: solid; border-color: #527bbd; border-collapse: collapse; } th.tableblock, td.tableblock { border-width: 1px; padding: 4px; border-style: solid; border-color: #527bbd; } table.tableblock.frame-topbot { border-left-style: hidden; border-right-style: hidden; } table.tableblock.frame-sides { border-top-style: hidden; border-bottom-style: hidden; } table.tableblock.frame-none { border-style: hidden; } th.tableblock.halign-left, td.tableblock.halign-left { text-align: left; } th.tableblock.halign-center, td.tableblock.halign-center { text-align: center; } th.tableblock.halign-right, td.tableblock.halign-right { text-align: right; } th.tableblock.valign-top, td.tableblock.valign-top { vertical-align: top; } th.tableblock.valign-middle, td.tableblock.valign-middle { vertical-align: middle; } th.tableblock.valign-bottom, td.tableblock.valign-bottom { vertical-align: bottom; } /* * manpage specific * * */ body.manpage h1 { padding-top: 0.5em; padding-bottom: 0.5em; border-top: 2px solid silver; border-bottom: 2px solid silver; } body.manpage h2 { border-style: none; } body.manpage div.sectionbody { margin-left: 3em; } @media print { body.manpage div#toc { display: none; } } </style> <script type="text/javascript"> /*<+'])'); // Function that scans the DOM tree for header elements (the DOM2 // nodeIterator API would be a better technique but not supported by all // browsers). var iterate = function (el) { for (var i = el.firstChild; i != null; i = i.nextSibling) { if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { var mo = re.exec(i.tagName); if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { result[result.length] = new TocEntry(i, getText(i), mo[1]-1); } iterate(i); } } } iterate(el); return result; } var toc = document.getElementById("toc"); if (!toc) { return; } // Delete existing TOC entries in case we're reloading the TOC. var tocEntriesToRemove = []; var i; for (i = 0; i < toc.childNodes.length; i++) { var entry = toc.childNodes[i]; if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") && entry.getAttribute("class").match(/^toclevel/)) tocEntriesToRemove.push(entry); } for (i = 0; i < tocEntriesToRemove.length; i++) { toc.removeChild(tocEntriesToRemove[i]); } // Rebuild TOC entries. var entries = tocEntries(document.getElementById("content"), toclevels); for (var i = 0; i < entries.length; ++i) { var entry = entries[i]; if (entry.element.id == "") entry.element.id = "_toc_" + i; var a = document.createElement("a"); a.href = "#" + entry.element.id; a.appendChild(document.createTextNode(entry.text)); var div = document.createElement("div"); div.appendChild(a); div.className = "toclevel" + entry.toclevel; toc.appendChild(div); } if (entries.length == 0) toc.parentNode.removeChild(toc); }, ///////////////////////////////////////////////////////////////////// // Footnotes generator ///////////////////////////////////////////////////////////////////// /* Based on footnote generation code from: * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html */ footnotes: function () { // Delete existing footnote entries in case we're reloading the footnodes. var i; var noteholder = document.getElementById("footnotes"); if (!noteholder) { return; } var entriesToRemove = []; for (i = 0; i < noteholder.childNodes.length; i++) { var entry = noteholder.childNodes[i]; if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote") entriesToRemove.push(entry); } for (i = 0; i < entriesToRemove.length; i++) { noteholder.removeChild(entriesToRemove[i]); } // Rebuild footnote entries. var cont = document.getElementById("content"); var spans = cont.getElementsByTagName("span"); var refs = {}; var n = 0; for (i=0; i<spans.length; i++) { if (spans[i].className == "footnote") { n++; var note = spans[i].getAttribute("data-note"); if (!note) { // Use [\s\S] in place of . so multi-line matches work. // Because JavaScript has no s (dotall) regex flag. note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; spans[i].innerHTML = "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + "' title='View footnote' class='footnote'>" + n + "</a>]"; spans[i].setAttribute("data-note", note); } noteholder.innerHTML += "<div class='footnote' id='_footnote_" + n + "'>" + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + n + "</a>. " + note + "</div>"; var id =spans[i].getAttribute("id"); if (id != null) refs["#"+id] = n; } } if (n == 0) noteholder.parentNode.removeChild(noteholder); else { // Process footnoterefs. for (i=0; i<spans.length; i++) { if (spans[i].className == "footnoteref") { var href = spans[i].getElementsByTagName("a")[0].getAttribute("href"); href = href.match(/#.*/)[0]; // Because IE return full URL. n = refs[href]; spans[i].innerHTML = "[<a href='#_footnote_" + n + "' title='View footnote' class='footnote'>" + n + "</a>]"; } } } }, install: function(toclevels) { var timerId; function reinstall() { asciidoc.footnotes(); if (toclevels) { asciidoc.toc(toclevels); } } function reinstallAndRemoveTimer() { clearInterval(timerId); reinstall(); } timerId = setInterval(reinstall, 500); if (document.addEventListener) document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false); else window.onload = reinstallAndRemoveTimer; } } asciidoc.install(); /*]]>*/ </script> </head> <body class="manpage"> <div id="header"> <h1> nvme-format(1) Manual Page </h1> <h2>NAME</h2> <div class="sectionbody"> <p>nvme-format - Format an NVMe device </p> </div> </div> <div id="content"> <div class="sect1"> <h2 id="_synopsis">SYNOPSIS</h2> <div class="sectionbody"> <div class="verseblock"> <pre class="content"><em>nvme format</em> <device> [--namespace-id=<nsid> | -n <nsid>] [--lbaf=<lbaf> | -l <lbaf>] [--block-size=<block size | -b <block size>] [--ses=<ses> | -s <ses>] [--pil=<pil> | -p <pil>] [--pi=<pi> | -i <pi>] [--ms=<ms> | -m <ms>] [--reset | -r] [--force] [--timeout=<timeout> | -t <timeout>] [--output-format=<fmt> | -o <fmt>] [--verbose | -v]</pre> <div class="attribution"> </div></div> </div> </div> <div class="sect1"> <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> <div class="paragraph"><p>For the NVMe device given, send an nvme Format Namespace admin command and provides the results.</p></div> <div class="paragraph"><p>The <device> parameter is mandatory and may be either the NVMe character device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). If the character device is given, and the controller does not support formatting of particular namespaces (ID_CTRL.FNA bit 0 enabled), then all namespaces will be formatted. If FNA is disabled, then the namespace identifier must be specified with the <em>namespace-id</em> option; specify a value of 0xffffffff to send the format to all namespaces. If the block device is given, the namespace identifier will default to the namespace ID of the block device given, but can be overridden with the same option.</p></div> <div class="paragraph"><p>Note, the numeric suffix on the character device, for example the <em>0</em> in /dev/nvme0, does NOT indicate this device handle is the parent controller of any namespaces with the same suffix. The namespace handle’s numeral may be coming from the subsystem identifier, which is independent of the controller’s identifier. Do not assume any particular device relationship based on their names. If you do, you may irrevocably erase data on an unintended device.</p></div> <div class="paragraph"><p>On success, the program will automatically issue BLKRRPART ioctl to force rescanning the namespaces. If the driver is recent enough, this will automatically update the physical block size. If it is not recent enough, you will need to remove and rescan your device some other way for the new block size to be visible, if the size was changed with this command.</p></div> </div> </div> <div class="sect1"> <h2 id="_options">OPTIONS</h2> <div class="sectionbody"> <div class="dlist"><dl> <dt class="hdlist1"> -n <nsid> </dt> <dt class="hdlist1"> --namespace-id=<nsid> </dt> <dd> <p> Send the format command for the specified nsid. This can be used to override the default value for either character device (unspecified) or the block device (result from NVME_IOCTL_ID). </p> </dd> <dt class="hdlist1"> -l <lbaf> </dt> <dt class="hdlist1"> --lbaf=<lbaf> </dt> <dd> <p> LBA Format: This field specifies the LBA format to apply to the NVM media. This corresponds to the LBA formats indicated in the Identify Namespace command. Conflicts with --block-size argument. Defaults to 0. </p> </dd> <dt class="hdlist1"> -b <block size> </dt> <dt class="hdlist1"> --block-size=<block size> </dt> <dd> <p> Block Size: This field is used to specify the target block size to format to. Potential lbaf values will be scanned and the lowest numbered will be selected for the format operation. Conflicts with --lbaf argument. </p> </dd> <dt class="hdlist1"> -s <ses> </dt> <dt class="hdlist1"> --ses=<ses> </dt> <dd> <p> Secure Erase Settings: This field specifies whether a secure erase should be performed as part of the format and the type of the secure erase operation. The erase applies to all user data, regardless of location (e.g., within an exposed LBA, within a cache, within deallocated LBAs, etc). Defaults to 0. </p> <div class="tableblock"> <table rules="all" width="100%" frame="border" cellspacing="0" cellpadding="4"> <col width="50%" /> <col width="50%" /> <tbody> <tr> <td align="left" valign="top"><p class="table">Value</p></td> <td align="left" valign="top"><p class="table">Definition</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">0</p></td> <td align="left" valign="top"><p class="table">No secure erase operation requested</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">1</p></td> <td align="left" valign="top"><p class="table">User Data Erase: All user data shall be erased, contents of the user data after the erase is indeterminate (e.g., the user data may be zero filled, one filled, etc). The controller may perform a cryptographic erase when a User Data Erase is requested if all user data is encrypted.</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">2</p></td> <td align="left" valign="top"><p class="table">Cryptographic Erase: All user data shall be erased cryptographically. This is accomplished by deleting the encryption key.</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">3–7</p></td> <td align="left" valign="top"><p class="table">Reserved</p></td> </tr> </tbody> </table> </div> </dd> <dt class="hdlist1"> -p <pil> </dt> <dt class="hdlist1"> --pil=<pil> </dt> <dd> <p> Protection Information Location: If set to ‘1’ and protection information is enabled, then protection information is transferred as the first eight bytes of metadata. If cleared to ‘0’ and protection information is enabled, then protection information is transferred as the last eight bytes of metadata. Defaults to 0. </p> </dd> <dt class="hdlist1"> -i <pi> </dt> <dt class="hdlist1"> --pi=<pi> </dt> <dd> <p> Protection Information: This field specifies whether end-to-end data protection is enabled and the type of protection information. Defaults to 0. </p> <div class="tableblock"> <table rules="all" width="100%" frame="border" cellspacing="0" cellpadding="4"> <col width="50%" /> <col width="50%" /> <tbody> <tr> <td align="left" valign="top"><p class="table">Value</p></td> <td align="left" valign="top"><p class="table">Definition</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">0</p></td> <td align="left" valign="top"><p class="table">Protection information is not enabled</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">1</p></td> <td align="left" valign="top"><p class="table">Protection information is enabled, Type 1</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">2</p></td> <td align="left" valign="top"><p class="table">Protection information is enabled, Type 2</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">3</p></td> <td align="left" valign="top"><p class="table">Protection information is enabled, Type 3</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">4–7</p></td> <td align="left" valign="top"><p class="table">Reserved</p></td> </tr> </tbody> </table> </div> </dd> <dt class="hdlist1"> -m <ms> </dt> <dt class="hdlist1"> --ms=<ms> </dt> <dd> <p> Metadata Settings: This field is set to ‘1’ if the metadata is transferred as part of an extended data LBA. This field is cleared to ‘0’ if the metadata is transferred as part of a separate buffer. The metadata may include protection information, based on the Protection Information (PI) field. Defaults to 0. </p> </dd> <dt class="hdlist1"> -r </dt> <dt class="hdlist1"> --reset </dt> <dd> <p> Issue a reset after successful format. Must use the character device for this. </p> </dd> <dt class="hdlist1"> --force </dt> <dd> <p> Just send the command immediately without warning of the implications. </p> </dd> <dt class="hdlist1"> -t <timeout> </dt> <dt class="hdlist1"> --timeout=<timeout> </dt> <dd> <p> Override default timeout value. In milliseconds. </p> </dd> <dt class="hdlist1"> -o <fmt> </dt> <dt class="hdlist1"> --output-format=<fmt> </dt> <dd> <p> Set the reporting format to <em>normal</em>, <em>json</em> or <em>binary</em>. Only one output format can be used at a time. </p> </dd> <dt class="hdlist1"> -v </dt> <dt class="hdlist1"> --verbose </dt> <dd> <p> Increase the information detail in the output. </p> </dd> </dl></div> </div> </div> <div class="sect1"> <h2 id="_examples">EXAMPLES</h2> <div class="sectionbody"> <div class="ulist"><ul> <li> <p> Format the device using all defaults: </p> <div class="listingblock"> <div class="content"> <pre><code># nvme format /dev/nvme0n1</code></pre> </div></div> </li> <li> <p> Format namespace 1 with user data secure erase settings and protection information: </p> <div class="listingblock"> <div class="content"> <pre><code># nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1</code></pre> </div></div> </li> </ul></div> </div> </div> <div class="sect1"> <h2 id="_nvme">NVME</h2> <div class="sectionbody"> <div class="paragraph"><p>Part of the nvme-user suite</p></div> </div> </div> </div> <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> Last updated 2024-05-03 16:03:16 CEST </div> </div> </body> </html>