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