[ndctl,v2,12/13] Documentation/cxl: add library API documentation

Message ID	20210219020331.725687-13-vishal.l.verma@intel.com
State	New, archived
Headers	show Return-Path: <linux-cxl-owner@kernel.org> IronPort-SDR: CG5XPrXNaGh+u4lDWg4UcQJon7EVLaVOAuPdzRDN19CFilGvr91Ux57LH5WupNB5hQVsfIj6cl 82sthrpPizOw== IronPort-SDR: QoIZ0i4ySHXLoUw8caSh8y6/4quGuLGeZUmWf0dCN7BiOYzK0Uk6h2v9Yow6zmPJAJ1FakqF4w /EFsCvloJ7Fg== From: Vishal Verma <vishal.l.verma@intel.com> To: <linux-cxl@vger.kernel.org> Cc: <linux-nvdimm@lists.01.org>, Ben Widawsky <ben.widawsky@intel.com>, Dan Williams <dan.j.williams@intel.com>, Vishal Verma <vishal.l.verma@intel.com> Subject: [ndctl PATCH v2 12/13] Documentation/cxl: add library API documentation Date: Thu, 18 Feb 2021 19:03:30 -0700 Message-Id: <20210219020331.725687-13-vishal.l.verma@intel.com> In-Reply-To: <20210219020331.725687-1-vishal.l.verma@intel.com> References: <20210219020331.725687-1-vishal.l.verma@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk
Series	Initial CXL support \| expand [ndctl,v2,00/13] Initial CXL support [ndctl,v2,01/13] cxl: add a cxl utility and libcxl library [ndctl,v2,02/13] cxl: add a local copy of the cxl_mem UAPI header [ndctl,v2,03/13] libcxl: add support for command query and submission [ndctl,v2,04/13] libcxl: add support for the 'Identify Device' command [ndctl,v2,05/13] test: rename 'ndctl_test' to 'test_ctx' [ndctl,v2,06/13] test: rename 'ndctl_test_' helpers to 'test_' [ndctl,v2,07/13] test: introduce a libcxl unit test [ndctl,v2,08/13] libcxl: add GET_HEALTH_INFO mailbox command and accessors [ndctl,v2,09/13] libcxl: add support for the 'GET_LSA' command [ndctl,v2,10/13] util/hexdump: Add a util helper to print a buffer in hex [ndctl,v2,11/13] test/libcxl: add a test for {set, get}_lsa commands [ndctl,v2,12/13] Documentation/cxl: add library API documentation [ndctl,v2,13/13] test/libcxl: introduce a command size fuzzing test

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 7f5e6f0..a357042 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 de43823..b0f93dc 100644 --- a/.gitignore +++ b/.gitignore @@ -13,12 +13,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 .dirstamp daxctl/config.h daxctl/daxctl 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,v2,12/13] Documentation/cxl: add library API documentation

Commit Message

Patch