Merge pull request #3457 from wlemkows/pmreorder-example

example: add pmreorder simple example

src/examples/Makefile

@@ -36,7 +36,7 @@
 
 include ../common.inc
 
-DIRS = libpmem libpmemblk libpmemlog libpmemobj libvmem librpmem libpmempool
+DIRS = libpmem libpmemblk libpmemlog libpmemobj libvmem librpmem libpmempool pmreorder
 
 include Makefile.inc
 

src/examples/pmreorder/.gitignore

@@ -0,0 +1 @@
+pmreorder_list

src/examples/pmreorder/Makefile

@@ -0,0 +1,43 @@
+#
+# Copyright 2018, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in
+#       the documentation and/or other materials provided with the
+#       distribution.
+#
+#     * Neither the name of the copyright holder nor the names of its
+#       contributors may be used to endorse or promote products derived
+#       from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+#
+# examples/pmreorder/Makefile -- build the pmreorder example
+#
+
+PROGS = pmreorder_list
+
+LIBS = -lpmem -pthread
+
+include ../Makefile.inc
+
+pmreorder_list: pmreorder_list.o

src/examples/pmreorder/README

@@ -0,0 +1,44 @@
+Persistent Memory Development Kit
+
+This is examples/pmreorder/README.
+
+This directory contains example for pmreorder tool.
+A detailed explanation of this tool can be found here:
+http://pmem.io/pmdk/manpages/linux/master/pmreorder/pmreorder.1.html
+
+pmreorder_list: simple list to check pmem consistency using pmreorder tool
+
+To build these examples:
+	make
+
+This example can be built against an installed library using:
+	make LIBDIR=/usr/lib INCDIR=/usr/include
+
+To enable pmreorder API logs in the library:
+export PMREORDER_EMIT_LOG=1
+
+To generate store_log run:
+
+LD_LIBRARY_PATH=<path_to_libs> \
+valgrind --tool=pmemcheck \
+-q --log-stores=yes \
+--log-file=store_log_pmreorder_list.log \
+--log-stores-stacktraces=yes \
+--log-stores-stacktraces-depth=2 \
+--expect-fence-after-clflush=yes \
+./pmreorder_list <g|b> <path>
+
+To check consistency run:
+
+LD_LIBRARY_PATH=<path_to_lib> \
+python3 \
+pmreorder.py \
+-l map_store.log \
+-o out_map_store_bad.log \
+-x pmem_memset_persist=NoReorderNoCheck \
+-r ReorderReverseAccumulative  \
+-p "./pmreorder_list c"
+
+If you're looking for documentation to get you started using PMDK,
+start here: http://pmem.io/pmdk and follow the links to examples and
+blog posts.

src/examples/pmreorder/pmreorder_list.c

