@@ -1,4 +1,5 @@
*.o
+*.xml
.deps/
.libs/
Makefile
new file mode 100644
@@ -0,0 +1,26 @@
+man1_MANS = \
+ ndctl.1 \
+ ndctl-zero-labels.1 \
+ ndctl-enable-region.1 \
+ ndctl-disable-region.1 \
+ ndctl-enable-namespace.1 \
+ ndctl-disable-namespace.1
+
+XML_DEPS = \
+ $(top_srcdir)/version.m4 \
+ Makefile \
+ region-description.txt \
+ xable-region-options.txt \
+ xable-namespace-options.txt
+
+RM ?= rm -f
+
+%.xml: %.txt $(XML_DEPS)
+ $(AM_V_GEN)$(RM) $@+ $@ && \
+ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
+ --unsafe -andctl_version=$(VERSION) -o $@+ $< && \
+ mv $@+ $@
+
+%.1: %.xml
+ $(AM_V_GEN)$(RM) $@ && \
+ $(XMLTO) -o . -m manpage-normal.xsl man $<
new file mode 100644
@@ -0,0 +1,91 @@
+## linkndctl: macro
+#
+# Usage: linkndctl:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show PERF link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linkndctl):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[attributes]
+asterisk=*
+plus=+
+caret=^
+startsb=[
+endsb=]
+tilde=~
+
+ifdef::backend-docbook[]
+[linkndctl-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+ifndef::ndctl-asciidoc-no-roff[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+# v1.72 breaks with this because it replaces dots not in roff requests.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+ifdef::doctype-manpage[]
+ .ft C
+endif::doctype-manpage[]
+|
+ifdef::doctype-manpage[]
+ .ft
+endif::doctype-manpage[]
+</literallayout>
+{title#}</example>
+endif::ndctl-asciidoc-no-roff[]
+
+ifdef::ndctl-asciidoc-no-roff[]
+ifdef::doctype-manpage[]
+# The following two small workarounds insert a simple paragraph after screen
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout><simpara></simpara>
+{title#}</example>
+
+[verseblock]
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+{title#}<literallayout>
+|
+</literallayout>
+{title#}</para></formalpara>
+{title%}<simpara></simpara>
+endif::doctype-manpage[]
+endif::ndctl-asciidoc-no-roff[]
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">ndctl</refmiscinfo>
+<refmiscinfo class="version">{ndctl_version}</refmiscinfo>
+<refmiscinfo class="manual">ndctl Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[linkndctl-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
new file mode 100644
@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+ special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format;
+ git.docbook.backslash and git.docbook.dot params
+ must be supplied by another XSL file or other means -->
+<xsl:template match="co">
+ <xsl:value-of select="concat(
+ $git.docbook.backslash,'fB(',
+ substring-after(@id,'-'),')',
+ $git.docbook.backslash,'fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+ <xsl:value-of select="$git.docbook.dot"/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+ <xsl:value-of select="concat(
+ $git.docbook.backslash,'fB',
+ substring-after(@arearefs,'-'),
+ '. ',$git.docbook.backslash,'fR')"/>
+ <xsl:apply-templates/>
+ <xsl:value-of select="$git.docbook.dot"/>
+ <xsl:text>br </xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
new file mode 100644
@@ -0,0 +1,13 @@
+<!-- manpage-normal.xsl:
+ special settings for manpages rendered from asciidoc+docbook
+ handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot" >.</xsl:param>
+
+</xsl:stylesheet>
new file mode 100644
@@ -0,0 +1,6 @@
+DESCRIPTION
+-----------
+A REGION, after resolving DPA aliasing and LABEL specified boundaries,
+surfaces one or more "namespace" devices. The arrival of a "namespace"
+device currently triggers either the nd_blk or nd_pmem driver to load
+and register a disk/block device.
new file mode 100644
@@ -0,0 +1,21 @@
+ndctl-disable-namespace(1)
+=========================
+
+NAME
+----
+ndctl-disable-namespace - disable the given namespace(s)
+
+SYNOPSIS
+--------
+[verse]
+'ndctl disable-namespace' <namespace> [<options>]
+
+include::namespace-description.txt[]
+
+OPTIONS
+-------
+include::xable-namespace-options.txt[]
+
+SEE ALSO
+--------
+linkndctl:ndctl-disable-namespace[1]
new file mode 100644
@@ -0,0 +1,22 @@
+ndctl-disable-region(1)
+=======================
+
+NAME
+----
+ndctl-disable-region - disable the given region(s) and all descendant namespaces
+
+SYNOPSIS
+--------
+[verse]
+'ndctl disable-region' <region> [<options>]
+
+include::region-description.txt[]
+
+OPTIONS
+-------
+<region>::
+include::xable-region-options.txt[]
+
+SEE ALSO
+--------
+linkndctl:ndctl-enable-region[1]
new file mode 100644
@@ -0,0 +1,21 @@
+ndctl-enable-namespace(1)
+=========================
+
+NAME
+----
+ndctl-enable-namespace - enable the given namespace(s)
+
+SYNOPSIS
+--------
+[verse]
+'ndctl enable-namespace' <namespace> [<options>]
+
+include::namespace-description.txt[]
+
+OPTIONS
+-------
+include::xable-namespace-options.txt[]
+
+SEE ALSO
+--------
+linkndctl:ndctl-disable-namespace[1]
new file mode 100644
@@ -0,0 +1,22 @@
+ndctl-enable-region(1)
+====================
+
+NAME
+----
+ndctl-enable-region - enable the given region(s) and all descendant namespaces
+
+SYNOPSIS
+--------
+[verse]
+'ndctl enable-region' <region> [<options>]
+
+include::region-description.txt[]
+
+OPTIONS
+-------
+<region>::
+include::xable-region-options.txt[]
+
+SEE ALSO
+--------
+linkndctl:ndctl-disable-region[1]
new file mode 100644
@@ -0,0 +1,41 @@
+ndctl-zero-labels(1)
+====================
+
+NAME
+----
+ndctl-zero-labels - zero out the label area on a dimm or set of dimms
+
+SYNOPSIS
+--------
+[verse]
+'ndctl zero-labels' <nmem0> [<nmem1>..<nmemN>] [<options>]
+
+DESCRIPTION
+-----------
+The namespace label area is a small persistent partition of capacity
+available on some NVDIMM devices. The label area is used to resolve
+aliasing between 'pmem' and 'blk' capacity by lineating namespace
+boundaries. This command resets the device to its default state by
+deleting all labels.
+
+OPTIONS
+-------
+
+<memory device(s)>...::
+ One or more 'nmemX' device names. The keyword 'all' can be specified to
+ zero every dimm in the system, optionally filtered by bus id (see --bus=
+ option).
+
+-b::
+--bus=::
+ Limit zeroing to memory devices (dimms) that are on the given bus.
+ Where 'bus' can be a provider name or a bus id number.
+
+-v::
+ Turn on verbose debug messages in the library (if ndctl was built with
+ logging and debug enabled).
+
+SEE ALSO
+--------
+http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf[NVDIMM Namespace
+Specification]
new file mode 100644
@@ -0,0 +1,43 @@
+ndctl(1)
+=======
+
+NAME
+----
+ndctl - Manage "libnvdimm" subsystem devices (Non-volatile Memory)
+
+SYNOPSIS
+--------
+[verse]
+'ndctl' [--version] [--help] [OPTIONS] COMMAND [ARGS]
+
+OPTIONS
+-------
+-v::
+--version::
+ Display ndctl version.
+
+-h::
+--help::
+ Run ndctl help command.
+
+DESCRIPTION
+-----------
+ndctl is utility for managing the "libnvdimm" kernel subsystem.
+The "libnvdimm" subsystem defines a kernel device model and control
+message interface for platform NVDIMM resources like those defined by
+the ACPI 6.0 NFIT (NVDIMM Firmware Interface Table). Operations
+supported by the tool include, provisioning capacity (namespaces), as
+well as enumerating/enabling/disabling the devices (dimms, regions,
+namspaces) associated with an NVDIMM bus.
+
+SEE ALSO
+--------
+linkndctl:ndctl-zero-labels[1],
+linkndctl:ndctl-enable-region[1],
+linkndctl:ndctl-disable-region[1],
+linkndctl:ndctl-enable-namespace[1],
+linkndctl:ndctl-disable-namespace[1],
+https://www.kernel.org/doc/Documentation/nvdimm/nvdimm.txt[LIBNVDIMM
+Overview],
+http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf[NVDIMM Driver
+Writer's Guide]
new file mode 100644
@@ -0,0 +1,8 @@
+DESCRIPTION
+-----------
+A generic REGION device is registered for each PMEM range or
+BLK-aperture set. LIBNVDIMM provides a built-in driver for these REGION
+devices. This driver is responsible for reconciling the aliased DPA
+mappings across all regions, parsing the LABEL, if present, and then
+emitting NAMESPACE devices with the resolved/exclusive DPA-boundaries
+for the nd_pmem or nd_blk device driver to consume.
new file mode 100644
@@ -0,0 +1,8 @@
+<namespace>::
+A 'namespaceX.Y' device name. The keyword 'all' can be specified to carry out
+the operation on every namespace in the system, optionally filtered by region
+(see --region=option)
+
+-r::
+--region=::
+include::xable-region-options.txt[]
new file mode 100644
@@ -0,0 +1,9 @@
+ A 'regionX' device name, or a region id number. The keyword 'all' can
+ be specified to carry out the operation on every region in the system,
+ optionally filtered by bus id (see --bus= option).
+
+-b::
+--bus=::
+ Enforce that the operation only be carried on devices that are
+ attached to the given bus. Where 'bus' can be a provider name or a bus
+ id number.
@@ -1,4 +1,5 @@
EXTRA_DIST =
+SUBDIRS = . Documentation
CLEANFILES =
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
AM_MAKEFLAGS = --no-print-directory
@@ -32,6 +32,16 @@ AC_PREFIX_DEFAULT([/usr])
AC_PROG_SED
AC_PROG_MKDIR_P
+AC_CHECK_PROG(ASCIIDOC, [asciidoc], [$(which asciidoc)], [missing])
+if test "x$ASCIIDOC" = xmissing; then
+ AC_MSG_ERROR([asciidoc needed to build documentation])
+fi
+AC_SUBST([ASCIIDOC])
+AC_CHECK_PROG(XMLTO, [xmlto], [$(which xmlto)], [missing])
+if test "x$XMLTO" = xmissing; then
+ AC_MSG_ERROR([xmlto needed to build documentation])
+fi
+AC_SUBST([XMLTO])
AC_C_TYPEOF
AC_DEFINE([HAVE_STATEMENT_EXPR], 1, [Define to 1 if you have statement expressions.])
@@ -130,6 +140,7 @@ AC_SUBST([my_CFLAGS])
AC_CONFIG_HEADERS(config.h)
AC_CONFIG_FILES([
Makefile
+ Documentation/Makefile
])
AC_OUTPUT
@@ -13,6 +13,8 @@ Url: https://github.com/pmem/ndctl
Source0: %{name}-git%{gitcommit}.tar.xz
BuildRequires: autoconf
+BuildRequires: asciidoc
+BuildRequires: xmlto
BuildRequires: automake
BuildRequires: libtool
BuildRequires: pkgconfig
@@ -70,6 +72,7 @@ make check
%defattr(-,root,root)
%license licenses/GPLv2 licenses/BSD-MIT licenses/CC0
%{_bindir}/ndctl
+%{_mandir}/man1/*
%files -n %lname
%defattr(-,root,root)
Adopt the asciidoc and xmlto collateral from perf to generate ndctl man pages. Signed-off-by: Dan Williams <dan.j.williams@intel.com> --- .gitignore | 1 Documentation/Makefile.am | 26 ++++++++ Documentation/asciidoc.conf | 91 +++++++++++++++++++++++++++++ Documentation/manpage-base.xsl | 35 +++++++++++ Documentation/manpage-normal.xsl | 13 ++++ Documentation/namespace-description.txt | 6 ++ Documentation/ndctl-disable-namespace.txt | 21 +++++++ Documentation/ndctl-disable-region.txt | 22 +++++++ Documentation/ndctl-enable-namespace.txt | 21 +++++++ Documentation/ndctl-enable-region.txt | 22 +++++++ Documentation/ndctl-zero-labels.txt | 41 +++++++++++++ Documentation/ndctl.txt | 43 ++++++++++++++ Documentation/region-description.txt | 8 +++ Documentation/xable-namespace-options.txt | 8 +++ Documentation/xable-region-options.txt | 9 +++ Makefile.am | 1 configure.ac | 11 ++++ contrib/ndctl.spec.in | 3 + 18 files changed, 382 insertions(+) create mode 100644 Documentation/Makefile.am create mode 100644 Documentation/asciidoc.conf create mode 100644 Documentation/manpage-base.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/namespace-description.txt create mode 100644 Documentation/ndctl-disable-namespace.txt create mode 100644 Documentation/ndctl-disable-region.txt create mode 100644 Documentation/ndctl-enable-namespace.txt create mode 100644 Documentation/ndctl-enable-region.txt create mode 100644 Documentation/ndctl-zero-labels.txt create mode 100644 Documentation/ndctl.txt create mode 100644 Documentation/region-description.txt create mode 100644 Documentation/xable-namespace-options.txt create mode 100644 Documentation/xable-region-options.txt