[ndctl,v3,19/21] Documentation/cxl: add library API documentation

Message ID	20210701201005.3065299-20-vishal.l.verma@intel.com
State	New, archived
Headers	show Return-Path: <linux-cxl-owner@kernel.org> From: Vishal Verma <vishal.l.verma@intel.com> To: <nvdimm@lists.linux.dev>, <linux-cxl@vger.kernel.org> Cc: Dan Williams <dan.j.williams@intel.com>, Ben Widawsky <ben.widawsky@intel.com>, Alison Schofield <alison.schofield@intel.com>, Ira Weiny <ira.weiny@intel.com>, Vishal Verma <vishal.l.verma@intel.com> Subject: [ndctl PATCH v3 19/21] Documentation/cxl: add library API documentation Date: Thu, 1 Jul 2021 14:10:03 -0600 Message-Id: <20210701201005.3065299-20-vishal.l.verma@intel.com> In-Reply-To: <20210701201005.3065299-1-vishal.l.verma@intel.com> References: <20210701201005.3065299-1-vishal.l.verma@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk
Series	Initial CXL support \| expand [ndctl,v3,00/21] Initial CXL support [ndctl,v3,01/21] ndctl: add .clang-format [ndctl,v3,02/21] cxl: add a cxl utility and libcxl library [ndctl,v3,03/21] cxl: add a local copy of the cxl_mem UAPI header [ndctl,v3,04/21] libcxl: add support for command query and submission [ndctl,v3,05/21] libcxl: add support for the 'Identify Device' command [ndctl,v3,06/21] test: rename 'ndctl_test' to 'test_ctx' [ndctl,v3,07/21] test: rename 'ndctl_test_' helpers to 'test_' [ndctl,v3,08/21] test: introduce a libcxl unit test [ndctl,v3,09/21] libcxl: add GET_HEALTH_INFO mailbox command and accessors [ndctl,v3,10/21] libcxl: add support for the 'GET_LSA' command [ndctl,v3,11/21] util/hexdump: Add a util helper to print a buffer in hex [ndctl,v3,12/21] test/libcxl: add a test for {set, get}_lsa commands [ndctl,v3,13/21] test/libcxl: introduce a command size fuzzing test [ndctl,v3,14/21] libcxl: add lsa_size to cxl_memdev, and an API to retrieve it [ndctl,v3,15/21] libcxl: PLACEHOLDER: add an interface to determine whether a memdev is active [ndctl,v3,16/21] libcxl: add interfaces for label operations [ndctl,v3,17/21] test/libcxl: add a test for cxl_memdev_{get,set}_lsa [ndctl,v3,18/21] cxl: add commands to read, write, and zero labels [ndctl,v3,19/21] Documentation/cxl: add library API documentation [ndctl,v3,20/21] ndctl: Add CXL packages to the RPM spec [ndctl,v3,21/21] cxl-cli: add bash completion