@@ -0,0 +1,200 @@
+/*
+ * Copyright 2018, Intel Corporation
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in
+ *       the documentation and/or other materials provided with the
+ *       distribution.
+ *
+ *     * Neither the name of the copyright holder nor the names of its
+ *       contributors may be used to endorse or promote products derived
+ *       from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * pmreorder_list.c -- explains how to use pmreorder tool with libpmem
+ *
+ * usage: pmreorder_list <g|b|c> <path>
+ * g - good case - add element to the list in a consistent way
+ * b - bad case - add element to the list in an inconsistent way
+ * c - check persistent consistency of the list
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <libpmem.h>
+
+#define MAX_NODES 10
+#define NODE_PTR(root, node_id) \
+	(node_id == 0 ? NULL : &(root)->nodes[(node_id)])
+
+typedef size_t node_id;
+
+struct list_node {
+	int value;
+	node_id next;
+};
+
+struct list_root {
+	node_id head;
+	struct list_node nodes[MAX_NODES];
+};
+
+/*
+ * check_consistency -- check if list meets the set requirements
+ *
+ * for consistent cases function returns 0
+ * for inconsistent cases function returns 1
+ */
+static int
+check_consistency(struct list_root *root)
+{
+	struct list_node *node = NODE_PTR(root, root->head);
+
+	/*
+	 * If node is linked to the list then its
+	 * value should be set properly.
+	 */
+	if (node == NULL)
+		return 0;
+
+	do {
+		if (node->value == 0)
+			return 1;
+		node = NODE_PTR(root, node->next);
+	} while (node != NULL);
+
+	return 0;
+}
+
+/*
+ * list_print -- print all elements to the screen
+ */
+static void
+list_print(struct list_root *list)
+{
+	FILE *fp;
+	fp = fopen("pmreorder_list.log", "w+");
+	fprintf(fp, "List:\n");
+
+	struct list_node *node = NODE_PTR(list, list->head);
+	if (node == NULL) {
+		fprintf(fp, "List is empty");
+		goto end;
+	}
+
+	do {
+		fprintf(fp, "Value: %d\n", node->value);
+		node = NODE_PTR(list, node->next);
+	} while (node != NULL);
+
+end:
+	fclose(fp);
+}
+
+/*
+ * list_insert_consistent -- add new element to the list in a consistent way
+ */
+static void
+list_insert_consistent(struct list_root *root, node_id node, int value)
+{
+	struct list_node *new = NODE_PTR(root, node);
+
+	new->value = value;
+	new->next = root->head;
+	pmem_persist(new, sizeof(new));
+
+	root->head = node;
+	pmem_persist(&root->head, sizeof(root->head));
+}
+
+/*
+ * list_insert_inconsistent -- add new element to the list
+ * in an inconsistent way
+ */
+static void
+list_insert_inconsistent(struct list_root *root, node_id node, int value)
+{
+	struct list_node *new = NODE_PTR(root, node);
+
+	new->next = root->head;
+	pmem_persist(&new->next, sizeof(node));
+
+	root->head = node;
+	pmem_persist(&root->head, sizeof(root->head));
+
+	new->value = value;
+	pmem_persist(&new->value, sizeof(value));
+}
+
+int
+main(int argc, char *argv[])
+{
+	void *pmemaddr;
+	size_t mapped_len;
+	int is_pmem;
+	int check;
+
+	if (argc != 3 || strchr("cgb", argv[1][0]) == NULL ||
+			argv[1][1] != '\0') {
+		printf("Usage: pmreorder_list <c|g|b> <path>\n");
+		exit(1);
+	}
+
+	/* create a pmem file and memory map it */
+	pmemaddr = pmem_map_file(argv[2], 0, 0, 0, &mapped_len, &is_pmem);
+	if (pmemaddr == NULL) {
+		perror("pmem_map_file");
+		exit(1);
+	}
+	struct list_root *r = pmemaddr;
+
+	char opt = argv[1][0];
+	if (strchr("gb", opt))
+		pmem_memset_persist(r, 0, sizeof(struct list_root) +
+				sizeof(struct list_node) * MAX_NODES);
+
+	switch (opt) {
+		case 'g':
+			list_insert_consistent(r, 5, 55);
+			list_insert_consistent(r, 3, 33);
+			list_insert_consistent(r, 6, 66);
+			break;
+		case 'b':
+			list_insert_inconsistent(r, 5, 55);
+			list_insert_inconsistent(r, 3, 33);
+			list_insert_inconsistent(r, 6, 66);
+			break;
+		case 'c':
+			check = check_consistency(r);
+			return check;
+		default:
+			printf("Unrecognized option: %c\n", opt);
+			abort();
+	}
+
+	list_print(r);
+
+	pmem_unmap(pmemaddr, mapped_len);
+	return 0;
+}

src/test/Makefile.inc

@@ -50,6 +50,7 @@ EX_LIBPMEM=$(EXAMPLES_DIR)/libpmem
 EX_LIBPMEMBLK=$(EXAMPLES_DIR)/libpmemblk
 EX_LIBPMEMLOG=$(EXAMPLES_DIR)/libpmemlog
 EX_LIBPMEMOBJ=$(EXAMPLES_DIR)/libpmemobj
+EX_PMREORDER=$(EXAMPLES_DIR)/pmreorder
 
 UT = ../unittest/libut.a
 LIBS += $(UT) $(LIBUUID)

src/test/ex_pmreorder/Makefile

@@ -0,0 +1,43 @@
+#
+# Copyright 2018, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in
+#       the documentation and/or other materials provided with the
+#       distribution.
+#
+#     * Neither the name of the copyright holder nor the names of its
+#       contributors may be used to endorse or promote products derived
+#       from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+#
+# src/test/ex_pmreorder/Makefile -- build pmreorder_list example
+# needed for ex_pmreorder tests
+#
+
+all: $(EXAMPLES)
+	$(MAKE) -C $(EX_PMREORDER)
+
+include ../Makefile.inc
+
+EXAMPLES=$(EX_PMREORDER)/pmreorder_list

src/test/ex_pmreorder/README

@@ -0,0 +1,7 @@
+Persistent Memory Development Kit
+
+This is src/test/ex_pmreorder/README.
+
+This directory contains tests for pmreorder_list example.
+
+The tests utilize examples from src/examples/pmreorder directory.