From: Vishal Verma <vishal.l.verma@intel.com> To: <linux-cxl@vger.kernel.org> Cc: Dan Williams <dan.j.williams@intel.com>, Ben Widawsky <ben.widawsky@intel.com>, <nvdimm@lists.linux.dev>, Vishal Verma <vishal.l.verma@intel.com> Subject: [ndctl PATCH v4 14/17] Documentation/cxl: add library API documentation Date: Thu, 7 Oct 2021 02:21:36 -0600 [thread overview] Message-ID: <20211007082139.3088615-15-vishal.l.verma@intel.com> (raw) In-Reply-To: <20211007082139.3088615-1-vishal.l.verma@intel.com> Add library API documentation for libcxl(3) using the existing asciidoc(tor) build system. Add a section 3 man page for 'libcxl' that provides an overview of the library and its usage, and a man page for the 'cxl_new()' API. Cc: Ben Widawsky <ben.widawsky@intel.com> Cc: Dan Williams <dan.j.williams@intel.com> Signed-off-by: Vishal Verma <vishal.l.verma@intel.com> --- Documentation/cxl/lib/cxl_new.txt | 43 +++++++++++++++++++++++ Documentation/cxl/lib/libcxl.txt | 56 +++++++++++++++++++++++++++++ configure.ac | 1 + Makefile.am | 1 + .gitignore | 3 ++ Documentation/cxl/lib/Makefile.am | 58 +++++++++++++++++++++++++++++++ 6 files changed, 162 insertions(+) create mode 100644 Documentation/cxl/lib/cxl_new.txt create mode 100644 Documentation/cxl/lib/libcxl.txt create mode 100644 Documentation/cxl/lib/Makefile.am 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 -- 2.31.1
next prev parent reply other threads:[~2021-10-07 8:22 UTC|newest] Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-10-07 8:21 [ndctl PATCH v4 00/17] Initial CXL support Vishal Verma 2021-10-07 8:21 ` [ndctl PATCH v4 01/17] ndctl: add .clang-format Vishal Verma 2021-10-07 8:21 ` [ndctl PATCH v4 02/17] cxl: add a cxl utility and libcxl library Vishal Verma 2021-10-07 8:21 ` [ndctl PATCH v4 03/17] cxl: add a local copy of the cxl_mem UAPI header Vishal Verma 2021-10-07 8:21 ` [ndctl PATCH v4 04/17] util: add the struct_size() helper from the kernel Vishal Verma 2021-10-14 2:40 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 05/17] libcxl: add support for command query and submission Vishal Verma 2021-10-14 2:53 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 06/17] libcxl: add support for the 'Identify Device' command Vishal Verma 2021-10-07 8:21 ` [ndctl PATCH v4 07/17] libcxl: add GET_HEALTH_INFO mailbox command and accessors Vishal Verma 2021-10-14 16:01 ` Dan Williams 2021-11-02 20:22 ` Verma, Vishal L 2021-11-02 20:27 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 08/17] libcxl: add support for the 'GET_LSA' command Vishal Verma 2021-10-14 16:35 ` Dan Williams 2021-10-14 20:06 ` Verma, Vishal L 2021-10-14 20:55 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 09/17] util/hexdump: Add a util helper to print a buffer in hex Vishal Verma 2021-10-14 16:48 ` Dan Williams 2021-10-14 20:33 ` Verma, Vishal L 2021-10-14 22:39 ` Dan Williams 2021-11-02 20:25 ` Verma, Vishal L 2021-10-07 8:21 ` [ndctl PATCH v4 10/17] libcxl: add label_size to cxl_memdev, and an API to retrieve it Vishal Verma 2021-10-14 18:24 ` Dan Williams 2021-10-14 21:50 ` Verma, Vishal L 2021-10-07 8:21 ` [ndctl PATCH v4 11/17] libcxl: add a stub interface to determine whether a memdev is active Vishal Verma 2021-10-14 19:59 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 12/17] libcxl: add interfaces for label operations Vishal Verma 2021-10-14 21:27 ` Dan Williams 2021-10-14 22:18 ` Verma, Vishal L 2021-10-14 22:24 ` Verma, Vishal L 2021-10-14 22:45 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 13/17] cxl: add commands to read, write, and zero labels Vishal Verma 2021-10-14 22:34 ` Dan Williams 2021-10-07 8:21 ` Vishal Verma [this message] 2021-10-14 23:31 ` [ndctl PATCH v4 14/17] Documentation/cxl: add library API documentation Dan Williams 2021-11-05 18:58 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 15/17] ndctl: Add CXL packages to the RPM spec Vishal Verma 2021-10-14 23:33 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 16/17] cxl-cli: add bash completion Vishal Verma 2021-10-14 23:34 ` Dan Williams 2021-10-07 8:21 ` [ndctl PATCH v4 17/17] cxl: add health information to cxl-list Vishal Verma 2021-10-11 22:07 ` Verma, Vishal L 2021-10-15 0:09 ` Dan Williams 2021-10-14 23:42 ` Verma, Vishal L 2021-10-15 21:15 ` Dan Williams
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20211007082139.3088615-15-vishal.l.verma@intel.com \ --to=vishal.l.verma@intel.com \ --cc=ben.widawsky@intel.com \ --cc=dan.j.williams@intel.com \ --cc=linux-cxl@vger.kernel.org \ --cc=nvdimm@lists.linux.dev \ --subject='Re: [ndctl PATCH v4 14/17] Documentation/cxl: add library API documentation' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).