diff --git a/Documentation/cxl/lib/cxl_new.txt b/Documentation/cxl/lib/cxl_new.txt new file mode 100644 index 0000000..d4d5bcb --- /dev/null +++ b/Documentation/cxl/lib/cxl_new.txt @@ -0,0 +1,43 @@ +// SPDX-License-Identifier: GPL-2.0 + +cxl_new(3) +========== + +NAME +---- +cxl_new - Create a new library context object that acts as a handle for all +library operations + +SYNOPSIS +-------- +[verse] +---- +#include <cxl/libcxl.h> + +int cxl_new(struct cxl_ctx **ctx); +---- + +DESCRIPTION +----------- +Instantiates a new library context, and stores an opaque pointer in ctx. The +context is freed by linklibcxl:cxl_unref[3], i.e. cxl_new(3) implies an +internal linklibcxl:cxl_ref[3]. + + +RETURN VALUE +------------ +Returns 0 on success, and a negative errno on failure. +Possible error codes are: + + * -ENOMEM + * -ENXIO + +EXAMPLE +------- +See example usage in test/libcxl.c + +include::../../copyright.txt[] + +SEE ALSO +-------- +linklibcxl:cxl_ref[3], linklibcxl:cxl_unref[3] diff --git a/Documentation/cxl/lib/libcxl.txt b/Documentation/cxl/lib/libcxl.txt new file mode 100644 index 0000000..47f4cc3 --- /dev/null +++ b/Documentation/cxl/lib/libcxl.txt @@ -0,0 +1,56 @@ +// SPDX-License-Identifier: GPL-2.0 + +libcxl(3) +========= + +NAME +---- +libcxl - A library to interact with CXL devices through sysfs(5) +and ioctl(2) interfaces + +SYNOPSIS +-------- +[verse] +#include <cxl/libcxl.h> +cc ... -lcxl + +DESCRIPTION +----------- +libcxl provides interfaces to interact with CXL devices in Linux, using sysfs +interfaces for most kernel interactions, and the ioctl() interface for command +submission. + +The starting point for all library interfaces is a 'cxl_ctx' object, returned +by linklibcxl:cxl_new[3]. CXL 'Type 3' memory devices are children of the +cxl_ctx object, and can be iterated through using an iterator API. + +Library level interfaces that are agnostic to any device, or a specific +subclass of operations have the prefix 'cxl_' + +The object representing a CXL Type 3 device is 'cxl_memdev'. Library interfaces +related to these devices have the prefix 'cxl_memdev_'. These interfaces are +mostly associated with sysfs interactions (unless otherwise noted in their +respective documentation pages). They are typically used to retrieve data +published by the kernel, or to send data or trigger kernel operations for a +given device. + +A 'cxl_cmd' is a reference counted object which is used to perform 'Mailbox' +commands as described in the CXL Specification. A 'cxl_cmd' object is tied to a +'cxl_memdev'. Associated library interfaces have the prefix 'cxl_cmd_'. Within +this sub-class of interfaces, there are: + + * 'cxl_cmd_new_*' interfaces that allocate a new cxl_cmd object for a given + command type. + + * 'cxl_cmd_submit' which submits the command via ioctl() + + * 'cxl_cmd_<name>_get_<field>' interfaces that get specific fields out of the + command response + + * 'cxl_cmd_get_*' interfaces to get general command related information. + +include::../../copyright.txt[] + +SEE ALSO +-------- +linklibcxl:cxl[1] diff --git a/configure.ac b/configure.ac index dadae0a..00497ae 100644 --- a/configure.ac +++ b/configure.ac @@ -231,6 +231,7 @@ AC_CONFIG_FILES([ Documentation/ndctl/Makefile Documentation/daxctl/Makefile Documentation/cxl/Makefile + Documentation/cxl/lib/Makefile ]) AC_OUTPUT diff --git a/Makefile.am b/Makefile.am index 4904ee7..e2f6bef 100644 --- a/Makefile.am +++ b/Makefile.am @@ -4,6 +4,7 @@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS} SUBDIRS = . cxl/lib daxctl/lib ndctl/lib cxl ndctl daxctl if ENABLE_DOCS SUBDIRS += Documentation/ndctl Documentation/daxctl Documentation/cxl +SUBDIRS += Documentation/cxl/lib endif SUBDIRS += test diff --git a/.gitignore b/.gitignore index 6a97b92..6468c7a 100644 --- a/.gitignore +++ b/.gitignore @@ -14,12 +14,15 @@ Makefile.in /libtool /stamp-h1 *.1 +*.3 Documentation/daxctl/asciidoc.conf Documentation/ndctl/asciidoc.conf Documentation/cxl/asciidoc.conf +Documentation/cxl/lib/asciidoc.conf Documentation/daxctl/asciidoctor-extensions.rb Documentation/ndctl/asciidoctor-extensions.rb Documentation/cxl/asciidoctor-extensions.rb +Documentation/cxl/lib/asciidoctor-extensions.rb Documentation/ndctl/attrs.adoc .dirstamp daxctl/config.h diff --git a/Documentation/cxl/lib/Makefile.am b/Documentation/cxl/lib/Makefile.am new file mode 100644 index 0000000..41e3a5f --- /dev/null +++ b/Documentation/cxl/lib/Makefile.am @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2020-2021 Intel Corporation. All rights reserved. + +if USE_ASCIIDOCTOR + +do_subst = sed -e 's,@Utility@,Libcxl,g' -e's,@utility@,libcxl,g' +CONFFILE = asciidoctor-extensions.rb +asciidoctor-extensions.rb: ../../asciidoctor-extensions.rb.in + $(AM_V_GEN) $(do_subst) < $< > $@ + +else + +do_subst = sed -e 's,UTILITY,libcxl,g' +CONFFILE = asciidoc.conf +asciidoc.conf: ../../asciidoc.conf.in + $(AM_V_GEN) $(do_subst) < $< > $@ + +endif + +man3_MANS = \ + libcxl.3 \ + cxl_new.3 + +EXTRA_DIST = $(man3_MANS) + +CLEANFILES = $(man3_MANS) + +XML_DEPS = \ + ../../../version.m4 \ + ../../copyright.txt \ + Makefile \ + $(CONFFILE) + +RM ?= rm -f + +if USE_ASCIIDOCTOR + +%.3: %.txt $(XML_DEPS) + $(AM_V_GEN)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage -acompat-mode \ + -I. -rasciidoctor-extensions \ + -amansource=libcxl -amanmanual="libcxl Manual" \ + -andctl_version=$(VERSION) -o $@+ $< && \ + mv $@+ $@ + +else + +%.xml: %.txt $(XML_DEPS) + $(AM_V_GEN)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ + --unsafe -alibcxl_version=$(VERSION) -o $@+ $< && \ + mv $@+ $@ + +%.3: %.xml $(XML_DEPS) + $(AM_V_GEN)$(RM) $@ && \ + $(XMLTO) -o . -m ../../manpage-normal.xsl man $< + +endif

[ndctl,v3,19/21] Documentation/cxl: add library API documentation

Commit Message

Patch