From 62fe17528d362110e258d56d8a2f44f2798f3f45 Mon Sep 17 00:00:00 2001

From: Vishal Verma <vishal.l.verma@intel.com>

Date: Thu, 7 Oct 2021 02:21:36 -0600

Subject: [PATCH 043/217] Documentation/cxl: add library API documentation

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>

Reviewed-by: Dan Williams <dan.j.williams@intel.com>

Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>

---

 .gitignore                        |  3 ++

 Documentation/cxl/lib/Makefile.am | 58 +++++++++++++++++++++++++++++++

 Documentation/cxl/lib/cxl_new.txt | 43 +++++++++++++++++++++++

 Documentation/cxl/lib/libcxl.txt  | 56 +++++++++++++++++++++++++++++

 Makefile.am                       |  1 +

 configure.ac                      |  1 +

 6 files changed, 162 insertions(+)

 create mode 100644 Documentation/cxl/lib/Makefile.am

 create mode 100644 Documentation/cxl/lib/cxl_new.txt

 create mode 100644 Documentation/cxl/lib/libcxl.txt

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

diff --git a/Documentation/cxl/lib/cxl_new.txt b/Documentation/cxl/lib/cxl_new.txt

new file mode 100644

index 0000000..147d4e0

--- /dev/null

+++ b/Documentation/cxl/lib/cxl_new.txt

@@ -0,0 +1,43 @@

+// SPDX-License-Identifier: LGPL-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..2539369

--- /dev/null

+++ b/Documentation/cxl/lib/libcxl.txt

@@ -0,0 +1,56 @@

+// SPDX-License-Identifier: LGPL-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/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/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

-- 

2.27.0