From patchwork Thu Jan 28 22:52:13 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Williams X-Patchwork-Id: 8154781 Return-Path: X-Original-To: patchwork-linux-nvdimm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 87029BEEE5 for ; Thu, 28 Jan 2016 22:52:44 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id EFA24202FE for ; Thu, 28 Jan 2016 22:52:42 +0000 (UTC) Received: from ml01.01.org (ml01.01.org [198.145.21.10]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 222C7202F8 for ; Thu, 28 Jan 2016 22:52:41 +0000 (UTC) Received: from ml01.vlan14.01.org (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 16BBA1A231C; Thu, 28 Jan 2016 14:52:41 -0800 (PST) X-Original-To: linux-nvdimm@lists.01.org Delivered-To: linux-nvdimm@lists.01.org Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by ml01.01.org (Postfix) with ESMTP id CE3E61A231C for ; Thu, 28 Jan 2016 14:52:39 -0800 (PST) Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga103.jf.intel.com with ESMTP; 28 Jan 2016 14:52:38 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.22,360,1449561600"; d="scan'208";a="736223141" Received: from dwillia2-desk3.jf.intel.com (HELO dwillia2-desk3.amr.corp.intel.com) ([10.54.39.136]) by orsmga003.jf.intel.com with ESMTP; 28 Jan 2016 14:52:38 -0800 Subject: [ndctl PATCH 03/13] ndctl: man pages From: Dan Williams To: linux-nvdimm@lists.01.org Date: Thu, 28 Jan 2016 14:52:13 -0800 Message-ID: <20160128225213.17855.12789.stgit@dwillia2-desk3.amr.corp.intel.com> In-Reply-To: <20160128225157.17855.5190.stgit@dwillia2-desk3.amr.corp.intel.com> References: <20160128225157.17855.5190.stgit@dwillia2-desk3.amr.corp.intel.com> User-Agent: StGit/0.17.1-9-g687f MIME-Version: 1.0 X-BeenThere: linux-nvdimm@lists.01.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "Linux-nvdimm developer list." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Adopt the asciidoc and xmlto collateral from perf to generate ndctl man pages. Signed-off-by: Dan Williams --- .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 diff --git a/.gitignore b/.gitignore index 45f6aa481dde..4899534e57e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *.o +*.xml .deps/ .libs/ Makefile diff --git a/Documentation/Makefile.am b/Documentation/Makefile.am new file mode 100644 index 000000000000..bd43714d5215 --- /dev/null +++ b/Documentation/Makefile.am @@ -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 $< diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 000000000000..26a822a17b7b --- /dev/null +++ b/Documentation/asciidoc.conf @@ -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: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinkndctl):(?P\S*?)\[(?P.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[linkndctl-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +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] +{title} + +ifdef::doctype-manpage[] + .ft C +endif::doctype-manpage[] +| +ifdef::doctype-manpage[] + .ft +endif::doctype-manpage[] + +{title#} +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] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::ndctl-asciidoc-no-roff[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +ndctl +{ndctl_version} +ndctl Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linkndctl-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 000000000000..a264fa616093 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 000000000000..a48f5b11f3dc --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + + diff --git a/Documentation/namespace-description.txt b/Documentation/namespace-description.txt new file mode 100644 index 000000000000..0446642bf308 --- /dev/null +++ b/Documentation/namespace-description.txt @@ -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. diff --git a/Documentation/ndctl-disable-namespace.txt b/Documentation/ndctl-disable-namespace.txt new file mode 100644 index 000000000000..067bc76f9148 --- /dev/null +++ b/Documentation/ndctl-disable-namespace.txt @@ -0,0 +1,21 @@ +ndctl-disable-namespace(1) +========================= + +NAME +---- +ndctl-disable-namespace - disable the given namespace(s) + +SYNOPSIS +-------- +[verse] +'ndctl disable-namespace' [] + +include::namespace-description.txt[] + +OPTIONS +------- +include::xable-namespace-options.txt[] + +SEE ALSO +-------- +linkndctl:ndctl-disable-namespace[1] diff --git a/Documentation/ndctl-disable-region.txt b/Documentation/ndctl-disable-region.txt new file mode 100644 index 000000000000..812a00d096f0 --- /dev/null +++ b/Documentation/ndctl-disable-region.txt @@ -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' [] + +include::region-description.txt[] + +OPTIONS +------- +:: +include::xable-region-options.txt[] + +SEE ALSO +-------- +linkndctl:ndctl-enable-region[1] diff --git a/Documentation/ndctl-enable-namespace.txt b/Documentation/ndctl-enable-namespace.txt new file mode 100644 index 000000000000..ece7b7e803e3 --- /dev/null +++ b/Documentation/ndctl-enable-namespace.txt @@ -0,0 +1,21 @@ +ndctl-enable-namespace(1) +========================= + +NAME +---- +ndctl-enable-namespace - enable the given namespace(s) + +SYNOPSIS +-------- +[verse] +'ndctl enable-namespace' [] + +include::namespace-description.txt[] + +OPTIONS +------- +include::xable-namespace-options.txt[] + +SEE ALSO +-------- +linkndctl:ndctl-disable-namespace[1] diff --git a/Documentation/ndctl-enable-region.txt b/Documentation/ndctl-enable-region.txt new file mode 100644 index 000000000000..cd425aa286f2 --- /dev/null +++ b/Documentation/ndctl-enable-region.txt @@ -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' [] + +include::region-description.txt[] + +OPTIONS +------- +:: +include::xable-region-options.txt[] + +SEE ALSO +-------- +linkndctl:ndctl-disable-region[1] diff --git a/Documentation/ndctl-zero-labels.txt b/Documentation/ndctl-zero-labels.txt new file mode 100644 index 000000000000..d5865e34475f --- /dev/null +++ b/Documentation/ndctl-zero-labels.txt @@ -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' [..] [] + +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 +------- + +...:: + 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] diff --git a/Documentation/ndctl.txt b/Documentation/ndctl.txt new file mode 100644 index 000000000000..87d2fbfcbcf9 --- /dev/null +++ b/Documentation/ndctl.txt @@ -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] diff --git a/Documentation/region-description.txt b/Documentation/region-description.txt new file mode 100644 index 000000000000..bc3d12295c01 --- /dev/null +++ b/Documentation/region-description.txt @@ -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. diff --git a/Documentation/xable-namespace-options.txt b/Documentation/xable-namespace-options.txt new file mode 100644 index 000000000000..a5c876180c91 --- /dev/null +++ b/Documentation/xable-namespace-options.txt @@ -0,0 +1,8 @@ +:: +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[] diff --git a/Documentation/xable-region-options.txt b/Documentation/xable-region-options.txt new file mode 100644 index 000000000000..243510cc0742 --- /dev/null +++ b/Documentation/xable-region-options.txt @@ -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. diff --git a/Makefile.am b/Makefile.am index 1a0d294dd34d..d768de1492cd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,5 @@ EXTRA_DIST = +SUBDIRS = . Documentation CLEANFILES = ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS} AM_MAKEFLAGS = --no-print-directory diff --git a/configure.ac b/configure.ac index c1c0f684e35c..5f25b56aca9a 100644 --- a/configure.ac +++ b/configure.ac @@ -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 diff --git a/contrib/ndctl.spec.in b/contrib/ndctl.spec.in index 1b9595050bce..bb224a13b151 100644 --- a/contrib/ndctl.spec.in +++ b/contrib/ndctl.spec.in @@ -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)